fix(examples): phase-3 API alignment for consolidated params on v4.6.52 (#1864)

Co-authored-by: Dhivya-Bharathy <[email protected]>

.env.example

@@ -0,0 +1,51 @@
+# PraisonAI Environment Variables
+# Copy this file to .env and update with your actual values
+
+# === Required ===
+OPENAI_API_KEY=sk-...          # OpenAI key for LLM calls. Get yours at https://platform.openai.com
+
+# === Required for Claw web-search tool ===
+TAVILY_API_KEY=tvly-...        # Get yours at https://app.tavily.com (free tier available)
+
+# === Optional: Claw dashboard security ===
+PRAISONAI_ALLOW_LOCAL_TOOLS=0  # Set to 1 to enable local shell tools (security risk)
+
+# === Optional: Alternative LLM Providers ===
+ANTHROPIC_API_KEY=sk-ant-...   # Anthropic Claude models
+GOOGLE_API_KEY=...             # Google Gemini models  
+GROQ_API_KEY=gsk_...           # Groq (fast inference)
+COHERE_API_KEY=...             # Cohere models
+AZURE_OPENAI_API_KEY=...       # Azure OpenAI
+AZURE_OPENAI_ENDPOINT=...      # Azure OpenAI endpoint
+
+# === Optional: Memory backends ===
+MEM0_API_KEY=...               # Mem0 memory service
+REDIS_URL=redis://localhost:6379  # Redis for state management
+
+# === Optional: Observability ===
+LANGFUSE_SECRET_KEY=sk-lf-...  # Langfuse tracing
+LANGFUSE_PUBLIC_KEY=pk-lf-...  # Langfuse public key
+
+# === Optional: Bot platforms ===
+TELEGRAM_BOT_TOKEN=...         # Telegram bot token
+DISCORD_BOT_TOKEN=...          # Discord bot token  
+SLACK_BOT_TOKEN=xoxb-...       # Slack bot token
+SLACK_APP_TOKEN=xapp-...       # Slack app token
+WHATSAPP_ACCESS_TOKEN=...      # WhatsApp bot access token
+WHATSAPP_PHONE_NUMBER_ID=...   # WhatsApp phone number ID
+
+# === Optional: Database ===
+DATABASE_URL=sqlite:///~/.praison/database.sqlite  # Database connection string
+
+# === Optional: Tool Security ===
+# ALLOWED_TOOLS=search,send_message       # Whitelist specific tools to prevent name collisions
+                                        # Useful in multi-environment setups with overlapping tool names
+                                        # Leave unset to use all tools (with collision warnings)
+                                        # Do NOT set to empty string: that's treated as configuration error
+                                        # In CI, unknown tool names in the whitelist cause strict startup failure
+# HERMES_ONLY_TOOLS=search,send_message  # (Deprecated) Backward compatibility alias for ALLOWED_TOOLS
+
+# === Optional: Development ===
+LOGLEVEL=INFO                  # Logging level (DEBUG, INFO, WARNING, ERROR)
+CHAINLIT_AUTH_SECRET=...       # Chainlit authentication secret
+DEBUG=false                    # Enable debug mode

.github/workflows/auto-pr-comment.yml

@@ -183,7 +183,7 @@ jobs:
             if (reviews.copilot.length) summaryParts.push('Copilot: ' + reviews.copilot.length + ' comments');
             if (reviews.greptile.length) summaryParts.push('Greptile: ' + reviews.greptile.length + ' comments');
             const reviewSummary = summaryParts.length ? summaryParts.join(' | ') : 'No bot reviews detected';
-            const claudeBody = '@claude You are the FINAL architecture reviewer. ' + reviewSummary + '.\n\n' +
+            const claudeBody = '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. ' + reviewSummary + '.\n\n' +
               'Review Context: ' + comments.data.length + ' total comments, ' + 
               (reviews.coderabbit.length + reviews.qodo.length + reviews.gemini.length + reviews.copilot.length + reviews.greptile.length) + ' bot reviews.\n\n' +
               'Phase 1: Review per AGENTS.md principles (protocol-driven, backward compatible, no perf impact).\n' +
@@ -313,7 +313,7 @@ jobs:
               issue_number: pr,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
+              body: '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
             });
             console.log(`Claude triggered on PR #${pr}`);
 
@@ -417,7 +417,7 @@ jobs:
               issue_number: pr,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: '@claude You are the FINAL architecture reviewer. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
+              body: '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
             });
             console.log(`Claude triggered on PR #${pr}`);
 
@@ -468,7 +468,7 @@ jobs:
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: '@claude You are the Lead Engineer. Read ALL analysis and reviews above carefully (Gemini, CodeRabbit, Qodo, Copilot, etc).\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
+              body: '@claude You are the Lead Engineer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL analysis and reviews above carefully (Gemini, CodeRabbit, Qodo, Copilot, etc).\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n\n**Phase 2: FIX Valid Issues**\n4. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n5. Push all code fixes directly to THIS branch (do NOT create a new PR)\n6. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n7. If all issues are resolved, approve the PR / close the Issue\n8. If blocking issues remain, request changes / leave clear action items'
             });
 
   # ================================================================

.github/workflows/claude.yml

@@ -181,12 +181,15 @@ jobs:
 
       - name: Fetch PR branch and Setup Remote
         if: github.event.issue.pull_request
+        env:
+          PR_BRANCH: ${{ steps.check_fork.outputs.pr_branch }}
+          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:${{ steps.check_fork.outputs.pr_branch }}
+          git fetch origin pull/${{ github.event.issue.number }}/head:"${PR_BRANCH}"
           
           # If it's a fork, make origin point to local to trick claude-code-action's `git fetch origin <branch>`
-          if [ "${{ steps.check_fork.outputs.is_fork }}" == "true" ]; then
+          if [ "${IS_FORK}" = "true" ]; then
             git remote set-url origin file://$(pwd)
           fi
 
@@ -201,7 +204,7 @@ jobs:
           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' || '' }}
