Release v4.6.67

The register_legacy_reply function in integration/_legacy_handlers.py was never
imported or used anywhere in the codebase. Legacy mode is actually handled by
the is_legacy_host() check in host_app.py that skips provider wiring.

Co-authored-by: praisonai-triage-agent[bot] <272766704+praisonai-triage-agent[bot]@users.noreply.github.com>
Co-authored-by: MervinPraison <[email protected]>

.github/workflows/claude.yml

@@ -151,24 +151,40 @@ jobs:
         id: check_fork
         uses: actions/github-script@v7
         with:
+          github-token: ${{ steps.app-token.outputs.token }}
           script: |
-            const isPR = context.eventName === 'pull_request' || (context.payload.issue && context.payload.issue.pull_request);
-            if (isPR) {
-              const prNumber = context.payload.pull_request ? context.payload.pull_request.number : context.payload.issue.number;
-              const pr = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: prNumber
-              });
-              
-              core.setOutput('pr_branch', pr.data.head.ref);
-              
-              if (pr.data.head.repo && pr.data.head.repo.full_name !== context.repo.full_name) {
-                core.setOutput('is_fork', 'true');
-                core.setOutput('clone_url', pr.data.head.repo.clone_url);
-                core.setOutput('branch', pr.data.head.ref);
-                return;
-              }
+            const isPR = context.eventName === 'pull_request'
+              || context.eventName === 'pull_request_review'
+              || context.eventName === 'pull_request_review_comment'
+              || (context.payload.issue && context.payload.issue.pull_request);
+
+            if (!isPR) {
+              core.setOutput('is_pr', 'false');
+              core.setOutput('is_fork', 'false');
+              return;
+            }
+
+            const prNumber = context.payload.pull_request
+              ? context.payload.pull_request.number
+              : context.payload.issue.number;
+            const pr = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber
+            });
+
+            core.setOutput('is_pr', 'true');
+            core.setOutput('pr_number', String(prNumber));
+            core.setOutput('pr_branch', pr.data.head.ref);
+            core.setOutput('head_repo', pr.data.head.repo.full_name);
+            core.setOutput('merge_state', (pr.data.mergeable_state || pr.data.merge_state_status || '').toUpperCase());
+
+            const baseRepo = `${context.repo.owner}/${context.repo.repo}`;
+            if (pr.data.head.repo && pr.data.head.repo.full_name !== baseRepo) {
+              core.setOutput('is_fork', 'true');
+              core.setOutput('clone_url', pr.data.head.repo.clone_url);
+              core.setOutput('branch', pr.data.head.ref);
+              return;
             }
             core.setOutput('is_fork', 'false');
 
@@ -180,17 +196,19 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
 
       - name: Fetch PR branch and Setup Remote
-        if: github.event.issue.pull_request
+        if: steps.check_fork.outputs.is_pr == 'true'
         env:
           PR_BRANCH: ${{ steps.check_fork.outputs.pr_branch }}
+          PR_NUMBER: ${{ steps.check_fork.outputs.pr_number }}
           IS_FORK: ${{ steps.check_fork.outputs.is_fork }}
         run: |
-          # Fetch PR head from base repo and put it into local branch
-          git fetch origin pull/${{ github.event.issue.number }}/head:"${PR_BRANCH}"
-          
+          git fetch origin "pull/${PR_NUMBER}/head:${PR_BRANCH}"
+          git checkout "${PR_BRANCH}"
+          git fetch origin main
+
           # If it's a fork, make origin point to local to trick claude-code-action's `git fetch origin <branch>`
           if [ "${IS_FORK}" = "true" ]; then
-            git remote set-url origin file://$(pwd)
+            git remote set-url origin "file://$(pwd)"
           fi
 
       - uses: anthropics/claude-code-action@beta
@@ -200,11 +218,13 @@ jobs:
           allowed_bots: 'praisonai-triage-agent[bot]'
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           github_token: ${{ steps.app-token.outputs.token }}
+          model: opus
           trigger_phrase: "@claude"
           label_trigger: "claude"
 
           direct_prompt: |
-            ${{ steps.check_fork.outputs.is_fork == 'true' && 'CRITICAL: THIS IS A PULL REQUEST FROM A FORK. YOU DO NOT HAVE PUSH PERMISSIONS TO THIS REPOSITORY. ONLY READ FILES, VALIDATE CODE, AND PROVIDE YOUR COMMENTS/FEEDBACK DIRECTLY IN THIS PR VIA COMMENTS. DO NOT ATTEMPT TO PUSH OR CREATE PULL REQUESTS.\n\n' || 'NOTE: The branch is under MervinPraison/PraisonAI (not a fork). You are able to make modifications and push directly to this branch.\n\n' }}
+            ${{ steps.check_fork.outputs.is_fork == 'true' && 'CRITICAL: THIS IS A PULL REQUEST FROM A FORK. YOU DO NOT HAVE PUSH PERMISSIONS TO THIS REPOSITORY. ONLY READ FILES, VALIDATE CODE, AND PROVIDE YOUR COMMENTS/FEEDBACK DIRECTLY IN THIS PR VIA COMMENTS. DO NOT ATTEMPT TO PUSH OR CREATE PULL REQUESTS.\n\n' || (steps.check_fork.outputs.is_pr == 'true' && 'NOTE: The branch is under MervinPraison/PraisonAI (not a fork). You are able to make modifications and push directly to this branch.\n\n' || 'NOTE: This is an issue (not a PR). Create a new fix branch per STEP 3 below.\n\n') }}
+            ${{ steps.check_fork.outputs.is_pr == 'true' && format('CONTEXT: PR #{0} on branch {1}. head.repo={2}, is_fork={3}, merge_state={4}. NEVER treat cursor/*, claude/* branch names or bot authors as forks — only is_fork=true means fork.\n\n', steps.check_fork.outputs.pr_number, steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.head_repo, steps.check_fork.outputs.is_fork, steps.check_fork.outputs.merge_state) || '' }}
             You are working on the PraisonAI SDK. Follow AGENTS.md strictly.
 
             STEP 0 — SETUP GIT IDENTITY & AUTH (GLOBAL — required for all repos):
@@ -233,15 +253,9 @@ jobs:
             - Is there a name collision with existing exports in __init__.py?
             If ANY of these conceptual checks fail (excluding routing), add a comment to the issue explaining why and close it. Do NOT create a PR.
 
-            STEP 3 — IMPLEMENT (for changes in THIS repo — PraisonAI):
-            - Create a fix branch: git checkout -b claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)
-            - Implement a minimal, focused fix
-            - Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper
-            - Keep changes small and backward-compatible
-            - Commit: git add -A && git commit -m "fix: <description> (fixes #$ISSUE_NUMBER)"
-            - Push: git push origin claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)
-            CRITICAL: After pushing, you MUST immediately run: gh pr create --title "fix: <title>" --body "Fixes #$ISSUE_NUMBER" --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)
-            Do NOT stop after pushing. Do NOT say "manually create a PR". Always create the PR automatically.
+            ${{ steps.check_fork.outputs.is_pr == 'true' && steps.check_fork.outputs.is_fork != 'true' && steps.check_fork.outputs.merge_state == 'DIRTY' && format('STEP 3 — RESOLVE MERGE CONFLICTS ON PR (branch: {0}, PR #{1}):\n- DO NOT create a new branch or PR\n- git fetch origin main && git rebase origin/main\n- Resolve conflicts: keep this PR intent, merge in main newer logic\n- git add -A && git rebase --continue (repeat until done)\n- git push --force-with-lease origin {0}\n- Run targeted pytest on changed paths\n- Comment files resolved and what you skipped\n', steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.pr_number) || '' }}
+            ${{ steps.check_fork.outputs.is_pr == 'true' && steps.check_fork.outputs.is_fork != 'true' && steps.check_fork.outputs.merge_state != 'DIRTY' && format('STEP 3 — IMPLEMENT ON EXISTING PR (branch: {0}, PR #{1}):\n- DO NOT create a new branch or PR\n- git checkout {0}\n- Implement minimal, focused fixes from reviewer feedback\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: <description>"\n- Push: git push origin {0}\n- Comment a summary of exact files modified and what you skipped\n', steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.pr_number) || '' }}
+            ${{ steps.check_fork.outputs.is_pr != 'true' && 'STEP 3 — IMPLEMENT (for changes in THIS repo — PraisonAI):\n- Create a fix branch: git checkout -b claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\n- Implement a minimal, focused fix\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: <description> (fixes #$ISSUE_NUMBER)"\n- Push: git push origin claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nCRITICAL: After pushing, you MUST immediately run: gh pr create --title "fix: <title>" --body "Fixes #$ISSUE_NUMBER" --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nDo NOT stop after pushing. Do NOT say "manually create a PR". Always create the PR automatically.\n' || '' }}
 
             STEP 3-ALT — IMPLEMENT IN EXTERNAL REPO (for PraisonAI-Tools, PraisonAIDocs, PraisonAI-Plugins):
             When work must happen in a different repository, follow these steps EXACTLY. Do NOT attempt to use `cd`, as directory state is not preserved. Use `git -C` for all commands.
@@ -267,10 +281,7 @@ jobs:
             - For docs changes: verify files exist and are valid markdown/MDX
             - Ensure no regressions
 
-            STEP 5 — CREATE PR:
-            - Commit with descriptive message, push, and create PR using `gh pr create`
-            - For external repos, use `gh pr create -R MervinPraison/<REPO_NAME>`
-            CRITICAL: You MUST create the PR automatically using `gh pr create`. Do NOT just provide a link or say "manual push required".
+            ${{ steps.check_fork.outputs.is_pr == 'true' && 'STEP 5 — SKIP: Already on an open PR. Do NOT run gh pr create.\n' || 'STEP 5 — CREATE PR:\n- Commit with descriptive message, push, and create PR using `gh pr create`\n- For external repos, use `gh pr create -R MervinPraison/<REPO_NAME>`\nCRITICAL: You MUST create the PR automatically using `gh pr create`. Do NOT just provide a link or say "manual push required".\n' }}
             NOTE: If you worked on an external repo, the wrapper action will report "No commits" for the main repo at the end. This is expected, do not worry about it.
           allowed_tools: |
             Bash(git:*)

.github/workflows/docker-publish.yml

@@ -22,8 +22,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3

.github/workflows/gemini-issue-automated-triage.yml

@@ -36,9 +36,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
-        with:
           token: ${{ steps.generate_token.outputs.token }}
 
       - name: Run Gemini Issue Triage

.github/workflows/gemini-issue-review.yml

@@ -37,9 +37,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
-        with:
           token: ${{ steps.generate_token.outputs.token }}
 
       - name: Set up Git

.github/workflows/gemini-pr-review.yml

@@ -48,9 +48,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
-        with:
           token: ${{ steps.generate_token.outputs.token }}
           ref: ${{ steps.checkout_ref.outputs.ref }}
           fetch-depth: 0

.github/workflows/integration-cross-repo.yml

@@ -60,16 +60,16 @@ jobs:
     - name: Run PraisonAI integration tests
       run: |
         cd PraisonAI/src/praisonai
-        python -m pytest tests/integration/test_aiui_* -v --timeout=300
+        python -m pytest tests/integration/test_aiui_* -v
         
     - name: Run PraisonAIUI integration tests
       run: |
         cd PraisonAIUI
         if [ -f tests/integration/test_agentic_roundtrip.py ]; then
-          python -m pytest tests/integration/test_agentic_roundtrip.py -v --timeout=300
+          python -m pytest tests/integration/test_agentic_roundtrip.py -v
         fi
         if [ -f tests/test_feature_sdk_backends.py ]; then
-          python -m pytest tests/test_feature_sdk_backends.py -v --timeout=300
+          python -m pytest tests/test_feature_sdk_backends.py -v
         fi
         
     - name: Test Pattern C CLI
@@ -152,7 +152,7 @@ jobs:
       run: |
         cd PraisonAI/src/praisonai
         if [ -n "$OPENAI_API_KEY" ]; then
-          python -m pytest tests/integration/test_aiui_host_agentic.py -v --timeout=600
+          python -m pytest tests/integration/test_aiui_host_agentic.py -v
         else
           echo "OPENAI_API_KEY not available, skipping agentic tests"
         fi

.github/workflows/python-package.yml

@@ -15,8 +15,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:

.github/workflows/release.yml

@@ -26,11 +26,8 @@ jobs:
     # First checkout the upstream repo at the specified tag
     - name: Checkout upstream repo
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
       with:
+        persist-credentials: false
         repository: MervinPraison/PraisonAI
         ref: ${{ github.event.inputs.tag }}
         fetch-depth: 0
@@ -48,11 +45,8 @@ jobs:
     # Now checkout the fork at main branch
     - name: Checkout fork
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
       with:
+        persist-credentials: false
         repository: ${{ github.event.inputs.fork_owner }}/PraisonAI
         ref: main
         fetch-depth: 0
@@ -449,11 +443,8 @@ jobs:
     # First checkout the fork's main branch
     - name: Checkout fork repo
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
       with:
+        persist-credentials: false
         fetch-depth: 0
         token: ${{ secrets.PAT_TOKEN }}
         repository: ${{ github.event.inputs.fork_owner }}/PraisonAI

.github/workflows/sync-secrets-to-aiui.yml

