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

Co-authored-by: Dhivya-Bharathy <[email protected]>
fix: resolve Gemini reviewer issues - remove redundant arguments and fix temp file pollution
2026-11-08 01:08:39 -10:00 · 2026-06-08 07:47:16 +01:00 · 2026-06-05 10:18:45 +00:00 · 2026-06-05 15:37:37 +05:30 · 2026-06-05 11:26:13 +05:30 · 2026-06-04 16:30:02 +05:30
379 changed files with 27081 additions and 7800 deletions
@@ -37,6 +37,14 @@ 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
@@ -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
@@ -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
@@ -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
          
@@ -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 != ''
@@ -382,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)

@@ -1,34 +0,0 @@
-# Security release checklist (maintainer)
-
-After merging security PRs [#1684](https://github.com/MervinPraison/PraisonAI/pull/1684) and [#1685](https://github.com/MervinPraison/PraisonAI/pull/1685):
-
-## 1. Publish PyPI (requires `PYPI_TOKEN`)
-
-```bash
-cd src/praisonai-agents
-export PYPI_TOKEN=...
-praisonai publish pypi
-
-cd ../praisonai
-python scripts/bump_and_release.py <WRAPPER_VERSION> --agents <AGENTS_VERSION> --wait
-```
-
-## 2. Publish GitHub security advisories
-
-Set versions to match PyPI, then:
-
-```bash
-AGENTS_VERSION=1.6.40 WRAPPER_VERSION=4.6.40 ./scripts/security_publish_advisories.sh
-```
-
-Add reporter `credits` per advisory via `gh api` before publishing if not already set.
-
-## 3. Verify
-
-```bash
-pip index versions praisonaiagents | head -1
-pip index versions praisonai | head -1
-gh api repos/MervinPraison/PraisonAI/security-advisories --jq '.[] | "\(.ghsa_id) \(.state) \(.cve_id // "pending")"'
-```
-
-Resources: https://github.com/MervinPraison/PraisonAI · https://docs.praison.ai · https://praison.ai
@@ -1,26 +0,0 @@
-# Security advisory triage (maintainer)
-
-| GHSA | Status after batch 1+2 | Notes |
-|------|------------------------|-------|
-| GHSA-4mr5-g6f9-cfrh | fixed batch 1 | Sandbox AST |
-| GHSA-5c6w-wwfq-7qqm | fixed batch 1 | spider_tools SSRF |
-| GHSA-9cr9-25q5-8prj | fixed batch 1 | MCP yaml paths |
-| GHSA-86qc-r5v2-v6x6 | fixed batch 1 | call server auth |
-| GHSA-hvhp-v2gc-268q | fixed batch 1 | write_file cwd |
-| GHSA-5cxw-77wg-jrf3 | fixed batch 1 | @url mentions |
-| GHSA-xp85-6wwf-r67c | fixed batch 1 | GHA branch quote |
-| GHSA-3qg8-5g3r-79v5 | fixed batch 1+2 | JWT + issue guard |
-| GHSA-xwq8, 7p8g, w388, g8rr | fixed batch 1 | platform RBAC/IDOR partial |
-| GHSA-943m, 5jx9, 4x6r, 27p4, cp4f | fixed batch 2 | platform IDOR completion |
-| GHSA-vg22-4gmj-prxw | fixed batch 2 | example eval hardening |
-| GHSA-8444-4fhq-fxpq | already-fixed | APIConfig.auth_enabled default True |
-| GHSA-78r8-wwqv-r299 | already-fixed | load_user_module gate |
-| GHSA-gv23-xxxx-xxxx, GHSA-h8q5-cp56-rr65, GHSA-6h6v-xxxx-xxxx, GHSA-h37g-4h4p-9x97 | fixed batch 3 | service-layer workspace_id on get/update/delete |
-| GHSA-c2m8-xxxx-xxxx, GHSA-8g2p-xxxx-xxxx | fixed batch 3 | only owner assigns admin/owner |
-| GHSA-h8q5-cp56-rr65 | fixed batch 3 | bind default 127.0.0.1 (+ PLATFORM_HOST) |
-| GHSA-6xj3-927j-6pqw | not-applicable | Open WebUI path; not in this repo |
-| GHSA-gmjg, 9q28 | published | prior release |
-
-**Code fixed on main; GHSA state still triage until PyPI publish + advisory publish.**
-
-Resources: https://github.com/MervinPraison/PraisonAI · https://docs.praison.ai · https://praison.ai
@@ -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,6 +172,7 @@ 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>
@@ -183,6 +185,7 @@ Methods:
 * <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>
@@ -476,8 +479,10 @@ Methods:
 * <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>
@@ -486,6 +491,7 @@ Methods:
 * <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>
@@ -601,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:
@@ -755,7 +768,7 @@ Methods:

 Types:
 ```python
-from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, 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
@@ -857,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>
@@ -890,11 +905,24 @@ Methods:
 * <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>
@@ -1052,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>
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=4.6.40" \
+    "praisonai>=4.6.52" \
    "praisonai[chat]" \
    "embedchain[github,youtube]"

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

@@ -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
@@ -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)
@@ -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:
@@ -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__":
@@ -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
@@ -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)
@@ -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
@@ -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)
@@ -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
@@ -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(
@@ -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",
        )
        
@@ -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",
        )
        
@@ -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
        )
        
@@ -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:")
@@ -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",
        )
        
@@ -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",
        )
        
@@ -17,8 +17,10 @@ from praisonaiagents import Agent
 agent = Agent(
    name="CockroachDB Agent",
    instructions="You are a helpful assistant.",
-    db={"database_url": os.getenv("COCKROACHDB_URL")},
-    session_id="crdb-demo-session",
+    memory={
+        "session_id": "crdb-demo-session",
+        "db": {"database_url": os.getenv("COCKROACHDB_URL")},
+    },
 )

 result = agent.start("What is distributed SQL? Explain in 2 sentences.")
@@ -18,8 +18,10 @@ from praisonaiagents import Agent
 agent = Agent(
    name="Neon Agent",
    instructions="You are a helpful assistant.",
-    db={"database_url": os.getenv("NEON_DATABASE_URL")},
-    session_id="neon-demo-session",
+    memory={
+        "session_id": "neon-demo-session",
+        "db": {"database_url": os.getenv("NEON_DATABASE_URL")},
+    },
 )

 # Option 2: Direct URL
@@ -20,8 +20,10 @@ from praisonaiagents import Agent
 agent = Agent(
    name="Supabase Agent",
    instructions="You are a helpful assistant.",
-    db={"database_url": os.getenv("SUPABASE_DATABASE_URL")},
-    session_id="supabase-demo-session",
+    memory={
+        "session_id": "supabase-demo-session",
+        "db": {"database_url": os.getenv("SUPABASE_DATABASE_URL")},
+    },
 )

 result = agent.start("What is Supabase? Explain in 2 sentences.")
@@ -18,11 +18,13 @@ from praisonaiagents import Agent
 agent = Agent(
    name="Turso Agent",
    instructions="You are a helpful assistant.",
-    db={
-        "database_url": os.getenv("TURSO_DATABASE_URL"),
-        "auth_token": os.getenv("TURSO_AUTH_TOKEN"),
+    memory={
+        "session_id": "turso-demo-session",
+        "db": {
+            "database_url": os.getenv("TURSO_DATABASE_URL"),
+            "auth_token": os.getenv("TURSO_AUTH_TOKEN"),
+        },
    },
-    session_id="turso-demo-session",
 )

 result = agent.start("What is edge computing? Explain in 2 sentences.")
@@ -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)}"
@@ -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}"
    
@@ -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__":
@@ -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__":
@@ -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",
+        },
    }
 )

@@ -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}")
@@ -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"

@@ -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)
@@ -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()
@@ -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
@@ -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
@@ -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()}")
@@ -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,
    
    
@@ -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)
@@ -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"
    )
    
@@ -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()
@@ -16,7 +16,7 @@ agents = AgentTeam(
    agents=[agent],
    tasks=[task],
    process="workflow",
-    max_iter=30
+    execution={"max_iter": 30},
 )

 agents.start()
@@ -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
@@ -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)}"
@@ -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()
@@ -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
@@ -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"},
        }
    )

@@ -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(
@@ -40,7 +40,7 @@ agent = Agent(
        "execute_command"
    ],
    memory=True,
-    web_search=True,
+    web=True,
    auto_approve_tools=True,
 )

@@ -36,10 +36,18 @@ def calculate(expression: str) -> dict:
        expression: Math expression (e.g., "2 + 2 * 3")
    """
    try:
-        allowed = set("0123456789+-*/.() ")
-        if not all(c in allowed for c in expression):
-            return {"error": "Invalid characters"}
-        return {"expression": expression, "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)}")
+        return {"expression": expression, "result": _ev(ast.parse(expression, mode="eval"))}
    except Exception as e:
        return {"error": str(e)}

@@ -47,12 +47,18 @@ def calculate(expression: str) -> Dict[str, Any]:
        The result of the calculation
    """
    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)  # Use safer alternative in production
+        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 {"expression": expression, "result": result}
    except Exception as e:
        return {"error": str(e)}
@@ -49,13 +49,18 @@ def calculate(expression: str) -> Dict[str, Any]:
        The result of the calculation
    """
    try:
-        # Safe evaluation of mathematical expressions
-        # In production, use a proper math parser
-        allowed_chars = set("0123456789+-*/.() ")
-        if not all(c in allowed_chars for c in expression):
-            return {"error": "Invalid characters in expression"}
-        
-        result = eval(expression)  # Note: Use safer alternative in production
+        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 {"expression": expression, "result": result}
    except Exception as e:
        return {"error": str(e)}
@@ -12,8 +12,8 @@ print("=== Advanced Graph Memory Integration Example ===\n")

 # Configure simple graph memory
 memory_config = {
-    "provider": "mem0",
    "config": {
+        "provider": "mem0",
        "vector_store": {
            "provider": "chroma",
            "config": {
@@ -60,8 +60,8 @@ query_task = Task(
 agents_system = AgentTeam(
    agents=[knowledge_agent],
    tasks=[build_task, query_task],
-    memory=True,
-    memory=memory_config, output="verbose"
+    memory=memory_config,
+    output="verbose",
 )

 print("Starting graph memory demonstration...")
@@ -12,8 +12,8 @@ print("=== Advanced Memory Search and Optimization Example ===\n")

 # Configure optimized memory settings
 memory_config = {
-    "provider": "mem0",
    "config": {
+        "provider": "mem0",
        "vector_store": {
            "provider": "chroma",
            "config": {
@@ -61,8 +61,8 @@ search_task = Task(
 agents_system = AgentTeam(
    agents=[research_agent],
    tasks=[build_memory_task, search_task],
-    memory=True,
-    memory=memory_config, output="verbose"
+    memory=memory_config,
+    output="verbose",
 )

 print("Starting memory search optimization demonstration...")
@@ -86,13 +86,13 @@ def main():
        agents=[researcher, retriever],
        tasks=[store_task, retrieve_task],
        memory={
-            "provider": "rag",
            "embedder": {
                "provider": "gemini",
                "config": {
                    "model": "text-embedding-004",
                }
-            }
+            },
+            "config": {"provider": "sqlite"},
        }
    )
    
@@ -152,8 +152,7 @@ def main():
    agents_system = AgentTeam(
        agents=[researcher],
        tasks=[build_knowledge_task, query_knowledge_task, expand_knowledge_task],
-        memory=True,
-        memory=memory_config
+        memory=memory_config,
    )
    
    print("\n🚀 Starting graph memory demonstration...")
@@ -30,7 +30,7 @@ def main():
    try:
        # Create memory instance
        memory = Memory(config={
-            "provider": "rag",
+            "backend": "sqlite",
            "use_embedding": False,
            "agent_name": "demo_agent",  # Used in trace events
        })
@@ -32,9 +32,8 @@ def init_agent():
    return Agent(
        name="Knowledge Agent",
        instructions="You answer questions based on the provided knowledge.",
-        knowledge=["kag-research-paper.pdf"],
-        knowledge=config,
-        user_id="user1",
+        knowledge={**config, "sources": ["kag-research-paper.pdf"]},
+        memory={"user_id": "user1"},
        llm="deepseek-r1"
    )

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

@@ -31,10 +31,9 @@ llm_config = {
 agent = Agent(
    instructions="You are a helpful Assistant specialized in scientific explanations. "
                "Provide clear, accurate, and engaging responses.",
-    llm=llm_config,                  # Pass the detailed configuration
-    # Enable detailed output
-    markdown=True,                   # Format responses in markdown
-    reflection=True               # Enable self-reflection
+    llm=llm_config,
+    output={"markdown": True},
+    reflection=True,
 )

 # Test the agent
@@ -189,8 +189,8 @@ def main():
    business_system = AgentTeam(
        agents=[data_manager, knowledge_curator, business_analyst, customer_service],
        tasks=business_tasks,
-        memory=True,
-        memory=mongodb_memory_config, output="verbose"
+        memory=mongodb_memory_config,
+        output="verbose",
    )
    
    # Execute the comprehensive business pipeline
@@ -55,8 +55,10 @@ def main():
        retrieve information from a comprehensive MongoDB knowledge base. You excel 
        at finding relevant information, synthesizing knowledge from multiple sources, 
        and providing accurate, context-aware responses.""",
-        knowledge=mongodb_knowledge_config,
-        knowledge=[os.path.join(os.path.dirname(__file__), "llms.md")],
+        knowledge={
+            **mongodb_knowledge_config,
+            "sources": [os.path.join(os.path.dirname(__file__), "llms.md")],
+        },
        memory=True,
        llm="gpt-4o-mini"
    )
@@ -28,8 +28,8 @@ if not os.environ.get("OPENAI_API_KEY"):
 def main():
    # MongoDB memory configuration
    mongodb_memory_config = {
-        "provider": "mongodb",
        "config": {
+            "provider": "mongodb",
            "connection_string": "mongodb://localhost:27017/",  # Replace with your MongoDB connection string
            "database": "praisonai_memory",
            "use_vector_search": True,  # Enable Atlas Vector Search (requires MongoDB Atlas)
@@ -93,8 +93,8 @@ def main():
    research_system = AgentTeam(
        agents=[research_agent],
        tasks=research_tasks,
-        memory=True,
-        memory=mongodb_memory_config, output="verbose"
+        memory=mongodb_memory_config,
+        output="verbose",
    )
    
    # Execute the research pipeline
@@ -50,7 +50,7 @@ agent = Agent(
    name="TechSupport",
    instructions="You are a technical support assistant.",
    knowledge=[sample_doc],
-    user_id="comparison_user",
+    memory={"user_id": "comparison_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -12,6 +12,7 @@ Environment:
 """

 import os
+import tempfile
 from praisonaiagents import Agent, AutoRagAgent

 # Ensure API key is set
@@ -20,8 +21,8 @@ if not os.environ.get("OPENAI_API_KEY"):
    exit(1)

 # Create a sample document for testing
-sample_doc = "/tmp/sample_doc.txt"
-with open(sample_doc, "w") as f:
+sample_doc = os.path.join(tempfile.gettempdir(), "sample_doc.txt")
+with open(sample_doc, "w", encoding="utf-8") as f:
    f.write("""
 PraisonAI Framework Documentation

@@ -44,7 +45,7 @@ agent = Agent(
    name="DocBot",
    instructions="You are a helpful documentation assistant. Answer questions based on the provided context.",
    knowledge=[sample_doc],
-    user_id="example_user",  # Required for RAG retrieval
+    memory={"user_id": "example_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -38,7 +38,7 @@ agent = Agent(
    name="PolicyBot",
    instructions="You are a customer service assistant.",
    knowledge=[sample_doc],
-    user_id="policy_user",
+    memory={"user_id": "policy_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -44,7 +44,7 @@ agent = Agent(
    name="MLExpert",
    instructions="You are a machine learning expert. Answer questions based on the provided context.",
    knowledge=[sample_doc],
-    user_id="rag_user",
+    memory={"user_id": "rag_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -59,7 +59,7 @@ agent = Agent(
    name="APIDocBot",
    instructions="You are an API documentation assistant.",
    knowledge=[sample_doc],
-    user_id="hybrid_user",
+    memory={"user_id": "hybrid_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -44,7 +44,7 @@ agent = Agent(
    name="ResearchBot",
    instructions="You are a research assistant. Always cite your sources.",
    knowledge=[doc1, doc2],
-    user_id="citation_user",
+    memory={"user_id": "citation_user"},
    llm="openai/gpt-4o-mini",
    output="minimal",
 )
@@ -28,7 +28,7 @@ def example_basic_persistence():
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant. Be very brief.",
-        session_id=session_id,
+        memory={"session_id": session_id},
        output="minimal",
    )
    
@@ -59,7 +59,7 @@ def example_session_restoration():
    agent1 = Agent(
        name="MemoryBot",
        instructions="You are a helpful assistant. Be very brief.",
-        session_id=session_id,
+        memory={"session_id": session_id},
        output="minimal",
    )
    
@@ -72,7 +72,7 @@ def example_session_restoration():
    agent2 = Agent(
        name="MemoryBot",
        instructions="You are a helpful assistant. Be very brief.",
-        session_id=session_id,
+        memory={"session_id": session_id},
        output="minimal",
    )
    
@@ -172,7 +172,7 @@ print("="*70)
 # Create sessions for different users working on the same project
 reviewer_session = Session(
    session_id="peer_review_001",
-    user_id="user_reviewer_01",  # Different user
+    user_id="user_reviewer_01",
    storage_path=session_dir
 )

@@ -14,13 +14,12 @@ def main():
    
    # Initialize memory with quality-based configuration
    memory_config = {
-        "provider": "rag",
-        "use_embedding": True,
-        "rag_db_path": "quality_memory_db"
+        "backend": "sqlite",
+        "user_id": "quality_demo_user",
    }
    
    memory = Memory(config=memory_config, verbose=5)
-    print(f"📦 Initialized memory system with provider: {memory_config['provider']}")
+    print(f"📦 Initialized memory system with backend: {memory_config['backend']}")
    
    # Create agent with memory
    agent = Agent(
@@ -28,7 +27,6 @@ def main():
        role="Information Quality Specialist",
        instructions="Store and retrieve information with quality assessment",
        memory=memory,
-        user_id="quality_demo_user"
    )
    
    print(f"🤖 Created agent: {agent.name}")
@@ -15,7 +15,7 @@ def main():
    # Create a session with persistent storage
    session = Session(
        session_id="demo_chat_001",
-        user_id="demo_user"
+        user_id="demo_user",
    )
    
    print(f"📝 Created session: {session}")
@@ -88,9 +88,8 @@ def main():
    workflow = AgentTeam(
        agents=[researcher, analyzer, writer],
        tasks=[research_task, analysis_task, report_task],
-        memory=True,
+        memory={"user_id": "research_project_001"},
        process="workflow",
-        user_id="research_project_001",
    )
    
    print(f"🤖 Created workflow with {len(workflow.agents)} agents and {len(workflow.tasks)} tasks")
@@ -14,7 +14,7 @@ def main():
        goal="Find information about a topic",
        backstory="You are an expert researcher who finds comprehensive information.",
        llm="gpt-4o-mini",  # Use a cost-effective model for examples
-        metrics=True  # 🎯 SIMPLIFIED: Just add this parameter!
+        output={"metrics": True}  # Token metrics via consolidated output config
    )
    
    # Create a simple task
@@ -14,7 +14,7 @@ def main():
        goal="Analyze data and provide insights",
        backstory="You are an experienced data analyst with expertise in market research.",
        llm="gpt-4o-mini",
-        metrics=True  # 🎯 Enable metrics tracking
+        output={"metrics": True}
    )
    
    writer_agent = Agent(
@@ -23,7 +23,7 @@ def main():
        goal="Create well-structured content",
        backstory="You are a skilled technical writer who creates clear, engaging content.",
        llm="gpt-4o-mini",
-        metrics=True  # 🎯 Enable metrics tracking
+        output={"metrics": True}
    )
    
    # Create multiple tasks
@@ -14,7 +14,7 @@ def main():
        goal="Conduct comprehensive market research",
        backstory="You are a seasoned market researcher with 10+ years of experience.",
        llm="gpt-4o-mini",
-        metrics=True  # 🎯 Enable automatic metrics tracking
+        output={"metrics": True}
    )
    
    strategy_agent = Agent(
@@ -23,7 +23,7 @@ def main():
        goal="Develop actionable business strategies",
        backstory="You are a strategic consultant who translates research into business plans.",
        llm="gpt-4o-mini",
-        metrics=True  # 🎯 Enable automatic metrics tracking
+        output={"metrics": True}
    )
    
    # Create tasks that will generate substantial token usage
@@ -22,7 +22,8 @@ rag_agent = Agent(
    
    You can use the internet_search function to search the web when needed.""",
    llm="gpt-4o",
-    markdown=True)
+    output={"markdown": True},
+)

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

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

 # Main Execution Workflow
@@ -5,7 +5,7 @@ Demonstrates using should_run to conditionally execute agent steps
 based on input or previous results.
 """

-from praisonaiagents import Agent, Workflow, Task
+from praisonaiagents import Agent, AgentFlow, Task

 # Condition functions
 def is_technical(ctx) -> bool:
@@ -53,7 +53,7 @@ workflow = AgentFlow(
        # Step 4: Function - formats output
        format_output
    ],
-    default_llm="gpt-4o-mini"  # Used for action-based steps
+    llm="gpt-4o-mini",  # Used for action-based steps
 )

 if __name__ == "__main__":
@@ -207,7 +207,7 @@ def api_augmented_rag():
        instructions="""You are a financial assistant with access to market APIs.
        Provide accurate financial information and context.
        Always note that prices are subject to change.""",
-        user_id="api_demo"
+        memory={"user_id": "api_demo"},
    )
    
    queries = [
@@ -51,13 +51,15 @@ print("=" * 60)
 agent = Agent(
    name="Knowledge Agent",
    instructions="You are a helpful assistant that answers questions based on the provided knowledge. Be concise.",
-    knowledge=[".praison/test_docs/overview.txt"],
-    retrieval_config={
-        "policy": "always",      # Always retrieve for this demo
-        "top_k": 3,              # Get top 3 chunks
-        "citations": True,       # Include citations
-        "max_context_tokens": 2000,
-    }
+    knowledge={
+        "sources": [".praison/test_docs/overview.txt"],
+        "config": {
+            "policy": "always",
+            "top_k": 3,
+            "citations": True,
+            "max_context_tokens": 2000,
+        },
+    },
 )

 # Test 1: Basic chat with retrieval
@@ -60,7 +60,7 @@ print("=" * 50)
 agent_with_discovery = Agent(
    name="Multi-Skill Agent",
    instructions="You are a versatile assistant with multiple skills.",
-    skills_dirs=["./"],  # Scan current directory for skill subdirectories
+    skills=["./"],  # Scan current directory for skill subdirectories
 )

 if agent_with_discovery.skill_manager:
@@ -0,0 +1,222 @@
+# Multi-Channel Bot Deployment Guide
+
+This guide explains how to set up multiple bots on the same platform (e.g., multiple Telegram bots) for different roles using PraisonAI, similar to Hermes-style AI workforces.
+
+## Overview
+
+PraisonAI supports running multiple bots on the same platform, each routing to different agents with specialized knowledge and capabilities. This is useful for:
+
+- **Role-based bots**: `@company_cfo_bot`, `@company_ops_bot`, `@company_content_bot`
+- **Department-specific agents**: Each with different knowledge brains and tool access
+- **Workflow separation**: Different bots handle different types of requests
+
+## Quick Start with Onboard Wizard
+
+The easiest way to set up multiple channels is using the onboard wizard:
+
+```bash
+praisonai onboard
+```
+
+The wizard now supports:
+1. **Multi-channel setup**: Add multiple bots for the same platform
+2. **Role-based naming**: Automatically generates `TELEGRAM_<ROLE>_BOT_TOKEN` environment variables
+3. **Agent routing**: Each channel routes to a different agent
+
+### Onboard Wizard Flow
+
+1. **Choose platform**: Start with your first platform (e.g., telegram)
+2. **Add more channels**: Wizard asks "Add another bot channel?"
+3. **Specify role**: Enter role name (e.g., "cfo", "ops", "content")
+4. **Configure tokens**: Each channel gets its own environment variable
+5. **Test connections**: Wizard tests each bot separately
+
+## Environment Variable Convention
+
+For multiple bots on the same platform, use this naming convention:
+
+| Channel | Environment Variable | Bot Purpose |
+|---------|---------------------|-------------|
+| `telegram_cfo` | `TELEGRAM_CFO_BOT_TOKEN` | CFO-related tasks |
+| `telegram_ops` | `TELEGRAM_OPS_BOT_TOKEN` | Operations tasks |
+| `telegram_content` | `TELEGRAM_CONTENT_BOT_TOKEN` | Content creation |
+| `telegram_support` | `TELEGRAM_SUPPORT_BOT_TOKEN` | Customer support |
+
+### Setting Up Tokens
+
+1. **Create bots in @BotFather**:
+   ```text
+   /newbot
+   Bot name: Company CFO Bot
+   Username: @company_cfo_bot
+   -> Copy token
+   
+   /newbot
+   Bot name: Company Ops Bot
+   Username: @company_ops_bot
+   -> Copy token
+   ```
+
+2. **Set environment variables**:
+   ```bash
+   export TELEGRAM_CFO_BOT_TOKEN="123456789:ABC..."
+   export TELEGRAM_OPS_BOT_TOKEN="987654321:DEF..."
+   export TELEGRAM_CONTENT_BOT_TOKEN="456789123:GHI..."
+   ```
+
+3. **Or use `~/.praisonai/.env`**:
+   ```env
+   TELEGRAM_CFO_BOT_TOKEN=123456789:ABC...
+   TELEGRAM_OPS_BOT_TOKEN=987654321:DEF...
+   TELEGRAM_CONTENT_BOT_TOKEN=456789123:GHI...
+   TELEGRAM_ALLOWED_USERS=123456789,987654321
+   ```
+
+## Example Configuration
+
+See `multi-telegram-hermes-workforce.yaml` for a complete example.
+
+### Key Features
+
+1. **Multiple Channels**:
+   ```yaml
+   channels:
+     telegram_cfo:
+       platform: telegram
+       token: ${TELEGRAM_CFO_BOT_TOKEN}
+       routes:
+         default: cfo
+     
+     telegram_ops:
+       platform: telegram
+       token: ${TELEGRAM_OPS_BOT_TOKEN}
+       routes:
+         default: ops
+   ```
+
+2. **Specialized Agents**:
+   ```yaml
+   agents:
+     cfo:
+       instructions: "You are a CFO agent. Help with financial analysis..."
+       model: gpt-4o-mini
+     
+     ops:
+       instructions: "You are an ops agent. Help with system monitoring..."
+       model: gpt-4o-mini
+   ```
+
+## Validation with Doctor
+
+Use the doctor command to validate your multi-channel setup:
+
+```bash
+praisonai doctor
+```
+
+The doctor checks for:
+- ✅ **Unique tokens**: Each channel uses a different bot token
+- ✅ **Naming convention**: Follows `PLATFORM_ROLE_BOT_TOKEN` pattern  
+- ✅ **Missing tokens**: All referenced environment variables are set
+- ❌ **Duplicate tokens**: Same token used by multiple channels (fails)
+
+## Deployment
+
+### Start Gateway
+
+```bash
+# Start the multi-bot gateway
+praisonai gateway start --config multi-telegram-hermes-workforce.yaml
+
+# Or install as daemon
+praisonai onboard  # Wizard installs daemon automatically
+praisonai gateway status
+```
+
+### Verify Setup
+
+1. **Check health**: `curl http://127.0.0.1:8765/health`
+2. **View dashboard**: `praisonai claw` → http://127.0.0.1:8082
+3. **Test bots**: Send messages to each bot to verify routing
+
+## Common Patterns
+
+### Basic Multi-Role Setup
+```yaml
+# Single platform, multiple roles
+channels:
+  telegram_support:
+    token: ${TELEGRAM_SUPPORT_BOT_TOKEN}
+    routes:
+      default: support_agent
+  
+  telegram_sales:
+    token: ${TELEGRAM_SALES_BOT_TOKEN}
+    routes:
+      default: sales_agent
+```
+
+### Cross-Platform Workforce
+```yaml
+# Multiple platforms, multiple roles
+channels:
+  telegram_cfo:
+    platform: telegram
+    token: ${TELEGRAM_CFO_BOT_TOKEN}
+    routes:
+      default: cfo
+  
+  discord_ops:
+    platform: discord
+    token: ${DISCORD_OPS_BOT_TOKEN}
+    routes:
+      default: ops
+  
+  slack_content:
+    platform: slack
+    token: ${SLACK_CONTENT_BOT_TOKEN}
+    routes:
+      default: content
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Token is used by multiple channels"**
+   - Each bot needs its own unique token from @BotFather
+   - Check environment variables for duplicates
+
+2. **"Channel skipped - no token"**
+   - Set the environment variable: `export TELEGRAM_CFO_BOT_TOKEN="..."`
+   - Or update `~/.praisonai/.env`
+
+3. **"Bot not responding"**
+   - Verify token is correct: `praisonai doctor`
+   - Check bot is not already running elsewhere
+   - Ensure allowlist includes your user ID
+
+### Debugging Commands
+
+```bash
+# Check configuration
+praisonai doctor
+
+# View logs
+praisonai gateway logs
+
+# Test connection
+curl -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
+     http://127.0.0.1:8765/info
+```
+
+## Migration from Single-Bot Setup
+
+If you currently have a single bot setup, you can add more channels:
+
+1. **Run onboard wizard**: `praisonai onboard`
+2. **Add new channels**: Wizard will preserve existing setup
+3. **Update configuration**: New channels added to existing `bot.yaml`
+4. **Restart gateway**: `praisonai gateway restart`
+
+The wizard preserves backward compatibility with single-bot configurations.
@@ -0,0 +1,19 @@
+# A2UI canvas agent — YAML example
+#
+# Usage:
+#   pip install praisonaiagents[a2ui]
+#   praisonai agent run --file a2ui-canvas.yaml --prompt "Show a welcome card"
+#
+# For live A2UI rendering, use PraisonAIUI (AG-UI / surfaces):
+#   pip install praisonaiui
+#   See examples/python/a2ui/send_surface.py and PraisonAIUI example 29.
+
+agent:
+  name: "ui-assistant"
+  instructions: |
+    You are a helpful assistant. When the user asks for UI elements
+    (buttons, cards, forms), call send_a2ui_messages with valid A2UI v0.9 JSON.
+    Use surface id "main" unless told otherwise.
+  llm: gpt-4o-mini
+  tools:
+    - send_a2ui_messages
@@ -0,0 +1,40 @@
+# Example: Agent with MCP Tool Integration
+#
+# This example shows how to configure an agent with MCP (Model Context Protocol)
+# servers for additional tool capabilities.
+#
+# Usage:
+#   praisonai workflow run --file examples/yaml/agent-with-mcp.yaml
+
+agent:
+  name: mcp_assistant
+  instructions: |
+    You are a helpful assistant with access to filesystem and time tools.
+    Use the MCP tools when needed to help users with file operations or time queries.
+  llm: gpt-4o-mini
+
+# MCP server configuration
+mcp:
+  servers:
+    filesystem:
+      # Filesystem access for the agent
+      command: npx
+      args:
+        - "-y"
+        - "@modelcontextprotocol/server-filesystem"
+        - "."
+      env: {}
+      enabled: true
+    
+    time:
+      # Time and date utilities
+      command: npx
+      args:
+        - "-y" 
+        - "@modelcontextprotocol/server-time"
+      env: {}
+      enabled: true
+
+# NOTE: Per-server tool filtering (tools.include/exclude) is not yet supported
+# by the MCP server config schema. Tool filtering should be applied after
+# calling mcp.get_tools() in your application code.
@@ -0,0 +1,66 @@
+# Multi-Telegram Channel Hermes Workforce Example
+# Generated by `praisonai onboard` with multi-channel support
+# Start with: praisonai gateway start --config multi-telegram-hermes-workforce.yaml
+
+gateway:
+  host: "127.0.0.1"
+  port: 8765
+
+# Legacy single-agent block for backward compatibility
+agent:
+  name: "assistant"
+  instructions: "You are a helpful AI assistant. You can search the web, manage schedules, and remember past conversations. Use your tools proactively."
+  model: "gpt-4o-mini"
+
+# Multi-agent workforce with different specialized roles
+agents:
+  cfo:
+    instructions: "You are a CFO agent. You are a helpful AI assistant. Use your tools proactively to help with CFO-related tasks like financial analysis, budget planning, and cost optimization."
+    model: gpt-4o-mini
+    memory: false
+
+  ops:
+    instructions: "You are an ops agent. You are a helpful AI assistant. Use your tools proactively to help with ops-related tasks like system monitoring, deployment, and infrastructure management."
+    model: gpt-4o-mini
+    memory: false
+
+  content:
+    instructions: "You are a content agent. You are a helpful AI assistant. Use your tools proactively to help with content-related tasks like writing, editing, and content strategy."
+    model: gpt-4o-mini
+    memory: false
+
+# Multiple Telegram channels - each with unique tokens and routing
+channels:
+  telegram_cfo:
+    platform: telegram
+    token: ${TELEGRAM_CFO_BOT_TOKEN}
+    group_policy: mention_only
+    allowed_users: ${TELEGRAM_ALLOWED_USERS}
+    # auto_approve_tools: true
+                               # Chat bots cannot show CLI approval prompts; safe tools auto-approved by default.
+    routes:
+      default: cfo
+
+  telegram_ops:
+    platform: telegram
+    token: ${TELEGRAM_OPS_BOT_TOKEN}
+    group_policy: mention_only
+    allowed_users: ${TELEGRAM_ALLOWED_USERS}
+    # auto_approve_tools: true
+                               # Chat bots cannot show CLI approval prompts; safe tools auto-approved by default.
+    routes:
+      default: ops
+
+  telegram_content:
+    platform: telegram
+    token: ${TELEGRAM_CONTENT_BOT_TOKEN}
+    group_policy: mention_only
+    allowed_users: ${TELEGRAM_ALLOWED_USERS}
+    # auto_approve_tools: true
+                               # Chat bots cannot show CLI approval prompts; safe tools auto-approved by default.
+    routes:
+      default: content
+
+# Legacy routing block
+routing:
+  default: assistant
@@ -93,7 +93,7 @@ def example_3_execute_yaml_directly():
    result = manager.execute_yaml(
        yaml_file,
        input_data="The future of AI",
-        output="verbose"
+        verbose=True,
    )
    
    print(f"Status: {result['status']}")
@@ -1,57 +0,0 @@
-#!/usr/bin/env bash
-# Publish security advisories after PyPI release.
-# Usage: AGENTS_VERSION=1.6.40 WRAPPER_VERSION=4.6.40 ./scripts/security_publish_advisories.sh
-set -euo pipefail
-
-REPO="MervinPraison/PraisonAI"
-AGENTS_VERSION="${AGENTS_VERSION:?Set AGENTS_VERSION (e.g. 1.6.40)}"
-WRAPPER_VERSION="${WRAPPER_VERSION:?Set WRAPPER_VERSION (e.g. 4.6.40)}"
-LAST_AGENTS="${LAST_AGENTS:-1.6.39}"
-LAST_WRAPPER="${LAST_WRAPPER:-4.6.39}"
-
-# Batch 1 + 2 GHSA IDs (update credits login per advisory via gh api first if needed)
-AGENTS_GHSAS=(
-  GHSA-4mr5-g6f9-cfrh
-  GHSA-5c6w-wwfq-7qqm
-  GHSA-5cxw-77wg-jrf3
-)
-
-WRAPPER_GHSAS=(
-  GHSA-9cr9-25q5-8prj
-  GHSA-86qc-r5v2-v6x6
-  GHSA-hvhp-v2gc-268q
-  GHSA-xp85-6wwf-r67c
-  GHSA-8444-4fhq-fxpq
-  GHSA-78r8-wwqv-r299
-  GHSA-vg22-4gmj-prxw
-  GHSA-6xj3-927j-6pqw
-)
-
-patch_advisory() {
-  local ghsa="$1" package="$2" last="$3" patched="$4"
-  gh api "repos/${REPO}/security-advisories/${ghsa}" --method PATCH --input - <<EOF
-{
-  "state": "draft",
-  "vulnerabilities": [
-    {
-      "package": {"ecosystem": "pip", "name": "${package}"},
-      "vulnerable_version_range": "<= ${last}",
-      "patched_versions": ">= ${patched}"
-    }
-  ]
-}
-EOF
-  gh api "repos/${REPO}/security-advisories/${ghsa}" --method PATCH -f state=published
-  gh api "repos/${REPO}/security-advisories/${ghsa}/cve" --method POST || true
-  echo "Published ${ghsa}"
-}
-
-for ghsa in "${AGENTS_GHSAS[@]}"; do
-  patch_advisory "$ghsa" "praisonaiagents" "$LAST_AGENTS" "$AGENTS_VERSION"
-done
-
-for ghsa in "${WRAPPER_GHSAS[@]}"; do
-  patch_advisory "$ghsa" "praisonai" "$LAST_WRAPPER" "$WRAPPER_VERSION"
-done
-
-echo "Done. Verify: gh api repos/${REPO}/security-advisories --jq '.[] | select(.state==\"published\") | .ghsa_id'"
@@ -95,4 +95,5 @@ chroma_db/
 .windsurf
 .ruff_cache
 *.sfdx
-.sfdx/
+.sfdx/
+.cursor/
@@ -79,10 +79,20 @@ def get_time(timezone: Literal["est", "pst"]) -> str:


 def calculate(expression: str) -> str:
-    """Calculate a math expression."""
+    """Calculate a math expression safely."""
    try:
-        result = eval(expression)
-        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:
        return "Error: Invalid expression"