+            ${{ 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' }}
             You are working on the PraisonAI SDK. Follow AGENTS.md strictly.
 
             STEP 0 — SETUP GIT IDENTITY & AUTH (GLOBAL — required for all repos):
@@ -212,6 +215,7 @@ jobs:
 
             STEP 1 — READ GUIDELINES:
             Read AGENTS.md to understand the architecture rules.
+            SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify or touch praisonai-rust or praisonai-ts packages.
 
             STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
             Before implementing anything, answer these questions:
@@ -230,9 +234,14 @@ jobs:
             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 and implement a minimal, focused fix
+            - 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.
 
             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.

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

@@ -0,0 +1,158 @@
+name: Cross-Repo Integration Tests
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/praisonai/praisonai/integration/**'
+      - 'src/praisonai/tests/integration/test_aiui_*'
+      - 'src/praisonai/pyproject.toml'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/praisonai/praisonai/integration/**'
+      - 'src/praisonai/tests/integration/test_aiui_*'
+      - 'src/praisonai/pyproject.toml'
+  workflow_dispatch:
+
+jobs:
+  cross-repo-integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    
+    steps:
+    - name: Checkout PraisonAI
+      uses: actions/checkout@v4
+      with:
+        path: PraisonAI
+        ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+        
+    - name: Checkout PraisonAIUI
+      uses: actions/checkout@v4
+      with:
+        repository: MervinPraison/PraisonAIUI
+        path: PraisonAIUI
+        ref: main
+        
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        # Install PraisonAI packages in development mode
+        cd PraisonAI/src/praisonai-agents
+        pip install -e .
+        cd ../praisonai
+        pip install -e ".[ui,dev]"
+        # Install PraisonAIUI in development mode
+        cd ../../../PraisonAIUI
+        pip install -e .
+        
+    - name: Verify versions
+      run: |
+        python -c "import praisonaiagents; print(f'praisonaiagents: {praisonaiagents.__version__}')"
+        python -c "import praisonai; print(f'praisonai: {praisonai.__version__}')"
+        python -c "import praisonaiui; print(f'praisonaiui: {praisonaiui.__version__}')"
+        
+    - name: Run PraisonAI integration tests
+      run: |
+        cd PraisonAI/src/praisonai
+        python -m pytest tests/integration/test_aiui_* -v --timeout=300
+        
+    - 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
+        fi
+        if [ -f tests/test_feature_sdk_backends.py ]; then
+          python -m pytest tests/test_feature_sdk_backends.py -v --timeout=300
+        fi
+        
+    - name: Test Pattern C CLI
+      run: |
+        cd PraisonAI/src/praisonai
+        # Test that ui-gateway command exists
+        python -m praisonai serve --help | grep ui-gateway
+        
+    - name: Test public API exports
+      run: |
+        cd PraisonAI/src/praisonai
+        python -c "from praisonai import run_integrated_gateway; print('✓ run_integrated_gateway imported')"
+        python -c "from praisonai import configure_host; print('✓ configure_host imported')"
+        
+    - name: Integration smoke test
+      env:
+        PRAISONAI_TEST_MODE: "1"
+        PYTHONPATH: ${{ github.workspace }}/PraisonAI/src/praisonai:${{ github.workspace }}/PraisonAI/src/praisonai-agents:${{ github.workspace }}/PraisonAIUI
+      run: |
+        cd PraisonAI/src/praisonai
+        python -c "
+        import sys
+        sys.path.insert(0, '.')
+        from praisonai.integration.host_app import configure_host
+        from praisonai import run_integrated_gateway
+        print('✓ Integration imports successful')
+        
+        # Test configure_host with new parameters
+        try:
+            configure_host(
+                style='dashboard', 
+                context_paths=['AGENTS.md'],
+                title='Test App'
+            )
+            print('✓ configure_host with new parameters works')
+        except Exception as e:
+            print(f'× configure_host failed: {e}')
+            sys.exit(1)
+        "
+        
+  # Optional job with API key for agentic tests (if secret is available)
+  agentic-integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: ${{ vars.RUN_AGENTIC_TESTS == 'true' }}
+    needs: cross-repo-integration
+    
+    steps:
+    - name: Checkout PraisonAI
+      uses: actions/checkout@v4
+      with:
+        path: PraisonAI
+        ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+        
+    - name: Checkout PraisonAIUI
+      uses: actions/checkout@v4
+      with:
+        repository: MervinPraison/PraisonAIUI
+        path: PraisonAIUI
+        ref: main
+        
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        cd PraisonAI/src/praisonai-agents
+        pip install -e .
+        cd ../praisonai
+        pip install -e ".[ui,dev]"
+        cd ../../../PraisonAIUI
+        pip install -e .
+        
+    - name: Run agentic integration test
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      run: |
+        cd PraisonAI/src/praisonai
+        if [ -n "$OPENAI_API_KEY" ]; then
+          python -m pytest tests/integration/test_aiui_host_agentic.py -v --timeout=600
+        else
+          echo "OPENAI_API_KEY not available, skipping agentic tests"
+        fi

.github/workflows/praisonai-issue-triage.yml

@@ -29,9 +29,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
-        with:
           fetch-depth: 0
           
       - name: Generate GitHub App Token
@@ -63,10 +60,12 @@ jobs:
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           PRAISONAI_AUTO_APPROVE: "true"
+          ISSUE_NUMBER_INPUT: ${{ inputs.issue_number }}
+          ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
         run: |
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            export ISSUE_NUMBER="${{ inputs.issue_number }}"
+            export ISSUE_NUMBER="$ISSUE_NUMBER_INPUT"
           else
-            export ISSUE_NUMBER="${{ github.event.issue.number }}"
+            export ISSUE_NUMBER="$ISSUE_NUMBER_EVENT"
           fi
           praisonai github triage --issue $ISSUE_NUMBER --agent-file .github/praisonai-issue-triage.yaml

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

@@ -30,22 +30,23 @@ jobs:
     steps:
       - name: Determine checkout ref
         id: dest
+        env:
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          PR_NUMBER_INPUT: ${{ inputs.pr_number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
           if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            echo "ref=refs/pull/${{ github.event.issue.number }}/head" >> "$GITHUB_OUTPUT"
+            echo "ref=refs/pull/$ISSUE_NUMBER/head" >> "$GITHUB_OUTPUT"
           elif [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "ref=refs/pull/${{ inputs.pr_number }}/head" >> "$GITHUB_OUTPUT"
+            echo "ref=refs/pull/$PR_NUMBER_INPUT/head" >> "$GITHUB_OUTPUT"
           else
-            echo "ref=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
+            echo "ref=$PR_HEAD_SHA" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Checkout Repository
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-        with:
-          persist-credentials: false
-        with:
           ref: ${{ steps.dest.outputs.ref }}
           fetch-depth: 0
           

.github/workflows/python-publish.yml

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

.github/workflows/test-windows.yml

@@ -26,8 +26,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:
@@ -176,6 +176,18 @@ jobs:
       run: praisonai queue list
       continue-on-error: true
 
+    # ==================== PACKAGING TESTS ====================
+    - name: Test packaging/daemon entry points
+      run: |
+        echo "Testing both entry point methods..."
+        python -m praisonai --version
+        praisonai --version
+
+    - name: Test doctor packaging command
+      run: |
+        echo "Testing doctor packaging diagnostics..."
+        praisonai doctor packaging --json
+
     # ==================== REAL API TESTS ====================
     - name: Real API test - Agent run
       if: env.OPENAI_API_KEY != ''

.gitignore

@@ -97,4 +97,5 @@ Cargo.lock
 
 src/praisonai/build*.egg-info/
 src/praisonai/PraisonAI.egg-info/
-jobs/*
+jobs/*
+*.egg-info

README.md

@@ -23,7 +23,11 @@
 
 </div>
 
-PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
+PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous, self-improving agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
+
+```bash
+curl -fsSL https://praison.ai/install.sh | bash
+```
 
 <div align="center">
   <br>
@@ -290,8 +294,35 @@ def search(query: str) -> str:
 
 @tool
 def calculate(expression: str) -> float:
-    """Evaluate a math expression."""
-    return eval(expression)
+    """Safely evaluate a numeric arithmetic expression."""
+    import ast
+    import operator
+    
+    # Define allowed operations
+    _OPS = {
+        ast.Add: operator.add,
+        ast.Sub: operator.sub,
+        ast.Mult: operator.mul,
+        ast.Div: operator.truediv,
+        ast.Pow: operator.pow,
+        ast.USub: operator.neg,
+        ast.UAdd: operator.pos,
+    }
+    
+    def _safe_eval(node):
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return node.value
+        elif isinstance(node, ast.BinOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))
+        elif isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_safe_eval(node.operand))
+        else:
+            raise ValueError("Unsupported expression")
+    
+    try:
+        return _safe_eval(ast.parse(expression, mode="eval").body)
+    except (ValueError, SyntaxError, TypeError, ZeroDivisionError, OverflowError):
+        raise ValueError("Invalid arithmetic expression")
 
 agent = Agent(
     instructions="You are a helpful assistant",
@@ -300,6 +331,7 @@ agent = Agent(
 agent.start("Search for AI news and calculate 15*4")
 ```
 
+> ⚠️ **Security Note:** Never use `eval()`, `exec()`, or `subprocess` in tool functions that process LLM-generated or user-supplied input. Always validate and sanitize inputs to prevent code injection attacks.
 > 📖 [Full tools docs](https://docs.praison.ai/docs/tools/tools) — BaseTool, tool packages, 100+ built-in tools
 
 ### 5. Persistence (Databases)
@@ -326,6 +358,15 @@ pip install "praisonai[claw]"
 praisonai claw
 ```
 
+#### Required Environment Variables
+
+Copy `.env.example` to `.env` and configure the following variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes | OpenAI API key for all LLM calls |
+| `TAVILY_API_KEY` | Yes (Claw) | Tavily key for the built-in web-search tool. Get one free at https://app.tavily.com |
+
 Open **http://localhost:8082** — the dashboard comes with 13 built-in pages: Chat, Agents, Memory, Knowledge, Channels, Guardrails, Cron, and more. Add messaging channels directly from the UI.
 
 > 📖 [Full Claw docs](https://docs.praison.ai/docs/concepts/claw) — platform tokens, CLI options, Docker, and YAML agent mode
@@ -341,7 +382,7 @@ praisonai flow
 
 Open **http://localhost:7861** — use the **Agent** and **Agent Team** components to create sequential or parallel workflows. Connect Chat Input → Agent Team → Chat Output for instant multi-agent pipelines.
 
-> 📖 [Full Flow docs](https://docs.praison.ai/docs/concepts/flow) — visual agent building, component reference, and deployment
+> 📖 [Full Flow docs](https://docs.praison.ai/docs/concepts/agentflow) — visual agent building, component reference, and deployment
 
 ### 8. PraisonAI UI 🤖 (Clean Chat)
 

api.md

@@ -40,6 +40,7 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_with_context</a>(message: str, context: 'ContextPack', **kwargs) -> str</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>() -> Optional[bool]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>(value: Optional[bool]) -> None</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">clone_for_channel</a>() -> 'Agent'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">close</a>() -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">console</a>() -> Optional[Any]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">context_manager</a>() -> Optional[Any]</code>
@@ -171,7 +172,9 @@ Methods:
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">safe_run</a>(**kwargs) -> ToolResult</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate</a>() -> bool</code>
 * <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_class</a>() -> bool</code>
+* <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">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>
@@ -179,8 +182,10 @@ 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">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">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>
@@ -206,10 +211,12 @@ Methods:
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">execute_callback_sync</a>(task_output: TaskOutput) -> None</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">get_next_task</a>(context: Dict[str, Any]) -> Optional[str]</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">initialize_memory</a>()</code>
+* <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">initialize_memory_async</a>()</code>
+* <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">set_status</a>(new_status: str) -> None</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">store_in_memory</a>(content: str, agent_name: str = None, task_id: str = None)</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">to_dict</a>() -> Dict[str, Any]</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">loop</a>(step: Any = None, steps: Optional[List[Any]] = None, over: Optional[str] = None, from_csv: Optional[str] = None, from_file: Optional[str] = None, var_name: str = 'item', parallel: bool = False, max_workers: Optional[int] = None, output_variable: Optional[str] = None) -> Loop</code>
-* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">parallel</a>(steps: List) -> Parallel</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">parallel</a>(steps: List, max_workers: Optional[int] = None, on_failure: str = 'partial_ok') -> Parallel</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">repeat</a>(step: Any, until: Optional[Callable[[WorkflowContext], bool]] = None, max_iterations: int = 10) -> Repeat</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">route</a>(routes: Dict[str, List], default: Optional[List] = None) -> Route</code>
 
@@ -466,14 +473,26 @@ Methods:
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">activate_by_name</a>(name: str) -> bool</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">add_skill</a>(skill_path: str) -> Optional[LoadedSkill]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">clear</a>() -> None</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">create_skill</a>(name: str, content: str, category: str = None) -> dict</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">delete_skill</a>(name: str) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">discover</a>(skill_dirs: Optional[List[str]] = None, include_defaults: bool = True) -> int</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">edit_skill</a>(name: str, content: str) -> dict</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_allowed_tools</a>(name: str) -> List[str]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_available_skills</a>() -> List[SkillMetadata]</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_available_skills_by_state</a>(state: SkillState) -> List[LoadedSkill]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_instructions</a>(name: str) -> Optional[str]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_skill</a>(name: str) -> Optional[LoadedSkill]</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_skills_diagnostics</a>() -> Dict[str, ValidationResult]</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_user_invocable_skills</a>() -> List[LoadedSkill]</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">invoke</a>(name: str, raw_args: str = '', session_id: Optional[str] = None, shell_exec: bool = False) -> Optional[str]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">load_resources</a>(name: str) -> bool</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">patch_skill</a>(name: str, old_string: str, new_string: str, file_path: str = None, replace_all: bool = False) -> dict</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">remove_skill_file</a>(name: str, file_path: str) -> dict</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">skill_names</a>() -> List[str]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">skills</a>() -> List[LoadedSkill]</code>
 * <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">to_prompt</a>() -> str</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">validate_skill_capabilities</a>(skill_name: str, force_refresh: bool = False) -> ValidationResult</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">write_skill_file</a>(name: str, file_path: str, file_content: str) -> dict</code>
 * <code title="class SkillMetadata">SkillMetadata.<a href="./src/praisonai-agents/praisonaiagents/skills/models.py">from_properties</a>(props: SkillProperties) -> 'SkillMetadata'</code>
 * <code title="class SkillProperties">SkillProperties.<a href="./src/praisonai-agents/praisonaiagents/skills/models.py">to_dict</a>() -> dict</code>
 * <code title="class SkillsConfig">SkillsConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
@@ -588,6 +607,13 @@ Methods:
 * <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">set_tool_budget</a>(tool_name: str, max_tokens: int, protected: bool = False) -> None</code>
 * <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">truncate_tool_output</a>(tool_name: str, output: str) -> str</code>
 
+# UI
+
+Types:
+```python
+from praisonaiagents import A2UI
+```
+
 # Config
 
 Types:
@@ -700,6 +726,7 @@ Methods:
 * <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">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>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">context_manager</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">current_plan</a>()</code>
 * <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">default_completion_checker</a>(task, agent_output)</code>
@@ -741,7 +768,7 @@ Methods:
 
 Types:
 ```python
-from praisonai import AgentApp, AgentOS, CloudProvider, Deploy, DeployConfig, DeployType, PraisonAI, __version__
+from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, PraisonAI, __version__, arun, run, run_integrated_gateway
 ```
 
 # CLI
@@ -771,6 +798,11 @@ Methods:
 * <code title="cli">praisonai bot bot-callback <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot discord <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot email <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot install-daemon <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot linear <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot list <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot purge <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot replay <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot slack <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot start <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot telegram <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
@@ -811,6 +843,7 @@ Methods:
 * <code title="cli">praisonai context show <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
 * <code title="cli">praisonai context stats <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
 * <code title="cli">praisonai context tail <a href="./src/praisonai/praisonai/cli/commands/context.py">--help</a></code>
+* <code title="cli">praisonai dashboard unified <a href="./src/praisonai/praisonai/cli/commands/dashboard.py">--help</a></code>
 * <code title="cli">praisonai debug acp <a href="./src/praisonai/praisonai/cli/commands/debug.py">--help</a></code>
 * <code title="cli">praisonai debug debug-callback <a href="./src/praisonai/praisonai/cli/commands/debug.py">--help</a></code>
 * <code title="cli">praisonai debug interactive <a href="./src/praisonai/praisonai/cli/commands/debug.py">--help</a></code>
@@ -837,8 +870,10 @@ Methods:
 * <code title="cli">praisonai doctor env <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 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>
 * <code title="cli">praisonai doctor troubleshoot <a href="./src/praisonai/praisonai/cli/commands/doctor.py">--help</a></code>
 * <code title="cli">praisonai endpoints list <a href="./src/praisonai/praisonai/cli/commands/endpoints.py">--help</a></code>
@@ -850,27 +885,50 @@ Methods:
 * <code title="cli">praisonai eval judge <a href="./src/praisonai/praisonai/cli/commands/eval.py">--help</a></code>
 * <code title="cli">praisonai eval list-judges <a href="./src/praisonai/praisonai/cli/commands/eval.py">--help</a></code>
 * <code title="cli">praisonai eval performance <a href="./src/praisonai/praisonai/cli/commands/eval.py">--help</a></code>
+* <code title="cli">praisonai examples find <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples info <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples list <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples report <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples run <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples run-all <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
 * <code title="cli">praisonai examples stats <a href="./src/praisonai/praisonai/cli/commands/examples.py">--help</a></code>
+* <code title="cli">praisonai flow export <a href="./src/praisonai/praisonai/cli/commands/flow.py">--help</a></code>
 * <code title="cli">praisonai flow flow-start <a href="./src/praisonai/praisonai/cli/commands/flow.py">--help</a></code>
+* <code title="cli">praisonai flow import <a href="./src/praisonai/praisonai/cli/commands/flow.py">--help</a></code>
+* <code title="cli">praisonai flow list <a href="./src/praisonai/praisonai/cli/commands/flow.py">--help</a></code>
 * <code title="cli">praisonai flow version <a href="./src/praisonai/praisonai/cli/commands/flow.py">--help</a></code>
 * <code title="cli">praisonai gateway channels <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai gateway gateway-callback <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
+* <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 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>
+* <code title="cli">praisonai gateway stop <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
+* <code title="cli">praisonai gateway uninstall <a href="./src/praisonai/praisonai/cli/commands/gateway.py">--help</a></code>
 * <code title="cli">praisonai github triage <a href="./src/praisonai/praisonai/cli/commands/github.py">--help</a></code>
 * <code title="cli">praisonai hooks add <a href="./src/praisonai/praisonai/cli/commands/hooks.py">--help</a></code>
 * <code title="cli">praisonai hooks list <a href="./src/praisonai/praisonai/cli/commands/hooks.py">--help</a></code>
 * <code title="cli">praisonai hooks remove <a href="./src/praisonai/praisonai/cli/commands/hooks.py">--help</a></code>
+* <code title="cli">praisonai kanban block <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban boards <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban comment <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban complete <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban create <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban dispatch <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban link <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban list <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban move <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban reclaim <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban show <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
+* <code title="cli">praisonai kanban unblock <a href="./src/praisonai/praisonai/cli/commands/kanban.py">--help</a></code>
 * <code title="cli">praisonai knowledge add <a href="./src/praisonai/praisonai/cli/commands/knowledge.py">--help</a></code>
 * <code title="cli">praisonai knowledge index <a href="./src/praisonai/praisonai/cli/commands/knowledge.py">--help</a></code>
 * <code title="cli">praisonai knowledge list <a href="./src/praisonai/praisonai/cli/commands/knowledge.py">--help</a></code>
 * <code title="cli">praisonai knowledge search <a href="./src/praisonai/praisonai/cli/commands/knowledge.py">--help</a></code>
+* <code title="cli">praisonai langextract render <a href="./src/praisonai/praisonai/cli/commands/langextract.py">--help</a></code>
+* <code title="cli">praisonai langextract view <a href="./src/praisonai/praisonai/cli/commands/langextract.py">--help</a></code>
 * <code title="cli">praisonai langfuse config <a href="./src/praisonai/praisonai/cli/commands/langfuse.py">--help</a></code>
 * <code title="cli">praisonai langfuse connect <a href="./src/praisonai/praisonai/cli/commands/langfuse.py">--help</a></code>
 * <code title="cli">praisonai langfuse init <a href="./src/praisonai/praisonai/cli/commands/langfuse.py">--help</a></code>
@@ -889,6 +947,17 @@ Methods:
 * <code title="cli">praisonai lsp start <a href="./src/praisonai/praisonai/cli/commands/lsp.py">--help</a></code>
 * <code title="cli">praisonai lsp status <a href="./src/praisonai/praisonai/cli/commands/lsp.py">--help</a></code>
 * <code title="cli">praisonai lsp stop <a href="./src/praisonai/praisonai/cli/commands/lsp.py">--help</a></code>
+* <code title="cli">praisonai managed delete <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed get <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed list <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed managed-callback <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed multi <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed restore <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed resume <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed run <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed save <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed show <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
+* <code title="cli">praisonai managed update <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
 * <code title="cli">praisonai mcp add <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
 * <code title="cli">praisonai mcp auth <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
 * <code title="cli">praisonai mcp describe <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
@@ -906,10 +975,22 @@ Methods:
 * <code title="cli">praisonai memory search <a href="./src/praisonai/praisonai/cli/commands/memory.py">--help</a></code>
 * <code title="cli">praisonai memory show <a href="./src/praisonai/praisonai/cli/commands/memory.py">--help</a></code>
 * <code title="cli">praisonai memory status <a href="./src/praisonai/praisonai/cli/commands/memory.py">--help</a></code>
+* <code title="cli">praisonai n8n export <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n import <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n list <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n preview <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n pull <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n push <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
+* <code title="cli">praisonai n8n test <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
 * <code title="cli">praisonai obs obs-fallback <a href="./src/praisonai/praisonai/cli/commands/obs.py">--help</a></code>
+* <code title="cli">praisonai onboard onboard-callback <a href="./src/praisonai/praisonai/cli/commands/onboard.py">--help</a></code>
 * <code title="cli">praisonai package install <a href="./src/praisonai/praisonai/cli/commands/package.py">--help</a></code>
 * <code title="cli">praisonai package list <a href="./src/praisonai/praisonai/cli/commands/package.py">--help</a></code>
 * <code title="cli">praisonai package uninstall <a href="./src/praisonai/praisonai/cli/commands/package.py">--help</a></code>
+* <code title="cli">praisonai pairing approve <a href="./src/praisonai/praisonai/cli/commands/pairing.py">--help</a></code>
+* <code title="cli">praisonai pairing clear <a href="./src/praisonai/praisonai/cli/commands/pairing.py">--help</a></code>
+* <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 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>
@@ -999,6 +1080,7 @@ Methods:
 * <code title="cli">praisonai serve status <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai serve stop <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai serve ui <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve ui-gateway <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai serve unified <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai session delete <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
 * <code title="cli">praisonai session export <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
@@ -1006,6 +1088,10 @@ Methods:
 * <code title="cli">praisonai session list <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
 * <code title="cli">praisonai session resume <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
 * <code title="cli">praisonai session show <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
+* <code title="cli">praisonai setup config <a href="./src/praisonai/praisonai/cli/commands/setup.py">--help</a></code>
+* <code title="cli">praisonai setup reset <a href="./src/praisonai/praisonai/cli/commands/setup.py">--help</a></code>
+* <code title="cli">praisonai setup setup-callback <a href="./src/praisonai/praisonai/cli/commands/setup.py">--help</a></code>
+* <code title="cli">praisonai setup wizard <a href="./src/praisonai/praisonai/cli/commands/setup.py">--help</a></code>
 * <code title="cli">praisonai skills check <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
 * <code title="cli">praisonai skills create <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
 * <code title="cli">praisonai skills eligible <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
@@ -1045,7 +1131,13 @@ Methods:
 * <code title="cli">praisonai train llm <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
 * <code title="cli">praisonai train show <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
 * <code title="cli">praisonai train train-callback <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
+* <code title="cli">praisonai ui agents <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
+* <code title="cli">praisonai ui bot <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
+* <code title="cli">praisonai ui realtime <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
 * <code title="cli">praisonai ui ui <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
+* <code title="cli">praisonai up logs <a href="./src/praisonai/praisonai/cli/commands/up.py">--help</a></code>
+* <code title="cli">praisonai up status <a href="./src/praisonai/praisonai/cli/commands/up.py">--help</a></code>
+* <code title="cli">praisonai up up-start <a href="./src/praisonai/praisonai/cli/commands/up.py">--help</a></code>
 * <code title="cli">praisonai version check <a href="./src/praisonai/praisonai/cli/commands/version.py">--help</a></code>
 * <code title="cli">praisonai version show <a href="./src/praisonai/praisonai/cli/commands/version.py">--help</a></code>
 * <code title="cli">praisonai version version-callback <a href="./src/praisonai/praisonai/cli/commands/version.py">--help</a></code>

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.5.146" \
+    "praisonai>=4.6.52" \
     "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.5.146" \
+    "praisonai>=4.6.52" \
     "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.5.146" \
+    "praisonai>=4.6.52" \
     "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

@@ -2,7 +2,7 @@
 from praisonaiagents import Agent
 from praisonaiagents import AgentFlow, Task
 from praisonaiagents.workflows.workflow_configs import (
-    WorkflowOutputConfig, WorkflowPlanningConfig, WorkflowMemoryConfig,
+    WorkflowPlanningConfig, WorkflowMemoryConfig,
 )
 
 # Full-featured workflow with all consolidated params
@@ -32,7 +32,7 @@ workflow = AgentFlow(
         ),
     ],
     # Workflow-level consolidated params
-    output=WorkflowOutputConfig(output="verbose", stream=True),
+    output="verbose",
     planning=WorkflowPlanningConfig(enabled=True, reasoning=True),
     memory=WorkflowMemoryConfig(backend="file"),
     # Agent-like params

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()
     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

@@ -16,8 +16,19 @@ def search_web(query: str) -> str:
 
 
 def calculate(expression: str) -> str:
-    """Calculate a math expression."""
-    return str(eval(expression))
+    """Calculate a math expression safely."""
+    import ast, operator
+    _OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
+            ast.Div: operator.truediv, ast.FloorDiv: operator.floordiv,
+            ast.Mod: operator.mod, ast.Pow: operator.pow,
+            ast.USub: operator.neg, ast.UAdd: operator.pos}
+    def _ev(n):
+        if isinstance(n, ast.Expression): return _ev(n.body)
+        if isinstance(n, ast.Constant) and isinstance(n.value, (int, float)): return n.value
+        if isinstance(n, ast.UnaryOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.operand))
+        if isinstance(n, ast.BinOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.left), _ev(n.right))
+        raise ValueError(f"Unsupported: {ast.dump(n)}")
+    return str(_ev(ast.parse(expression, mode="eval")))
 
 
 # Check if we have an API key
@@ -37,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
@@ -59,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/managed-agents/persistence/clickhouse_managed.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + ClickHouse Persistence — Real conversation with session resume.
+
+ClickHouse stores analytics/state; SQLite stores conversation history.
+
+Prerequisites:
+    pip install praisonai praisonaiagents clickhouse-connect
+    export OPENAI_API_KEY="sk-..."
+    # ClickHouse running on localhost:8123
+"""
+
+import json
+import os
+import sys
+import tempfile
+
+import clickhouse_connect
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+CH_HOST = os.getenv("CH_HOST", "localhost")
+CH_PORT = int(os.getenv("CH_PORT", "8123"))
+CH_USER = os.getenv("CH_USER", "clickhouse")
+CH_PASSWORD = os.getenv("CH_PASSWORD", "clickhouse")
+SQLITE_PATH = os.path.join(tempfile.gettempdir(), "managed_ch_conv.db")
+print(f"ManagedAgent + ClickHouse Persistence\nCH: {CH_HOST}:{CH_PORT}\nSQLite: {SQLITE_PATH}\n")
+
+# Setup ClickHouse table
+client = clickhouse_connect.get_client(host=CH_HOST, port=CH_PORT, username=CH_USER, password=CH_PASSWORD)
+TABLE = "managed_agent_sessions"
+client.command(f"""
+    CREATE TABLE IF NOT EXISTS {TABLE} (
+        session_id String, agent_id String,
+        input_tokens UInt64, output_tokens UInt64,
+        state_json String, created_at DateTime DEFAULT now()
+    ) ENGINE = MergeTree() ORDER BY (session_id, created_at)
+""")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=SQLITE_PATH)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="ClickHouse Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My favourite movie is Interstellar by Christopher Nolan, 2014. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: The Hans Zimmer soundtrack is my favourite film score. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# Store to ClickHouse
+session_id = managed.session_id
+client.insert(TABLE, [[
+    session_id, managed.agent_id or "",
+    managed.total_input_tokens, managed.total_output_tokens,
+    json.dumps({"environment_id": managed.environment_id}),
+]], column_names=["session_id", "agent_id", "input_tokens", "output_tokens", "state_json"])
+
+# ── Phase 2: ClickHouse Verification ──
+print("\n=== Phase 2: ClickHouse Verification ===")
+rows = client.query(f"SELECT session_id, agent_id FROM {TABLE} WHERE session_id=%(sid)s LIMIT 1", parameters={"sid": session_id})
+for row in rows.result_rows:
+    print(f"  session_id: {row[0]}, agent_id: {row[1]}")
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=SQLITE_PATH)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(session_id)
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my favourite movie, director, year, and soundtrack composer?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Interstellar'": "interstellar" in r,
+    "Remembers 'Nolan'": "nolan" in r,
+    "Remembers '2014'": "2014" in r,
+    "Remembers 'Zimmer'": "zimmer" in r,
+    "Session ID continuity": managed2.session_id == session_id,
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+client.command(f"ALTER TABLE {TABLE} DELETE WHERE session_id = '{session_id}'")
+client.close()
+os.unlink(SQLITE_PATH)
+print(f"\n{'PASS' if all_passed else 'FAIL'}: ClickHouse ManagedAgent persistence test")

examples/managed-agents/persistence/cockroachdb_managed.py

@@ -0,0 +1,27 @@
+"""
+CockroachDB Serverless Persistence Example.
+
+CockroachDB Serverless provides distributed SQL with scale-to-zero.
+Auto-handles serialization retries (error 40001) and SSL.
+
+Setup:
+  1. Create free CockroachDB Serverless cluster at https://cockroachlabs.cloud
+  2. Copy connection string from dashboard
+  3. Set env var: export COCKROACHDB_URL="postgresql://user:[email protected]:26257/mydb?sslmode=verify-full"
+  4. pip install praisonai[cockroachdb]
+"""
+
+import os
+from praisonaiagents import Agent
+
+agent = Agent(
+    name="CockroachDB Agent",
+    instructions="You are a helpful assistant.",
+    memory={
+        "session_id": "crdb-demo-session",
+        "db": {"database_url": os.getenv("COCKROACHDB_URL")},
+    },
+)
+
+result = agent.start("What is distributed SQL? Explain in 2 sentences.")
+print(result)

examples/managed-agents/persistence/json_managed.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + JSON File Persistence — Real conversation with session resume.
+
+Uses DefaultSessionStore (JSON files on disk). No external database required.
+
+Prerequisites:
+    pip install praisonai praisonaiagents
+    export OPENAI_API_KEY="sk-..."
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig
+from praisonaiagents import Agent
+from praisonaiagents.session.store import DefaultSessionStore
+
+SESSION_DIR = os.path.join(tempfile.gettempdir(), "managed_json_sessions")
+print(f"ManagedAgent + JSON File Persistence\nSession dir: {SESSION_DIR}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+store = DefaultSessionStore(session_dir=SESSION_DIR)
+managed = ManagedAgent(
+    provider="local", session_store=store,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="JSON Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My favourite city is Barcelona, Spain. I love the Sagrada Familia. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: I always stay at Hotel Arts in Barcelona. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# ── Phase 2: Verify JSON files ──
+print("\n=== Phase 2: JSON File Verification ===")
+json_files = [f for f in os.listdir(SESSION_DIR) if f.endswith(".json")]
+print(f"Files: {json_files}")
+for fname in json_files:
+    with open(os.path.join(SESSION_DIR, fname), "r") as f:
+        data = json.load(f)
+    print(f"  {fname}: {len(data.get('messages', []))} messages")
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+session_id = saved_ids["session_id"]
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, store
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+store2 = DefaultSessionStore(session_dir=SESSION_DIR)
+managed2 = ManagedAgent(provider="local", session_store=store2)
+managed2.resume_session(session_id)
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my favourite city, landmark, and hotel?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Barcelona'": "barcelona" in r,
+    "Remembers 'Sagrada Familia'": "sagrada" in r,
+    "Remembers 'Hotel Arts'": "hotel arts" in r or "arts" in r,
+    "Session ID continuity": managed2.session_id == session_id,
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+shutil.rmtree(SESSION_DIR)
+print(f"\n{'PASS' if all_passed else 'FAIL'}: JSON File ManagedAgent persistence test")

examples/managed-agents/persistence/mongodb_managed.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + MongoDB Persistence — Real conversation with session resume.
+
+MongoDB stores state metadata; SQLite stores conversation history.
+
+Prerequisites:
+    pip install praisonai praisonaiagents pymongo
+    export OPENAI_API_KEY="sk-..."
+    # MongoDB running on localhost:27017
+"""
+
+import os
+import sys
+import tempfile
+
+import pymongo
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+MONGO_URL = os.getenv("MONGO_URL", "mongodb://localhost:27017")
+SQLITE_PATH = os.path.join(tempfile.gettempdir(), "managed_mongo_conv.db")
+print(f"ManagedAgent + MongoDB Persistence\nMongoDB: {MONGO_URL}\nSQLite: {SQLITE_PATH}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=SQLITE_PATH)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="MongoDB Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My favourite book is 'Dune' by Frank Herbert, published 1965. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: 'Dune Messiah' is my second favourite. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# Store session metadata into MongoDB for verification
+mongo_client = pymongo.MongoClient(MONGO_URL)
+mongo_col = mongo_client["praisonai_managed"]["sessions"]
+state_doc = {
+    "_id": managed.session_id,
+    "agent_id": managed.agent_id,
+    "total_input_tokens": managed.total_input_tokens,
+}
+mongo_col.replace_one({"_id": managed.session_id}, state_doc, upsert=True)
+
+# ── Phase 2: MongoDB Verification ──
+print("\n=== Phase 2: MongoDB Verification ===")
+doc = mongo_col.find_one({"_id": managed.session_id})
+print(f"  Session in MongoDB: {doc['_id']}" if doc else "  WARNING: not found")
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+session_id = saved_ids["session_id"]
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=SQLITE_PATH)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(session_id)
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my favourite book, author, year, and second favourite?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Dune'": "dune" in r,
+    "Remembers 'Herbert'": "herbert" in r,
+    "Remembers '1965'": "1965" in r,
+    "Remembers 'Messiah'": "messiah" in r,
+    "Session ID continuity": managed2.session_id == session_id,
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+mongo_col.delete_one({"_id": session_id})
+mongo_client.close()
+os.unlink(SQLITE_PATH)
+print(f"\n{'PASS' if all_passed else 'FAIL'}: MongoDB ManagedAgent persistence test")

examples/managed-agents/persistence/mysql_managed.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + MySQL Persistence — Real conversation with session resume.
+
+Prerequisites:
+    pip install praisonai praisonaiagents mysql-connector-python
+    export OPENAI_API_KEY="sk-..."
+    # MySQL running on localhost:3307
+"""
+
+import os
+import sys
+
+import mysql.connector
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+MYSQL_URL = os.getenv("MYSQL_URL", "mysql://root:praisontest@localhost:3307/praisonai")
+print(f"ManagedAgent + MySQL Persistence\nDB: {MYSQL_URL}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=MYSQL_URL)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="MySQL Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: I live in Tokyo, Japan and love ramen from Ichiran. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: I work as a machine learning engineer at a robotics company. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# ── Phase 2: Direct MySQL Verification ──
+print("\n=== Phase 2: MySQL Verification ===")
+conn = mysql.connector.connect(host="localhost", port=3307, user="root", password="praisontest", database="praisonai")
+cursor = conn.cursor()
+cursor.execute("SELECT table_name FROM information_schema.tables WHERE table_schema='praisonai' AND table_name LIKE '%message%'")
+msg_tables = [r[0] for r in cursor.fetchall()]
+print(f"Message tables: {msg_tables}")
+for t in msg_tables:
+    cursor.execute(f"SELECT COUNT(*) FROM `{t}`")
+    print(f"  {t}: {cursor.fetchone()[0]} rows")
+conn.close()
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=MYSQL_URL)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(saved_ids["session_id"])
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("Where do I live, what's my favourite food, and what do I do for work?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Tokyo'": "tokyo" in r,
+    "Remembers 'ramen'": "ramen" in r,
+    "Remembers 'Ichiran'": "ichiran" in r,
+    "Remembers 'machine learning'": "machine learning" in r or "ml" in r,
+    "Remembers 'robotics'": "robotic" in r,
+    "Session ID continuity": managed2.session_id == saved_ids["session_id"],
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+print(f"\n{'PASS' if all_passed else 'FAIL'}: MySQL ManagedAgent persistence test")

examples/managed-agents/persistence/neon_managed.py

@@ -0,0 +1,36 @@
+"""
+Neon Serverless PostgreSQL Persistence Example.
+
+Neon auto-idles after inactivity — you only pay when active.
+The PraisonAI adapter auto-handles cold-start retries and SSL.
+
+Setup:
+  1. Create free Neon project at https://neon.tech
+  2. Copy connection string from dashboard
+  3. Set env var: export NEON_DATABASE_URL="postgresql://user:[email protected]/dbname?sslmode=require"
+  4. pip install praisonai[neon]
+"""
+
+import os
+from praisonaiagents import Agent
+
+# Option 1: Use NEON_DATABASE_URL env var (recommended)
+agent = Agent(
+    name="Neon Agent",
+    instructions="You are a helpful assistant.",
+    memory={
+        "session_id": "neon-demo-session",
+        "db": {"database_url": os.getenv("NEON_DATABASE_URL")},
+    },
+)
+
+# Option 2: Direct URL
+# agent = Agent(
+#     name="Neon Agent",
+#     instructions="You are a helpful assistant.",
+#     db={"database_url": "postgresql://user:[email protected]/dbname?sslmode=require"},
+#     session_id="neon-demo-session",
+# )
+
+result = agent.start("What is serverless PostgreSQL? Explain in 2 sentences.")
+print(result)

examples/managed-agents/persistence/postgres_managed.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + PostgreSQL Persistence — Real conversation with session resume.
+
+Prerequisites:
+    pip install praisonai praisonaiagents psycopg2-binary
+    export OPENAI_API_KEY="sk-..."
+    # PostgreSQL running on localhost:5432
+"""
+
+import os
+import sys
+
+import psycopg2
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+PG_URL = os.getenv("PG_URL", "postgresql://postgres:postgres@localhost:5432/postgres")
+print(f"ManagedAgent + PostgreSQL Persistence\nDB: {PG_URL}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=PG_URL)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="PG Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My favourite language is Rust, 3 years experience. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: I'm building a web crawler with the reqwest crate. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# ── Phase 2: Direct PostgreSQL Verification ──
+print("\n=== Phase 2: PostgreSQL Verification ===")
+conn = psycopg2.connect(PG_URL)
+cursor = conn.cursor()
+cursor.execute("""
+    SELECT table_name FROM information_schema.tables
+    WHERE table_schema = 'public' AND table_name LIKE '%message%'
+""")
+msg_tables = [r[0] for r in cursor.fetchall()]
+print(f"Message tables: {msg_tables}")
+for t in msg_tables:
+    cursor.execute(f"SELECT COUNT(*) FROM {t}")
+    print(f"  {t}: {cursor.fetchone()[0]} rows")
+conn.close()
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=PG_URL)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(saved_ids["session_id"])
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my favourite language, experience, and what am I building?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Rust'": "rust" in r,
+    "Remembers '3 years'": "3" in r and "year" in r,
+    "Remembers 'crawler'": "crawler" in r or "crawl" in r,
+    "Remembers 'reqwest'": "reqwest" in r,
+    "Session ID continuity": managed2.session_id == saved_ids["session_id"],
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+print(f"\n{'PASS' if all_passed else 'FAIL'}: PostgreSQL ManagedAgent persistence test")

examples/managed-agents/persistence/redis_managed.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + Redis Persistence — Real conversation with session resume.
+
+Redis stores state/metadata; SQLite stores conversation history.
+
+Prerequisites:
+    pip install praisonai praisonaiagents redis
+    export OPENAI_API_KEY="sk-..."
+    # Redis running on localhost:6379
+"""
+
+import os
+import sys
+import tempfile
+
+import redis as redis_lib
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+REDIS_URL = os.getenv("REDIS_URL", "redis://:myredissecret@localhost:6379/0")
+SQLITE_PATH = os.path.join(tempfile.gettempdir(), "managed_redis_conv.db")
+print(f"ManagedAgent + Redis Persistence\nRedis: {REDIS_URL}\nSQLite: {SQLITE_PATH}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=SQLITE_PATH, state_url=REDIS_URL)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="Redis Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My cat Luna is a Siamese who loves tuna treats. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: Luna was adopted from a shelter in Portland, Oregon. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# ── Phase 2: Direct Redis Verification ──
+print("\n=== Phase 2: Redis Verification ===")
+rc = redis_lib.Redis(host="localhost", port=6379, password="myredissecret", decode_responses=True)
+all_keys = rc.keys("*")
+print(f"Total Redis keys: {len(all_keys)}")
+
+# ── Phase 3: Destroy instance ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=SQLITE_PATH, state_url=REDIS_URL)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(saved_ids["session_id"])
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my cat's name, breed, favourite treat, and adoption city?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Luna'": "luna" in r,
+    "Remembers 'Siamese'": "siamese" in r,
+    "Remembers 'tuna'": "tuna" in r,
+    "Remembers 'Portland'": "portland" in r,
+    "Session ID continuity": managed2.session_id == saved_ids["session_id"],
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+os.unlink(SQLITE_PATH)
+print(f"\n{'PASS' if all_passed else 'FAIL'}: Redis ManagedAgent persistence test")

examples/managed-agents/persistence/sqlite_managed.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+ManagedAgent + SQLite Persistence — Real conversation with session resume.
+
+Prerequisites:
+    pip install praisonai praisonaiagents
+    export OPENAI_API_KEY="sk-..."
+"""
+
+import os
+import sqlite3
+import sys
+import tempfile
+
+if not os.getenv("OPENAI_API_KEY"):
+    sys.exit("ERROR: OPENAI_API_KEY not set.")
+
+from praisonai import ManagedAgent, LocalManagedConfig, DB
+from praisonaiagents import Agent
+
+DB_PATH = os.path.join(tempfile.gettempdir(), "managed_sqlite_test.db")
+print(f"ManagedAgent + SQLite Persistence\nDB: {DB_PATH}\n")
+
+# ── Phase 1: Create agent, teach facts ──
+print("=== Phase 1: First Session ===")
+
+db = DB(database_url=DB_PATH)
+managed = ManagedAgent(
+    provider="local", db=db,
+    config=LocalManagedConfig(
+        model="gpt-4o-mini", name="SQLite Memory Agent",
+        system="You are a helpful assistant. Remember all facts the user tells you.",
+    ),
+)
+
+agent = Agent(name="User", backend=managed)
+
+result1 = agent.run("Remember: My dog's name is Biscuit, a golden retriever. Confirm.")
+print(f"Agent: {result1[:200]}...")
+print(f"Session ID: {managed.session_id}")
+
+result2 = agent.run("Also remember: Biscuit's favourite toy is a blue squeaky ball. Confirm.")
+print(f"Agent: {result2[:200]}...")
+
+# ── Phase 2: Verify SQLite directly ──
+print("\n=== Phase 2: SQLite Verification ===")
+conn = sqlite3.connect(DB_PATH)
+cursor = conn.cursor()
+cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
+tables = [r[0] for r in cursor.fetchall()]
+print(f"Tables: {tables}")
+for t in tables:
+    if "message" in t.lower():
+        cursor.execute(f"SELECT COUNT(*) FROM [{t}]")
+        print(f"  {t}: {cursor.fetchone()[0]} rows")
+conn.close()
+
+# ── Phase 3: Destroy instance (simulate idle) ──
+print("\n=== Phase 3: Instance Goes Idle ===")
+saved_ids = managed.save_ids()
+print(f"Saved IDs: {saved_ids}")
+del agent, managed, db
+print("Agent destroyed.\n")
+
+# ── Phase 4: Resume — no config needed, restored from DB ──
+print("=== Phase 4: Resume Session ===")
+db2 = DB(database_url=DB_PATH)
+managed2 = ManagedAgent(provider="local", db=db2)
+managed2.resume_session(saved_ids["session_id"])
+print(f"Resumed session: {managed2.session_id}")
+
+agent2 = Agent(name="User", backend=managed2)
+result3 = agent2.run("What is my dog's name, breed, and favourite toy?")
+print(f"Agent: {result3[:300]}...")
+
+# ── Phase 5: Validate ──
+print("\n=== Phase 5: Validation ===")
+r = result3.lower()
+checks = {
+    "Remembers 'Biscuit'": "biscuit" in r,
+    "Remembers 'golden retriever'": "golden retriever" in r,
+    "Remembers toy": "blue" in r or "squeaky" in r,
+    "Session ID continuity": managed2.session_id == saved_ids["session_id"],
+}
+all_passed = True
+for check, ok in checks.items():
+    print(f"  [{'PASS' if ok else 'FAIL'}] {check}")
+    if not ok:
+        all_passed = False
+
+os.unlink(DB_PATH)
+print(f"\n{'PASS' if all_passed else 'FAIL'}: SQLite ManagedAgent persistence test")

examples/managed-agents/persistence/supabase_direct_managed.py

@@ -0,0 +1,30 @@
+"""
+Supabase Direct PostgreSQL Persistence Example.
+
+Supabase offers two connection modes:
+  1. REST API (via supabase-py) — set SUPABASE_URL + SUPABASE_KEY
+  2. Direct PostgreSQL (via psycopg2) — use Postgres connection string
+
+This example uses direct PostgreSQL mode with auto-retry for paused projects.
+
+Setup:
+  1. Create free Supabase project at https://supabase.com
+  2. Go to Settings > Database > Connection string (URI)
+  3. Set env var: export SUPABASE_DATABASE_URL="postgresql://postgres.xxx:[pass]@xxx.pooler.supabase.com:6543/postgres"
+  4. pip install praisonai[postgresql]
+"""
+
+import os
+from praisonaiagents import Agent
+
+agent = Agent(
+    name="Supabase Agent",
+    instructions="You are a helpful assistant.",
+    memory={
+        "session_id": "supabase-demo-session",
+        "db": {"database_url": os.getenv("SUPABASE_DATABASE_URL")},
+    },
+)
+
+result = agent.start("What is Supabase? Explain in 2 sentences.")
+print(result)

examples/managed-agents/persistence/turso_managed.py

@@ -0,0 +1,31 @@
+"""
+Turso/libSQL Persistence Example.
+
+Turso provides SQLite-at-the-edge with automatic sync and scale-to-zero.
+
+Setup:
+  1. Create free Turso database at https://turso.tech
+  2. Run: turso db tokens create <db-name>
+  3. Set env vars:
+     export TURSO_DATABASE_URL="libsql://mydb-user.turso.io"
+     export TURSO_AUTH_TOKEN="eyJ..."
+  4. pip install praisonai[turso]
+"""
+
+import os
+from praisonaiagents import Agent
+
+agent = Agent(
+    name="Turso Agent",
+    instructions="You are a helpful assistant.",
+    memory={
+        "session_id": "turso-demo-session",
+        "db": {
+            "database_url": os.getenv("TURSO_DATABASE_URL"),
+            "auth_token": os.getenv("TURSO_AUTH_TOKEN"),
+        },
+    },
+)
+
+result = agent.start("What is edge computing? Explain in 2 sentences.")
+print(result)

examples/mcp/multi_server.py

@@ -19,20 +19,43 @@ import os
 
 def calculate(expression: str) -> str:
     """
-    A simple calculator tool that evaluates mathematical expressions.
-    
+    A simple calculator tool that evaluates mathematical expressions safely.
+
     Args:
         expression: A mathematical expression to evaluate (e.g., "2 + 2")
-    
+
     Returns:
         The result of the calculation
     """
+    import ast
+    import operator
+
+    _OPS = {
+        ast.Add: operator.add,
+        ast.Sub: operator.sub,
+        ast.Mult: operator.mul,
+        ast.Div: operator.truediv,
+        ast.FloorDiv: operator.floordiv,
+        ast.Mod: operator.mod,
+        ast.Pow: operator.pow,
+        ast.USub: operator.neg,
+        ast.UAdd: operator.pos,
+    }
+
+    def _safe_eval(node):
+        if isinstance(node, ast.Expression):
+            return _safe_eval(node.body)
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return node.value
+        if isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_safe_eval(node.operand))
+        if isinstance(node, ast.BinOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))
+        raise ValueError(f"Unsupported expression: {ast.dump(node)}")
+
     try:
-        # Safe evaluation of mathematical expressions
-        allowed_chars = set("0123456789+-*/.() ")
-        if not all(c in allowed_chars for c in expression):
-            return "Error: Invalid characters in expression"
-        result = eval(expression)
+        tree = ast.parse(expression, mode="eval")
+        result = _safe_eval(tree)
         return f"Result: {result}"
     except Exception as e:
         return f"Error: {str(e)}"

examples/mcp_server/custom_tools_server.py

@@ -24,12 +24,18 @@ def main():
     def calculate(expression: str) -> str:
         """Safely evaluate a mathematical expression."""
         try:
-            # Only allow safe math operations
-            allowed = set("0123456789+-*/.(). ")
-            if not all(c in allowed for c in expression):
-                return "Error: Invalid characters in expression"
-            result = eval(expression)  # Safe due to character filtering
-            return f"Result: {result}"
+            import ast, operator
+            _OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
+                    ast.Div: operator.truediv, ast.FloorDiv: operator.floordiv,
+                    ast.Mod: operator.mod, ast.Pow: operator.pow,
+                    ast.USub: operator.neg, ast.UAdd: operator.pos}
+            def _ev(n):
+                if isinstance(n, ast.Expression): return _ev(n.body)
+                if isinstance(n, ast.Constant) and isinstance(n.value, (int, float)): return n.value
+                if isinstance(n, ast.UnaryOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.operand))
+                if isinstance(n, ast.BinOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.left), _ev(n.right))
+                raise ValueError(f"Unsupported: {ast.dump(n)}")
+            return f"Result: {_ev(ast.parse(expression, mode='eval'))}"
         except Exception as e:
             return f"Error: {e}"
     