@@ -0,0 +1,31 @@
+name: Sync Claude Secrets to PraisonAIUI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync secrets to PraisonAIUI
+        env:
+          GH_TOKEN: ${{ secrets.SECRETS_ADMIN_PAT }}
+          TARGET: MervinPraison/PraisonAIUI
+          CLAUDE_APP_ID: ${{ secrets.CLAUDE_APP_ID }}
+          CLAUDE_APP_PRIVATE_KEY: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          GH_TOKEN_VALUE: ${{ secrets.GH_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [ -z "${GH_TOKEN:-}" ]; then
+            echo "SECRETS_ADMIN_PAT is not configured in this repository"
+            exit 1
+          fi
+          echo -n "$CLAUDE_APP_ID" | gh secret set CLAUDE_APP_ID --repo "$TARGET"
+          echo -n "$CLAUDE_APP_PRIVATE_KEY" | gh secret set CLAUDE_APP_PRIVATE_KEY --repo "$TARGET"
+          echo -n "$CLAUDE_CODE_OAUTH_TOKEN" | gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo "$TARGET"
+          echo -n "$GH_TOKEN_VALUE" | gh secret set GH_TOKEN --repo "$TARGET"
+          echo "Synced CLAUDE_APP_ID, CLAUDE_APP_PRIVATE_KEY, CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN → $TARGET"

.github/workflows/test-comprehensive.yml

@@ -37,10 +37,8 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5

.github/workflows/test-core.yml

@@ -22,8 +22,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:

.github/workflows/test-extended.yml

@@ -13,10 +13,8 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
 
     - name: Set up Python
       uses: actions/setup-python@v5
@@ -81,10 +79,8 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
 
     - name: Set up Python
       uses: actions/setup-python@v5

.github/workflows/test-frameworks.yml

@@ -33,10 +33,8 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5

.github/workflows/test-optimized.yml

@@ -45,8 +45,8 @@ jobs:
     timeout-minutes: 5
     steps:
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
@@ -105,8 +105,8 @@ jobs:
     
     steps:
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
@@ -187,8 +187,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11
@@ -259,8 +259,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11
@@ -318,8 +318,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11
@@ -377,8 +377,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11
@@ -436,8 +436,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11
@@ -495,8 +495,8 @@ jobs:
         fi
     
     - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
       if: steps.check-key.outputs.has_key == 'true'
     
     - name: Set up Python 3.11

.github/workflows/test-real.yml

@@ -45,10 +45,8 @@ jobs:
         
     - name: Checkout code
       uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-        with:
-          persist-credentials: false
+      with:
+        persist-credentials: false
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5

.gitignore

@@ -88,6 +88,9 @@ issue_details.json
 .internal
 .praisonai
 
+# Backup files
+*.bak
+
 # Rust / Cargo
 target/
 Cargo.lock

AGENTS.md

@@ -0,0 +1,10 @@
+# Agent Instructions
+
+You are working on the PraisonAI project.
+
+## Project Guidelines
+- Follow the existing code style and conventions
+- Be concise and helpful in responses  
+- Test implementation thoroughly
+- Ensure backward compatibility with existing APIs
+- Follow protocol-driven design: core protocols in praisonaiagents/, heavy implementations in praisonai/

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing to PraisonAI
+
+Thank you for your interest! Here's how to get started:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Guidelines
+
+- Follow existing code style
+- Add tests for new features
+- Update documentation as needed

README.md

@@ -770,11 +770,11 @@ agent.start('Write a movie script about a robot in Mars');
 
 ## ⚡ Performance
 
-PraisonAI is built for speed, with agent instantiation in under 4μs. This reduces overhead, improves responsiveness, and helps multi-agent systems scale efficiently in real-world production workloads.
+PraisonAI is built for speed, with agent instantiation in around 14μs. This reduces overhead, improves responsiveness, and helps multi-agent systems scale efficiently in real-world production workloads.
 
 | Performance Metric | PraisonAI |
 |--------------------|-----------|
-| Avg Instantiation Time | **3.77 μs** |
+| Avg Instantiation Time | **14 μs** |
 
 ---
 

api.md

@@ -15,6 +15,7 @@ Methods:
 * <code title="class GuardrailResult">GuardrailResult.<a href="./src/praisonai-agents/praisonaiagents/guardrails/guardrail_result.py">from_tuple</a>(result: Tuple[bool, Any]) -> 'GuardrailResult'</code>
 * <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">from_dict</a>(data: Dict[str, Any]) -> 'HandoffConfig'</code>
 * <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class HandoffResult">HandoffResult.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">from_outcome</a>(outcome: AgentRunOutcome, target_agent: Optional[str] = None, source_agent: Optional[str] = None, handoff_depth: int = 0) -> 'HandoffResult'</code>
 * <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">json</a>() -> Optional[str]</code>
 * <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">to_dict</a>() -> dict</code>
 * <code title="class ToolResult">ToolResult.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">to_dict</a>() -> Dict[str, Any]</code>
@@ -58,6 +59,8 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">handoff_to</a>(target_agent: 'Agent', prompt: str, context: Optional[Dict[str, Any]] = None, config: Optional['HandoffConfig'] = None) -> 'HandoffResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">handoff_to_async</a>(target_agent: 'Agent', prompt: str, context: Optional[Dict[str, Any]] = None, config: Optional['HandoffConfig'] = None) -> 'HandoffResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">is_closed</a>() -> bool</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">llm_instance</a>()</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">llm_instance</a>(value)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">llm_model</a>() -> Optional[str]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">output_style</a>() -> Optional[str]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">output_style</a>(value: Optional[str]) -> None</code>
@@ -75,7 +78,7 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until_async</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">skill_manager</a>() -> Optional[Any]</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">store_memory</a>(content: str, memory_type: str = 'short_term', **kwargs: Any) -> None</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">store_memory</a>(content: str, memory_type: str = 'short_term', action: str = 'add', **kwargs: Any) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>() -> Optional[Any]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>(value: Optional[Any]) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">thinking_budget</a>() -> Optional[int]</code>
@@ -175,6 +178,7 @@ Methods:
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_schema_roundtrip</a>() -> bool</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">__call__</a>(*args, **kwargs) -> Any</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">check_availability</a>() -> tuple[bool, str]</code>
+* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">get_schema</a>() -> Dict[str, Any]</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">injected_params</a>() -> Dict[str, Any]</code>
 * <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">run</a>(**kwargs) -> Any</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">clear</a>() -> None</code>
@@ -182,16 +186,18 @@ Methods:
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_single_file_plugins</a>() -> int</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get</a>(name: str) -> Optional[Union[BaseTool, Callable]]</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_all</a>() -> Dict[str, Union[BaseTool, Callable]]</code>
-* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">list_available_tools</a>(context: Optional[Dict[str, Any]] = None) -> List[Union[BaseTool, Callable]]</code>
+* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_tool_definitions</a>() -> List[Dict[str, Any]]</code>
+* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_trust_level</a>(name: str) -> Optional[str]</code>
+* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">list_available_tools</a>(context: Optional[Dict[str, Any]] = None, ttl_seconds: Optional[float] = None) -> List[Union[BaseTool, Callable]]</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">list_base_tools</a>() -> List[BaseTool]</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">list_tools</a>() -> List[str]</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">list_tools_with_allowed_filter</a>(context: Optional[Dict[str, Any]] = None) -> List[str]</code>
-* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">register</a>(tool: Union[BaseTool, Callable], name: Optional[str] = None, overwrite: bool = False) -> None</code>
+* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">register</a>(tool: Union[BaseTool, Callable], name: Optional[str] = None, overwrite: bool = False, trust_level: Optional[str] = None, dynamic_schema_overrides: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None) -> None</code>
 * <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">unregister</a>(name: str) -> bool</code>
 * <code title="class Tools">Tools.<a href="./src/praisonai-agents/praisonaiagents/tools/tools.py">internet_search</a>(*args, **kwargs)</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_registry</a>() -> ToolRegistry</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_tool</a>(name: str) -> Optional[Union[BaseTool, Callable]]</code>
-* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">register_tool</a>(tool: Union[BaseTool, Callable], name: Optional[str] = None) -> None</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">register_tool</a>(tool: Union[BaseTool, Callable], name: Optional[str] = None, trust_level: Optional[str] = None, dynamic_schema_overrides: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None) -> None</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">tool</a>(func: Optional[Callable] = None) -> Union[FunctionTool, Callable[[Callable], FunctionTool]]</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_tool</a>(tool: Any) -> bool</code>
 
@@ -236,6 +242,7 @@ from praisonaiagents import Memory, MemoryBackend, MemoryConfig
 
 Methods:
 
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">build_cache_optimized_context</a>(task_descr: str, user_id: Optional[str] = None, additional: str = '', max_items: int = 3, include_cache_boundary: bool = True, include_in_output: Optional[bool] = None) -> Dict[str, str]</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">build_context_for_task</a>(task_descr: str, user_id: Optional[str] = None, additional: str = '', max_items: int = 3, include_in_output: Optional[bool] = None) -> str</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">calculate_quality_metrics</a>(output: str, expected_output: str, llm: Optional[str] = None, custom_prompt: Optional[str] = None) -> Dict[str, float]</code>
 * <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">close_connections</a>()</code>
@@ -353,7 +360,7 @@ Methods:
 * <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">to_tool_function</a>(source_agent: 'Agent') -> Callable</code>
 * <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">tool_description</a>() -> str</code>
 * <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">tool_name</a>() -> str</code>
-* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">handoff</a>(agent: 'Agent', tool_name_override: Optional[str] = None, tool_description_override: Optional[str] = None, on_handoff: Optional[Callable] = None, input_type: Optional[type] = None, input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]] = None, config: Optional[HandoffConfig] = None, context_policy: Optional[str] = None, timeout_seconds: Optional[float] = None, max_concurrent: Optional[int] = None, detect_cycles: Optional[bool] = None, max_depth: Optional[int] = None) -> Handoff</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">handoff</a>(agent: 'Agent', tool_name_override: Optional[str] = None, tool_description_override: Optional[str] = None, on_handoff: Optional[Callable] = None, input_type: Optional[type] = None, input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]] = None, config: Optional[HandoffConfig] = None, context_policy: Optional[str] = None, timeout_seconds: Optional[float] = None, max_concurrent: Optional[int] = None, detect_cycles: Optional[bool] = None, max_depth: Optional[int] = None, tool_policy_mode: Optional[Literal['intersect', 'passthrough']] = None, blocked_tools: Optional[List[str]] = None) -> Handoff</code>
 * <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">compress_history</a>(data: HandoffInputData) -> HandoffInputData</code>
 * <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">keep_last_n_messages</a>(n: int) -> Callable[[HandoffInputData], HandoffInputData]</code>
 * <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">remove_all_tools</a>(data: HandoffInputData) -> HandoffInputData</code>
@@ -511,10 +518,12 @@ Methods:
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">add_memory</a>(text: str, memory_type: str = 'long', **metadata) -> None</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">chat</a>(message: str, **kwargs) -> str</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">clear_memory</a>(memory_type: str = 'all') -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">close</a>() -> None</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">create_agent</a>(*args, **kwargs) -> 'Agent'</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">get_context</a>(query: str, max_items: int = 3) -> str</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">get_state</a>(key: str, default: Any = None) -> Any</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">increment_state</a>(key: str, increment: int = 1, default: int = 0) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">is_expired</a>() -> bool</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">knowledge</a>() -> 'Knowledge'</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">memory</a>() -> 'Memory'</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">restore_state</a>() -> Dict[str, Any]</code>
@@ -523,6 +532,7 @@ Methods:
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">search_memory</a>(query: str, memory_type: str = 'long', limit: int = 5) -> List[Dict[str, Any]]</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">send_message</a>(message: str, **kwargs) -> str</code>
 * <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">set_state</a>(key: str, value: Any) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">time_to_expiry</a>() -> Optional[float]</code>
 
 # MCP
 
@@ -626,6 +636,7 @@ Methods:
 * <code title="class AutonomyConfig">AutonomyConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/autonomy.py">effective_track_changes</a>() -> bool</code>
 * <code title="class AutonomyConfig">AutonomyConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/autonomy.py">from_dict</a>(data: Dict[str, Any]) -> 'AutonomyConfig'</code>
 * <code title="class CachingConfig">CachingConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class ExecutionConfig">ExecutionConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">from_dict</a>(data: Dict[str, Any]) -> 'ExecutionConfig'</code>
 * <code title="class ExecutionConfig">ExecutionConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
 * <code title="class GuardrailConfig">GuardrailConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
 * <code title="class HooksConfig">HooksConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
@@ -693,7 +704,7 @@ Methods:
 
 Types:
 ```python
-from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, aembedding, aembeddings, embedding, embeddings, get_dimensions
+from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, __version__, aembedding, aembeddings, embedding, embeddings, get_dimensions
 ```
 
 Methods:
@@ -718,12 +729,16 @@ Methods:
 * <code title="class AgentFlow">AgentFlow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">verbose</a>(value: bool)</code>
 * <code title="class AgentOSProtocol">AgentOSProtocol.<a href="./src/praisonai-agents/praisonaiagents/app/protocols.py">get_app</a>() -> Any</code>
 * <code title="class AgentOSProtocol">AgentOSProtocol.<a href="./src/praisonai-agents/praisonaiagents/app/protocols.py">serve</a>(host: Optional[str] = None, port: Optional[int] = None, reload: bool = False, **kwargs: Any) -> None</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aannounce_completion</a>(agent_id: str, task_id: str, result: Any, success: bool = True, error: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">add_task</a>(task)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aexecute_task</a>(task_id)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">announce_completion</a>(agent_id: str, task_id: str, result: Any, success: bool = True, error: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">append_to_state</a>(key: str, value: Any, max_length: Optional[int] = None) -> List[Any]</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_all_tasks</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_task</a>(task_id)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aspawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart</a>(content = None, return_dict = False, **kwargs)</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">await_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clean_json_output</a>(output: str) -> str</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clear_state</a>() -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">close</a>() -> None</code>
@@ -738,6 +753,7 @@ Methods:
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_all_tasks_status</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_detailed_token_report</a>() -> Dict[str, Any]</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_plan_markdown</a>() -> str</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_spawned_agents</a>() -> List[SpawnedSubAgent]</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_state</a>(key: str, default: Any = None) -> Any</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_details</a>(task_id)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_result</a>(task_id)</code>
@@ -754,10 +770,12 @@ Methods:
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_output_to_file</a>(task, task_output)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> None</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">set_state</a>(key: str, value: Any) -> None</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">spawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start</a>(content = None, return_dict = False, output = None, **kwargs)</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">todo_list</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_plan_step_status</a>(step_id: str, status: str) -> bool</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_state</a>(updates: Dict) -> None</code>
+* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">wait_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
 * <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval</a>(request: ApprovalRequest) -> ApprovalDecision</code>
 * <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval_sync</a>(request: ApprovalRequest) -> ApprovalDecision</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembedding</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
@@ -777,11 +795,17 @@ Methods:
 
 * <code title="cli">praisonai <a href="./src/praisonai/praisonai/cli/main.py">--help</a></code>
 * <code title="cli">praisonai acp acp-main <a href="./src/praisonai/praisonai/cli/commands/acp.py">--help</a></code>
+* <code title="cli">praisonai agent list <a href="./src/praisonai/praisonai/cli/commands/agent.py">--help</a></code>
+* <code title="cli">praisonai agent show <a href="./src/praisonai/praisonai/cli/commands/agent.py">--help</a></code>
 * <code title="cli">praisonai agents create <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
 * <code title="cli">praisonai agents info <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
 * <code title="cli">praisonai agents list <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
 * <code title="cli">praisonai app app <a href="./src/praisonai/praisonai/cli/commands/app.py">--help</a></code>
 * <code title="cli">praisonai audit agent-centric <a href="./src/praisonai/praisonai/cli/commands/audit.py">--help</a></code>
+* <code title="cli">praisonai auth list <a href="./src/praisonai/praisonai/cli/commands/auth.py">--help</a></code>
+* <code title="cli">praisonai auth login <a href="./src/praisonai/praisonai/cli/commands/auth.py">--help</a></code>
+* <code title="cli">praisonai auth logout <a href="./src/praisonai/praisonai/cli/commands/auth.py">--help</a></code>
+* <code title="cli">praisonai auth status <a href="./src/praisonai/praisonai/cli/commands/auth.py">--help</a></code>
 * <code title="cli">praisonai batch batch-run <a href="./src/praisonai/praisonai/cli/commands/batch.py">--help</a></code>
 * <code title="cli">praisonai batch list <a href="./src/praisonai/praisonai/cli/commands/batch.py">--help</a></code>
 * <code title="cli">praisonai batch report <a href="./src/praisonai/praisonai/cli/commands/batch.py">--help</a></code>
@@ -822,6 +846,8 @@ Methods:
 * <code title="cli">praisonai claw claw <a href="./src/praisonai/praisonai/cli/commands/claw.py">--help</a></code>
 * <code title="cli">praisonai code <a href="./src/praisonai/praisonai/cli/main.py">--help</a></code>
 * <code title="cli">praisonai code code-main <a href="./src/praisonai/praisonai/cli/commands/code.py">--help</a></code>
+* <code title="cli">praisonai command list <a href="./src/praisonai/praisonai/cli/commands/command.py">--help</a></code>
+* <code title="cli">praisonai command show <a href="./src/praisonai/praisonai/cli/commands/command.py">--help</a></code>
 * <code title="cli">praisonai commit commit-main <a href="./src/praisonai/praisonai/cli/commands/commit.py">--help</a></code>
 * <code title="cli">praisonai completion bash <a href="./src/praisonai/praisonai/cli/commands/completion.py">--help</a></code>
 * <code title="cli">praisonai completion completion-callback <a href="./src/praisonai/praisonai/cli/commands/completion.py">--help</a></code>
@@ -834,6 +860,9 @@ Methods:
 * <code title="cli">praisonai config path <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
 * <code title="cli">praisonai config reset <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
 * <code title="cli">praisonai config set <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
+* <code title="cli">praisonai config show <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
+* <code title="cli">praisonai config sources <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
+* <code title="cli">praisonai config validate <a href="./src/praisonai/praisonai/cli/commands/config.py">--help</a></code>
 * <code title="cli">praisonai context add <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
 * <code title="cli">praisonai context clear <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
 * <code title="cli">praisonai context compact <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
@@ -868,10 +897,12 @@ Methods:
 * <code title="cli">praisonai doctor db <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor doctor-callback <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor env <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
+* <code title="cli">praisonai doctor fix <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor mcp <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor network <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor packaging <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor performance <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
+* <code title="cli">praisonai doctor runtime <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor selftest <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor skills <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai doctor tools <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
@@ -902,6 +933,9 @@ Methods:
 * <code title="cli">praisonai gateway install <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway logs <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway mint-link <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
+* <code title="cli">praisonai gateway pause <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
+* <code title="cli">praisonai gateway reconnect <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
+* <code title="cli">praisonai gateway resume <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway send <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway start <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway status <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
@@ -992,6 +1026,14 @@ Methods:
 * <code title="cli">praisonai pairing list <a href="./src/praisonai/praisonai/cli/commands/pairing.py">--help</a></code>
 * <code title="cli">praisonai pairing revoke <a href="./src/praisonai/praisonai/cli/commands/pairing.py">--help</a></code>
 * <code title="cli">praisonai paths show <a href="./src/praisonai/praisonai/cli/commands/paths.py">--help</a></code>
+* <code title="cli">praisonai permissions allow <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions ask <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions deny <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions export <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions import-rules <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions list <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions remove <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
+* <code title="cli">praisonai permissions reset <a href="./src/praisonai/praisonai/cli/commands/permissions.py">--help</a></code>
 * <code title="cli">praisonai plugins create <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
 * <code title="cli">praisonai plugins disable <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
 * <code title="cli">praisonai plugins discover <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
@@ -1290,7 +1332,7 @@ export { // Python parity additions
 export { // Subagent Tool (agent-as-tool pattern)
   SubagentTool, BaseTool, FunctionTool, ToolRegistry, ToolResult, ToolValidationError, createDelegator, createSubagentTool, createSubagentTools, createTool, getRegistry, getTool, registerTool, tool, validateTool } from "./tools";
 export { airweaveSearch, bedrockBrowserClick, bedrockBrowserFill, bedrockBrowserNavigate, bedrockCodeInterpreter, codeExecution, codeMode, createCustomTool, exaSearch, firecrawlCrawl, firecrawlScrape, parallelSearch, perplexitySearch, registerCustomTool, registerLocalTool, registerNpmTool, superagentGuard, superagentRedact, superagentVerify, tavilyCrawl, tavilyExtract, tavilySearch, valyuBioSearch, valyuCompanyResearch, valyuEconomicsSearch, valyuFinanceSearch, valyuPaperSearch, valyuPatentSearch, valyuSecSearch, valyuWebSearch } from "./tools/builtins";
-export { BudgetExceededError, MissingDependencyError, MissingEnvVarError, ToolsRegistry, composeMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createRedactionMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolsRegistry, createTracingMiddleware, createValidationMiddleware, getRegistry, getTool, getToolsRegistry, get_registry, get_tool, registerTool, register_tool, resetToolsRegistry, validateTool, validate_tool } from "./tools/registry";
+export { BudgetExceededError, MissingDependencyError, MissingEnvVarError, ToolsRegistry, composeMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createRedactionMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolsRegistry, createTracingMiddleware, createValidationMiddleware, getToolsRegistry, get_registry, get_tool, register_tool, resetToolsRegistry, validate_tool } from "./tools/registry";
 export type { InstallHints, PraisonTool, RedactionHooks, RegisteredTool, ToolCapabilities, ToolExecutionContext, ToolExecutionResult, ToolFactory, ToolHooks, ToolInstallStatus, ToolLimits, ToolLogger, ToolMetadata, ToolMiddleware, ToolParameterProperty, ToolParameterSchema } from "./tools/registry";
 export { registerBuiltinTools, tools } from "./tools/tools";
 export { // Classes

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.52" \
+    "praisonai>=4.6.67" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.52" \
+    "praisonai>=4.6.67" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.52" \
+    "praisonai>=4.6.67" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/benchmark/benchmark_example.py

@@ -35,7 +35,7 @@ def run_quick_comparison():
         prompt="What is 2+2?",
         iterations=2,
         paths=["openai_sdk", "praisonai_agent"],
-        output="verbose"
+        verbose=True
     )
     
     # Print comparison table
@@ -56,7 +56,7 @@ def run_full_benchmark():
     report = handler.run_full_benchmark(
         prompt="Hi",
         iterations=3,
-        output="verbose"
+        verbose=True
     )
     
     # Print full report
@@ -78,7 +78,7 @@ def run_agent_benchmark():
         prompt="Explain Python in one sentence",
         iterations=3,
         paths=["openai_sdk", "praisonai_agent"],
-        output="verbose"
+        verbose=True
     )
     
     # Show timeline diagrams

examples/compare/cli_compare_advanced.py

@@ -22,7 +22,7 @@ custom_modes = {
 }
 
 # Create handler with verbose output
-handler = CompareHandler(output="verbose")
+handler = CompareHandler(verbose=True)
 
 # Example: Manually create comparison results for analysis
 # (useful for testing without API calls)

examples/compare/cli_compare_basic.py

@@ -22,7 +22,7 @@ modes = parse_modes("basic,tools,planning")
 print(f"\nParsed modes: {modes}")
 
 # Create compare handler
-handler = CompareHandler(output="verbose")
+handler = CompareHandler(verbose=True)
 
 # Compare modes (this will run actual agent calls)
 # Uncomment to run:

examples/consolidated_params/advanced_memory.py

@@ -15,7 +15,7 @@ agent = Agent(
 # With array [preset, overrides]
 agent_override = Agent(
     instructions="You are a helpful assistant.",
-    memory=["redis", {"user_id": "custom_user"}],
+    memory=MemoryConfig(backend="redis", user_id="custom_user"),
 )
 
 if __name__ == "__main__":

examples/consolidated_params/advanced_workflow_full_features.py

@@ -32,7 +32,7 @@ workflow = AgentFlow(
         ),
     ],
     # Workflow-level consolidated params
-    output=WorkflowOutputConfig(output="verbose", stream=True),
+    output=WorkflowOutputConfig(verbose=True, stream=True),
     planning=WorkflowPlanningConfig(enabled=True, reasoning=True),
     memory=WorkflowMemoryConfig(backend="file"),
     # Agent-like params

examples/consolidated_params/basic_web.py

@@ -5,12 +5,12 @@ Demonstrates web search with consolidated params.
 Presets: duckduckgo, tavily, google, bing, serper, search_only, fetch_only
 """
 
-from praisonaiagents import Agent
+from praisonaiagents import Agent, WebConfig
 
-# Basic: Enable web search with preset
+# Basic: Enable web search with preset (search only — fetch needs Claude)
 agent = Agent(
     instructions="You are a research assistant with web access.",
-    web="duckduckgo",  # Presets: duckduckgo, tavily, google, bing, serper
+    web=WebConfig(search=True, fetch=False, search_provider="duckduckgo"),
 )
 
 if __name__ == "__main__":

examples/consolidated_params/basic_workflow.py

@@ -15,8 +15,20 @@ workflow = AgentFlow(
     ],
     output="verbose",
     planning=True,
+    variables={"topic": "AI agents"},
 )
 
 if __name__ == "__main__":
-    result = workflow.run(variables={"topic": "AI agents"})
+    import os
+    import sys
+
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY to run this example.")
+        sys.exit(0)
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    result = workflow.run("AI agents")
     print(result)

examples/eval/accuracy_example.py

@@ -24,7 +24,7 @@ if has_api_key:
         input_text="What is 2 + 2?",
         expected_output="4",
         num_iterations=3,  # Run 3 times for statistical significance
-        output="verbose"
+        verbose=True
     )
 
     # Run evaluation
@@ -42,7 +42,7 @@ else:
         input_text="What is 2 + 2?",
         expected_output="4",
         num_iterations=1,
-        output="verbose"
+        verbose=True
     )
     
     # Test with mock output

examples/eval/criteria_example.py

@@ -27,7 +27,7 @@ if has_api_key:
         scoring_type="numeric",  # Score 1-10
         threshold=7.0,           # Pass if score >= 7
         num_iterations=2,
-        output="verbose"
+        verbose=True
     )
 
     # Run evaluation
@@ -45,7 +45,7 @@ if has_api_key:
         agent=agent,
         input_text="Tell me a joke",
         scoring_type="binary",  # Pass or Fail
-        output="verbose"
+        verbose=True
     )
 
     binary_result = binary_evaluator.run(print_summary=True)

examples/eval/performance_example.py

@@ -26,7 +26,7 @@ if has_api_key:
         num_iterations=10,  # Run 10 benchmark iterations
         warmup_runs=2,      # 2 warmup runs before measurement
         track_memory=True,  # Track memory usage
-        output="verbose"
+        verbose=True
     )
 
     # Run evaluation

examples/eval/reliability_example.py

@@ -48,7 +48,7 @@ if has_api_key:
         input_text="Search for the weather in Paris and calculate 25 * 4",
         expected_tools=["search_web", "calculate"],  # Tools that should be called
         forbidden_tools=["delete_file"],  # Tools that should NOT be called
-        output="verbose"
+        verbose=True
     )
 
     # Run evaluation
@@ -70,7 +70,7 @@ evaluator = ReliabilityEvaluator(
     agent=mock_agent,
     expected_tools=["search_web", "calculate"],  # Tools that should be called
     forbidden_tools=["delete_file"],  # Tools that should NOT be called
-    output="verbose"
+    verbose=True
 )
 
 result2 = evaluator.evaluate_tool_calls(

examples/knowledge/compression_demo.py

@@ -184,7 +184,7 @@ Answer questions based ONLY on the provided knowledge context.
 When asked about codes, provide the EXACT code from the documents.
 Be concise but accurate.""",
             knowledge=[temp_dir],
-            user_id="compression_demo_user",
+            memory={"user_id": "compression_demo_user"},
             output="verbose",
         )
         

examples/knowledge/hierarchical_summaries_demo.py

@@ -164,7 +164,7 @@ Answer questions based ONLY on the provided knowledge context.
 When asked about department codes, provide the EXACT code from the documents.
 Be specific about which department you're referring to.""",
             knowledge=[temp_dir],
-            user_id="hierarchy_demo_user",
+            memory={"user_id": "hierarchy_demo_user"},
             output="verbose",
         )
         