examples/middleware/configurable_model.py

@@ -10,8 +10,7 @@ from praisonaiagents import Agent
 agent = Agent(
     name="FlexBot",
     instructions="You are a helpful assistant.",
-    llm="gpt-4o-mini",
-    llm_config={"configurable": True}
+    llm={"model": "gpt-4o-mini", "configurable": True},
 )
 
 if __name__ == "__main__":

examples/middleware/injected_state.py

@@ -21,7 +21,7 @@ agent = Agent(
     name="ContextBot",
     instructions="You help show context information.",
     tools=[show_context],
-    session_id="my-session-123"
+    memory={"session_id": "my-session-123"},
 )
 
 if __name__ == "__main__":

examples/observability/langfuse_example.py

@@ -1,48 +1,40 @@
 """
-Langfuse Integration Example
+Langfuse Integration Example (Updated for TraceSinkProtocol)
 
-This example shows how to use Langfuse for LLM observability.
+This example shows how to use Langfuse for LLM observability with PraisonAI's native trace infrastructure.
 
 Setup:
-    1. Sign up at https://langfuse.com/
-    2. Get your API keys from the project settings
-    3. Set environment variables:
-       export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
-       export LANGFUSE_SECRET_KEY=sk-lf-xxx
-    4. Install dependencies:
-       pip install opentelemetry-sdk opentelemetry-exporter-otlp
+    pip install "praisonai[langfuse]"
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
 
 Usage:
     python langfuse_example.py
 """
-
-import os
-from praisonai_tools.observability import obs
 from praisonaiagents import Agent
-
-# Initialize Langfuse
-success = obs.init(
-    provider="langfuse",
-    project_name="praisonai-demo",
+from praisonai.observability import LangfuseSink
+from praisonaiagents.trace.protocol import (
+    TraceEmitter, set_default_emitter
 )
 
-if not success:
-    print("Failed to initialize Langfuse. Check your API keys.")
-    print("Required: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY")
-    exit(1)
+# Initialize Langfuse observability
+sink = LangfuseSink()
+emitter = TraceEmitter(sink=sink, enabled=True)
+set_default_emitter(emitter)
 
-print("Langfuse initialized successfully!")
-print(f"View traces at: https://cloud.langfuse.com/")
-
-# Create agent
+# Create and run agent — all traces automatically captured
 agent = Agent(
+    name="Coder",
     instructions="You are a helpful coding assistant.",
-    model="gpt-4o-mini",
+    llm="openai/gpt-4o-mini",
 )
 
-# Run with tracing
-with obs.trace("coding-session", user_id="developer-1"):
-    response = agent.chat("Write a Python function to calculate fibonacci numbers")
-    print(response)
+try:
+    result = agent.start("Write a Python function to calculate fibonacci numbers")
+    print(result)
+finally:
+    # Ensure traces are flushed and resources cleaned up
+    sink.flush()
+    sink.close()
 
 print("\nCheck Langfuse dashboard for traces!")

examples/persistence/clickhouse_persistence.py

@@ -0,0 +1,156 @@
+"""
+ClickHouse — Persistence Example
+
+Demonstrates:
+  - Connecting to ClickHouse
+  - Creating tables for agent state
+  - Writing and reading agent metadata
+  - JSON state storage and retrieval
+  - Session resume after simulated restart
+
+Requirements:
+    pip install clickhouse-connect
+    Docker: ClickHouse on localhost:8123 (user=clickhouse, password=clickhouse)
+
+Run:
+    python clickhouse_persistence.py
+"""
+
+import json
+import uuid
+import clickhouse_connect
+
+CH_HOST = "localhost"
+CH_PORT = 8123
+CH_USER = "clickhouse"
+CH_PASSWORD = "clickhouse"
+
+print(f"ClickHouse: {CH_HOST}:{CH_PORT}\n")
+
+client = clickhouse_connect.get_client(
+    host=CH_HOST, port=CH_PORT, username=CH_USER, password=CH_PASSWORD,
+)
+
+TABLE_SESSIONS = f"praison_sessions_{uuid.uuid4().hex[:8]}"
+TABLE_STATE = f"praison_state_{uuid.uuid4().hex[:8]}"
+
+# --- Phase 1: Create tables and insert session data ---
+print("=== Phase 1: Create Tables & Insert Sessions ===")
+client.command(f"""
+    CREATE TABLE IF NOT EXISTS {TABLE_SESSIONS} (
+        session_id String,
+        agent_id String,
+        agent_version UInt32,
+        total_input_tokens UInt64,
+        total_output_tokens UInt64,
+        model String,
+        created_at DateTime DEFAULT now()
+    ) ENGINE = MergeTree()
+    ORDER BY session_id
+""")
+
+sessions = [
+    ["session_ch_001", "agent_demo_001", 3, 500, 200, "gpt-4o"],
+    ["session_ch_002", "agent_demo_002", 1, 1000, 400, "gpt-4o-mini"],
+    ["session_ch_003", "agent_demo_001", 3, 750, 300, "gpt-4o"],
+]
+
+client.insert(
+    TABLE_SESSIONS, sessions,
+    column_names=["session_id", "agent_id", "agent_version", "total_input_tokens", "total_output_tokens", "model"],
+)
+
+for s in sessions:
+    print(f"  Inserted: {s[0]} (agent={s[1]}, tokens_in={s[3]})")
+
+print()
+
+# --- Phase 2: Query and verify ---
+print("=== Phase 2: Query & Verify ===")
+result = client.query(f"SELECT * FROM {TABLE_SESSIONS} ORDER BY session_id")
+print(f"  Total sessions: {len(result.result_rows)}")
+for row in result.result_rows:
+    print(f"    {row[0]}: agent={row[1]}, v{row[2]}, tokens_in={row[3]}, model={row[5]}")
+
+assert len(result.result_rows) == 3
+assert result.result_rows[0][0] == "session_ch_001"
+
+# Aggregate query
+agg = client.query(f"SELECT agent_id, SUM(total_input_tokens) as total_in FROM {TABLE_SESSIONS} GROUP BY agent_id ORDER BY agent_id")
+print("\n  Tokens by agent:")
+for row in agg.result_rows:
+    print(f"    {row[0]}: {row[1]} input tokens")
+
+print()
+
+# --- Phase 3: JSON state storage ---
+print("=== Phase 3: JSON State Storage ===")
+client.command(f"""
+    CREATE TABLE IF NOT EXISTS {TABLE_STATE} (
+        session_id String,
+        state_json String,
+        updated_at DateTime DEFAULT now()
+    ) ENGINE = ReplacingMergeTree(updated_at)
+    ORDER BY session_id
+""")
+
+state = {
+    "agent_id": "agent_demo_001",
+    "agent_version": 3,
+    "environment_id": "env_ch_001",
+    "total_input_tokens": 2000,
+    "total_output_tokens": 800,
+    "compute_instance_id": "flyio_ch_001",
+    "session_history": [
+        {"id": "session_ch_001", "status": "completed"},
+        {"id": "session_ch_003", "status": "idle"},
+    ],
+}
+
+client.insert(
+    TABLE_STATE,
+    [["session_ch_001", json.dumps(state)]],
+    column_names=["session_id", "state_json"],
+)
+print("  Stored JSON state for session_ch_001")
+
+# Retrieve
+result = client.query(f"SELECT state_json FROM {TABLE_STATE} WHERE session_id = 'session_ch_001'")
+recovered = json.loads(result.result_rows[0][0])
+print(f"  Recovered agent_id: {recovered['agent_id']}")
+print(f"  Recovered tokens: in={recovered['total_input_tokens']}, out={recovered['total_output_tokens']}")
+print(f"  Recovered compute: {recovered['compute_instance_id']}")
+assert recovered["total_input_tokens"] == 2000
+
+print()
+
+# --- Phase 4: Session Resume ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+client.close()
+
+client2 = clickhouse_connect.get_client(
+    host=CH_HOST, port=CH_PORT, username=CH_USER, password=CH_PASSWORD,
+)
+
+result2 = client2.query(f"SELECT state_json FROM {TABLE_STATE} WHERE session_id = 'session_ch_001'")
+assert len(result2.result_rows) > 0, "State not found after restart!"
+recovered2 = json.loads(result2.result_rows[0][0])
+print(f"  Recovered after restart: agent={recovered2['agent_id']}, tokens_in={recovered2['total_input_tokens']}")
+
+# Update state
+recovered2["total_input_tokens"] += 500
+client2.insert(
+    TABLE_STATE,
+    [["session_ch_001", json.dumps(recovered2)]],
+    column_names=["session_id", "state_json"],
+)
+print(f"  Updated tokens_in: {recovered2['total_input_tokens']}")  # noqa: F541
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+client2.command(f"DROP TABLE IF EXISTS {TABLE_SESSIONS}")
+client2.command(f"DROP TABLE IF EXISTS {TABLE_STATE}")
+client2.close()
+print("  Tables dropped.")
+
+print("\n✅ ClickHouse Persistence — All tests passed!")

examples/persistence/json_file_session_store.py

@@ -0,0 +1,128 @@
+"""
+JSON File DefaultSessionStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a DefaultSessionStore (JSON file-backed)
+  - Adding messages and metadata
+  - Verifying data on disk
+  - Session resume after simulated restart
+  - Full managed agent state roundtrip (7 data categories)
+
+Requirements:
+    pip install praisonaiagents
+
+Run:
+    python json_file_session_store.py
+"""
+
+import json
+import os
+import shutil
+import tempfile
+import uuid
+from praisonaiagents.session.store import DefaultSessionStore
+
+# --- Setup ---
+session_dir = os.path.join(tempfile.gettempdir(), f"praison_json_example_{uuid.uuid4().hex[:6]}")
+os.makedirs(session_dir, exist_ok=True)
+print(f"Session directory: {session_dir}\n")
+
+store = DefaultSessionStore(session_dir=session_dir)
+SESSION_ID = f"json-demo-{uuid.uuid4().hex[:8]}"
+
+# --- Phase 1: Add messages ---
+print("=== Phase 1: Add Messages ===")
+messages = [
+    ("user", "What is machine learning?"),
+    ("assistant", "Machine learning is a subset of AI that enables systems to learn from data."),
+    ("user", "Give me an example."),
+    ("assistant", "Spam filters use ML to classify emails as spam or not spam."),
+]
+
+for role, content in messages:
+    store.add_message(SESSION_ID, role, content)
+    print(f"  Added [{role}]: {content[:60]}")
+
+print()
+
+# --- Phase 2: Store metadata (simulating managed agent state) ---
+print("=== Phase 2: Store Metadata ===")
+session = store.get_session(SESSION_ID)
+session.metadata = {
+    "agent_id": "json_demo_agent_001",
+    "agent_version": 2,
+    "environment_id": "env_local_json",
+    "total_input_tokens": 450,
+    "total_output_tokens": 180,
+    "compute_instance_id": "local_json_demo",
+    "session_history": [
+        {"id": SESSION_ID, "status": "idle", "title": "ML chat"},
+    ],
+}
+store._save_session(session)
+
+print(f"  agent_id: {session.metadata['agent_id']}")
+print(f"  tokens: in={session.metadata['total_input_tokens']}, out={session.metadata['total_output_tokens']}")
+print(f"  compute: {session.metadata['compute_instance_id']}")
+
+print()
+
+# --- Phase 3: Verify on disk ---
+print("=== Phase 3: Verify JSON File on Disk ===")
+json_file = os.path.join(session_dir, f"{SESSION_ID}.json")
+assert os.path.exists(json_file), f"JSON file not found: {json_file}"
+
+with open(json_file) as f:
+    data = json.load(f)
+
+print(f"  File: {json_file}")
+print(f"  Session ID: {data['session_id']}")
+print(f"  Messages: {len(data.get('messages', []))}")
+print(f"  Metadata agent_id: {data['metadata']['agent_id']}")
+print(f"  Metadata tokens_in: {data['metadata']['total_input_tokens']}")
+
+assert data["metadata"]["agent_id"] == "json_demo_agent_001"
+assert data["metadata"]["total_input_tokens"] == 450
+assert len(data["messages"]) == 4
+
+print()
+
+# --- Phase 4: Session Resume ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+del store
+
+store2 = DefaultSessionStore(session_dir=session_dir)
+
+# Verify session exists
+assert store2.session_exists(SESSION_ID), "Session not found after restart!"
+
+# Recover history
+history = store2.get_chat_history(SESSION_ID)
+print(f"  Recovered messages: {len(history)}")
+assert len(history) == 4
+
+# Recover metadata
+session2 = store2.get_session(SESSION_ID)
+meta = session2.metadata
+print(f"  Recovered agent_id: {meta['agent_id']}")
+print(f"  Recovered tokens: in={meta['total_input_tokens']}, out={meta['total_output_tokens']}")
+print(f"  Recovered compute: {meta['compute_instance_id']}")
+print(f"  Recovered session_history: {len(meta['session_history'])} entries")
+
+assert meta["agent_id"] == "json_demo_agent_001"
+assert meta["total_input_tokens"] == 450
+assert meta["compute_instance_id"] == "local_json_demo"
+
+# Continue conversation
+store2.add_message(SESSION_ID, "user", "What about deep learning?")
+store2.add_message(SESSION_ID, "assistant", "Deep learning uses neural networks with many layers.")
+final_history = store2.get_chat_history(SESSION_ID)
+print(f"  Messages after resume: {len(final_history)}")
+assert len(final_history) == 6
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+shutil.rmtree(session_dir)
+print("  Session directory removed.")
+
+print("\n✅ JSON File DefaultSessionStore — All tests passed!")

examples/persistence/knowledge_qdrant.py

@@ -50,10 +50,12 @@ 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={
-        "vector_store": "qdrant",
-        "url": "http://localhost:6333"
+        "sources": [doc_path],
+        "vector_store": {
+            "provider": "qdrant",
+            "url": "http://localhost:6333",
+        },
     }
 )
 

examples/persistence/mongodb_state_store.py