examples/knowledge/large_corpus_strategy_demo.py

@@ -124,7 +124,7 @@ def main():
             # Show strategy selection for different corpus sizes
             print(f"\nStrategy selection by corpus size:")
             for size in [100, 1000, 10000, 50000, 100000]:
-                strategy = select_strategy(corpus_tokens=size)
+                strategy = select_strategy(CorpusStats(file_count=max(1, size // 1000), total_tokens=size))
                 print(f"  {size:>6} tokens -> {strategy.value}")
                 
         except ImportError as e:
@@ -142,7 +142,7 @@ Answer questions based ONLY on the provided knowledge context.
 When asked about verification codes, provide the EXACT code from the documents.
 If information is not in the context, say 'Information not found in documents.'""",
             knowledge=[temp_dir],
-            user_id="strategy_demo_user",
+            memory={"user_id": "strategy_demo_user"},
             output="verbose",  # Use new consolidated param
         )
         

examples/knowledge/mem0_backend_example.py

@@ -65,7 +65,7 @@ def main():
             name="PolicyExpert",
             instructions="You are a company policy expert. Answer questions based ONLY on the provided knowledge. Quote exact values when asked about codes or numbers.",
             knowledge=[temp_dir],  # Add directory with documents
-            user_id="example_user",  # Required for mem0 backend
+            memory={"user_id": "example_user"},
         )
         
         print("\n1. Testing Agent.chat() with context-required question:")

examples/knowledge/scope_identifiers_example.py

@@ -50,7 +50,7 @@ def main():
             name="HR_Assistant_User1",
             instructions="You are an HR assistant.",
             knowledge=[temp_dir],
-            user_id="user_alice",  # Knowledge scoped to Alice
+            memory={"user_id": "user_alice"},
         )
         
         response = user1_agent.chat("What is the policy on remote work?")
@@ -80,7 +80,7 @@ def main():
             name="Personal_HR_Bot",
             instructions="You are a personal HR assistant.",
             knowledge=[temp_dir],
-            user_id="user_bob",
+            memory={"user_id": "user_bob"},
             agent_id="hr_bot_v2",
         )
         

examples/knowledge/scope_isolation_example.py

@@ -49,7 +49,7 @@ Only authorized personnel with code WRENCH-992 may access this project.
             name="AgentA_Ingester",
             instructions="You ingest and store knowledge.",
             knowledge=[temp_dir],
-            user_id="user_alice",  # Scoped to Alice
+            memory={"user_id": "user_alice"},
             output="silent",
         )
         
@@ -103,7 +103,7 @@ Only authorized personnel with code WRENCH-992 may access this project.
             name="AgentB_Querier",
             instructions="Answer questions based on the provided knowledge. If you don't have the information, say so.",
             knowledge=[temp_dir],
-            user_id="user_alice",  # Same scope as Agent A
+            memory={"user_id": "user_alice"},
             output="silent",
         )
         

examples/persistence/knowledge_qdrant.py

@@ -50,10 +50,10 @@ print("=== Qdrant Knowledge Store Demo (Agent-First) ===")
 agent = Agent(
     name="KnowledgeAssistant",
     instructions="You are a helpful assistant with access to technical documentation.",
-    knowledge=[doc_path],
     knowledge={
+        "sources": [doc_path],
         "vector_store": "qdrant",
-        "url": "http://localhost:6333"
+        "url": "http://localhost:6333",
     }
 )
 

examples/python/agents/code-agent.py

@@ -6,10 +6,18 @@ It includes self-reflection for improving code quality and multiple specialized
 """
 
 from praisonaiagents import Agent, Task, AgentTeam
-from praisonaiagents.tools import CodeInterpreter
 
-# Initialize code execution tool
-code_interpreter = CodeInterpreter()
+def run_python_code(code: str) -> str:
+    """Execute Python code safely and return stdout or errors."""
+    import io
+    import contextlib
+    try:
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            exec(code, {"__builtins__": __builtins__})
+        return buf.getvalue() or "Executed successfully (no output)"
+    except Exception as e:
+        return f"Execution error: {e}"
 
 # Custom code analysis tool
 def analyze_code_complexity(code: str) -> str:
@@ -32,9 +40,7 @@ code_writer = Agent(
     goal="Write clean, efficient, and well-documented Python code",
     backstory="You are a senior Python developer with 10+ years of experience in writing production-quality code.",
     instructions="Write Python code that follows PEP 8 standards, includes proper error handling, and has clear documentation.",
-    reflection=True,
-    
-    
+    output="silent",
 )
 
 code_reviewer = Agent(
@@ -52,7 +58,7 @@ code_executor = Agent(
     goal="Safely execute and test Python code",
     backstory="You are responsible for running code and reporting results or errors.",
     instructions="Execute the provided code safely and report the output or any errors encountered.",
-    tools=[code_interpreter]
+    tools=[run_python_code]
 )
 
 # Example tasks
@@ -87,7 +93,7 @@ def demonstrate_code_agent():
     workflow = AgentTeam(
         agents=[code_writer, code_reviewer, code_executor],
         tasks=[write_task, review_task, execute_task],
-        process="sequential", output="verbose"
+        process="sequential", output="silent"
     )
     
     # Run the workflow
@@ -106,10 +112,8 @@ general_code_agent = Agent(
 3. Explain code concepts
 4. Refactor code for better performance
 5. Add tests and documentation""",
-    tools=[code_interpreter, analyze_code_complexity],
-    reflection=True,
-    
-    
+    tools=[run_python_code, analyze_code_complexity],
+    output="silent",
 )
 
 if __name__ == "__main__":

examples/python/agents/math-agent.py

@@ -41,21 +41,25 @@ def calculate_statistics(numbers: list) -> str:
     """Calculate basic statistics for a list of numbers."""
     if not numbers:
         return "No numbers provided"
-    
-    n = len(numbers)
-    mean = sum(numbers) / n
-    sorted_nums = sorted(numbers)
+    try:
+        nums = [float(x) for x in numbers]
+    except (TypeError, ValueError):
+        return "Error: all values must be numbers"
+
+    n = len(nums)
+    mean = sum(nums) / n
+    sorted_nums = sorted(nums)
     median = sorted_nums[n//2] if n % 2 else (sorted_nums[n//2-1] + sorted_nums[n//2]) / 2
-    variance = sum((x - mean)**2 for x in numbers) / n
+    variance = sum((x - mean)**2 for x in nums) / n
     std_dev = math.sqrt(variance)
-    
+
     return f"""Statistics:
 - Count: {n}
 - Mean: {mean:.4f}
 - Median: {median:.4f}
 - Standard Deviation: {std_dev:.4f}
-- Min: {min(numbers)}
-- Max: {max(numbers)}"""
+- Min: {min(nums)}
+- Max: {max(nums)}"""
 
 # Create specialized math agents
 calculation_agent = Agent(
@@ -66,8 +70,7 @@ calculation_agent = Agent(
     instructions="Perform the requested calculations step by step, showing your work clearly.",
     tools=[basic_calculator, solve_quadratic, calculate_statistics],
     reflection=True,
-    
-    
+    output="silent",
 )
 
 problem_solver_agent = Agent(
@@ -82,8 +85,7 @@ problem_solver_agent = Agent(
 4. Show each step of the solution
 5. Verify the answer makes sense""",
     reflection=True,
-    
-    
+    output="silent",
 )
 
 math_tutor_agent = Agent(
@@ -91,7 +93,8 @@ math_tutor_agent = Agent(
     role="Mathematics tutor and explainer",
     goal="Explain mathematical concepts clearly and help users understand math",
     backstory="You are a patient math tutor who can explain concepts at any level from elementary to advanced.",
-    instructions="Explain mathematical concepts using simple language, provide examples, and check for understanding."
+    instructions="Explain mathematical concepts using simple language, provide examples, and check for understanding.",
+    output="silent",
 )
 
 # Example workflow for solving complex problems
@@ -126,7 +129,8 @@ def solve_math_problem_workflow():
     workflow = AgentTeam(
         agents=[problem_solver_agent, calculation_agent, math_tutor_agent],
         tasks=[understand_task, solve_task, verify_task],
-        process="sequential", output="verbose"
+        process="sequential",
+        output="silent",
     )
     
     return workflow.start()
@@ -148,8 +152,7 @@ math_assistant = Agent(
 Always show your work step by step.""",
     tools=[basic_calculator, solve_quadratic, calculate_statistics],
     reflection=True,
-    
-    
+    output="silent",
 )
 
 if __name__ == "__main__":

examples/python/bot_run_control_example.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+Example: Bot In-Flight Run Control
+
+Demonstrates how to use SessionRunControl to provide better UX for bots
+during long-running agent operations. Shows busy feedback, pending message
+handling, and /stop command support.
+
+This example shows the "before" and "after" behavior described in issue #1914.
+"""
+
+import asyncio
+import time
+from typing import Optional
+
+# Mock agent for demonstration
+class MockAgent:
+    """Simple mock agent that simulates long-running tasks."""
+    
+    def __init__(self, name="assistant"):
+        self.name = name
+        self.chat_history = []
+        self._interrupt_controller = None
+    
+    def chat(self, prompt: str) -> str:
+        """Simulate a long-running chat response."""
+        print(f"[Agent] Starting to process: '{prompt[:50]}...'")
+        
+        # Simulate long processing with interrupt checking
+        for i in range(30):  # 3 second task (30 x 0.1s)
+            time.sleep(0.1)
+            
+            # Check for interruption
+            if (self._interrupt_controller and 
+                hasattr(self._interrupt_controller, 'is_set') and
+                self._interrupt_controller.is_set()):
+                reason = getattr(self._interrupt_controller, 'reason', 'unknown')
+                print(f"[Agent] ⚠️ Interrupted: {reason}")
+                raise InterruptedError(f"Task cancelled: {reason}")
+                
+        response = f"Completed analysis of: {prompt}"
+        print(f"[Agent] ✅ Finished: {response}")
+        return response
+
+
+async def demo_without_run_control():
+    """Demonstrate the old behavior (silent blocking)."""
+    print("\n" + "="*60)
+    print("🔴 BEFORE: Without Run Control (Silent Blocking)")
+    print("="*60)
+    
+    from praisonai.bots._session import BotSessionManager
+    
+    # Standard session manager (no run control)
+    session_mgr = BotSessionManager()
+    agent = MockAgent("research-agent")
+    user_id = "user123"
+    
+    print("\n1. User sends long task:")
+    print("   User: 'research quantum computing trends'")
+    
+    # Start first task (this will run for 3 seconds)
+    task1 = asyncio.create_task(
+        session_mgr.chat(agent, user_id, "research quantum computing trends")
+    )
+    
+    # Simulate user sending follow-up messages during execution
+    await asyncio.sleep(0.5)
+    print("\n2. User sends follow-up (this will block silently):")
+    print("   User: 'actually focus on business impact'")
+    
+    task2 = asyncio.create_task(
+        session_mgr.chat(agent, user_id, "actually focus on business impact")  
+    )
+    
+    await asyncio.sleep(0.5)
+    print("\n3. User tries to send /stop (this will also block):")
+    print("   User: '/stop'")
+    
+    task3 = asyncio.create_task(
+        session_mgr.chat(agent, user_id, "/stop")
+    )
+    
+    print("\n⏳ Waiting for all messages to complete...")
+    results = await asyncio.gather(task1, task2, task3)
+    
+    print("\n📊 Results (all processed sequentially with no feedback):")
+    for i, result in enumerate(results, 1):
+        print(f"   {i}. {result}")
+    
+    print("\n❌ Problems with this approach:")
+    print("   - No immediate feedback on follow-up messages")
+    print("   - No way to cancel long-running tasks") 
+    print("   - User doesn't know if bot is working or broken")
+
+
+async def demo_with_run_control():
+    """Demonstrate the new behavior with run control."""
+    print("\n" + "="*60)
+    print("🟢 AFTER: With Run Control (Better UX)")  
+    print("="*60)
+    
+    from praisonai.bots._run_control import SessionRunControl
+    from praisonai.bots._session import BotSessionManager
+    from praisonai.bots._commands import handle_stop_command
+    
+    # Session manager with run control
+    run_control = SessionRunControl(
+        busy_mode="queue",
+        busy_ack_template="⏳ {action} — will process after current task finishes"
+    )
+    session_mgr = BotSessionManager(run_control=run_control)
+    agent = MockAgent("research-agent")
+    user_id = "user123"
+    
+    print("\n1. User sends long task:")
+    print("   User: 'research quantum computing trends'")
+    
+    # Start first task
+    task1 = asyncio.create_task(
+        session_mgr.chat_with_run_control(agent, user_id, "research quantum computing trends")
+    )
+    
+    # Immediate follow-up messages get acknowledgments
+    await asyncio.sleep(0.5)
+    print("\n2. User sends follow-up (gets immediate feedback):")
+    print("   User: 'actually focus on business impact'")
+    
+    result2 = await session_mgr.chat_with_run_control(
+        agent, user_id, "actually focus on business impact"
+    )
+    print(f"   Bot: {result2['response']}")
+    print(f"   Metadata: {result2['metadata']}")
+    
+    await asyncio.sleep(0.5)
+    print("\n3. User decides to stop current task:")
+    print("   User: '/stop'")
+    
+    stop_response = await handle_stop_command(user_id, run_control)
+    print(f"   Bot: {stop_response}")
+    
+    # Wait for first task to complete (it should be cancelled)
+    try:
+        result1 = await task1
+        print(f"\n📊 Task 1 result: {result1['response']}")
+        print(f"   Metadata: {result1['metadata']}")
+    except asyncio.CancelledError:
+        print("\n📊 Task 1 was cancelled as expected")
+    
+    print("\n4. User sends fresh request after stopping:")
+    print("   User: 'what's the weather like?'")
+    
+    result4 = await session_mgr.chat_with_run_control(
+        agent, user_id, "what's the weather like?"
+    )
+    print(f"   Bot: {result4['response']}")
+    
+    print("\n✅ Benefits of this approach:")
+    print("   - Immediate feedback on all messages")
+    print("   - Can cancel long-running tasks with /stop")
+    print("   - Pending messages are queued and processed in order")
+    print("   - User always knows what's happening")
+
+
+async def demo_interrupt_mode():
+    """Demonstrate interrupt mode."""
+    print("\n" + "="*60)
+    print("⚡ BONUS: Interrupt Mode (Cancel and Restart)")
+    print("="*60)
+    
+    from praisonai.bots._run_control import SessionRunControl
+    from praisonai.bots._session import BotSessionManager
+    
+    # Use interrupt mode instead of queue mode
+    run_control = SessionRunControl(busy_mode="interrupt")
+    session_mgr = BotSessionManager(run_control=run_control)
+    agent = MockAgent("research-agent")
+    user_id = "user123"
+    
+    print("\n1. User starts long task:")
+    print("   User: 'research renewable energy for 30 pages'")
+    
+    task1 = asyncio.create_task(
+        session_mgr.chat_with_run_control(agent, user_id, "research renewable energy for 30 pages")
+    )
+    
+    await asyncio.sleep(0.5)
+    print("\n2. User changes mind (interrupts and restarts):")
+    print("   User: 'actually just summarize solar panel efficiency'")
+    
+    result2 = await session_mgr.chat_with_run_control(
+        agent, user_id, "actually just summarize solar panel efficiency"
+    )
+    print(f"   Bot: {result2['response']}")
+    
+    # Wait for original task (should be interrupted)
+    try:
+        result1 = await task1
+        print(f"\n📊 Original task result: {result1['response']}")
+        if result1['metadata'].get('interrupted'):
+            print("   ✅ Original task was properly interrupted")
+    except:
+        print("\n📊 Original task was cancelled")
+    
+    print("\n✅ Interrupt mode is great for:")
+    print("   - When users frequently change direction")
+    print("   - Interactive sessions where latest intent matters most")
+    print("   - Real-time collaboration scenarios")
+
+
+async def main():
+    """Run all demonstrations."""
+    print("🚀 Bot In-Flight Run Control Demo")
+    print("Solving the silent lock problem described in issue #1914")
+    
+    # Show the problem
+    await demo_without_run_control()
+    
+    # Show the solution  
+    await demo_with_run_control()
+    
+    # Show advanced feature
+    await demo_interrupt_mode()
+    
+    print("\n" + "="*60)
+    print("🎯 Summary")
+    print("="*60)
+    print("SessionRunControl solves the silent blocking problem by providing:")
+    print("1. Immediate feedback for mid-run messages")
+    print("2. /stop command support via InterruptController")
+    print("3. Configurable policies (queue/interrupt/steer)")
+    print("4. Run generation tracking to prevent race conditions")
+    print("5. Pending message merging and ordering")
+    print("\nThis makes bot interactions feel responsive and predictable!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/cli/git_integration_example.py

@@ -8,7 +8,7 @@ Docs: https://docs.praison.ai/cli/git-integration
 from praisonai.cli.features import GitIntegrationHandler
 
 # Initialize
-handler = GitIntegrationHandler(output="verbose")
+handler = GitIntegrationHandler(verbose=True)
 git = handler.initialize(repo_path=".")
 
 # Check if it's a git repo

examples/python/cli/repo_map_example.py

@@ -8,7 +8,7 @@ Docs: https://docs.praison.ai/cli/repo-map
 from praisonai.cli.features import RepoMapHandler
 
 # Initialize with current directory
-handler = RepoMapHandler(output="verbose")
+handler = RepoMapHandler(verbose=True)
 repo_map = handler.initialize(root=".")
 
 # Get the repository map

examples/python/cli/sandbox_execution_example.py

@@ -9,7 +9,7 @@ from praisonai.cli.features import SandboxExecutorHandler
 from praisonai.cli.features.sandbox_executor import SandboxMode
 
 # Initialize with basic sandbox
-handler = SandboxExecutorHandler(output="verbose")
+handler = SandboxExecutorHandler(verbose=True)
 sandbox = handler.initialize(mode="basic")
 
 print(f"Sandbox mode: {handler.get_mode()}")

examples/python/concepts/chat-with-pdf.py

@@ -25,8 +25,7 @@ pdf_agent = Agent(
     goal="Help users understand and extract information from PDF documents",
     backstory="You are an expert at reading, analyzing, and answering questions about PDF documents. You provide accurate, detailed answers based on the document content.",
     instructions="Read the provided PDF document and answer questions about its content. Be specific and cite relevant sections when possible.",
-    knowledge=["document.pdf"],  # Replace with your PDF file path
-    knowledge=config,
+    knowledge={**config, "sources": ["document.pdf"]},  # Replace with your PDF path
     reflection=True,
     
     

examples/python/concepts/knowledge-agents-task.py

@@ -1,6 +1,9 @@
+from pathlib import Path
+
 from praisonaiagents import Agent, Task, AgentTeam
 import logging
 import os
+import sys
 
 # Configure logging
 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
@@ -17,14 +20,18 @@ config = {
     }
 }
 
+_sample_path = Path(__file__).with_name("sample_knowledge.txt")
+if not _sample_path.exists():
+    _sample_path.write_text("Mervin Praison is the creator of PraisonAI.\n", encoding="utf-8")
+
 # Create an agent with knowledge capabilities
 knowledge_agent = Agent(
     name="KnowledgeAgent",
     role="Information Specialist",
     goal="Store and retrieve knowledge efficiently",
     backstory="Expert in managing and utilizing stored knowledge",
-    knowledge=["sample.pdf"],
-    knowledge=config)
+    knowledge={**config, "sources": [str(_sample_path)]},
+)
 
 # Define a task for the agent
 knowledge_task = Task(
@@ -39,8 +46,16 @@ agents = AgentTeam(
     agents=[knowledge_agent],
     tasks=[knowledge_task],
     process="sequential",
-    user_id="user1"
 )
 
-# Start execution
-result = agents.start()
+if __name__ == "__main__":
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY to run this example.")
+        sys.exit(0)
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    result = agents.start()
+    print(result)

examples/python/concepts/knowledge-reranker-example.py

@@ -138,8 +138,7 @@ def main():
     agent = Agent(
         name="AI Research Assistant",
         instructions="You are an AI research assistant. Use your knowledge base to answer questions about artificial intelligence topics.",
-        knowledge=sample_documents,  # Will use default knowledge config
-        knowledge=rerank_config,  # Use reranking config
+        knowledge={**rerank_config, "sources": sample_documents},
         llm="gpt-4o-mini"
     )
     

examples/python/concepts/rag-agents.py

@@ -32,8 +32,12 @@ rag_task = Task(
 agents = AgentTeam(
     agents=[rag_agent],
     tasks=[rag_task],
-    user_id="user1"
 )
 
-# Start Agents
-agents.start()
+if __name__ == "__main__":
+    import os
+    import sys
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY to run this example.")
+        sys.exit(0)
+    agents.start()

examples/python/general/memory_example.py

@@ -5,7 +5,7 @@ import os
 def main():
     # Initialize memory config
     memory_config = {
-        "provider": "rag",
+        "backend": "sqlite",
         "use_embedding": True,
         "storage": {
             "type": "sqlite",
@@ -105,7 +105,7 @@ def main():
         agents=[researcher, retriever],
         tasks=[store_task, verify_task, query_task, query_both_task],  # Use same verbose level as memory
         memory={
-            "provider": "rag",
+            "backend": "sqlite",
             "embedder": {
                 "provider": "openai",
                 "config": {

examples/python/memory/advanced-graph-memory-integration.py

@@ -60,8 +60,8 @@ query_task = Task(
 agents_system = AgentTeam(
     agents=[knowledge_agent],
     tasks=[build_task, query_task],
-    memory=True,
-    memory=memory_config, output="verbose"
+    memory=memory_config,
+    output="verbose",
 )
 
 print("Starting graph memory demonstration...")

examples/python/memory/advanced-memory-search-optimization.py

@@ -61,8 +61,8 @@ search_task = Task(
 agents_system = AgentTeam(
     agents=[research_agent],
     tasks=[build_memory_task, search_task],
-    memory=True,
-    memory=memory_config, output="verbose"
+    memory=memory_config,
+    output="verbose",
 )
 
 print("Starting memory search optimization demonstration...")

examples/python/memory/gemini-embedding-example.py

@@ -86,7 +86,7 @@ def main():
         agents=[researcher, retriever],
         tasks=[store_task, retrieve_task],
         memory={
-            "provider": "rag",
+            "backend": "sqlite",
             "embedder": {
                 "provider": "gemini",
                 "config": {

examples/python/memory/graph-memory-agent.py

@@ -152,8 +152,7 @@ def main():
     agents_system = AgentTeam(
         agents=[researcher],
         tasks=[build_knowledge_task, query_knowledge_task, expand_knowledge_task],
-        memory=True,
-        memory=memory_config
+        memory=memory_config,
     )
     
     print("\n🚀 Starting graph memory demonstration...")

examples/python/memory_with_tracing_example.py

@@ -30,7 +30,7 @@ def main():
     try:
         # Create memory instance
         memory = Memory(config={
-            "provider": "rag",
+            "backend": "sqlite",
             "use_embedding": False,
             "agent_name": "demo_agent",  # Used in trace events
         })

examples/python/message_steering_example.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Message Steering Example
+
+Demonstrates real-time message steering for agents during execution.
+Shows how to send guidance messages to agents while they're running tasks.
+
+Usage:
+    # Python API
+    python message_steering_example.py
+    
+    # CLI with steering enabled
+    praisonai --message-steering "Write a detailed report about AI trends" 
+    
+    # YAML (add message_steering: true to agent config)
+"""
+
+import asyncio
+import threading
+import time
+from praisonaiagents import Agent
+
+
+def basic_message_steering():
+    """Basic message steering example - enable steering and send guidance."""
+    print("🎯 Basic Message Steering Example")
+    print("=" * 50)
+    
+    # Create agent with message steering enabled
+    agent = Agent(
+        name="researcher", 
+        instructions="You are a helpful research assistant",
+        message_steering=True,  # Enable real-time message steering
+        llm="gpt-4o-mini"
+    )
+    
+    print("✅ Agent created with message steering enabled")
+    print(f"📊 Steering status: {agent.get_steering_status()}")
+    
+    # Send some guidance
+    msg_id_1 = agent.steer("Focus on recent developments from 2024")
+    msg_id_2 = agent.steer("Keep response under 200 words", priority=10)
+    
+    print(f"📨 Sent steering messages: {msg_id_1}, {msg_id_2}")
+    print(f"📊 Steering status: {agent.get_steering_status()}")
+    
+    # Execute task - steering will be automatically injected
+    result = agent.start("Summarize the latest AI trends")
+    
+    print("\n📝 Result:")
+    print(result)
+
+
+def threaded_message_steering():
+    """Advanced example - send steering messages while agent is running."""
+    print("\n🚀 Threaded Message Steering Example")
+    print("=" * 50)
+    
+    agent = Agent(
+        name="writer",
+        instructions="You are a content writer", 
+        message_steering=True,
+        llm="gpt-4o-mini"
+    )
+    
+    result_holder = [None]
+    
+    def run_agent():
+        """Run agent in background thread."""
+        result = agent.start("Write a comprehensive article about quantum computing")
+        result_holder[0] = result
+    
+    # Start agent in background
+    thread = threading.Thread(target=run_agent)
+    thread.start()
+    
+    # Send steering messages while it's running
+    time.sleep(0.5)  # Let execution start
+    agent.steer("Make it accessible to beginners")
+    
+    time.sleep(1.0) 
+    agent.steer("Include practical applications", priority=15)
+    
+    time.sleep(1.5)
+    agent.steer("Keep it under 300 words total", priority=20)
+    
+    # Wait for completion
+    thread.join(timeout=60)
+    
+    if result_holder[0]:
+        print("\n📝 Final Result:")
+        print(result_holder[0])
+    else:
+        print("⚠️ Agent execution timed out")
+
+
+async def async_message_steering():
+    """Async example showing message steering with async execution."""
+    print("\n⚡ Async Message Steering Example")
+    print("=" * 50)
+    
+    agent = Agent(
+        name="analyst",
+        instructions="You are a data analyst",
+        message_steering=True,
+        llm="gpt-4o-mini"
+    )
+    
+    # Start async task
+    async def run_analysis():
+        return await agent.astart("Analyze the impact of AI on job markets")
+    
+    # Create task
+    task = asyncio.create_task(run_analysis())
+    
+    # Send steering while running
+    await asyncio.sleep(0.3)
+    agent.steer("Focus on positive opportunities")
+    
+    await asyncio.sleep(0.7)  
+    agent.steer("Include specific examples", priority=12)
+    
+    # Wait for result
+    result = await task
+    
+    print("\n📝 Analysis Result:")
+    print(result)
+
+
+def cli_yaml_examples():
+    """Show CLI and YAML usage examples."""
+    print("\n💻 CLI & YAML Examples")
+    print("=" * 50)
+    
+    print("🔧 CLI Usage:")
+    print("  praisonai --message-steering 'Your task here'")
+    print("  # Then in another terminal:")
+    print("  # agent.steer('Additional guidance')")
+    
+    print("\n📄 YAML Configuration:")
+    yaml_example = """
+# agents.yaml
+framework: praisonai
+roles:
+  researcher:
+    role: Research Assistant
+    goal: Conduct thorough research
+    backstory: Expert researcher with steering support
+    message_steering: true    # Enable steering for this agent
+    tools:
+      - internet_search
+      - write_file
+    tasks:
+      research_task:
+        description: Research AI trends and write report
+        expected_output: Comprehensive research report
+"""
+    print(yaml_example.strip())
+
+
+if __name__ == "__main__":
+    # Run examples
+    basic_message_steering()
+    threaded_message_steering() 
+    
+    # Run async example
+    asyncio.run(async_message_steering())
+    
+    # Show CLI/YAML usage
+    cli_yaml_examples()
+    
+    print("\n✨ Message steering examples completed!")
+    print("📚 See docs for more advanced patterns and priority levels")

examples/python/models/deepseek/deepseek-rag-agents-streamlit.py

@@ -32,9 +32,8 @@ def init_agent():
     return Agent(
         name="Knowledge Agent",
         instructions="You answer questions based on the provided knowledge.",
-        knowledge=["kag-research-paper.pdf"],
-        knowledge=config,
-        user_id="user1",
+        knowledge={**config, "sources": ["kag-research-paper.pdf"]},
+        memory={"user_id": "user1"},
         llm="deepseek-r1"
     )
 

examples/python/models/deepseek/deepseek-rag-agents.py

@@ -30,9 +30,8 @@ config = {
 agent = Agent(
     name="Knowledge Agent",
     instructions="You answer questions based on the provided knowledge.",
-    knowledge=["kag-research-paper.pdf"], # Indexing
-    knowledge=config,
-    user_id="user1",
+    knowledge={**config, "sources": ["kag-research-paper.pdf"]},
+    memory={"user_id": "user1"},
     llm="deepseek-r1"
 )
 

examples/python/mongodb/mongodb_comprehensive_example.py

@@ -189,8 +189,8 @@ def main():
     business_system = AgentTeam(
         agents=[data_manager, knowledge_curator, business_analyst, customer_service],
         tasks=business_tasks,
-        memory=True,
-        memory=mongodb_memory_config, output="verbose"
+        memory=mongodb_memory_config,
+        output="verbose",
     )
     
     # Execute the comprehensive business pipeline

examples/python/mongodb/mongodb_knowledge_example.py

@@ -55,8 +55,10 @@ def main():
         retrieve information from a comprehensive MongoDB knowledge base. You excel 
         at finding relevant information, synthesizing knowledge from multiple sources, 
         and providing accurate, context-aware responses.""",
-        knowledge=mongodb_knowledge_config,
-        knowledge=[os.path.join(os.path.dirname(__file__), "llms.md")],
+        knowledge={
+            **mongodb_knowledge_config,
+            "sources": [os.path.join(os.path.dirname(__file__), "llms.md")],
+        },
         memory=True,
         llm="gpt-4o-mini"
     )

examples/python/mongodb/mongodb_memory_example.py

@@ -93,8 +93,8 @@ def main():
     research_system = AgentTeam(
         agents=[research_agent],
         tasks=research_tasks,
-        memory=True,
-        memory=mongodb_memory_config, output="verbose"
+        memory=mongodb_memory_config,
+        output="verbose",
     )
     
     # Execute the research pipeline

examples/python/rag/agent_vs_auto_rag.py

@@ -50,7 +50,7 @@ agent = Agent(
     name="TechSupport",
     instructions="You are a technical support assistant.",
     knowledge=[sample_doc],
-    user_id="comparison_user",
+    memory={"user_id": "comparison_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/rag/auto_rag_agent_basic.py

@@ -20,8 +20,9 @@ if not os.environ.get("OPENAI_API_KEY"):
     exit(1)
 
 # Create a sample document for testing
-sample_doc = "/tmp/sample_doc.txt"
-with open(sample_doc, "w") as f:
+from pathlib import Path
+sample_doc = str(Path(__file__).with_name("sample_doc.txt"))
+with open(sample_doc, "w", encoding="utf-8") as f:
     f.write("""
 PraisonAI Framework Documentation
 
@@ -44,7 +45,7 @@ agent = Agent(
     name="DocBot",
     instructions="You are a helpful documentation assistant. Answer questions based on the provided context.",
     knowledge=[sample_doc],
-    user_id="example_user",  # Required for RAG retrieval
+    memory={"user_id": "example_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/rag/auto_rag_agent_policy.py

@@ -38,7 +38,7 @@ agent = Agent(
     name="PolicyBot",
     instructions="You are a customer service assistant.",
     knowledge=[sample_doc],
-    user_id="policy_user",
+    memory={"user_id": "policy_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/rag/rag_basic.py

@@ -44,7 +44,7 @@ agent = Agent(
     name="MLExpert",
     instructions="You are a machine learning expert. Answer questions based on the provided context.",
     knowledge=[sample_doc],
-    user_id="rag_user",
+    memory={"user_id": "rag_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/rag/rag_hybrid.py

@@ -59,7 +59,7 @@ agent = Agent(
     name="APIDocBot",
     instructions="You are an API documentation assistant.",
     knowledge=[sample_doc],
-    user_id="hybrid_user",
+    memory={"user_id": "hybrid_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/rag/rag_with_citations.py

@@ -44,7 +44,7 @@ agent = Agent(
     name="ResearchBot",
     instructions="You are a research assistant. Always cite your sources.",
     knowledge=[doc1, doc2],
-    user_id="citation_user",
+    memory={"user_id": "citation_user"},
     llm="openai/gpt-4o-mini",
     output="minimal",
 )

examples/python/sessions/comprehensive-session-management.py

@@ -172,7 +172,7 @@ print("="*70)
 # Create sessions for different users working on the same project
 reviewer_session = Session(
     session_id="peer_review_001",
-    user_id="user_reviewer_01",  # Different user
+    user_id="user_reviewer_01",
     storage_path=session_dir
 )
 

examples/python/stateful/memory-quality-example.py

@@ -14,13 +14,12 @@ def main():
     
     # Initialize memory with quality-based configuration
     memory_config = {
-        "provider": "rag",
-        "use_embedding": True,
-        "rag_db_path": "quality_memory_db"
+        "backend": "sqlite",
+        "user_id": "quality_demo_user",
     }
     
     memory = Memory(config=memory_config, verbose=5)
-    print(f"📦 Initialized memory system with provider: {memory_config['provider']}")
+    print(f"📦 Initialized memory system with backend: {memory_config['backend']}")
     
     # Create agent with memory
     agent = Agent(
@@ -28,7 +27,6 @@ def main():
         role="Information Quality Specialist",
         instructions="Store and retrieve information with quality assessment",
         memory=memory,
-        user_id="quality_demo_user"
     )
     
     print(f"🤖 Created agent: {agent.name}")
@@ -181,7 +179,7 @@ def main():
     
     context = memory.build_context_for_task(
         task_descr="Explain AI alignment challenges",
-        user_id="quality_demo_user",
+        memory={"user_id": "quality_demo_user"},
         max_items=3
     )
     

examples/python/stateful/session-example.py

@@ -15,7 +15,7 @@ def main():
     # Create a session with persistent storage
     session = Session(
         session_id="demo_chat_001",
-        user_id="demo_user"
+        memory={"user_id": "demo_user"},
     )
     
     print(f"📝 Created session: {session}")

examples/python/stateful/workflow-state-example.py

@@ -88,9 +88,8 @@ def main():
     workflow = AgentTeam(
         agents=[researcher, analyzer, writer],
         tasks=[research_task, analysis_task, report_task],
-        memory=True,
+        memory={"user_id": "research_project_001"},
         process="workflow",
-        user_id="research_project_001",
     )
     
     print(f"🤖 Created workflow with {len(workflow.agents)} agents and {len(workflow.tasks)} tasks")

examples/python/tools/jira_agent_example.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+JIRA Agent Watch Example
+
+This example demonstrates how to use the JIRA watch tools with PraisonAI agents.
+The agent can monitor JIRA issues and projects for changes, search for issues,
+and get detailed issue information.
+
+Setup:
+1. Install JIRA library: pip install jira
+2. Set environment variables:
+   - [email protected] (for cloud JIRA)
+   - JIRA_API_TOKEN=your_api_token
+   - Or use JIRA_USERNAME + JIRA_API_TOKEN for server JIRA
+
+Usage:
+    python jira_agent_example.py
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.tools import jira_tools
+
+
+def main():
+    """Demonstrate JIRA agent watch capabilities."""
+    
+    # Check if JIRA credentials are available
+    jira_email = os.getenv('JIRA_EMAIL')
+    jira_token = os.getenv('JIRA_API_TOKEN')
+    jira_username = os.getenv('JIRA_USERNAME')
+    
+    if not jira_token:
+        print("❌ JIRA_API_TOKEN environment variable not set")
+        print("Please set your JIRA API token:")
+        print("export JIRA_API_TOKEN='your_token_here'")
+        return
+        
+    if not (jira_email or jira_username):
+        print("❌ JIRA credentials incomplete")
+        print("Please set either:")
+        print("- JIRA_EMAIL (for cloud JIRA)")
+        print("- JIRA_USERNAME (for server JIRA)")
+        return
+
+    # Create agent with JIRA tools
+    agent = Agent(
+        name="JIRA Monitor Agent",
+        instructions="""
+        You are a JIRA monitoring agent. You can:
+        
+        1. Watch specific JIRA issues for changes
+        2. Monitor JIRA projects for new issues and updates  
+        3. Search for issues using JQL queries
+        4. Get detailed information about specific issues
+        
+        When using JIRA tools, always provide the full JIRA URL 
+        (e.g., https://yourcompany.atlassian.net).
+        
+        Be helpful and provide clear summaries of JIRA activity.
+        """,
+        tools=jira_tools(),  # Add all JIRA tools
+        llm="gpt-4o-mini"
+    )
+    
+    print("🎯 JIRA Agent Watch Example")
+    print("=" * 50)
+    print()
+    print("Available JIRA tools:")
+    print("- jira_watch_issue: Monitor a specific issue for changes")
+    print("- jira_watch_project: Monitor a project for new/updated issues")
+    print("- jira_get_issue_info: Get detailed info about an issue")  
+    print("- jira_search_issues: Search issues using JQL")
+    print()
+    
+    # Example interactions
+    example_prompts = [
+        "Get information about JIRA issue DEMO-1 from https://praisonai.atlassian.net",
+        "Search for open issues in project DEMO from https://praisonai.atlassian.net using JQL: 'project = DEMO AND status = Open'",
+        "Watch JIRA issue DEMO-1 from https://praisonai.atlassian.net for 2 minutes (check every 60 seconds, max 2 checks)",
+    ]
+    
+    print("📝 Example prompts you can try:")
+    for i, prompt in enumerate(example_prompts, 1):
+        print(f"{i}. {prompt}")
+    print()
+    
+    # Interactive mode
+    print("💬 Interactive JIRA Agent (type 'quit' to exit)")
+    print("-" * 50)
+    
+    while True:
+        try:
+            user_input = input("\n🧑 You: ").strip()
+            
+            if user_input.lower() in ['quit', 'exit', 'q']:
+                print("👋 Goodbye!")
+                break
+                
+            if not user_input:
+                continue
+                
+            print("🤖 Agent: ", end="", flush=True)
+            response = agent.start(user_input)
+            print(response)
+            
+        except KeyboardInterrupt:
+            print("\n👋 Goodbye!")
+            break
+        except Exception as e:
+            print(f"❌ Error: {e}")
+
+
+if __name__ == "__main__":
+    main()

examples/python/toolsets_example.py

@@ -0,0 +1,227 @@
+"""
+Named Toolsets Example
+
+This example demonstrates how to use named toolsets to organize and reuse 
+groups of tools across agents and workflows.
+
+Toolsets provide:
+- Organized tool collections (web, research, development, etc.)
+- Progressive disclosure (safe → research → development)
+- Composable design (toolsets can include other toolsets)
+- YAML configuration support
+"""
+
+import os
+from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents.toolsets import (
+    list_toolsets, 
+    resolve_toolset,
+    register_toolset
+)
+
+# Set up environment (replace with your actual API key)
+os.environ.setdefault("OPENAI_API_KEY", "your-openai-api-key-here")
+
+
+def demo_basic_toolsets():
+    """Demonstrate basic toolset functionality."""
+    print("=== Basic Toolsets Demo ===")
+    
+    # List available toolsets
+    available_toolsets = list_toolsets()
+    print(f"Available toolsets: {available_toolsets}")
+    
+    # Show what tools are in each prebuilt toolset
+    for toolset_name in ["safe", "web", "research"]:
+        tools = resolve_toolset(toolset_name)
+        print(f"\n{toolset_name.upper()} toolset contains: {tools}")
+
+
+def demo_agent_with_toolsets():
+    """Demonstrate agents using toolsets."""
+    print("\n=== Agent with Toolsets Demo ===")
+    
+    # Create a research agent with research toolset
+    researcher = Agent(
+        name="researcher",
+        role="Research Specialist",
+        goal="Research topics thoroughly using web tools",
+        instructions="You are a research specialist with access to web search and file tools.",
+        toolsets=["research"],  # includes web tools + file tools
+        llm="gpt-4o-mini"
+    )
+    
+    print(f"Research agent has {len(researcher.tools)} tools available")
+    print(f"Tools: {[getattr(t, '__name__', str(t)) for t in researcher.tools]}")
+    
+    # Create a safe agent with minimal tools
+    safe_agent = Agent(
+        name="safe_assistant",
+        role="Safe Assistant", 
+        goal="Help users safely without risky operations",
+        instructions="You are a helpful assistant with access to only safe, read-only tools.",
+        toolsets=["safe"],
+        llm="gpt-4o-mini"
+    )
+    
+    print(f"\nSafe agent has {len(safe_agent.tools)} tools available")
+    print(f"Safe tools: {[getattr(t, '__name__', str(t)) for t in safe_agent.tools]}")
+
+
+def demo_custom_toolsets():
+    """Demonstrate creating and using custom toolsets."""
+    print("\n=== Custom Toolsets Demo ===")
+    
+    # Register a custom toolset for data analysis
+    register_toolset(
+        "data_analysis",
+        tools=["read_file", "write_file"],
+        includes=["safe"],  # Include safe tools too
+        description="Tools for data analysis workflows"
+    )
+    
+    # Create an agent with the custom toolset
+    analyst = Agent(
+        name="data_analyst",
+        role="Data Analyst",
+        goal="Analyze data files and generate reports",
+        instructions="You specialize in data analysis. Read files, process data, and write reports.",
+        toolsets=["data_analysis"],
+        llm="gpt-4o-mini"
+    )
+    
+    print(f"Data analyst has {len(analyst.tools)} tools available")
+    print(f"Analysis tools: {[getattr(t, '__name__', str(t)) for t in analyst.tools]}")
+
+
+def demo_mixed_tools_and_toolsets():
+    """Demonstrate mixing explicit tools with toolsets."""
+    print("\n=== Mixed Tools and Toolsets Demo ===")
+    
+    # Create agent with both explicit tools and toolsets
+    hybrid_agent = Agent(
+        name="hybrid_assistant",
+        role="Hybrid Assistant",
+        goal="Assist with both research and custom tasks",
+        instructions="You can research topics and perform custom analysis tasks.",
+        tools=["write_file"],  # Explicit tool
+        toolsets=["research"],  # Toolset with web + file tools
+        llm="gpt-4o-mini"
+    )
+    
+    print(f"Hybrid agent has {len(hybrid_agent.tools)} tools available")
+    tool_names = [getattr(t, '__name__', str(t)) for t in hybrid_agent.tools]
+    print(f"Hybrid tools: {tool_names}")
+    
+    # Note: write_file might appear twice (once explicit, once from toolset)
+    # The agent handles deduplication automatically
+
+
+def demo_multi_agent_with_toolsets():
+    """Demonstrate multi-agent workflows with different toolsets."""
+    print("\n=== Multi-Agent with Toolsets Demo ===")
+    
+    # Create agents with different toolsets for different roles
+    researcher = Agent(
+        name="researcher",
+        role="Research Specialist",
+        goal="Research topics and gather information",
+        toolsets=["research"],
+        llm="gpt-4o-mini"
+    )
+    
+    writer = Agent(
+        name="writer",
+        role="Content Writer",  
+        goal="Write content based on research",
+        toolsets=["safe"],  # Safe tools for writing
+        llm="gpt-4o-mini"
+    )
+    
+    # Create tasks for each agent
+    research_task = Task(
+        name="research_task",
+        description="Research the benefits of renewable energy",
+        expected_output="A summary of key benefits of renewable energy",
+        agent=researcher
+    )
+    
+    writing_task = Task(
+        name="writing_task", 
+        description="Write a blog post about renewable energy based on the research",
+        expected_output="A well-written blog post about renewable energy benefits",
+        agent=writer
+    )
+    
+    # Create team with different toolsets per agent
+    team = AgentTeam(
+        agents=[researcher, writer],
+        tasks=[research_task, writing_task],
+        process="sequential"
+    )
+    
+    print(f"Team created with {len(team.agents)} agents using different toolsets")
+    print(f"Research agent tools: {len(researcher.tools)}")
+    print(f"Writer agent tools: {len(writer.tools)}")
+
+
+def demo_yaml_config():
+    """Show how toolsets work in YAML configuration."""
+    print("\n=== YAML Configuration Example ===")
+    
+    yaml_config = """
+# agents.yaml - Example using toolsets
+agents:
+  researcher:
+    role: Research Specialist
+    goal: Research topics thoroughly
+    toolsets:
+      - research  # Includes web search, file tools
+    llm: gpt-4o-mini
+    
+  analyst:
+    role: Data Analyst
+    goal: Analyze research data
+    tools:
+      - write_file  # Explicit tool
+    toolsets:
+      - safe  # Safe toolset
+    llm: gpt-4o-mini
+
+tasks:
+  research_task:
+    description: Research renewable energy trends
+    agent: researcher
+    expected_output: Research summary
+    
+  analysis_task:
+    description: Analyze the research data
+    agent: analyst
+    expected_output: Analysis report
+"""
+    
+    print("Example YAML configuration with toolsets:")
+    print(yaml_config)
+    print("Use: praisonai run 'Research renewable energy' --toolset research")
+    print("Or:  praisonai chat --toolset web,files")
+
+
+if __name__ == "__main__":
+    print("🛠️  PraisonAI Named Toolsets Example")
+    print("=" * 50)
+    
+    # Run all demos
+    demo_basic_toolsets()
+    demo_agent_with_toolsets()
+    demo_custom_toolsets()
+    demo_mixed_tools_and_toolsets()
+    demo_multi_agent_with_toolsets()
+    demo_yaml_config()
+    
+    print("\n✅ Toolsets example completed!")
+    print("\n💡 Key Benefits:")
+    print("   • Organized tool collections")
+    print("   • Progressive disclosure (safe → research → development)")
+    print("   • Reusable across agents and workflows") 
+    print("   • YAML configuration support")
+    print("   • Composable design with includes")

examples/python/ui/ollama-rag-agents-streamlit.py

@@ -32,9 +32,8 @@ def init_agent():
     return Agent(
         name="Knowledge Agent",
         instructions="You answer questions based on the provided knowledge.",
-        knowledge=["kag-research-paper.pdf"],
-        knowledge=config,
-        user_id="user1",
+        knowledge={**config, "sources": ["kag-research-paper.pdf"]},
+        memory={"user_id": "user1"},
         llm="deepseek-r1"
     )
 

examples/python/usecases/domain-context-solution.py

@@ -264,13 +264,12 @@ agents = AgentTeam(
     tasks=[tool_query_task, pentester_analysis_task, ciso_review_task],
     process="hierarchical",
     manager_llm="gpt-4o-mini",
-    memory=True,  # Enable shared memory for domain context
     memory={
-        "provider": "rag",
+        "backend": "sqlite",
         "config": {
             "collection_name": f"{domain.replace('.', '_')}_security_analysis"
-        }
-    }
+        },
+    },
 )
 
 # Main Execution Workflow

examples/python/workflows/simple_workflow.py

@@ -5,7 +5,7 @@ Demonstrates using Agent instances directly as workflow steps.
 Each agent processes the input and passes output to the next agent.
 """
 
-from praisonaiagents import Agent, Workflow
+from praisonaiagents import Agent, AgentFlow
 
 # Create agents with specific roles
 researcher = Agent(

examples/python/workflows/workflow_branching.py

@@ -6,7 +6,6 @@ to different next steps based on output content.
 """
 
 from praisonaiagents import AgentFlow, Task
-from praisonaiagents import AgentFlowManager
 
 # Create a workflow with branching
 workflow = AgentFlow(
@@ -36,16 +35,9 @@ workflow = AgentFlow(
 )
 
 if __name__ == "__main__":
-    # Create manager and register workflow
-    manager = WorkflowManager()
-    manager.workflows["Decision Workflow"] = workflow
-    
-    # Execute - will branch to success_handler since 42 is positive
-    result = manager.execute(
-        "Decision Workflow",
-        default_llm="gpt-4o-mini"
-    )
-    
+    result = workflow.run("", llm="gpt-4o-mini", verbose=True)
     print("Workflow completed!")
-    for step_result in result["results"]:
-        print(f"  {step_result['step']}: {step_result['status']}")
+    for step in result.get("steps", []):
+        name = step.get("step", step.get("name", "unknown"))
+        status = step.get("status", "completed")
+        print(f"  {name}: {status}")

examples/python/workflows/workflow_conditional.py

@@ -54,11 +54,13 @@ workflow = AgentFlow(
         analyzer,  # Always runs
         Task(
             name="tech_review",
+            description="Review technical aspects of the content",
             agent=tech_reviewer,
             should_run=is_technical  # Only runs for technical content
         ),
         Task(
             name="creative_enhance",
+            description="Enhance the creative aspects of the content",
             agent=creative_enhancer,
             should_run=needs_creative  # Only runs for creative content
         ),

examples/python/workflows/workflow_early_stop.py

@@ -6,9 +6,8 @@ functions that return StepResult with stop_workflow=True.
 """
 
 from praisonaiagents import (
-    Workflow, Task, WorkflowContext, StepResult
+    AgentFlow, Task, WorkflowContext, StepResult
 )
-from praisonaiagents import AgentFlowManager
 
 # Custom validator that can stop the workflow
 def validate_data(context: WorkflowContext) -> StepResult:
@@ -50,20 +49,13 @@ workflow = AgentFlow(
 )
 
 if __name__ == "__main__":
-    manager = WorkflowManager()
-    manager.workflows["Data Processing"] = workflow
-    
-    # Test with invalid data (will stop early)
     print("=== Testing with invalid data ===")
-    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
-    
-    for step_result in result["results"]:
-        print(f"  {step_result['step']}: {step_result['output']}")
-    
-    # Test with valid data (will complete)
+    result = workflow.run("", llm="gpt-4o-mini", verbose=True)
+    for step in result.get("steps", []):
+        print(f"  {step.get('step', 'step')}: {step.get('output', step.get('status'))}")
+
     print("\n=== Testing with valid data ===")
     workflow.variables["data"] = {"value": 42}
-    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
-    
-    for step_result in result["results"]:
-        print(f"  {step_result['step']}: {step_result['status']}")
+    result = workflow.run("", llm="gpt-4o-mini", verbose=True)
+    for step in result.get("steps", []):
+        print(f"  {step.get('step', 'step')}: {step.get('status', 'completed')}")

examples/python/workflows/workflow_loops.py

@@ -6,7 +6,6 @@ Each item is processed individually with the loop variable.
 """
 
 from praisonaiagents import AgentFlow, Task
-from praisonaiagents import AgentFlowManager
 
 # Create a workflow with loop
 workflow = AgentFlow(
@@ -30,18 +29,12 @@ workflow = AgentFlow(
 )
 
 if __name__ == "__main__":
-    # Create manager and register workflow
-    manager = WorkflowManager()
-    manager.workflows["Process Items"] = workflow
-    
-    # Execute - will process each fruit in the list
-    result = manager.execute(
-        "Process Items",
-        default_llm="gpt-4o-mini"
-    )
-    
+    result = workflow.run("", llm="gpt-4o-mini", verbose=True)
     print("Workflow completed!")
-    for step_result in result["results"]:
-        print(f"  {step_result['step']}: {step_result['status']}")
-        if isinstance(step_result.get("output"), list):
-            print(f"    Loop processed {len(step_result['output'])} items")
+    for step in result.get("steps", []):
+        name = step.get("step", step.get("name", "unknown"))
+        status = step.get("status", "completed")
+        print(f"  {name}: {status}")
+        out = step.get("output")
+        if isinstance(out, list):
+            print(f"    Loop processed {len(out)} items")

examples/python/workflows/workflow_mixed_steps.py

@@ -53,7 +53,7 @@ workflow = AgentFlow(
         # Step 4: Function - formats output
         format_output
     ],
-    default_llm="gpt-4o-mini"  # Used for action-based steps
+    llm="gpt-4o-mini"  # Used for action-based steps
 )
 
 if __name__ == "__main__":

examples/python/workflows/workflow_parallel.py

@@ -5,7 +5,7 @@ Demonstrates running multiple agents concurrently and
 combining their results with an aggregator agent.
 """
 
-from praisonaiagents import Agent, Workflow
+from praisonaiagents import Agent, AgentFlow
 from praisonaiagents.workflows import parallel
 
 # Create parallel research agents

examples/python/workflows/workflow_routing.py

@@ -5,7 +5,7 @@ Demonstrates decision-based routing where an agent classifier
 routes to specialized handler agents based on the request type.
 """
 
-from praisonaiagents import Agent, Workflow
+from praisonaiagents import Agent, AgentFlow
 from praisonaiagents.workflows import route
 
 # Create classifier agent

examples/rag/external_sources.py

@@ -207,7 +207,7 @@ def api_augmented_rag():
         instructions="""You are a financial assistant with access to market APIs.
         Provide accurate financial information and context.
         Always note that prices are subject to change.""",
-        user_id="api_demo"
+        memory={"user_id": "api_demo"},
     )
     
     queries = [

examples/yaml/message_steering_example.yaml

@@ -0,0 +1,47 @@
+framework: praisonai
+topic: AI Research with Message Steering
+
+roles:
+  researcher:
+    role: AI Research Analyst
+    goal: Conduct comprehensive AI research with real-time guidance
+    backstory: You are an expert AI researcher who can receive and incorporate real-time guidance during your work
+    message_steering: true  # Enable real-time message steering
+    tools:
+      - internet_search
+      - write_file
+    tasks:
+      research_task:
+        description: |
+          Research the latest developments in AI and write a comprehensive report.
+          You may receive additional guidance during execution via message steering.
+        expected_output: |
+          A well-structured research report covering recent AI developments,
+          incorporating any real-time guidance received during execution.
+
+  writer:
+    role: Technical Writer
+    goal: Write clear, engaging content based on research
+    backstory: You are a skilled technical writer who can adapt content based on real-time feedback
+    message_steering: true  # Enable steering for dynamic content adjustment
+    tools:
+      - read_file
+      - write_file
+    tasks:
+      writing_task:
+        description: |
+          Take the research findings and create an accessible article for a general audience.
+          Adjust style and focus based on any steering messages received.
+        expected_output: |
+          A polished article that transforms technical research into accessible content,
+          refined based on real-time steering guidance.
+
+dependencies:
+  - writing_task: [research_task]
+
+# Usage Instructions:
+# 1. Run: praisonai --agent-file message_steering_example.yaml
+# 2. While running, use steering API to send guidance:
+#    agent.steer("Focus more on practical applications")
+#    agent.steer("Keep it under 500 words", priority=15)
+#    agent.steer("Add more examples", priority=10)

examples/yaml/toolsets_workflow.yaml

@@ -0,0 +1,148 @@
+# Named Toolsets YAML Example
+# This example demonstrates using toolsets in YAML configuration
+
+# Global configuration
+config:
+  llm: gpt-4o-mini
+  memory: true
+
+# Define agents with different toolsets
+agents:
+  # Research agent with research toolset (includes web tools)
+  researcher:
+    role: Senior Research Analyst
+    goal: Research topics thoroughly using web search and analysis tools
+    instructions: |
+      You are a senior research analyst with access to web search and file tools.
+      Research topics comprehensively and provide detailed findings.
+    toolsets:
+      - research  # Includes: web search, file tools, basic analysis
+    
+  # Writer agent with safe toolset for writing tasks
+  writer:
+    role: Content Writer
+    goal: Create engaging content based on research
+    instructions: |
+      You are a skilled content writer. Transform research into clear,
+      engaging content for the target audience.
+    toolsets:
+      - safe  # Safe, read-only tools for writing
+    
+  # Developer agent with development toolset
+  developer:
+    role: Software Developer
+    goal: Create and modify code based on requirements
+    instructions: |
+      You are a software developer with access to development tools.
+      Write, test, and debug code according to specifications.
+    toolsets:
+      - development  # Includes: code tools, file operations, testing
+      
+  # Data analyst with mixed tools and toolsets
+  analyst:
+    role: Data Analyst  
+    goal: Analyze data and generate insights
+    instructions: |
+      You are a data analyst. Process data files and generate
+      actionable insights and visualizations.
+    tools:
+      - read_file  # Explicit tool
+      - write_file  # Explicit tool
+    toolsets:
+      - safe  # Safe toolset for analysis
+      
+  # Security-focused agent with minimal toolset
+  security_auditor:
+    role: Security Auditor
+    goal: Review and audit for security issues
+    instructions: |
+      You are a security auditor with minimal tool access.
+      Focus on reading and analyzing without making changes.
+    toolsets:
+      - safe  # Minimal, safe tools only
+
+# Define tasks for the workflow
+tasks:
+  # Research task using research toolset
+  research_phase:
+    description: |
+      Research the latest trends in AI agent frameworks.
+      Focus on:
+      - Popular frameworks and their features
+      - Industry adoption patterns
+      - Security considerations
+      - Performance benchmarks
+    expected_output: |
+      A comprehensive research report covering AI agent frameworks,
+      including trends, adoption, security, and performance data.
+    agent: researcher
+    
+  # Content creation using safe toolset
+  content_creation:
+    description: |
+      Create a technical blog post based on the research findings.
+      The post should be:
+      - Well-structured with clear sections
+      - Accessible to technical and non-technical audiences  
+      - Include actionable insights
+      - 1000-1500 words
+    expected_output: |
+      A polished blog post about AI agent frameworks suitable
+      for publication on a technical blog.
+    agent: writer
+    
+  # Code development using development toolset
+  code_examples:
+    description: |
+      Create code examples demonstrating key concepts from the research.
+      Include:
+      - Simple "hello world" style examples
+      - Intermediate use cases
+      - Best practices examples
+      - Proper documentation
+    expected_output: |
+      A collection of well-documented code examples that illustrate
+      the concepts discussed in the research and blog post.
+    agent: developer
+    
+  # Data analysis using mixed tools/toolsets
+  trend_analysis:
+    description: |
+      Analyze the research data to identify trends and patterns.
+      Create:
+      - Summary statistics
+      - Trend analysis
+      - Recommendations based on findings
+    expected_output: |
+      A data analysis report with trends, patterns, and
+      actionable recommendations for AI framework adoption.
+    agent: analyst
+    
+  # Security review using minimal toolset
+  security_review:
+    description: |
+      Review all outputs for security considerations.
+      Check for:
+      - Potential security vulnerabilities in code examples
+      - Security best practices in recommendations
+      - Privacy considerations in data handling
+    expected_output: |
+      A security review report identifying any security concerns
+      and recommendations for secure implementation.
+    agent: security_auditor
+
+# Workflow process (sequential execution)
+process: sequential
+
+# Optional: Define workflow dependencies
+# tasks:
+#   research_phase:
+#     dependencies: []
+#   content_creation: 
+#     dependencies: [research_phase]
+#   code_examples:
+#     dependencies: [research_phase]
+#   trend_analysis:
+#     dependencies: [research_phase]
+#   security_review:
+#     dependencies: [content_creation, code_examples, trend_analysis]

src/praisonai-agents/AGENTS.md

@@ -378,7 +378,7 @@ Agent parameters are consolidated into Config objects following the pattern:
 
 | Config Object | Replaces (Deprecated) |
 |--------------|----------------------|
-| `execution=ExecutionConfig(code_execution=True, code_mode="safe", rate_limiter=obj)` | `allow_code_execution`, `code_execution_mode`, `rate_limiter` |
+| `execution=ExecutionConfig(code_execution=True, code_mode="safe", rate_limiter=obj, context_compaction=False)` | `allow_code_execution`, `code_execution_mode`, `rate_limiter` |
 | `memory=MemoryConfig(auto_save="session_name")` | `auto_save` |
 | `autonomy=AutonomyConfig(verification_hooks=[...])` | `verification_hooks` |
 | `handoffs=[other_agent]` | `allow_delegation` |
@@ -390,6 +390,8 @@ Agent parameters are consolidated into Config objects following the pattern:
 
 **Deprecated standalone params still work** (backward compatible) but emit `DeprecationWarning`.
 
+> **📢 Deprecation Notice:** `ExecutionConfig.context_compaction` currently defaults to `False` during a deprecation period. In the next release, it will default to `True` for automatic proactive context overflow protection. To opt out explicitly, set `context_compaction=False`. To use the new behavior early, set `context_compaction=True`.
+
 ```python
 # ❌ Old way (deprecated)
 agent = Agent(
@@ -413,6 +415,7 @@ agent = Agent(
         code_execution=True,
         code_mode="safe",
         rate_limiter=my_limiter,
+        context_compaction=False,  # prepare for next release when default becomes True; warning still fires during deprecation period
     ),
     memory=MemoryConfig(auto_save="my_session"),
     autonomy=AutonomyConfig(verification_hooks=[my_hook]),

src/praisonai-agents/DOCS_PARITY.md

@@ -1,6 +1,6 @@
 # Documentation Parity Tracker (Python)
 
-> **Categories:** 60 | **Documented:** 57 | **Parity:** 95.0%
+> **Categories:** 64 | **Documented:** 61 | **Parity:** 95.3%
 
 This report compares **Python SDK feature categories** against **Python documentation** (docs/concepts, docs/features, etc.).
 
@@ -8,72 +8,76 @@ This report compares **Python SDK feature categories** against **Python document
 
 | Metric | Count |
 |--------|-------|
-| Feature Categories | 60 |
-| **Documented Categories** | **57** |
+| Feature Categories | 64 |
+| **Documented Categories** | **61** |
 | **Undocumented Categories** | **3** |
-| **Parity** | **95.0%** |
+| **Parity** | **95.3%** |
 
 ## Documented Categories
 
 | Category | Features | Docs | Lines |
 |----------|----------|------|-------|
 | ✅ AGUI | 1 | 2 | 420 |
-| ✅ Agent | 19 | 30 | 8367 |
-| ✅ Agent-to-Agent (A2A) | 1 | 3 | 625 |
-| ✅ Approval | 1 | 2 | 889 |
+| ✅ Agent | 21 | 34 | 9360 |
+| ✅ Agent-to-Agent (A2A) | 1 | 7 | 2880 |
+| ✅ Agent-to-User (A2U) | 1 | 3 | 547 |
+| ✅ Approval | 1 | 3 | 1283 |
 | ✅ Audio | 2 | 10 | 649 |
-| ✅ Auto Generation | 3 | 6 | 1386 |
-| ✅ Autonomy | 3 | 4 | 1146 |
-| ✅ Bots | 5 | 2 | 573 |
+| ✅ Auto Generation | 4 | 6 | 1724 |
+| ✅ Autonomy | 3 | 5 | 1919 |
+| ✅ Bots | 7 | 14 | 5228 |
+| ✅ Budget | 1 | 1 | 287 |
+| ✅ CLI | 5 | 98 | 24103 |
 | ✅ Chunking | 2 | 2 | 285 |
 | ✅ Citations | 2 | 1 | 202 |
-| ✅ Code Execution | 3 | 13 | 3395 |
+| ✅ Code Execution | 3 | 13 | 3551 |
 | ✅ Conditions | 1 | 3 | 1086 |
-| ✅ Configuration | 2 | 7 | 1753 |
-| ✅ Context Management | 13 | 29 | 7576 |
-| ✅ Database | 1 | 31 | 3037 |
+| ✅ Configuration | 3 | 7 | 1812 |
+| ✅ Context Management | 16 | 31 | 9294 |
+| ✅ Database | 1 | 34 | 4339 |
 | ✅ Display | 6 | 2 | 1175 |
 | ✅ Embeddings | 6 | 23 | 1966 |
-| ✅ Evaluation | 1 | 6 | 2538 |
-| ✅ Events | 1 | 2 | 699 |
-| ✅ Execution | 3 | 2 | 515 |
-| ✅ Files | 2 | 5 | 863 |
-| ✅ Flow | 1 | 1 | 284 |
-| ✅ Gateway | 6 | 1 | 256 |
-| ✅ Guardrails | 4 | 4 | 2279 |
-| ✅ Handoffs | 10 | 4 | 1674 |
-| ✅ Hooks | 2 | 6 | 1606 |
+| ✅ Evaluation | 1 | 6 | 2539 |
+| ✅ Events | 1 | 2 | 704 |
+| ✅ Execution | 3 | 3 | 1059 |
+| ✅ Files | 2 | 6 | 1100 |
+| ✅ Flow | 1 | 2 | 435 |
+| ✅ Gateway | 6 | 10 | 3924 |
+| ✅ Guardrails | 4 | 4 | 2008 |
+| ✅ Handoffs | 11 | 5 | 2155 |
+| ✅ Hooks | 2 | 6 | 1916 |
 | ✅ Image | 1 | 11 | 1096 |
-| ✅ Knowledge | 3 | 12 | 3262 |
-| ✅ LLM | 2 | 2 | 1049 |
-| ✅ Loops | 4 | 1 | 250 |
-| ✅ MCP | 2 | 47 | 9754 |
-| ✅ Memory | 6 | 12 | 4474 |
-| ✅ Output | 3 | 4 | 868 |
-| ✅ Parallel Execution | 2 | 2 | 347 |
-| ✅ Planning | 6 | 5 | 1506 |
-| ✅ Plugins | 8 | 3 | 1494 |
-| ✅ Prompts | 2 | 4 | 796 |
-| ✅ Providers | 2 | 50 | 5396 |
+| ✅ Knowledge | 3 | 12 | 3466 |
+| ✅ LLM | 3 | 5 | 2251 |
+| ✅ Loops | 4 | 3 | 774 |
+| ✅ MCP | 2 | 51 | 10960 |
+| ✅ Memory | 6 | 16 | 5855 |
+| ✅ Observability | 2 | 23 | 2590 |
+| ✅ Output | 3 | 4 | 903 |
+| ✅ Parallel Execution | 3 | 2 | 399 |
+| ✅ Planning | 6 | 5 | 1519 |
+| ✅ Plugins | 8 | 3 | 1502 |
+| ✅ Prompts | 2 | 7 | 1570 |
+| ✅ Providers | 2 | 51 | 5911 |
 | ✅ Query | 1 | 2 | 616 |
-| ✅ RAG | 5 | 14 | 2910 |
+| ✅ RAG | 5 | 15 | 3190 |
 | ✅ Realtime | 2 | 5 | 584 |
 | ✅ Reflection | 3 | 2 | 469 |
-| ✅ Retrieval | 2 | 5 | 941 |
+| ✅ Retrieval | 2 | 5 | 944 |
 | ✅ Routing | 1 | 2 | 597 |
-| ✅ Sandbox | 5 | 3 | 1002 |
-| ✅ Security | 1 | 1 | 875 |
-| ✅ Sessions | 2 | 8 | 2128 |
-| ✅ Skills | 5 | 5 | 2002 |
-| ✅ Tasks | 2 | 5 | 2590 |
-| ✅ Telemetry | 1 | 2 | 541 |
+| ✅ Sandbox | 5 | 6 | 2294 |
+| ✅ Security | 1 | 3 | 2518 |
+| ✅ Sessions | 4 | 9 | 3826 |
+| ✅ Skills | 5 | 9 | 3415 |
+| ✅ Tasks | 2 | 6 | 3064 |
+| ✅ Telemetry | 1 | 2 | 560 |
 | ✅ Templates | 1 | 7 | 1411 |
-| ✅ Tools | 4 | 97 | 17827 |
+| ✅ Tools | 12 | 113 | 23809 |
 | ✅ Tracing | 3 | 2 | 139 |
-| ✅ Video | 2 | 5 | 460 |
+| ✅ Video | 2 | 6 | 510 |
 | ✅ Vision | 2 | 1 | 283 |
-| ✅ Web | 4 | 6 | 1267 |
-| ✅ Workflows | 4 | 9 | 3579 |
+| ✅ Web | 4 | 6 | 1297 |
+| ✅ Workflows | 4 | 11 | 4302 |
 
 ## Stub Documentation (Need Content)
 
@@ -94,21 +98,18 @@ These categories have documentation files but < 50 lines (stubs):
 
 These docs exist but don't match any implemented feature category:
 
-- ℹ️ AI SDK (1 docs, 112 lines)
-- ℹ️ Agent-to-User (A2U) (3 docs, 770 lines)
-- ℹ️ CLI (91 docs, 21386 lines)
-- ℹ️ Callbacks (1 docs, 985 lines)
-- ℹ️ Chat (3 docs, 546 lines)
+- ℹ️ AI SDK (2 docs, 527 lines)
+- ℹ️ Callbacks (1 docs, 1122 lines)
+- ℹ️ Chat (3 docs, 634 lines)
 - ℹ️ Deep Research (2 docs, 437 lines)
-- ℹ️ Deployment (29 docs, 5931 lines)
-- ℹ️ Jobs (1 docs, 358 lines)
+- ℹ️ Deployment (29 docs, 6013 lines)
+- ℹ️ Jobs (2 docs, 961 lines)
 - ℹ️ Middleware (1 docs, 60 lines)
-- ℹ️ Observability (21 docs, 1580 lines)
-- ℹ️ Process (1 docs, 506 lines)
-- ℹ️ Scheduler (2 docs, 858 lines)
-- ℹ️ Storage (4 docs, 722 lines)
-- ℹ️ Streaming (3 docs, 485 lines)
-- ℹ️ Token Management (3 docs, 1020 lines)
+- ℹ️ Process (1 docs, 545 lines)
+- ℹ️ Scheduler (2 docs, 1084 lines)
+- ℹ️ Storage (5 docs, 957 lines)
+- ℹ️ Streaming (4 docs, 1163 lines)
+- ℹ️ Token Management (4 docs, 1383 lines)
 - ℹ️ Vector Store (11 docs, 733 lines)
 
 ---

src/praisonai-agents/benchmarks/BENCHMARK_RESULTS.md

@@ -1,35 +1,70 @@
 # PraisonAI Agents - Benchmark Results
 
-**Generated:** 2025-12-18 14:40:22
-**Iterations:** 100
-**Test:** Agent instantiation (without tools)
+**Generated:** 2026-06-17
+**Methodology:** 10 warmup runs + 1000 measured iterations (`performance_benchmark.py` config)
+**Config:** `Agent(name=..., instructions=..., model="gpt-4o-mini", tools=[get_weather], output="silent")`
 
-## Results
+## Agent Instantiation Time
 
-| Framework | Avg Time (μs) | Relative |
-|-----------|---------------|----------|
-| **PraisonAI** | **3.77** | **1.00x (fastest)** |
-| OpenAI Agents SDK | 5.26 | 1.39x |
-| Agno | 5.64 | 1.49x |
-| PraisonAI (LiteLLM) | 7.56 | 2.00x |
-| PydanticAI | 226.94 | 60.16x |
-| LangGraph | 4,558.71 | 1,209x |
-| CrewAI | 15,607.92 | 4,138x |
+| Framework | Avg Time (μs) | Min (μs) | Median (μs) | Relative |
+|-----------|---------------|----------|-------------|----------|
+| OpenAI Agents SDK | 5.05 | — | — | 1.00x (fastest) |
+| Agno | 5.27 | — | — | 1.04x |
+| **PraisonAI** | **13.62** | **12.58** | **12.96** | **2.69x** |
+| PraisonAI (LiteLLM) | 14.49 | 13.37 | 13.71 | 2.86x |
+
+### PraisonAI detail (1000 iter)
+
+| Variant | Avg (μs) | Min (μs) | Median (μs) | Std (μs) |
+|---------|----------|----------|-------------|----------|
+| With tools (`gpt-4o-mini`) | 13.62 | 12.58 | 12.96 | 2.73 |
+| With tools (`openai/gpt-4o-mini`) | 14.49 | 13.37 | 13.71 | 4.14 |
+| Minimal, no tools | 13.40 | — | — | — |
+
+## Historical baseline
+
+| Source | Config | Avg (μs) | Notes |
+|--------|--------|----------|-------|
+| `performance_benchmark.py` (Dec 2025) | tools + 1000 iter | **3.20** | Pre-init-bloat baseline |
+| `simple_benchmark.py` (Dec 2025) | no tools, 100 iter | **3.77** | Saved in prior `BENCHMARK_RESULTS.md` |
+| Current (Jun 2026) | tools + 1000 iter | **13.62** | After lazy-init optimisations (was ~31 μs pre-fix) |
 
 ## Package Versions
 
 | Package | Version |
-|---------|--------|
-| PraisonAI | 0.1.5 |
-| Agno | 2.3.14 |
-| PydanticAI | 1.35.0 |
-| OpenAI Agents SDK | 0.6.3 |
-| LangGraph | 1.0.5 |
-| CrewAI | 1.6.1 |
+|---------|---------|
+| PraisonAI | 1.6.60 |
+| Agno | 2.4.2 |
+| OpenAI Agents SDK | 0.7.0 |
 
 ## How to Reproduce
 
+PraisonAI-only (fast; avoids CrewAI/LangGraph import hang):
+
 ```bash
 cd praisonai-agents
-python benchmarks/simple_benchmark.py
+PYTHONWARNINGS='ignore::DeprecationWarning' python -c "
+import time, statistics
+from typing import Literal
+from praisonaiagents import Agent
+
+def get_weather(city: Literal['nyc', 'sf']):
+    return 'cloudy' if city == 'nyc' else 'sunny'
+
+def bench(fn, n=1000, w=10):
+    for _ in range(w): fn()
+    times = []
+    for _ in range(n):
+        s = time.perf_counter(); fn(); times.append(time.perf_counter()-s)
+    print(f'avg={statistics.mean(times)*1e6:.2f} μs')
+
+bench(lambda: Agent(name='Test', instructions='Hi', model='gpt-4o-mini', tools=[get_weather], output='silent'))
+"
+```
+
+Full multi-framework benchmark:
+
+```bash
+cd praisonai-agents
+PYTHONWARNINGS='ignore::DeprecationWarning' python benchmarks/performance_benchmark.py --save
 ```

src/praisonai-agents/benchmarks/INSTANTIATION_RCA.md

@@ -0,0 +1,62 @@
+# Agent Instantiation — Root Cause Analysis
+
+**Date:** 2026-06-17  
+**Version:** praisonaiagents 1.6.58 (dev)  
+**Methodology:** 10 warmup + 1000 measured iterations, `time.perf_counter()`
+
+## Summary
+
+Instantiation regressed from **~3.2 μs** (Dec 2025) to **~31 μs** (~10×). After fixes, steady-state is **~16 μs** (~2× historical). PraisonAI is competitive with Agno (~5 μs) on warmed benchmarks using `model=`.
+
+## Before vs After Fixes
+
+| Config | Historical | Pre-fix | Post-fix |
+|--------|------------|---------|----------|
+| Minimal (`name`, `output="silent"`) | 3.20 μs | 31.36 μs | **16.35 μs** |
+| `model="gpt-4o-mini"` | 3.77 μs | 32.19 μs | **16.86 μs** |
+| `llm="gpt-4o-mini"` (deprecated) | 3.77 μs | 46.48 μs | **~18 μs** (warn once) |
+| LiteLLM `openai/gpt-4o-mini` cold | 7.31 μs | **3.7 s** | **53.63 μs** |
+| LiteLLM warmed instantiate | — | 60 μs | **19.83 μs** |
+| Import `Agent` | — | 20.8 ms | **29.6 ms** |
+
+## Root Causes (validated)
+
+| ID | Cause | Status | Fix applied |
+|----|-------|--------|-------------|
+| H1 | Config loader cold start (+9 ms first init) | CONFIRMED | Fast path when no config defaults (`_defaults_has_any_values`) |
+| H2 | LoopGuard on every init (~2 μs) | CONFIRMED | Lazy `_ensure_loop_guard()` on first tool call |
+| H3 | Approval presets | REJECTED | No change needed |
+| H4 | `llm=` deprecation every init (+16 μs) | CONFIRMED | Warn once per process in `warn_deprecated_param` |
+| H5 | Init bloat / config resolution (~25 μs) | CONFIRMED | Partially addressed via loader fast path |
+| H6 | LiteLLM eager `LLM()` import (+3.7 s) | CONFIRMED | Deferred `_llm_init_params` + lazy `llm_instance` property |
+| H7 | `ExecutionConfig` deprecation every init | CONFIRMED | Fixed stack walk; internal SDK path cached |
+
+## cProfile — Post-fix (500 warmed `model=` inits)
+
+| Function | Time (ms) | Per call |
+|----------|-----------|----------|
+| `Agent.__init__` | 8 | ~16 μs |
+| `apply_config_defaults` | 1 | ~2 μs |
+| `ExecutionConfig.__post_init__` | 1 | ~2 μs (first call only walks stack) |
+| `_warnings.warn` | **0** | removed from hot path |
+
+## Fixes implemented
+
+1. **`praisonaiagents/config/feature_configs.py`** — Fix `ExecutionConfig.__post_init__` deprecation guard; cache internal SDK detection.
+2. **`praisonaiagents/utils/deprecation.py`** — Warn once per process for deprecated params.
+3. **`praisonaiagents/config/loader.py`** — Skip `apply_config_defaults` lookups when config has no defaults.
+4. **`praisonaiagents/agent/agent.py`** — Lazy LoopGuard, lazy LLM instance, deferred LiteLLM params.
+5. **`benchmarks/simple_benchmark.py`** — Use `model=`, add 10-iteration warmup.
+6. **`benchmarks/performance_benchmark.py`** — Use `model=` instead of deprecated `llm=`.
+
+## Remaining gap (~16 μs vs ~3 μs)
+
+The residual ~13 μs is primarily **`Agent.__init__` size** (~1200 lines of consolidated config resolution added since v0.1.5). Further optimisation requires a dedicated slim fast-path for `Agent(name=..., output="silent")` without full config object churn.
+
+## How to reproduce
+
+```bash
+cd praisonai-agents
+PYTHONWARNINGS='ignore::DeprecationWarning' python benchmarks/simple_benchmark.py
+PYTHONWARNINGS='ignore::DeprecationWarning' python benchmarks/performance_benchmark.py
+```

src/praisonai-agents/benchmarks/param_impact_benchmark.py

@@ -120,8 +120,8 @@ def run_benchmark(iterations: int = 100) -> List[ParamResult]:
         ('backstory', 'I am an AI assistant.', 'backstory="..."'),
         
         # LLM configuration
-        ('llm', 'gpt-4o-mini', 'llm="gpt-4o-mini"'),
-        ('llm', 'openai/gpt-4o-mini', 'llm="openai/gpt-4o-mini" (LiteLLM)'),
+        ('model', 'gpt-4o-mini', 'model="gpt-4o-mini"'),
+        ('model', 'openai/gpt-4o-mini', 'model="openai/gpt-4o-mini" (LiteLLM)'),
         
         # Tools
         ('tools', [sample_tool], 'tools=[sample_tool]'),
@@ -298,7 +298,7 @@ def save_results(results: List[ParamResult], filename: str = 'PARAM_IMPACT_RESUL
         f.write('### Best Practices\n\n')
         f.write('1. Use `output="silent"` for production workloads\n')
         f.write('2. Only enable `context=True` when needed for long conversations\n')
-        f.write('3. Use `llm="gpt-4o-mini"` (OpenAI SDK) for fastest instantiation\n')
+        f.write('3. Use `model="gpt-4o-mini"` for fastest instantiation\n')
         f.write('4. Avoid `memory=True` unless persistent memory is required\n')
         
         f.write('\n## How to Reproduce\n\n')

src/praisonai-agents/benchmarks/performance_benchmark.py

@@ -185,7 +185,7 @@ def instantiate_praisonai_agent():
     return PraisonAgent(
         name="Test Agent",
         instructions="Be concise, reply with one sentence.",
-        llm="gpt-4o-mini",
+        model="gpt-4o-mini",
         tools=tools,
         output="silent"
     )
@@ -196,7 +196,7 @@ def instantiate_praisonai_litellm_agent():
     return PraisonAgent(
         name="Test Agent",
         instructions="Be concise, reply with one sentence.",
-        llm="openai/gpt-4o-mini",
+        model="openai/gpt-4o-mini",
         tools=tools,
         output="silent"
     )

src/praisonai-agents/benchmarks/simple_benchmark.py

@@ -14,6 +14,7 @@ import argparse
 
 
 ITERATIONS = 100
+WARMUP = 10
 
 
 def sample_tool(city: Literal['nyc', 'sf']):
@@ -23,8 +24,10 @@ def sample_tool(city: Literal['nyc', 'sf']):
     return 'sunny'
 
 
-def measure_instantiation(create_fn, iterations=ITERATIONS):
+def measure_instantiation(create_fn, iterations=ITERATIONS, warmup=WARMUP):
     """Measure average instantiation time in microseconds."""
+    for _ in range(warmup):
+        create_fn()
     times = []
     for _ in range(iterations):
         start = time.perf_counter()
@@ -48,11 +51,11 @@ def run_benchmark():
     from praisonaiagents import Agent as PraisonAgent
     
     results['PraisonAI'] = measure_instantiation(
-        lambda: PraisonAgent(name='Test', llm='gpt-4o-mini', output="silent")
+        lambda: PraisonAgent(name='Test', model='gpt-4o-mini', output="silent")
     )
     
     results['PraisonAI (LiteLLM)'] = measure_instantiation(
-        lambda: PraisonAgent(name='Test', llm='openai/gpt-4o-mini', output="silent")
+        lambda: PraisonAgent(name='Test', model='openai/gpt-4o-mini', output="silent")
     )
     
     # Other frameworks for comparison

src/praisonai-agents/examples/context_compaction_example.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+Context Compaction Example - Python API
+
+Demonstrates how to configure context compaction policies in PraisonAI agents.
+This provides examples for CLI/YAML parity.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.config.feature_configs import ExecutionConfig
+from praisonaiagents.context.adapters import ContextCompactionPolicyAdapter
+from praisonaiagents.context.protocols import CompactionStrategy
+
+
+def example_default_behavior():
+    """Example 1: Default behavior (during deprecation period)."""
+    print("=== Example 1: Default Behavior ===")
+    
+    # Currently defaults to False with deprecation warning
+    agent = Agent(
+        name="default_agent",
+        instructions="You are a helpful assistant."
+    )
+    
+    print(f"Context compaction enabled: {agent.execution.context_compaction}")
+    print("Note: Currently False during deprecation period, will change to True in next release\n")
+
+
+def example_explicit_disable():
+    """Example 2: Explicitly disable context compaction."""
+    print("=== Example 2: Explicitly Disabled ===")
+    
+    agent = Agent(
+        name="no_compaction_agent",
+        instructions="You are a helpful assistant.",
+        execution=ExecutionConfig(context_compaction=False)
+    )
+    
+    print(f"Context compaction enabled: {agent.execution.context_compaction}")
+    print("No automatic compaction will occur\n")
+
+
+def example_default_policy():
+    """Example 3: Use default compaction policy."""
+    print("=== Example 3: Default Policy ===")
+    
+    agent = Agent(
+        name="default_policy_agent", 
+        instructions="You are a helpful assistant.",
+        execution=ExecutionConfig(context_compaction=True)
+    )
+    
+    print(f"Context compaction enabled: {agent.execution.context_compaction}")
+    print("Will use balanced default policy (trigger at 90%, preserve 5 recent turns)\n")
+
+
+def example_conservative_policy():
+    """Example 4: Conservative compaction policy."""
+    print("=== Example 4: Conservative Policy ===")
+    
+    conservative_policy = ContextCompactionPolicyAdapter(
+        trigger_at=0.80,  # Trigger at 80% capacity
+        strategy=CompactionStrategy.DROP_OLDEST_TOOLS,
+        preserve_last_n_turns=8,  # Keep more conversation history
+        target_utilization=0.60,  # Target 60% utilization after compaction
+        aggressive_tool_truncation=False
+    )
+    
+    agent = Agent(
+        name="conservative_agent",
+        instructions="You are a helpful assistant.",
+        execution=ExecutionConfig(context_compaction=conservative_policy)
+    )
+    
+    print(f"Policy trigger: {conservative_policy.trigger_at}")
+    print(f"Strategy: {conservative_policy.strategy}")
+    print(f"Preserve turns: {conservative_policy.preserve_last_n_turns}")
+    print(f"Target utilization: {conservative_policy.target_utilization}\n")
+
+
+def example_aggressive_policy():
+    """Example 5: Aggressive compaction policy."""
+    print("=== Example 5: Aggressive Policy ===")
+    
+    aggressive_policy = ContextCompactionPolicyAdapter(
+        trigger_at=0.95,  # Wait until 95% capacity
+        strategy=CompactionStrategy.SUMMARISE,  # Use LLM summarization  
+        preserve_last_n_turns=3,  # Keep only recent exchanges
+        target_utilization=0.75,  # Target higher utilization 
+        aggressive_tool_truncation=True,  # Truncate large tool outputs
+        model_overrides={
+            "gpt-4": {"trigger_at": 0.92},  # Different threshold for gpt-4
+            "claude-3": {"trigger_at": 0.88}
+        }
+    )
+    
+    agent = Agent(
+        name="aggressive_agent",
+        instructions="You are a helpful assistant.",
+        execution=ExecutionConfig(context_compaction=aggressive_policy)
+    )
+    
+    print(f"Policy trigger: {aggressive_policy.trigger_at}")
+    print(f"Strategy: {aggressive_policy.strategy}")  
+    print(f"Preserve turns: {aggressive_policy.preserve_last_n_turns}")
+    print(f"Model overrides: {aggressive_policy.model_overrides}\n")
+
+
+def example_yaml_config():
+    """Example 6: YAML configuration equivalent."""
+    print("=== Example 6: YAML Configuration Equivalent ===")
+    print("""
+# agent_config.yaml
+name: "helpful_agent"
+instructions: "You are a helpful assistant."
+llm: "gpt-4o-mini"
+execution:
+  context_compaction:
+    trigger_at: 0.85
+    strategy: "drop_oldest_tools"
+    preserve_last_n_turns: 6
+    target_utilization: 0.65
+    aggressive_tool_truncation: true
+    model_overrides:
+      "gpt-4":
+        trigger_at: 0.90
+        strategy: "summarise"
+""")
+    
+    # Python equivalent:
+    policy = ContextCompactionPolicyAdapter(
+        trigger_at=0.85,
+        strategy="drop_oldest_tools",
+        preserve_last_n_turns=6,
+        target_utilization=0.65,
+        aggressive_tool_truncation=True,
+        model_overrides={
+            "gpt-4": {
+                "trigger_at": 0.90,
+                "strategy": "summarise"
+            }
+        }
+    )
+    
+    agent = Agent(
+        name="helpful_agent",
+        instructions="You are a helpful assistant.",
+        llm="gpt-4o-mini",
+        execution=ExecutionConfig(context_compaction=policy)
+    )
+    
+    print(f"Loaded policy trigger: {policy.trigger_at}")
+    print(f"Loaded strategy: {policy.strategy}\n")
+
+
+def example_cli_equivalent():
+    """Example 7: CLI equivalent commands."""
+    print("=== Example 7: CLI Equivalent ===")
+    print("""
+# Basic usage (will use default policy when enabled)
+praisonai agent run --name "assistant" --instructions "Be helpful"
+
+# Disable compaction explicitly  
+praisonai agent run --name "assistant" --execution '{"context_compaction": false}'
+
+# Use conservative policy
+praisonai agent run --name "assistant" \\
+    --execution '{
+        "context_compaction": {
+            "trigger_at": 0.80,
+            "strategy": "drop_oldest_tools",
+            "preserve_last_n_turns": 8
+        }
+    }'
+
+# Load from YAML config file
+praisonai agent run --config agent_config.yaml
+""")
+
+
+def example_serialization_round_trip():
+    """Example 8: Serialization round-trip."""
+    print("=== Example 8: Serialization Round-Trip ===")
+    
+    # Create agent with custom policy
+    original_policy = ContextCompactionPolicyAdapter(
+        trigger_at=0.88,
+        strategy=CompactionStrategy.SUMMARISE
+    )
+    
+    config = ExecutionConfig(context_compaction=original_policy)
+    
+    # Serialize to dict (for JSON/YAML storage)
+    config_dict = config.to_dict()
+    print(f"Serialized context_compaction type: {type(config_dict['context_compaction'])}")
+    
+    # Deserialize back to object
+    restored_config = ExecutionConfig.from_dict(config_dict)
+    restored_policy = restored_config.context_compaction
+    
+    print(f"Restored policy type: {type(restored_policy)}")
+    print(f"Attributes preserved: trigger_at={restored_policy.trigger_at}, strategy={restored_policy.strategy}")
+    print("✓ Round-trip serialization successful\n")
+
+
+if __name__ == "__main__":
+    print("Context Compaction Configuration Examples\n")
+    print("=" * 50)
+    
+    try:
+        example_default_behavior()
+        example_explicit_disable()
+        example_default_policy()
+        example_conservative_policy()
+        example_aggressive_policy()
+        example_yaml_config()
+        example_cli_equivalent()
+        example_serialization_round_trip()
+        
+        print("=" * 50)
+        print("✅ All examples completed successfully!")
+        print("\nFor more information, see:")
+        print("- Documentation: https://docs.praisonai.com/context-compaction")
+        print("- Examples: examples/context_compaction_example.py")
+        
+    except Exception as e:
+        print(f"❌ Example failed: {e}")
+        import traceback
+        traceback.print_exc()

src/praisonai-agents/praisonaiagents/__init__.py

@@ -114,6 +114,9 @@ def _get_lazy_cache():
 # ============================================================================
 
 _LAZY_IMPORTS = {
+    # Version information (lazy loaded to avoid file I/O on import)
+    '__version__': ('praisonaiagents._version', '__version__'),
+    
     # Tools (moved from eager imports for lazy loading)
     'Tools': ('praisonaiagents.tools.tools', 'Tools'),
     'BaseTool': ('praisonaiagents.tools.base', 'BaseTool'),
@@ -127,6 +130,23 @@ _LAZY_IMPORTS = {
     'get_tool': ('praisonaiagents.tools.registry', 'get_tool'),
     'ToolRegistry': ('praisonaiagents.tools.registry', 'ToolRegistry'),
     
+    # Toolsets (named toolset groups)
+    'ToolsetSpec': ('praisonaiagents.toolsets', 'ToolsetSpec'),
+    'ToolsetRegistry': ('praisonaiagents.toolsets', 'ToolsetRegistry'),
+    'get_toolset_registry': ('praisonaiagents.toolsets', 'get_toolset_registry'),
+    'register_toolset': ('praisonaiagents.toolsets', 'register_toolset'),
+    'resolve_toolset': ('praisonaiagents.toolsets', 'resolve_toolset'),
+    'resolve_toolsets': ('praisonaiagents.toolsets', 'resolve_toolsets'),
+    'list_toolsets': ('praisonaiagents.toolsets', 'list_toolsets'),
+    'get_toolset': ('praisonaiagents.toolsets', 'get_toolset'),
+    'unregister_toolset': ('praisonaiagents.toolsets', 'unregister_toolset'),
+    'has_toolset': ('praisonaiagents.toolsets', 'has_toolset'),
+    
+    # Run outcomes - typed validation and agent execution results
+    'AgentRunOutcome': ('praisonaiagents.run_outcome', 'AgentRunOutcome'),
+    'RunStatus': ('praisonaiagents.run_outcome', 'RunStatus'),
+    'validate_decision_string': ('praisonaiagents.run_outcome', 'validate_decision_string'),
+    
     # Main display utilities (imports rich)
     'TaskOutput': ('praisonaiagents.main', 'TaskOutput'),
     'ReflectionOutput': ('praisonaiagents.main', 'ReflectionOutput'),
@@ -174,6 +194,7 @@ _LAZY_IMPORTS = {
     'RECOMMENDED_PROMPT_PREFIX': ('praisonaiagents.agent.handoff', 'RECOMMENDED_PROMPT_PREFIX'),
     'prompt_with_handoff_instructions': ('praisonaiagents.agent.handoff', 'prompt_with_handoff_instructions'),
     'HandoffConfig': ('praisonaiagents.agent.handoff', 'HandoffConfig'),
+    'HandoffToolPolicy': ('praisonaiagents.agent.handoff', 'HandoffToolPolicy'),
     'HandoffResult': ('praisonaiagents.agent.handoff', 'HandoffResult'),
     'HandoffInputData': ('praisonaiagents.agent.handoff', 'HandoffInputData'),
     'ContextPolicy': ('praisonaiagents.agent.handoff', 'ContextPolicy'),
@@ -386,6 +407,17 @@ _LAZY_IMPORTS = {
     'MultiAgentMemoryConfig': ('praisonaiagents.config.feature_configs', 'MultiAgentMemoryConfig'),
     'ToolSearchConfig': ('praisonaiagents.config.feature_configs', 'ToolSearchConfig'),
     
+    # Context compaction policies
+    'ContextCompactionPolicy': ('praisonaiagents.context.policy', 'ContextCompactionPolicy'),
+    'ContextCompactionPolicyProtocol': ('praisonaiagents.context.policy', 'ContextCompactionPolicyProtocol'),
+    'CompactionRoute': ('praisonaiagents.context.policy', 'CompactionRoute'),
+    'CompactionStrategy': ('praisonaiagents.context.policy', 'CompactionStrategy'),
+    'ContextBudgetResult': ('praisonaiagents.context.policy', 'ContextBudgetResult'),
+    'get_default_policy': ('praisonaiagents.context.policy', 'get_default_policy'),
+    'CONSERVATIVE_POLICY': ('praisonaiagents.context.policy', 'CONSERVATIVE_POLICY'),
+    'BALANCED_POLICY': ('praisonaiagents.context.policy', 'BALANCED_POLICY'),
+    'AGGRESSIVE_POLICY': ('praisonaiagents.context.policy', 'AGGRESSIVE_POLICY'),
+    
     # Parameter resolver
     'resolve': ('praisonaiagents.config.param_resolver', 'resolve'),
     'ArrayMode': ('praisonaiagents.config.param_resolver', 'ArrayMode'),
@@ -626,6 +658,11 @@ def _custom_handler(name, cache):
         mod = importlib.import_module('.db', 'praisonaiagents')
         cache['db'] = mod
         return mod
+    if name == 'toolsets':
+        import importlib
+        mod = importlib.import_module('.toolsets', 'praisonaiagents')
+        cache['toolsets'] = mod
+        return mod
     
     raise AttributeError(f"Not handled by custom_handler: {name}")
 
@@ -741,6 +778,9 @@ def warmup(include_litellm: bool = False, include_openai: bool = True) -> dict:
 # ============================================================================
 
 __all__ = [
+    # Version information
+    '__version__',
+    
     # Core classes - the essentials
     'Agent',
     'AgentTeam',  # Primary class for multi-agent coordination (v1.0+)

src/praisonai-agents/praisonaiagents/_config.py

@@ -111,32 +111,3 @@ def _get_plugins_list() -> list:
 
 PLUGINS_ENABLED = _get_plugins_enabled()
 PLUGINS_LIST = _get_plugins_list()
-
-
-def missing_dependency_error(
-    package_name: str,
-    extra_name: Optional[str] = None,
-    feature_name: Optional[str] = None
-) -> ImportError:
-    """
-    Create a standardized ImportError for missing optional dependencies.
-    
-    Args:
-        package_name: The name of the missing package (e.g., 'litellm')
-        extra_name: The pip extra to install (e.g., 'llm' for [llm])
-        feature_name: Human-readable feature name (e.g., 'LLM support')
-    
-    Returns:
-        ImportError with helpful install instructions
-    """
-    if extra_name:
-        install_cmd = f"pip install 'praisonaiagents[{extra_name}]'"
-    else:
-        install_cmd = f"pip install {package_name}"
-    
-    feature_desc = f" for {feature_name}" if feature_name else ""
-    
-    return ImportError(
-        f"{package_name} is required{feature_desc} but not installed. "
-        f"Please install with: {install_cmd}"
-    )

src/praisonai-agents/praisonaiagents/_resolver_helpers.py

@@ -1,49 +0,0 @@
-"""
-Resolver helper functions for consolidated parameters.
-
-These helpers wrap the canonical resolver for specific parameter types,
-handling special cases like callable validators for guardrails.
-"""
-
-from typing import Any, Type
-
-from .config.param_resolver import resolve, ArrayMode
-from .config.presets import GUARDRAIL_PRESETS
-
-
-def resolve_guardrails(value: Any, config_class: Type) -> Any:
-    """
-    Resolve guardrails parameter.
-    
-    Handles special case of callable validators which have highest precedence.
-    
-    Args:
-        value: The guardrails parameter value
-        config_class: GuardrailConfig class
-        
-    Returns:
-        Resolved config, callable, or string
-    """
-    # Handle None
-    if value is None:
-        return None
-    
-    # Handle False (disabled)
-    if value is False:
-        return None
-    
-    # Handle callable (highest precedence after None check)
-    # This includes functions, lambdas, and callable objects
-    if callable(value) and not isinstance(value, type):
-        return value
-    
-    # Use canonical resolver for everything else
-    return resolve(
-        value=value,
-        param_name="guardrails",
-        config_class=config_class,
-        presets=GUARDRAIL_PRESETS,
-        array_mode=ArrayMode.PRESET_OVERRIDE,
-        string_mode="llm_prompt",
-        default=None,
-    )