@@ -0,0 +1,123 @@
+"""
+MongoDB StateStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a MongoDB StateStore
+  - Key-value operations (get/set/delete/exists)
+  - Complex state persistence (agent metadata, usage tokens)
+  - Direct MongoDB verification
+  - Session resume after simulated restart
+
+Requirements:
+    pip install praisonai pymongo
+    Docker: MongoDB on localhost:27017 (no auth)
+
+Run:
+    python mongodb_state_store.py
+"""
+
+import uuid
+import pymongo
+from praisonai.persistence.state.mongodb import MongoDBStateStore
+
+MONGO_URL = "mongodb://localhost:27017"
+DATABASE = "praisonai_example"
+COLLECTION = f"state_{uuid.uuid4().hex[:8]}"
+
+print(f"MongoDB: {MONGO_URL}")
+print(f"Database: {DATABASE}, Collection: {COLLECTION}\n")
+
+store = MongoDBStateStore(url=MONGO_URL, database=DATABASE, collection=COLLECTION)
+
+# --- Phase 1: Basic key-value operations ---
+print("=== Phase 1: Basic Key-Value Operations ===")
+store.set("agent_id", "mongo_demo_agent_001")
+store.set("model", "gpt-4o-mini")
+store.set("counter", 42)
+
+print(f"  agent_id: {store.get('agent_id')}")
+print(f"  model: {store.get('model')}")
+print(f"  counter: {store.get('counter')}")
+print(f"  exists('agent_id'): {store.exists('agent_id')}")
+print(f"  exists('missing'): {store.exists('missing')}")
+
+assert store.get("agent_id") == "mongo_demo_agent_001"
+assert store.get("counter") == 42
+
+print()
+
+# --- Phase 2: Complex state persistence ---
+print("=== Phase 2: Complex State Persistence ===")
+managed_state = {
+    "agent_id": "mongo_demo_agent_001",
+    "agent_version": 4,
+    "environment_id": "env_mongo_001",
+    "total_input_tokens": 800,
+    "total_output_tokens": 300,
+    "compute_instance_id": "e2b_mongo_demo",
+    "session_history": [
+        {"id": "session_m1", "status": "completed"},
+        {"id": "session_m2", "status": "idle"},
+    ],
+}
+
+store.set("managed_state", managed_state)
+recovered = store.get("managed_state")
+
+print(f"  agent_id: {recovered['agent_id']}")
+print(f"  agent_version: {recovered['agent_version']}")
+print(f"  total_input_tokens: {recovered['total_input_tokens']}")
+print(f"  compute_instance_id: {recovered['compute_instance_id']}")
+print(f"  session_history count: {len(recovered['session_history'])}")
+
+assert recovered["agent_id"] == "mongo_demo_agent_001"
+assert recovered["total_input_tokens"] == 800
+
+print()
+
+# --- Phase 3: Direct MongoDB Verification ---
+print("=== Phase 3: Direct MongoDB Verification ===")
+client = pymongo.MongoClient(MONGO_URL)
+doc = client[DATABASE][COLLECTION].find_one({"_id": "managed_state"})
+print(f"  Raw doc _id: {doc['_id']}")
+print(f"  Raw doc value.agent_id: {doc['value']['agent_id']}")
+print(f"  Raw doc value.total_input_tokens: {doc['value']['total_input_tokens']}")
+assert doc["value"]["compute_instance_id"] == "e2b_mongo_demo"
+client.close()
+
+print()
+
+# --- Phase 4: Session Resume ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+store.close()
+
+store2 = MongoDBStateStore(url=MONGO_URL, database=DATABASE, collection=COLLECTION)
+
+recovered2 = store2.get("managed_state")
+assert recovered2 is not None, "State not found after restart!"
+print(f"  Recovered agent_id: {recovered2['agent_id']}")
+print(f"  Recovered tokens: in={recovered2['total_input_tokens']}, out={recovered2['total_output_tokens']}")
+print(f"  Recovered compute: {recovered2['compute_instance_id']}")
+
+# Update
+recovered2["total_input_tokens"] += 400
+store2.set("managed_state", recovered2)
+final = store2.get("managed_state")
+print(f"  Updated input_tokens: {final['total_input_tokens']}")
+assert final["total_input_tokens"] == 1200
+
+# Delete test
+store2.delete("counter")
+assert not store2.exists("counter")
+print("  Delete verified: counter removed")
+
+store2.close()
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+client = pymongo.MongoClient(MONGO_URL)
+client[DATABASE].drop_collection(COLLECTION)
+client.close()
+print("  Collection dropped.")
+
+print("\n✅ MongoDB StateStore — All tests passed!")

examples/persistence/mysql_conversation_store.py

@@ -0,0 +1,136 @@
+"""
+MySQL ConversationStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a MySQL ConversationStore
+  - Creating sessions, adding messages
+  - Direct SQL verification that data is in MySQL
+  - Session resume after simulated restart
+
+Requirements:
+    pip install praisonai mysql-connector-python
+    Docker: MySQL on localhost:3307 (user=root, password=praisontest, database=praisonai)
+
+Run:
+    python mysql_conversation_store.py
+"""
+
+import uuid
+import mysql.connector
+from praisonai.persistence.conversation.mysql import MySQLConversationStore
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+MYSQL_HOST = "localhost"
+MYSQL_PORT = 3307
+MYSQL_USER = "root"
+MYSQL_PASSWORD = "praisontest"
+MYSQL_DB = "praisonai"
+TABLE_PREFIX = f"example_{uuid.uuid4().hex[:6]}_"
+
+print(f"MySQL: {MYSQL_USER}@{MYSQL_HOST}:{MYSQL_PORT}/{MYSQL_DB}")
+print(f"Table prefix: {TABLE_PREFIX}\n")
+
+store = MySQLConversationStore(
+    host=MYSQL_HOST, port=MYSQL_PORT, user=MYSQL_USER,
+    password=MYSQL_PASSWORD, database=MYSQL_DB, table_prefix=TABLE_PREFIX,
+)
+SESSION_ID = f"mysql-demo-{uuid.uuid4().hex[:8]}"
+
+# --- Phase 1: Create session and add messages ---
+print("=== Phase 1: Create Session & Add Messages ===")
+session = ConversationSession(
+    session_id=SESSION_ID,
+    agent_id="mysql_demo_agent",
+    name="MySQL Demo",
+    metadata={"agent_version": 7, "model": "gpt-4o-mini"},
+)
+store.create_session(session)
+
+messages = [
+    ("user", "What makes MySQL popular?"),
+    ("assistant", "MySQL is popular for its speed, reliability, and ease of use in web applications."),
+    ("user", "What about scalability?"),
+    ("assistant", "MySQL supports replication, sharding, and clustering for horizontal scalability."),
+]
+
+for role, content in messages:
+    msg = ConversationMessage(session_id=SESSION_ID, role=role, content=content)
+    store.add_message(SESSION_ID, msg)
+    print(f"  Added [{role}]: {content[:60]}")
+
+print()
+
+# --- Phase 2: Verify data ---
+print("=== Phase 2: Verify Data in MySQL ===")
+retrieved = store.get_session(SESSION_ID)
+print(f"  Session: {retrieved.session_id}")
+print(f"  Agent ID: {retrieved.agent_id}")
+print(f"  Metadata: {retrieved.metadata}")
+
+stored = store.get_messages(SESSION_ID)
+print(f"  Messages: {len(stored)}")
+for msg in stored:
+    print(f"    [{msg.role}] {msg.content[:70]}")
+
+print()
+
+# --- Phase 3: Direct SQL Verification ---
+print("=== Phase 3: Direct SQL Verification ===")
+conn = mysql.connector.connect(
+    host=MYSQL_HOST, port=MYSQL_PORT, user=MYSQL_USER,
+    password=MYSQL_PASSWORD, database=MYSQL_DB,
+)
+cur = conn.cursor()
+cur.execute(f"SELECT COUNT(*) FROM {TABLE_PREFIX}messages WHERE session_id = %s", (SESSION_ID,))
+count = cur.fetchone()[0]
+print(f"  Raw SQL message count: {count}")
+assert count == 4, f"Expected 4, got {count}"
+
+cur.execute(f"SELECT agent_id FROM {TABLE_PREFIX}sessions WHERE session_id = %s", (SESSION_ID,))
+agent_id = cur.fetchone()[0]
+print(f"  Raw SQL agent_id: {agent_id}")
+assert agent_id == "mysql_demo_agent"
+conn.close()
+
+print()
+
+# --- Phase 4: Session Resume ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+store.close()
+
+store2 = MySQLConversationStore(
+    host=MYSQL_HOST, port=MYSQL_PORT, user=MYSQL_USER,
+    password=MYSQL_PASSWORD, database=MYSQL_DB, table_prefix=TABLE_PREFIX,
+)
+resumed = store2.get_session(SESSION_ID)
+assert resumed is not None, "Session not found after restart!"
+print(f"  Resumed session: {resumed.session_id}")
+print(f"  Metadata preserved: {resumed.metadata}")
+
+msgs = store2.get_messages(SESSION_ID)
+print(f"  Messages recovered: {len(msgs)}")
+assert len(msgs) == 4
+
+# Continue
+store2.add_message(SESSION_ID, ConversationMessage(session_id=SESSION_ID, role="user", content="Thanks!"))
+store2.add_message(SESSION_ID, ConversationMessage(session_id=SESSION_ID, role="assistant", content="You're welcome!"))
+final = store2.get_messages(SESSION_ID)
+print(f"  Messages after resume: {len(final)}")
+assert len(final) == 6
+
+store2.close()
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+conn = mysql.connector.connect(
+    host=MYSQL_HOST, port=MYSQL_PORT, user=MYSQL_USER,
+    password=MYSQL_PASSWORD, database=MYSQL_DB,
+)
+cur = conn.cursor()
+cur.execute(f"DROP TABLE IF EXISTS {TABLE_PREFIX}messages")
+cur.execute(f"DROP TABLE IF EXISTS {TABLE_PREFIX}sessions")
+conn.commit()
+conn.close()
+print("  Tables dropped.")
+
+print("\n✅ MySQL ConversationStore — All tests passed!")

examples/persistence/postgres_conversation_store.py

@@ -0,0 +1,120 @@
+"""
+PostgreSQL ConversationStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a PostgreSQL ConversationStore
+  - Creating sessions, adding messages, storing metadata
+  - Direct SQL verification that data is in PostgreSQL
+  - Session resume after simulated restart
+
+Requirements:
+    pip install praisonai psycopg2-binary
+    Docker: PostgreSQL on localhost:5432 (user=postgres, password=postgres)
+
+Run:
+    python postgres_conversation_store.py
+"""
+
+import uuid
+import psycopg2
+from praisonai.persistence.conversation.postgres import PostgresConversationStore
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+PG_URL = "postgresql://postgres:postgres@localhost:5432/postgres"
+TABLE_PREFIX = f"example_{uuid.uuid4().hex[:6]}_"
+
+print(f"PostgreSQL URL: {PG_URL}")
+print(f"Table prefix: {TABLE_PREFIX}\n")
+
+store = PostgresConversationStore(url=PG_URL, table_prefix=TABLE_PREFIX)
+SESSION_ID = f"pg-demo-{uuid.uuid4().hex[:8]}"
+
+# --- Phase 1: Create session and add messages ---
+print("=== Phase 1: Create Session & Add Messages ===")
+session = ConversationSession(
+    session_id=SESSION_ID,
+    agent_id="pg_demo_agent",
+    name="PostgreSQL Demo",
+    metadata={"agent_version": 5, "model": "gpt-4o"},
+)
+store.create_session(session)
+
+messages = [
+    ("user", "What are the benefits of PostgreSQL?"),
+    ("assistant", "PostgreSQL offers ACID compliance, extensibility, JSON support, and excellent performance."),
+    ("user", "How does it compare to MySQL?"),
+    ("assistant", "PostgreSQL has better standards compliance and advanced features, while MySQL is simpler for basic use."),
+]
+
+for role, content in messages:
+    msg = ConversationMessage(session_id=SESSION_ID, role=role, content=content)
+    store.add_message(SESSION_ID, msg)
+    print(f"  Added [{role}]: {content[:60]}")
+
+print()
+
+# --- Phase 2: Verify data in PostgreSQL ---
+print("=== Phase 2: Verify Data in PostgreSQL ===")
+retrieved = store.get_session(SESSION_ID)
+print(f"  Session: {retrieved.session_id}")
+print(f"  Agent ID: {retrieved.agent_id}")
+print(f"  Metadata: {retrieved.metadata}")
+
+stored = store.get_messages(SESSION_ID)
+print(f"  Messages: {len(stored)}")
+for msg in stored:
+    print(f"    [{msg.role}] {msg.content[:70]}")
+
+print()
+
+# --- Phase 3: Direct SQL Verification ---
+print("=== Phase 3: Direct SQL Verification ===")
+conn = psycopg2.connect(PG_URL)
+cur = conn.cursor()
+cur.execute(f"SELECT COUNT(*) FROM public.{TABLE_PREFIX}messages WHERE session_id = %s", (SESSION_ID,))
+count = cur.fetchone()[0]
+print(f"  Raw SQL message count: {count}")
+assert count == 4, f"Expected 4, got {count}"
+
+cur.execute(f"SELECT agent_id FROM public.{TABLE_PREFIX}sessions WHERE session_id = %s", (SESSION_ID,))
+agent_id = cur.fetchone()[0]
+print(f"  Raw SQL agent_id: {agent_id}")
+assert agent_id == "pg_demo_agent"
+conn.close()
+
+print()
+
+# --- Phase 4: Session Resume ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+store.close()
+
+store2 = PostgresConversationStore(url=PG_URL, table_prefix=TABLE_PREFIX)
+resumed = store2.get_session(SESSION_ID)
+assert resumed is not None, "Session not found after restart!"
+print(f"  Resumed session: {resumed.session_id}")
+print(f"  Metadata preserved: {resumed.metadata}")
+
+msgs = store2.get_messages(SESSION_ID)
+print(f"  Messages recovered: {len(msgs)}")
+assert len(msgs) == 4
+
+# Continue
+store2.add_message(SESSION_ID, ConversationMessage(session_id=SESSION_ID, role="user", content="Thanks!"))
+store2.add_message(SESSION_ID, ConversationMessage(session_id=SESSION_ID, role="assistant", content="You're welcome!"))
+final = store2.get_messages(SESSION_ID)
+print(f"  Messages after resume: {len(final)}")
+assert len(final) == 6
+
+store2.close()
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+conn = psycopg2.connect(PG_URL)
+conn.autocommit = True
+cur = conn.cursor()
+cur.execute(f"DROP TABLE IF EXISTS public.{TABLE_PREFIX}messages CASCADE")
+cur.execute(f"DROP TABLE IF EXISTS public.{TABLE_PREFIX}sessions CASCADE")
+conn.close()
+print("  Tables dropped.")
+
+print("\n✅ PostgreSQL ConversationStore — All tests passed!")

examples/persistence/redis_state_store.py

@@ -0,0 +1,129 @@
+"""
+Redis StateStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a Redis StateStore
+  - Key-value operations (get/set/delete/exists)
+  - JSON state persistence (agent metadata, usage tokens)
+  - Hash operations for structured data
+  - Session resume: simulate restart, recover state
+
+Requirements:
+    pip install praisonai redis
+    Docker: Redis on localhost:6379 (password=myredissecret)
+
+Run:
+    python redis_state_store.py
+"""
+
+import uuid
+import redis as redis_lib
+from praisonai.persistence.state.redis import RedisStateStore
+
+REDIS_HOST = "localhost"
+REDIS_PORT = 6379
+REDIS_PASSWORD = "myredissecret"
+PREFIX = f"example_{uuid.uuid4().hex[:6]}:"
+
+print(f"Redis: {REDIS_HOST}:{REDIS_PORT}")
+print(f"Key prefix: {PREFIX}\n")
+
+store = RedisStateStore(
+    host=REDIS_HOST, port=REDIS_PORT, password=REDIS_PASSWORD, prefix=PREFIX,
+)
+
+# --- Phase 1: Basic key-value operations ---
+print("=== Phase 1: Basic Key-Value Operations ===")
+store.set("agent_id", "redis_demo_agent_001")
+store.set("model", "gpt-4o-mini")
+store.set("counter", "42")
+
+print(f"  agent_id: {store.get('agent_id')}")
+print(f"  model: {store.get('model')}")
+print(f"  counter: {store.get('counter')}")
+print(f"  exists('agent_id'): {store.exists('agent_id')}")
+print(f"  exists('missing'): {store.exists('missing')}")
+
+print()
+
+# --- Phase 2: JSON state persistence ---
+print("=== Phase 2: JSON State Persistence ===")
+managed_state = {
+    "agent_id": "redis_demo_agent_001",
+    "agent_version": 3,
+    "environment_id": "env_local_001",
+    "total_input_tokens": 1500,
+    "total_output_tokens": 600,
+    "compute_instance_id": "docker_redis_demo",
+    "session_history": [
+        {"id": "session_001", "status": "completed", "title": "Weather chat"},
+        {"id": "session_002", "status": "idle", "title": "Code review"},
+    ],
+}
+
+store.set_json("managed_state", managed_state)
+recovered = store.get_json("managed_state")
+
+print(f"  agent_id: {recovered['agent_id']}")
+print(f"  agent_version: {recovered['agent_version']}")
+print(f"  total_input_tokens: {recovered['total_input_tokens']}")
+print(f"  total_output_tokens: {recovered['total_output_tokens']}")
+print(f"  compute_instance_id: {recovered['compute_instance_id']}")
+print(f"  session_history count: {len(recovered['session_history'])}")
+
+assert recovered["agent_id"] == "redis_demo_agent_001"
+assert recovered["total_input_tokens"] == 1500
+assert recovered["compute_instance_id"] == "docker_redis_demo"
+
+print()
+
+# --- Phase 3: Hash operations ---
+print("=== Phase 3: Hash Operations ===")
+store.hset("agent_meta", "version", "5")
+store.hset("agent_meta", "env_id", "env_abc")
+store.hset("agent_meta", "model", "gpt-4o")
+
+print(f"  version: {store.hget('agent_meta', 'version')}")
+all_meta = store.hgetall("agent_meta")
+print(f"  all fields: {all_meta}")
+
+print()
+
+# --- Phase 4: Session Resume (Simulating Restart) ---
+print("=== Phase 4: Session Resume (Simulating Restart) ===")
+store.close()
+
+# New store instance (simulating process restart)
+store2 = RedisStateStore(
+    host=REDIS_HOST, port=REDIS_PORT, password=REDIS_PASSWORD, prefix=PREFIX,
+)
+
+# Recover state
+recovered2 = store2.get_json("managed_state")
+assert recovered2 is not None, "State not found after restart!"
+print(f"  Recovered agent_id: {recovered2['agent_id']}")
+print(f"  Recovered tokens: in={recovered2['total_input_tokens']}, out={recovered2['total_output_tokens']}")
+print(f"  Recovered compute: {recovered2['compute_instance_id']}")
+print(f"  Recovered sessions: {len(recovered2['session_history'])}")
+
+# Update state (simulate more work)
+recovered2["total_input_tokens"] += 500
+recovered2["total_output_tokens"] += 200
+store2.set_json("managed_state", recovered2)
+
+final = store2.get_json("managed_state")
+print(f"  Updated tokens: in={final['total_input_tokens']}, out={final['total_output_tokens']}")
+assert final["total_input_tokens"] == 2000
+assert final["total_output_tokens"] == 800
+
+store2.close()
+
+# --- Cleanup ---
+print("\n=== Cleanup ===")
+r = redis_lib.Redis(host=REDIS_HOST, port=REDIS_PORT, password=REDIS_PASSWORD)
+for key in r.keys(f"{PREFIX}*"):
+    r.delete(key)
+r.close()
+print("  Keys deleted.")
+
+print("\n✅ Redis StateStore — All tests passed!")

examples/persistence/sqlite_conversation_store.py

@@ -0,0 +1,112 @@
+"""
+SQLite ConversationStore — Full Persistence Example
+
+Demonstrates:
+  - Creating a SQLite ConversationStore
+  - Creating sessions and adding messages
+  - Verifying data is stored in the SQLite file
+  - Session resume: destroy agent, restore from DB, verify state
+
+Requirements:
+    pip install praisonai
+
+Run:
+    python sqlite_conversation_store.py
+"""
+
+import os
+import sqlite3
+import tempfile
+from praisonai.persistence.conversation.sqlite import SQLiteConversationStore
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+# --- Setup ---
+db_path = os.path.join(tempfile.gettempdir(), "praison_sqlite_example.db")
+print(f"SQLite DB path: {db_path}\n")
+
+store = SQLiteConversationStore(path=db_path)
+
+SESSION_ID = "sqlite-demo-session-001"
+
+# --- Phase 1: Create session and add messages ---
+print("=== Phase 1: Create Session & Add Messages ===")
+session = ConversationSession(
+    session_id=SESSION_ID,
+    agent_id="sqlite_demo_agent",
+    name="SQLite Demo Session",
+    metadata={"agent_version": 3, "environment": "local"},
+)
+store.create_session(session)
+
+messages = [
+    ("user", "Hello! What is the capital of France?"),
+    ("assistant", "The capital of France is Paris."),
+    ("user", "What about Germany?"),
+    ("assistant", "The capital of Germany is Berlin."),
+]
+
+for role, content in messages:
+    msg = ConversationMessage(session_id=SESSION_ID, role=role, content=content)
+    store.add_message(SESSION_ID, msg)
+    print(f"  Added [{role}]: {content[:50]}")
+
+print()
+
+# --- Phase 2: Verify data in DB ---
+print("=== Phase 2: Verify Data in SQLite ===")
+retrieved_session = store.get_session(SESSION_ID)
+print(f"  Session ID: {retrieved_session.session_id}")
+print(f"  Agent ID: {retrieved_session.agent_id}")
+print(f"  Metadata: {retrieved_session.metadata}")
+
+stored_messages = store.get_messages(SESSION_ID)
+print(f"  Messages stored: {len(stored_messages)}")
+for msg in stored_messages:
+    print(f"    [{msg.role}] {msg.content[:60]}")
+
+print()
+
+# --- Phase 3: Session Resume ---
+print("=== Phase 3: Session Resume (Simulating Restart) ===")
+store.close()
+
+# Reopen store from same file (simulating process restart)
+store2 = SQLiteConversationStore(path=db_path)
+
+# Verify session still exists
+resumed_session = store2.get_session(SESSION_ID)
+assert resumed_session is not None, "Session not found after restart!"
+print(f"  Resumed session: {resumed_session.session_id}")
+print(f"  Agent ID: {resumed_session.agent_id}")
+print(f"  Metadata preserved: {resumed_session.metadata}")
+
+# Verify messages
+resumed_messages = store2.get_messages(SESSION_ID)
+print(f"  Messages recovered: {len(resumed_messages)}")
+assert len(resumed_messages) == 4, f"Expected 4 messages, got {len(resumed_messages)}"
+
+# Continue the conversation
+new_msg = ConversationMessage(session_id=SESSION_ID, role="user", content="What about Spain?")
+store2.add_message(SESSION_ID, new_msg)
+new_msg2 = ConversationMessage(session_id=SESSION_ID, role="assistant", content="The capital of Spain is Madrid.")
+store2.add_message(SESSION_ID, new_msg2)
+
+final_messages = store2.get_messages(SESSION_ID)
+print(f"  Messages after resume: {len(final_messages)}")
+assert len(final_messages) == 6
+
+store2.close()
+
+# --- Phase 4: Direct SQLite verification ---
+print("\n=== Phase 4: Direct SQLite Verification ===")
+conn = sqlite3.connect(db_path)
+cur = conn.cursor()
+cur.execute("SELECT COUNT(*) FROM praison_messages WHERE session_id = ?", (SESSION_ID,))
+count = cur.fetchone()[0]
+print(f"  Raw SQL message count: {count}")
+assert count == 6
+conn.close()
+
+# Cleanup
+os.remove(db_path)
+print("\n✅ SQLite ConversationStore — All tests passed!")

examples/policy/basic_policy.py

@@ -57,8 +57,8 @@ def main():
     agent = Agent(
         name="SecureAgent",
         instructions="You are a file management assistant.",
-        policy=engine
     )
+    agent.policy = engine
     
     print("\n--- Agent with Policy Enforcement Created ---")
     print(f"Agent: {agent.name}")

examples/python/a2a/a2a-server.py

@@ -21,9 +21,36 @@ def search_web(query: str) -> str:
     return f"Search results for: {query}"
 
 def calculate(expression: str) -> str:
-    """Calculate a mathematical expression."""
+    """Calculate a mathematical expression safely."""
+    import ast
+    import operator
+
+    _OPS = {
+        ast.Add: operator.add,
+        ast.Sub: operator.sub,
+        ast.Mult: operator.mul,
+        ast.Div: operator.truediv,
+        ast.FloorDiv: operator.floordiv,
+        ast.Mod: operator.mod,
+        ast.Pow: operator.pow,
+        ast.USub: operator.neg,
+        ast.UAdd: operator.pos,
+    }
+
+    def _eval(node):
+        if isinstance(node, ast.Expression):
+            return _eval(node.body)
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return node.value
+        if isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_eval(node.operand))
+        if isinstance(node, ast.BinOp) and type(node.op) in _OPS:
+            return _OPS[type(node.op)](_eval(node.left), _eval(node.right))
+        raise ValueError(f"Unsupported expression: {ast.dump(node)}")
+
     try:
-        return f"Result: {eval(expression)}"
+        tree = ast.parse(expression, mode="eval")
+        return f"Result: {_eval(tree)}"
     except Exception:
         return "Invalid expression"
 

examples/python/a2ui/send_surface.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Minimal A2UI example — agent + send_a2ui_messages tool.
+
+Install:
+    pip install praisonaiagents[a2ui]
+
+Run:
+    python send_surface.py
+
+For live rendering, use PraisonAIUI with AG-UI (/agui) — see integrate-a2ui-frontend docs.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.a2ui_tools import send_a2ui_messages
+
+agent = Agent(
+    name="ui-assistant",
+    instructions=(
+        "When asked for UI, call send_a2ui_messages with A2UI v0.9 JSON "
+        "(createSurface on surface id 'main')."
+    ),
+    tools=[send_a2ui_messages],
+)
+
+if __name__ == "__main__":
+    result = agent.start("Show a simple welcome card on surface main")
+    print(result)

examples/python/camera/camera-continuous.py

@@ -75,7 +75,7 @@ class ContinuousCameraMonitor:
             agents=[self.vision_agent],
             tasks=[task],
             process="sequential",
-            verbose=0  # Reduced verbosity for continuous monitoring
+            output="silent",  # Reduced verbosity for continuous monitoring
         )
         
         return agents.start()

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,8 @@
-from praisonaiagents import Agent, Task, AgentTeam
-import logging
+import tempfile
 import os
+import sys
+import logging
+from praisonaiagents import Agent, Task, AgentTeam
 
 # Configure logging
 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
@@ -17,14 +19,20 @@ config = {
     }
 }
 
+# Create sample file in system temp directory
+_sample_path = os.path.join(tempfile.gettempdir(), "sample_knowledge.txt")
+if not os.path.exists(_sample_path):
+    with open(_sample_path, "w", encoding="utf-8") as f:
+        f.write("Mervin Praison is the creator of PraisonAI.\n")
+
 # 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": [_sample_path]},
+)
 
 # Define a task for the agent
 knowledge_task = Task(
@@ -39,8 +47,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/concepts/repetitive-agents.py

@@ -16,7 +16,7 @@ agents = AgentTeam(
     agents=[agent],
     tasks=[task],
     process="workflow",
-    max_iter=30
+    execution={"max_iter": 30},
 )
 
 agents.start()

examples/python/custom_tools/example_latency_tracking.py

@@ -61,7 +61,6 @@ def example_with_wrappers():
         role="Data Analyst",
         goal="Analyze data and provide insights",
         llm="gpt-4o-mini",
-        request_id="request_2"  # Unique request ID
     )
     
     # Operations are automatically tracked

examples/python/custom_tools/tools_with_latency.py

@@ -49,7 +49,18 @@ def calculate_with_tracking(expression: str) -> str:
     time.sleep(0.05)
     
     try:
-        result = eval(expression)
+        import ast, operator
+        _OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
+                ast.Div: operator.truediv, ast.FloorDiv: operator.floordiv,
+                ast.Mod: operator.mod, ast.Pow: operator.pow,
+                ast.USub: operator.neg, ast.UAdd: operator.pos}
+        def _ev(n):
+            if isinstance(n, ast.Expression): return _ev(n.body)
+            if isinstance(n, ast.Constant) and isinstance(n.value, (int, float)): return n.value
+            if isinstance(n, ast.UnaryOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.operand))
+            if isinstance(n, ast.BinOp) and type(n.op) in _OPS: return _OPS[type(n.op)](_ev(n.left), _ev(n.right))
+            raise ValueError(f"Unsupported: {ast.dump(n)}")
+        result = _ev(ast.parse(expression, mode="eval"))
         return f"Result: {result}"
     except Exception as e:
         return f"Error: {str(e)}"

examples/python/data/cot-agents.py

@@ -132,7 +132,8 @@ agents = AgentTeam(
     agents=[qa_generator, total_questions_evaluator, cot_generator, upload_to_huggingface],
     tasks=[generate_task, evaluate_total_questions_task, generate_cot_task, upload_to_huggingface_task],
     process="workflow",
-    max_iter=30, output="minimal"
+    execution={"max_iter": 30},
+    output="minimal",
 )
 
 agents.start()

examples/python/failover_example.py

@@ -18,7 +18,7 @@ openai_profile = AuthProfile(
     provider="openai",
     api_key=os.environ.get("OPENAI_API_KEY", "sk-..."),
     priority=1,  # Highest priority
-    rate_limit=100,
+    rate_limit_rpm=100,
 )
 
 anthropic_profile = AuthProfile(
@@ -26,7 +26,7 @@ anthropic_profile = AuthProfile(
     provider="anthropic",
     api_key=os.environ.get("ANTHROPIC_API_KEY", "sk-ant-..."),
     priority=2,  # Second priority
-    rate_limit=50,
+    rate_limit_rpm=50,
 )
 
 groq_profile = AuthProfile(
@@ -34,7 +34,7 @@ groq_profile = AuthProfile(
     provider="groq",
     api_key=os.environ.get("GROQ_API_KEY", "gsk-..."),
     priority=3,  # Third priority (fast but limited)
-    rate_limit=30,
+    rate_limit_rpm=30,
 )
 
 # Configure failover behavior

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,13 +105,13 @@ def main():
         agents=[researcher, retriever],
         tasks=[store_task, verify_task, query_task, query_both_task],  # Use same verbose level as memory
         memory={
-            "provider": "rag",
             "embedder": {
                 "provider": "openai",
                 "config": {
                     "model": "text-embedding-3-small"
                 }
-            }
+            },
+            "config": {"provider": "sqlite"},
         }
     )
 

examples/python/guardrails/production-guardrails-patterns.py

@@ -6,6 +6,7 @@ built-in validation and safety mechanisms for secure agent operations.
 """
 
 from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents.config.feature_configs import GuardrailConfig
 from praisonaiagents.tools import internet_search
 
 print("=== Production Guardrails Patterns Example ===\n")
@@ -38,8 +39,8 @@ production_agent = Agent(
     goal="Generate safe, compliant content for production use",
     backstory="Production-ready agent with built-in safety and compliance checks",
     tools=[internet_search],
-    guardrails=content_guardrail,
-    max_retries=3)
+    guardrails=GuardrailConfig(validator=content_guardrail, max_retries=3),
+)
 
 # Create secure task with validation
 secure_task = Task(

examples/python/linear_agent_example.py

@@ -0,0 +1,68 @@
+"""
+Linear Agent Example for PraisonAI.
+
+Demonstrates how to create a Linear bot that responds to issue mentions
+and assignments with full coding capabilities.
+"""
+
+import asyncio
+from praisonaiagents import Agent
+from praisonai.bots import LinearBot
+
+# Create an agent with Linear tools and coding capabilities
+agent = Agent(
+    name="PraisonAI Coder",
+    instructions="""
+    You are an autonomous coding agent integrated with Linear.
+    
+    When you are mentioned or assigned an issue:
+    1. Analyze the issue description and requirements
+    2. Break down complex tasks into smaller steps  
+    3. Use available tools to implement solutions
+    4. Update the issue with progress comments
+    5. Create GitHub pull requests when code changes are needed
+    
+    Focus on being helpful, thorough, and providing clear updates.
+    """,
+    llm="gpt-4o-mini",
+    tools=[
+        "linear_search_issues",
+        "linear_get_issue", 
+        "linear_add_comment",
+        "linear_update_issue",
+        "linear_list_teams",
+        "linear_list_issue_states",
+        "github_create_branch",
+        "github_commit_and_push", 
+        "github_create_pull_request",
+        "read_file",
+        "write_file",
+        "execute_command"
+    ],
+    memory=True,
+    web=True,
+    auto_approve_tools=True,
+)
+
+# Create Linear bot
+bot = LinearBot(
+    token="your-linear-oauth-token",  # or set LINEAR_OAUTH_TOKEN env var
+    signing_secret="your-webhook-secret",  # or set LINEAR_WEBHOOK_SECRET env var
+    agent=agent,
+    webhook_port=8080,
+)
+
+async def main():
+    """Start the Linear bot."""
+    print("Starting Linear bot...")
+    print("Set up your Linear webhook to point to: http://your-host:8080/webhook")
+    print("Configure AgentSession and Comment events in Linear webhook settings")
+    
+    try:
+        await bot.start()
+    except KeyboardInterrupt:
+        print("\nStopping bot...")
+        await bot.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/managed-agents/01_create_agent.py

@@ -0,0 +1,9 @@
+from praisonai import Agent, ManagedAgent
+
+# Zero config — defaults: name="Agent", model="claude-haiku-4-5"
+managed = ManagedAgent()
+agent = Agent(name="coder", backend=managed)
+result = agent.start("Say hello")
+
+print(f"Agent ID: {managed.agent_id}")
+print(f"Version: {managed.agent_version}")

examples/python/managed-agents/02_create_environment.py

@@ -0,0 +1,17 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Environment is created automatically — just specify packages/networking in config
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Coding Assistant",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant. Write clean, well-documented code.",
+        networking={"type": "unrestricted"},
+    ),
+)
+
+agent = Agent(name="coder", backend=managed)
+result = agent.start("Say hello")
+
+print(f"Agent ID: {managed.agent_id}")
+print(f"Environment ID: {managed.environment_id}")

examples/python/managed-agents/03_create_session.py

@@ -0,0 +1,18 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Agent, environment, and session are all created automatically on first use
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Coding Assistant",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant. Write clean, well-documented code.",
+        session_title="Quickstart session",
+    ),
+)
+
+agent = Agent(name="coder", backend=managed)
+result = agent.start("Say hello")
+
+print(f"Agent ID: {managed.agent_id}")
+print(f"Environment ID: {managed.environment_id}")
+print(f"Session ID: {managed.session_id}")

examples/python/managed-agents/04_stream_response.py

@@ -0,0 +1,18 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Coding Assistant",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant. Write clean, well-documented code.",
+    ),
+)
+
+agent = Agent(name="coder", backend=managed)
+
+result = agent.start(
+    "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
+    stream=True,
+)
+
+print("\nAgent finished.")

examples/python/managed-agents/05_select_tools.py

@@ -0,0 +1,27 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Select specific tools: only bash, read, write — everything else disabled
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Bash Only Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant that can only use bash commands.",
+        tools=[
+            {
+                "type": "agent_toolset_20260401",
+                "default_config": {"enabled": False},
+                "configs": [
+                    {"name": "bash", "enabled": True},
+                    {"name": "read", "enabled": True},
+                    {"name": "write", "enabled": True},
+                ],
+            },
+        ],
+    ),
+)
+
+agent = Agent(name="bash-agent", backend=managed)
+result = agent.start("List the current directory contents and show system info using uname -a")
+
+print(result)
+print("\nAgent finished.")

examples/python/managed-agents/06_disable_tools.py

@@ -0,0 +1,25 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Disable specific tools: web access disabled, everything else stays on
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="No Web Agent",
+        model="claude-haiku-4-5",
+        system="You are a coding assistant. You cannot access the web.",
+        tools=[
+            {
+                "type": "agent_toolset_20260401",
+                "configs": [
+                    {"name": "web_fetch", "enabled": False},
+                    {"name": "web_search", "enabled": False},
+                ],
+            },
+        ],
+    ),
+)
+
+agent = Agent(name="no-web-agent", backend=managed)
+result = agent.start("Write a hello world Python script and run it")
+
+print(result)
+print("\nAgent finished.")

examples/python/managed-agents/07_custom_tools.py

@@ -0,0 +1,41 @@
+import json
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+
+def handle_weather(tool_name, tool_input):
+    """Custom tool callback — PraisonAI calls this when the agent uses get_weather."""
+    location = tool_input.get("location", "Unknown")
+    print(f"\n[Custom tool call: {tool_name}]")
+    print(f"[Input: {json.dumps(tool_input)}]")
+    return f"Weather in {location}: 15°C, partly cloudy, humidity 72%"
+
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Weather Agent",
+        model="claude-haiku-4-5",
+        system="You are a weather assistant. Use the get_weather tool to check weather.",
+        tools=[
+            {"type": "agent_toolset_20260401"},
+            {
+                "type": "custom",
+                "name": "get_weather",
+                "description": "Get current weather for a location",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string", "description": "City name"},
+                    },
+                    "required": ["location"],
+                },
+            },
+        ],
+    ),
+    on_custom_tool=handle_weather,
+)
+
+agent = Agent(name="weather-agent", backend=managed)
+result = agent.start("What is the weather in London?")
+
+print(result)
+print("\nAgent finished.")

examples/python/managed-agents/08_update_agent.py

@@ -0,0 +1,22 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="My Agent v1",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant.",
+    ),
+)
+
+agent = Agent(name="updatable", backend=managed)
+
+# First call creates the agent
+result = agent.start("Say hello briefly")
+print(f"Created: {managed.agent_id}, version: {managed.agent_version}")
+
+# Update the agent's system prompt (no need to recreate)
+managed.update_agent(
+    name="My Agent v2",
+    system="You are a senior Python developer. Write production-quality code.",
+)
+print(f"Updated: {managed.agent_id}, version: {managed.agent_version}")

examples/python/managed-agents/09_list_sessions.py

@@ -0,0 +1,23 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Session Demo Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant.",
+    ),
+)
+
+agent = Agent(name="session-demo", backend=managed)
+
+# Run a task to create agent + session
+agent.start("Say hello briefly")
+
+# List sessions for this agent
+sessions = managed.list_sessions()
+print(f"Total sessions: {len(sessions)}")
+for s in sessions[:5]:
+    print(f"  ID: {s['id']}")
+    print(f"  Status: {s['status']}")
+    print(f"  Title: {s['title']}")
+    print()

examples/python/managed-agents/10_web_search.py

@@ -0,0 +1,17 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Research Agent",
+        model="claude-haiku-4-5",
+        system="You are a research assistant. Search the web for information.",
+    ),
+)
+
+agent = Agent(name="researcher", backend=managed)
+result = agent.start(
+    "Search the web for the latest Python 3.13 features and summarize them in 3 bullet points"
+)
+
+print(result)
+print("\nAgent finished.")

examples/python/managed-agents/11_multi_turn.py

@@ -0,0 +1,25 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Multi Turn Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant.",
+    ),
+)
+
+agent = Agent(name="multi-turn", backend=managed)
+print(f"Session ID: {managed.session_id}")
+
+# Multi-turn: each call reuses the same session — agent remembers context
+messages = [
+    "Create a file called greeting.py that prints 'Hello World'",
+    "Now modify greeting.py to accept a name as a command line argument",
+    "Run greeting.py with the argument 'Claude'",
+]
+
+for i, message in enumerate(messages):
+    print(f"\n--- Turn {i + 1}: {message} ---\n")
+    result = agent.start(message)
+    print(result)
+    print("\nAgent finished turn.")

examples/python/managed-agents/12_environment_setup.py

@@ -0,0 +1,22 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Just add packages to the config — environment is created automatically
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Data Science Agent",
+        model="claude-haiku-4-5",
+        system="You are a data science assistant.",
+        packages={"pip": ["pandas", "numpy"]},
+    ),
+)
+
+agent = Agent(name="data-scientist", backend=managed)
+
+print(f"Environment ID: {managed.environment_id}")
+
+result = agent.start(
+    "Create a Python script that generates random sales data with pandas and saves a summary to sales_summary.txt"
+)
+
+print(result)
+print("\nAgent finished.")

examples/python/managed-agents/13_interrupt_session.py

@@ -0,0 +1,20 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Interruptable Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant.",
+    ),
+)
+
+agent = Agent(name="interruptable", backend=managed)
+
+# Start a task
+result = agent.start("Write a Python script that prints numbers 1 to 5")
+print(result)
+
+# Interrupt the agent mid-work
+print("\n[Sending interrupt...]")
+managed.interrupt()
+print("Agent stopped.")

examples/python/managed-agents/14_track_usage.py

@@ -0,0 +1,28 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Usage Tracker Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant.",
+    ),
+)
+
+agent = Agent(name="tracker", backend=managed)
+result = agent.start("Write a one-line Python script that prints the current date and run it")
+
+print(result)
+print("\nAgent finished.")
+
+# Usage tracked automatically
+print("\n--- Usage Report ---")
+print(f"Input tokens:  {managed.total_input_tokens}")
+print(f"Output tokens: {managed.total_output_tokens}")
+
+# Or retrieve detailed session info from the API
+info = managed.retrieve_session()
+print(f"\nSession ID: {info.get('id')}")
+print(f"Status: {info.get('status')}")
+if "usage" in info:
+    print(f"API Input tokens:  {info['usage']['input_tokens']}")
+    print(f"API Output tokens: {info['usage']['output_tokens']}")

examples/python/managed-agents/15_resume_session.py

@@ -0,0 +1,35 @@
+import json
+import pathlib
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+IDS_FILE = pathlib.Path("managed_ids.json")
+
+if IDS_FILE.exists():
+    saved = json.loads(IDS_FILE.read_text())
+    print(f"Resuming session: {saved['session_id']}\n")
+
+    managed = ManagedAgent()
+    managed.resume_session(saved["session_id"])
+
+    agent = Agent(name="coder", backend=managed)
+    result = agent.start("What is my favourite number?", stream=True)
+
+else:
+    managed = ManagedAgent(
+        config=ManagedConfig(
+            name="Persistent Coder",
+            model="claude-haiku-4-5",
+            system="You are a helpful coding assistant.",
+        ),
+    )
+    agent = Agent(name="coder", backend=managed)
+    result = agent.start("Remember this: my favourite number is 42.", stream=True)
+
+    ids = managed.save_ids()
+    IDS_FILE.write_text(json.dumps(ids, indent=2))
+
+    print(f"\nSaved IDs to {IDS_FILE}")
+    print(f"  agent_id      : {managed.agent_id}")
+    print(f"  environment_id: {managed.environment_id}")
+    print(f"  session_id    : {managed.session_id}")
+    print("\nRun this script again to resume the session.")

examples/python/managed-agents/16_session_ids_explained.py

@@ -0,0 +1,21 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Session Demo",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant.",
+    ),
+)
+agent = Agent(name="demo", backend=managed)
+
+agent.start("Say hello and confirm you are ready.", stream=True)
+
+print("\n--- IDs ---")
+print(f"agent_id      : {managed.agent_id}")
+print(f"environment_id: {managed.environment_id}")
+print(f"session_id    : {managed.session_id}")
+print(f"chat_history  : {len(agent.chat_history)} messages")
+
+ids = managed.save_ids()
+print(f"\nsave_ids(): {ids}")

examples/python/managed-agents/17_multi_packages.py

@@ -0,0 +1,22 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Multiple package managers — pip + npm installed before agent starts
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Full Stack Agent",
+        model="claude-haiku-4-5",
+        system="You are a full stack developer.",
+        packages={
+            "pip": ["pandas", "numpy", "scikit-learn"],
+            "npm": ["express"],
+        },
+    ),
+)
+
+agent = Agent(name="fullstack", backend=managed)
+result = agent.start(
+    "Verify pandas and express are installed: run 'python3 -c \"import pandas; print(pandas.__version__)\"' and 'node -e \"console.log(require.resolve('express'))\"'",
+    stream=True,
+)
+
+print("\nAgent finished.")

examples/python/managed-agents/18_limited_networking.py

@@ -0,0 +1,24 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Limited networking: restrict container to specific hosts only
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Restricted Network Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant with restricted network access.",
+        networking={
+            "type": "limited",
+            "allowed_hosts": ["api.github.com"],
+            "allow_mcp_servers": False,
+            "allow_package_managers": True,
+        },
+    ),
+)
+
+agent = Agent(name="restricted", backend=managed)
+result = agent.start(
+    "Try to fetch https://api.github.com and report what you get. Then try https://example.com — it should fail.",
+    stream=True,
+)
+
+print("\nAgent finished.")

examples/python/managed-agents/19_manage_environments.py

@@ -0,0 +1,43 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# Environment management: list, retrieve, archive, delete
+
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Env Management Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant.",
+    ),
+)
+agent = Agent(name="env-mgmt", backend=managed)
+
+# First call creates agent + environment + session
+agent.start("Say hello briefly")
+
+# Access the underlying Anthropic client for environment management
+client = managed._get_client()
+env_id = managed.environment_id
+print(f"Environment ID: {env_id}")
+
+# List all environments
+environments = client.beta.environments.list()
+print(f"\nTotal environments: {len(environments.data)}")
+for env in environments.data[:5]:
+    print(f"  {env.id} | {env.name} | {getattr(env, 'status', 'active')}")
+
+# Retrieve a specific environment
+env = client.beta.environments.retrieve(env_id)
+print(f"\nRetrieved: {env.id} | {env.name}")
+
+# Archive (read-only, existing sessions continue)
+archived = client.beta.environments.archive(env_id)
+print(f"Archived: {archived.id} | status: {getattr(archived, 'status', 'archived')}")
+
+# Delete (only if no sessions reference it — may fail if sessions exist)
+try:
+    client.beta.environments.delete(env_id)
+    print(f"Deleted: {env_id}")
+except Exception as e:
+    print(f"Delete skipped (expected if sessions exist): {e}")
+
+print("\nEnvironment management complete.")

examples/python/managed-agents/20_mcp_servers.py

@@ -0,0 +1,35 @@
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# MCP servers: configure agent with remote MCP tool servers
+# Note: Anthropic's managed agents only support URL-based (SSE) MCP servers
+managed = ManagedAgent(
+    config=ManagedConfig(
+        name="MCP Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant with access to MCP servers.",
+        tools=[
+            {"type": "agent_toolset_20260401"},
+            {"type": "mcp_toolset", "mcp_server_name": "deepwiki"},
+        ],
+        mcp_servers=[
+            {
+                "type": "url",
+                "url": "https://mcp.deepwiki.com/sse",
+                "name": "deepwiki",
+            },
+        ],
+        networking={
+            "type": "limited",
+            "allow_mcp_servers": True,
+            "allow_package_managers": True,
+        },
+    ),
+)
+
+agent = Agent(name="mcp-agent", backend=managed)
+result = agent.start(
+    "Use the deepwiki MCP to read the wiki page for the anthropics/anthropic-cookbook github repo and give a one sentence summary",
+    stream=True,
+)
+
+print("\nAgent finished.")

examples/python/managed-agents/app.py

@@ -0,0 +1,340 @@
+import json
+import pathlib
+from praisonai import Agent, ManagedAgent, ManagedConfig
+
+# 1. Create an agent
+
+managed = ManagedAgent()
+agent = Agent(name="teacher", backend=managed)
+result = agent.start("Say hello briefly", stream=True)
+
+print(f"[1] Agent created: {managed.agent_id} (v{managed.agent_version})")
+
+# 2. Update the agent
+
+managed.update_agent(
+    name="Teaching Agent v2",
+    system="You are a senior Python developer. Write clean, production-quality code.",
+)
+
+print(f"[2] Agent updated: Teaching Agent v2 (v{managed.agent_version})")
+
+# 3-4. Environment + Session are created automatically (already done in step 1)
+
+print(f"[3] Environment created: {managed.environment_id}")
+print(f"[4] Session created: {managed.session_id}")
+
+# 5. Stream a response
+
+print("\n[5] Streaming response...")
+
+result = agent.start("Write a Python script that prints 'Hello from Managed Agents!' and run it", stream=True)
+
+# 6. Multi-turn conversation (same session remembers context)
+
+print("\n[6] Multi-turn: sending follow-up...")
+
+result = agent.start("Now modify that script to accept a name argument and greet that person", stream=True)
+
+# 7. Track usage
+
+info = managed.retrieve_session()
+print("\n[7] Usage report:")
+if info.get("usage"):
+    print(f"    Input tokens:  {info['usage']['input_tokens']}")
+    print(f"    Output tokens: {info['usage']['output_tokens']}")
+else:
+    print(f"    Input tokens:  {managed.total_input_tokens}")
+    print(f"    Output tokens: {managed.total_output_tokens}")
+
+# 8. List sessions
+
+sessions = managed.list_sessions()
+print(f"\n[8] Total sessions: {len(sessions)}")
+for s in sessions[:3]:
+    print(f"    {s['id']} | {s['status']} | {s['title']}")
+
+# 9. Selective tools (only bash + read + write)
+
+bash_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Bash Only Agent",
+        model="claude-haiku-4-5",
+        system="You can only use bash, read, and write tools.",
+        tools=[
+            {
+                "type": "agent_toolset_20260401",
+                "default_config": {"enabled": False},
+                "configs": [
+                    {"name": "bash", "enabled": True},
+                    {"name": "read", "enabled": True},
+                    {"name": "write", "enabled": True},
+                ],
+            },
+        ],
+    ),
+)
+
+bash_agent = Agent(name="bash-only", backend=bash_managed)
+
+print("\n[9] Bash-only agent streaming...")
+result = bash_agent.start("Show the current date and Python version using bash", stream=True)
+
+# 10. Disable specific tools (web disabled, everything else on)
+
+no_web_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="No Web Agent",
+        model="claude-haiku-4-5",
+        system="You are a coding assistant. You cannot access the web.",
+        tools=[
+            {
+                "type": "agent_toolset_20260401",
+                "configs": [
+                    {"name": "web_fetch", "enabled": False},
+                    {"name": "web_search", "enabled": False},
+                ],
+            },
+        ],
+    ),
+)
+
+no_web_agent = Agent(name="no-web", backend=no_web_managed)
+
+print("\n[10] No-web agent streaming...")
+result = no_web_agent.start("Write a Python one-liner that calculates 2**100 and print the result", stream=True)
+
+# 11. Custom tools (you define the tool, PraisonAI calls your callback)
+
+
+def handle_weather(tool_name, tool_input):
+    print(f"\n  [Custom tool: {tool_name} | Input: {json.dumps(tool_input)}]")
+    return "Tokyo: 22°C, sunny, humidity 55%"
+
+
+custom_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Weather Agent",
+        model="claude-haiku-4-5",
+        system="You are a weather assistant. Use the get_weather tool to check weather.",
+        tools=[
+            {"type": "agent_toolset_20260401"},
+            {
+                "type": "custom",
+                "name": "get_weather",
+                "description": "Get current weather for a location",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string", "description": "City name"},
+                    },
+                    "required": ["location"],
+                },
+            },
+        ],
+    ),
+    on_custom_tool=handle_weather,
+)
+
+custom_agent = Agent(name="weather", backend=custom_managed)
+
+print("\n[11] Custom tool agent streaming...")
+result = custom_agent.start("What is the weather in Tokyo?", stream=True)
+
+# 12. Web search agent
+
+search_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Search Agent",
+        model="claude-haiku-4-5",
+        system="You are a research assistant. Search the web and summarize.",
+    ),
+)
+
+search_agent = Agent(name="searcher", backend=search_managed)
+
+print("\n[12] Web search agent streaming...")
+result = search_agent.start("Search the web for Python 3.13 new features and give me 3 bullet points", stream=True)
+
+# 13. Environment with pre-installed packages
+
+data_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Data Science Agent",
+        model="claude-haiku-4-5",
+        system="You are a data science assistant.",
+        packages={"pip": ["pandas", "numpy"]},
+    ),
+)
+
+data_agent = Agent(name="data-scientist", backend=data_managed)
+
+print("\n[13] Data science environment streaming...")
+result = data_agent.start("Use pandas to create a small DataFrame with 3 rows of sample data and print it", stream=True)
+
+# 14. Interrupt a session
+
+interrupt_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Interruptable Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful coding assistant.",
+    ),
+)
+
+interrupt_agent = Agent(name="interruptable", backend=interrupt_managed)
+
+print("\n[14] Interrupt demo...")
+result = interrupt_agent.start("Write a Python script that prints numbers 1 to 10", stream=True)
+interrupt_managed.interrupt()
+print("  [Interrupt sent]")
+
+# 15. Session resume — save IDs, create a fresh ManagedAgent, resume, and verify context
+
+print("\n[15] Session resume demo...")
+
+# Tell the original agent a memorable fact
+result = agent.start("Remember this: my favourite number is 42", stream=True)
+
+# Save IDs to disk
+ids = managed.save_ids()
+ids_file = pathlib.Path("managed_ids.json")
+ids_file.write_text(json.dumps(ids, indent=2))
+print(f"  Saved IDs to {ids_file}: {ids}")
+
+# Create a completely new ManagedAgent and resume the saved session
+resume_managed = ManagedAgent()
+resume_managed.resume_session(ids["session_id"])
+resume_agent = Agent(name="resumed", backend=resume_managed)
+
+# Ask about the fact — proves the session memory was preserved
+result = resume_agent.start("What is my favourite number?", stream=True)
+print(f"  Resumed session: {resume_managed.session_id}")
+
+# Clean up
+ids_file.unlink(missing_ok=True)
+
+# 16. Multi-package managers — pip + npm installed before agent starts
+
+print("\n[16] Multi-package managers...")
+
+multi_pkg_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Full Stack Agent",
+        model="claude-haiku-4-5",
+        system="You are a full stack developer.",
+        packages={
+            "pip": ["pandas", "numpy", "scikit-learn"],
+            "npm": ["express"],
+        },
+    ),
+)
+
+multi_pkg_agent = Agent(name="fullstack", backend=multi_pkg_managed)
+result = multi_pkg_agent.start(
+    "Verify pandas and express are installed: run python3 -c 'import pandas; print(pandas.__version__)' and node -e 'console.log(require.resolve(\"express\"))'",
+    stream=True,
+)
+
+# 17. Limited networking — restrict container to specific hosts
+
+print("\n[17] Limited networking...")
+
+limited_net_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="Restricted Network Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant with restricted network access.",
+        networking={
+            "type": "limited",
+            "allowed_hosts": ["api.github.com"],
+            "allow_mcp_servers": False,
+            "allow_package_managers": True,
+        },
+    ),
+)
+
+limited_net_agent = Agent(name="restricted", backend=limited_net_managed)
+result = limited_net_agent.start("Fetch https://api.github.com and report the status", stream=True)
+
+# 18. Environment management — list, retrieve, archive
+
+print("\n[18] Environment management...")
+
+env_client = managed._get_client()
+
+# List all environments
+environments = env_client.beta.environments.list()
+print(f"  Total environments: {len(environments.data)}")
+for env in environments.data[:3]:
+    print(f"    {env.id} | {env.name}")
+
+# Retrieve a specific environment
+env = env_client.beta.environments.retrieve(managed.environment_id)
+print(f"  Retrieved: {env.id} | {env.name}")
+
+# 19. MCP servers — configure agent with remote MCP tool servers
+
+print("\n[19] MCP servers...")
+
+mcp_managed = ManagedAgent(
+    config=ManagedConfig(
+        name="MCP Agent",
+        model="claude-haiku-4-5",
+        system="You are a helpful assistant with access to MCP servers.",
+        tools=[
+            {"type": "agent_toolset_20260401"},
+            {"type": "mcp_toolset", "mcp_server_name": "deepwiki"},
+        ],
+        mcp_servers=[
+            {
+                "type": "url",
+                "url": "https://mcp.deepwiki.com/sse",
+                "name": "deepwiki",
+            },
+        ],
+        networking={
+            "type": "limited",
+            "allow_mcp_servers": True,
+            "allow_package_managers": True,
+        },
+    ),
+)
+
+mcp_agent = Agent(name="mcp-agent", backend=mcp_managed)
+result = mcp_agent.start("Use the deepwiki MCP to read the wiki page for the anthropics/anthropic-cookbook github repo and give a one sentence summary", stream=True)
+
+# Final usage summary
+
+print("\n" + "=" * 60)
+print("FINAL USAGE SUMMARY")
+print("=" * 60)
+
+all_backends = [
+    ("Teaching Agent v2", managed),
+    ("Bash Only Agent", bash_managed),
+    ("No Web Agent", no_web_managed),
+    ("Weather Agent", custom_managed),
+    ("Search Agent", search_managed),
+    ("Data Science Agent", data_managed),
+    ("Interruptable Agent", interrupt_managed),
+    ("Resumed Session", resume_managed),
+    ("Full Stack Agent", multi_pkg_managed),
+    ("Restricted Network", limited_net_managed),
+    ("MCP Agent", mcp_managed),
+]
+
+total_input = 0
+total_output = 0
+
+for name, backend in all_backends:
+    info = backend.retrieve_session()
+    usage = info.get("usage", {})
+    inp = usage.get("input_tokens", backend.total_input_tokens)
+    out = usage.get("output_tokens", backend.total_output_tokens)
+    total_input += inp
+    total_output += out
+    print(f"  {name:30s} | in: {inp:6d} | out: {out:6d}")
+
+print(f"  {'TOTAL':30s} | in: {total_input:6d} | out: {total_output:6d}")
+print("=" * 60)

examples/python/managed-agents/basic.py

@@ -0,0 +1,5 @@
+from praisonai import Agent, ManagedAgent
+
+agent = Agent(name="teacher", backend=ManagedAgent())
+result = agent.start("Write a Python script that prints 'Hello from Managed Agents!' and run it")
+print(result)

examples/python/managed-agents/provider/all_providers.py

@@ -0,0 +1,117 @@
+"""All compute providers — comprehensive test across Local, Docker, E2B, and Modal.
+
+This example demonstrates local agent loops with various compute backends for tool sandboxing.
+Uses the new LocalAgent class to clearly indicate local execution with optional cloud compute.
+
+Requires:
+  - Docker running locally
+  - E2B_API_KEY set
+  - modal CLI configured (modal token set)
+"""
+import asyncio
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
+
+
+async def test_provider(name, compute, extra_provision_kwargs=None):
+    """Test a single compute provider end-to-end."""
+    print(f"\n{'='*60}")
+    print(f"  PROVIDER: {name}")
+    print(f"{'='*60}")
+
+    managed = LocalAgent(
+        compute=compute,
+        config=LocalAgentConfig(
+            model="gpt-4o-mini",
+            system="You are a helpful assistant. Be concise.",
+            name=f"{name}Agent",
+        ),
+    )
+    agent = Agent(name=f"{name}-test", backend=managed)
+
+    # 1. Provision
+    print(f"\n  [1] Provisioning {name}...")
+    provision_kwargs = extra_provision_kwargs or {}
+    info = await managed.provision_compute(**provision_kwargs)
+    print(f"      Instance: {info.instance_id}")
+    print(f"      Status:   {info.status}")
+
+    # 2. Execute command
+    print(f"\n  [2] Execute in {name}...")
+    result = await managed.execute_in_compute("python3 -c 'print(42 * 13)'")
+    stdout = result["stdout"].strip()
+    assert "546" in stdout, f"Expected 546, got: {stdout}"
+    print(f"      42 * 13 = {stdout} ✓")
+
+    # 3. Execute echo
+    result = await managed.execute_in_compute(f"echo 'Hello from {name}'")
+    print(f"      Echo: {result['stdout'].strip()}")
+
+    # 4. Agent LLM
+    print(f"\n  [3] Agent LLM via {name}...")
+    llm_result = agent.start("What is 9 * 8? Just the number.", stream=True)
+    print(f"      LLM result: {llm_result}")
+
+    # 5. Multi-turn
+    print("\n  [4] Multi-turn...")
+    llm_result = agent.start("Add 10 to that. Just the number.", stream=True)
+    print(f"      Follow-up: {llm_result}")
+
+    # 6. Usage
+    session = managed.retrieve_session()
+    usage = session["usage"]
+    print(f"\n  [5] Usage: in={usage['input_tokens']}, out={usage['output_tokens']}")
+
+    # 7. Shutdown
+    print(f"\n  [6] Shutdown {name}...")
+    await managed.shutdown_compute()
+    print("      Done ✓")
+
+    return {
+        "name": name,
+        "input_tokens": usage["input_tokens"],
+        "output_tokens": usage["output_tokens"],
+    }
+
+
+async def main():
+    results = []
+
+    # Docker
+    try:
+        r = await test_provider("Docker", "docker", {"image": "python:3.12-slim"})
+        results.append(r)
+    except Exception as e:
+        print(f"\n  Docker FAILED: {e}")
+
+    # E2B
+    try:
+        r = await test_provider("E2B", "e2b", {"idle_timeout_s": 120})
+        results.append(r)
+    except Exception as e:
+        print(f"\n  E2B FAILED: {e}")
+
+    # Modal
+    try:
+        r = await test_provider("Modal", "modal", {"idle_timeout_s": 120})
+        results.append(r)
+    except Exception as e:
+        print(f"\n  Modal FAILED: {e}")
+
+    # Summary
+    print(f"\n\n{'='*60}")
+    print("  SUMMARY")
+    print(f"{'='*60}")
+    total_in = 0
+    total_out = 0
+    for r in results:
+        total_in += r["input_tokens"]
+        total_out += r["output_tokens"]
+        print(f"  {r['name']:15s} | in: {r['input_tokens']:6d} | out: {r['output_tokens']:6d}")
+    print(f"  {'TOTAL':15s} | in: {total_in:6d} | out: {total_out:6d}")
+    print(f"{'='*60}")
+    print(f"  {len(results)}/{3} providers passed")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/managed-agents/provider/all_runtimes.py

@@ -0,0 +1,47 @@
+"""Run every managed-runtime example and report a summary.
+
+Executes the runtime_*.py files in this directory as subprocesses with a
+30s per-example timeout. Exits non-zero if any example fails.
+"""
+import os
+import subprocess
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+EXAMPLES = [
+    # ── LLM providers (where the LLM reasoning happens) ──
+    "runtime_anthropic.py",   # full loop in Anthropic cloud
+    "runtime_openai.py",      # LLM in OpenAI cloud
+    "runtime_gemini.py",      # LLM in Google cloud
+    "runtime_ollama.py",      # LLM on local/self-hosted Ollama
+    # ── Cloud/compute providers (where tool execution happens) ──
+    "runtime_e2b.py",         # tools sandboxed in E2B cloud VM
+    "runtime_modal.py",       # tools sandboxed in Modal serverless cloud
+    "runtime_fly.py",         # tools sandboxed on Fly.io Machines
+    "runtime_daytona.py",     # tools sandboxed in Daytona cloud workspace
+    "runtime_docker.py",      # tools sandboxed in local Docker container
+]
+
+results = []
+for name in EXAMPLES:
+    path = os.path.join(HERE, name)
+    start = time.time()
+    proc = subprocess.run(
+        [sys.executable, path],
+        capture_output=True, text=True, timeout=120,
+        env=os.environ.copy(),  # propagate API keys and PYTHONPATH
+    )
+    dur = time.time() - start
+    ok = proc.returncode == 0
+    results.append((name, ok, dur, proc.stdout.strip().splitlines()[-1] if proc.stdout.strip() else ""))
+    print(f"[{'OK' if ok else 'FAIL'}] {name:30s} {dur:.2f}s")
+    if not ok:
+        print(proc.stdout)
+        print(proc.stderr)
+
+print("\nSummary:")
+for name, ok, dur, tail in results:
+    print(f"  {'✓' if ok else '✗'} {name:30s} {dur:5.2f}s  {tail[:60]}")
+
+sys.exit(0 if all(r[1] for r in results) else 1)

examples/python/managed-agents/provider/daytona_compute.py

@@ -0,0 +1,55 @@
+"""Daytona compute provider — run agent tools inside a Daytona cloud sandbox.
+
+Requires: DAYTONA_API_KEY environment variable set.
+          Organization must have a default region configured in Daytona Dashboard.
+Install:  pip install daytona-sdk
+"""
+import asyncio
+from praisonai import Agent, ManagedAgent, LocalManagedConfig
+
+# ── 1. Create agent with Daytona compute ──
+managed = ManagedAgent(
+    provider="local",
+    compute="daytona",
+    config=LocalManagedConfig(
+        model="gpt-4o-mini",
+        system="You are a helpful coding assistant. Be concise.",
+        name="DaytonaAgent",
+    ),
+)
+
+agent = Agent(name="daytona-agent", backend=managed)
+
+print("[1] Agent created with Daytona compute")
+print(f"    Compute: {managed.compute_provider.provider_name}")
+
+# ── 2. Provision Daytona sandbox ──
+print("\n[2] Provisioning Daytona sandbox...")
+info = asyncio.run(managed.provision_compute(idle_timeout_s=120))
+print(f"    Instance: {info.instance_id}")
+print(f"    Status:   {info.status}")
+
+# ── 3. Execute commands ──
+print("\n[3] Executing commands in Daytona...")
+result = asyncio.run(managed.execute_in_compute("python3 -c 'import sys; print(sys.version)'"))
+print(f"    Python version: {result['stdout'].strip()}")
+print(f"    Exit code: {result['exit_code']}")
+
+result = asyncio.run(managed.execute_in_compute("echo 'Hello from Daytona!'"))
+print(f"    Echo: {result['stdout'].strip()}")
+
+# ── 4. Agent LLM execution ──
+print("\n[4] Agent LLM execution...")
+result = agent.start("What is 11 * 13? Just the number.", stream=True)
+print(f"    Result: {result}")
+
+# ── 5. Usage ──
+info = managed.retrieve_session()
+print(f"\n[5] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# ── 6. Shutdown ──
+print("\n[6] Shutting down Daytona sandbox...")
+asyncio.run(managed.shutdown_compute())
+print("    Shutdown complete.")
+
+print("\nDone!")

examples/python/managed-agents/provider/docker_compute.py

@@ -0,0 +1,67 @@
+"""Docker compute provider — run agent tools inside a Docker container.
+
+Requires: Docker running locally.
+"""
+import asyncio
+from praisonai import Agent, ManagedAgent, LocalManagedConfig
+
+# ── 1. Basic agent with Docker compute ──
+managed = ManagedAgent(
+    provider="local",
+    compute="docker",
+    config=LocalManagedConfig(
+        model="gpt-4o-mini",
+        system="You are a helpful coding assistant. Be concise.",
+        name="DockerAgent",
+    ),
+)
+
+agent = Agent(name="docker-agent", backend=managed)
+
+print("[1] Agent created with Docker compute")
+print(f"    Agent ID: {managed.agent_id or '(lazy — created on first call)'}")
+print(f"    Compute:  {managed.compute_provider.provider_name}")
+
+# ── 2. Provision Docker container ──
+print("\n[2] Provisioning Docker container...")
+info = asyncio.run(managed.provision_compute(image="python:3.12-slim"))
+print(f"    Instance: {info.instance_id}")
+print(f"    Status:   {info.status}")
+
+# ── 3. Execute commands inside the container ──
+print("\n[3] Executing commands in Docker...")
+result = asyncio.run(managed.execute_in_compute("python3 -c 'import sys; print(sys.version)'"))
+print(f"    Python version: {result['stdout'].strip()}")
+print(f"    Exit code: {result['exit_code']}")
+
+result = asyncio.run(managed.execute_in_compute("echo 'Hello from Docker!'"))
+print(f"    Echo: {result['stdout'].strip()}")
+
+# ── 4. Install packages in the container ──
+print("\n[4] Installing packages...")
+result = asyncio.run(managed.execute_in_compute("pip install requests -q"))
+print(f"    pip exit code: {result['exit_code']}")
+
+result = asyncio.run(managed.execute_in_compute("python3 -c 'import requests; print(requests.__version__)'"))
+print(f"    requests version: {result['stdout'].strip()}")
+
+# ── 5. Use agent with LLM (runs locally, compute is for tool sandboxing) ──
+print("\n[5] Agent LLM execution...")
+result = agent.start("What is 15 * 23? Just the number.", stream=True)
+print(f"    Result: {result}")
+
+# ── 6. Multi-turn ──
+print("\n[6] Multi-turn...")
+result = agent.start("Double that number.", stream=True)
+print(f"    Result: {result}")
+
+# ── 7. Usage tracking ──
+info = managed.retrieve_session()
+print(f"\n[7] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# ── 8. Shutdown Docker container ──
+print("\n[8] Shutting down Docker container...")
+asyncio.run(managed.shutdown_compute())
+print("    Shutdown complete.")
+
+print("\nDone!")

examples/python/managed-agents/provider/e2b_compute.py

@@ -0,0 +1,66 @@
+"""E2B compute provider — run agent tools inside an E2B cloud sandbox.
+
+Requires: E2B_API_KEY environment variable set.
+Install:  pip install e2b
+"""
+import asyncio
+from praisonai import Agent, ManagedAgent, LocalManagedConfig
+
+# ── 1. Create agent with E2B compute ──
+managed = ManagedAgent(
+    provider="local",
+    compute="e2b",
+    config=LocalManagedConfig(
+        model="gpt-4o-mini",
+        system="You are a helpful coding assistant. Be concise.",
+        name="E2BAgent",
+    ),
+)
+
+agent = Agent(name="e2b-agent", backend=managed)
+
+print("[1] Agent created with E2B compute")
+print(f"    Compute: {managed.compute_provider.provider_name}")
+
+# ── 2. Provision E2B sandbox ──
+print("\n[2] Provisioning E2B sandbox...")
+info = asyncio.run(managed.provision_compute(idle_timeout_s=120))
+print(f"    Instance: {info.instance_id}")
+print(f"    Status:   {info.status}")
+
+# ── 3. Execute commands in the sandbox ──
+print("\n[3] Executing commands in E2B...")
+result = asyncio.run(managed.execute_in_compute("python3 -c 'import sys; print(sys.version)'"))
+print(f"    Python version: {result['stdout'].strip()}")
+print(f"    Exit code: {result['exit_code']}")
+
+result = asyncio.run(managed.execute_in_compute("echo 'Hello from E2B!'"))
+print(f"    Echo: {result['stdout'].strip()}")
+
+# ── 4. Run a Python script ──
+print("\n[4] Running Python script...")
+result = asyncio.run(managed.execute_in_compute(
+    "python3 -c 'for i in range(5): print(f\"Line {i}\")'"
+))
+print(f"    Output:\n{result['stdout']}")
+
+# ── 5. Agent LLM execution ──
+print("[5] Agent LLM execution...")
+result = agent.start("What is the square root of 144? Just the number.", stream=True)
+print(f"    Result: {result}")
+
+# ── 6. Multi-turn ──
+print("\n[6] Multi-turn...")
+result = agent.start("Now cube that number.", stream=True)
+print(f"    Result: {result}")
+
+# ── 7. Usage ──
+info = managed.retrieve_session()
+print(f"\n[7] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# ── 8. Shutdown ──
+print("\n[8] Shutting down E2B sandbox...")
+asyncio.run(managed.shutdown_compute())
+print("    Shutdown complete.")
+
+print("\nDone!")