Release v3.12.2

docs: auto-update api.md [skip ci]
Release v3.12.1
2026-11-12 01:41:26 -10:00 · 2026-01-30 10:24:14 +00:00 · 2026-01-30 08:31:24 +00:00 · 2026-01-30 08:31:09 +00:00 · 2026-01-30 08:00:39 +00:00 · 2026-01-30 08:00:22 +00:00
568 changed files with 102181 additions and 4307 deletions
@@ -0,0 +1,145 @@
+name: Performance Benchmarks
+
+on:
+  workflow_dispatch:
+    inputs:
+      iterations:
+        description: 'Number of benchmark iterations'
+        required: false
+        default: '100'
+      fail_on_regression:
+        description: 'Fail if performance regresses'
+        required: false
+        default: 'true'
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e src/praisonai-agents[all]
+          pip install agno crewai langgraph
+
+      - name: Run Import Time Benchmark
+        id: import_time
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/import_time.py 2>&1 | tee import_time_output.txt
+          
+          # Extract import time
+          IMPORT_TIME=$(grep -oP 'Median:\s+\K[\d.]+' import_time_output.txt || echo "0")
+          echo "import_time=$IMPORT_TIME" >> $GITHUB_OUTPUT
+          
+          # Check threshold (200ms)
+          if (( $(echo "$IMPORT_TIME > 200" | bc -l) )); then
+            echo "::warning::Import time ${IMPORT_TIME}ms exceeds 200ms threshold"
+            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
+              echo "import_passed=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "import_passed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Memory Usage Benchmark
+        id: memory
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/memory_usage.py 2>&1 | tee memory_output.txt
+          
+          # Extract peak memory
+          PEAK_MEMORY=$(grep -oP 'Peak:\s+\K[\d.]+' memory_output.txt || echo "0")
+          echo "peak_memory=$PEAK_MEMORY" >> $GITHUB_OUTPUT
+          
+          # Check threshold (30MB)
+          if (( $(echo "$PEAK_MEMORY > 30" | bc -l) )); then
+            echo "::warning::Memory usage ${PEAK_MEMORY}MB exceeds 30MB threshold"
+            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
+              echo "memory_passed=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "memory_passed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Simple Benchmark
+        id: simple
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/simple_benchmark.py 2>&1 | tee simple_output.txt
+          
+          # Extract PraisonAI time
+          PRAISON_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' simple_output.txt | head -1 || echo "0")
+          echo "praison_time=$PRAISON_TIME" >> $GITHUB_OUTPUT
+
+      - name: Run Tools Benchmark
+        id: tools
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/tools_benchmark.py 2>&1 | tee tools_output.txt
+          
+          # Extract PraisonAI time with tools
+          PRAISON_TOOLS_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' tools_output.txt | head -1 || echo "0")
+          echo "praison_tools_time=$PRAISON_TOOLS_TIME" >> $GITHUB_OUTPUT
+
+      - name: Run Parameter Impact Benchmark
+        id: param_impact
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/param_impact_benchmark.py --no-save --iterations ${{ inputs.iterations }} 2>&1 | tee param_impact_output.txt
+
+      - name: Check Lazy Imports
+        id: lazy_imports
+        run: |
+          cd src/praisonai-agents
+          python -c "
+          import sys
+          from praisonaiagents import Agent
+          agent = Agent(name='Test', output='silent')
+          
+          # Check litellm is NOT loaded
+          if 'litellm' in sys.modules:
+              print('FAIL: litellm loaded during silent agent creation')
+              exit(1)
+          else:
+              print('PASS: litellm not loaded (lazy import working)')
+          "
+
+      - name: Generate Benchmark Summary
+        if: always()
+        run: |
+          echo "## Performance Benchmark Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Metric | Value | Threshold | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|--------|-------|-----------|--------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Import Time | ${{ steps.import_time.outputs.import_time }}ms | <200ms | ${{ steps.import_time.outputs.import_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Peak Memory | ${{ steps.memory.outputs.peak_memory }}MB | <30MB | ${{ steps.memory.outputs.memory_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Agent Instantiation | ${{ steps.simple.outputs.praison_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
+          echo "| Agent with Tools | ${{ steps.tools.outputs.praison_tools_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Lazy Import Check" >> $GITHUB_STEP_SUMMARY
+          echo "✅ litellm not loaded during silent agent creation" >> $GITHUB_STEP_SUMMARY
+
+      - name: Fail on Regression
+        if: inputs.fail_on_regression == 'true'
+        run: |
+          if [ "${{ steps.import_time.outputs.import_passed }}" == "false" ]; then
+            echo "::error::Import time regression detected"
+            exit 1
+          fi
+          if [ "${{ steps.memory.outputs.memory_passed }}" == "false" ]; then
+            echo "::error::Memory usage regression detected"
+            exit 1
+          fi
+          echo "All performance checks passed!"
@@ -137,7 +137,6 @@ PraisonAI Agents is the **fastest AI agent framework** for agent instantiation.
 | PraisonAI (LiteLLM) | 7.56 | 2.00x |
 | PydanticAI | 226.94 | 60.16x |
 | LangGraph | 4,558.71 | 1,209x |
-| CrewAI | 15,607.92 | 4,138x |

 <details>
 <summary>Run benchmarks yourself</summary>
@@ -3,16 +3,32 @@
 This file is auto-generated. Do not edit manually.
 Regenerate with: `praisonai docs api-md --write`

-# Agents
+# Shared Types

 Types:
 ```python
-from praisonaiagents import Agent, Agents
+from praisonaiagents import ContextPolicy, GuardrailResult, HandoffConfig, HandoffCycleError, HandoffDepthError, HandoffError, HandoffInputData, HandoffResult, HandoffTimeoutError, ReflectionOutput, StepResult, TaskOutput, ToolResult, ToolValidationError, WorkflowContext
 ```

 Methods:

-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">achat</a>(prompt: str, temperature = 1.0, tools = None, output_json = None, output_pydantic = None, reasoning_steps = False, task_name = None, task_description = None, task_id = None)</code>
+* <code title="class GuardrailResult">GuardrailResult.<a href="./src/praisonai-agents/praisonaiagents/guardrails/guardrail_result.py">from_tuple</a>(result: Tuple[bool, Any]) -> 'GuardrailResult'</code>
+* <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">from_dict</a>(data: Dict[str, Any]) -> 'HandoffConfig'</code>
+* <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">json</a>() -> Optional[str]</code>
+* <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">to_dict</a>() -> dict</code>
+* <code title="class ToolResult">ToolResult.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">to_dict</a>() -> Dict[str, Any]</code>
+
+# Agents
+
+Types:
+```python
+from praisonaiagents import Agent, AutoAgents, AutoRagAgent, ContextAgent, DeepResearchAgent, ImageAgent, PlanningAgent, PromptExpanderAgent, QueryRewriterAgent, create_context_agent
+```
+
+Methods:
+
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">achat</a>(prompt: str, temperature = 1.0, tools = None, output_json = None, output_pydantic = None, reasoning_steps = False, task_name = None, task_description = None, task_id = None, attachments = None)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">aexecute</a>(task, context = None)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">agent_id</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">analyze_prompt</a>(prompt: str) -> set</code>
@@ -22,7 +38,7 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">auto_memory</a>(value)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>(value)</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat</a>(prompt, temperature = 1.0, tools = None, output_json = None, output_pydantic = None, reasoning_steps = False, stream = None, task_name = None, task_description = None, task_id = None, config = None, force_retrieval = False, skip_retrieval = False)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat</a>(prompt, temperature = 1.0, tools = None, output_json = None, output_pydantic = None, reasoning_steps = False, stream = None, task_name = None, task_description = None, task_id = None, config = None, force_retrieval = False, skip_retrieval = False, attachments = None, tool_choice = None)</code>
 * <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>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>(value)</code>
@@ -31,13 +47,17 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">console</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">context_manager</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">context_manager</a>(value)</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">display_generating</a>(content: str, start_time: float)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">delete_history</a>(index: int) -> bool</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">delete_history_matching</a>(pattern: str) -> int</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">display_name</a>() -> str</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">ephemeral</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">execute</a>(task, context = None)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">execute_tool</a>(function_name, arguments)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">execute_tool_async</a>(function_name: str, arguments: Dict[str, Any]) -> Any</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">from_template</a>(uri: str, config: Optional[Dict[str, Any]] = None, offline: bool = False, **kwargs) -> 'Agent'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">generate_task</a>() -> 'Task'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">get_available_tools</a>() -> List[Any]</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">get_history_size</a>() -> int</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">get_memory_context</a>(query: Optional[str] = None) -> str</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">get_recommended_stage</a>(prompt: str) -> str</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">get_rules_context</a>(file_path: Optional[str] = None, include_manual: Optional[List[str]] = None) -> str</code>
@@ -51,6 +71,7 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">output_style</a>(value)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">policy</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">policy</a>(value)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">prune_history</a>(keep_last: int = 5) -> int</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">query</a>(question: str, **kwargs) -> 'RAGResult'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">rag</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">rag_query</a>(question: str, **kwargs) -> 'RAGResult'</code>
@@ -58,84 +79,666 @@ Methods:
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">retrieve</a>(query: str, **kwargs) -> 'ContextPack'</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">rules_manager</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run</a>(prompt: str, **kwargs)</code>
-* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous_async</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">session_id</a>() -> Optional[str]</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">skill_manager</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">start</a>(prompt: str = None, **kwargs)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">store_memory</a>(content: str, memory_type: str = 'short_term', **kwargs)</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>()</code>
+* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>(value)</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">switch_model</a>(new_model: str) -> None</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">thinking_budget</a>()</code>
 * <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">thinking_budget</a>(value)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">add_task</a>(task)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aexecute_task</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">append_to_state</a>(key: str, value: Any, max_length: Optional[int] = None) -> List[Any]</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_all_tasks</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_task</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart</a>(content = None, return_dict = False, **kwargs)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clean_json_output</a>(output: str) -> str</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clear_state</a>() -> None</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">context_manager</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">current_plan</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">default_completion_checker</a>(task, agent_output)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">delete_state</a>(key: str) -> bool</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">display_token_usage</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">execute_task</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_agent_details</a>(agent_name)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_all_state</a>() -> Dict[str, Any]</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_all_tasks_status</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_detailed_token_report</a>() -> Dict[str, Any]</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_plan_markdown</a>() -> str</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_state</a>(key: str, default: Any = None) -> Any</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_details</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_result</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_status</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_todo_markdown</a>() -> str</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_token_usage_summary</a>() -> Dict[str, Any]</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">has_state</a>(key: str) -> bool</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">increment_state</a>(key: str, amount: float = 1, default: float = 0) -> float</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">launch</a>(path: str = '/agents', port: int = 8000, host: str = '0.0.0.0', debug: bool = False, protocol: str = 'http')</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">restore_session_state</a>(session_id: str) -> bool</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run</a>(content = None, return_dict = False, **kwargs)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_all_tasks</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_task</a>(task_id)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_output_to_file</a>(task, task_output)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> None</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">set_state</a>(key: str, value: Any) -> None</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start</a>(content = None, return_dict = False, output = None, **kwargs)</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">todo_list</a>()</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_plan_step_status</a>(step_id: str, status: str) -> bool</code>
-* <code title="class Agents">Agents.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_state</a>(updates: Dict) -> None</code>
+* <code title="class AutoAgents">AutoAgents.<a href="./src/praisonai-agents/praisonaiagents/agents/autoagents.py">astart</a>()</code>
+* <code title="class AutoAgents">AutoAgents.<a href="./src/praisonai-agents/praisonaiagents/agents/autoagents.py">start</a>()</code>
+* <code title="class AutoRagAgent">AutoRagAgent.<a href="./src/praisonai-agents/praisonaiagents/agents/auto_rag_agent.py">achat</a>(message: str, **kwargs) -> str</code>
+* <code title="class AutoRagAgent">AutoRagAgent.<a href="./src/praisonai-agents/praisonaiagents/agents/auto_rag_agent.py">chat</a>(message: str, **kwargs) -> str</code>
+* <code title="class AutoRagAgent">AutoRagAgent.<a href="./src/praisonai-agents/praisonaiagents/agents/auto_rag_agent.py">name</a>() -> str</code>
+* <code title="class AutoRagAgent">AutoRagAgent.<a href="./src/praisonai-agents/praisonaiagents/agents/auto_rag_agent.py">rag</a>() -> Optional['RAG']</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">aanalyze_codebase</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">acreate_implementation_blueprint</a>(feature_request: str, context_analysis: Optional[Dict[str, Any]] = None) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">agenerate_prp</a>(feature_request: str, context_analysis: Optional[Dict[str, Any]] = None) -> str</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">analyze_codebase</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">analyze_codebase_with_gitingest</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">analyze_integration_points</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">analyze_test_patterns</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">build_implementation_blueprint</a>(feature_request: str, context_analysis: Dict[str, Any] = None) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">compile_context_documentation</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">create_implementation_blueprint</a>(feature_request: str, context_analysis: Optional[Dict[str, Any]] = None) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">create_quality_gates</a>(requirements: List[str]) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">create_validation_framework</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">execute_prp</a>(prp_file_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">extract_implementation_patterns</a>(project_path: str, ast_analysis: Dict[str, Any] = None) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">generate_comprehensive_prp</a>(feature_request: str, context_analysis: Dict[str, Any] = None) -> str</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">generate_feature_prp</a>(feature_request: str) -> str</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">generate_prp</a>(feature_request: str, context_analysis: Optional[Dict[str, Any]] = None) -> str</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">get_agent_interaction_summary</a>() -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">log_debug</a>(message: str, **kwargs)</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">perform_ast_analysis</a>(project_path: str) -> Dict[str, Any]</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">save_comprehensive_session_report</a>()</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">save_markdown_output</a>(content: str, filename: str, section_title: str = 'Output')</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">setup_logging</a>()</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">setup_output_directories</a>()</code>
+* <code title="class ContextAgent">ContextAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">start</a>(input_text: str) -> str</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">aresearch</a>(query: str, instructions: Optional[str] = None, model: Optional[str] = None, summary_mode: Optional[Literal['auto', 'detailed', 'concise']] = None, web_search: Optional[bool] = None, code_interpreter: Optional[bool] = None, mcp_servers: Optional[List[Dict[str, Any]]] = None, file_ids: Optional[List[str]] = None, file_search: Optional[bool] = None, file_search_stores: Optional[List[str]] = None) -> DeepResearchResponse</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">async_openai_client</a>()</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">clarify</a>(query: str, model: Optional[str] = None) -> str</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">follow_up</a>(query: str, previous_interaction_id: str, model: Optional[str] = None) -> DeepResearchResponse</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">gemini_client</a>()</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">openai_client</a>()</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">research</a>(query: str, instructions: Optional[str] = None, model: Optional[str] = None, summary_mode: Optional[Literal['auto', 'detailed', 'concise']] = None, web_search: Optional[bool] = None, code_interpreter: Optional[bool] = None, mcp_servers: Optional[List[Dict[str, Any]]] = None, file_ids: Optional[List[str]] = None, file_search: Optional[bool] = None, file_search_stores: Optional[List[str]] = None, stream: bool = True) -> DeepResearchResponse</code>
+* <code title="class DeepResearchAgent">DeepResearchAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/deep_research_agent.py">rewrite_query</a>(query: str, model: Optional[str] = None) -> str</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">achat</a>(prompt: str, temperature: float = 0.2, tools: Optional[List[Any]] = None, output_json: Optional[str] = None, output_pydantic: Optional[Any] = None, reasoning_steps: bool = False, **kwargs) -> Union[str, Dict[str, Any]]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">aedit</a>(image: str, prompt: str, mask: Optional[str] = None, n: int = 1, size: Optional[str] = None, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">agenerate</a>(prompt: str, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">agenerate_image</a>(prompt: str, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">avariation</a>(image: str, n: int = 1, size: Optional[str] = None, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">chat</a>(prompt: str, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">edit</a>(image: str, prompt: str, mask: Optional[str] = None, n: int = 1, size: Optional[str] = None, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">generate</a>(prompt: str, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">generate_image</a>(prompt: str, **kwargs) -> Dict[str, Any]</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">litellm</a>()</code>
+* <code title="class ImageAgent">ImageAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/image_agent.py">variation</a>(image: str, n: int = 1, size: Optional[str] = None, **kwargs) -> Dict[str, Any]</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">analyze_context</a>(context: str) -> str</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">analyze_context_sync</a>(context: str) -> str</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">create_plan</a>(request: str, agents: List['Agent'], tasks: Optional[List['Task']] = None, context: Optional[str] = None) -> Plan</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">create_plan_sync</a>(request: str, agents: List['Agent'], tasks: Optional[List['Task']] = None, context: Optional[str] = None) -> Plan</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">is_tool_allowed</a>(tool_name: str) -> bool</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">refine_plan</a>(plan: Plan, feedback: str) -> Plan</code>
+* <code title="class PlanningAgent">PlanningAgent.<a href="./src/praisonai-agents/praisonaiagents/planning/planner.py">refine_plan_sync</a>(plan: Plan, feedback: str) -> Plan</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">agent</a>()</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">expand</a>(prompt: str, strategy: ExpandStrategy = ..., context: Optional[str] = None) -> ExpandResult</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">expand_basic</a>(prompt: str, context: Optional[str] = None) -> ExpandResult</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">expand_creative</a>(prompt: str, context: Optional[str] = None) -> ExpandResult</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">expand_detailed</a>(prompt: str, context: Optional[str] = None) -> ExpandResult</code>
+* <code title="class PromptExpanderAgent">PromptExpanderAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/prompt_expander_agent.py">expand_structured</a>(prompt: str, context: Optional[str] = None) -> ExpandResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">add_abbreviation</a>(abbrev: str, expansion: str) -> None</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">add_abbreviations</a>(abbreviations: Dict[str, str]) -> None</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">agent</a>()</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite</a>(query: str, strategy: RewriteStrategy = ..., chat_history: Optional[List[Dict[str, str]]] = None, context: Optional[str] = None, num_queries: int = None) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_basic</a>(query: str) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_contextual</a>(query: str, chat_history: List[Dict[str, str]]) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_hyde</a>(query: str) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_multi_query</a>(query: str, num_queries: int = None) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_step_back</a>(query: str) -> RewriteResult</code>
+* <code title="class QueryRewriterAgent">QueryRewriterAgent.<a href="./src/praisonai-agents/praisonaiagents/agent/query_rewriter_agent.py">rewrite_sub_queries</a>(query: str) -> RewriteResult</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/agent/context_agent.py">create_context_agent</a>(llm: Optional[Union[str, Any]] = None, **kwargs) -> ContextAgent</code>

 # Tools

 Types:
 ```python
-from praisonaiagents import Tools, tool
+from praisonaiagents import BaseTool, FunctionTool, ToolRegistry, Tools, get_registry, get_tool, register_tool, tool, validate_tool
 ```

 Methods:

+* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">__call__</a>(**kwargs) -> Any</code>
+* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">get_schema</a>() -> Dict[str, Any]</code>
+* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">run</a>(**kwargs) -> Any</code>
+* <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 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">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>
+* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_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_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">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>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_registry</a>() -> ToolRegistry</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">get_tool</a>(name: str) -> Optional[Union[BaseTool, Callable]]</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">register_tool</a>(tool: Union[BaseTool, Callable], name: Optional[str] = None) -> None</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">tool</a>(func: Optional[Callable] = None) -> Union[FunctionTool, Callable[[Callable], FunctionTool]]</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_tool</a>(tool: Any) -> bool</code>
+
+# Workflows
+
+Types:
+```python
+from praisonaiagents import Loop, Parallel, Pipeline, Repeat, Route, Workflow, loop, parallel, repeat, route
+```
+
+Methods:
+
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">arun</a>(input: str = '', llm: Optional[str] = None, verbose: bool = False) -> Dict[str, Any]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">astart</a>(input: str = '', llm: Optional[str] = None, verbose: bool = False) -> Dict[str, Any]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">from_template</a>(uri: str, config: Optional[Dict[str, Any]] = None, offline: bool = False, **kwargs) -> 'Workflow'</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">memory_config</a>() -> Optional[Dict[str, Any]]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">on_step_complete</a>() -> Optional[Callable]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">on_step_error</a>() -> Optional[Callable]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">on_step_start</a>() -> Optional[Callable]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">on_workflow_complete</a>() -> Optional[Callable]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">on_workflow_start</a>() -> Optional[Callable]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">planning_llm</a>() -> Optional[str]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">reasoning</a>() -> bool</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">run</a>(input: str = '', llm: Optional[str] = None, verbose: bool = False, stream: bool = None) -> Dict[str, Any]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">start</a>(input: str = '', **kwargs) -> Dict[str, Any]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">stream</a>() -> bool</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">verbose</a>() -> bool</code>
+* <code title="class Workflow">Workflow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">verbose</a>(value: bool)</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">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>
+
+# DB
+
+Types:
+```python
+from praisonaiagents import db
+```
+
+# Memory
+
+Types:
+```python
+from praisonaiagents import Memory, MemoryBackend, MemoryConfig
+```
+
+Methods:
+
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">build_context_for_task</a>(task_descr: str, user_id: Optional[str] = None, additional: str = '', max_items: int = 3, include_in_output: Optional[bool] = None) -> str</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">calculate_quality_metrics</a>(output: str, expected_output: str, llm: Optional[str] = None, custom_prompt: Optional[str] = None) -> Dict[str, float]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">compute_quality_score</a>(completeness: float, relevance: float, clarity: float, accuracy: float, weights: Dict[str, float] = None) -> float</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_long_term</a>(memory_id: str) -> bool</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memories</a>(memory_ids: List[str]) -> int</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memories_matching</a>(query: str, memory_type: Optional[str] = None, limit: int = 10) -> int</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memory</a>(memory_id: str, memory_type: Optional[str] = None) -> bool</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_short_term</a>(memory_id: str) -> bool</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">finalize_task_output</a>(content: str, agent_name: str, quality_score: float, threshold: float = 0.7, metrics: Dict[str, Any] = None, task_id: str = None)</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_all_memories</a>() -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_learn_context</a>() -> str</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">learn</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_all</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_entity_only</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_long_term</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_short_term</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_user_memory</a>()</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search</a>(query: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, limit: int = 5, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_entity</a>(query: str, limit: int = 5) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_long_term</a>(query: str, limit: int = 5, relevance_cutoff: float = 0.0, min_quality: float = 0.0, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_short_term</a>(query: str, limit: int = 5, min_quality: float = 0.0, relevance_cutoff: float = 0.0, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_user_memory</a>(user_id: str, query: str, limit: int = 5, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_with_quality</a>(query: str, min_quality: float = 0.0, memory_type: Literal['short', 'long'] = 'long', limit: int = 5) -> List[Dict[str, Any]]</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_entity</a>(name: str, type_: str, desc: str, relations: str)</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_long_term</a>(text: str, metadata: Dict[str, Any] = None, completeness: float = None, relevance: float = None, clarity: float = None, accuracy: float = None, weights: Dict[str, float] = None, evaluator_quality: float = None)</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_quality</a>(text: str, quality_score: float, task_id: Optional[str] = None, iteration: Optional[int] = None, metrics: Optional[Dict[str, float]] = None, memory_type: Literal['short', 'long'] = 'long') -> None</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_short_term</a>(text: str, metadata: Dict[str, Any] = None, completeness: float = None, relevance: float = None, clarity: float = None, accuracy: float = None, weights: Dict[str, float] = None, evaluator_quality: float = None)</code>
+* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_user_memory</a>(user_id: str, text: str, extra: Dict[str, Any] = None)</code>
+* <code title="class MemoryConfig">MemoryConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+
+# Knowledge
+
+Types:
+```python
+from praisonaiagents import Chunking, ChunkingStrategy, Knowledge, KnowledgeConfig
+```
+
+Methods:
+
+* <code title="class Chunking">Chunking.<a href="./src/praisonai-agents/praisonaiagents/knowledge/chunking.py">SUPPORTED_CHUNKERS</a>() -> Dict[str, Any]</code>
+* <code title="class Chunking">Chunking.<a href="./src/praisonai-agents/praisonaiagents/knowledge/chunking.py">__call__</a>(text: Union[str, List[str]], **kwargs) -> Union[List[Any], List[List[Any]]]</code>
+* <code title="class Chunking">Chunking.<a href="./src/praisonai-agents/praisonaiagents/knowledge/chunking.py">chunk</a>(text: Union[str, List[str]], **kwargs) -> Union[List[Any], List[List[Any]]]</code>
+* <code title="class Chunking">Chunking.<a href="./src/praisonai-agents/praisonaiagents/knowledge/chunking.py">chunker</a>()</code>
+* <code title="class Chunking">Chunking.<a href="./src/praisonai-agents/praisonaiagents/knowledge/chunking.py">embedding_model</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">add</a>(file_path, user_id = None, agent_id = None, run_id = None, metadata = None)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">chunker</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">config</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">delete</a>(memory_id)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">delete_all</a>(user_id = None, agent_id = None, run_id = None)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">get</a>(memory_id)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">get_all</a>(user_id = None, agent_id = None, run_id = None)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">get_corpus_stats</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">history</a>(memory_id)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">index</a>(path: str, incremental: bool = True, force: bool = False, include_glob: list = None, exclude_glob: list = None, user_id: str = None, agent_id: str = None, run_id: str = None)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">markdown</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">memory</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">normalize_content</a>(content)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">reset</a>()</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">search</a>(query, user_id = None, agent_id = None, run_id = None, rerank = None, **kwargs)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">store</a>(content, user_id = None, agent_id = None, run_id = None, metadata = None)</code>
+* <code title="class Knowledge">Knowledge.<a href="./src/praisonai-agents/praisonaiagents/knowledge/knowledge.py">update</a>(memory_id, data)</code>
+* <code title="class KnowledgeConfig">KnowledgeConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+
+# RAG
+
+Types:
+```python
+from praisonaiagents import CitationsMode, ContextPack, RAG, RAGCitation, RAGConfig, RAGResult, RetrievalConfig, RetrievalPolicy
+```
+
+Methods:
+
+* <code title="class ContextPack">ContextPack.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">format_for_prompt</a>(include_sources: bool = True) -> str</code>
+* <code title="class ContextPack">ContextPack.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">from_dict</a>(data: Dict[str, Any]) -> 'ContextPack'</code>
+* <code title="class ContextPack">ContextPack.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">has_citations</a>() -> bool</code>
+* <code title="class ContextPack">ContextPack.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">aquery</a>(question: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, **kwargs) -> RAGResult</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">aretrieve</a>(query: str, **kwargs) -> ContextPack</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">astream</a>(question: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, **kwargs) -> AsyncIterator[str]</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">get_citations</a>(question: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, **kwargs) -> List[Citation]</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">llm</a>()</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">query</a>(question: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, **kwargs) -> RAGResult</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">retrieve</a>(query: str, **kwargs) -> ContextPack</code>
+* <code title="class RAG">RAG.<a href="./src/praisonai-agents/praisonaiagents/rag/pipeline.py">stream</a>(question: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, **kwargs) -> Iterator[str]</code>
+* <code title="class RAGCitation">RAGCitation.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">from_dict</a>(data: Dict[str, Any]) -> 'Citation'</code>
+* <code title="class RAGCitation">RAGCitation.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class RAGConfig">RAGConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">from_dict</a>(data: Dict[str, Any]) -> 'RAGConfig'</code>
+* <code title="class RAGConfig">RAGConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class RAGResult">RAGResult.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">format_answer_with_citations</a>() -> str</code>
+* <code title="class RAGResult">RAGResult.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">from_dict</a>(data: Dict[str, Any]) -> 'RAGResult'</code>
+* <code title="class RAGResult">RAGResult.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">has_citations</a>() -> bool</code>
+* <code title="class RAGResult">RAGResult.<a href="./src/praisonai-agents/praisonaiagents/rag/models.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">from_dict</a>(data: Dict[str, Any]) -> 'RetrievalConfig'</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">get_strategy</a>(corpus_stats = None)</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">get_token_budget</a>(model_name: Optional[str] = None)</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">should_retrieve</a>(query: str, force: bool = False, skip: bool = False) -> bool</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">to_knowledge_config</a>() -> Dict[str, Any]</code>
+* <code title="class RetrievalConfig">RetrievalConfig.<a href="./src/praisonai-agents/praisonaiagents/rag/retrieval_config.py">to_rag_config</a>() -> Dict[str, Any]</code>
+
+# Handoff
+
+Types:
+```python
+from praisonaiagents import Handoff, RECOMMENDED_PROMPT_PREFIX, handoff, handoff_filters, prompt_with_handoff_instructions
+```
+
+Methods:
+
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">default_tool_description</a>() -> str</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">default_tool_name</a>() -> str</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">execute_async</a>(source_agent: 'Agent', prompt: str, context: Optional[Dict[str, Any]] = None) -> HandoffResult</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">execute_programmatic</a>(source_agent: 'Agent', prompt: str, context: Optional[Dict[str, Any]] = None) -> HandoffResult</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">to_tool_function</a>(source_agent: 'Agent') -> Callable</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">tool_description</a>() -> str</code>
+* <code title="class Handoff">Handoff.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">tool_name</a>() -> str</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">handoff</a>(agent: 'Agent', tool_name_override: Optional[str] = None, tool_description_override: Optional[str] = None, on_handoff: Optional[Callable] = None, input_type: Optional[type] = None, input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]] = None, config: Optional[HandoffConfig] = None, context_policy: Optional[str] = None, timeout_seconds: Optional[float] = None, max_concurrent: Optional[int] = None, detect_cycles: Optional[bool] = None, max_depth: Optional[int] = None) -> Handoff</code>
+* <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">keep_last_n_messages</a>(n: int) -> Callable[[HandoffInputData], HandoffInputData]</code>
+* <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">remove_all_tools</a>(data: HandoffInputData) -> HandoffInputData</code>
+* <code title="class handoff_filters">handoff_filters.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">remove_system_messages</a>(data: HandoffInputData) -> HandoffInputData</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">prompt_with_handoff_instructions</a>(base_prompt: str, agent: 'Agent') -> str</code>
+
+# Guardrails
+
+Types:
+```python
+from praisonaiagents import GuardrailAction, GuardrailConfig, LLMGuardrail
+```
+
+Methods:
+
+* <code title="class GuardrailConfig">GuardrailConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class LLMGuardrail">LLMGuardrail.<a href="./src/praisonai-agents/praisonaiagents/guardrails/llm_guardrail.py">__call__</a>(task_output: TaskOutput) -> Tuple[bool, Union[str, TaskOutput]]</code>
+
+# Planning
+
+Types:
+```python
+from praisonaiagents import ApprovalCallback, Plan, PlanStep, PlanStorage, PlanningConfig, READ_ONLY_TOOLS, RESTRICTED_TOOLS, TodoItem, TodoList
+```
+
+Methods:
+
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">__call__</a>(plan: 'Plan') -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">always_approve</a>(plan: 'Plan') -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">always_reject</a>(plan: 'Plan') -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">approve_if_no_dangerous_tools</a>(plan: 'Plan') -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">approve_if_small</a>(plan: 'Plan', max_steps: int = 5) -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">async_call</a>(plan: 'Plan') -> bool</code>
+* <code title="class ApprovalCallback">ApprovalCallback.<a href="./src/praisonai-agents/praisonaiagents/planning/approval.py">console_approval</a>(plan: 'Plan') -> bool</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">add_step</a>(step: PlanStep) -> None</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">approve</a>() -> None</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">cancel</a>() -> None</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">complete</a>() -> None</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">completed_step_ids</a>() -> List[str]</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">from_dict</a>(data: Dict[str, Any]) -> 'Plan'</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">from_markdown</a>(markdown: str) -> 'Plan'</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">get_next_steps</a>() -> List[PlanStep]</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">get_step</a>(step_id: str) -> Optional[PlanStep]</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">is_complete</a>() -> bool</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">progress</a>() -> float</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">remove_step</a>(step_id: str) -> bool</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">start_execution</a>() -> None</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">to_markdown</a>() -> str</code>
+* <code title="class Plan">Plan.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">update_step_status</a>(step_id: str, status: str) -> bool</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">from_dict</a>(data: Dict[str, Any]) -> 'PlanStep'</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">is_ready</a>(completed_steps: List[str]) -> bool</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">mark_complete</a>() -> None</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">mark_in_progress</a>() -> None</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">mark_skipped</a>() -> None</code>
+* <code title="class PlanStep">PlanStep.<a href="./src/praisonai-agents/praisonaiagents/planning/plan.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">cleanup_old_plans</a>(keep_count: int = 10) -> int</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">delete_plan</a>(plan_id: str) -> bool</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">delete_todo</a>(name: str) -> bool</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">get_latest_plan</a>() -> Optional[Plan]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">list_plans</a>() -> List[Dict[str, Any]]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">list_todos</a>() -> List[str]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">load_plan</a>(plan_id: str) -> Optional[Plan]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">load_plan_from_file</a>(path: str) -> Optional[Plan]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">load_todo</a>(name: str = 'current') -> Optional[TodoList]</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">save_plan</a>(plan: Plan, filename: Optional[str] = None) -> str</code>
+* <code title="class PlanStorage">PlanStorage.<a href="./src/praisonai-agents/praisonaiagents/planning/storage.py">save_todo</a>(todo: TodoList, name: str = 'current') -> str</code>
+* <code title="class PlanningConfig">PlanningConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">complete</a>() -> None</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">from_dict</a>(data: Dict[str, Any]) -> 'TodoItem'</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">is_ready</a>(completed_ids: List[str]) -> bool</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">reset</a>() -> None</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">start</a>() -> None</code>
+* <code title="class TodoItem">TodoItem.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">add</a>(item: Union[TodoItem, str]) -> TodoItem</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">complete</a>(item_id: str) -> bool</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">completed</a>() -> List[TodoItem]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">completed_ids</a>() -> List[str]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">from_dict</a>(data: Dict[str, Any]) -> 'TodoList'</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">from_json</a>(json_str: str) -> 'TodoList'</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">from_markdown</a>(markdown: str) -> 'TodoList'</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">from_plan</a>(plan: 'Plan') -> 'TodoList'</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">get</a>(item_id: str) -> Optional[TodoItem]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">get_ready_items</a>() -> List[TodoItem]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">in_progress</a>() -> List[TodoItem]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">is_complete</a>() -> bool</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">pending</a>() -> List[TodoItem]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">progress</a>() -> float</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">remove</a>(item_id: str) -> bool</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">start</a>(item_id: str) -> bool</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">sync_with_plan</a>(plan: 'Plan') -> None</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">to_json</a>() -> str</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">to_markdown</a>() -> str</code>
+* <code title="class TodoList">TodoList.<a href="./src/praisonai-agents/praisonaiagents/planning/todo.py">update_from_plan</a>(plan: 'Plan') -> None</code>
+
+# Skills
+
+Types:
+```python
+from praisonaiagents import SkillLoader, SkillManager, SkillMetadata, SkillProperties, SkillsConfig
+```
+
+Methods:
+
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">activate</a>(skill: LoadedSkill) -> bool</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load</a>(skill_path: str, activate: bool = False) -> Optional[LoadedSkill]</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_all_resources</a>(skill: LoadedSkill) -> None</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_assets</a>(skill: LoadedSkill) -> dict</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_metadata</a>(skill_path: str) -> Optional[LoadedSkill]</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_references</a>(skill: LoadedSkill) -> dict</code>
+* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_scripts</a>(skill: LoadedSkill) -> dict</code>
+* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">activate</a>(skill: LoadedSkill) -> bool</code>
+* <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">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">get_available_skills</a>() -> List[SkillMetadata]</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">load_resources</a>(name: str) -> bool</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 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>
+
+# Session
+
+Types:
+```python
+from praisonaiagents import Session
+```
+
+Methods:
+
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">Agent</a>(name: str, role: str = 'Assistant', instructions: Optional[str] = None, tools: Optional[List[Any]] = None, memory: bool = True, knowledge: Optional[List[str]] = None, **kwargs) -> 'Agent'</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">add_knowledge</a>(source: str) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">add_memory</a>(text: str, memory_type: str = 'long', **metadata) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">chat</a>(message: str, **kwargs) -> str</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">clear_memory</a>(memory_type: str = 'all') -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">create_agent</a>(*args, **kwargs) -> 'Agent'</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">get_context</a>(query: str, max_items: int = 3) -> str</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">get_state</a>(key: str, default: Any = None) -> Any</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">increment_state</a>(key: str, increment: int = 1, default: int = 0) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">knowledge</a>() -> 'Knowledge'</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">memory</a>() -> 'Memory'</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">restore_state</a>() -> Dict[str, Any]</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">save_state</a>(state_data: Dict[str, Any]) -> None</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">search_knowledge</a>(query: str, limit: int = 5) -> List[Dict[str, Any]]</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">search_memory</a>(query: str, memory_type: str = 'long', limit: int = 5) -> List[Dict[str, Any]]</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">send_message</a>(message: str, **kwargs) -> str</code>
+* <code title="class Session">Session.<a href="./src/praisonai-agents/praisonaiagents/session/api.py">set_state</a>(key: str, value: Any) -> None</code>
+
+# MCP
+
+Types:
+```python
+from praisonaiagents import MCP
+```
+
+Methods:
+
+* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_tools</a>() -> List[Callable]</code>
+* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">shutdown</a>()</code>
+* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">to_openai_tool</a>()</code>
+
+# Telemetry
+
+Types:
+```python
+from praisonaiagents import MinimalTelemetry, TelemetryCollector, cleanup_telemetry_resources, disable_performance_mode, disable_telemetry, enable_performance_mode, enable_telemetry, get_telemetry
+```
+
+Methods:
+
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">flush</a>()</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">get_metrics</a>() -> Dict[str, Any]</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">shutdown</a>()</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">track_agent_execution</a>(agent_name: str = None, success: bool = True, async_mode: bool = False)</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">track_error</a>(error_type: str = None)</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">track_feature_usage</a>(feature_name: str)</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">track_task_completion</a>(task_name: str = None, success: bool = True)</code>
+* <code title="class MinimalTelemetry">MinimalTelemetry.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">track_tool_usage</a>(tool_name: str, success: bool = True, execution_time: float = None)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">get_metrics</a>() -> Dict[str, Any]</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">record_cost</a>(cost: float, model: str = None)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">record_tokens</a>(prompt_tokens: int, completion_tokens: int, model: str = None)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">start</a>()</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">stop</a>()</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">trace_agent_execution</a>(agent_name: str, **attributes)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">trace_llm_call</a>(model: str = None, **attributes)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">trace_task_execution</a>(task_name: str, agent_name: str = None, **attributes)</code>
+* <code title="class TelemetryCollector">TelemetryCollector.<a href="./src/praisonai-agents/praisonaiagents/telemetry/telemetry.py">trace_tool_call</a>(tool_name: str, **attributes)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">cleanup_telemetry_resources</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">disable_performance_mode</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">disable_telemetry</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">enable_performance_mode</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">enable_telemetry</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/telemetry/__init__.py">get_telemetry</a>() -> 'MinimalTelemetry'</code>
+
+# Observability
+
+Types:
+```python
+from praisonaiagents import FlowDisplay, obs, track_workflow
+```
+
+Methods:
+
+* <code title="class FlowDisplay">FlowDisplay.<a href="./src/praisonai-agents/praisonaiagents/flow_display.py">display</a>()</code>
+* <code title="class FlowDisplay">FlowDisplay.<a href="./src/praisonai-agents/praisonaiagents/flow_display.py">start</a>()</code>
+* <code title="class FlowDisplay">FlowDisplay.<a href="./src/praisonai-agents/praisonaiagents/flow_display.py">stop</a>()</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/flow_display.py">track_workflow</a>()</code>
+
+# Context
+
+Types:
+```python
+from praisonaiagents import ContextManager, ManagerConfig
+```
+
+Methods:
+
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">capture_llm_boundary</a>(messages: List[Dict[str, Any]], tools: List[Dict[str, Any]]) -> SnapshotHookData</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">emergency_truncate</a>(messages: List[Dict[str, Any]], target_tokens: int) -> List[Dict[str, Any]]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">estimate_tokens</a>(text: str, validate: bool = False) -> Tuple[int, Optional[EstimationMetrics]]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">get_history</a>() -> List[Dict[str, Any]]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">get_last_snapshot_hook</a>() -> Optional[SnapshotHookData]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">get_resolved_config</a>() -> Dict[str, Any]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">get_stats</a>() -> Dict[str, Any]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">get_tool_budget</a>(tool_name: str) -> int</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">process</a>(messages: List[Dict[str, Any]], system_prompt: str = '', tools: Optional[List[Dict[str, Any]]] = None, trigger: Literal['turn', 'tool_call', 'manual', 'overflow'] = 'turn') -> Dict[str, Any]</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">register_snapshot_callback</a>(callback: Callable[[SnapshotHookData], None]) -> None</code>
+* <code title="class ContextManager">ContextManager.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">reset</a>() -> None</code>
+* <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>
+* <code title="class ManagerConfig">ManagerConfig.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">from_env</a>() -> 'ManagerConfig'</code>
+* <code title="class ManagerConfig">ManagerConfig.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">merge</a>(**overrides) -> 'ManagerConfig'</code>
+* <code title="class ManagerConfig">ManagerConfig.<a href="./src/praisonai-agents/praisonaiagents/context/manager.py">to_dict</a>() -> Dict[str, Any]</code>
+
+# Config
+
+Types:
+```python
+from praisonaiagents import AutonomyConfig, AutonomyLevel, CachingConfig, ExecutionConfig, ExecutionPreset, GuardrailConfig, HooksConfig, KnowledgeConfig, MemoryConfig, MultiAgentExecutionConfig, MultiAgentHooksConfig, MultiAgentMemoryConfig, MultiAgentOutputConfig, MultiAgentPlanningConfig, OutputConfig, OutputPreset, PlanningConfig, ReflectionConfig, SkillsConfig, TemplateConfig, WebConfig, WebSearchProvider
+```
+
+Methods:
+
+* <code title="class AutonomyConfig">AutonomyConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class CachingConfig">CachingConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class ExecutionConfig">ExecutionConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class GuardrailConfig">GuardrailConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class HooksConfig">HooksConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class KnowledgeConfig">KnowledgeConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MemoryConfig">MemoryConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MultiAgentExecutionConfig">MultiAgentExecutionConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MultiAgentHooksConfig">MultiAgentHooksConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MultiAgentMemoryConfig">MultiAgentMemoryConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MultiAgentOutputConfig">MultiAgentOutputConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class MultiAgentPlanningConfig">MultiAgentPlanningConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class OutputConfig">OutputConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class PlanningConfig">PlanningConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class ReflectionConfig">ReflectionConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class SkillsConfig">SkillsConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class TemplateConfig">TemplateConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+* <code title="class WebConfig">WebConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
+
+# Display
+
+Types:
+```python
+from praisonaiagents import async_display_callbacks, clean_triple_backticks, display_error, display_generating, display_instruction, display_interaction, display_self_reflection, display_tool_call, error_logs, register_display_callback, sync_display_callbacks
+```
+
+Methods:
+
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">clean_triple_backticks</a>(text: str) -> str</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_error</a>(message: str, console = None)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_generating</a>(content: str = '', start_time: Optional[float] = None)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_instruction</a>(message: str, console = None, agent_name: str = None, agent_role: str = None, agent_tools: List[str] = None)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_interaction</a>(message, response, markdown = True, generation_time = None, console = None, agent_name = None, agent_role = None, agent_tools = None, task_name = None, task_description = None, task_id = None, metrics = None)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_self_reflection</a>(message: str, console = None)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">display_tool_call</a>(message: str, console = None, tool_name: str = None, tool_input: dict = None, tool_output: str = None, elapsed_time: float = None, success: bool = True)</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/main.py">register_display_callback</a>(display_type: str, callback_fn, is_async: bool = False)</code>
+
+# Utilities
+
+Types:
+```python
+from praisonaiagents import ArrayMode, is_policy_string, parse_policy_string, resolve, resolve_autonomy, resolve_caching, resolve_context, resolve_execution, resolve_guardrail_policies, resolve_guardrails, resolve_hooks, resolve_knowledge, resolve_memory, resolve_output, resolve_planning, resolve_reflection, resolve_routing, resolve_skills, resolve_web
+```
+
+Methods:
+
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/parse_utils.py">is_policy_string</a>(value: str) -> bool</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/parse_utils.py">parse_policy_string</a>(value: str) -> tuple</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve</a>(value: Any, param_name: str, config_class: Optional[Type] = None, presets: Optional[Dict[str, Any]] = None, default: Any = None, instance_check: Optional[Callable[[Any], bool]] = None, url_schemes: Optional[Dict[str, str]] = None, array_mode: Optional[str] = None, string_mode: Optional[str] = None) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_autonomy</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_caching</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_context</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_execution</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_guardrail_policies</a>(policies: list, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_guardrails</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_hooks</a>(value: Any, config_class: Optional[Type] = None) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_knowledge</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_memory</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_output</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_planning</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_reflection</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_routing</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_skills</a>(value: Any, config_class: Type) -> Any</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/config/param_resolver.py">resolve_web</a>(value: Any, config_class: Type) -> Any</code>

 # Other

 Types:
 ```python
-from praisonaiagents import Task
+from praisonaiagents import AgentManager, EmbeddingResult, Task, aembedding, aembeddings, embedding, embeddings, get_dimensions
 ```

 Methods:

+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">add_task</a>(task)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aexecute_task</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">append_to_state</a>(key: str, value: Any, max_length: Optional[int] = None) -> List[Any]</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_all_tasks</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_task</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart</a>(content = None, return_dict = False, **kwargs)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clean_json_output</a>(output: str) -> str</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clear_state</a>() -> None</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">context_manager</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">current_plan</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">default_completion_checker</a>(task, agent_output)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">delete_state</a>(key: str) -> bool</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">display_token_usage</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">execute_task</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_agent_details</a>(agent_name)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_all_state</a>() -> Dict[str, Any]</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_all_tasks_status</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_detailed_token_report</a>() -> Dict[str, Any]</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_plan_markdown</a>() -> str</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_state</a>(key: str, default: Any = None) -> Any</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_details</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_result</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_task_status</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_todo_markdown</a>() -> str</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_token_usage_summary</a>() -> Dict[str, Any]</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">has_state</a>(key: str) -> bool</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">increment_state</a>(key: str, amount: float = 1, default: float = 0) -> float</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">launch</a>(path: str = '/agents', port: int = 8000, host: str = '0.0.0.0', debug: bool = False, protocol: str = 'http')</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">restore_session_state</a>(session_id: str) -> bool</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run</a>(content = None, return_dict = False, **kwargs)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_all_tasks</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_task</a>(task_id)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_output_to_file</a>(task, task_output)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> None</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">set_state</a>(key: str, value: Any) -> None</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start</a>(content = None, return_dict = False, output = None, **kwargs)</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">todo_list</a>()</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_plan_step_status</a>(step_id: str, status: str) -> bool</code>
+* <code title="class AgentManager">AgentManager.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_state</a>(updates: Dict) -> None</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">execute_callback</a>(task_output: TaskOutput) -> None</code>
 * <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">initialize_memory</a>()</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="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembedding</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembeddings</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">embedding</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">embeddings</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/dimensions.py">get_dimensions</a>(model_name: str) -> int</code>

 # Wrapper (praisonai)

 Types:
 ```python
-from praisonai import CloudProvider, Deploy, DeployConfig, DeployType, PraisonAI, __version__
+from praisonai import AgentApp, CloudProvider, Deploy, DeployConfig, DeployType, PraisonAI, __version__
 ```

 # CLI
@@ -147,6 +750,7 @@ Methods:
 * <code title="cli">praisonai agents create <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
 * <code title="cli">praisonai agents info <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
 * <code title="cli">praisonai agents list <a href="./src/praisonai/praisonai/cli/commands/agents.py">--help</a></code>
+* <code title="cli">praisonai app app <a href="./src/praisonai/praisonai/cli/commands/app.py">--help</a></code>
 * <code title="cli">praisonai audit agent-centric <a href="./src/praisonai/praisonai/cli/commands/audit.py">--help</a></code>
 * <code title="cli">praisonai batch batch-run <a href="./src/praisonai/praisonai/cli/commands/batch.py">--help</a></code>
 * <code title="cli">praisonai batch list <a href="./src/praisonai/praisonai/cli/commands/batch.py">--help</a></code>
@@ -160,6 +764,19 @@ Methods:
 * <code title="cli">praisonai benchmark profile <a href="./src/praisonai/praisonai/cli/commands/benchmark.py">--help</a></code>
 * <code title="cli">praisonai benchmark sdk <a href="./src/praisonai/praisonai/cli/commands/benchmark.py">--help</a></code>
 * <code title="cli">praisonai benchmark workflow <a href="./src/praisonai/praisonai/cli/commands/benchmark.py">--help</a></code>
+* <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 slack <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>
+* <code title="cli">praisonai browser browser-callback <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser click <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser navigate <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser open <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser profiles <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser screenshot <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser snapshot <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser status <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
+* <code title="cli">praisonai browser type <a href="./src/praisonai/praisonai/cli/commands/browser.py">--help</a></code>
 * <code title="cli">praisonai call call-main <a href="./src/praisonai/praisonai/cli/commands/call.py">--help</a></code>
 * <code title="cli">praisonai chat <a href="./src/praisonai/praisonai/cli/main.py">--help</a></code>
 * <code title="cli">praisonai chat chat-main <a href="./src/praisonai/praisonai/cli/commands/chat.py">--help</a></code>
@@ -220,6 +837,8 @@ Methods:
 * <code title="cli">praisonai environment doctor <a href="./src/praisonai/praisonai/cli/commands/environment.py">--help</a></code>
 * <code title="cli">praisonai environment view <a href="./src/praisonai/praisonai/cli/commands/environment.py">--help</a></code>
 * <code title="cli">praisonai eval accuracy <a href="./src/praisonai/praisonai/cli/commands/eval.py">--help</a></code>
+* <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 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>
@@ -234,14 +853,18 @@ Methods:
 * <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 loop help <a href="./src/praisonai/praisonai/cli/commands/loop.py">--help</a></code>
+* <code title="cli">praisonai loop loop-main <a href="./src/praisonai/praisonai/cli/commands/loop.py">--help</a></code>
 * <code title="cli">praisonai lsp logs <a href="./src/praisonai/praisonai/cli/commands/lsp.py">--help</a></code>
 * <code title="cli">praisonai lsp lsp-callback <a href="./src/praisonai/praisonai/cli/commands/lsp.py">--help</a></code>
 * <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 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>
 * <code title="cli">praisonai mcp list <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
+* <code title="cli">praisonai mcp logout <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
 * <code title="cli">praisonai mcp mcp-callback <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
 * <code title="cli">praisonai mcp remove <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
 * <code title="cli">praisonai mcp run <a href="./src/praisonai/praisonai/cli/commands/mcp.py">--help</a></code>
@@ -257,6 +880,12 @@ Methods:
 * <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 plugins disable <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
+* <code title="cli">praisonai plugins doctor <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
+* <code title="cli">praisonai plugins enable <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
+* <code title="cli">praisonai plugins info <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
+* <code title="cli">praisonai plugins list <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
+* <code title="cli">praisonai plugins plugins-callback <a href="./src/praisonai/praisonai/cli/commands/plugins.py">--help</a></code>
 * <code title="cli">praisonai profile imports <a href="./src/praisonai/praisonai/cli/commands/profile.py">--help</a></code>
 * <code title="cli">praisonai profile optimize <a href="./src/praisonai/praisonai/cli/commands/profile.py">--help</a></code>
 * <code title="cli">praisonai profile profile-callback <a href="./src/praisonai/praisonai/cli/commands/profile.py">--help</a></code>
@@ -270,11 +899,24 @@ Methods:
 * <code title="cli">praisonai rag query <a href="./src/praisonai/praisonai/cli/commands/rag.py">--help</a></code>
 * <code title="cli">praisonai rag serve <a href="./src/praisonai/praisonai/cli/commands/rag.py">--help</a></code>
 * <code title="cli">praisonai realtime realtime-main <a href="./src/praisonai/praisonai/cli/commands/realtime.py">--help</a></code>
+* <code title="cli">praisonai recipe apply <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
+* <code title="cli">praisonai recipe create <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
+* <code title="cli">praisonai recipe info <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
 * <code title="cli">praisonai recipe install <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
+* <code title="cli">praisonai recipe judge <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
 * <code title="cli">praisonai recipe list <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
+* <code title="cli">praisonai recipe optimize <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
 * <code title="cli">praisonai recipe run <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
+* <code title="cli">praisonai recipe serve <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
 * <code title="cli">praisonai registry list <a href="./src/praisonai/praisonai/cli/commands/registry.py">--help</a></code>
 * <code title="cli">praisonai registry serve <a href="./src/praisonai/praisonai/cli/commands/registry.py">--help</a></code>
+* <code title="cli">praisonai replay cleanup <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay context <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay dashboard <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay delete <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay flow <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay list <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
+* <code title="cli">praisonai replay show <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
 * <code title="cli">praisonai research research-main <a href="./src/praisonai/praisonai/cli/commands/research.py">--help</a></code>
 * <code title="cli">praisonai retrieval index <a href="./src/praisonai/praisonai/cli/commands/retrieval.py">--help</a></code>
 * <code title="cli">praisonai retrieval query <a href="./src/praisonai/praisonai/cli/commands/retrieval.py">--help</a></code>
@@ -284,6 +926,11 @@ Methods:
 * <code title="cli">praisonai rules list <a href="./src/praisonai/praisonai/cli/commands/rules.py">--help</a></code>
 * <code title="cli">praisonai run <a href="./src/praisonai/praisonai/cli/main.py">--help</a></code>
 * <code title="cli">praisonai run run-main <a href="./src/praisonai/praisonai/cli/commands/run.py">--help</a></code>
+* <code title="cli">praisonai sandbox explain <a href="./src/praisonai/praisonai/cli/commands/sandbox.py">--help</a></code>
+* <code title="cli">praisonai sandbox list <a href="./src/praisonai/praisonai/cli/commands/sandbox.py">--help</a></code>
+* <code title="cli">praisonai sandbox recreate <a href="./src/praisonai/praisonai/cli/commands/sandbox.py">--help</a></code>
+* <code title="cli">praisonai sandbox sandbox-callback <a href="./src/praisonai/praisonai/cli/commands/sandbox.py">--help</a></code>
+* <code title="cli">praisonai sandbox status <a href="./src/praisonai/praisonai/cli/commands/sandbox.py">--help</a></code>
 * <code title="cli">praisonai schedule delete <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
 * <code title="cli">praisonai schedule describe <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
 * <code title="cli">praisonai schedule list <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
@@ -293,17 +940,33 @@ Methods:
 * <code title="cli">praisonai schedule start <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
 * <code title="cli">praisonai schedule stats <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
 * <code title="cli">praisonai schedule stop <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
+* <code title="cli">praisonai serve a2a <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve a2u <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve acp <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve agents <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve docs <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve gateway <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve lsp <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve mcp <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve rag <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve recipe <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve registry <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
+* <code title="cli">praisonai serve scheduler <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai serve serve-callback <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <code title="cli">praisonai serve start <a href="./src/praisonai/praisonai/cli/commands/serve.py">--help</a></code>
 * <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 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>
 * <code title="cli">praisonai session import <a href="./src/praisonai/praisonai/cli/commands/session.py">--help</a></code>
 * <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 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>
 * <code title="cli">praisonai skills info <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
 * <code title="cli">praisonai skills install <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
 * <code title="cli">praisonai skills list <a href="./src/praisonai/praisonai/cli/commands/skills.py">--help</a></code>
@@ -324,11 +987,16 @@ Methods:
 * <code title="cli">praisonai tools info <a href="./src/praisonai/praisonai/cli/commands/tools.py">--help</a></code>
 * <code title="cli">praisonai tools list <a href="./src/praisonai/praisonai/cli/commands/tools.py">--help</a></code>
 * <code title="cli">praisonai tools test <a href="./src/praisonai/praisonai/cli/commands/tools.py">--help</a></code>
+* <code title="cli">praisonai tools validate <a href="./src/praisonai/praisonai/cli/commands/tools.py">--help</a></code>
 * <code title="cli">praisonai traces disable <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
 * <code title="cli">praisonai traces enable <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
 * <code title="cli">praisonai traces list <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
 * <code title="cli">praisonai traces status <a href="./src/praisonai/praisonai/cli/commands/traces.py">--help</a></code>
-* <code title="cli">praisonai train train-main <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
+* <code title="cli">praisonai train agents <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
+* <code title="cli">praisonai train list <a href="./src/praisonai/praisonai/cli/commands/train.py">--help</a></code>
+* <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 chat <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
 * <code title="cli">praisonai ui code <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
 * <code title="cli">praisonai ui gradio <a href="./src/praisonai/praisonai/cli/commands/ui.py">--help</a></code>
@@ -347,6 +1015,8 @@ Types/Exports:
 ```ts
 export { Agent, Agents, PraisonAIAgents, Router } from "./agent";
 export type { PraisonAIAgentsConfig, SimpleAgentConfig, SimpleRouteConfig, SimpleRouterConfig } from "./agent";
+export { AudioAgent, createAudioAgent } from "./agent/audio";
+export type { AudioAgentConfig, AudioProvider, AudioSpeakOptions, AudioSpeakResult, AudioTranscribeOptions, AudioTranscribeResult } from "./agent/audio";
 export { ContextAgent, createContextAgent } from "./agent/context";
 export { Handoff, handoff, handoffFilters } from "./agent/handoff";
 export { ImageAgent, createImageAgent } from "./agent/image";
@@ -368,7 +1038,7 @@ export { // Agent loop
  configureTelemetry, // Tool Approval (AI SDK v6 parity)
  ApprovalManager, // Tools
  defineTool, // UI Message (AI SDK v6 parity)
-  convertToModelMessages, AIAgentStep, AIEmbedManyResult, AIEmbedOptions, AIEmbedResult, AIFilePart, AIGenerateImageOptions, AIGenerateImageResult, AIGenerateObjectOptions, AIGenerateObjectResult, AIGenerateTextOptions, AIGenerateTextResult, AIImagePart, AIMiddleware, AIMiddlewareConfig, AIModelMessage, AISpan, AISpanKind, AISpanOptions, AISpanStatus, AIStreamObjectOptions, AIStreamObjectResult, AIStreamTextOptions, AIStreamTextResult, AITelemetryEvent, AITelemetrySettings, AITextPart, AIToolDefinition, AITracer, AgentLoop, DANGEROUS_PATTERNS, MODEL_ALIASES, SPEECH_MODELS, TRANSCRIPTION_MODELS, ToolApprovalDeniedError, ToolApprovalTimeoutError, aiEmbed, aiEmbedMany, aiGenerateImage, aiGenerateObject, aiGenerateText, aiStreamObject, aiStreamText, applyMiddleware, autoEnableDevTools, base64ToUint8Array, clearAICache, clearEvents, closeAllMCPClients, closeMCPClient, convertToUIMessages, createAILoggingMiddleware, createAISpan, createApprovalResponse, createDangerousPatternChecker, createDevToolsMiddleware, createExpressHandler, createFastifyHandler, createFilePart, createHonoHandler, createMultimodalMessage, createNestHandler, createPagesHandler, createPdfPart, createSystemMessage, createTelemetryMiddleware, createTelemetrySettings, createTextMessage, createTextPart, createToolSet, disableAITelemetry, disableDevTools, enableAITelemetry, functionToTool, getAICacheStats, getApprovalManager, getDevToolsState, getDevToolsUrl, getEvents, getMCPClient, getModel, getTelemetrySettings, getToolsNeedingApproval, getTracer, hasModelAlias, hasPendingApprovals, initOpenTelemetry, isDangerous, isDataUrl, isDevToolsEnabled, isTelemetryEnabled, isUrl, listModelAliases, mcpToolsToAITools, parseModel, pipeUIMessageStreamToResponse, recordEvent, resolveModelAlias, safeValidateUIMessages, setApprovalManager, stopAfterSteps, stopWhen, stopWhenNoToolCalls, toMessageContent, toUIMessageStreamResponse, transcribe, uint8ArrayToBase64, validateUIMessages, withApproval, withSpan, wrapModel } from "./ai";
+  convertToModelMessages, AIAgentStep, AIEmbedManyResult, AIEmbedOptions, AIEmbedResult, AIFilePart, AIGenerateImageOptions, AIGenerateImageResult, AIGenerateObjectOptions, AIGenerateObjectResult, AIGenerateTextOptions, AIGenerateTextResult, AIImagePart, AIMiddleware, AIMiddlewareConfig, AIModelMessage, AISpan, AISpanKind, AISpanOptions, AISpanStatus, AIStreamObjectOptions, AIStreamObjectResult, AIStreamTextOptions, AIStreamTextResult, AITelemetryEvent, AITelemetrySettings, AITextPart, AIToolDefinition, AITracer, AgentLoop, DANGEROUS_PATTERNS, MCPClientType, MODEL_ALIASES, SPEECH_MODELS, TRANSCRIPTION_MODELS, ToolApprovalDeniedError, ToolApprovalTimeoutError, aiEmbed, aiEmbedMany, aiGenerateImage, aiGenerateObject, aiGenerateText, aiStreamObject, aiStreamText, applyMiddleware, autoEnableDevTools, base64ToUint8Array, clearAICache, clearEvents, closeAllMCPClients, closeMCPClient, convertToUIMessages, createAILoggingMiddleware, createAISpan, createApprovalResponse, createDangerousPatternChecker, createDevToolsMiddleware, createExpressHandler, createFastifyHandler, createFilePart, createHonoHandler, createMultimodalMessage, createNestHandler, createPagesHandler, createPdfPart, createSystemMessage, createTelemetryMiddleware, createTelemetrySettings, createTextMessage, createTextPart, createToolSet, disableAITelemetry, disableDevTools, enableAITelemetry, functionToTool, getAICacheStats, getApprovalManager, getDevToolsState, getDevToolsUrl, getEvents, getMCPClient, getModel, getTelemetrySettings, getToolsNeedingApproval, getTracer, hasModelAlias, hasPendingApprovals, initOpenTelemetry, isDangerous, isDataUrl, isDevToolsEnabled, isTelemetryEnabled, isUrl, listModelAliases, mcpToolsToAITools, parseModel, pipeUIMessageStreamToResponse, recordEvent, resolveModelAlias, safeValidateUIMessages, setApprovalManager, stopAfterSteps, stopWhen, stopWhenNoToolCalls, toMessageContent, toUIMessageStreamResponse, transcribe, uint8ArrayToBase64, validateUIMessages, withApproval, withSpan, wrapModel } from "./ai";
 export { AutoAgents, createAutoAgents } from "./auto";
 export { BaseCache, FileCache, MemoryCache, createFileCache, createMemoryCache } from "./cache";
 export { CLI_SPEC_VERSION, executeCommand, parseArgs } from "./cli";
@@ -392,9 +1062,11 @@ export type { DbAdapter, DbConfig, DbMessage, DbRun, DbTrace } from "./db";
 export { MemoryPostgresAdapter, NeonPostgresAdapter, PostgresSessionStorage, createMemoryPostgres, createNeonPostgres, createPostgresSessionStorage } from "./db/postgres";
 export { MemoryRedisAdapter, UpstashRedisAdapter, createMemoryRedis, createUpstashRedis } from "./db/redis";
 export { SQLiteAdapter, createSQLiteAdapter } from "./db/sqlite";
-export { EvalSuite, accuracyEval, performanceEval, reliabilityEval } from "./eval";
+export { // LLM-as-Judge
+  Judge, AccuracyJudge, CriteriaJudge, EvalResults, EvalSuite, Evaluator, RecipeJudge, accuracyEval, addJudge, addOptimizationRule, containsKeywordsCriterion, createDefaultEvaluator, createEvalResults, createEvaluator, getJudge, getOptimizationRule, lengthCriterion, listJudges, listOptimizationRules, noHarmfulContentCriterion, parseJudgeResponse, performanceEval, relevanceCriterion, reliabilityEval, removeJudge, removeOptimizationRule } from "./eval";
 export { AgentEventBus, AgentEvents, EventEmitterPubSub, PubSub, createEventBus, createPubSub } from "./events";
 export { LLMGuardrail, createLLMGuardrail } from "./guardrails/llm-guardrail";
+export { DisplayTypes, HooksManager, WorkflowHooksExecutor, clearAllCallbacks, clearApprovalCallback, createHooksManager, createLoggingOperationHooks, createLoggingWorkflowHooks, createTimingWorkflowHooks, createValidationOperationHooks, createWorkflowHooks, executeCallback, executeSyncCallback, getRegisteredDisplayTypes, hasApprovalCallback, registerApprovalCallback, registerDisplayCallback, requestApproval, unregisterDisplayCallback } from "./hooks";
 export { // Computer Use
  createComputerUse, ComputerUseClient, createCLIApprovalPrompt, createComputerUseAgent } from "./integrations/computer-use";
 export { BaseObservabilityProvider, ConsoleObservabilityProvider, LangfuseObservabilityProvider, MemoryObservabilityProvider, ObservabilityTraceContext, createConsoleObservability, createLangfuseObservability, createMemoryObservability } from "./integrations/observability";
@@ -412,10 +1084,14 @@ export { // Provider classes
  ProviderRegistry, // Types
  type LLMProvider, AnthropicProvider, BaseProvider, GoogleProvider, ProviderMessage, ProviderToolDefinition, createProviderRegistry, getAvailableProviders, getDefaultProvider, getDefaultRegistry, hasProvider, isProviderAvailable, listProviders, parseModelString, registerBuiltinProviders, registerProvider, unregisterProvider } from "./llm/providers";
 export { ADAPTERS, AISDK_PROVIDERS, COMMUNITY_PROVIDERS, PROVIDER_ALIASES } from "./llm/providers/ai-sdk/types";
+export { MCPClient, MCPSecurity, MCPServer, MCPSessionManager, createApiKeyPolicy, createMCPClient, createMCPSecurity, createMCPServer, createMCPSession, createRateLimitPolicy, getMCPTools } from "./mcp";
 export { AutoMemory, AutoMemoryKnowledgeBase, AutoMemoryVectorStore, DEFAULT_POLICIES, createAutoMemory, createLLMSummarizer } from "./memory/auto-memory";
+export { DocsManager, createDocsManager } from "./memory/docs-manager";
 export { FileMemory, createFileMemory } from "./memory/file-memory";
+export { MemoryHooks, createEncryptionHooks, createLoggingHooks, createMemoryHooks, createValidationHooks } from "./memory/hooks";
 export { Memory, createMemory } from "./memory/memory";
 export type { MemoryConfig, MemoryEntry } from "./memory/memory";
+export { RulesManager, createRulesManager, createSafetyRules } from "./memory/rules-manager";
 export { // Adapters
  NoopObservabilityAdapter, // Constants
  OBSERVABILITY_TOOLS, // Global adapter management
@@ -423,14 +1099,17 @@ export { // Adapters
  type SpanKind, ConsoleObservabilityAdapter, MemoryObservabilityAdapter, clearAdapterCache, createConsoleAdapter, createMemoryAdapter, createObservabilityAdapter, getObservabilityAdapter, getObservabilityToolInfo, hasObservabilityToolEnvVar, listObservabilityTools, noopAdapter, resetObservabilityAdapter, trace } from "./observability";
 export { Plan, PlanStep, PlanStorage, PlanningAgent, TaskAgent, TodoItem, TodoList, createPlan, createPlanStorage, createPlanningAgent, createTaskAgent, createTodoList } from "./planning";
 export { SkillManager, createSkillManager, parseSkillFile } from "./skills";
-export { AgentTelemetry, TelemetryCollector, cleanupTelemetry, createAgentTelemetry, disableTelemetry, enableTelemetry, getTelemetry } from "./telemetry";
-export { BaseTool, FunctionTool, ToolRegistry, ToolResult, ToolValidationError, createTool, getRegistry, getTool, registerTool, tool, validateTool } from "./tools";
+export { AgentTelemetry, PerformanceMonitor, TelemetryCollector, TelemetryIntegration, cleanupTelemetry, createAgentTelemetry, createConsoleSink, createHTTPSink, createPerformanceMonitor, createTelemetryIntegration, disableTelemetry, enableTelemetry, getTelemetry } from "./telemetry";
+export { // Subagent Tool (agent-as-tool pattern)
+  SubagentTool, BaseTool, FunctionTool, ToolRegistry, ToolResult, ToolValidationError, createDelegator, createSubagentTool, createSubagentTools, createTool, getRegistry, getTool, registerTool, tool, validateTool } from "./tools";
 export { airweaveSearch, bedrockBrowserClick, bedrockBrowserFill, bedrockBrowserNavigate, bedrockCodeInterpreter, codeExecution, codeMode, createCustomTool, exaSearch, firecrawlCrawl, firecrawlScrape, parallelSearch, perplexitySearch, registerCustomTool, registerLocalTool, registerNpmTool, superagentGuard, superagentRedact, superagentVerify, tavilyCrawl, tavilyExtract, tavilySearch, valyuBioSearch, valyuCompanyResearch, valyuEconomicsSearch, valyuFinanceSearch, valyuPaperSearch, valyuPatentSearch, valyuSecSearch, valyuWebSearch } from "./tools/builtins";
 export { MissingDependencyError, MissingEnvVarError, ToolsRegistry, composeMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createRedactionMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolsRegistry, createTracingMiddleware, createValidationMiddleware, getToolsRegistry, resetToolsRegistry } from "./tools/registry";
 export type { InstallHints, PraisonTool, RedactionHooks, RegisteredTool, ToolCapabilities, ToolExecutionContext, ToolExecutionResult, ToolFactory, ToolHooks, ToolInstallStatus, ToolLimits, ToolLogger, ToolMetadata, ToolMiddleware, ToolParameterProperty, ToolParameterSchema } from "./tools/registry";
 export { registerBuiltinTools, tools } from "./tools/tools";
-export { Workflow, loop, parallel, repeat, route } from "./workflows";
-export type { StepResult, WorkflowContext, WorkflowStep } from "./workflows";
+export { // New: Python-parity Loop and Repeat classes
+  Loop, // WorkflowStep class
+  WorkflowStep, Repeat, Workflow, loop, loopPattern, parallel, repeat, repeatPattern, route } from "./workflows";
+export type { LoopConfig, LoopResult, RepeatConfig, RepeatContext, RepeatResult, StepContextConfig, StepExecutionConfig, StepOutputConfig, StepResult, StepRoutingConfig, WorkflowContext, WorkflowStepConfig } from "./workflows";
 export { createWorkflowFromYAML, loadWorkflowFromFile, parseYAMLWorkflow, validateWorkflowDefinition } from "./workflows/yaml-parser";
 ```

@@ -13,6 +13,12 @@ GOOGLE_API_KEY=your_google_api_key_here
 GROQ_API_KEY=your_groq_api_key_here
 COHERE_API_KEY=your_cohere_api_key_here

+# Bot Tokens (for messaging bot services)
+SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
+SLACK_APP_TOKEN=xapp-your-slack-app-token
+DISCORD_BOT_TOKEN=your-discord-bot-token
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
+
 # Optional: Service Configuration
 FLASK_ENV=development
 CHAINLIT_HOST=0.0.0.0
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=3.9.4" \
+    "praisonai>=3.12.2" \
    "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>=3.9.4" \
+    "praisonai>=3.12.2" \
    "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>=3.9.4" \
+    "praisonai>=3.12.2" \
    "praisonai[ui]" \
    "praisonai[crewai]"

@@ -0,0 +1,15 @@
+# Bot Environment Variables
+# Copy to .env and fill in your values
+
+# Required: LLM API Key
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Slack Bot (Socket Mode)
+SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
+SLACK_APP_TOKEN=xapp-your-slack-app-token
+
+# Discord Bot
+DISCORD_BOT_TOKEN=your-discord-bot-token
+
+# Telegram Bot
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
@@ -0,0 +1,42 @@
+# Dockerfile for PraisonAI Slack Bot
+# Secrets are passed at runtime via environment variables
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    python3-dev \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create praison config directory
+RUN mkdir -p /root/.praison
+
+# Install praisonai with bot dependencies
+RUN pip install --no-cache-dir \
+    praisonai \
+    slack-bolt \
+    slack-sdk \
+    "discord.py>=2.0.0" \
+    "python-telegram-bot>=20.0"
+
+# Set environment variables for directory management
+ENV PRAISON_CONFIG_DIR=/root/.praison
+ENV DOCKER_CONTAINER=true
+
+# Bot tokens should be passed at runtime (not baked into image)
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...
+
+# Optional: Copy custom agent configuration
+# COPY agent.yaml /app/agent.yaml
+
+# Expose no ports - Socket Mode doesn't need them
+# For webhook mode, expose port 3000
+
+# Default command - tokens from environment
+CMD ["praisonai", "bot", "slack"]
@@ -0,0 +1,66 @@
+# PraisonAI Bot Docker Deployment
+
+Deploy Slack, Discord, or Telegram bots using Docker.
+
+## Quick Start
+
+```bash
+# 1. Copy environment template
+cp .env.template .env
+
+# 2. Edit .env with your tokens
+nano .env
+
+# 3. Run specific bot
+docker compose up slack-bot -d
+
+# Or run all bots
+docker compose up -d
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes | LLM API key |
+| `SLACK_BOT_TOKEN` | For Slack | Bot token (xoxb-...) |
+| `SLACK_APP_TOKEN` | For Slack | App token (xapp-...) |
+| `DISCORD_BOT_TOKEN` | For Discord | Bot token |
+| `TELEGRAM_BOT_TOKEN` | For Telegram | Bot token |
+
+## Slack Setup
+
+1. Create app at https://api.slack.com/apps
+2. Enable **Socket Mode** → Generate App-Level Token with `connections:write`
+3. Add **OAuth Scopes**: `chat:write`, `app_mentions:read`, `im:history`
+4. Enable **Event Subscriptions** → Subscribe to `app_mention`, `message.im`
+5. **Install to Workspace**
+6. Copy Bot Token and App Token to `.env`
+
+## Commands
+
+```bash
+# Start Slack bot
+docker compose up slack-bot -d
+
+# View logs
+docker compose logs -f slack-bot
+
+# Stop bot
+docker compose down slack-bot
+
+# Rebuild after updates
+docker compose build --no-cache slack-bot
+```
+
+## Custom Agent Configuration
+
+Mount your agent config:
+
+```yaml
+services:
+  slack-bot:
+    volumes:
+      - ./agent.yaml:/app/agent.yaml
+    command: ["praisonai", "bot", "slack", "--agent", "/app/agent.yaml"]
+```
@@ -0,0 +1,53 @@
+version: '3.8'
+
+# PraisonAI Bot Services
+# Run specific bots: docker compose up slack-bot
+# Run all bots: docker compose up
+
+services:
+  # Slack Bot
+  slack-bot:
+    build:
+      context: ../..
+      dockerfile: docker/bots/Dockerfile
+    volumes:
+      - praison_data:/root/.praison
+    environment:
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}
+      SLACK_APP_TOKEN: ${SLACK_APP_TOKEN}
+      PRAISON_CONFIG_DIR: /root/.praison
+    command: [ "praisonai", "bot", "slack" ]
+    restart: unless-stopped
+
+  # Discord Bot
+  discord-bot:
+    build:
+      context: ../..
+      dockerfile: docker/bots/Dockerfile
+    volumes:
+      - praison_data:/root/.praison
+    environment:
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN}
+      PRAISON_CONFIG_DIR: /root/.praison
+    command: [ "praisonai", "bot", "discord" ]
+    restart: unless-stopped
+
+  # Telegram Bot
+  telegram-bot:
+    build:
+      context: ../..
+      dockerfile: docker/bots/Dockerfile
+    volumes:
+      - praison_data:/root/.praison
+    environment:
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
+      PRAISON_CONFIG_DIR: /root/.praison
+    command: [ "praisonai", "bot", "telegram" ]
+    restart: unless-stopped
+
+volumes:
+  praison_data:
+    driver: local
@@ -22,7 +22,7 @@ services:
      CHAINLIT_DB_DIR: /root/.praison
    command: praisonai ui --host 0.0.0.0
    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8082"]
+      test: [ "CMD", "curl", "-f", "http://localhost:8082" ]
      interval: 10s
      timeout: 5s
      retries: 3
@@ -49,7 +49,7 @@ services:
      CHAINLIT_DB_DIR: /root/.praison
    command: praisonai chat --host 0.0.0.0 --port 8083
    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8083"]
+      test: [ "CMD", "curl", "-f", "http://localhost:8083" ]
      interval: 10s
      timeout: 5s
      retries: 3
@@ -69,7 +69,7 @@ services:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      PRAISON_CONFIG_DIR: /root/.praison
    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      test: [ "CMD", "curl", "-f", "http://localhost:8080/health" ]
      interval: 10s
      timeout: 5s
      retries: 3
@@ -89,6 +89,7 @@ services:
      PRAISON_CONFIG_DIR: /root/.praison
    networks:
      - praison_network
+  # For bot services (Slack, Discord, Telegram), see docker/bots/

 volumes:
  praison_data:
@@ -96,4 +97,4 @@ volumes:

 networks:
  praison_network:
-    driver: bridge
+    driver: bridge
@@ -2,12 +2,14 @@
 Embeddings Capability Example

 Demonstrates text embedding generation using PraisonAI capabilities.
+Both `embed` and `embedding` work identically - use whichever you prefer.
 """

-from praisonai.capabilities import embed
+from praisonai import embed, embedding  # Both work from top-level
+# Or: from praisonai.capabilities import embed, embedding

-# Single text embedding
-print("=== Single Text Embedding ===")
+# Single text embedding using embed()
+print("=== Single Text Embedding (using embed) ===")
 result = embed(
    input="Hello, world!",
    model="text-embedding-3-small"
@@ -16,6 +18,14 @@ print(f"Embedding dimensions: {len(result.embeddings[0])}")
 print(f"First 5 values: {result.embeddings[0][:5]}")
 print(f"Usage: {result.usage}")

+# Same thing using embedding() alias
+print("\n=== Single Text Embedding (using embedding alias) ===")
+result = embedding(
+    input="Hello, world!",
+    model="text-embedding-3-small"
+)
+print(f"Embedding dimensions: {len(result.embeddings[0])}")
+
 # Multiple text embeddings
 print("\n=== Multiple Text Embeddings ===")
 result = embed(
@@ -25,3 +35,12 @@ result = embed(
 print(f"Number of embeddings: {len(result.embeddings)}")
 for i, emb in enumerate(result.embeddings):
    print(f"  Text {i+1}: {len(emb)} dimensions")
+
+# With custom dimensions (for models that support it)
+print("\n=== Custom Dimensions ===")
+result = embed(
+    input="Hello world",
+    model="text-embedding-3-large",
+    dimensions=256
+)
+print(f"Reduced dimensions: {len(result.embeddings[0])}")
@@ -1,21 +1,24 @@
-"""
-Basic Memory Example - Agent-Centric API
-
-Demonstrates the simplest memory usage with consolidated params.
-"""
-
+"""Basic memory example - minimal usage."""
 from praisonaiagents import Agent

-# Basic: Enable memory with preset
+# Simple enable (uses default file-based memory)
 agent = Agent(
    instructions="You are a helpful assistant with memory.",
-    memory="sqlite",  # Preset: sqlite, redis, postgres, file
+    memory=True,
 )

-# Run a simple task
-response = agent.start("Remember that my favorite color is blue.")
-print(response)
+# With preset
+agent_redis = Agent(
+    instructions="You are a helpful assistant.",
+    memory="redis",  # Uses redis preset
+)

-# Follow-up to test memory
-response = agent.start("What is my favorite color?")
-print(response)
+# With URL
+agent_postgres = Agent(
+    instructions="You are a helpful assistant.",
+    memory="postgresql://localhost/mydb",  # URL auto-detected
+)
+
+if __name__ == "__main__":
+    response = agent.chat("Remember that my favorite color is blue.")
+    print(response)
@@ -1,26 +1,22 @@
-"""
-Basic Workflow Example - Agent-Centric API
-
-Demonstrates minimal workflow with consolidated params.
-"""
-
+"""Basic workflow example with consolidated params."""
 from praisonaiagents import Agent
 from praisonaiagents.workflows import Workflow, WorkflowStep

-# Create a simple workflow
+# Create agents
+writer = Agent(instructions="You are a content writer.")
+editor = Agent(instructions="You are an editor.")
+
+# Create workflow with consolidated params
 workflow = Workflow(
-    name="simple_workflow",
-    output="verbose",  # Workflow-level output preset
+    name="Content Pipeline",
+    steps=[
+        WorkflowStep(name="write", agent=writer, action="Write about {{topic}}"),
+        WorkflowStep(name="edit", agent=editor, action="Edit the content", context=["write"]),
+    ],
+    output="verbose",
+    planning=True,
 )

-# Add a step
-step = WorkflowStep(
-    name="writer",
-    action="Write a haiku about programming",
-    agent=Agent(instructions="You are a creative poet."),
-    output="result.txt",  # Save output to file
-)
-
-# Note: This is a structural example - actual execution requires workflow.run()
-print("Workflow created with output preset:", workflow.output)
-print("Step output file:", step.output_file)
+if __name__ == "__main__":
+    result = workflow.run(variables={"topic": "AI agents"})
+    print(result)
@@ -0,0 +1,59 @@
+"""
+Basic Context Management Example
+
+Demonstrates enabling context management with ContextConfig.
+This manages token budgets, auto-compaction, and prevents context overflow.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import ContextConfig, OptimizerStrategy
+
+# Example 1: Enable context with defaults
+agent_basic = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant",
+    context=True  # Auto-compact at 80% utilization
+)
+
+# Example 2: Custom configuration
+agent_custom = Agent(
+    name="CustomAgent",
+    instructions="You are a helpful assistant with custom context settings",
+    context=ContextConfig(
+        auto_compact=True,
+        compact_threshold=0.8,      # Trigger at 80% utilization
+        strategy=OptimizerStrategy.SMART,
+        output_reserve=8000,        # Reserve tokens for output
+        keep_recent_turns=5,        # Always keep last 5 turns
+        tool_output_max=10000,      # Max tokens per tool output
+    )
+)
+
+# Example 3: Sliding window strategy
+agent_sliding = Agent(
+    name="SlidingAgent",
+    instructions="You are a helpful assistant using sliding window",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SLIDING_WINDOW,
+        keep_recent_turns=10,       # Keep last 10 turns
+    )
+)
+
+if __name__ == "__main__":
+    print("=== Basic Context Example ===")
+    print("Context management is automatically enabled.")
+    print()
+    
+    # Test basic agent
+    result = agent_basic.chat("Hello! What is 2 + 2?")
+    print(f"Response: {result}")
+    print()
+    
+    # Show context config
+    print("=== Context Configuration ===")
+    config = ContextConfig(
+        auto_compact=True,
+        compact_threshold=0.8,
+        strategy=OptimizerStrategy.SMART,
+    )
+    print(f"Config: {config.to_dict()}")
@@ -0,0 +1,71 @@
+"""
+Session Tracking Example
+
+Demonstrates tracking conversation state (goal, plan, progress) across turns.
+Inspired by Agno's SessionContextStore pattern.
+"""
+
+from praisonaiagents.context import SessionContextTracker
+
+# Create session tracker
+tracker = SessionContextTracker(
+    session_id="user123",
+    track_summary=True,
+    track_goal=True,
+    track_plan=True,
+    track_progress=True,
+)
+
+# Set the user's goal
+tracker.update_goal("Build a Python web application with Flask")
+
+# Define the plan
+tracker.update_plan([
+    "Create Flask project structure",
+    "Add routes for API endpoints",
+    "Implement database models",
+    "Add authentication",
+    "Write tests",
+    "Deploy to cloud"
+])
+
+# Mark completed steps
+tracker.add_progress("Created Flask project structure")
+tracker.add_progress("Added routes for API endpoints")
+
+# Update summary
+tracker.update_summary(
+    "User is building a Flask web app. Completed project setup and API routes. "
+    "Next: implement database models."
+)
+
+if __name__ == "__main__":
+    print("=== Session Tracking Example ===")
+    print()
+    
+    # Show current state
+    print(f"Session ID: {tracker.session_id}")
+    print(f"Goal: {tracker.goal}")
+    print(f"Plan: {tracker.plan}")
+    print(f"Progress: {tracker.progress}")
+    print()
+    
+    # Get context string (simple format)
+    print("=== Context String ===")
+    print(tracker.to_context_string())
+    print()
+    
+    # Get system prompt section (XML format with guidelines)
+    print("=== System Prompt Section ===")
+    print(tracker.to_system_prompt_section())
+    print()
+    
+    # Export to dict for persistence
+    print("=== Export as Dict ===")
+    data = tracker.to_dict()
+    print(f"Exported: {data.keys()}")
+    print()
+    
+    # Recreate from dict
+    new_tracker = SessionContextTracker.from_dict(data)
+    print(f"Restored goal: {new_tracker.goal}")
@@ -0,0 +1,81 @@
+"""
+Multi-Memory Aggregation Example
+
+Demonstrates concurrent fetching from multiple context sources.
+Inspired by CrewAI's ContextualMemory pattern.
+"""
+
+import asyncio
+from praisonaiagents.context import ContextAggregator, create_aggregator_from_config
+
+# Example 1: Basic aggregator with mock sources
+def mock_memory_search(query: str) -> str:
+    """Mock memory search - returns recent conversation context."""
+    return f"[Memory] User previously asked about: {query}. They prefer Python."
+
+def mock_knowledge_search(query: str) -> str:
+    """Mock knowledge search - returns facts from knowledge base."""
+    return f"[Knowledge] Relevant facts: Python is a high-level programming language."
+
+def mock_rag_retrieve(query: str) -> str:
+    """Mock RAG retrieval - returns document chunks."""
+    return f"[RAG] Retrieved: Documentation about {query} from the codebase."
+
+# Create aggregator
+aggregator = ContextAggregator(
+    max_tokens=4000,
+    separator="\n\n---\n\n",
+    include_source_labels=True
+)
+
+# Register sources with priorities (lower = higher priority)
+aggregator.register_source("memory", mock_memory_search, priority=10)
+aggregator.register_source("knowledge", mock_knowledge_search, priority=20)
+aggregator.register_source("rag", mock_rag_retrieve, priority=30)
+
+async def demo_async():
+    """Demo async aggregation."""
+    print("=== Async Aggregation ===")
+    result = await aggregator.aggregate("Python web development")
+    print(f"Sources used: {result.sources_used}")
+    print(f"Tokens used: {result.tokens_used}")
+    print(f"Fetch times: {result.fetch_times}")
+    print()
+    print("Context:")
+    print(result.context)
+    return result
+
+def demo_sync():
+    """Demo sync aggregation."""
+    print("=== Sync Aggregation ===")
+    result = aggregator.aggregate_sync("Flask API development")
+    print(f"Sources used: {result.sources_used}")
+    print(f"Tokens used: {result.tokens_used}")
+    print()
+    print("Context:")
+    print(result.context)
+    return result
+
+if __name__ == "__main__":
+    print("=== Multi-Memory Aggregation Example ===")
+    print()
+    
+    # Show registered sources
+    print(f"Registered sources: {aggregator.sources}")
+    print()
+    
+    # Demo sync aggregation
+    demo_sync()
+    print()
+    
+    # Demo async aggregation
+    asyncio.run(demo_async())
+    print()
+    
+    # Demo selective sources
+    print("=== Selective Sources ===")
+    result = aggregator.aggregate_sync(
+        "Find database info",
+        sources=["memory", "knowledge"]  # Only use these
+    )
+    print(f"Sources used: {result.sources_used}")
@@ -0,0 +1,76 @@
+"""
+Compaction Strategies Example
+
+Demonstrates different context compaction strategies.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import ContextConfig, OptimizerStrategy
+
+# Strategy 1: TRUNCATE - Fast, removes oldest messages
+agent_truncate = Agent(
+    name="TruncateAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.TRUNCATE,
+        compact_threshold=0.8,
+    )
+)
+
+# Strategy 2: SLIDING_WINDOW - Keeps recent N turns
+agent_sliding = Agent(
+    name="SlidingAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SLIDING_WINDOW,
+        keep_recent_turns=10,
+    )
+)
+
+# Strategy 3: SMART - Importance-based (default)
+agent_smart = Agent(
+    name="SmartAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SMART,  # Default
+        compact_threshold=0.8,
+    )
+)
+
+# Strategy 4: PRUNE_TOOLS - Truncate old tool outputs
+agent_prune = Agent(
+    name="PruneAgent",
+    instructions="You are a helpful assistant with tools",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.PRUNE_TOOLS,
+        tool_output_max=5000,  # Max tokens per tool output
+    )
+)
+
+# Strategy 5: NON_DESTRUCTIVE - Only prune tools, keep all history
+agent_safe = Agent(
+    name="SafeAgent",
+    instructions="You are a helpful assistant (safety-critical)",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.NON_DESTRUCTIVE,
+    )
+)
+
+if __name__ == "__main__":
+    print("=== Compaction Strategies Example ===")
+    print()
+    
+    strategies = [
+        ("TRUNCATE", OptimizerStrategy.TRUNCATE, "Remove oldest messages"),
+        ("SLIDING_WINDOW", OptimizerStrategy.SLIDING_WINDOW, "Keep last N turns"),
+        ("SMART", OptimizerStrategy.SMART, "Importance-based (default)"),
+        ("PRUNE_TOOLS", OptimizerStrategy.PRUNE_TOOLS, "Truncate tool outputs"),
+        ("NON_DESTRUCTIVE", OptimizerStrategy.NON_DESTRUCTIVE, "Only prune tools"),
+    ]
+    
+    for name, strategy, description in strategies:
+        print(f"  {name:20} - {description}")
+    
+    print()
+    print("Usage:")
+    print("  context=ContextConfig(strategy=OptimizerStrategy.SLIDING_WINDOW)")
@@ -0,0 +1,85 @@
+"""
+Context Monitoring Example
+
+Demonstrates monitoring context usage with logging and metrics.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import ContextConfig, MonitorConfig, OptimizerStrategy
+
+# Example 1: Human-readable monitoring
+agent_human = Agent(
+    name="MonitoredAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        auto_compact=True,
+        monitor=MonitorConfig(
+            enabled=True,
+            path="./context_logs/",
+            format="human",           # Human-readable format
+            frequency="turn",         # Log on every turn
+            redact_sensitive=True,    # Redact sensitive data
+            multi_agent_files=True,   # Separate files per agent
+        )
+    )
+)
+
+# Example 2: JSON monitoring (for parsing)
+agent_json = Agent(
+    name="JSONMonitorAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        monitor=MonitorConfig(
+            enabled=True,
+            path="./context_logs/",
+            format="json",            # JSON format for parsing
+            frequency="tool_call",    # Log on tool calls
+        )
+    )
+)
+
+# Example 3: Overflow-only monitoring
+agent_overflow = Agent(
+    name="OverflowAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        monitor=MonitorConfig(
+            enabled=True,
+            path="./context_logs/",
+            format="human",
+            frequency="overflow",     # Only log on overflow
+        )
+    )
+)
+
+if __name__ == "__main__":
+    print("=== Context Monitoring Example ===")
+    print()
+    
+    # Show monitor configuration
+    config = MonitorConfig(
+        enabled=True,
+        path="./context_logs/",
+        format="human",
+        frequency="turn",
+        redact_sensitive=True,
+    )
+    
+    print("Monitor Config:")
+    print(f"  enabled: {config.enabled}")
+    print(f"  path: {config.path}")
+    print(f"  format: {config.format}")
+    print(f"  frequency: {config.frequency}")
+    print(f"  redact_sensitive: {config.redact_sensitive}")
+    print()
+    
+    print("Frequency options:")
+    print("  'turn'      - Log on every conversation turn")
+    print("  'tool_call' - Log when tools are called")
+    print("  'manual'    - Manual logging only")
+    print("  'overflow'  - Log only when context overflows")
+    print()
+    
+    print("Format options:")
+    print("  'human' - Human-readable format")
+    print("  'json'  - JSON format for parsing")
@@ -0,0 +1,274 @@
+"""
+Example 15: Recursive Context Pattern
+
+Demonstrates the RLM (Recursive Language Model) pattern for handling large context:
+- Store large documents as artifacts (not in LLM context)
+- Agent uses tools (grep/head/tail/chunk) to explore artifacts
+- Dramatically reduces token usage (~2K vs ~10K+)
+
+This pattern solves "context rot" by treating context as programmatically
+explorable data instead of dumping everything into the LLM's context window.
+"""
+
+import tempfile
+import os
+from praisonaiagents import Agent
+from praisonai.context import FileSystemArtifactStore
+from praisonai.context.queue import create_artifact_tools
+from praisonaiagents.context.artifacts import ArtifactMetadata
+
+
+def create_sample_document():
+    """Create a sample large document for testing."""
+    # Simulate a research paper / large document
+    content = """
+# Attention Is All You Need
+
+## Abstract
+
+The dominant sequence transduction models are based on complex recurrent or 
+convolutional neural networks that include an encoder and a decoder. The best
+performing models also connect the encoder and decoder through an attention
+mechanism. We propose a new simple network architecture, the Transformer,
+based solely on attention mechanisms, dispensing with recurrence and convolutions
+entirely. 
+
+## Introduction
+
+Recurrent neural networks, long short-term memory and gated recurrent neural 
+networks in particular, have been firmly established as state of the art 
+approaches in sequence modeling and transduction problems such as language 
+modeling and machine translation. 
+
+## Background
+
+The goal of reducing sequential computation also forms the foundation of the 
+Extended Neural GPU, ByteNet and ConvS2S, all of which use convolutional neural
+networks as basic building block.
+
+## Model Architecture
+
+### Encoder and Decoder Stacks
+
+The encoder is composed of a stack of N = 6 identical layers. Each layer has 
+two sub-layers. The first is a multi-head self-attention mechanism, and the 
+second is a simple, position-wise fully connected feed-forward network.
+
+### Attention
+
+An attention function can be described as mapping a query and a set of key-value
+pairs to an output, where the query, keys, values, and output are all vectors.
+
+#### Scaled Dot-Product Attention
+
+We call our particular attention "Scaled Dot-Product Attention". The input 
+consists of queries and keys of dimension dk, and values of dimension dv.
+
+The formula is: Attention(Q, K, V) = softmax(QK^T / sqrt(d_k))V
+
+### Multi-Head Attention
+
+Multi-head attention allows the model to jointly attend to information from
+different representation subspaces at different positions.
+
+## Results
+
+### Machine Translation
+
+On the WMT 2014 English-to-German translation task, the big transformer model
+outperforms the best previously reported models including ensembles.
+
+The model achieved a BLEU score of 28.4 on the WMT 2014 English-to-German 
+translation task, improving over the existing best results by over 2 BLEU.
+
+On the WMT 2014 English-to-French translation task, our big model achieves 
+a BLEU score of 41.8, outperforming all published single models.
+
+### Training
+
+Training took 3.5 days on 8 P100 GPUs. The big model was trained for 300,000
+steps (3.5 days) at a cost of approximately $1000 in cloud compute.
+
+## Model Variations
+
+| Model | Parameters | BLEU EN-DE | BLEU EN-FR |
+|-------|------------|------------|------------|
+| Base  | 65M        | 27.3       | 38.1       |
+| Big   | 213M       | 28.4       | 41.8       |
+
+The base model has 65 million parameters (65 × 10^6).
+The big model has 213 million parameters.
+
+## Conclusion
+
+In this work, we presented the Transformer, the first sequence transduction
+model based entirely on attention, replacing the recurrent layers most commonly
+used in encoder-decoder architectures with multi-headed self-attention.
+
+The Transformer can be trained significantly faster than architectures based
+on recurrent or convolutional layers.
+
+## Authors
+
+Ashish Vaswani (Google Brain)
+Noam Shazeer (Google Brain)
+Niki Parmar (Google Research)
+Jakob Uszkoreit (Google Research)
+Llion Jones (Google Research)
+Aidan N. Gomez (University of Toronto)
+Łukasz Kaiser (Google Brain)
+Illia Polosukhin
+
+## References
+
+[1] Neural Machine Translation by Jointly Learning to Align and Translate
+[2] Sequence to Sequence Learning with Neural Networks
+[3] Learning Phrase Representations using RNN Encoder-Decoder
+"""
+    # Repeat content to make it larger
+    full_content = (content + "\n\n") * 10  # ~35KB
+    return full_content
+
+
+def main():
+    print("=" * 70)
+    print("Recursive Context Pattern - Token Efficiency Demo")
+    print("=" * 70)
+    
+    # Track token usage across methods
+    token_stats = {
+        "traditional": {"input": 0, "output": 0},
+        "recursive": {"input": 0, "output": 0},
+    }
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # 1. Create artifact store and tools
+        store = FileSystemArtifactStore(base_dir=tmpdir)
+        artifact_tools = create_artifact_tools(store=store)
+        
+        print(f"\n1. Created FileSystemArtifactStore")
+        print(f"   Location: {tmpdir}")
+        print(f"   Tools available: {[t.__name__ for t in artifact_tools]}")
+        
+        # 2. Create sample document and store as artifact
+        document = create_sample_document()
+        doc_size = len(document)
+        doc_tokens = doc_size // 4  # Rough estimate: 4 chars per token
+        
+        metadata = ArtifactMetadata(
+            agent_id="research_agent",
+            run_id="demo_run",
+            tool_name="document_loader",
+            turn_id=1
+        )
+        
+        ref = store.store(document, metadata)
+        
+        print(f"\n2. Stored document as artifact")
+        print(f"   Size: {doc_size:,} chars (~{doc_tokens:,} tokens)")
+        print(f"   Path: {ref.path}")
+        print(f"   Summary: {ref.summary[:80]}...")
+        
+        # 3. Create agent WITH artifact tools (Recursive Context approach)
+        agent = Agent(
+            instructions="""You are a research paper analyst with access to artifact exploration tools.
+When given an artifact path, use the tools to explore it efficiently:
+- artifact_grep: Search for patterns (USE THIS FIRST)
+- artifact_head: See first N lines
+- artifact_tail: See last N lines
+- artifact_chunk: Get specific line ranges
+
+Be precise and cite line numbers when finding information.""",
+            tools=artifact_tools,
+            output='silent'  # Quiet output for cleaner demo
+        )
+        
+        print(f"\n3. Created agent with {len(agent.tools)} artifact tools")
+        
+        # 4. Query using RECURSIVE CONTEXT (small prompt + tools)
+        print(f"\n4. RECURSIVE CONTEXT APPROACH")
+        print("-" * 40)
+        
+        prompt = f"""I have a research paper stored at: {ref.path}
+
+Find the BLEU score on the WMT 2014 English-to-German translation task.
+Use artifact_grep to search, then report the answer with line number."""
+
+        prompt_tokens = len(prompt) // 4
+        print(f"   Prompt size: {len(prompt)} chars (~{prompt_tokens} tokens)")
+        print(f"   Document NOT in prompt context!")
+        
+        response = agent.chat(prompt)
+        
+        # Estimate output tokens (could use actual LiteLLM response if available)
+        output_tokens = len(response) // 4
+        
+        # Calculate recursive approach tokens (prompt + tool calls + response)
+        # Tool call: ~200 tokens for tool desc + call
+        # Tool response: ~300 tokens for grep results
+        estimated_total = prompt_tokens + 200 + 300 + output_tokens
+        token_stats["recursive"]["input"] = estimated_total
+        
+        print(f"\n   Agent Response:")
+        print(f"   {response[:200]}...")
+        print(f"\n   Estimated tokens used: ~{estimated_total:,}")
+        
+        # 5. Compare with TRADITIONAL approach (full context)
+        print(f"\n5. TRADITIONAL APPROACH (for comparison)")
+        print("-" * 40)
+        
+        traditional_prompt_tokens = prompt_tokens + doc_tokens
+        token_stats["traditional"]["input"] = traditional_prompt_tokens
+        
+        print(f"   If we passed FULL document in prompt:")
+        print(f"   Prompt: {prompt_tokens} + Document: {doc_tokens} = {traditional_prompt_tokens:,} tokens")
+        
+        # 6. Show token savings
+        print(f"\n6. TOKEN COMPARISON")
+        print("=" * 40)
+        
+        savings = token_stats["traditional"]["input"] - token_stats["recursive"]["input"]
+        savings_pct = (savings / token_stats["traditional"]["input"]) * 100
+        
+        print(f"   Traditional approach: ~{token_stats['traditional']['input']:,} tokens")
+        print(f"   Recursive approach:   ~{token_stats['recursive']['input']:,} tokens")
+        print(f"   -----------------------------------")
+        print(f"   SAVINGS:             ~{savings:,} tokens ({savings_pct:.0f}%)")
+        
+        # 7. Demonstrate other artifact operations
+        print(f"\n7. ARTIFACT OPERATIONS DEMO")
+        print("-" * 40)
+        
+        # head
+        head_result = store.head(ref, lines=5)
+        print(f"   head(5 lines):")
+        for line in head_result.split('\n')[:3]:
+            print(f"      {line[:60]}")
+        
+        # grep
+        grep_results = store.grep(ref, pattern=r"BLEU.*\d+", max_matches=3)
+        print(f"\n   grep('BLEU.*\\d+'):")
+        for match in grep_results[:2]:
+            print(f"      Line {match.line_number}: {match.line_content[:50].strip()}...")
+        
+        # chunk
+        chunk_result = store.chunk(ref, start_line=50, end_line=55)
+        print(f"\n   chunk(lines 50-55):")
+        for line in chunk_result.split('\n')[:3]:
+            print(f"      {line[:60]}")
+        
+        print("\n" + "=" * 70)
+        print("CONCLUSION: Recursive Context Pattern")
+        print("=" * 70)
+        print("""
+The Recursive Context pattern (RLM) provides:
+✓ Token efficiency: ~{savings_pct:.0f}% reduction in token usage
+✓ Scalability: Handle documents of any size
+✓ Precision: Agent searches for exactly what it needs
+✓ Cost savings: Lower API costs due to fewer tokens
+✓ Better accuracy: Avoids "context rot" from large contexts
+""".format(savings_pct=savings_pct))
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,145 @@
+"""
+Agent-centric Embedding Example
+
+This example shows how to use embeddings with PraisonAI Agents.
+Embeddings are used internally by Agent for:
+- Knowledge retrieval (RAG)
+- Memory storage and search
+- Semantic similarity
+
+You can also use the embedding API directly for custom use cases.
+"""
+
+from praisonaiagents import Agent, embedding
+
+# =============================================================================
+# Example 1: Direct Embedding API
+# =============================================================================
+
+def example_direct_embedding():
+    """Use the embedding API directly."""
+    
+    # Single text embedding
+    result = embedding("Hello, world!")
+    print(f"Single embedding: {len(result.embeddings[0])} dimensions")
+    
+    # Batch embedding
+    texts = ["AI agents are powerful", "Machine learning is fascinating"]
+    result = embedding(texts, model="text-embedding-3-small")
+    print(f"Batch embeddings: {len(result.embeddings)} vectors")
+    
+    # Custom dimensions (for models that support it)
+    result = embedding("Hello", model="text-embedding-3-large", dimensions=256)
+    print(f"Custom dimensions: {len(result.embeddings[0])} dimensions")
+    
+    return result
+
+
+# =============================================================================
+# Example 2: Agent with Knowledge (uses embeddings internally)
+# =============================================================================
+
+def example_agent_with_knowledge():
+    """Agent with knowledge uses embeddings for RAG."""
+    
+    agent = Agent(
+        instructions="You are a helpful assistant with knowledge about AI.",
+        knowledge=["AI agents can use tools to accomplish tasks."],
+        knowledge_config={
+            "embedder": {
+                "provider": "openai",
+                "config": {"model": "text-embedding-3-small"}
+            }
+        }
+    )
+    
+    # The agent uses embeddings internally for knowledge retrieval
+    response = agent.chat("What can AI agents do?")
+    print(f"Agent response: {response}")
+    
+    return agent
+
+
+# =============================================================================
+# Example 3: Agent with Memory (uses embeddings internally)
+# =============================================================================
+
+def example_agent_with_memory():
+    """Agent with memory uses embeddings for semantic search."""
+    
+    agent = Agent(
+        instructions="You are a helpful assistant that remembers conversations.",
+        memory=True,
+        memory_config={
+            "embedding_model": "text-embedding-3-small"
+        }
+    )
+    
+    # The agent uses embeddings internally for memory storage/retrieval
+    agent.chat("My name is Alice and I love Python programming.")
+    response = agent.chat("What do I love?")
+    print(f"Agent remembered: {response}")
+    
+    return agent
+
+
+# =============================================================================
+# Example 4: Custom Embedding for Similarity Search
+# =============================================================================
+
+def example_similarity_search():
+    """Use embeddings for custom similarity search."""
+    import math
+    
+    def cosine_similarity(a, b):
+        dot = sum(x * y for x, y in zip(a, b))
+        norm_a = math.sqrt(sum(x * x for x in a))
+        norm_b = math.sqrt(sum(x * x for x in b))
+        return dot / (norm_a * norm_b) if norm_a and norm_b else 0
+    
+    # Embed documents
+    documents = [
+        "Python is a programming language",
+        "JavaScript runs in browsers",
+        "AI agents can automate tasks"
+    ]
+    doc_embeddings = embedding(documents)
+    
+    # Embed query
+    query = "What language is used for web development?"
+    query_embedding = embedding(query)
+    
+    # Find most similar document
+    similarities = [
+        cosine_similarity(query_embedding.embeddings[0], doc_emb)
+        for doc_emb in doc_embeddings.embeddings
+    ]
+    
+    best_idx = similarities.index(max(similarities))
+    print(f"Most similar document: {documents[best_idx]}")
+    print(f"Similarity score: {similarities[best_idx]:.4f}")
+    
+    return similarities
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Example 1: Direct Embedding API")
+    print("=" * 60)
+    example_direct_embedding()
+    
+    print("\n" + "=" * 60)
+    print("Example 4: Custom Similarity Search")
+    print("=" * 60)
+    example_similarity_search()
+    
+    # Uncomment to run agent examples (requires API key)
+    # print("\n" + "=" * 60)
+    # print("Example 2: Agent with Knowledge")
+    # print("=" * 60)
+    # example_agent_with_knowledge()
+    
+    # print("\n" + "=" * 60)
+    # print("Example 3: Agent with Memory")
+    # print("=" * 60)
+    # example_agent_with_memory()
@@ -2,32 +2,34 @@
 """
 Basic Hooks Example for PraisonAI Agents.

-This example demonstrates how to use the hooks system to:
+This example demonstrates the simplified hook API using add_hook():
 1. Log tool calls before execution
 2. Block dangerous operations
 3. Add context to agent responses
 4. Monitor session lifecycle

+For the simplest example, see simple_hooks.py
+
 Usage:
    python basic_hooks.py
 """

 import asyncio
-from praisonaiagents import Agent
 from praisonaiagents.hooks import (
-    HookRegistry, HookRunner, HookEvent, HookResult,
+    add_hook, remove_hook, has_hook, get_default_registry,
+    HookRunner, HookEvent, HookResult,
    BeforeToolInput, AfterToolInput
 )


 def main():
-    # Create a hook registry
-    registry = HookRegistry()
+    # Clear any existing hooks from previous runs
+    get_default_registry().clear()
    
    # ==========================================================================
-    # Hook 1: Log all tool calls
+    # Hook 1: Log all tool calls (using string event name)
    # ==========================================================================
-    @registry.on(HookEvent.BEFORE_TOOL)
+    @add_hook('before_tool')
    def log_tool_calls(event_data: BeforeToolInput) -> HookResult:
        """Log every tool call before execution."""
        print(f"\n📝 [LOG] Tool: {event_data.tool_name}")
@@ -35,9 +37,9 @@ def main():
        return HookResult.allow()
    
    # ==========================================================================
-    # Hook 2: Block dangerous file operations (using function logic)
+    # Hook 2: Block dangerous file operations
    # ==========================================================================
-    @registry.on(HookEvent.BEFORE_TOOL)
+    @add_hook('before_tool')
    def block_delete_operations(event_data: BeforeToolInput) -> HookResult:
        """Block any delete or remove operations."""
        dangerous_keywords = ['delete', 'remove', 'rm', 'unlink']
@@ -53,7 +55,7 @@ def main():
    # ==========================================================================
    # Hook 3: Require confirmation for write operations
    # ==========================================================================
-    @registry.on(HookEvent.BEFORE_TOOL)
+    @add_hook('before_tool')
    def confirm_write_operations(event_data: BeforeToolInput) -> HookResult:
        """Request confirmation for write operations."""
        write_keywords = ['write', 'save', 'create', 'update']
@@ -62,14 +64,13 @@ def main():
        if any(kw in tool_lower for kw in write_keywords):
            print(f"\n⚠️  [CONFIRM] Write operation: {event_data.tool_name}")
            # In a real scenario, you might prompt the user here
-            # For this example, we'll auto-approve
            return HookResult.allow("Auto-approved for demo")
        return HookResult.allow()
    
    # ==========================================================================
    # Hook 4: Add timing information after tool execution
    # ==========================================================================
-    @registry.on(HookEvent.AFTER_TOOL)
+    @add_hook('after_tool')
    def log_tool_completion(event_data: AfterToolInput) -> HookResult:
        """Log tool completion with timing."""
        print(f"\n✅ [DONE] Tool: {event_data.tool_name}")
@@ -82,10 +83,14 @@ def main():
    # Test the hooks
    # ==========================================================================
    print("=" * 60)
-    print("Testing Hooks System")
+    print("Testing Hooks System (using add_hook API)")
    print("=" * 60)
    
-    runner = HookRunner(registry)
+    # Check hooks are registered
+    print(f"\nHooks registered for 'before_tool': {has_hook('before_tool')}")
+    print(f"Hooks registered for 'after_tool': {has_hook('after_tool')}")
+    
+    runner = HookRunner(get_default_registry())
    
    # Test 1: Normal tool call (should be logged and allowed)
    print("\n--- Test 1: Normal read operation ---")
@@ -132,7 +137,7 @@ def main():
    print("\n" + "=" * 60)
    print("Registered Hooks:")
    print("=" * 60)
-    for event, hooks in registry.list_hooks().items():
+    for event, hooks in get_default_registry().list_hooks().items():
        print(f"\n{event}:")
        for hook in hooks:
            print(f"  - {hook['name']} (matcher: {hook['matcher'] or '*'})")
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Simple Hooks Example for PraisonAI Agents.
+
+This example shows the SIMPLEST way to use hooks with the add_hook API.
+Just a few lines of code to intercept tool calls!
+
+No need to import HookResult - just return None/True to allow, 
+False to deny, or a string to deny with a reason.
+
+Usage:
+    python simple_hooks.py
+"""
+
+from praisonaiagents.hooks import add_hook, has_hook
+
+
+# =============================================================================
+# Register hooks with simple string event names
+# =============================================================================
+
+@add_hook('before_tool')
+def log_tools(event_data):
+    """Log every tool call. Return nothing (None) to allow."""
+    print(f"🔧 Tool: {event_data.tool_name}")
+    # No return needed - defaults to allow
+
+
+@add_hook('before_tool')
+def block_dangerous(event_data):
+    """Block delete operations. Return False or string to deny."""
+    if 'delete' in event_data.tool_name.lower():
+        print(f"🚫 Blocked: {event_data.tool_name}")
+        return "Delete operations are not allowed"  # String = deny with reason
+    # No return = allow
+
+
+@add_hook('after_tool')
+def log_completion(event_data):
+    """Log tool completion."""
+    print(f"✅ Done: {event_data.tool_name} ({event_data.execution_time_ms:.0f}ms)")
+
+
+# =============================================================================
+# Test the hooks
+# =============================================================================
+
+if __name__ == "__main__":
+    print("=" * 50)
+    print("Simple Hooks Example")
+    print("=" * 50)
+    
+    # Check hooks are registered
+    print(f"\nHooks registered for 'before_tool': {has_hook('before_tool')}")
+    print(f"Hooks registered for 'after_tool': {has_hook('after_tool')}")
+    
+    # You can now create an Agent and the hooks will be applied
+    print("\n💡 Hooks are now globally registered!")
+    print("   Any Agent will automatically use these hooks.")
+    print("\n   Example:")
+    print("   from praisonaiagents import Agent")
+    print("   agent = Agent(instructions='You are helpful')")
+    print("   agent.start('Help me with files')")
+    print("\n📝 Hook returns:")
+    print("   - None or True  → Allow the operation")
+    print("   - False         → Deny the operation")
+    print("   - 'reason'      → Deny with a custom message")
@@ -0,0 +1,128 @@
+/**
+ * AudioAgent Integration Test
+ * 
+ * Tests the AudioAgent for TTS and STT using AI SDK.
+ * Requires OPENAI_API_KEY for live tests.
+ * 
+ * Run: npx ts-node audio-agent.ts
+ */
+
+import { AudioAgent, createAudioAgent } from '../../../src/praisonai-ts/dist';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+    console.log('=== AudioAgent Integration Test ===\n');
+
+    // Test 1: Create AudioAgent with defaults
+    console.log('1. Testing AudioAgent creation:');
+    const agent = new AudioAgent({
+        name: 'TestAudioAgent',
+        provider: 'openai',
+        voice: 'alloy',
+        verbose: true
+    });
+    console.log('   Agent ID:', agent.id);
+    console.log('   Agent Name:', agent.name);
+    console.log('   Success: ✅');
+
+    // Test 2: Factory function
+    console.log('\n2. Testing createAudioAgent() factory:');
+    const agent2 = createAudioAgent({ provider: 'openai', voice: 'nova' });
+    console.log('   Agent created:', typeof agent2);
+    console.log('   Success: ✅');
+
+    // Test 3: Live TTS (requires API key)
+    if (process.env.OPENAI_API_KEY) {
+        console.log('\n3. Testing Text-to-Speech (live API):');
+        try {
+            const ttsAgent = new AudioAgent({
+                provider: 'openai',
+                voice: 'alloy',
+                verbose: false
+            });
+
+            const result = await ttsAgent.speak('Hello from PraisonAI AudioAgent!');
+            console.log('   Audio format:', result.format);
+            console.log('   Audio size:', result.audio.byteLength || result.audio.length, 'bytes');
+
+            // Optionally save to file
+            const outputPath = path.join(__dirname, 'test-output.mp3');
+            if (result.audio instanceof Buffer) {
+                fs.writeFileSync(outputPath, result.audio);
+                console.log('   Saved to:', outputPath);
+            }
+            console.log('   Success: ✅');
+        } catch (error: any) {
+            console.log('   ⚠️ TTS failed:', error.message);
+        }
+
+        // Test 4: Live Transcription (requires audio file)
+        console.log('\n4. Testing Speech-to-Text (live API):');
+        try {
+            const sttAgent = new AudioAgent({
+                provider: 'openai',
+                verbose: false
+            });
+
+            // Check if we have the test output from TTS
+            const audioPath = path.join(__dirname, 'test-output.mp3');
+            if (fs.existsSync(audioPath)) {
+                const result = await sttAgent.transcribe(audioPath);
+                console.log('   Transcribed text:', result.text);
+                console.log('   Language:', result.language || 'auto-detected');
+                console.log('   Success: ✅');
+
+                // Cleanup
+                fs.unlinkSync(audioPath);
+                console.log('   Cleaned up test file');
+            } else {
+                console.log('   Skipped (no test audio file available)');
+            }
+        } catch (error: any) {
+            console.log('   ⚠️ STT failed:', error.message);
+        }
+
+        // Test 5: Chat method (auto-detect mode)
+        console.log('\n5. Testing chat() method:');
+        try {
+            const chatAgent = new AudioAgent({ provider: 'openai', voice: 'echo' });
+
+            // Text input -> TTS
+            const chatResult = await chatAgent.chat('Testing audio chat interface');
+            console.log('   Chat result:', chatResult);
+            console.log('   Success: ✅');
+        } catch (error: any) {
+            console.log('   ⚠️ Chat failed:', error.message);
+        }
+
+    } else {
+        console.log('\n3-5. Live API Tests: Skipped (OPENAI_API_KEY not set)');
+        console.log('   Set OPENAI_API_KEY to run live tests');
+    }
+
+    // Test 6: Different providers (just creation, no live calls)
+    console.log('\n6. Testing provider configurations:');
+    const providers = ['openai', 'elevenlabs', 'groq', 'deepgram'] as const;
+
+    for (const provider of providers) {
+        try {
+            const a = new AudioAgent({ provider });
+            console.log(`   ${provider}: ✅ (created)`);
+        } catch (error: any) {
+            console.log(`   ${provider}: ⚠️ ${error.message}`);
+        }
+    }
+
+    // Test 7: Voice options
+    console.log('\n7. Testing OpenAI voice options:');
+    const voices = ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'];
+    for (const voice of voices) {
+        const a = new AudioAgent({ provider: 'openai', voice });
+        console.log(`   ${voice}: ✅`);
+    }
+
+    console.log('\n=== AudioAgent Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,124 @@
+/**
+ * ChonkieAdapter Integration Test
+ * 
+ * Tests the ChonkieJS adapter for text chunking.
+ * Works without ChonkieJS installed (uses native fallback).
+ * 
+ * Run: npx ts-node chonkie-adapter.ts
+ */
+
+import {
+  ChonkieAdapter,
+  createChonkieAdapter,
+  hasChonkie,
+  Chunking
+} from '../../../src/praisonai-ts/dist';
+
+async function main() {
+  console.log('=== ChonkieAdapter Integration Test ===\n');
+
+  // Test 1: Check ChonkieJS availability
+  console.log('1. Checking ChonkieJS availability:');
+  const chonkieAvailable = await hasChonkie();
+  console.log(`   ChonkieJS installed: ${chonkieAvailable ? '✅' : '❌ (using native fallback)'}`);
+
+  // Test 2: Create adapter with default config
+  console.log('\n2. Testing ChonkieAdapter creation:');
+  const adapter = new ChonkieAdapter({
+    strategy: 'token',
+    chunkSize: 100,
+    overlap: 20
+  });
+  console.log('   Adapter created: ✅');
+  console.log('   Info:', adapter.getInfo());
+
+  // Test 3: Chunk text
+  console.log('\n3. Testing text chunking:');
+  const sampleText = `
+    PraisonAI is a high-performance, agentic AI framework designed with minimal client-side API.
+    It features extreme performance sensitivity, lazy loading everywhere, and optional dependencies only.
+    The framework supports clean separation between Core SDK, Wrapper/integrations, and Tools/plugins.
+    All features must have a relevant CLI integration and representation.
+  `.trim();
+
+  const chunks = await adapter.chunk(sampleText);
+  console.log(`   Input length: ${sampleText.length} characters`);
+  console.log(`   Chunks created: ${chunks.length}`);
+  chunks.forEach((chunk, i) => {
+    console.log(`   [${i}]: "${chunk.content.slice(0, 50)}..." (${chunk.content.length} chars)`);
+  });
+  console.log('   Success: ✅');
+
+  // Test 4: Different strategies
+  console.log('\n4. Testing different chunking strategies:');
+  const strategies = ['size', 'sentence', 'paragraph', 'semantic'] as const;
+
+  for (const strategy of strategies) {
+    const strategyAdapter = createChonkieAdapter({ strategy, chunkSize: 80 });
+    const strategyChunks = await strategyAdapter.chunk(sampleText);
+    console.log(`   ${strategy}: ${strategyChunks.length} chunks`);
+  }
+  console.log('   Success: ✅');
+
+  // Test 5: Native Chunking class
+  console.log('\n5. Testing native Chunking class:');
+  const nativeChunker = new Chunking({ chunkSize: 100, overlap: 10, strategy: 'sentence' });
+  const nativeChunks = nativeChunker.chunk(sampleText);
+  console.log(`   Native chunks: ${nativeChunks.length}`);
+  console.log('   Success: ✅');
+
+  // Test 6: Factory function
+  console.log('\n6. Testing createChunking() factory:');
+  const factoryChunker = createChunking({ chunkSize: 200 });
+  const factoryChunks = factoryChunker.chunk(sampleText);
+  console.log(`   Factory chunks: ${factoryChunks.length}`);
+  console.log('   Success: ✅');
+
+  // Test 7: Merge small chunks
+  console.log('\n7. Testing mergeSmallChunks:');
+  const tinyChunker = new Chunking({ chunkSize: 20, overlap: 5 });
+  const tinyChunks = tinyChunker.chunk(sampleText);
+  const mergedChunks = tinyChunker.mergeSmallChunks(tinyChunks, 50);
+  console.log(`   Before merge: ${tinyChunks.length} chunks`);
+  console.log(`   After merge: ${mergedChunks.length} chunks`);
+  console.log('   Success: ✅');
+
+  // Test 8: Code chunking (if ChonkieJS available)
+  if (chonkieAvailable) {
+    console.log('\n8. Testing code chunking (ChonkieJS):');
+    const codeAdapter = createChonkieAdapter({ strategy: 'code', language: 'typescript' });
+    const codeText = `
+function hello() {
+  console.log('Hello');
+}
+
+class MyClass {
+  constructor() {
+    this.value = 42;
+  }
+  
+  getValue() {
+    return this.value;
+  }
+}
+    `.trim();
+
+    const codeChunks = await codeAdapter.chunk(codeText);
+    console.log(`   Code chunks: ${codeChunks.length}`);
+    console.log('   Success: ✅');
+  } else {
+    console.log('\n8. Code chunking: Skipped (ChonkieJS not installed)');
+  }
+
+  // Test 9: Verify adapter info
+  console.log('\n9. Verifying adapter state:');
+  const info = adapter.getInfo();
+  console.log(`   Strategy: ${info.strategy}`);
+  console.log(`   Using ChonkieJS: ${info.usingChonkie}`);
+  console.log(`   Chunk size: ${info.config.chunkSize}`);
+  console.log('   Success: ✅');
+
+  console.log('\n=== ChonkieAdapter Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,97 @@
+/**
+ * QueryEngine Integration Test
+ * 
+ * Tests semantic and keyword search for RAG applications.
+ * 
+ * Run: npx ts-node query-engine.ts
+ */
+
+import {
+    QueryEngine,
+    createQueryEngine,
+    createSimpleQueryEngine
+} from '../../../src/praisonai-ts/dist';
+
+async function main() {
+    console.log('=== QueryEngine Integration Test ===\n');
+
+    // Test 1: Simple in-memory engine
+    console.log('1. Testing simple in-memory QueryEngine:');
+    const docs = [
+        { id: 'doc1', content: 'PraisonAI is a high-performance AI agent framework designed for production use.' },
+        { id: 'doc2', content: 'TypeScript provides static typing and better tooling for JavaScript projects.' },
+        { id: 'doc3', content: 'Agents can use tools, memory, and knowledge to complete complex tasks.' },
+        { id: 'doc4', content: 'RAG (Retrieval-Augmented Generation) improves AI responses with relevant context.' },
+        { id: 'doc5', content: 'Workflows enable sequential and parallel execution of agent tasks.' }
+    ];
+
+    const engine = createSimpleQueryEngine(docs);
+
+    const results1 = await engine.query('agent framework', { topK: 2 });
+    console.log('   Query: "agent framework"');
+    console.log(`   Found: ${results1.length} results`);
+    results1.forEach((r, i) => {
+        console.log(`   [${i + 1}] ${r.content.slice(0, 50)}... (score: ${r.score.toFixed(2)})`);
+    });
+    console.log('   Success: ✅');
+
+    // Test 2: Different queries
+    console.log('\n2. Testing various queries:');
+    const queries = ['TypeScript', 'RAG', 'workflow', 'tools memory'];
+
+    for (const q of queries) {
+        const results = await engine.query(q, { topK: 1 });
+        console.log(`   "${q}" → ${results.length > 0 ? results[0].content.slice(0, 40) + '...' : 'No results'}`);
+    }
+    console.log('   Success: ✅');
+
+    // Test 3: Query for context string
+    console.log('\n3. Testing queryForContext:');
+    const context = await engine.queryForContext('agent tasks', { topK: 2 });
+    console.log('   Context string (preview):');
+    console.log('   ' + context.split('\n')[0]);
+    console.log('   Success: ✅');
+
+    // Test 4: Cache behavior
+    console.log('\n4. Testing caching:');
+    const start = Date.now();
+    await engine.query('agent framework', { topK: 2 });
+    const cachedTime = Date.now() - start;
+    console.log(`   Cached query time: ${cachedTime}ms (should be fast)`);
+
+    engine.clearCache();
+    const start2 = Date.now();
+    await engine.query('agent framework', { topK: 2 });
+    const uncachedTime = Date.now() - start2;
+    console.log(`   Uncached query time: ${uncachedTime}ms`);
+    console.log('   Success: ✅');
+
+    // Test 5: QueryEngine configuration
+    console.log('\n5. Testing custom QueryEngine configuration:');
+    const customEngine = new QueryEngine({
+        keywordSearch: async (query, options) => {
+            return docs
+                .filter(d => d.content.toLowerCase().includes(query.toLowerCase()))
+                .map(d => ({ id: d.id, content: d.content, score: 0.8 }))
+                .slice(0, options?.topK ?? 5);
+        },
+        defaultOptions: { mode: 'keyword', topK: 3 }
+    });
+
+    const customResults = await customEngine.query('TypeScript');
+    console.log(`   Custom engine results: ${customResults.length}`);
+    console.log('   Success: ✅');
+
+    // Test 6: Empty results handling
+    console.log('\n6. Testing empty results:');
+    const emptyResults = await engine.query('nonexistent_query_12345');
+    console.log(`   Results for nonsense query: ${emptyResults.length}`);
+
+    const emptyContext = await engine.queryForContext('nonexistent_query_12345');
+    console.log(`   Context: "${emptyContext}"`);
+    console.log('   Success: ✅');
+
+    console.log('\n=== QueryEngine Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,136 @@
+/**
+ * MCP Client Integration Test
+ * 
+ * Tests the MCP (Model Context Protocol) client.
+ * Note: Requires an MCP server for full integration tests.
+ * 
+ * Run: npx ts-node mcp-client.ts
+ */
+
+import {
+    MCPClient,
+    createMCPClient,
+    getMCPTools,
+    type MCPClientConfig
+} from '../../../src/praisonai-ts/dist/mcp';
+
+async function main() {
+    console.log('=== MCPClient Integration Test ===\n');
+
+    // Test 1: Create MCP client
+    console.log('1. Testing MCPClient creation:');
+    const client = new MCPClient({
+        serverUrl: 'http://localhost:3000',
+        transport: 'http',
+        timeout: 5000,
+        verbose: true
+    });
+    console.log('   Client ID:', client.id);
+    console.log('   Connected:', client.isConnected());
+    console.log('   Success: ✅');
+
+    // Test 2: Factory function
+    console.log('\n2. Testing createMCPClient() factory:');
+    const client2 = createMCPClient({ serverUrl: 'http://localhost:8080' });
+    console.log('   Client created:', typeof client2);
+    console.log('   Success: ✅');
+
+    // Test 3: Transport configurations
+    console.log('\n3. Testing transport configurations:');
+    const transports: MCPClientConfig['transport'][] = ['http', 'websocket', 'sse', 'stdio'];
+
+    for (const transport of transports) {
+        try {
+            const c = new MCPClient({
+                transport,
+                serverUrl: transport !== 'stdio' ? 'http://localhost:3000' : undefined,
+                command: transport === 'stdio' ? 'npx' : undefined,
+                args: transport === 'stdio' ? ['mcp-server'] : undefined
+            });
+            console.log(`   ${transport}: ✅ (configured)`);
+        } catch (error: any) {
+            console.log(`   ${transport}: ⚠️ ${error.message}`);
+        }
+    }
+
+    // Test 4: Session info
+    console.log('\n4. Testing session management:');
+    const session = client.getSession();
+    console.log('   Session ID:', session.id);
+    console.log('   Connected:', session.connected);
+    console.log('   Tools:', session.tools.length);
+    console.log('   Resources:', session.resources.length);
+    console.log('   Success: ✅');
+
+    // Test 5: Live connection test (optional - requires running server)
+    const testServerUrl = process.env.MCP_SERVER_URL;
+    if (testServerUrl) {
+        console.log('\n5. Testing live MCP connection:');
+        try {
+            const liveClient = new MCPClient({
+                serverUrl: testServerUrl,
+                transport: 'http',
+                timeout: 10000,
+                verbose: false
+            });
+
+            await liveClient.connect();
+            console.log('   Connected: ✅');
+
+            const tools = await liveClient.listTools();
+            console.log(`   Tools discovered: ${tools.length}`);
+
+            for (const tool of tools.slice(0, 3)) {
+                console.log(`   - ${tool.name}: ${tool.description || 'No description'}`);
+            }
+
+            // Get tools in AI SDK format
+            const aiTools = await liveClient.getToolsAsAISDK();
+            console.log(`   AI SDK tools: ${aiTools.length}`);
+
+            await liveClient.disconnect();
+            console.log('   Disconnected: ✅');
+        } catch (error: any) {
+            console.log(`   ⚠️ Connection failed: ${error.message}`);
+        }
+    } else {
+        console.log('\n5. Live connection: Skipped (MCP_SERVER_URL not set)');
+        console.log('   Set MCP_SERVER_URL to test live connections');
+    }
+
+    // Test 6: Mock tool call simulation
+    console.log('\n6. Testing tool call preparation:');
+    const mockTool = {
+        name: 'search',
+        description: 'Search for information',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' }
+            },
+            required: ['query']
+        }
+    };
+    console.log('   Mock tool:', mockTool.name);
+    console.log('   Schema:', JSON.stringify(mockTool.inputSchema));
+    console.log('   Success: ✅');
+
+    // Test 7: API Key configuration
+    console.log('\n7. Testing API key configuration:');
+    const authClient = new MCPClient({
+        serverUrl: 'http://api.example.com',
+        apiKey: 'test-api-key-12345'
+    });
+    console.log('   Client with API key: ✅');
+
+    // Test 8: getMCPTools helper
+    console.log('\n8. Testing getMCPTools helper signature:');
+    console.log('   getMCPTools function:', typeof getMCPTools);
+    console.log('   Returns: { client, tools }');
+    console.log('   Success: ✅');
+
+    console.log('\n=== MCPClient Tests Complete ===');
+    console.log('\nNote: For full integration tests, run an MCP server and set MCP_SERVER_URL');
+}
+
+main().catch(console.error);
@@ -0,0 +1,137 @@
+/**
+ * MemoryHooks Integration Test
+ * 
+ * Tests pre/post hooks for memory operations.
+ * 
+ * Run: npx ts-node memory-hooks.ts
+ */
+
+import {
+    MemoryHooks,
+    createMemoryHooks,
+    createLoggingHooks,
+    createValidationHooks,
+    Memory,
+    createMemory
+} from '../../../src/praisonai-ts/dist';
+
+async function main() {
+    console.log('=== MemoryHooks Integration Test ===\n');
+
+    // Test 1: Basic hooks
+    console.log('1. Testing basic MemoryHooks:');
+    const logs: string[] = [];
+
+    const hooks = new MemoryHooks({
+        beforeStore: async (key, value) => {
+            logs.push(`beforeStore: ${key}`);
+            return { key, value };
+        },
+        afterStore: async (key) => {
+            logs.push(`afterStore: ${key}`);
+        },
+        beforeRetrieve: async (key) => {
+            logs.push(`beforeRetrieve: ${key}`);
+            return key;
+        },
+        afterRetrieve: async (key, value) => {
+            logs.push(`afterRetrieve: ${key}`);
+            return value;
+        }
+    });
+
+    await hooks.beforeStore('key1', { data: 'value1' });
+    await hooks.afterStore('key1', { data: 'value1' });
+    await hooks.beforeRetrieve('key1');
+    await hooks.afterRetrieve('key1', { data: 'value1' });
+
+    console.log('   Triggered hooks:', logs);
+    console.log('   Success: ✅');
+
+    // Test 2: Logging hooks
+    console.log('\n2. Testing createLoggingHooks:');
+    const logMessages: string[] = [];
+    const loggingHooks = createLoggingHooks((msg) => logMessages.push(msg));
+
+    await loggingHooks.beforeStore('test', 'data');
+    await loggingHooks.afterStore('test', 'data');
+    await loggingHooks.beforeRetrieve('test');
+    await loggingHooks.afterRetrieve('test', 'data');
+
+    console.log('   Log messages:', logMessages.length);
+    logMessages.forEach(m => console.log('    -', m));
+    console.log('   Success: ✅');
+
+    // Test 3: Validation hooks
+    console.log('\n3. Testing createValidationHooks:');
+    const validationHooks = createValidationHooks((key, value) => {
+        // Only allow non-empty strings
+        if (typeof value !== 'string' || value.length === 0) {
+            return { valid: false, reason: 'Value must be non-empty string' };
+        }
+        return { valid: true };
+    });
+
+    const validResult = await validationHooks.beforeStore('good', 'valid string');
+    console.log('   Valid data allowed:', validResult !== null);
+
+    const invalidResult = await validationHooks.beforeStore('bad', '');
+    console.log('   Invalid data blocked:', invalidResult === null);
+    console.log('   Success: ✅');
+
+    // Test 4: Delete hooks
+    console.log('\n4. Testing delete hooks:');
+    const deleteHooks = new MemoryHooks({
+        beforeDelete: async (key) => {
+            console.log(`   [Hook] About to delete: ${key}`);
+            return true; // Allow deletion
+        },
+        afterDelete: async (key, success) => {
+            console.log(`   [Hook] Delete ${key}: ${success ? 'succeeded' : 'failed'}`);
+        }
+    });
+
+    const canDelete = await deleteHooks.beforeDelete('item-to-delete');
+    console.log('   Deletion allowed:', canDelete);
+    await deleteHooks.afterDelete('item-to-delete', true);
+    console.log('   Success: ✅');
+
+    // Test 5: Search hooks
+    console.log('\n5. Testing search hooks:');
+    const searchHooks = new MemoryHooks({
+        beforeSearch: async (query, options) => {
+            console.log(`   [Hook] Searching: "${query}"`);
+            // Could modify query here
+            return { query: query.toLowerCase(), options };
+        },
+        afterSearch: async (query, results) => {
+            console.log(`   [Hook] Found ${results.length} results for "${query}"`);
+            return results;
+        }
+    });
+
+    const searchParams = await searchHooks.beforeSearch('UPPERCASE QUERY');
+    console.log('   Modified query:', searchParams?.query);
+
+    await searchHooks.afterSearch('query', [{ id: '1' }, { id: '2' }]);
+    console.log('   Success: ✅');
+
+    // Test 6: Dynamic hook management
+    console.log('\n6. Testing dynamic hook management:');
+    const dynamicHooks = new MemoryHooks({});
+
+    console.log('   Initial config:', Object.keys(dynamicHooks.getConfig()).length === 0 ? 'empty' : 'has hooks');
+
+    dynamicHooks.addHook('logging', true);
+    dynamicHooks.setLogging(true);
+
+    console.log('   After adding logging:', dynamicHooks.getConfig().logging);
+
+    dynamicHooks.removeHook('logging');
+    console.log('   After removing:', dynamicHooks.getConfig().logging ?? 'undefined');
+    console.log('   Success: ✅');
+
+    console.log('\n=== MemoryHooks Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,181 @@
+/**
+ * Feature Parity Integration Test Runner
+ * 
+ * Runs all integration tests for the new TypeScript features.
+ * Tests include real API calls when OPENAI_API_KEY is available.
+ * 
+ * Run: npx ts-node run-feature-tests.ts
+ */
+
+import { execSync, spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+
+interface TestResult {
+    name: string;
+    passed: boolean;
+    duration: number;
+    output: string;
+    error?: string;
+}
+
+const TEST_FILES = [
+    // Workflow patterns
+    'workflows/loop-pattern.ts',
+    'workflows/repeat-pattern.ts',
+    // Agents
+    'agents/audio-agent.ts',
+    // Knowledge
+    'knowledge/chonkie-adapter.ts',
+    // MCP
+    'mcp/mcp-client-test.ts',
+];
+
+async function runTest(testFile: string): Promise<TestResult> {
+    const startTime = Date.now();
+    const fullPath = path.join(__dirname, testFile);
+    const name = path.basename(testFile, '.ts');
+
+    return new Promise((resolve) => {
+        const proc = spawn('npx', ['ts-node', fullPath], {
+            cwd: __dirname,
+            env: { ...process.env },
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        proc.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+
+        proc.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+
+        proc.on('close', (code) => {
+            const duration = Date.now() - startTime;
+            resolve({
+                name,
+                passed: code === 0,
+                duration,
+                output: stdout,
+                error: stderr || undefined
+            });
+        });
+
+        proc.on('error', (error) => {
+            const duration = Date.now() - startTime;
+            resolve({
+                name,
+                passed: false,
+                duration,
+                output: '',
+                error: error.message
+            });
+        });
+
+        // Timeout after 60 seconds
+        setTimeout(() => {
+            proc.kill();
+            resolve({
+                name,
+                passed: false,
+                duration: 60000,
+                output: stdout,
+                error: 'Test timed out after 60 seconds'
+            });
+        }, 60000);
+    });
+}
+
+async function main() {
+    console.log('╔════════════════════════════════════════════════════════════╗');
+    console.log('║     PraisonAI TypeScript Feature Parity Integration Tests  ║');
+    console.log('╚════════════════════════════════════════════════════════════╝\n');
+
+    // Environment info
+    console.log('Environment:');
+    console.log(`  OPENAI_API_KEY: ${process.env.OPENAI_API_KEY ? '✅ Set' : '❌ Not set'}`);
+    console.log(`  MCP_SERVER_URL: ${process.env.MCP_SERVER_URL ? '✅ Set' : '❌ Not set'}`);
+    console.log(`  Node version: ${process.version}`);
+    console.log('');
+
+    // Check if test files exist
+    console.log('Test Files:');
+    for (const file of TEST_FILES) {
+        const fullPath = path.join(__dirname, file);
+        const exists = fs.existsSync(fullPath);
+        console.log(`  ${exists ? '✅' : '❌'} ${file}`);
+    }
+    console.log('');
+
+    // Run tests
+    console.log('Running Tests...\n');
+    console.log('─'.repeat(60));
+
+    const results: TestResult[] = [];
+    for (const testFile of TEST_FILES) {
+        const fullPath = path.join(__dirname, testFile);
+        if (!fs.existsSync(fullPath)) {
+            results.push({
+                name: path.basename(testFile, '.ts'),
+                passed: false,
+                duration: 0,
+                output: '',
+                error: 'File not found'
+            });
+            continue;
+        }
+
+        console.log(`\n▶ Running: ${testFile}`);
+        const result = await runTest(testFile);
+        results.push(result);
+
+        if (result.passed) {
+            console.log(`  ✅ PASSED (${result.duration}ms)`);
+        } else {
+            console.log(`  ❌ FAILED (${result.duration}ms)`);
+            if (result.error) {
+                console.log(`     Error: ${result.error.slice(0, 200)}...`);
+            }
+        }
+    }
+
+    console.log('\n' + '─'.repeat(60));
+
+    // Summary
+    const passed = results.filter(r => r.passed).length;
+    const failed = results.filter(r => !r.passed).length;
+    const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+
+    console.log('\n╔════════════════════════════════════════════════════════════╗');
+    console.log('║                      TEST SUMMARY                          ║');
+    console.log('╚════════════════════════════════════════════════════════════╝');
+    console.log(`  Total Tests: ${results.length}`);
+    console.log(`  Passed: ${passed} ✅`);
+    console.log(`  Failed: ${failed} ${failed > 0 ? '❌' : ''}`);
+    console.log(`  Duration: ${(totalDuration / 1000).toFixed(2)}s`);
+    console.log('');
+
+    // Detailed results
+    if (failed > 0) {
+        console.log('Failed Tests:');
+        for (const result of results.filter(r => !r.passed)) {
+            console.log(`  ❌ ${result.name}`);
+            if (result.error) {
+                console.log(`     ${result.error.slice(0, 100)}`);
+            }
+        }
+        console.log('');
+    }
+
+    // Exit with appropriate code
+    process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch((error) => {
+    console.error('Test runner failed:', error);
+    process.exit(1);
+});
@@ -0,0 +1,112 @@
+/**
+ * SubagentTool Integration Test
+ * 
+ * Tests the agent-as-tool pattern with real agents.
+ * 
+ * Run: npx ts-node subagent-tool.ts
+ * Requires: OPENAI_API_KEY
+ */
+
+import {
+    Agent,
+    SubagentTool,
+    createSubagentTool,
+    createSubagentTools,
+    createDelegator
+} from '../../../src/praisonai-ts/dist';
+
+async function main() {
+    console.log('=== SubagentTool Integration Test ===\n');
+
+    // Test 1: Create SubagentTool
+    console.log('1. Testing SubagentTool creation:');
+    const mockAgent = {
+        name: 'MockAgent',
+        chat: async (input: string) => `Echo: ${input}`
+    };
+
+    const tool = new SubagentTool(mockAgent, {
+        name: 'echo',
+        description: 'Echo the input'
+    });
+
+    console.log('   Tool name:', tool.name);
+    console.log('   Tool ID:', tool.id);
+    console.log('   Schema:', JSON.stringify(tool.getSchema()));
+    console.log('   Success: ✅');
+
+    // Test 2: Execute tool with mock agent
+    console.log('\n2. Testing tool execution:');
+    const mockResult = await tool.execute({ input: 'Hello World' });
+    console.log('   Input: "Hello World"');
+    console.log('   Output:', mockResult);
+    console.log('   Success: ✅');
+
+    // Test 3: Factory function
+    console.log('\n3. Testing createSubagentTool factory:');
+    const factoryTool = createSubagentTool(mockAgent, { name: 'factory_echo' });
+    console.log('   Tool name:', factoryTool.name);
+    console.log('   Success: ✅');
+
+    // Test 4: Multiple subagent tools
+    console.log('\n4. Testing createSubagentTools (batch):');
+    const agents = [
+        { name: 'Agent1', chat: async (i: string) => `A1: ${i}` },
+        { name: 'Agent2', chat: async (i: string) => `A2: ${i}` }
+    ];
+    const tools = createSubagentTools(agents);
+    console.log('   Created tools:', tools.length);
+    tools.forEach(t => console.log('    -', t.name));
+    console.log('   Success: ✅');
+
+    // Test 5: AI SDK format conversion
+    console.log('\n5. Testing AI SDK format conversion:');
+    const aiTool = tool.toAISDKTool();
+    console.log('   Type:', aiTool.type);
+    console.log('   Function name:', aiTool.function.name);
+    console.log('   Has execute:', typeof aiTool.execute === 'function');
+    console.log('   Success: ✅');
+
+    // Test 6: Live test with real agent
+    if (process.env.OPENAI_API_KEY) {
+        console.log('\n6. Testing with real Agent (live API):');
+        try {
+            const researcher = new Agent({
+                name: 'QuickResearcher',
+                instructions: 'Answer in exactly 5 words.',
+                llm: 'openai/gpt-4o-mini'
+            });
+
+            const researchTool = createSubagentTool(researcher, {
+                name: 'quick_research',
+                description: 'Get a quick 5-word answer'
+            });
+
+            const result = await researchTool.execute({ input: 'What is AI?' });
+            console.log('   Question: "What is AI?"');
+            console.log('   Answer:', result);
+            console.log('   Success: ✅');
+        } catch (error: any) {
+            console.log('   Error:', error.message);
+        }
+    } else {
+        console.log('\n6. Live test: Skipped (OPENAI_API_KEY not set)');
+    }
+
+    // Test 7: Input/Output transforms
+    console.log('\n7. Testing transforms:');
+    const transformTool = createSubagentTool(mockAgent, {
+        name: 'transform_echo',
+        inputTransform: (input) => input.toUpperCase(),
+        outputTransform: (output) => `[TRANSFORMED] ${output}`
+    });
+
+    const transformResult = await transformTool.execute({ input: 'hello' });
+    console.log('   Input: "hello"');
+    console.log('   Output:', transformResult);
+    console.log('   Success: ✅');
+
+    console.log('\n=== SubagentTool Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,88 @@
+/**
+ * Loop Pattern Integration Test
+ * 
+ * Tests the Loop workflow pattern with real data.
+ * 
+ * Run: npx ts-node loop-pattern.ts
+ */
+
+import { Loop, loopPattern, Agent, Workflow } from '../../../src/praisonai-ts/dist';
+
+async function main() {
+    console.log('=== Loop Pattern Integration Test ===\n');
+
+    // Test 1: Basic Loop with array
+    console.log('1. Testing Loop with array iteration:');
+    const items = ['apple', 'banana', 'cherry'];
+
+    const processor = (item: string) => `Processed: ${item.toUpperCase()}`;
+    const arrayLoop = new Loop(processor, { over: 'items' });
+
+    const result1 = await arrayLoop.run({ items });
+    console.log('   Results:', result1.results);
+    console.log('   Iterations:', result1.iterations);
+    console.log('   Success:', result1.success ? '✅' : '❌');
+
+    // Test 2: Loop with convenience function
+    console.log('\n2. Testing loop() convenience function:');
+    const doubler = (n: number) => n * 2;
+    const numberLoop = loopPattern(doubler, { over: 'numbers' });
+
+    const result2 = await numberLoop.run({ numbers: [1, 2, 3, 4, 5] });
+    console.log('   Input: [1, 2, 3, 4, 5]');
+    console.log('   Output:', result2.results);
+    console.log('   Success:', result2.success ? '✅' : '❌');
+
+    // Test 3: Loop with Agent (requires OPENAI_API_KEY)
+    if (process.env.OPENAI_API_KEY) {
+        console.log('\n3. Testing Loop with Agent (live API):');
+        try {
+            const agent = new Agent({
+                name: 'Summarizer',
+                instructions: 'Summarize the given topic in one sentence.',
+                llm: 'openai/gpt-4o-mini'
+            });
+
+            const topics = ['AI', 'TypeScript'];
+            const agentLoop = new Loop(agent, { over: 'topics', varName: 'topic' });
+
+            console.log('   Processing topics:', topics);
+            const result3 = await agentLoop.run({ topics });
+
+            result3.results.forEach((res, i) => {
+                console.log(`   [${topics[i]}]: ${res.slice(0, 80)}...`);
+            });
+            console.log('   Success:', result3.success ? '✅' : '❌');
+        } catch (error: any) {
+            console.log('   ⚠️ Agent test failed:', error.message);
+        }
+    } else {
+        console.log('\n3. Agent Loop Test: Skipped (OPENAI_API_KEY not set)');
+    }
+
+    // Test 4: Loop with error handling
+    console.log('\n4. Testing Loop with continueOnError:');
+    const errorProneProcessor = (item: string) => {
+        if (item === 'fail') throw new Error('Intentional failure');
+        return `OK: ${item}`;
+    };
+
+    const errorLoop = new Loop(errorProneProcessor, {
+        over: 'items',
+        continueOnError: true
+    });
+
+    const result4 = await errorLoop.run({ items: ['a', 'fail', 'b'] });
+    console.log('   Results:', result4.results);
+    console.log('   Errors:', result4.errors.length);
+    console.log('   Success:', result4.success ? '✅' : '❌ (expected - has errors)');
+
+    // Test 5: Loop type exports
+    console.log('\n5. Verifying exports:');
+    console.log('   Loop class:', typeof Loop);
+    console.log('   loop function:', typeof loopPattern);
+
+    console.log('\n=== Loop Pattern Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,114 @@
+/**
+ * Repeat Pattern Integration Test
+ * 
+ * Tests the Repeat workflow pattern for evaluator-optimizer loops.
+ * 
+ * Run: npx ts-node repeat-pattern.ts
+ */
+
+import { Repeat, repeatPattern, Agent } from '../../../src/praisonai-ts/dist';
+
+async function main() {
+    console.log('=== Repeat Pattern Integration Test ===\n');
+
+    // Test 1: Basic repeat until condition
+    console.log('1. Testing Repeat with condition:');
+    let counter = 0;
+    const incrementer = () => {
+        counter++;
+        return `Iteration ${counter}`;
+    };
+
+    const repeat1 = new Repeat(incrementer, {
+        until: (ctx) => ctx.iteration >= 3,
+        maxIterations: 10
+    });
+
+    const result1 = await repeat1.run('start');
+    console.log('   Results:', result1.iterations);
+    console.log('   Final:', result1.result);
+    console.log('   Condition met:', result1.conditionMet ? '✅' : '❌');
+    console.log('   Max reached:', result1.maxReached ? '⚠️' : 'No');
+
+    // Test 2: Repeat with content condition
+    console.log('\n2. Testing Repeat with content-based condition:');
+    let quality = 0;
+    const improver = (input: string, prev: string | null) => {
+        quality += 25;
+        return `Quality: ${quality}% - ${prev || input}`;
+    };
+
+    const repeat2 = new Repeat(improver, {
+        until: (ctx) => ctx.lastResult?.includes('100%') ?? false,
+        maxIterations: 5
+    });
+
+    quality = 0; // Reset
+    const result2 = await repeat2.run('Initial draft');
+    console.log('   Iterations:', result2.count);
+    console.log('   Final:', result2.result);
+    console.log('   Condition met:', result2.conditionMet ? '✅' : '❌');
+
+    // Test 3: Repeat reaching max iterations
+    console.log('\n3. Testing Repeat hitting max iterations:');
+    const neverDone = () => 'still working...';
+
+    const repeat3 = new Repeat(neverDone, {
+        until: () => false, // Never satisfied
+        maxIterations: 3
+    });
+
+    const result3 = await repeat3.run('start');
+    console.log('   Iterations:', result3.count);
+    console.log('   Max reached:', result3.maxReached ? '✅ (expected)' : '❌');
+
+    // Test 4: Repeat with Agent (requires OPENAI_API_KEY)
+    if (process.env.OPENAI_API_KEY) {
+        console.log('\n4. Testing Repeat with Agent (live API):');
+        try {
+            const agent = new Agent({
+                name: 'Optimizer',
+                instructions: 'Improve the given text. Add more detail and clarity. Say "DONE" when satisfied.',
+                llm: 'openai/gpt-4o-mini'
+            });
+
+            const repeat4 = new Repeat(agent, {
+                until: (ctx) => ctx.lastResult?.includes('DONE') ?? false,
+                maxIterations: 3
+            });
+
+            const result4 = await repeat4.run('Make this better: Hello world');
+            console.log('   Iterations:', result4.count);
+            console.log('   Final (truncated):', result4.result.slice(0, 100) + '...');
+            console.log('   Condition met:', result4.conditionMet ? '✅' : 'Max reached');
+        } catch (error: any) {
+            console.log('   ⚠️ Agent test failed:', error.message);
+        }
+    } else {
+        console.log('\n4. Agent Repeat Test: Skipped (OPENAI_API_KEY not set)');
+    }
+
+    // Test 5: Convenience function
+    console.log('\n5. Testing repeatPattern() convenience function:');
+    let seq = 0;
+    const sequencer = () => `seq-${++seq}`;
+
+    const repeat5 = repeatPattern(sequencer, {
+        until: (ctx) => ctx.iteration >= 2,
+        maxIterations: 5
+    });
+
+    seq = 0; // Reset
+    const result5 = await repeat5.run('');
+    console.log('   Results:', result5.iterations);
+    console.log('   Success:', result5.conditionMet ? '✅' : '❌');
+
+    // Test 6: Verify exports
+    console.log('\n6. Verifying exports:');
+    console.log('   Repeat class:', typeof Repeat);
+    console.log('   repeatPattern function:', typeof repeatPattern);
+
+    console.log('\n=== Repeat Pattern Tests Complete ===');
+}
+
+main().catch(console.error);
@@ -0,0 +1,10 @@
+from praisonaiagents import AudioAgent
+
+# Text to Speech
+tts = AudioAgent(llm="openai/tts-1")
+tts.say("Hello!", output="hello.mp3")
+
+# Speech to Text
+stt = AudioAgent(llm="openai/whisper-1")
+text = stt.listen("hello.mp3")
+print(text)
@@ -0,0 +1,7 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="groq/whisper-large-v3")  # 10x faster
+text = agent.transcribe("audio.mp3", language="en")
+print(text)
+
+# Models: openai/whisper-1, groq/whisper-large-v3, deepgram/nova-2
@@ -0,0 +1,8 @@
+# Speech-to-Text with Groq (fastest)
+# Requires: export GROQ_API_KEY=your-key
+
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="groq/whisper-large-v3")
+text = agent.listen("audio.mp3")  # Replace with your audio file
+print(text)
@@ -0,0 +1,5 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="deepgram/nova-2")
+text = agent.listen("audio.mp3")
+print(text)
@@ -0,0 +1,5 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="groq/whisper-large-v3")
+text = agent.listen("audio.mp3")
+print(text)
@@ -0,0 +1,5 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="openai/whisper-1")
+text = agent.listen("audio.mp3")
+print(text)
@@ -0,0 +1,7 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="openai/tts-1-hd")
+agent.speech("Hello!", voice="nova", speed=1.2, output="hello.mp3")
+
+# Voices: alloy, echo, fable, onyx, nova, shimmer
+# Models: openai/tts-1, openai/tts-1-hd, openai/gpt-4o-mini-tts
@@ -0,0 +1,8 @@
+# Text-to-Speech with OpenAI
+# Requires: export OPENAI_API_KEY=your-key
+
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="openai/tts-1")
+agent.say("Hello world!", output="hello.mp3")
+print("Saved to hello.mp3")
@@ -0,0 +1,4 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="elevenlabs/eleven_multilingual_v2")
+agent.say("Hello world!", output="hello.mp3")
@@ -0,0 +1,4 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="gemini/gemini-2.5-flash-preview-tts")
+agent.say("Hello world!", output="hello.mp3", voice="leda")
@@ -0,0 +1,4 @@
+from praisonaiagents import AudioAgent
+
+agent = AudioAgent(llm="openai/tts-1")
+agent.say("Hello world!", output="hello.mp3")
@@ -0,0 +1,76 @@
+"""
+Messaging Bot Example - Deploy Agents to Telegram, Discord, Slack
+
+This example demonstrates how to configure bots for different
+messaging platforms.
+"""
+
+import os
+from praisonaiagents import Agent, BotConfig
+
+# Telegram Bot Configuration
+telegram_config = BotConfig(
+    token=os.environ.get("TELEGRAM_BOT_TOKEN", ""),
+    command_prefix="/",
+    mention_required=True,
+    typing_indicator=True,
+    max_message_length=4096,
+    metadata={"platform": "telegram"}
+)
+
+# Discord Bot Configuration
+discord_config = BotConfig(
+    token=os.environ.get("DISCORD_BOT_TOKEN", ""),
+    command_prefix="!",
+    mention_required=True,
+    typing_indicator=True,
+    metadata={
+        "platform": "discord",
+        "guild_ids": []  # Add your guild IDs here
+    }
+)
+
+# Slack Bot Configuration
+slack_config = BotConfig(
+    token=os.environ.get("SLACK_BOT_TOKEN", ""),
+    command_prefix="/",
+    mention_required=True,
+    typing_indicator=True,
+    metadata={
+        "platform": "slack",
+        "app_token": os.environ.get("SLACK_APP_TOKEN", "")
+    }
+)
+
+# Create the agent that will handle messages
+assistant = Agent(
+    name="assistant",
+    instructions="""You are a helpful assistant that responds to messages 
+    from users on messaging platforms. Be friendly and concise.""",
+    llm="gpt-4o-mini"
+)
+
+if __name__ == "__main__":
+    print("Bot Configurations:")
+    print()
+    
+    print("Telegram Config:")
+    print(f"  Token configured: {bool(telegram_config.token)}")
+    print(f"  Command prefix: {telegram_config.command_prefix}")
+    print(f"  Mention required: {telegram_config.mention_required}")
+    print()
+    
+    print("Discord Config:")
+    print(f"  Token configured: {bool(discord_config.token)}")
+    print(f"  Command prefix: {discord_config.command_prefix}")
+    print()
+    
+    print("Slack Config:")
+    print(f"  Token configured: {bool(slack_config.token)}")
+    print(f"  Command prefix: {slack_config.command_prefix}")
+    print()
+    
+    print("To start a bot, use the CLI:")
+    print("  praisonai bot telegram --token $TELEGRAM_BOT_TOKEN")
+    print("  praisonai bot discord --token $DISCORD_BOT_TOKEN")
+    print("  praisonai bot slack --token $SLACK_BOT_TOKEN")
@@ -0,0 +1,391 @@
+"""
+Conditional Branching Example - PraisonAI Agents
+
+This example demonstrates the `if:` pattern for conditional workflow execution:
+1. Basic if/then/else branching
+2. Numeric condition evaluation (>, <, >=, <=, ==, !=)
+3. String condition evaluation (==, !=)
+4. Contains condition (in, contains)
+5. Combining if: with loop: for per-item decisions
+
+The if: pattern enables dynamic workflow paths based on
+runtime conditions and variable values.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import if_, loop
+
+
+# =============================================================================
+# Example 1: Basic If/Then/Else - Score-Based Routing
+# =============================================================================
+
+def basic_if_example():
+    """
+    Route to different handlers based on a score threshold.
+    """
+    print("\n" + "="*60)
+    print("Example 1: Basic If/Then/Else - Score Routing")
+    print("="*60)
+    
+    def approve(ctx: WorkflowContext) -> StepResult:
+        score = ctx.variables.get("score", 0)
+        print(f"  ✅ APPROVED: Score {score} meets threshold")
+        return StepResult(output="Application approved")
+    
+    def reject(ctx: WorkflowContext) -> StepResult:
+        score = ctx.variables.get("score", 0)
+        print(f"  ❌ REJECTED: Score {score} below threshold")
+        return StepResult(output="Application rejected")
+    
+    # Test with passing score
+    workflow_pass = Workflow(
+        steps=[
+            if_(
+                condition="{{score}} >= 70",
+                then_steps=[approve],
+                else_steps=[reject]
+            )
+        ],
+        variables={"score": 85}
+    )
+    
+    print("\nTest 1: Score = 85")
+    workflow_pass.start("Evaluate application")
+    
+    # Test with failing score
+    workflow_fail = Workflow(
+        steps=[
+            if_(
+                condition="{{score}} >= 70",
+                then_steps=[approve],
+                else_steps=[reject]
+            )
+        ],
+        variables={"score": 55}
+    )
+    
+    print("\nTest 2: Score = 55")
+    workflow_fail.start("Evaluate application")
+
+
+# =============================================================================
+# Example 2: String Condition - Status-Based Processing
+# =============================================================================
+
+def string_condition_example():
+    """
+    Branch based on string equality.
+    """
+    print("\n" + "="*60)
+    print("Example 2: String Condition - Status Processing")
+    print("="*60)
+    
+    def process_active(ctx: WorkflowContext) -> StepResult:
+        print("  🟢 Processing ACTIVE user")
+        return StepResult(output="Active user processed")
+    
+    def process_inactive(ctx: WorkflowContext) -> StepResult:
+        print("  🔴 Processing INACTIVE user")
+        return StepResult(output="Inactive user archived")
+    
+    # Test with active status
+    workflow = Workflow(
+        steps=[
+            if_(
+                condition="{{status}} == active",
+                then_steps=[process_active],
+                else_steps=[process_inactive]
+            )
+        ],
+        variables={"status": "active"}
+    )
+    
+    print("\nTest: status = 'active'")
+    workflow.start("Process user")
+    
+    # Test with inactive status
+    workflow2 = Workflow(
+        steps=[
+            if_(
+                condition="{{status}} == active",
+                then_steps=[process_active],
+                else_steps=[process_inactive]
+            )
+        ],
+        variables={"status": "inactive"}
+    )
+    
+    print("\nTest: status = 'inactive'")
+    workflow2.start("Process user")
+
+
+# =============================================================================
+# Example 3: Contains Condition - Content Filtering
+# =============================================================================
+
+def contains_condition_example():
+    """
+    Branch based on whether a string contains a substring.
+    """
+    print("\n" + "="*60)
+    print("Example 3: Contains Condition - Content Filtering")
+    print("="*60)
+    
+    def flag_content(ctx: WorkflowContext) -> StepResult:
+        print("  🚨 FLAGGED: Message contains sensitive content")
+        return StepResult(output="Content flagged for review")
+    
+    def approve_content(ctx: WorkflowContext) -> StepResult:
+        print("  ✅ APPROVED: Message is clean")
+        return StepResult(output="Content approved")
+    
+    # Test with flagged content
+    workflow1 = Workflow(
+        steps=[
+            if_(
+                condition="error in {{message}}",
+                then_steps=[flag_content],
+                else_steps=[approve_content]
+            )
+        ],
+        variables={"message": "System error: connection failed"}
+    )
+    
+    print("\nTest 1: Message contains 'error'")
+    workflow1.start("Filter content")
+    
+    # Test with clean content
+    workflow2 = Workflow(
+        steps=[
+            if_(
+                condition="error in {{message}}",
+                then_steps=[flag_content],
+                else_steps=[approve_content]
+            )
+        ],
+        variables={"message": "Operation completed successfully"}
+    )
+    
+    print("\nTest 2: Message is clean")
+    workflow2.start("Filter content")
+
+
+# =============================================================================
+# Example 4: If Inside Loop - Per-Item Decisions
+# =============================================================================
+
+def if_inside_loop_example():
+    """
+    Make decisions for each item in a collection.
+    Combines iteration with conditional branching.
+    """
+    print("\n" + "="*60)
+    print("Example 4: If Inside Loop - Per-Item Decisions")
+    print("="*60)
+    
+    results = {"premium": [], "standard": []}
+    
+    def premium_service(ctx: WorkflowContext) -> StepResult:
+        customer = ctx.variables.get("customer", {})
+        name = customer.get("name", "Unknown")
+        results["premium"].append(name)
+        print(f"  ⭐ {name}: Premium service activated")
+        return StepResult(output=f"Premium service for {name}")
+    
+    def standard_service(ctx: WorkflowContext) -> StepResult:
+        customer = ctx.variables.get("customer", {})
+        name = customer.get("name", "Unknown")
+        results["standard"].append(name)
+        print(f"  📦 {name}: Standard service activated")
+        return StepResult(output=f"Standard service for {name}")
+    
+    workflow = Workflow(
+        steps=[
+            loop(
+                steps=[
+                    if_(
+                        condition="{{customer.tier}} == premium",
+                        then_steps=[premium_service],
+                        else_steps=[standard_service]
+                    )
+                ],
+                over="customers",
+                var_name="customer"
+            )
+        ],
+        variables={
+            "customers": [
+                {"name": "Alice", "tier": "premium"},
+                {"name": "Bob", "tier": "standard"},
+                {"name": "Charlie", "tier": "premium"},
+                {"name": "Diana", "tier": "standard"}
+            ]
+        }
+    )
+    
+    print("\nProcessing customers:")
+    workflow.start("Assign service tiers")
+    
+    print(f"\nSummary:")
+    print(f"  Premium customers: {results['premium']}")
+    print(f"  Standard customers: {results['standard']}")
+
+
+# =============================================================================
+# Example 5: Nested Conditions - Multi-Level Decision Tree
+# =============================================================================
+
+def nested_conditions_example():
+    """
+    Demonstrate nested if conditions for complex decision trees.
+    """
+    print("\n" + "="*60)
+    print("Example 5: Nested Conditions - Decision Tree")
+    print("="*60)
+    
+    def vip_treatment(ctx: WorkflowContext) -> StepResult:
+        print("  👑 VIP Treatment: Dedicated support + Priority queue")
+        return StepResult(output="VIP treatment applied")  # noqa: ARG001
+    
+    def regular_premium(ctx: WorkflowContext) -> StepResult:
+        print("  ⭐ Premium: Priority support")
+        return StepResult(output="Premium support applied")
+    
+    def basic_support(ctx: WorkflowContext) -> StepResult:
+        print("  📞 Basic: Standard support queue")
+        return StepResult(output="Basic support applied")
+    
+    # Outer condition: Is premium?
+    # Inner condition (if premium): Is VIP?
+    workflow = Workflow(
+        steps=[
+            if_(
+                condition="{{tier}} == premium",
+                then_steps=[
+                    if_(
+                        condition="{{spend}} > 10000",
+                        then_steps=[vip_treatment],
+                        else_steps=[regular_premium]
+                    )
+                ],
+                else_steps=[basic_support]
+            )
+        ],
+        variables={"tier": "premium", "spend": 15000}
+    )
+    
+    print("\nTest 1: Premium tier, high spend")
+    workflow.start("Determine support level")
+    
+    workflow2 = Workflow(
+        steps=[
+            if_(
+                condition="{{tier}} == premium",
+                then_steps=[
+                    if_(
+                        condition="{{spend}} > 10000",
+                        then_steps=[vip_treatment],
+                        else_steps=[regular_premium]
+                    )
+                ],
+                else_steps=[basic_support]
+            )
+        ],
+        variables={"tier": "premium", "spend": 5000}
+    )
+    
+    print("\nTest 2: Premium tier, low spend")
+    workflow2.start("Determine support level")
+    
+    workflow3 = Workflow(
+        steps=[
+            if_(
+                condition="{{tier}} == premium",
+                then_steps=[
+                    if_(
+                        condition="{{spend}} > 10000",
+                        then_steps=[vip_treatment],
+                        else_steps=[regular_premium]
+                    )
+                ],
+                else_steps=[basic_support]
+            )
+        ],
+        variables={"tier": "basic", "spend": 20000}
+    )
+    
+    print("\nTest 3: Basic tier (regardless of spend)")
+    workflow3.start("Determine support level")
+
+
+# =============================================================================
+# Example 6: No Else Branch - Optional Processing
+# =============================================================================
+
+def no_else_example():
+    """
+    If condition without else branch - only execute if true.
+    """
+    print("\n" + "="*60)
+    print("Example 6: No Else Branch - Optional Processing")
+    print("="*60)
+    
+    def send_notification(ctx: WorkflowContext) -> StepResult:
+        print("  📧 Notification sent!")
+        return StepResult(output="Notification sent")
+    
+    def continue_processing(ctx: WorkflowContext) -> StepResult:
+        print("  ➡️ Continuing with main workflow...")
+        return StepResult(output="Continued")
+    
+    # Only send notification if opted in
+    workflow = Workflow(
+        steps=[
+            if_(
+                condition="{{notify}} == true",
+                then_steps=[send_notification]
+                # No else_steps - just skip if false
+            ),
+            continue_processing
+        ],
+        variables={"notify": "true"}
+    )
+    
+    print("\nTest 1: notify = true")
+    workflow.start("Process with notification")
+    
+    workflow2 = Workflow(
+        steps=[
+            if_(
+                condition="{{notify}} == true",
+                then_steps=[send_notification]
+            ),
+            continue_processing
+        ],
+        variables={"notify": "false"}
+    )
+    
+    print("\nTest 2: notify = false")
+    workflow2.start("Process without notification")
+
+
+# =============================================================================
+# Main - Run All Examples
+# =============================================================================
+
+if __name__ == "__main__":
+    print("\n" + "="*60)
+    print("PraisonAI Conditional Branching Examples")
+    print("="*60)
+    
+    basic_if_example()
+    string_condition_example()
+    contains_condition_example()
+    if_inside_loop_example()
+    nested_conditions_example()
+    no_else_example()
+    
+    print("\n" + "="*60)
+    print("All conditional branching examples completed!")
+    print("="*60)
@@ -0,0 +1,214 @@
+"""Example: Merge Strategies for Multi-Agent Workflows
+
+This example demonstrates how to use and create custom merge strategies
+for combining outputs from parallel agent executions.
+"""
+from praisonaiagents.agents import (
+    MergeStrategyProtocol,
+    FirstWinsMerge,
+    ConcatMerge,
+    DictMerge,
+)
+
+
+def example_first_wins_merge():
+    """Demonstrate FirstWinsMerge strategy."""
+    print("=" * 50)
+    print("FirstWinsMerge Examples")
+    print("=" * 50)
+    
+    merge = FirstWinsMerge()
+    
+    # 1. Basic usage - returns first non-None
+    print("\n1. Basic Usage:")
+    outputs = [None, "Agent 2 response", "Agent 3 response"]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 2. All None returns None
+    print("\n2. All None:")
+    outputs = [None, None, None]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 3. First value wins
+    print("\n3. First Value Wins:")
+    outputs = ["Fast agent", "Slow agent", "Slowest agent"]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 4. Works with any type
+    print("\n4. Various Types:")
+    print(f"   Dict: {merge.merge([None, {'key': 'value'}])}")
+    print(f"   List: {merge.merge([None, [1, 2, 3]])}")
+    print(f"   Number: {merge.merge([None, 42])}")
+
+
+def example_concat_merge():
+    """Demonstrate ConcatMerge strategy."""
+    print("\n" + "=" * 50)
+    print("ConcatMerge Examples")
+    print("=" * 50)
+    
+    # 1. Default separator (double newline)
+    print("\n1. Default Separator:")
+    merge = ConcatMerge()
+    outputs = ["Part 1: Introduction", "Part 2: Analysis", "Part 3: Conclusion"]
+    result = merge.merge(outputs)
+    print(f"   Result:\n{result}")
+    
+    # 2. Custom separator
+    print("\n2. Custom Separator:")
+    merge = ConcatMerge(separator=" | ")
+    outputs = ["Alice", "Bob", "Charlie"]
+    result = merge.merge(outputs)
+    print(f"   Result: {result}")
+    
+    # 3. Skips None values
+    print("\n3. Skips None:")
+    merge = ConcatMerge(separator=", ")
+    outputs = ["A", None, "C", None, "E"]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 4. Converts non-strings
+    print("\n4. Converts Non-Strings:")
+    merge = ConcatMerge(separator=" + ")
+    outputs = [1, 2, 3]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+
+
+def example_dict_merge():
+    """Demonstrate DictMerge strategy."""
+    print("\n" + "=" * 50)
+    print("DictMerge Examples")
+    print("=" * 50)
+    
+    # 1. Basic shallow merge
+    print("\n1. Shallow Merge (default):")
+    merge = DictMerge()
+    outputs = [
+        {"name": "Alice", "score": 10},
+        {"name": "Bob", "level": 5},
+        {"score": 20, "rank": 1}
+    ]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 2. Later values override
+    print("\n2. Override Behavior:")
+    merge = DictMerge()
+    outputs = [
+        {"status": "pending"},
+        {"status": "processing"},
+        {"status": "complete"}
+    ]
+    result = merge.merge(outputs)
+    print(f"   Result: {result}")
+    
+    # 3. Deep merge for nested dicts
+    print("\n3. Deep Merge:")
+    merge = DictMerge(deep=True)
+    outputs = [
+        {"config": {"a": 1, "b": 2}},
+        {"config": {"b": 3, "c": 4}},
+        {"config": {"d": 5}}
+    ]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 4. Skips non-dict values
+    print("\n4. Skips Non-Dict Values:")
+    merge = DictMerge()
+    outputs = [{"a": 1}, "not a dict", None, {"b": 2}]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+
+
+def example_custom_merge():
+    """Demonstrate creating custom merge strategies."""
+    print("\n" + "=" * 50)
+    print("Custom Merge Strategy Examples")
+    print("=" * 50)
+    
+    # 1. Longest output merge
+    class LongestOutputMerge:
+        """Returns the longest output."""
+        def merge(self, outputs, context=None):
+            valid = [o for o in outputs if o is not None]
+            if not valid:
+                return None
+            return max(valid, key=lambda x: len(str(x)))
+    
+    print("\n1. LongestOutputMerge:")
+    merge = LongestOutputMerge()
+    outputs = ["short", "medium length", "this is the longest response"]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result}")
+    
+    # 2. Majority vote merge
+    class MajorityVoteMerge:
+        """Returns the most common output."""
+        def merge(self, outputs, context=None):
+            from collections import Counter
+            valid = [o for o in outputs if o is not None]
+            if not valid:
+                return None
+            counts = Counter(valid)
+            return counts.most_common(1)[0][0]
+    
+    print("\n2. MajorityVoteMerge:")
+    merge = MajorityVoteMerge()
+    outputs = ["yes", "yes", "no", "yes", "no"]
+    result = merge.merge(outputs)
+    print(f"   Inputs: {outputs}")
+    print(f"   Result: {result} (3 votes)")
+    
+    # 3. Weighted merge
+    class WeightedMerge:
+        """Merges with agent weights from context."""
+        def merge(self, outputs, context=None):
+            weights = context.get("weights", [1] * len(outputs)) if context else [1] * len(outputs)
+            best_idx = 0
+            best_weight = 0
+            for i, (output, weight) in enumerate(zip(outputs, weights)):
+                if output is not None and weight > best_weight:
+                    best_idx = i
+                    best_weight = weight
+            return outputs[best_idx] if outputs else None
+    
+    print("\n3. WeightedMerge:")
+    merge = WeightedMerge()
+    outputs = ["junior answer", "senior answer", "expert answer"]
+    context = {"weights": [1, 5, 10]}
+    result = merge.merge(outputs, context=context)
+    print(f"   Inputs: {outputs}")
+    print(f"   Weights: {context['weights']}")
+    print(f"   Result: {result}")
+    
+    # 4. Protocol compliance
+    print("\n4. Protocol Compliance:")
+    print(f"   LongestOutputMerge: {isinstance(LongestOutputMerge(), MergeStrategyProtocol)}")
+    print(f"   MajorityVoteMerge: {isinstance(MajorityVoteMerge(), MergeStrategyProtocol)}")
+    print(f"   WeightedMerge: {isinstance(WeightedMerge(), MergeStrategyProtocol)}")
+
+
+if __name__ == "__main__":
+    example_first_wins_merge()
+    example_concat_merge()
+    example_dict_merge()
+    example_custom_merge()
+    
+    print("\n" + "=" * 50)
+    print("All examples completed!")
+    print("=" * 50)
@@ -0,0 +1,174 @@
+"""Example: Retry Policies and Fallback Chains
+
+This example demonstrates how to configure retry behavior with
+exponential backoff, jitter, and fallback chains.
+"""
+from praisonaiagents.tools import (
+    RetryPolicy,
+    FallbackChain,
+    ToolExecutionConfig,
+)
+
+
+def example_retry_policy():
+    """Demonstrate RetryPolicy configuration and usage."""
+    print("=" * 50)
+    print("RetryPolicy Examples")
+    print("=" * 50)
+    
+    # 1. Default policy
+    print("\n1. Default RetryPolicy:")
+    policy = RetryPolicy()
+    print(f"   max_attempts: {policy.max_attempts}")
+    print(f"   backoff_factor: {policy.backoff_factor}")
+    print(f"   initial_delay_ms: {policy.initial_delay_ms}")
+    print(f"   max_delay_ms: {policy.max_delay_ms}")
+    print(f"   retry_on: {policy.retry_on}")
+    
+    # 2. Exponential backoff calculation
+    print("\n2. Exponential Backoff (no jitter):")
+    policy = RetryPolicy(
+        initial_delay_ms=1000,
+        backoff_factor=2.0,
+        max_delay_ms=30000,
+        jitter=False
+    )
+    for attempt in range(5):
+        delay = policy.get_delay_ms(attempt)
+        print(f"   Attempt {attempt}: delay = {delay}ms")
+    
+    # 3. With jitter for production
+    print("\n3. With Jitter (production-ready):")
+    policy = RetryPolicy(
+        initial_delay_ms=1000,
+        backoff_factor=2.0,
+        jitter=True,
+        jitter_factor=0.25  # ±25%
+    )
+    print("   Delays for attempt 0 (10 samples):")
+    delays = [policy.get_delay_ms(0) for _ in range(10)]
+    print(f"   {delays}")
+    print(f"   Range: {min(delays)} - {max(delays)} (expected: 750-1250)")
+    
+    # 4. should_retry logic
+    print("\n4. should_retry Logic:")
+    policy = RetryPolicy(max_attempts=3, retry_on={"timeout", "rate_limit"})
+    
+    test_cases = [
+        ("timeout", 0),
+        ("timeout", 2),
+        ("timeout", 3),  # At max_attempts
+        ("unknown_error", 0),  # Not in retry_on
+    ]
+    for error_type, attempt in test_cases:
+        result = policy.should_retry(error_type, attempt)
+        print(f"   should_retry('{error_type}', {attempt}) = {result}")
+    
+    # 5. Custom error types
+    print("\n5. Custom Error Types:")
+    policy = RetryPolicy(retry_on={"api_error", "network_error", "throttled"})
+    print(f"   Retries on: {policy.retry_on}")
+    print(f"   should_retry('api_error', 0) = {policy.should_retry('api_error', 0)}")
+    print(f"   should_retry('timeout', 0) = {policy.should_retry('timeout', 0)}")
+
+
+def example_fallback_chain():
+    """Demonstrate FallbackChain configuration."""
+    print("\n" + "=" * 50)
+    print("FallbackChain Examples")
+    print("=" * 50)
+    
+    # 1. Basic chain
+    print("\n1. Basic FallbackChain:")
+    chain = FallbackChain(
+        tools=["web_search", "cached_search", "default_response"]
+    )
+    print(f"   Tools: {chain.tools}")
+    print(f"   Length: {len(chain)}")
+    print(f"   stop_on_success: {chain.stop_on_success}")
+    
+    # 2. Iteration
+    print("\n2. Iterating over chain:")
+    for i, tool in enumerate(chain):
+        print(f"   {i+1}. {tool}")
+    
+    # 3. Try all (don't stop on success)
+    print("\n3. Try All Mode:")
+    chain = FallbackChain(
+        tools=["validator_1", "validator_2", "validator_3"],
+        stop_on_success=False
+    )
+    print(f"   stop_on_success: {chain.stop_on_success}")
+    print("   (All tools will be tried regardless of success)")
+
+
+def example_tool_execution_config():
+    """Demonstrate ToolExecutionConfig combining retry and fallback."""
+    print("\n" + "=" * 50)
+    print("ToolExecutionConfig Examples")
+    print("=" * 50)
+    
+    # 1. Default config
+    print("\n1. Default Config:")
+    config = ToolExecutionConfig()
+    print(f"   retry_policy: {config.retry_policy}")
+    print(f"   fallback_chain: {config.fallback_chain}")
+    print(f"   timeout_ms: {config.timeout_ms}")
+    
+    # 2. Using default() factory
+    print("\n2. Default Factory:")
+    config = ToolExecutionConfig.default()
+    print(f"   retry_policy.max_attempts: {config.retry_policy.max_attempts}")
+    
+    # 3. Full configuration
+    print("\n3. Full Configuration:")
+    config = ToolExecutionConfig(
+        retry_policy=RetryPolicy(
+            max_attempts=5,
+            backoff_factor=1.5,
+            initial_delay_ms=500,
+            jitter=True
+        ),
+        fallback_chain=FallbackChain(
+            tools=["primary_api", "backup_api", "cache"]
+        ),
+        timeout_ms=10000
+    )
+    print(f"   retry_policy.max_attempts: {config.retry_policy.max_attempts}")
+    print(f"   retry_policy.jitter: {config.retry_policy.jitter}")
+    print(f"   fallback_chain tools: {config.fallback_chain.tools}")
+    print(f"   timeout_ms: {config.timeout_ms}")
+
+
+def example_validation():
+    """Demonstrate validation of RetryPolicy parameters."""
+    print("\n" + "=" * 50)
+    print("Validation Examples")
+    print("=" * 50)
+    
+    invalid_configs = [
+        ("max_attempts=0", {"max_attempts": 0}),
+        ("backoff_factor=0.5", {"backoff_factor": 0.5}),
+        ("initial_delay_ms=-1", {"initial_delay_ms": -1}),
+        ("max_delay < initial", {"initial_delay_ms": 1000, "max_delay_ms": 500}),
+        ("jitter_factor=1.5", {"jitter_factor": 1.5}),
+    ]
+    
+    for name, kwargs in invalid_configs:
+        try:
+            RetryPolicy(**kwargs)
+            print(f"\n   {name}: No error (unexpected!)")
+        except ValueError as e:
+            print(f"\n   {name}:")
+            print(f"   → ValueError: {e}")
+
+
+if __name__ == "__main__":
+    example_retry_policy()
+    example_fallback_chain()
+    example_tool_execution_config()
+    example_validation()
+    
+    print("\n" + "=" * 50)
+    print("All examples completed!")
+    print("=" * 50)
@@ -0,0 +1,163 @@
+"""Example: Tool Validation with Custom Validators
+
+This example demonstrates how to use ValidationResult and implement
+custom validators using the ToolValidatorProtocol.
+"""
+from praisonaiagents.tools import (
+    ValidationResult,
+    ToolValidatorProtocol,
+    PassthroughValidator,
+)
+
+
+def example_validation_result():
+    """Demonstrate ValidationResult usage."""
+    print("=" * 50)
+    print("ValidationResult Examples")
+    print("=" * 50)
+    
+    # 1. Success factory
+    success = ValidationResult.success()
+    print(f"\n1. Success: valid={success.valid}, bool={bool(success)}")
+    
+    # 2. Failure factory
+    failure = ValidationResult.failure(
+        errors=["Query cannot be empty", "Missing required field"],
+        remediation="Provide a non-empty query string"
+    )
+    print(f"\n2. Failure: valid={failure.valid}")
+    print(f"   Errors: {failure.errors}")
+    print(f"   Remediation: {failure.remediation}")
+    
+    # 3. Fluent API - building incrementally
+    result = ValidationResult(valid=True)
+    result.add_warning("Query is very long, may be slow")
+    result.add_warning("Consider using pagination")
+    print(f"\n3. With warnings: valid={result.valid}, warnings={result.warnings}")
+    
+    # 4. Adding errors changes validity
+    result.add_error("Rate limit exceeded")
+    print(f"\n4. After error: valid={result.valid}, errors={result.errors}")
+
+
+class InputLengthValidator:
+    """Custom validator that checks string input lengths."""
+    
+    def __init__(self, max_length: int = 100):
+        self.max_length = max_length
+    
+    def validate_args(self, tool_name, args, context=None):
+        """Validate that string arguments don't exceed max length."""
+        for key, value in args.items():
+            if isinstance(value, str) and len(value) > self.max_length:
+                return ValidationResult.failure(
+                    errors=[f"Argument '{key}' ({len(value)} chars) exceeds limit ({self.max_length})"],
+                    remediation=f"Truncate '{key}' to {self.max_length} characters or less"
+                )
+        return ValidationResult.success()
+    
+    def validate_result(self, tool_name, result, context=None):
+        """Validate tool results."""
+        return ValidationResult.success()
+
+
+class TypeValidator:
+    """Custom validator that checks argument types."""
+    
+    def __init__(self, type_specs: dict):
+        """
+        Args:
+            type_specs: Dict mapping arg names to expected types
+                       e.g., {"query": str, "limit": int}
+        """
+        self.type_specs = type_specs
+    
+    def validate_args(self, tool_name, args, context=None):
+        result = ValidationResult(valid=True)
+        
+        for arg_name, expected_type in self.type_specs.items():
+            if arg_name in args:
+                actual_value = args[arg_name]
+                if not isinstance(actual_value, expected_type):
+                    result.add_error(
+                        f"Argument '{arg_name}' must be {expected_type.__name__}, "
+                        f"got {type(actual_value).__name__}"
+                    )
+        
+        if not result.valid:
+            result.remediation = "Check argument types and try again"
+        
+        return result
+    
+    def validate_result(self, tool_name, result, context=None):
+        return ValidationResult.success()
+
+
+def example_custom_validators():
+    """Demonstrate custom validator implementations."""
+    print("\n" + "=" * 50)
+    print("Custom Validator Examples")
+    print("=" * 50)
+    
+    # 1. InputLengthValidator
+    print("\n1. InputLengthValidator:")
+    validator = InputLengthValidator(max_length=50)
+    
+    # Valid input
+    result = validator.validate_args("search", {"query": "short query"})
+    print(f"   Short query: valid={result.valid}")
+    
+    # Invalid input
+    long_query = "x" * 100
+    result = validator.validate_args("search", {"query": long_query})
+    print(f"   Long query: valid={result.valid}")
+    print(f"   Error: {result.errors[0]}")
+    print(f"   Fix: {result.remediation}")
+    
+    # 2. TypeValidator
+    print("\n2. TypeValidator:")
+    validator = TypeValidator({"query": str, "limit": int, "offset": int})
+    
+    # Valid types
+    result = validator.validate_args("search", {"query": "test", "limit": 10})
+    print(f"   Correct types: valid={result.valid}")
+    
+    # Invalid types
+    result = validator.validate_args("search", {"query": 123, "limit": "ten"})
+    print(f"   Wrong types: valid={result.valid}")
+    for error in result.errors:
+        print(f"   - {error}")
+    
+    # 3. Protocol compliance check
+    print("\n3. Protocol Compliance:")
+    print(f"   InputLengthValidator: {isinstance(InputLengthValidator(), ToolValidatorProtocol)}")
+    print(f"   TypeValidator: {isinstance(TypeValidator({}), ToolValidatorProtocol)}")
+    print(f"   PassthroughValidator: {isinstance(PassthroughValidator(), ToolValidatorProtocol)}")
+
+
+def example_passthrough_validator():
+    """Demonstrate the default PassthroughValidator."""
+    print("\n" + "=" * 50)
+    print("PassthroughValidator Example")
+    print("=" * 50)
+    
+    validator = PassthroughValidator()
+    
+    # Always returns valid
+    result = validator.validate_args("any_tool", {"any": "args"})
+    print(f"\nvalidate_args: valid={result.valid}")
+    
+    result = validator.validate_result("any_tool", {"any": "result"})
+    print(f"validate_result: valid={result.valid}")
+    
+    print("\nPassthroughValidator is useful as a default when no validation is needed.")
+
+
+if __name__ == "__main__":
+    example_validation_result()
+    example_custom_validators()
+    example_passthrough_validator()
+    
+    print("\n" + "=" * 50)
+    print("All examples completed!")
+    print("=" * 50)
@@ -0,0 +1,170 @@
+"""
+Model Failover Example - Automatic Provider Switching
+
+This example demonstrates how to configure model failover
+for reliability and cost optimization.
+"""
+
+import os
+from praisonaiagents import (
+    AuthProfile,
+    FailoverConfig,
+    FailoverManager,
+)
+
+# Create auth profiles for different providers
+openai_profile = AuthProfile(
+    name="openai-primary",
+    provider="openai",
+    api_key=os.environ.get("OPENAI_API_KEY", "sk-..."),
+    priority=1,  # Highest priority
+    rate_limit=100,
+)
+
+anthropic_profile = AuthProfile(
+    name="anthropic-backup",
+    provider="anthropic",
+    api_key=os.environ.get("ANTHROPIC_API_KEY", "sk-ant-..."),
+    priority=2,  # Second priority
+    rate_limit=50,
+)
+
+groq_profile = AuthProfile(
+    name="groq-fallback",
+    provider="groq",
+    api_key=os.environ.get("GROQ_API_KEY", "gsk-..."),
+    priority=3,  # Third priority (fast but limited)
+    rate_limit=30,
+)
+
+# Configure failover behavior
+failover_config = FailoverConfig(
+    max_retries=3,
+    retry_delay=1.0,
+    exponential_backoff=True,
+    max_retry_delay=60.0,
+    failover_on_rate_limit=True,
+    failover_on_timeout=True,
+    failover_on_error=True,
+)
+
+# Create failover manager
+manager = FailoverManager(failover_config)
+manager.add_profile(openai_profile)
+manager.add_profile(anthropic_profile)
+manager.add_profile(groq_profile)
+
+def demonstrate_failover():
+    """Demonstrate failover functionality."""
+    
+    print("Failover Manager Status:")
+    print()
+    
+    # Get current status
+    status = manager.status()
+    for name, info in status.items():
+        print(f"  {name}:")
+        print(f"    Status: {info.get('status', 'unknown')}")
+        print(f"    Priority: {info.get('priority', 'N/A')}")
+        print(f"    Failures: {info.get('failure_count', 0)}")
+    print()
+    
+    # Get next available profile
+    next_profile = manager.get_next_profile()
+    if next_profile:
+        print(f"Next profile to use: {next_profile.name}")
+        print(f"  Provider: {next_profile.provider}")
+        print(f"  Priority: {next_profile.priority}")
+    print()
+    
+    # Simulate marking a failure
+    print("Simulating failure on primary provider...")
+    manager.mark_failure("openai-primary", "Rate limit exceeded")
+    
+    # Get next profile after failure
+    next_profile = manager.get_next_profile()
+    if next_profile:
+        print(f"After failure, next profile: {next_profile.name}")
+    print()
+    
+    # Get retry delay
+    delay = manager.get_retry_delay("openai-primary")
+    print(f"Retry delay for openai-primary: {delay}s")
+    print()
+    
+    # Reset all providers
+    print("Resetting all providers...")
+    manager.reset_all()
+    
+    next_profile = manager.get_next_profile()
+    if next_profile:
+        print(f"After reset, next profile: {next_profile.name}")
+
+def cost_optimization_example():
+    """Example of cost-optimized failover."""
+    
+    print("\nCost Optimization Example:")
+    print("-" * 40)
+    
+    # Create cost-optimized manager
+    cost_manager = FailoverManager()
+    
+    # Cheaper model first
+    cost_manager.add_profile(AuthProfile(
+        name="gpt-4o-mini",
+        provider="openai",
+        api_key=os.environ.get("OPENAI_API_KEY", ""),
+        priority=1,
+        metadata={"model": "gpt-4o-mini", "cost_per_1k": 0.00015}
+    ))
+    
+    # Premium model as fallback
+    cost_manager.add_profile(AuthProfile(
+        name="gpt-4o",
+        provider="openai",
+        api_key=os.environ.get("OPENAI_API_KEY", ""),
+        priority=2,
+        metadata={"model": "gpt-4o", "cost_per_1k": 0.005}
+    ))
+    
+    # Most expensive as last resort
+    cost_manager.add_profile(AuthProfile(
+        name="claude-opus",
+        provider="anthropic",
+        api_key=os.environ.get("ANTHROPIC_API_KEY", ""),
+        priority=3,
+        metadata={"model": "claude-3-opus", "cost_per_1k": 0.015}
+    ))
+    
+    print("Cost-optimized failover chain:")
+    for profile in [
+        cost_manager.get_profile("gpt-4o-mini"),
+        cost_manager.get_profile("gpt-4o"),
+        cost_manager.get_profile("claude-opus"),
+    ]:
+        if profile:
+            cost = profile.metadata.get("cost_per_1k", "N/A")
+            print(f"  {profile.priority}. {profile.name} (${cost}/1K tokens)")
+
+if __name__ == "__main__":
+    print("Model Failover Configuration")
+    print("=" * 40)
+    print()
+    
+    print("Failover Config:")
+    print(f"  Max retries: {failover_config.max_retries}")
+    print(f"  Initial delay: {failover_config.retry_delay}s")
+    print(f"  Exponential backoff: {failover_config.exponential_backoff}")
+    print(f"  Max delay: {failover_config.max_retry_delay}s")
+    print()
+    
+    print("Auth Profiles:")
+    for profile in [openai_profile, anthropic_profile, groq_profile]:
+        print(f"  {profile.name}:")
+        print(f"    Provider: {profile.provider}")
+        print(f"    Priority: {profile.priority}")
+        print(f"    Rate limit: {profile.rate_limit} req/min")
+    print()
+    
+    demonstrate_failover()
+    cost_optimization_example()
@@ -0,0 +1,47 @@
+"""
+Gateway Example - Multi-Agent Coordination
+
+This example demonstrates how to use the Gateway for coordinating
+multiple agents and managing real-time communication.
+"""
+
+from praisonaiagents import Agent, GatewayConfig, SessionConfig
+
+# Configure the gateway
+gateway_config = GatewayConfig(
+    host="127.0.0.1",
+    port=8765,
+    max_connections=100,
+    heartbeat_interval=30,
+    session_config=SessionConfig(
+        timeout=3600,  # 1 hour session timeout
+        max_messages=500,
+    )
+)
+
+# Create specialized agents
+researcher = Agent(
+    name="researcher",
+    instructions="You research topics thoroughly and provide detailed information.",
+    llm="gpt-4o-mini"
+)
+
+writer = Agent(
+    name="writer",
+    instructions="You write clear, engaging content based on research.",
+    llm="gpt-4o-mini"
+)
+
+# Example: Simple agent interaction
+if __name__ == "__main__":
+    print("Gateway Configuration:")
+    print(f"  Host: {gateway_config.host}")
+    print(f"  Port: {gateway_config.port}")
+    print(f"  WebSocket URL: {gateway_config.ws_url}")
+    print(f"  Max Connections: {gateway_config.max_connections}")
+    print()
+    
+    # Test agent
+    response = researcher.start("What are the key benefits of multi-agent systems?")
+    print("Researcher Response:")
+    print(response)
@@ -0,0 +1,17 @@
+from praisonaiagents import ImageAgent
+
+agent = ImageAgent(llm="openai/dall-e-3", style="vivid")
+
+# Generate with options
+result = agent.generate("A futuristic city", size="1792x1024", quality="hd")
+print(result.data[0].url)
+
+# Edit image (dall-e-2 only)
+agent2 = ImageAgent(llm="openai/dall-e-2")
+edited = agent2.edit("photo.png", "Add a rainbow")
+print(edited.data[0].url)
+
+# Generate variations
+variations = agent2.variation("photo.png", n=3)
+for img in variations.data:
+    print(img.url)
@@ -0,0 +1,8 @@
+# Image Generation with DALL-E
+# Requires: export OPENAI_API_KEY=your-key
+
+from praisonaiagents import ImageAgent
+
+agent = ImageAgent(llm="openai/dall-e-3")
+result = agent.generate("A sunset over mountains")
+print(result.data[0].url)
@@ -0,0 +1,72 @@
+"""
+MCP Auth Storage Example
+
+This example demonstrates how to use the MCPAuthStorage class
+to manage OAuth tokens for remote MCP servers.
+"""
+
+from praisonaiagents.mcp import (
+    MCPAuthStorage,
+    generate_state,
+    generate_code_verifier,
+    generate_code_challenge,
+    get_redirect_url
+)
+import time
+
+# Initialize auth storage
+storage = MCPAuthStorage()
+print(f"Auth storage path: {storage.filepath}")
+
+# Generate PKCE parameters for OAuth flow
+state = generate_state()
+verifier = generate_code_verifier()
+challenge = generate_code_challenge(verifier)
+redirect_url = get_redirect_url()
+
+print("\n=== PKCE Parameters ===")
+print(f"State: {state[:30]}...")
+print(f"Verifier: {verifier[:30]}...")
+print(f"Challenge: {challenge[:30]}...")
+print(f"Redirect URL: {redirect_url}")
+
+# Store tokens (simulating OAuth callback)
+print("\n=== Storing Tokens ===")
+storage.set_tokens("example-server", {
+    "access_token": "example_access_token_12345",
+    "refresh_token": "example_refresh_token_67890",
+    "expires_at": time.time() + 3600,  # 1 hour from now
+    "scope": "read write"
+}, server_url="https://mcp.example.com/mcp")
+print("Tokens stored successfully")
+
+# Retrieve tokens
+entry = storage.get("example-server")
+print("\n=== Retrieved Entry ===")
+print(f"Server URL: {entry['server_url']}")
+print(f"Access Token: {entry['tokens']['access_token'][:20]}...")
+print(f"Expires At: {entry['tokens']['expires_at']}")
+
+# Check token expiration
+is_expired = storage.is_token_expired("example-server")
+print("\n=== Token Status ===")
+print(f"Is Expired: {is_expired}")
+
+# URL validation
+print("\n=== URL Validation ===")
+valid = storage.get_for_url("example-server", "https://mcp.example.com/mcp")
+print(f"Same URL: {valid is not None}")
+
+invalid = storage.get_for_url("example-server", "https://different.url/mcp")
+print(f"Different URL: {invalid is None}")
+
+# List all entries
+print("\n=== All Entries ===")
+all_entries = storage.all()
+for name, entry in all_entries.items():
+    print(f"  {name}: {entry.get('server_url', 'N/A')}")
+
+# Cleanup
+storage.remove("example-server")
+print("\n=== Cleanup ===")
+print("Removed example-server entry")
@@ -0,0 +1,32 @@
+"""
+Remote MCP Server with OAuth Authentication Example
+
+This example shows how to connect to a remote MCP server
+that requires OAuth 2.1 authentication.
+
+Prerequisites:
+1. Configure the remote server in ~/.praison/config.yaml
+2. Run: praisonai mcp auth <server-name>
+"""
+
+from praisonaiagents import Agent, MCP
+from praisonaiagents.mcp import MCPAuthStorage
+
+# Check if authenticated
+storage = MCPAuthStorage()
+entry = storage.get("my-remote-server")
+
+if not entry or not entry.get("tokens"):
+    print("Not authenticated. Run: praisonai mcp auth my-remote-server")
+    exit(1)
+
+# Create agent with remote MCP server
+agent = Agent(
+    name="Remote Assistant",
+    instructions="You help with tasks using the remote MCP server.",
+    llm="gpt-4o-mini",
+    tools=MCP("https://mcp.example.com/mcp")
+)
+
+# Start the agent
+agent.start("What tools are available?")
@@ -0,0 +1,72 @@
+"""
+Example: Memory with Tracing
+
+This example demonstrates how to use memory with context tracing enabled.
+When tracing is enabled, memory operations (store/search) emit trace events
+that can be used for debugging and analysis with the LLM Judge.
+
+Usage:
+    python memory_with_tracing_example.py
+
+To judge the trace:
+    praisonai recipe judge <trace_id> --memory
+"""
+
+from praisonaiagents.memory import Memory
+from praisonaiagents.trace.context_events import (
+    ContextTraceEmitter, 
+    ContextListSink,
+    set_context_emitter,
+    reset_context_emitter,
+)
+
+
+def main():
+    # Set up trace emitter to capture events
+    sink = ContextListSink()
+    emitter = ContextTraceEmitter(sink=sink, session_id="memory-demo", enabled=True)
+    token = set_context_emitter(emitter)
+    
+    try:
+        # Create memory instance
+        memory = Memory(config={
+            "provider": "rag",
+            "use_embedding": False,
+            "agent_name": "demo_agent",  # Used in trace events
+        })
+        
+        # Store some memories
+        print("Storing memories...")
+        memory.store_short_term("The user's name is Alice")
+        memory.store_short_term("Alice likes Python programming")
+        memory.store_long_term("Important: Alice prefers dark mode in all applications")
+        
+        # Search memories
+        print("\nSearching memories...")
+        results = memory.search_short_term("Alice", limit=5)
+        print(f"Found {len(results)} short-term memories")
+        
+        results = memory.search_long_term("preferences", limit=5)
+        print(f"Found {len(results)} long-term memories")
+        
+        # Print captured trace events
+        events = sink.get_events()
+        print(f"\n--- Captured {len(events)} trace events ---")
+        for event in events:
+            print(f"  {event.event_type.value}: {event.data}")
+        
+        # Filter memory-specific events
+        memory_events = [e for e in events if 'memory' in e.event_type.value]
+        print(f"\n--- Memory-specific events: {len(memory_events)} ---")
+        for event in memory_events:
+            print(f"  {event.event_type.value}:")
+            print(f"    agent: {event.agent_name}")
+            print(f"    data: {event.data}")
+        
+    finally:
+        reset_context_emitter(token)
+        print("\nTrace emitter reset.")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,252 @@
+"""
+Nested Workflows Example - PraisonAI Agents
+
+This example demonstrates how to use nested workflow patterns:
+1. Loop inside Loop (nested iteration)
+2. Parallel inside Loop (concurrent processing per item)
+3. Route inside Loop (conditional routing per item)
+4. Depth limit protection (prevents infinite recursion)
+
+These patterns enable complex data processing pipelines
+while maintaining clean, readable workflow definitions.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop, parallel, route
+
+
+# =============================================================================
+# Example 1: Nested Loops - Process Matrix Data
+# =============================================================================
+
+def nested_loop_example():
+    """
+    Process a 2D matrix using nested loops.
+    Outer loop iterates rows, inner loop iterates columns.
+    """
+    print("\n" + "="*60)
+    print("Example 1: Nested Loops - Matrix Processing")
+    print("="*60)
+    
+    results = []
+    
+    def process_cell(ctx: WorkflowContext) -> StepResult:
+        row = ctx.variables.get("row", {})
+        col = ctx.variables.get("col", "")
+        row_name = row.get("name", "?")
+        results.append(f"{row_name}-{col}")
+        return StepResult(output=f"Processed cell {row_name}-{col}")
+    
+    # Inner loop processes columns for each row
+    inner_loop = loop(
+        process_cell,
+        over="columns",
+        var_name="col"
+    )
+    
+    # Outer loop iterates through rows
+    outer_loop = loop(
+        steps=[inner_loop],
+        over="rows",
+        var_name="row"
+    )
+    
+    workflow = Workflow(
+        steps=[outer_loop],
+        variables={
+            "rows": [
+                {"name": "Row1"},
+                {"name": "Row2"}
+            ],
+            "columns": ["A", "B", "C"]
+        }
+    )
+    
+    workflow.start("Process matrix")
+    print(f"Processed cells: {results}")
+    # Output: ['Row1-A', 'Row1-B', 'Row1-C', 'Row2-A', 'Row2-B', 'Row2-C']
+
+
+# =============================================================================
+# Example 2: Parallel Inside Loop - Concurrent Task Processing
+# =============================================================================
+
+def parallel_inside_loop_example():
+    """
+    For each project, run multiple analysis tasks in parallel.
+    Combines iteration with concurrent execution.
+    """
+    print("\n" + "="*60)
+    print("Example 2: Parallel Inside Loop - Concurrent Analysis")
+    print("="*60)
+    
+    results = []
+    
+    def security_scan(ctx: WorkflowContext) -> StepResult:
+        project = ctx.variables.get("project", "unknown")
+        results.append(f"security:{project}")
+        return StepResult(output=f"Security scan complete for {project}")
+    
+    def performance_test(ctx: WorkflowContext) -> StepResult:
+        project = ctx.variables.get("project", "unknown")
+        results.append(f"performance:{project}")
+        return StepResult(output=f"Performance test complete for {project}")
+    
+    def code_review(ctx: WorkflowContext) -> StepResult:
+        project = ctx.variables.get("project", "unknown")
+        results.append(f"review:{project}")
+        return StepResult(output=f"Code review complete for {project}")
+    
+    # Parallel tasks run concurrently for each project
+    parallel_analysis = parallel([security_scan, performance_test, code_review])
+    
+    # Loop through projects, running parallel analysis for each
+    workflow = Workflow(
+        steps=[
+            loop(
+                steps=[parallel_analysis],
+                over="projects",
+                var_name="project"
+            )
+        ],
+        variables={
+            "projects": ["frontend", "backend", "api"]
+        }
+    )
+    
+    workflow.start("Analyze all projects")
+    print(f"Analysis results: {sorted(results)}")
+
+
+# =============================================================================
+# Example 3: Route Inside Loop - Conditional Processing Per Item
+# =============================================================================
+
+def route_inside_loop_example():
+    """
+    Process items differently based on their type.
+    Each item in the loop is routed to the appropriate handler.
+    """
+    print("\n" + "="*60)
+    print("Example 3: Route Inside Loop - Type-Based Processing")
+    print("="*60)
+    
+    results = []
+    
+    def process_image(ctx: WorkflowContext) -> StepResult:
+        item = ctx.variables.get("item", {})
+        results.append(f"image:{item.get('name')}")
+        return StepResult(output=f"Processed image: {item.get('name')}")
+    
+    def process_video(ctx: WorkflowContext) -> StepResult:
+        item = ctx.variables.get("item", {})
+        results.append(f"video:{item.get('name')}")
+        return StepResult(output=f"Processed video: {item.get('name')}")
+    
+    def process_document(ctx: WorkflowContext) -> StepResult:
+        item = ctx.variables.get("item", {})
+        results.append(f"document:{item.get('name')}")
+        return StepResult(output=f"Processed document: {item.get('name')}")
+    
+    # Route based on item type
+    type_router = route({
+        "image": [process_image],
+        "video": [process_video],
+        "document": [process_document]
+    })
+    
+    # First, determine the type, then route
+    def get_type(ctx: WorkflowContext) -> StepResult:
+        item = ctx.variables.get("item", {})
+        item_type = item.get("type", "unknown")
+        return StepResult(output=item_type)
+    
+    workflow = Workflow(
+        steps=[
+            loop(
+                steps=[get_type, type_router],
+                over="files",
+                var_name="item"
+            )
+        ],
+        variables={
+            "files": [
+                {"name": "photo.jpg", "type": "image"},
+                {"name": "movie.mp4", "type": "video"},
+                {"name": "report.pdf", "type": "document"},
+                {"name": "logo.png", "type": "image"}
+            ]
+        }
+    )
+    
+    workflow.start("Process all files")
+    print(f"Processing results: {results}")
+
+
+# =============================================================================
+# Example 4: Three-Level Nesting - Complex Data Pipeline
+# =============================================================================
+
+def three_level_nesting_example():
+    """
+    Demonstrate three levels of nesting:
+    Department -> Team -> Member
+    """
+    print("\n" + "="*60)
+    print("Example 4: Three-Level Nesting - Organization Processing")
+    print("="*60)
+    
+    results = []
+    
+    def process_member(ctx: WorkflowContext) -> StepResult:
+        dept = ctx.variables.get("dept", {}).get("name", "?")
+        team = ctx.variables.get("team", {}).get("name", "?")
+        member = ctx.variables.get("member", "?")
+        results.append(f"{dept}/{team}/{member}")
+        return StepResult(output=f"Processed {member}")
+    
+    # Level 3: Process each member
+    member_loop = loop(process_member, over="members", var_name="member")
+    
+    # Level 2: Process each team (contains member loop)
+    team_loop = loop(steps=[member_loop], over="teams", var_name="team")
+    
+    # Level 1: Process each department (contains team loop)
+    dept_loop = loop(steps=[team_loop], over="departments", var_name="dept")
+    
+    workflow = Workflow(
+        steps=[dept_loop],
+        variables={
+            "departments": [
+                {"name": "Engineering"},
+                {"name": "Marketing"}
+            ],
+            "teams": [
+                {"name": "Frontend", "members": ["Alice", "Bob"]},
+                {"name": "Backend", "members": ["Charlie"]}
+            ],
+            "members": ["Member1", "Member2"]  # Simplified for demo
+        }
+    )
+    
+    workflow.start("Process organization")
+    print(f"Processed paths: {results}")
+
+
+# =============================================================================
+# Main - Run All Examples
+# =============================================================================
+
+if __name__ == "__main__":
+    print("\n" + "="*60)
+    print("PraisonAI Nested Workflows Examples")
+    print("="*60)
+    
+    nested_loop_example()
+    parallel_inside_loop_example()
+    route_inside_loop_example()
+    three_level_nesting_example()
+    
+    print("\n" + "="*60)
+    print("All nested workflow examples completed!")
+    print("="*60)
@@ -0,0 +1,12 @@
+from praisonaiagents import OCRAgent
+
+agent = OCRAgent()
+
+# Extract with page selection (pages is 0-indexed)
+result = agent.extract("https://arxiv.org/pdf/2201.04234", pages=[0, 1])
+for page in result.pages:
+    print(f"Page {page.index}: {page.markdown[:200]}")
+
+# Quick read - just get the text
+text = agent.read("https://arxiv.org/pdf/2201.04234")
+print(f"Total length: {len(text)} chars")
@@ -0,0 +1,9 @@
+# OCR with Mistral
+# Requires: export MISTRAL_API_KEY=your-key
+# Note: Source must be a URL (https://) or base64
+
+from praisonaiagents import OCRAgent
+
+agent = OCRAgent()
+text = agent.read("https://arxiv.org/pdf/2201.04234")
+print(text[:500])  # First 500 chars
@@ -0,0 +1,5 @@
+from praisonaiagents import OCRAgent
+
+agent = OCRAgent(llm="mistral/mistral-ocr-latest")
+text = agent.read("https://arxiv.org/pdf/2201.04234")
+print(text[:500])  # First 500 chars
@@ -0,0 +1,137 @@
+"""
+Sandbox Example - Secure Code Execution
+
+This example demonstrates how to configure and use sandboxes
+for safe code execution.
+"""
+
+from praisonaiagents import (
+    SandboxConfig, 
+    ResourceLimits, 
+    SandboxResult, 
+    SandboxStatus
+)
+from praisonaiagents.sandbox import SecurityPolicy
+
+# Minimal sandbox for untrusted code
+minimal_sandbox = SandboxConfig(
+    sandbox_type="subprocess",
+    resource_limits=ResourceLimits.minimal(),
+    security_policy=SecurityPolicy.strict(),
+)
+
+# Standard sandbox for general use
+standard_sandbox = SandboxConfig(
+    sandbox_type="subprocess",
+    resource_limits=ResourceLimits.standard(),
+    security_policy=SecurityPolicy.standard(),
+)
+
+# Docker sandbox for full isolation
+docker_sandbox = SandboxConfig.docker(image="python:3.11-slim")
+
+# Custom sandbox configuration
+custom_sandbox = SandboxConfig(
+    sandbox_type="subprocess",
+    working_dir="/tmp/sandbox",
+    resource_limits=ResourceLimits(
+        memory_mb=256,
+        cpu_percent=50,
+        timeout_seconds=30,
+        network_enabled=False,
+        max_processes=5,
+    ),
+    security_policy=SecurityPolicy(
+        allow_network=False,
+        allow_file_write=True,
+        allow_subprocess=False,
+        blocked_imports=["subprocess", "os.system", "eval"],
+    ),
+    auto_cleanup=True,
+)
+
+def demonstrate_result_handling():
+    """Show how to handle sandbox results."""
+    
+    # Simulated successful result
+    success_result = SandboxResult(
+        status=SandboxStatus.COMPLETED,
+        exit_code=0,
+        stdout="Hello, World!\n",
+        stderr="",
+        duration_seconds=0.1,
+    )
+    
+    # Simulated timeout result
+    timeout_result = SandboxResult(
+        status=SandboxStatus.TIMEOUT,
+        exit_code=None,
+        stdout="Partial output...",
+        stderr="",
+        error="Execution timed out after 30 seconds",
+        duration_seconds=30.0,
+    )
+    
+    # Simulated error result
+    error_result = SandboxResult(
+        status=SandboxStatus.FAILED,
+        exit_code=1,
+        stdout="",
+        stderr="NameError: name 'undefined_var' is not defined",
+        error="Execution failed",
+    )
+    
+    print("Result Handling Examples:")
+    print()
+    
+    for name, result in [
+        ("Success", success_result),
+        ("Timeout", timeout_result),
+        ("Error", error_result)
+    ]:
+        print(f"{name} Result:")
+        print(f"  Status: {result.status.name}")
+        print(f"  Success: {result.success}")
+        if result.stdout:
+            print(f"  Output: {result.stdout.strip()}")
+        if result.stderr:
+            print(f"  Error: {result.stderr.strip()}")
+        if result.error:
+            print(f"  Message: {result.error}")
+        print()
+
+if __name__ == "__main__":
+    print("Sandbox Configurations:")
+    print()
+    
+    print("Minimal Sandbox (for untrusted code):")
+    print(f"  Type: {minimal_sandbox.sandbox_type}")
+    print(f"  Memory: {minimal_sandbox.resource_limits.memory_mb}MB")
+    print(f"  Timeout: {minimal_sandbox.resource_limits.timeout_seconds}s")
+    print(f"  Network: {minimal_sandbox.resource_limits.network_enabled}")
+    print()
+    
+    print("Standard Sandbox:")
+    print(f"  Type: {standard_sandbox.sandbox_type}")
+    print(f"  Memory: {standard_sandbox.resource_limits.memory_mb}MB")
+    print(f"  Timeout: {standard_sandbox.resource_limits.timeout_seconds}s")
+    print()
+    
+    print("Docker Sandbox:")
+    print(f"  Type: {docker_sandbox.sandbox_type}")
+    print(f"  Image: {docker_sandbox.image}")
+    print()
+    
+    print("Custom Sandbox:")
+    print(f"  Type: {custom_sandbox.sandbox_type}")
+    print(f"  Working Dir: {custom_sandbox.working_dir}")
+    print(f"  Memory: {custom_sandbox.resource_limits.memory_mb}MB")
+    print(f"  Max Processes: {custom_sandbox.resource_limits.max_processes}")
+    print()
+    
+    demonstrate_result_handling()
+    
+    print("To run code in sandbox via CLI:")
+    print("  praisonai sandbox run \"print('Hello, World!')\"")
+    print("  praisonai sandbox run --file script.py")
+    print("  praisonai sandbox shell")
@@ -0,0 +1,22 @@
+"""
+Example 1: Save Agent Output Using write_file Tool
+
+The agent decides when and what to save based on the task.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools import write_file
+
+# Create agent with write_file tool
+agent = Agent(
+    name="ContentWriter",
+    role="Technical Writer",
+    goal="Create and save technical documentation",
+    tools=[write_file]
+)
+
+# Agent will use write_file tool to save the content
+result = agent.start("Write a short poem about coding and save it to poem.txt")
+
+print("✅ Task completed!")
+print(f"Result: {result}")
@@ -0,0 +1,30 @@
+"""
+Example 2: Save Agent Output Using Task.output_file
+
+Task output is automatically saved to the specified file.
+"""
+
+from praisonaiagents import Agent, Task, Agents
+
+# Create agent
+writer = Agent(
+    name="ContentWriter",
+    role="Writer",
+    goal="Create engaging content"
+)
+
+# Task with output_file - auto-saves result
+task = Task(
+    description="Write a short blog post about the benefits of AI assistants",
+    expected_output="A well-structured blog post in markdown format",
+    agent=writer,
+    output_file="blog_post.md",
+    create_directory=True
+)
+
+# Run
+agents = Agents(agents=[writer], tasks=[task])
+result = agents.start()
+
+print("✅ Task completed!")
+print("Output saved to: blog_post.md")
@@ -0,0 +1,41 @@
+"""
+Example 3: Save Agent Output Using Workflow output_file
+
+Workflow step output is automatically saved with variable substitution.
+"""
+
+from praisonaiagents import Workflow
+
+# Define workflow with output_file
+workflow_config = {
+    "metadata": {
+        "name": "content-generator",
+        "version": "1.0"
+    },
+    "variables": {
+        "output_dir": "generated",
+        "topic": "Python programming"
+    },
+    "agents": {
+        "writer": {
+            "role": "Content Writer",
+            "goal": "Create engaging content",
+            "llm": "gpt-4o-mini"
+        }
+    },
+    "steps": [
+        {
+            "agent": "writer",
+            "action": "Write a short tutorial about Python basics",
+            "expected_output": "A beginner-friendly tutorial",
+            "output_file": "{{output_dir}}/tutorial.md"
+        }
+    ]
+}
+
+# Run workflow
+workflow = Workflow(config=workflow_config)
+result = workflow.run()
+
+print("✅ Workflow completed!")
+print("Output saved to: generated/tutorial.md")
@@ -0,0 +1,27 @@
+"""
+Example 4: Save Agent Output Manually
+
+Capture the response and save it with full control.
+"""
+
+from praisonaiagents import Agent
+from pathlib import Path
+
+# Create agent
+agent = Agent(
+    name="StoryWriter",
+    instructions="You are a creative writer who writes short stories."
+)
+
+# Get response
+response = agent.start("Write a very short story about a robot learning to paint")
+
+# Save manually with error handling
+output_path = Path("stories/robot_story.txt")
+output_path.parent.mkdir(parents=True, exist_ok=True)
+
+try:
+    output_path.write_text(response)
+    print(f"✅ Saved to {output_path}")
+except IOError as e:
+    print(f"❌ Failed to save: {e}")
@@ -0,0 +1,49 @@
+"""
+Example: Auto-save agent output to file
+
+This example demonstrates how to automatically save agent responses to files.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.config import OutputConfig
+
+# Method 1: Simplest - just pass a file path string
+agent = Agent(
+    instructions="You are a helpful assistant",
+    output="output/response.txt"  # Just a string path!
+)
+
+# When you call start(), the response is automatically saved
+# result = agent.start("Write a short greeting")
+# Prints: ✅ Output saved to output/response.txt
+
+# Method 2: With template formatting using OutputConfig
+agent_with_template = Agent(
+    instructions="You are a blog writer",
+    output=OutputConfig(
+        output_file="output/blog_post.md",
+        template="""# {{title}}
+
+{{content}}
+
+---
+*Generated by AI*
+"""
+    )
+)
+
+# The agent will format its response according to the template
+# result = agent_with_template.start("Write about Python programming")
+
+# Method 3: Combine with other output settings
+agent_verbose = Agent(
+    instructions="You are a researcher",
+    output=OutputConfig(
+        verbose=True,           # Show rich output in terminal
+        output_file="output/research.md",  # Also save to file
+        template="## Research Summary\n\n{{content}}"
+    )
+)
+
+print("Examples ready! Uncomment agent.start() calls to run.")
+print("Output will be saved to the specified files automatically.")
@@ -0,0 +1,35 @@
+# Save Agent Output Examples
+
+Examples demonstrating different methods to save agent output to files.
+
+## Examples
+
+| File | Method | Description |
+|------|--------|-------------|
+| `01_write_file_tool.py` | write_file Tool | Agent decides when/what to save |
+| `02_task_output_file.py` | Task.output_file | Auto-save task result |
+| `03_workflow_output_file.py` | Workflow output_file | Save workflow step output |
+| `04_manual_save.py` | Manual | Full control over saving |
+
+## Setup
+
+```bash
+pip install praisonaiagents
+export OPENAI_API_KEY="your-key"
+```
+
+## Run Examples
+
+```bash
+python 01_write_file_tool.py
+python 02_task_output_file.py
+python 03_workflow_output_file.py
+python 04_manual_save.py
+```
+
+## Which Method to Use?
+
+- **write_file Tool**: When agent needs to decide what to save
+- **Task.output_file**: For task-based workflows with auto-save
+- **Workflow output_file**: For YAML workflows with variable substitution
+- **Manual**: When you need full control over the saving process
@@ -0,0 +1,156 @@
+"""
+Specialized Agents Example
+
+Demonstrates using specialized agent types (AudioAgent, VideoAgent, ImageAgent, OCRAgent)
+with the Agents class for multi-agent workflows.
+
+Usage:
+    python specialized_agents_example.py
+"""
+
+# Example 1: Simple TTS with AudioAgent
+def example_tts():
+    """Text-to-Speech example using AudioAgent."""
+    from praisonaiagents import AudioAgent
+    
+    agent = AudioAgent(llm="openai/tts-1")
+    agent.speech("Hello, welcome to PraisonAI!", output="hello.mp3")
+    print("Generated: hello.mp3")
+
+# Example 2: Simple STT with AudioAgent
+def example_stt():
+    """Speech-to-Text example using AudioAgent."""
+    from praisonaiagents import AudioAgent
+    
+    agent = AudioAgent(llm="openai/whisper-1")
+    text = agent.transcribe("hello.mp3")
+    print(f"Transcribed: {text}")
+
+# Example 3: Image generation with ImageAgent
+def example_image():
+    """Image generation example using ImageAgent."""
+    from praisonaiagents import ImageAgent
+    
+    agent = ImageAgent(llm="openai/dall-e-3")
+    result = agent.generate("A beautiful sunset over mountains")
+    print(f"Generated image: {result}")
+
+# Example 4: Multi-agent pipeline with mixed agent types via YAML
+def example_multi_agent_pipeline():
+    """
+    Multi-agent pipeline example using YAML workflow:
+    1. AudioAgent (STT) - Transcribe audio
+    2. Agent (Research) - Research the topic
+    3. ImageAgent - Generate image
+    
+    Note: Specialized agents (AudioAgent, VideoAgent, etc.) are best used
+    through YAML workflows or directly via their methods (speech, transcribe, etc.)
+    """
+    from praisonaiagents.workflows.yaml_parser import YAMLWorkflowParser
+    
+    # Define multi-agent pipeline in YAML
+    yaml_content = """
+name: Multi-Agent Pipeline
+process: sequential
+
+agents:
+  transcriber:
+    agent: AudioAgent
+    llm: openai/whisper-1
+    role: Transcriber
+    goal: Transcribe audio to text
+  
+  researcher:
+    role: Research Specialist
+    goal: Research topics and provide summaries
+    instructions: You research topics and provide concise summaries.
+  
+  artist:
+    agent: ImageAgent
+    llm: openai/dall-e-3
+    role: Visual Artist
+    goal: Create images based on research
+
+steps:
+  - agent: transcriber
+    action: transcribe
+    input: "{{audio_file}}"
+  
+  - agent: researcher
+    action: "Research the following topic and provide a summary: {{previous_output}}"
+  
+  - agent: artist
+    action: generate
+    prompt: "Create an image representing: {{previous_output}}"
+
+variables:
+  audio_file: input.mp3
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print("Multi-agent pipeline created successfully!")
+    print(f"Workflow: {workflow.name}")
+    print(f"Agents: {list(parser._agents.keys())}")
+    print(f"Agent types: {[a.__class__.__name__ for a in parser._agents.values()]}")
+    print(f"Steps: {len(workflow.steps)}")
+
+# Example 5: Using YAML workflow with specialized agents
+def example_yaml_workflow():
+    """Parse YAML workflow with specialized agent types."""
+    from praisonaiagents.workflows.yaml_parser import YAMLWorkflowParser
+    
+    yaml_content = """
+name: Media Pipeline
+process: sequential
+
+agents:
+  transcriber:
+    agent: AudioAgent
+    llm: openai/whisper-1
+    role: Transcriber
+    goal: Transcribe audio
+  
+  researcher:
+    role: Researcher
+    goal: Research topics
+  
+  artist:
+    agent: ImageAgent
+    llm: openai/dall-e-3
+    role: Artist
+    goal: Create images
+
+steps:
+  - agent: transcriber
+    action: transcribe
+  - agent: researcher
+    action: "Research: {{previous_output}}"
+  - agent: artist
+    action: generate
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print(f"Workflow: {workflow.name}")
+    print(f"Agents: {list(parser._agents.keys())}")
+    print(f"Agent types: {[a.__class__.__name__ for a in parser._agents.values()]}")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Specialized Agents Examples")
+    print("=" * 60)
+    
+    # Run the YAML workflow example (doesn't require API keys)
+    print("\n--- Example: YAML Workflow with Specialized Agents ---")
+    example_yaml_workflow()
+    
+    print("\n--- Example: Multi-Agent Pipeline ---")
+    example_multi_agent_pipeline()
+    
+    print("\n" + "=" * 60)
+    print("Examples completed!")
+    print("=" * 60)
@@ -0,0 +1,17 @@
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="gemini/veo-3.1-generate-preview")
+
+# Generate video
+video = agent.generate("A sunset timelapse", seconds="8", size="1920x1080")
+print(f"Started: {video.id}")
+
+# Wait and download
+completed = agent.wait_for_completion(video.id)
+if completed.status == "completed":
+    agent.download(video.id, "sunset.mp4")
+
+# List all videos
+videos = agent.list()
+
+# Models: openai/sora-2, gemini/veo-3.0-generate-preview, azure/sora-2
@@ -0,0 +1,5 @@
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="azure/sora-2")
+video = agent.generate("Mountain landscape")
+print(video.id)
@@ -0,0 +1,9 @@
+# Video Generation with OpenAI Sora
+# Requires: export OPENAI_API_KEY=your-key
+# Note: Sora requires organization verification
+
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="openai/sora-2")
+video = agent.generate("A cat playing with yarn")
+print(f"Video ID: {video.id}")
@@ -0,0 +1,5 @@
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="gemini/veo-3.1-generate-preview")
+video = agent.generate("Ocean waves at sunset")
+print(video.id)
@@ -0,0 +1,5 @@
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="openai/sora-2")
+video = agent.generate("A cat playing with yarn")
+print(video.id)
@@ -0,0 +1,5 @@
+from praisonaiagents import VideoAgent
+
+agent = VideoAgent(llm="runwayml/gen4_turbo")
+video = agent.generate("Animate this forest", size="1280x720", seconds="10")
+print(video.id)
@@ -0,0 +1,93 @@
+"""
+Recipe Output Modes Example
+
+Demonstrates how to use different output modes when running recipes.
+Output modes control the verbosity and format of execution feedback.
+
+Available modes:
+- silent: No output (default, best performance)
+- status: Shows tool calls inline
+- trace: Timestamped execution trace
+- verbose: Full interactive output with panels
+- debug: Trace + metrics (tokens, cost, model)
+- json: Machine-readable JSONL events
+
+CLI Usage:
+    praisonai recipe run my-recipe --output status
+    praisonai recipe run my-recipe --output trace
+    praisonai recipe run my-recipe -v  # alias for --output verbose
+"""
+
+from praisonai.recipe import run
+
+
+def example_silent_mode():
+    """Silent mode - no output, best performance."""
+    print("=== Silent Mode (default) ===")
+    result = run(
+        "my-recipe",
+        input={"query": "Hello"},
+        options={"output": "silent"}
+    )
+    print(f"Result: {result}")
+
+
+def example_status_mode():
+    """Status mode - shows tool calls inline."""
+    print("\n=== Status Mode ===")
+    print("Shows: ▸ tool → result ✓")
+    result = run(
+        "my-recipe",
+        input={"query": "Hello"},
+        options={"output": "status"}
+    )
+    print(f"Result: {result}")
+
+
+def example_trace_mode():
+    """Trace mode - timestamped execution trace."""
+    print("\n=== Trace Mode ===")
+    print("Shows: [HH:MM:SS] ▸ tool → result [0.2s] ✓")
+    result = run(
+        "my-recipe",
+        input={"query": "Hello"},
+        options={"output": "trace"}
+    )
+    print(f"Result: {result}")
+
+
+def example_verbose_mode():
+    """Verbose mode - full interactive output with panels."""
+    print("\n=== Verbose Mode ===")
+    result = run(
+        "my-recipe",
+        input={"query": "Hello"},
+        options={"output": "verbose"}
+    )
+    print(f"Result: {result}")
+
+
+def example_backward_compat():
+    """Backward compatibility - verbose flag maps to output='verbose'."""
+    print("\n=== Backward Compatibility ===")
+    print("Using verbose=True (deprecated, use output='verbose' instead)")
+    result = run(
+        "my-recipe",
+        input={"query": "Hello"},
+        options={"verbose": True}  # Maps to output="verbose"
+    )
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    print(__doc__)
+    print("Note: These examples require a recipe named 'my-recipe' to be available.")
+    print("Create one with: praisonai recipe init my-recipe")
+    print()
+    
+    # Uncomment to run examples:
+    # example_silent_mode()
+    # example_status_mode()
+    # example_trace_mode()
+    # example_verbose_mode()
+    # example_backward_compat()
@@ -0,0 +1,274 @@
+"""
+Storage Backends Example for PraisonAI Agents.
+
+Demonstrates how to use different storage backends (File, SQLite, Redis)
+for agent data persistence across all supported components.
+
+Supported Backends:
+- FileBackend: JSON file-based storage (default, zero dependencies)
+- SQLiteBackend: SQLite database storage (zero dependencies)
+- RedisBackend: Redis-based storage (requires redis package)
+
+Supported Components:
+- BaseJSONStore: Generic JSON storage
+- TrainingStorage: Agent training data
+- SessionManager: CLI session state
+- RunHistory: Recipe run history
+- MCPToolIndex: MCP tool schemas
+
+Usage:
+    python storage_backends_example.py
+"""
+
+from praisonaiagents.storage import (
+    FileBackend,
+    SQLiteBackend,
+    BaseJSONStore,
+    get_backend,
+)
+
+
+def example_file_backend():
+    """Example: Using FileBackend for JSON file storage."""
+    print("\n=== FileBackend Example ===")
+    
+    # Create file backend
+    backend = FileBackend(storage_dir="/tmp/praison_example")
+    
+    # Save data
+    backend.save("agent_state", {
+        "agent_name": "Research Assistant",
+        "messages": ["Hello", "How can I help?"],
+        "context": {"topic": "AI"}
+    })
+    
+    # Load data
+    data = backend.load("agent_state")
+    print(f"Loaded: {data}")
+    
+    # List keys
+    keys = backend.list_keys()
+    print(f"Keys: {keys}")
+    
+    # Check existence
+    print(f"Exists: {backend.exists('agent_state')}")
+    
+    # Clean up
+    backend.delete("agent_state")
+    print("Deleted agent_state")
+
+
+def example_sqlite_backend():
+    """Example: Using SQLiteBackend for database storage."""
+    print("\n=== SQLiteBackend Example ===")
+    
+    # Create SQLite backend (single file, better for concurrent access)
+    backend = SQLiteBackend(db_path="/tmp/praison_example.db")
+    
+    # Save multiple sessions
+    for i in range(3):
+        backend.save(f"session_{i}", {
+            "session_id": f"sess-{i}",
+            "messages": [f"Message {j}" for j in range(i + 1)],
+            "timestamp": "2024-01-01T00:00:00Z"
+        })
+    
+    # List all sessions
+    keys = backend.list_keys(prefix="session_")
+    print(f"Sessions: {keys}")
+    
+    # Load specific session
+    session = backend.load("session_1")
+    print(f"Session 1: {session}")
+    
+    # Clean up
+    backend.clear()
+    backend.close()
+    print("Cleaned up SQLite backend")
+
+
+def example_backend_factory():
+    """Example: Using get_backend factory function."""
+    print("\n=== Backend Factory Example ===")
+    
+    # Easy switching between backends
+    backend_type = "sqlite"  # Change to "file" or "redis" as needed
+    
+    if backend_type == "file":
+        backend = get_backend("file", storage_dir="/tmp/praison_factory")
+    elif backend_type == "sqlite":
+        backend = get_backend("sqlite", db_path="/tmp/praison_factory.db")
+    # elif backend_type == "redis":
+    #     backend = get_backend("redis", url="redis://localhost:6379")
+    
+    # Use backend
+    backend.save("config", {"model": "gpt-4", "temperature": 0.7})
+    config = backend.load("config")
+    print(f"Config: {config}")
+    
+    # Clean up
+    backend.delete("config")
+
+
+def example_with_base_json_store():
+    """Example: Using BaseJSONStore with custom backend."""
+    print("\n=== BaseJSONStore with Backend Example ===")
+    
+    # Create a custom store with SQLite backend
+    backend = SQLiteBackend(db_path="/tmp/praison_store.db")
+    
+    store = BaseJSONStore(
+        storage_path="/tmp/my_store.json",  # Used as key name
+        backend=backend,
+    )
+    
+    # Save and load data
+    store.save({"items": [1, 2, 3], "count": 3})
+    data = store.load()
+    print(f"Store data: {data}")
+    
+    # Clean up
+    store.delete()
+    backend.close()
+
+
+def example_training_storage_with_backend():
+    """Example: Using TrainingStorage with SQLite backend."""
+    print("\n=== TrainingStorage with Backend Example ===")
+    
+    try:
+        from praisonai.train.agents.storage import TrainingStorage
+        
+        # Create SQLite backend for training data
+        backend = SQLiteBackend(db_path="/tmp/training.db")
+        
+        # Use with TrainingStorage
+        storage = TrainingStorage(
+            session_id="train-example-001",
+            backend=backend,
+        )
+        
+        print(f"Training storage created with session: {storage.session_id}")
+        print("Training data will be stored in SQLite instead of JSON files")
+        
+        backend.close()
+    except ImportError:
+        print("praisonai package not installed, skipping training example")
+
+
+def example_session_manager_with_backend():
+    """Example: Using SessionManager with SQLite backend."""
+    print("\n=== SessionManager with Backend Example ===")
+    
+    try:
+        from praisonai.cli.state.sessions import SessionManager
+        
+        # Create SQLite backend for sessions
+        backend = SQLiteBackend(db_path="/tmp/sessions.db")
+        
+        # Use with SessionManager
+        manager = SessionManager(backend=backend)
+        sessions = manager.list(limit=10)
+        
+        print(f"SessionManager created with SQLite backend, {len(sessions)} sessions")
+        print("Sessions will be stored in database instead of files")
+        
+        backend.close()
+    except ImportError:
+        print("praisonai package not installed, skipping session example")
+
+
+def example_run_history_with_backend():
+    """Example: Using RunHistory with SQLite backend."""
+    print("\n=== RunHistory with Backend Example ===")
+    
+    try:
+        from praisonai.recipe.history import RunHistory
+        
+        # Create SQLite backend for run history
+        backend = SQLiteBackend(db_path="/tmp/runs.db")
+        
+        # Use with RunHistory
+        history = RunHistory(backend=backend)
+        runs = history.list()
+        
+        print(f"RunHistory created with SQLite backend, {len(runs)} runs")
+        print("Recipe runs will be stored in database instead of files")
+        
+        backend.close()
+    except ImportError:
+        print("praisonai package not installed, skipping run history example")
+
+
+def example_mcp_tool_index_with_backend():
+    """Example: Using MCPToolIndex with SQLite backend."""
+    print("\n=== MCPToolIndex with Backend Example ===")
+    
+    try:
+        from praisonai.mcp_server.tool_index import MCPToolIndex
+        
+        # Create SQLite backend for MCP tool index
+        backend = SQLiteBackend(db_path="/tmp/mcp.db")
+        
+        # Use with MCPToolIndex
+        index = MCPToolIndex(backend=backend)
+        servers = index.list_servers()
+        
+        print(f"MCPToolIndex created with SQLite backend, {len(servers)} servers")
+        print("MCP tool schemas will be stored in database instead of files")
+        
+        backend.close()
+    except ImportError:
+        print("praisonai package not installed, skipping MCP example")
+
+
+def example_redis_backend():
+    """Example: Using RedisBackend for high-speed caching."""
+    print("\n=== RedisBackend Example ===")
+    
+    try:
+        from praisonaiagents.storage import RedisBackend
+        
+        # Create Redis backend with TTL
+        backend = RedisBackend(
+            url="redis://localhost:6379",
+            prefix="example:",
+            ttl=3600  # 1 hour TTL
+        )
+        
+        # CRUD operations
+        backend.save("test_key", {"data": "value", "count": 42})
+        data = backend.load("test_key")
+        print(f"Loaded from Redis: {data}")
+        
+        # List keys
+        keys = backend.list_keys()
+        print(f"Keys: {keys}")
+        
+        # Clean up
+        backend.delete("test_key")
+        backend.close()
+        print("RedisBackend example completed")
+        
+    except ImportError:
+        print("redis package not installed: pip install redis")
+    except Exception as e:
+        print(f"Redis not available: {e}")
+
+
+if __name__ == "__main__":
+    print("PraisonAI Storage Backends Examples")
+    print("=" * 50)
+    
+    example_file_backend()
+    example_sqlite_backend()
+    example_backend_factory()
+    example_with_base_json_store()
+    example_training_storage_with_backend()
+    example_session_manager_with_backend()
+    example_run_history_with_backend()
+    example_mcp_tool_index_with_backend()
+    example_redis_backend()
+    
+    print("\n" + "=" * 50)
+    print("All examples completed!")
@@ -0,0 +1,211 @@
+"""
+Custom Trace Sink Example
+
+Demonstrates how to create custom trace sinks for PraisonAI agents.
+The trace system uses a protocol-driven design - implement 3 methods
+and your sink works with any agent.
+
+Protocol: ContextTraceSinkProtocol (AGENTS.md naming: XProtocol for interfaces)
+- emit(event) - Receive a trace event
+- flush() - Flush any buffered events  
+- close() - Release resources
+
+Examples:
+1. HTTP Sink - Send events to a remote server
+2. SQLite Sink - Store events in a database
+3. Console Sink - Pretty-print events to terminal
+"""
+
+from praisonaiagents import (
+    Agent,
+    ContextTraceEmitter,
+    ContextTraceSinkProtocol,  # Protocol for type hints (optional)
+    trace_context,
+)
+
+
+# =============================================================================
+# Example 1: HTTP Sink - Send events to a remote server
+# =============================================================================
+
+class HTTPSink:
+    """Send trace events to a remote HTTP endpoint."""
+    
+    def __init__(self, url: str, batch_size: int = 10):
+        self.url = url
+        self.batch_size = batch_size
+        self.buffer = []
+    
+    def emit(self, event):
+        """Buffer events and send in batches."""
+        self.buffer.append(event.to_dict())
+        if len(self.buffer) >= self.batch_size:
+            self.flush()
+    
+    def flush(self):
+        """Send buffered events to server."""
+        if self.buffer:
+            # In production, use: requests.post(self.url, json=self.buffer)
+            print(f"[HTTP] Would send {len(self.buffer)} events to {self.url}")
+            self.buffer.clear()
+    
+    def close(self):
+        """Flush remaining events."""
+        self.flush()
+
+
+# =============================================================================
+# Example 2: SQLite Sink - Store events in a database
+# =============================================================================
+
+class SQLiteSink:
+    """Store trace events in SQLite database."""
+    
+    def __init__(self, db_path: str = "traces.db"):
+        import sqlite3
+        self.conn = sqlite3.connect(db_path)
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS events (
+                id INTEGER PRIMARY KEY,
+                session_id TEXT,
+                event_type TEXT,
+                agent_name TEXT,
+                timestamp REAL,
+                data TEXT
+            )
+        """)
+        self.conn.commit()
+    
+    def emit(self, event):
+        """Insert event into database."""
+        import json
+        self.conn.execute(
+            "INSERT INTO events (session_id, event_type, agent_name, timestamp, data) VALUES (?, ?, ?, ?, ?)",
+            (event.session_id, event.event_type.value, event.agent_name, event.timestamp, json.dumps(event.data))
+        )
+    
+    def flush(self):
+        """Commit pending transactions."""
+        self.conn.commit()
+    
+    def close(self):
+        """Commit and close connection."""
+        self.flush()
+        self.conn.close()
+
+
+# =============================================================================
+# Example 3: Console Sink - Pretty-print events
+# =============================================================================
+
+class ConsoleSink:
+    """Print trace events to console with colors."""
+    
+    COLORS = {
+        "session_start": "\033[92m",  # Green
+        "session_end": "\033[92m",
+        "agent_start": "\033[94m",    # Blue
+        "agent_end": "\033[94m",
+        "tool_call_start": "\033[93m", # Yellow
+        "tool_call_end": "\033[93m",
+        "llm_request": "\033[95m",    # Magenta
+        "llm_response": "\033[95m",
+    }
+    RESET = "\033[0m"
+    
+    def emit(self, event):
+        """Print event with color coding."""
+        color = self.COLORS.get(event.event_type.value, "")
+        print(f"{color}[{event.event_type.value}]{self.RESET} {event.agent_name or 'session'}")
+    
+    def flush(self):
+        pass
+    
+    def close(self):
+        pass
+
+
+# =============================================================================
+# Usage Examples
+# =============================================================================
+
+def example_http_sink():
+    """Example: Send events to HTTP endpoint."""
+    print("\n=== HTTP Sink Example ===")
+    
+    sink = HTTPSink(url="https://my-telemetry.example.com/events")
+    emitter = ContextTraceEmitter(sink=sink, session_id="http-demo", enabled=True)
+    
+    with trace_context(emitter):
+        # Events automatically go to HTTPSink
+        emitter.session_start({"demo": True})
+        emitter.agent_start("demo_agent", {"role": "demo"})
+        emitter.agent_end("demo_agent")
+        emitter.session_end()
+    
+    print("HTTP sink example complete")
+
+
+def example_console_sink():
+    """Example: Pretty-print events to console."""
+    print("\n=== Console Sink Example ===")
+    
+    sink = ConsoleSink()
+    emitter = ContextTraceEmitter(sink=sink, session_id="console-demo", enabled=True)
+    
+    with trace_context(emitter):
+        emitter.session_start({})
+        emitter.agent_start("researcher", {"role": "Research Assistant"})
+        emitter.tool_call_start("researcher", "web_search", {"query": "AI trends"})
+        emitter.tool_call_end("researcher", "web_search", "Found 10 results", 150.0)
+        emitter.llm_request("researcher", "gpt-4o-mini", [{"role": "user", "content": "test"}])
+        emitter.llm_response("researcher", 100, 500, "stop", "Response text")
+        emitter.agent_end("researcher")
+        emitter.session_end()
+    
+    print("Console sink example complete")
+
+
+def example_with_real_agent():
+    """Example: Use custom sink with a real agent.
+    
+    Note: Requires OPENAI_API_KEY environment variable.
+    """
+    import os
+    print("\n=== Real Agent with Custom Sink ===")
+    
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Skipping real agent test (no OPENAI_API_KEY)")
+        return
+    
+    # Create custom sink
+    sink = ConsoleSink()
+    emitter = ContextTraceEmitter(sink=sink, session_id="real-agent-demo", enabled=True)
+    
+    # Use trace_context to capture all agent events
+    with trace_context(emitter):
+        agent = Agent(
+            name="demo_agent",
+            instructions="You are a helpful assistant. Be brief.",
+            llm="gpt-4o-mini",
+        )
+        
+        # This chat will emit events to ConsoleSink
+        result = agent.chat("Say hello in 5 words or less")
+        print(f"\nAgent response: {result}")
+    
+    print("Real agent example complete")
+
+
+if __name__ == "__main__":
+    # Run examples
+    example_http_sink()
+    example_console_sink()
+    example_with_real_agent()
+    
+    print("\n✅ All examples complete!")
+    print("\nKey points:")
+    print("1. Implement emit(), flush(), close() - that's it!")
+    print("2. Use trace_context() for automatic cleanup")
+    print("3. Zero overhead when tracing is disabled")
@@ -0,0 +1,106 @@
+"""
+Workflow Output Modes Example
+
+Demonstrates how to use different output modes with Workflow.
+Workflows use the same output presets as Agent for consistency (DRY approach).
+
+Available presets:
+- silent: No output (default, fastest)
+- status: Tool calls + final output inline
+- trace: Timestamped execution trace
+- verbose: Full Rich panels
+- debug: Trace + metrics
+- json: JSONL output for piping
+"""
+
+from praisonaiagents import Agent, Workflow
+
+
+def main():
+    # Create a simple agent
+    researcher = Agent(
+        name="Researcher",
+        role="Research Analyst",
+        goal="Research and provide information",
+        instructions="You are a research analyst. Provide concise, factual information."
+    )
+    
+    # Example 1: Status output (recommended for CLI)
+    print("=" * 50)
+    print("Example 1: Status Output (output='status')")
+    print("=" * 50)
+    
+    workflow_status = Workflow(
+        name="Status Example",
+        steps=[researcher],
+        output="status"  # Shows: ▸ tool → result ✓
+    )
+    # result = workflow_status.start("What is Python?")
+    print("Workflow created with output='status'")
+    print(f"  actions_trace: {getattr(workflow_status._output_config, 'actions_trace', False)}")
+    print()
+    
+    # Example 2: Trace output (with timestamps)
+    print("=" * 50)
+    print("Example 2: Trace Output (output='trace')")
+    print("=" * 50)
+    
+    workflow_trace = Workflow(
+        name="Trace Example",
+        steps=[researcher],
+        output="trace"  # Shows: [HH:MM:SS] ▸ tool → result [0.2s] ✓
+    )
+    print("Workflow created with output='trace'")
+    print(f"  status_trace: {getattr(workflow_trace._output_config, 'status_trace', False)}")
+    print()
+    
+    # Example 3: Verbose output (Rich panels)
+    print("=" * 50)
+    print("Example 3: Verbose Output (output='verbose')")
+    print("=" * 50)
+    
+    workflow_verbose = Workflow(
+        name="Verbose Example",
+        steps=[researcher],
+        output="verbose"  # Full interactive display
+    )
+    print("Workflow created with output='verbose'")
+    print(f"  verbose: {getattr(workflow_verbose._output_config, 'verbose', False)}")
+    print()
+    
+    # Example 4: Silent output (default, fastest)
+    print("=" * 50)
+    print("Example 4: Silent Output (output='silent' or default)")
+    print("=" * 50)
+    
+    workflow_silent = Workflow(
+        name="Silent Example",
+        steps=[researcher],
+        output="silent"  # No output - zero overhead
+    )
+    print("Workflow created with output='silent'")
+    print(f"  verbose: {getattr(workflow_silent._output_config, 'verbose', False)}")
+    print(f"  actions_trace: {getattr(workflow_silent._output_config, 'actions_trace', False)}")
+    print()
+    
+    # Example 5: JSON output (for piping)
+    print("=" * 50)
+    print("Example 5: JSON Output (output='json')")
+    print("=" * 50)
+    
+    workflow_json = Workflow(
+        name="JSON Example",
+        steps=[researcher],
+        output="json"  # JSONL output for scripting
+    )
+    print("Workflow created with output='json'")
+    print(f"  json_output: {getattr(workflow_json._output_config, 'json_output', False)}")
+    print()
+    
+    print("=" * 50)
+    print("All examples completed successfully!")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,62 @@
+# Nested Workflow Patterns Example
+# Demonstrates: nested loops, if conditions, and combined patterns
+
+agents:
+  data_processor:
+    role: Data Processor
+    goal: Process individual data items
+    backstory: Expert at transforming and validating data
+    
+  quality_checker:
+    role: Quality Checker  
+    goal: Verify data quality meets standards
+    backstory: Meticulous quality assurance specialist
+    
+  approver:
+    role: Approver
+    goal: Approve high-quality items
+    backstory: Senior reviewer with approval authority
+    
+  rejector:
+    role: Rejector
+    goal: Handle rejected items
+    backstory: Specialist in rejection workflows
+
+workflow:
+  name: Nested Data Processing Pipeline
+  
+  variables:
+    batches:
+      - name: batch_1
+        items: ["item_a", "item_b"]
+      - name: batch_2
+        items: ["item_c", "item_d"]
+    quality_threshold: 80
+  
+  steps:
+    # Step 1: Process each batch with nested item loop
+    - loop:
+        over: batches
+        var_name: batch
+        steps:
+          # Nested loop: process each item in the batch
+          - loop:
+              over: "{{batch.items}}"
+              var_name: item
+              steps:
+                - agent: data_processor
+                  action: "Process item {{item}} from {{batch.name}}"
+    
+    # Step 2: Quality check with conditional branching
+    - agent: quality_checker
+      action: "Check quality of all processed items and return a score"
+    
+    # Step 3: Conditional approval based on quality score
+    - if:
+        condition: "{{quality_score}} >= {{quality_threshold}}"
+        then:
+          - agent: approver
+            action: "Approve the batch - quality score meets threshold"
+        else:
+          - agent: rejector
+            action: "Reject the batch - quality score below threshold"
@@ -0,0 +1,280 @@
+# Performance Benchmark CI
+# Runs import time and instantiation benchmarks on push/PR
+# Fails if import time exceeds 200ms threshold
+
+name: Performance Benchmark
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'praisonaiagents/**'
+      - 'benchmarks/**'
+      - '.github/workflows/benchmark.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'praisonaiagents/**'
+      - 'benchmarks/**'
+      - '.github/workflows/benchmark.yml'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install package
+        run: |
+          pip install -e .
+          pip install pytest
+      
+      - name: Measure Import Time
+        id: import_time
+        run: |
+          # Measure import time (full Agent import)
+          IMPORT_TIME=$(python -c "
+          import time
+          import sys
+          
+          # Clear any cached modules
+          for key in list(sys.modules.keys()):
+              if 'praisonai' in key:
+                  del sys.modules[key]
+          
+          start = time.perf_counter()
+          from praisonaiagents import Agent
+          elapsed = (time.perf_counter() - start) * 1000
+          print(f'{elapsed:.1f}')
+          ")
+          
+          echo "import_time=$IMPORT_TIME" >> $GITHUB_OUTPUT
+          echo "Import time: ${IMPORT_TIME}ms"
+      
+      - name: Check Import Time Threshold
+        run: |
+          IMPORT_TIME=${{ steps.import_time.outputs.import_time }}
+          THRESHOLD=200
+          
+          echo "Import time: ${IMPORT_TIME}ms"
+          echo "Threshold: ${THRESHOLD}ms"
+          
+          # Compare using bc for floating point
+          if (( $(echo "$IMPORT_TIME > $THRESHOLD" | bc -l) )); then
+            echo "❌ FAIL: Import time ${IMPORT_TIME}ms exceeds threshold ${THRESHOLD}ms"
+            exit 1
+          else
+            echo "✅ PASS: Import time ${IMPORT_TIME}ms is within threshold ${THRESHOLD}ms"
+          fi
+      
+      - name: Measure Instantiation Time
+        run: |
+          python -c "
+          import time
+          from praisonaiagents import Agent
+          
+          # Warmup
+          for _ in range(5):
+              Agent(name='Test', output='silent')
+          
+          # Measure
+          times = []
+          for _ in range(50):
+              start = time.perf_counter()
+              Agent(name='Test', output='silent')
+              times.append((time.perf_counter() - start) * 1e6)
+          
+          avg = sum(times) / len(times)
+          min_t = min(times)
+          max_t = max(times)
+          
+          print(f'Instantiation time:')
+          print(f'  Average: {avg:.2f}μs')
+          print(f'  Min: {min_t:.2f}μs')
+          print(f'  Max: {max_t:.2f}μs')
+          "
+      
+      - name: Verify Lazy Imports
+        run: |
+          python -c "
+          import sys
+          
+          # Clear any cached modules
+          for key in list(sys.modules.keys()):
+              if 'praisonai' in key or 'litellm' in key:
+                  del sys.modules[key]
+          
+          # Import package
+          import praisonaiagents
+          
+          # Check heavy deps are NOT loaded
+          heavy_deps = ['litellm', 'chromadb', 'mem0', 'rich']
+          loaded = []
+          for dep in heavy_deps:
+              if dep in sys.modules:
+                  loaded.append(dep)
+          
+          if loaded:
+              print(f'⚠️ WARNING: Heavy deps loaded eagerly: {loaded}')
+              # Don't fail, just warn - some deps may be needed
+          else:
+              print('✅ All heavy deps are lazy loaded')
+          "
+      
+      - name: Run Quick Benchmark (if available)
+        continue-on-error: true
+        run: |
+          if [ -f "benchmarks/quick_benchmark.py" ]; then
+            python benchmarks/quick_benchmark.py --fast || true
+          else
+            echo "Quick benchmark not found, skipping"
+          fi
+
+  # Real API benchmark - only runs when API keys are available
+  # Triggered manually or on main branch with secrets
+  real-api-benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name == 'workflow_dispatch' || (github.ref == 'refs/heads/main' && github.event_name == 'push')
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install package
+        run: |
+          pip install -e .
+          pip install pytest
+      
+      - name: Check API Key Availability
+        id: check_keys
+        run: |
+          if [ -n "${{ secrets.OPENAI_API_KEY }}" ]; then
+            echo "has_openai=true" >> $GITHUB_OUTPUT
+            echo "✅ OpenAI API key available"
+          else
+            echo "has_openai=false" >> $GITHUB_OUTPUT
+            echo "⚠️ OpenAI API key not available, skipping real API tests"
+          fi
+      
+      - name: Run Real API Benchmark
+        if: steps.check_keys.outputs.has_openai == 'true'
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          python -c "
+          import time
+          import os
+          
+          # Verify API key is set
+          if not os.environ.get('OPENAI_API_KEY'):
+              print('❌ OPENAI_API_KEY not set')
+              exit(1)
+          
+          from praisonaiagents import Agent
+          
+          # Create a simple agent
+          agent = Agent(
+              name='BenchmarkAgent',
+              instructions='You are a helpful assistant. Be concise.',
+              llm='gpt-4o-mini',
+              output='silent'
+          )
+          
+          # Warmup run
+          print('Running warmup...')
+          agent.chat('Say hello in one word')
+          
+          # Benchmark runs
+          print('Running benchmark (3 iterations)...')
+          times = []
+          for i in range(3):
+              start = time.perf_counter()
+              response = agent.chat('What is 2+2? Answer with just the number.')
+              elapsed = time.perf_counter() - start
+              times.append(elapsed)
+              print(f'  Run {i+1}: {elapsed:.2f}s')
+          
+          avg = sum(times) / len(times)
+          print(f'')
+          print(f'Real API Benchmark Results:')
+          print(f'  Average response time: {avg:.2f}s')
+          print(f'  Min: {min(times):.2f}s')
+          print(f'  Max: {max(times):.2f}s')
+          
+          # Verify response quality
+          if '4' in response:
+              print('✅ Response quality check passed')
+          else:
+              print(f'⚠️ Unexpected response: {response}')
+          "
+      
+      - name: Run Multi-Agent Benchmark
+        if: steps.check_keys.outputs.has_openai == 'true'
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          python -c "
+          import time
+          import os
+          
+          from praisonaiagents import Agent, Agents, Task
+          
+          # Create agents
+          researcher = Agent(
+              name='Researcher',
+              instructions='You research topics. Be brief.',
+              llm='gpt-4o-mini',
+              output='silent'
+          )
+          
+          writer = Agent(
+              name='Writer', 
+              instructions='You write summaries. Be brief.',
+              llm='gpt-4o-mini',
+              output='silent'
+          )
+          
+          # Create tasks
+          task1 = Task(
+              description='List 2 facts about Python programming',
+              agent=researcher,
+              expected_output='2 brief facts'
+          )
+          
+          task2 = Task(
+              description='Summarize the facts in one sentence',
+              agent=writer,
+              expected_output='One sentence summary'
+          )
+          
+          # Run workflow
+          print('Running multi-agent workflow...')
+          start = time.perf_counter()
+          
+          agents = Agents(agents=[researcher, writer], tasks=[task1, task2])
+          result = agents.start()
+          
+          elapsed = time.perf_counter() - start
+          
+          print(f'')
+          print(f'Multi-Agent Benchmark Results:')
+          print(f'  Total workflow time: {elapsed:.2f}s')
+          print(f'  Agents: 2')
+          print(f'  Tasks: 2')
+          print('✅ Multi-agent workflow completed successfully')
+          "
@@ -11,7 +11,8 @@ Shows how to monitor agent performance when using external tools.
 """

 from praisonaiagents import Agent
-from praisonaiagents.tools import duckduckgo, wikipedia_tools
+from praisonaiagents import duckduckgo
+from praisonai_tools import wikipedia_tools
 from praisonaiagents.telemetry import (
    monitor_function, track_api_call, get_api_stats,
    get_slowest_functions, performance_monitor
@@ -0,0 +1,635 @@
+# AGENTS.md - PraisonAI SDK Comprehensive Guide
+
+> **For AI Agents and Developers**: This document provides the complete context needed to work with the PraisonAI ecosystem, including design principles, architecture, repository structure, and implementation guidelines.
+
+---
+
+## 1. What is PraisonAI?
+
+PraisonAI is a **high-performance, agentic AI framework** designed for building production-ready AI agents and multi-agent workflows.
+
+### Core Philosophy
+
+```
+Simpler than competitors • More extensible • Faster • Agent-centric
+```
+
+| Principle | Description |
+|-----------|-------------|
+| **Agent-Centric** | Every design decision centers on Agents, workflows, sessions, tools, and memory |
+| **Protocol-Driven Core** | Core SDK is lightweight with protocols/hooks/adapters only |
+| **Minimal API** | Fewer parameters, sensible defaults, explicit overrides |
+| **Performance-First** | Lazy loading, optional dependencies, no hot-path regressions |
+| **Production-Ready** | Safe by default, multi-agent safe, async-safe |
+Powerful, lightweight, highly reliable and robust
+Easy and developer frienldy for non developers
+Easy and user friendly
+---
+
+## 2. Repository Structure
+
+### 2.1 Canonical Paths
+
+```
+/Users/praison/praisonai-package/
+├── src/
+│   ├── praisonai-agents/          # Core SDK (praisonaiagents)
+│   │   ├── praisonaiagents/       # Python package
+│   │   ├── tests/                 # Unit & integration tests
+│   │   ├── examples/              # Package-level examples
+│   │   └── pyproject.toml         # Package config
+│   │
+│   ├── praisonai/                 # Wrapper (praisonai)
+│   │   ├── praisonai/             # CLI, integrations, heavy impls
+│   │   └── pyproject.toml
+│   │
+│   └── praisonai-ts/              # TypeScript SDK
+│       └── src/
+│
+├── examples/                      # Main examples directory
+│   ├── python/                # Python examples (primary)
+│   ├── yaml/                  # YAML configuration examples
+│   ├── js/                    # JavaScript/TypeScript examples
+│   └── cookbooks/             # End-to-end recipes
+│
+/Users/praison/PraisonAI-tools/    # External tools/plugins
+/Users/praison/PraisonAIDocs/      # Documentation (Mintlify)
+    └── docs/
+        ├── agents/
+        ├── api/
+        ├── capabilities/
+        ├── cli/
+        ├── concepts/
+        ├── features/
+        ├── guides/
+        ├── knowledge/
+        ├── memory/
+        ├── models/
+        ├── observability/
+        ├── rag/
+        ├── sdk/
+        ├── tools/
+        ├── tutorials/
+        └── ... (49+ subdirectories)
+```
+
+### 2.2 Package Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      praisonai (Wrapper)                        │
+│  CLI • Integrations • Heavy Implementations • Optional Deps     │
+├─────────────────────────────────────────────────────────────────┤
+│                    praisonaiagents (Core SDK)                   │
+│  Protocols • Hooks • Adapters • Base Classes • Decorators       │
+├─────────────────────────────────────────────────────────────────┤
+│                   praisonai-tools (External)                    │
+│  Optional Tools • Plugins • Community Extensions                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Core SDK Architecture (praisonaiagents)
+
+### 3.1 Key Modules
+
+| Module | Size | Purpose |
+|--------|------|---------|
+| `agent/` | 1.4M | Agent class, protocols, handoff, autonomy |
+| `memory/` | 984K | Memory protocols, adapters, file memory |
+| `context/` | 960K | Context management, artifacts, fast context |
+| `tools/` | 732K | Tool SDK, decorators, registry, protocols |
+| `llm/` | 620K | LLM client, model router |
+| `workflows/` | 456K | Workflow engine, patterns (Route, Parallel, Loop) |
+| `knowledge/` | 436K | Knowledge/RAG protocols, vector stores |
+| `hooks/` | 260K | Hook system, middleware, events |
+| `eval/` | 240K | Evaluation framework |
+| `rag/` | 264K | RAG protocols, retriever, reranker |
+| `plugins/` | 56K | Plugin manager, registry |
+| `policy/` | 64K | Policy engine |
+| `bus/` | 48K | Event bus |
+| `streaming/` | 56K | Streaming events, callbacks |
+| `trace/` | 152K | Trace protocols, context events |
+
+### 3.2 Protocol-First Design
+
+Core SDK uses `typing.Protocol` for all extension points:
+
+```
+Pattern: Each major module has a protocols.py file
+
+- Protocols define WHAT (interface contract)
+- Adapters implement HOW (concrete implementation)
+- Naming: XProtocol for interfaces, XAdapter for implementations
+- Users can implement any protocol for custom behavior
+```
+
+**Discovery:** Find all protocols dynamically:
+```bash
+grep -r "class.*Protocol" praisonaiagents/ --include="*.py"
+```
+
+**Key principle:** When adding new extensibility, create a Protocol first, then implement adapters.
+
+### 3.3 Core Dependencies
+
+```toml
+# Required (always loaded) - pyproject.toml
+dependencies = [
+    "pydantic>=2.10.0",    # Type validation
+    "rich",                # Terminal UI
+    "openai>=2.0.0",       # OpenAI client
+    "posthog>=3.0.0",      # Telemetry
+    "aiohttp>=3.8.0"       # Async HTTP
+]
+
+# Optional (lazy loaded)
+[project.optional-dependencies]
+memory = ["chromadb>=1.0.0", "litellm>=1.81.0"]
+knowledge = ["mem0ai>=0.1.0", "chromadb>=1.0.0", "markitdown[all]>=0.1.0"]
+mcp = ["mcp>=1.20.0", "fastapi>=0.115.0", "uvicorn>=0.34.0"]
+llm = ["litellm>=1.81.0"]
+api = ["fastapi>=0.115.0", "uvicorn>=0.34.0"]
+auth = ["PyJWT>=2.8.0", "passlib[bcrypt]>=1.7.4"]
+mongodb = ["pymongo>=4.6.3", "motor>=3.4.0"]
+```
+
+---
+
+## 4. Core Engineering Principles
+
+### 4.1 Protocol-Driven Core (MUST)
+
+```
+Core SDK (praisonaiagents)          Wrapper (praisonai)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━         ━━━━━━━━━━━━━━━━━━━
+✅ Protocols                        ✅ Heavy implementations
+✅ Hooks                            ✅ CLI commands
+✅ Adapters                         ✅ External integrations
+✅ Base classes                     ✅ Optional deps
+✅ Decorators                       ✅ UI components
+✅ Dataclasses                      ✅ Database adapters
+❌ Heavy implementations            ❌ Core logic
+```
+
+### 4.2 No Performance Impact (MUST)
+
+```python
+# ✅ CORRECT: Lazy import
+def use_chromadb():
+    try:
+        import chromadb
+    except ImportError:
+        raise ImportError("Install with: pip install praisonaiagents[memory]")
+
+# ❌ WRONG: Module-level heavy import
+import chromadb  # Adds 500ms+ to import time
+```
+
+**Rules:**
+- No module-level imports of optional dependencies
+- No heavy initialization in `__init__.py`
+- Use `__getattr__` for lazy loading in package roots
+- Target: < 200ms package import time
+
+### 4.3 DRY Approach (MUST)
+
+- Reuse existing abstractions; don't duplicate
+- Refactor safely when duplication is found
+- Check existing protocols before creating new ones
+- Use existing EventBus instead of creating new messaging
+
+### 4.4 Agent-Centric Design (MUST)
+
+Every API decision must prioritize:
+1. **Agents** - Core execution unit
+2. **Multi-agent workflows** - Coordination patterns
+3. **Sessions** - State management
+4. **Tools** - Agent capabilities
+5. **Memory** - Persistence and context
+
+### 4.5 Async-Safe & Multi-Agent Safe (MUST)
+
+```
+Async-Safe:
+- All I/O operations must have async variants
+- Never block the event loop with sync I/O in async context
+- Use asyncio primitives for coordination (not threading)
+
+Multi-Agent Safe:
+- No shared mutable global state between agents
+- Each agent owns its context, memory, and session
+- Cross-agent communication via explicit channels (EventBus, handoff)
+- Resource isolation by default, explicit sharing when needed
+```
+
+### 4.6 Invariants (Never Break)
+
+| Invariant | Meaning |
+|-----------|---------|
+| Protocol-driven core | Core SDK has NO heavy implementations |
+| Lazy imports | Optional deps never imported at module level |
+| Backward compatible | Public API changes require deprecation cycle |
+| Safe defaults | New features are opt-in, not opt-out |
+| Deterministic tests | Tests must not depend on timing or external state |
+
+### 4.7 Concurrency Model
+
+```
+Sync/Async Boundaries:
+- User-facing: Both sync and async entry points (run/start)
+- Internal: Prefer async, wrap for sync callers
+- Tools: Support both sync and async execution
+- Hooks: Fire in the current execution context (sync or async)
+
+Event Loop Rules:
+- One event loop per thread
+- Never nest event loops
+- Use asyncio.run() only at top level
+```
+
+### 4.8 Error Handling & Observability
+
+```
+Error Model:
+- Fail fast with clear error messages
+- Include remediation hints in exceptions
+- Propagate context (agent name, tool name, session ID)
+- Hook points for error interception (on_error events)
+
+Observability Hooks:
+- All key operations emit events via EventBus
+- Trace protocols for external observability integration
+- Structured logging with correlation IDs
+- Metrics collection via optional adapters
+```
+
+### 4.9 Naming Conventions
+
+```python
+# Registration/Mutation
+add_X()          # User-facing registration (add_hook, add_policy)
+remove_X()       # Unregistration
+register_X()     # Internal/framework registration
+
+# Retrieval
+get_X()          # Single item by ID (get_tool, get_policy)
+search_X()       # Multiple by query (search_memory)
+list_X()         # All items (list_tools, list_plugins)
+has_X()          # Existence check
+
+# Persistence
+save() / load()  # Disk persistence (NOT store)
+
+# Configuration
+class XConfig:   # Configuration dataclass (MemoryConfig, HooksConfig)
+
+# Protocols
+class XProtocol(Protocol):  # Abstract interface
+class XAdapter:             # Implementation
+
+# Execution
+run()            # Synchronous, blocking
+start()          # Async/long-running
+execute()        # Internal/low-level
+```
+
+---
+
+## 5. API Philosophy
+
+### 5.1 Simple API (User-Facing)
+
+```python
+# Basic usage - 3 lines
+from praisonaiagents import Agent
+agent = Agent(name="assistant", instructions="Be helpful")
+response = agent.start("Hello!")
+
+# With tools - still simple
+from praisonaiagents import Agent, tool
+
+@tool
+def search(query: str) -> list:
+    """Search the web."""
+    return [{"result": query}]
+
+agent = Agent(name="researcher", tools=[search])
+```
+
+### 5.2 Progressive Disclosure
+
+```python
+# Level 1: Minimal (most users)
+agent = Agent(name="assistant")
+
+# Level 2: With common options
+agent = Agent(
+    name="assistant",
+    llm="gpt-4o-mini",
+    memory=True
+)
+
+# Level 3: Full control (power users)
+from praisonaiagents import Agent, MemoryConfig, HooksConfig
+
+agent = Agent(
+    name="assistant",
+    llm="gpt-4o-mini",
+    memory=MemoryConfig(provider="chroma", use_long_term=True),
+    hooks=HooksConfig(before_tool=[my_validator]),
+    guardrail=my_guardrail
+)
+```
+
+---
+
+## 6. Extension Points
+
+### 6.1 Tools
+
+```python
+# Decorator style (simplest)
+from praisonaiagents import tool
+
+@tool
+def my_tool(query: str) -> str:
+    """Tool description."""
+    return f"Result: {query}"
+
+# Class style (more control)
+from praisonaiagents.tools import BaseTool
+
+class MyTool(BaseTool):
+    name = "my_tool"
+    description = "Does something"
+    
+    def run(self, query: str) -> str:
+        return f"Result: {query}"
+```
+
+**Base files:**
+- `praisonaiagents/tools/base.py` - BaseTool class
+- `praisonaiagents/tools/decorator.py` - @tool decorator
+- `praisonaiagents/tools/registry.py` - Tool registry
+
+> [!IMPORTANT]
+> **Agents only recognize parameters.** When creating tools, always expose all options as function parameters—agents cannot discover env vars or config files.
+
+### 6.2 Hooks & Middleware
+
+```python
+from praisonaiagents.hooks import add_hook, before_tool, after_tool
+
+@before_tool
+def validate_args(event):
+    print(f"Calling: {event.tool_name}")
+
+@after_tool
+def log_result(event):
+    print(f"Result: {event.result}")
+
+# Or functional style
+hook_id = add_hook("before_tool", my_handler)
+```
+
+### 6.3 Memory Adapters
+
+```python
+from praisonaiagents.memory.protocols import MemoryProtocol
+
+class MyMemoryAdapter:  # Implements MemoryProtocol
+    def store_short_term(self, text, metadata=None):
+        ...
+    def search_short_term(self, query, limit=5):
+        ...
+```
+
+### 6.4 Database Adapters
+
+```python
+# Base files in praisonaiagents/db/
+from praisonaiagents.db import DbAdapter, AsyncDbAdapter
+
+class MyDbAdapter(DbAdapter):
+    def connect(self): ...
+    def query(self, sql, params): ...
+```
+
+---
+
+## 7. CLI Representation
+
+Every feature must have CLI parity:
+
+```bash
+# Basic agent
+praisonai agent run --name "assistant" --prompt "Hello"
+
+# With tools
+praisonai agent run --tools web_search --prompt "Search for Python"
+
+# Multi-agent workflow
+praisonai workflow run --file workflow.yaml
+
+# Server mode
+praisonai serve --port 8000
+```
+
+---
+
+## 8. Documentation Standards
+
+### 8.1 Mintlify Components
+
+Use these Mintlify components for docs:
+
+- `<Accordion>` / `<AccordionGroup>` - Collapsible content
+- `<Card>` / `<CardGroup>` / `<Columns>` - Visual containers
+- `<CodeGroup>` - Tabbed code blocks
+- `<Steps>` / `<Step>` - Sequential instructions
+- `<Tabs>` / `<Tab>` - Tabbed content
+- `<Note>`, `<Warning>`, `<Info>`, `<Tip>` - Callouts
+- `<Frame>` - Image containers
+- `<Icon>` - Inline icons
+- `<Tooltip>` - Hover text
+
+### 8.2 Mermaid Diagram Standards
+
+```
+Two-color scheme:
+- Dark Red (#8B0000) - Agents, inputs, outputs
+- Teal/Cyan (#189AB4) - Tools
+- White text (#fff) for contrast
+```
+
+```mermaid
+graph LR
+    A[Input]:::agent --> B[Agent]:::agent
+    B --> C[Tool]:::tool
+    C --> D[Output]:::agent
+    
+    classDef agent fill:#8B0000,color:#fff
+    classDef tool fill:#189AB4,color:#fff
+```
+
+### 8.3 Documentation Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Beginner-friendly** | Non-developers should understand core concepts |
+| **Copy-paste success** | Code examples must run with minimal setup |
+| **Less text, more interaction** | Prefer components over long paragraphs |
+| **Show, don't tell** | Use diagrams, tabs, and accordions to explain |
+| **Few lines, big impact** | Examples should feel like "only 3 lines to do this" |
+
+### 8.4 Page Title Conventions
+
+```
+SDK docs:     "Memory Module", "Tools Module", "Hooks Module"
+API docs:     "Agent API", "Tool API", "Memory API"
+Guides:       "Single Agent Guide", "Multi-Agent Guide"
+Tutorials:    "Build a Research Agent", "Create Custom Tools"
+```
+
+### 8.5 Example Quality Standards
+
+```
+Every code example MUST:
+- Run without modification (copy-paste success)
+- Include necessary imports
+- Use realistic but simple data
+- Show expected output in comments
+- Be the SHORTEST way to accomplish the task
+```
+
+---
+
+## 9. Testing Standards
+
+### 9.1 TDD Mandatory
+
+```python
+# 1. Write failing test first
+def test_new_feature():
+    result = new_feature()
+    assert result == expected
+
+# 2. Implement feature
+# 3. Verify test passes
+```
+
+### 9.2 Test Structure
+
+```
+tests/
+├── unit/                  # Fast, isolated tests
+├── integration/           # Cross-module tests
+├── e2e/                  # End-to-end tests
+└── fixtures/             # Test data
+```
+
+### 9.3 Run Tests
+
+```bash
+# All tests
+pytest tests/
+
+# Specific category
+pytest tests/unit/
+
+# With coverage
+pytest --cov=praisonaiagents tests/
+```
+
+---
+
+## 10. Implementation Checklist
+
+For every feature/change:
+
+- [ ] **Protocol-first**: Add protocol to core if needed
+- [ ] **No new deps**: Use optional dependencies only
+- [ ] **Lazy imports**: Heavy deps imported inside functions
+- [ ] **Naming**: Follow conventions (add_*, get_*, XConfig)
+- [ ] **Tests**: TDD - write failing tests first
+- [ ] **CLI**: Add corresponding CLI command/option
+- [ ] **Docs**: Update Mintlify documentation
+- [ ] **Examples**: Add to examples/ directory
+- [ ] **Multi-agent safe**: No shared mutable state
+- [ ] **Async-safe**: Support async/await patterns
+- [ ] **Performance**: No import-time or hot-path regressions
+
+---
+
+## 11. Quick Reference
+
+### 11.1 Core Imports
+
+```python
+# Most common
+from praisonaiagents import Agent, Agents, Task, tool, Tools
+
+# Configuration
+from praisonaiagents import (
+    MemoryConfig, KnowledgeConfig, PlanningConfig,
+    OutputConfig, ExecutionConfig, HooksConfig
+)
+
+# Hooks
+from praisonaiagents.hooks import add_hook, before_tool, after_tool
+
+# Event Bus
+from praisonaiagents.bus import EventBus, get_default_bus
+
+# Memory
+from praisonaiagents import Memory, Session
+
+# Workflows
+from praisonaiagents import Workflow, Route, Parallel, Loop
+```
+
+### 11.2 File Locations
+
+| What | Where |
+|------|-------|
+| Agent class | `praisonaiagents/agent/agent.py` |
+| Tool decorator | `praisonaiagents/tools/decorator.py` |
+| Base tool | `praisonaiagents/tools/base.py` |
+| Hook system | `praisonaiagents/hooks/` |
+| Memory protocols | `praisonaiagents/memory/protocols.py` |
+| Event bus | `praisonaiagents/bus/bus.py` |
+| Workflow engine | `praisonaiagents/workflows/workflows.py` |
+| Policy engine | `praisonaiagents/policy/engine.py` |
+
+---
+
+## 12. Design Goals
+
+> Make PraisonAI the **best agent framework in the world**
+
+1. **Simpler** than competitors (fewer concepts, cleaner API)
+2. **More extensible** (protocol-driven, plugin-ready)
+3. **Faster** (lazy loading, minimal overhead)
+4. **Safer** (guardrails, policies, HITL by default)
+5. **Production-ready** (observability, checkpoints, replay)
+
+---
+
+## 13. Paid Value Path
+
+The core remains **free and open source**. Clear upgrade paths to paid value:
+
+| Free (Core) | Paid (Cloud/Services) |
+|-------------|----------------------|
+| All protocols | Managed hosting |
+| All base classes | Enterprise support |
+| Local execution | Budget management |
+| File-based memory | Multi-tenant RBAC |
+| Basic observability | Advanced analytics |
+| Community support | SLA-backed support |
+
+---
+
+*This document is the source of truth for the PraisonAI SDK architecture and design principles.*
@@ -3,6 +3,9 @@
 Agent-level guardrails example.
 This example demonstrates how to use guardrails at the Agent level
 which will apply to all tasks executed by that agent.
+
+Note: Agent guardrails only support function-based validation or preset strings
+(permissive, safety, strict). For LLM-based guardrails, use Task guardrails.
 """
 from typing import Tuple, Any
 from praisonaiagents import Agent, TaskOutput
@@ -38,10 +41,10 @@ def validate_professional_tone(task_output: TaskOutput) -> Tuple[bool, Any]:


 def main():
-    """Demonstrate Agent-level guardrails with function-based and LLM-based validation."""
+    """Demonstrate Agent-level guardrails with function-based validation."""
    print("=== Agent Guardrail Examples ===\n")
    
-    # Example 1: Function-based guardrail
+    # Example 1: Function-based guardrail for content length
    print("1. Function-based guardrail (content length validation):")
    agent1 = Agent(
        name="ContentWriter",
@@ -54,12 +57,12 @@ def main():
    except Exception as e:
        print(f"Error: {e}\n")
    
-    # Example 2: LLM-based guardrail (string description)
-    print("2. LLM-based guardrail (professional tone validation):")
+    # Example 2: Function-based guardrail for professional tone
+    print("2. Function-based guardrail (professional tone validation):")
    agent2 = Agent(
        name="BusinessWriter", 
-        instructions="You are a business communication expert",
-        guardrails="Ensure the content is professional, formal, and suitable for business communication. No casual language or slang."
+        instructions="You are a business communication expert. Write formal, professional content.",
+        guardrails=validate_professional_tone
    )
    try:
        result2 = agent2.start("Write a welcome message for new employees")
@@ -67,20 +70,22 @@ def main():
    except Exception as e:
        print(f"Error: {e}\n")
    
-    # Example 3: Multiple agents with different guardrails
-    print("3. Professional tone function-based guardrail:")
+    # Example 3: Using preset guardrails (built-in options)
+    print("3. Using preset guardrail ('safety'):")
    agent3 = Agent(
-        name="ProfessionalWriter",
-        instructions="Write professional business content",
-        guardrails=validate_professional_tone
+        name="SafeWriter",
+        instructions="Write helpful content",
+        guardrails="safety"  # Valid presets: permissive, safety, strict
    )
    try:
-        result3 = agent3.start("Write a casual greeting message")
+        result3 = agent3.start("Write a friendly greeting message")
        print(f"Result: {result3}\n")
    except Exception as e:
        print(f"Error: {e}\n")
    
    print("=== Agent Guardrails Demonstration Complete ===")
+    print("\nNote: For LLM-based guardrails with custom descriptions,")
+    print("use Task-level guardrails instead of Agent-level guardrails.")


 if __name__ == "__main__":
@@ -1,6 +1,6 @@
 # PraisonAI Agents - Tools Benchmark Results

-**Generated:** 2025-12-18 14:40:35
+**Generated:** 2026-01-23 11:50:18
 **Iterations:** 100
 **Test:** Agent instantiation WITH TOOLS

@@ -8,22 +8,22 @@

 | Framework | Avg Time (μs) | Relative |
 |-----------|---------------|----------|
-| **PraisonAI** | **3.24** | **1.00x (fastest)** |
-| Agno | 5.12 | 1.58x |
-| PraisonAI (LiteLLM) | 8.59 | 2.65x |
-| OpenAI Agents SDK | 279.95 | 86.44x |
-| LangGraph | 2,310.82 | 713x |
-| CrewAI | 15,773.44 | 4,870x |
+| **PraisonAI** | **5.30** | **1.00x (fastest)** |
+| Agno | 5.62 | 1.06x |
+| PraisonAI (LiteLLM) | 11.08 | 2.09x |
+| OpenAI Agents SDK | 315.49 | 59.55x |
+| LangGraph | 2,511.95 | 474x |
+| CrewAI | 41,349.24 | 7,804x |

 ## Package Versions

 | Package | Version |
 |---------|--------|
-| PraisonAI | 0.1.5 |
-| Agno | 2.3.14 |
+| PraisonAI | 0.13.11 |
+| Agno | 2.4.2 |
 | OpenAI Agents SDK | 0.6.3 |
-| LangGraph | 1.0.5 |
-| CrewAI | 1.6.1 |
+| LangGraph | 1.0.7 |
+| CrewAI | 1.8.1 |

 ## How to Reproduce

@@ -9,8 +9,16 @@ Key Optimizations Applied:
 2. Lazy os.getcwd() - fast_context_path resolved only when needed
 3. Lazy console initialization - Rich Console created on demand

+Advanced Profiling Features:
+- Line-by-line profiling of __init__ method
+- Call graph analysis
+- Memory allocation tracking
+- Function call counting
+- Attribute access profiling
+
 Usage:
    python benchmarks/deep_profiling.py
+    python benchmarks/deep_profiling.py --deep  # More detailed profiling
 """

 import time
@@ -136,7 +144,7 @@ def profile_praisonai_detailed():
        instructions="Be concise, reply with one sentence.",
        llm="gpt-4o-mini",
        tools=tools,
-        verbose=False
+        output="silent"
    )
    profiler.end_step()
    
@@ -156,7 +164,7 @@ def profile_praisonai_detailed():
            instructions="Be concise, reply with one sentence.",
            llm="gpt-4o-mini",
            tools=tools,
-            verbose=False
+            output="silent"
        )
    
    pr.disable()
@@ -249,14 +257,14 @@ def profile_praisonai_components():
    
    # Test different configurations
    configs = [
-        ("Minimal (no tools, no llm)", {"name": "Test", "verbose": False}),
-        ("With name only", {"name": "Test Agent", "verbose": False}),
-        ("With instructions", {"name": "Test", "instructions": "Be concise", "verbose": False}),
-        ("With llm (gpt-4o-mini)", {"name": "Test", "llm": "gpt-4o-mini", "verbose": False}),
-        ("With llm (openai/gpt-4o-mini)", {"name": "Test", "llm": "openai/gpt-4o-mini", "verbose": False}),
-        ("With tools", {"name": "Test", "tools": tools, "verbose": False}),
-        ("Full config (OpenAI SDK)", {"name": "Test", "instructions": "Be concise", "llm": "gpt-4o-mini", "tools": tools, "verbose": False}),
-        ("Full config (LiteLLM)", {"name": "Test", "instructions": "Be concise", "llm": "openai/gpt-4o-mini", "tools": tools, "verbose": False}),
+        ("Minimal (no tools, no llm)", {"name": "Test", "output": "silent"}),
+        ("With name only", {"name": "Test Agent", "output": "silent"}),
+        ("With instructions", {"name": "Test", "instructions": "Be concise", "output": "silent"}),
+        ("With llm (gpt-4o-mini)", {"name": "Test", "llm": "gpt-4o-mini", "output": "silent"}),
+        ("With llm (openai/gpt-4o-mini)", {"name": "Test", "llm": "openai/gpt-4o-mini", "output": "silent"}),
+        ("With tools", {"name": "Test", "tools": tools, "output": "silent"}),
+        ("Full config (OpenAI SDK)", {"name": "Test", "instructions": "Be concise", "llm": "gpt-4o-mini", "tools": tools, "output": "silent"}),
+        ("Full config (LiteLLM)", {"name": "Test", "instructions": "Be concise", "llm": "openai/gpt-4o-mini", "tools": tools, "output": "silent"}),
    ]
    
    print(f"\n{'Configuration':<40} {'Avg Time (μs)':<15} {'Min (μs)':<15} {'Max (μs)':<15}")
@@ -295,7 +303,7 @@ def compare_specific_operations():
    
    # Operation 1: Bare minimum instantiation
    def praisonai_minimal():
-        return PraisonAgent(name="Test", verbose=False)
+        return PraisonAgent(name="Test", output="silent")
    
    def agno_minimal():
        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"))
@@ -306,7 +314,7 @@ def compare_specific_operations():
    
    # Operation 2: With tools
    def praisonai_with_tools():
-        return PraisonAgent(name="Test", tools=tools, verbose=False)
+        return PraisonAgent(name="Test", tools=tools, output="silent")
    
    def agno_with_tools():
        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
@@ -322,7 +330,7 @@ def compare_specific_operations():
            instructions="Be concise",
            llm="gpt-4o-mini",
            tools=tools,
-            verbose=False
+            output="silent"
        )
    
    def agno_full():
@@ -344,12 +352,199 @@ def compare_specific_operations():
        print(f"{op_name:<30} {praison_time:<18.2f} {agno_time:<18.2f} {ratio:<10.1f}x")


+# ============================================================================
+# Advanced: Attribute Access Profiling
+# ============================================================================
+
+def profile_attribute_access():
+    """Profile attribute access patterns in Agent.__init__"""
+    print("\n" + "="*70)
+    print("ATTRIBUTE ACCESS PROFILING")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    
+    # Count attribute accesses during init
+    attr_counts = {}
+    original_setattr = object.__setattr__
+    
+    def counting_setattr(obj, name, value):
+        if isinstance(obj, PraisonAgent):
+            attr_counts[name] = attr_counts.get(name, 0) + 1
+        return original_setattr(obj, name, value)
+    
+    # Temporarily patch
+    import builtins
+    old_setattr = builtins.setattr if hasattr(builtins, 'setattr') else None
+    
+    # Create agent and count
+    agent = PraisonAgent(name="Test", output="silent")
+    
+    # Sort by count
+    sorted_attrs = sorted(attr_counts.items(), key=lambda x: x[1], reverse=True)
+    
+    print(f"\n{'Attribute':<40} {'Set Count':<15}")
+    print("-" * 55)
+    for attr, count in sorted_attrs[:30]:
+        print(f"{attr:<40} {count:<15}")
+    
+    print(f"\nTotal attributes set: {len(attr_counts)}")
+    print(f"Total setattr calls: {sum(attr_counts.values())}")
+
+
+# ============================================================================
+# Advanced: Function Call Analysis
+# ============================================================================
+
+def analyze_init_function_calls():
+    """Analyze which functions are called during Agent.__init__"""
+    print("\n" + "="*70)
+    print("FUNCTION CALL ANALYSIS: PraisonAI Agent.__init__")
+    print("="*70)
+    
+    import sys
+    from praisonaiagents import Agent as PraisonAgent
+    
+    call_counts = {}
+    
+    def trace_calls(frame, event, arg):
+        if event == 'call':
+            code = frame.f_code
+            func_name = code.co_name
+            filename = code.co_filename
+            
+            # Only track praisonaiagents calls
+            if 'praisonaiagents' in filename:
+                key = f"{func_name} ({filename.split('/')[-1]}:{code.co_firstlineno})"
+                call_counts[key] = call_counts.get(key, 0) + 1
+        return trace_calls
+    
+    # Enable tracing
+    sys.settrace(trace_calls)
+    
+    try:
+        agent = PraisonAgent(name="Test", output="silent")
+    finally:
+        sys.settrace(None)
+    
+    # Sort by count
+    sorted_calls = sorted(call_counts.items(), key=lambda x: x[1], reverse=True)
+    
+    print(f"\n{'Function':<60} {'Calls':<10}")
+    print("-" * 70)
+    for func, count in sorted_calls[:40]:
+        print(f"{func:<60} {count:<10}")
+    
+    print(f"\nTotal unique functions called: {len(call_counts)}")
+    print(f"Total function calls: {sum(call_counts.values())}")
+
+
+# ============================================================================
+# Advanced: Import Time Analysis
+# ============================================================================
+
+def analyze_import_overhead():
+    """Analyze import overhead for key modules"""
+    print("\n" + "="*70)
+    print("IMPORT OVERHEAD ANALYSIS")
+    print("="*70)
+    
+    import sys
+    import importlib
+    
+    modules_to_test = [
+        'praisonaiagents',
+        'praisonaiagents.agent.agent',
+        'praisonaiagents.config.param_resolver',
+        'praisonaiagents.config.presets',
+        'praisonaiagents.config.feature_configs',
+    ]
+    
+    print(f"\n{'Module':<50} {'Import Time (ms)':<20}")
+    print("-" * 70)
+    
+    for module_name in modules_to_test:
+        # Clear from cache
+        to_remove = [k for k in sys.modules.keys() if k.startswith('praisonaiagents')]
+        for k in to_remove:
+            del sys.modules[k]
+        
+        start = time.perf_counter()
+        try:
+            importlib.import_module(module_name)
+            elapsed = (time.perf_counter() - start) * 1000
+            print(f"{module_name:<50} {elapsed:<20.2f}")
+        except ImportError as e:
+            print(f"{module_name:<50} FAILED: {e}")
+
+
+# ============================================================================
+# Advanced: Agno vs PraisonAI Architecture Comparison
+# ============================================================================
+
+def compare_architecture():
+    """Compare architectural differences between Agno and PraisonAI"""
+    print("\n" + "="*70)
+    print("ARCHITECTURE COMPARISON: Agno vs PraisonAI")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    from agno.agent import Agent as AgnoAgent
+    from agno.models.openai import OpenAIChat
+    
+    # Create instances
+    praison_agent = PraisonAgent(name="Test", output="silent")
+    agno_agent = AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"))
+    
+    print("\n### Class Structure ###")
+    print(f"\nPraisonAI Agent:")
+    print(f"  - Uses @dataclass: No (regular class)")
+    print(f"  - __slots__: {'Yes' if hasattr(PraisonAgent, '__slots__') else 'No'}")
+    print(f"  - Instance dict size: {len(praison_agent.__dict__)} attributes")
+    
+    print(f"\nAgno Agent:")
+    print(f"  - Uses @dataclass: Yes (init=False)")
+    print(f"  - __slots__: {'Yes' if hasattr(AgnoAgent, '__slots__') else 'No'}")
+    print(f"  - Instance dict size: {len(agno_agent.__dict__)} attributes")
+    
+    print("\n### Key Differences ###")
+    print("\n1. Agno uses @dataclass(init=False) - class attributes pre-declared")
+    print("2. Agno __init__ is mostly simple attribute assignments")
+    print("3. PraisonAI __init__ does extensive parameter resolution")
+    print("4. PraisonAI imports config modules inside __init__")
+    print("5. PraisonAI calls resolve() 10+ times for feature params")
+    
+    # Count resolve calls in PraisonAI
+    print("\n### Parameter Resolution Overhead ###")
+    print("\nPraisonAI resolve() calls in __init__:")
+    print("  - output: resolve()")
+    print("  - execution: resolve()")
+    print("  - templates: resolve()")
+    print("  - caching: resolve()")
+    print("  - hooks: resolve()")
+    print("  - skills: resolve()")
+    print("  - memory: resolve()")
+    print("  - knowledge: resolve()")
+    print("  - planning: resolve()")
+    print("  - reflection: resolve()")
+    print("  - guardrails: resolve()")
+    print("  - web: resolve()")
+    print("  Total: 12 resolve() calls per Agent creation")
+
+
 # ============================================================================
 # Main
 # ============================================================================

 if __name__ == "__main__":
    import os
+    import argparse
+    
+    parser = argparse.ArgumentParser(description='Deep Profiling Benchmark')
+    parser.add_argument('--deep', action='store_true', help='Run deep profiling (slower)')
+    parser.add_argument('--save', action='store_true', help='Save results to file')
+    args = parser.parse_args()
+    
    os.environ.setdefault("OPENAI_API_KEY", "sk-test")
    
    print("="*70)
@@ -363,6 +558,17 @@ if __name__ == "__main__":
    profile_praisonai_components()
    compare_specific_operations()
    
+    # Advanced profiling (optional)
+    if args.deep:
+        print("\n" + "="*70)
+        print("ADVANCED PROFILING (--deep mode)")
+        print("="*70)
+        analyze_init_function_calls()
+        analyze_import_overhead()
+    
+    # Always run architecture comparison
+    compare_architecture()
+    
    print("\n" + "="*70)
    print("PROFILING COMPLETE")
    print("="*70)
@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Detailed Profiling Benchmark
+
+Provides function-level profiling for PraisonAI agent execution.
+Shows exactly which functions are called, from which files, and how long each takes.
+
+Usage:
+    export OPENAI_API_KEY=your_key
+    python benchmarks/detailed_profiling_benchmark.py
+    python benchmarks/detailed_profiling_benchmark.py --framework praisonai
+    python benchmarks/detailed_profiling_benchmark.py --framework agno
+"""
+
+import time
+import os
+import sys
+import argparse
+import cProfile
+import pstats
+import io
+from functools import wraps
+from collections import defaultdict
+from datetime import datetime
+
+# Defaults
+DEFAULT_MODEL = "gpt-4o-mini"
+DEFAULT_PROMPT = "What is 2+2? Reply with just the number."
+
+
+class DetailedProfiler:
+    """Detailed function-level profiler with file path tracking."""
+    
+    def __init__(self):
+        self.call_times = defaultdict(list)
+        self.call_counts = defaultdict(int)
+        self.profiler = None
+        
+    def start(self):
+        """Start cProfile profiler."""
+        self.profiler = cProfile.Profile()
+        self.profiler.enable()
+        
+    def stop(self):
+        """Stop profiler and return stats."""
+        if self.profiler:
+            self.profiler.disable()
+            return self.profiler
+        return None
+    
+    def get_stats_string(self, sort_by='cumtime', limit=50):
+        """Get formatted stats string."""
+        if not self.profiler:
+            return "No profiler data"
+        
+        s = io.StringIO()
+        ps = pstats.Stats(self.profiler, stream=s)
+        ps.sort_stats(sort_by)
+        ps.print_stats(limit)
+        return s.getvalue()
+    
+    def get_detailed_breakdown(self, filter_pattern=None, limit=100):
+        """Get detailed breakdown with file paths."""
+        if not self.profiler:
+            return []
+        
+        stats = pstats.Stats(self.profiler)
+        
+        results = []
+        for (filename, line, func), (cc, nc, tt, ct, callers) in stats.stats.items():
+            # Filter by pattern if provided
+            if filter_pattern and filter_pattern not in filename and filter_pattern not in func:
+                continue
+            
+            results.append({
+                'file': filename,
+                'line': line,
+                'function': func,
+                'calls': nc,
+                'total_time': tt,
+                'cumulative_time': ct,
+                'time_per_call': tt / nc if nc > 0 else 0,
+            })
+        
+        # Sort by cumulative time
+        results.sort(key=lambda x: x['cumulative_time'], reverse=True)
+        return results[:limit]
+
+
+def profile_praisonai_detailed(model, prompt):
+    """Profile PraisonAI agent execution in detail."""
+    print("\n" + "=" * 80)
+    print("DETAILED PROFILING: PraisonAI")
+    print("=" * 80)
+    
+    profiler = DetailedProfiler()
+    
+    # Profile import
+    print("\n--- Import Phase ---")
+    import_start = time.perf_counter()
+    profiler.start()
+    from praisonaiagents import Agent
+    profiler.stop()
+    import_time = time.perf_counter() - import_start
+    print(f"Import time: {import_time*1000:.2f}ms")
+    
+    # Show import profile
+    print("\nTop 20 functions during import (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler.get_detailed_breakdown(filter_pattern='praisonai', limit=20)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Profile instantiation
+    print("\n--- Instantiation Phase ---")
+    profiler2 = DetailedProfiler()
+    inst_start = time.perf_counter()
+    profiler2.start()
+    agent = Agent(
+        name="Calculator",
+        instructions="You are a helpful assistant. Be very brief.",
+        llm=model
+    )
+    profiler2.stop()
+    inst_time = time.perf_counter() - inst_start
+    print(f"Instantiation time: {inst_time*1000:.2f}ms")
+    
+    print("\nTop 30 functions during instantiation (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler2.get_detailed_breakdown(filter_pattern='praisonai', limit=30)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Profile execution
+    print("\n--- Execution Phase (agent.start) ---")
+    profiler3 = DetailedProfiler()
+    exec_start = time.perf_counter()
+    profiler3.start()
+    response = agent.start(prompt, output="silent")
+    profiler3.stop()
+    exec_time = time.perf_counter() - exec_start
+    print(f"Execution time: {exec_time*1000:.2f}ms ({exec_time:.2f}s)")
+    print(f"Response: {str(response)[:100]}")
+    
+    print("\nTop 50 functions during execution (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler3.get_detailed_breakdown(limit=50)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # PraisonAI-specific functions
+    print("\n--- PraisonAI-Specific Functions ---")
+    print("-" * 80)
+    praisonai_funcs = profiler3.get_detailed_breakdown(filter_pattern='praisonai', limit=50)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in praisonai_funcs:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("SUMMARY: PraisonAI")
+    print("=" * 80)
+    print(f"Import time:        {import_time*1000:>10.2f}ms")
+    print(f"Instantiation time: {inst_time*1000:>10.2f}ms")
+    print(f"Execution time:     {exec_time*1000:>10.2f}ms")
+    print(f"Total time:         {(import_time+inst_time+exec_time)*1000:>10.2f}ms")
+    
+    return {
+        'import_time': import_time,
+        'instantiation_time': inst_time,
+        'execution_time': exec_time,
+        'total_time': import_time + inst_time + exec_time,
+    }
+
+
+def profile_agno_detailed(model, prompt):
+    """Profile Agno agent execution in detail."""
+    print("\n" + "=" * 80)
+    print("DETAILED PROFILING: Agno")
+    print("=" * 80)
+    
+    profiler = DetailedProfiler()
+    
+    # Profile import
+    print("\n--- Import Phase ---")
+    import_start = time.perf_counter()
+    profiler.start()
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    profiler.stop()
+    import_time = time.perf_counter() - import_start
+    print(f"Import time: {import_time*1000:.2f}ms")
+    
+    print("\nTop 20 functions during import (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler.get_detailed_breakdown(filter_pattern='agno', limit=20)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Profile instantiation
+    print("\n--- Instantiation Phase ---")
+    profiler2 = DetailedProfiler()
+    inst_start = time.perf_counter()
+    profiler2.start()
+    agent = Agent(
+        model=OpenAIChat(id=model),
+        instructions=["You are a helpful assistant. Be very brief."],
+    )
+    profiler2.stop()
+    inst_time = time.perf_counter() - inst_start
+    print(f"Instantiation time: {inst_time*1000:.2f}ms")
+    
+    print("\nTop 30 functions during instantiation (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler2.get_detailed_breakdown(filter_pattern='agno', limit=30)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Profile execution
+    print("\n--- Execution Phase (agent.run) ---")
+    profiler3 = DetailedProfiler()
+    exec_start = time.perf_counter()
+    profiler3.start()
+    response = agent.run(prompt)
+    profiler3.stop()
+    exec_time = time.perf_counter() - exec_start
+    content = str(response.content)[:100] if hasattr(response, 'content') else str(response)[:100]
+    print(f"Execution time: {exec_time*1000:.2f}ms ({exec_time:.2f}s)")
+    print(f"Response: {content}")
+    
+    print("\nTop 50 functions during execution (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler3.get_detailed_breakdown(limit=50)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Agno-specific functions
+    print("\n--- Agno-Specific Functions ---")
+    print("-" * 80)
+    agno_funcs = profiler3.get_detailed_breakdown(filter_pattern='agno', limit=50)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in agno_funcs:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("SUMMARY: Agno")
+    print("=" * 80)
+    print(f"Import time:        {import_time*1000:>10.2f}ms")
+    print(f"Instantiation time: {inst_time*1000:>10.2f}ms")
+    print(f"Execution time:     {exec_time*1000:>10.2f}ms")
+    print(f"Total time:         {(import_time+inst_time+exec_time)*1000:>10.2f}ms")
+    
+    return {
+        'import_time': import_time,
+        'instantiation_time': inst_time,
+        'execution_time': exec_time,
+        'total_time': import_time + inst_time + exec_time,
+    }
+
+
+def profile_crewai_detailed(model, prompt):
+    """Profile CrewAI agent execution in detail."""
+    print("\n" + "=" * 80)
+    print("DETAILED PROFILING: CrewAI")
+    print("=" * 80)
+    
+    profiler = DetailedProfiler()
+    
+    # Profile import
+    print("\n--- Import Phase ---")
+    import_start = time.perf_counter()
+    profiler.start()
+    from crewai import Agent, Task, Crew
+    profiler.stop()
+    import_time = time.perf_counter() - import_start
+    print(f"Import time: {import_time*1000:.2f}ms")
+    
+    # Profile instantiation
+    print("\n--- Instantiation Phase ---")
+    profiler2 = DetailedProfiler()
+    inst_start = time.perf_counter()
+    profiler2.start()
+    agent = Agent(
+        role="Calculator",
+        goal="Answer math questions",
+        backstory="You are a helpful assistant.",
+        llm=model,
+        verbose=False
+    )
+    task = Task(
+        description=prompt,
+        expected_output="A number",
+        agent=agent
+    )
+    crew = Crew(
+        agents=[agent],
+        tasks=[task],
+        verbose=False
+    )
+    profiler2.stop()
+    inst_time = time.perf_counter() - inst_start
+    print(f"Instantiation time: {inst_time*1000:.2f}ms")
+    
+    # Profile execution
+    print("\n--- Execution Phase (crew.kickoff) ---")
+    profiler3 = DetailedProfiler()
+    exec_start = time.perf_counter()
+    profiler3.start()
+    response = crew.kickoff()
+    profiler3.stop()
+    exec_time = time.perf_counter() - exec_start
+    print(f"Execution time: {exec_time*1000:.2f}ms ({exec_time:.2f}s)")
+    print(f"Response: {str(response)[:100]}")
+    
+    print("\nTop 50 functions during execution (by cumulative time):")
+    print("-" * 80)
+    breakdown = profiler3.get_detailed_breakdown(limit=50)
+    print(f"{'Function':<40} {'File':<50} {'Calls':>8} {'CumTime':>10}")
+    print("-" * 80)
+    for item in breakdown:
+        func = item['function'][:38]
+        file = item['file'].split('/')[-1][:48] if '/' in item['file'] else item['file'][:48]
+        print(f"{func:<40} {file:<50} {item['calls']:>8} {item['cumulative_time']*1000:>9.2f}ms")
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("SUMMARY: CrewAI")
+    print("=" * 80)
+    print(f"Import time:        {import_time*1000:>10.2f}ms")
+    print(f"Instantiation time: {inst_time*1000:>10.2f}ms")
+    print(f"Execution time:     {exec_time*1000:>10.2f}ms")
+    print(f"Total time:         {(import_time+inst_time+exec_time)*1000:>10.2f}ms")
+    
+    return {
+        'import_time': import_time,
+        'instantiation_time': inst_time,
+        'execution_time': exec_time,
+        'total_time': import_time + inst_time + exec_time,
+    }
+
+
+def compare_results(results):
+    """Compare results across frameworks."""
+    print("\n" + "=" * 80)
+    print("COMPARISON SUMMARY")
+    print("=" * 80)
+    
+    print(f"\n{'Framework':<20} {'Import':<12} {'Instantiate':<12} {'Execute':<12} {'Total':<12}")
+    print("-" * 68)
+    
+    # Sort by execution time
+    sorted_results = sorted(results.items(), key=lambda x: x[1]['execution_time'])
+    fastest_exec = sorted_results[0][1]['execution_time']
+    
+    for name, times in sorted_results:
+        import_ms = times['import_time'] * 1000
+        inst_ms = times['instantiation_time'] * 1000
+        exec_ms = times['execution_time'] * 1000
+        total_ms = times['total_time'] * 1000
+        ratio = times['execution_time'] / fastest_exec
+        
+        print(f"{name:<20} {import_ms:>10.1f}ms {inst_ms:>10.1f}ms {exec_ms:>10.1f}ms {total_ms:>10.1f}ms ({ratio:.2f}x)")
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='PraisonAI Agents - Detailed Profiling Benchmark')
+    parser.add_argument('--framework', '-f', type=str, default='all', 
+                        choices=['all', 'praisonai', 'agno', 'crewai'],
+                        help='Framework to profile (default: all)')
+    parser.add_argument('--model', '-m', type=str, default=DEFAULT_MODEL, 
+                        help=f'Model to use (default: {DEFAULT_MODEL})')
+    parser.add_argument('--prompt', '-p', type=str, default=DEFAULT_PROMPT, 
+                        help=f'Prompt to use')
+    args = parser.parse_args()
+    
+    # Check API key
+    if not os.environ.get('OPENAI_API_KEY'):
+        print("ERROR: Set OPENAI_API_KEY environment variable")
+        exit(1)
+    
+    print("=" * 80)
+    print("PraisonAI Agents - Detailed Profiling Benchmark")
+    print("=" * 80)
+    print(f"\nModel: {args.model}")
+    print(f"Prompt: \"{args.prompt}\"")
+    print(f"Framework: {args.framework}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    results = {}
+    
+    if args.framework in ['all', 'praisonai']:
+        try:
+            results['PraisonAI'] = profile_praisonai_detailed(args.model, args.prompt)
+        except Exception as e:
+            print(f"PraisonAI error: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    if args.framework in ['all', 'agno']:
+        try:
+            results['Agno'] = profile_agno_detailed(args.model, args.prompt)
+        except Exception as e:
+            print(f"Agno error: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    if args.framework in ['all', 'crewai']:
+        try:
+            results['CrewAI'] = profile_crewai_detailed(args.model, args.prompt)
+        except Exception as e:
+            print(f"CrewAI error: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    if len(results) > 1:
+        compare_results(results)
+    
+    print("\n" + "=" * 80)
+    print("Profiling complete!")
+    print("=" * 80)
@@ -219,7 +219,7 @@ def save_results(results: dict, model: str, iterations: int, prompt: str):

 if __name__ == '__main__':
    parser = argparse.ArgumentParser(description='PraisonAI Agents - Real Execution Benchmark')
-    parser.add_argument('--no-save', action='store_true', help='Do not save results to file')
+    parser.add_argument('--save', action='store_true', help='Save results to file')
    parser.add_argument('--model', '-m', type=str, default=DEFAULT_MODEL, help=f'Model to use (default: {DEFAULT_MODEL})')
    parser.add_argument('--iterations', '-i', type=int, default=DEFAULT_ITERATIONS, help=f'Number of iterations (default: {DEFAULT_ITERATIONS})')
    parser.add_argument('--prompt', '-p', type=str, default=DEFAULT_PROMPT, help=f'Prompt to use (default: "{DEFAULT_PROMPT}")')
@@ -287,8 +287,8 @@ if __name__ == '__main__':
    
    print('\n' + '=' * 60)
    
-    # Save results (unless --no-save)
-    if results and not args.no_save:
+    # Save results (if --save)
+    if results and args.save:
        save_results(results, model, iterations, prompt)
-    elif args.no_save:
-        print('\nResults not saved (--no-save flag used)')
+    elif not args.save:
+        print('\nResults not saved (use --save flag to save results to file)')
@@ -16,6 +16,7 @@ CI Gate:
 import sys
 import time
 import statistics
+import argparse


 def clear_modules():
@@ -145,4 +146,11 @@ def main():


 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='PraisonAI Agents Import Time Benchmark')
+    parser.add_argument('--save', action='store_true', help='Save results to file')
+    args = parser.parse_args()
+    
+    if not args.save:
+        print("\nNote: Results are not saved to file by default. Use --save to save them.")
+        
    sys.exit(main())
@@ -15,6 +15,7 @@ CI Gate:
 """
 import sys
 import tracemalloc
+import argparse


 def clear_modules():
@@ -86,4 +87,11 @@ def main():


 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='PraisonAI Agents Memory Usage Benchmark')
+    parser.add_argument('--save', action='store_true', help='Save results to file')
+    args = parser.parse_args()
+    
+    if not args.save:
+        print("\nNote: Results are not saved to file by default. Use --save to save them.")
+        
    sys.exit(main())
@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Parameter Impact Benchmark
+
+Profiles each Agent parameter to identify which features have the most
+performance impact. Results are ordered by cost (time + memory).
+
+This benchmark helps identify optimization opportunities by measuring
+the incremental cost of each feature.
+
+Usage:
+    python benchmarks/param_impact_benchmark.py
+    python benchmarks/param_impact_benchmark.py --no-save
+    python benchmarks/param_impact_benchmark.py --iterations 50
+"""
+
+import argparse
+import gc
+import time
+import tracemalloc
+import statistics
+from typing import Literal, List, Dict, Any, Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class ParamResult:
+    """Result for a single parameter test."""
+    param_name: str
+    param_value: Any
+    avg_time_us: float  # microseconds
+    min_time_us: float
+    max_time_us: float
+    std_dev_us: float
+    avg_memory_kb: float  # kilobytes
+    delta_time_us: float = 0.0  # difference from baseline
+    delta_memory_kb: float = 0.0
+
+
+def measure_instantiation(
+    create_fn: Callable,
+    iterations: int = 100,
+    warmup: int = 10
+) -> Dict[str, float]:
+    """Measure instantiation time and memory for a function."""
+    # Warmup
+    for _ in range(warmup):
+        create_fn()
+    
+    # Measure time
+    times = []
+    for _ in range(iterations):
+        gc.collect()
+        start = time.perf_counter()
+        create_fn()
+        elapsed = (time.perf_counter() - start) * 1_000_000  # microseconds
+        times.append(elapsed)
+    
+    # Measure memory (separate pass for accuracy)
+    memory_usages = []
+    for _ in range(min(iterations, 20)):  # Fewer iterations for memory
+        gc.collect()
+        tracemalloc.start()
+        create_fn()
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        memory_usages.append(peak / 1024)  # KB
+    
+    return {
+        'avg_time': statistics.mean(times),
+        'min_time': min(times),
+        'max_time': max(times),
+        'std_dev': statistics.stdev(times) if len(times) > 1 else 0,
+        'avg_memory': statistics.mean(memory_usages) if memory_usages else 0,
+    }
+
+
+def sample_tool(city: Literal['nyc', 'sf']):
+    """Sample tool for benchmark testing."""
+    return 'cloudy' if city == 'nyc' else 'sunny'
+
+
+def run_benchmark(iterations: int = 100) -> List[ParamResult]:
+    """Run parameter impact benchmark."""
+    from praisonaiagents import Agent
+    
+    results = []
+    
+    print('=' * 70)
+    print('PraisonAI Agents - Parameter Impact Benchmark')
+    print('=' * 70)
+    print(f'\nIterations: {iterations}')
+    print('Measuring incremental cost of each Agent parameter\n')
+    
+    # Baseline: Minimal agent
+    print("Testing baseline (minimal agent)...")
+    baseline_stats = measure_instantiation(
+        lambda: Agent(name='Test', output='silent'),
+        iterations
+    )
+    baseline_result = ParamResult(
+        param_name='BASELINE',
+        param_value='Agent(name="Test", output="silent")',
+        avg_time_us=baseline_stats['avg_time'],
+        min_time_us=baseline_stats['min_time'],
+        max_time_us=baseline_stats['max_time'],
+        std_dev_us=baseline_stats['std_dev'],
+        avg_memory_kb=baseline_stats['avg_memory'],
+    )
+    results.append(baseline_result)
+    print(f"  Baseline: {baseline_stats['avg_time']:.2f} μs, {baseline_stats['avg_memory']:.2f} KB")
+    
+    # Define parameters to test
+    # Format: (param_name, param_value, description)
+    params_to_test = [
+        # Core identity
+        ('instructions', 'Be helpful and concise.', 'instructions="..."'),
+        ('role', 'Assistant', 'role="Assistant"'),
+        ('goal', 'Help users', 'goal="Help users"'),
+        ('backstory', 'I am an AI assistant.', 'backstory="..."'),
+        
+        # LLM configuration
+        ('llm', 'gpt-4o-mini', 'llm="gpt-4o-mini"'),
+        ('llm', 'openai/gpt-4o-mini', 'llm="openai/gpt-4o-mini" (LiteLLM)'),
+        
+        # Tools
+        ('tools', [sample_tool], 'tools=[sample_tool]'),
+        
+        # Features (bool flags)
+        ('context', True, 'context=True'),
+        ('context', False, 'context=False'),
+        ('planning', True, 'planning=True'),
+        ('reflection', True, 'reflection=True'),
+        ('memory', True, 'memory=True'),
+        
+        # Output modes
+        ('output', 'verbose', 'output="verbose"'),
+        ('output', 'actions', 'output="actions"'),
+        ('output', 'stream', 'output="stream"'),
+        
+        # Execution config
+        ('execution', 'fast', 'execution="fast"'),
+        ('execution', 'thorough', 'execution="thorough"'),
+        
+        # Caching
+        ('caching', True, 'caching=True'),
+        ('caching', False, 'caching=False'),
+    ]
+    
+    # Test each parameter
+    for param_name, param_value, description in params_to_test:
+        print(f"Testing {description}...")
+        
+        try:
+            # Build kwargs
+            kwargs = {'name': 'Test', 'output': 'silent'}
+            kwargs[param_name] = param_value
+            
+            # Special case: if testing output param, don't override with silent
+            if param_name == 'output':
+                kwargs = {'name': 'Test'}
+                kwargs[param_name] = param_value
+            
+            stats = measure_instantiation(
+                lambda k=kwargs: Agent(**k),
+                iterations
+            )
+            
+            result = ParamResult(
+                param_name=param_name,
+                param_value=description,
+                avg_time_us=stats['avg_time'],
+                min_time_us=stats['min_time'],
+                max_time_us=stats['max_time'],
+                std_dev_us=stats['std_dev'],
+                avg_memory_kb=stats['avg_memory'],
+                delta_time_us=stats['avg_time'] - baseline_stats['avg_time'],
+                delta_memory_kb=stats['avg_memory'] - baseline_stats['avg_memory'],
+            )
+            results.append(result)
+            
+            delta_sign = '+' if result.delta_time_us >= 0 else ''
+            print(f"  {stats['avg_time']:.2f} μs ({delta_sign}{result.delta_time_us:.2f} μs from baseline)")
+            
+        except Exception as e:
+            print(f"  SKIPPED: {e}")
+    
+    return results
+
+
+def print_results(results: List[ParamResult]):
+    """Print results sorted by performance impact."""
+    print('\n' + '=' * 70)
+    print('RESULTS - Sorted by Time Impact (highest cost first)')
+    print('=' * 70)
+    
+    # Sort by delta time (excluding baseline)
+    sorted_results = sorted(
+        [r for r in results if r.param_name != 'BASELINE'],
+        key=lambda x: x.delta_time_us,
+        reverse=True
+    )
+    
+    # Get baseline
+    baseline = next((r for r in results if r.param_name == 'BASELINE'), None)
+    
+    if baseline:
+        print(f"\nBaseline: {baseline.avg_time_us:.2f} μs, {baseline.avg_memory_kb:.2f} KB")
+    
+    print(f"\n{'Parameter':<35} {'Avg (μs)':<12} {'Delta (μs)':<12} {'Memory (KB)':<12} {'Impact':<10}")
+    print('-' * 85)
+    
+    for r in sorted_results:
+        # Calculate impact level
+        if r.delta_time_us > 1000:
+            impact = '🔴 HIGH'
+        elif r.delta_time_us > 100:
+            impact = '🟡 MEDIUM'
+        elif r.delta_time_us > 10:
+            impact = '🟢 LOW'
+        else:
+            impact = '⚪ MINIMAL'
+        
+        delta_str = f"+{r.delta_time_us:.2f}" if r.delta_time_us >= 0 else f"{r.delta_time_us:.2f}"
+        print(f"{r.param_value:<35} {r.avg_time_us:<12.2f} {delta_str:<12} {r.avg_memory_kb:<12.2f} {impact:<10}")
+    
+    # Summary
+    print('\n' + '=' * 70)
+    print('SUMMARY')
+    print('=' * 70)
+    
+    high_impact = [r for r in sorted_results if r.delta_time_us > 1000]
+    medium_impact = [r for r in sorted_results if 100 < r.delta_time_us <= 1000]
+    low_impact = [r for r in sorted_results if 10 < r.delta_time_us <= 100]
+    
+    print(f"\nHigh impact (>1ms): {len(high_impact)} parameters")
+    for r in high_impact:
+        print(f"  - {r.param_value}: +{r.delta_time_us:.2f} μs")
+    
+    print(f"\nMedium impact (100μs-1ms): {len(medium_impact)} parameters")
+    for r in medium_impact:
+        print(f"  - {r.param_value}: +{r.delta_time_us:.2f} μs")
+    
+    print(f"\nLow impact (10-100μs): {len(low_impact)} parameters")
+    
+    print('\n' + '=' * 70)
+
+
+def save_results(results: List[ParamResult], filename: str = 'PARAM_IMPACT_RESULTS.md'):
+    """Save results to markdown file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), filename)
+    
+    # Sort by delta time
+    sorted_results = sorted(
+        [r for r in results if r.param_name != 'BASELINE'],
+        key=lambda x: x.delta_time_us,
+        reverse=True
+    )
+    baseline = next((r for r in results if r.param_name == 'BASELINE'), None)
+    
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Parameter Impact Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n\n')
+        
+        if baseline:
+            f.write(f'**Baseline:** {baseline.avg_time_us:.2f} μs, {baseline.avg_memory_kb:.2f} KB\n\n')
+        
+        f.write('## Results (Sorted by Impact)\n\n')
+        f.write('| Parameter | Avg Time (μs) | Delta (μs) | Memory (KB) | Impact |\n')
+        f.write('|-----------|---------------|------------|-------------|--------|\n')
+        
+        for r in sorted_results:
+            if r.delta_time_us > 1000:
+                impact = '🔴 HIGH'
+            elif r.delta_time_us > 100:
+                impact = '🟡 MEDIUM'
+            elif r.delta_time_us > 10:
+                impact = '🟢 LOW'
+            else:
+                impact = '⚪ MINIMAL'
+            
+            delta_str = f"+{r.delta_time_us:.2f}" if r.delta_time_us >= 0 else f"{r.delta_time_us:.2f}"
+            f.write(f'| {r.param_value} | {r.avg_time_us:.2f} | {delta_str} | {r.avg_memory_kb:.2f} | {impact} |\n')
+        
+        f.write('\n## Recommendations\n\n')
+        
+        high_impact = [r for r in sorted_results if r.delta_time_us > 1000]
+        if high_impact:
+            f.write('### High Impact Parameters (>1ms)\n\n')
+            f.write('These parameters add significant overhead and should be used carefully:\n\n')
+            for r in high_impact:
+                f.write(f'- **{r.param_value}**: +{r.delta_time_us:.2f} μs\n')
+            f.write('\n')
+        
+        f.write('### Best Practices\n\n')
+        f.write('1. Use `output="silent"` for production workloads\n')
+        f.write('2. Only enable `context=True` when needed for long conversations\n')
+        f.write('3. Use `llm="gpt-4o-mini"` (OpenAI SDK) for fastest instantiation\n')
+        f.write('4. Avoid `memory=True` unless persistent memory is required\n')
+        
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/param_impact_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    return filepath
+
+
+def main():
+    parser = argparse.ArgumentParser(description='PraisonAI Parameter Impact Benchmark')
+    parser.add_argument('--iterations', type=int, default=100, help='Number of iterations per test')
+    parser.add_argument('--save', action='store_true', help='Save results to file')
+    args = parser.parse_args()
+    
+    results = run_benchmark(iterations=args.iterations)
+    print_results(results)
+    
+    if args.save:
+        save_results(results)
+    else:
+        print('\nResults not saved (use --save flag to save results to file)')
+
+
+if __name__ == '__main__':
+    main()
Author	SHA1	Message	Date
Mervin Praison	a14ca673da	Release v3.12.2	2026-01-30 10:24:14 +00:00
github-actions[bot]	02d9d1e04f	docs: auto-update api.md [skip ci]	2026-01-30 08:31:24 +00:00
Mervin Praison	d3ee549ccc	Release v3.12.1	2026-01-30 08:31:09 +00:00
github-actions[bot]	63fbd04af3	docs: auto-update api.md [skip ci]	2026-01-30 08:00:39 +00:00
Mervin Praison	51f95ad904	Release v3.12.0	2026-01-30 08:00:22 +00:00
Mervin Praison	44b800df0e	Release v3.11.14	2026-01-30 05:27:32 +00:00
Mervin Praison	6e3a99b8b6	Release v3.11.13	2026-01-29 20:52:07 +00:00
Mervin Praison	b7d53b8f11	Release v3.11.12	2026-01-29 18:23:32 +00:00
Mervin Praison	643fac5762	Release v3.11.11	2026-01-29 18:07:10 +00:00
Mervin Praison	92b71cbc8f	Release v3.11.10	2026-01-29 17:59:29 +00:00
Mervin Praison	d7555ba1b2	Release v3.11.9	2026-01-29 17:53:32 +00:00
github-actions[bot]	22dd13ec66	docs: auto-update api.md [skip ci]	2026-01-29 17:40:47 +00:00
Mervin Praison	ba40e818e4	Release v3.11.8	2026-01-29 17:40:31 +00:00
Mervin Praison	12f829321c	update	2026-01-29 16:39:37 +00:00
Mervin Praison	149ed5bd94	refactor(docker): move bot services to dedicated docker/bots/ folder - Create docker/bots/ with own Dockerfile, docker-compose.yml, README - Remove bot services from main docker-compose.yml - Add .env.template with bot tokens - Add README with setup instructions for Slack/Discord/Telegram	2026-01-29 16:16:31 +00:00
Mervin Praison	15f2937dd5	feat(docker): add bot Dockerfile and services - Add Dockerfile.bot for Slack/Discord/Telegram bots - Add slack-bot, discord-bot, telegram-bot services to docker-compose - Add bot tokens to .env.template - Secrets passed at runtime via environment variables	2026-01-29 16:15:23 +00:00
Mervin Praison	d28199a18d	feat(bots): fix asyncio error and add thread configuration - Fix asyncio.run() error by using run_in_executor() for sync agent.chat() - Add reply_in_thread config option (default: False for inline replies) - Add thread_threshold for auto-threading long responses (default: 500 chars) - Add INFO logging for message received/sent flow	2026-01-29 16:11:21 +00:00
Mervin Praison	0d3d6bb852	Release v3.11.4	2026-01-29 15:18:30 +00:00
Mervin Praison	5f93f83c9f	fix: register bot/gateway/sandbox commands in CLI - Add 'bot', 'gateway', 'sandbox', 'wizard', 'migrate', 'security', 'persistence' to LEGACY_COMMANDS in legacy.py - Add same commands to special_commands list in main.py:797 (argparse fix) - Fix handle_bot_command to parse list args from main.py - 'praisonai bot slack --token $TOKEN' now works correctly	2026-01-29 14:23:40 +00:00
Mervin Praison	c9786fbd1e	Release v3.11.3	2026-01-29 14:17:18 +00:00
github-actions[bot]	95e8e38998	docs: auto-update api.md [skip ci]	2026-01-29 13:45:28 +00:00
Mervin Praison	73f8961e61	Release v3.11.2	2026-01-29 13:45:08 +00:00
github-actions[bot]	4caf10a982	docs: auto-update api.md [skip ci]	2026-01-29 12:31:08 +00:00
Mervin Praison	fb42a1010a	Release v3.11.1	2026-01-29 12:30:51 +00:00
github-actions[bot]	fe60dd40af	docs: auto-update api.md [skip ci]	2026-01-29 10:45:19 +00:00
Mervin Praison	7f37d754a7	Release v3.11.0	2026-01-29 10:45:00 +00:00
github-actions[bot]	26f60fb056	docs: auto-update api.md [skip ci]	2026-01-28 13:20:05 +00:00
Mervin Praison	0f0b640184	Release v3.10.27	2026-01-28 13:19:48 +00:00
Mervin Praison	d857dfc6b7	Release v3.10.26	2026-01-27 15:07:21 +00:00
github-actions[bot]	0135a9e09f	docs: auto-update api.md [skip ci]	2026-01-27 05:52:59 +00:00
Mervin Praison	847b5e6372	Release v3.10.25	2026-01-27 05:52:43 +00:00
github-actions[bot]	05a7265c4e	docs: auto-update api.md [skip ci]	2026-01-26 18:39:42 +00:00
Mervin Praison	de1734c29a	Release v3.10.24	2026-01-26 18:39:28 +00:00
github-actions[bot]	f0e91b11ae	docs: auto-update api.md [skip ci]	2026-01-26 17:47:05 +00:00
Mervin Praison	6e1a9143e2	Release v3.10.23	2026-01-26 17:46:49 +00:00
github-actions[bot]	10d76d3a85	docs: auto-update api.md [skip ci]	2026-01-26 17:06:34 +00:00
Mervin Praison	a38a9c06c6	Release v3.10.22	2026-01-26 17:06:19 +00:00
github-actions[bot]	9c90416ab5	docs: auto-update api.md [skip ci]	2026-01-26 08:08:44 +00:00
Mervin Praison	efa5247344	Release v3.10.21	2026-01-26 08:08:18 +00:00
Mervin Praison	720213d82d	Merge pull request #1100 from MervinPraison/pr-1099-fix Pr 1099 fix	2026-01-25 00:47:27 +00:00
Loganaden Velvindron	f6af16ef5e	Fix range check	2026-01-25 00:46:37 +00:00
Loganaden Velvindron	8439b98ec2	Fix CVE-2026-22218	2026-01-25 00:45:51 +00:00
Loganaden Velvindron	92271fc118	Fix CVE-2026-22218 Allow building with chainlit 2.9.4 to fix CVE-2026-22218	2026-01-25 00:45:32 +00:00
Mervin Praison	1b43dc6a4b	Update naming convention guide with list_X pattern and clarify decorator usage	2026-01-25 00:43:02 +00:00
Mervin Praison	929cefa55e	Release v3.10.20	2026-01-25 00:36:03 +00:00
Mervin Praison	225843e39b	Release v3.10.19	2026-01-25 00:25:39 +00:00
Mervin Praison	77913183a9	Release v3.10.18	2026-01-24 14:33:15 +00:00
Mervin Praison	e5b5d747f4	Release v3.10.17	2026-01-24 09:26:02 +00:00
Mervin Praison	8cb779c51c	Release v3.10.16	2026-01-24 07:32:55 +00:00
github-actions[bot]	020ca46c90	docs: auto-update api.md [skip ci]	2026-01-24 07:01:25 +00:00
Mervin Praison	557e243eed	Release v3.10.15	2026-01-24 07:01:13 +00:00
Mervin Praison	0628204fce	Update README.md	2026-01-23 14:46:55 +00:00
Mervin Praison	2a11bf5221	Release v3.10.14	2026-01-23 12:58:40 +00:00
github-actions[bot]	ecc2182d24	docs: auto-update api.md [skip ci]	2026-01-23 12:16:33 +00:00
Mervin Praison	c6b91b2d57	Release v3.10.13	2026-01-23 12:16:16 +00:00
github-actions[bot]	a5ed17945f	docs: auto-update api.md [skip ci]	2026-01-23 10:33:02 +00:00
Mervin Praison	ff3ca3052d	Release v3.10.12	2026-01-23 10:32:48 +00:00
github-actions[bot]	6f1f4a5363	docs: auto-update api.md [skip ci]	2026-01-23 07:32:54 +00:00
Mervin Praison	dd9dfa5970	Release v3.10.11	2026-01-23 07:32:37 +00:00
Mervin Praison	5f4fc8fa2f	Release v3.10.10	2026-01-23 05:18:03 +00:00
github-actions[bot]	dd9dd5d5d9	docs: auto-update api.md [skip ci]	2026-01-23 03:47:00 +00:00
Mervin Praison	d2c629b82c	Release v3.10.9	2026-01-23 03:46:46 +00:00
Mervin Praison	609ac5f7a6	Release v3.10.8	2026-01-22 14:13:38 +00:00
Mervin Praison	75c72e909e	Release v3.10.7	2026-01-22 13:47:01 +00:00
Mervin Praison	9492ff8de1	Release v3.10.6	2026-01-22 11:24:49 +00:00
Mervin Praison	a0a3aa1a53	Release v3.10.5	2026-01-22 08:30:15 +00:00
Mervin Praison	6a20001551	Refactor port availability test to use `socket.socket` and relax import and profiling time assertions.	2026-01-22 07:49:51 +00:00
Mervin Praison	577295c147	Release v3.10.4	2026-01-22 07:06:28 +00:00
github-actions[bot]	06f64a551c	docs: auto-update api.md [skip ci]	2026-01-22 05:16:01 +00:00
Mervin Praison	928b824180	Release v3.10.3	2026-01-22 05:15:48 +00:00
github-actions[bot]	1631973256	docs: auto-update api.md [skip ci]	2026-01-21 17:30:54 +00:00
Mervin Praison	a9d7f6fd76	Release v3.10.2	2026-01-21 17:30:30 +00:00
Mervin Praison	cc5360e60e	Release v3.10.1	2026-01-21 15:01:51 +00:00
Mervin Praison	863dd9bc34	Release v3.10.0	2026-01-21 13:11:42 +00:00
Mervin Praison	8c39769971	Release v3.9.35	2026-01-21 05:41:54 +00:00
Mervin Praison	93904f8530	Release v3.9.34	2026-01-20 20:40:03 +00:00
Mervin Praison	ffc3775446	Release v3.9.33	2026-01-20 19:01:01 +00:00
Mervin Praison	86e76b7a3e	Release v3.9.32	2026-01-20 14:56:13 +00:00
Mervin Praison	b18d6007c2	Release v3.9.31	2026-01-20 12:43:18 +00:00
github-actions[bot]	c656af3166	docs: auto-update api.md [skip ci]	2026-01-20 12:20:08 +00:00
Mervin Praison	3c2fff05dd	Release v3.9.30	2026-01-20 12:19:52 +00:00
github-actions[bot]	092097faa6	docs: auto-update api.md [skip ci]	2026-01-20 08:17:03 +00:00
Mervin Praison	068ddecb91	Release v3.9.29	2026-01-20 08:16:43 +00:00
github-actions[bot]	444d14cb54	docs: auto-update api.md [skip ci]	2026-01-20 06:59:39 +00:00
Mervin Praison	090316dce3	Release v3.9.28	2026-01-20 06:59:26 +00:00
Mervin Praison	a40cddd402	Release v3.9.27	2026-01-19 19:44:12 +00:00
Mervin Praison	62472a2342	Release v3.9.26	2026-01-19 18:29:39 +00:00
Mervin Praison	35186a0e66	Release v3.9.25	2026-01-19 17:11:41 +00:00
Mervin Praison	d08d98ca12	Release v3.9.24	2026-01-19 14:44:13 +00:00
Mervin Praison	2c9e8b46cb	Release v3.9.23	2026-01-19 09:34:36 +00:00
Mervin Praison	ce3b25c085	Release v3.9.22	2026-01-18 22:56:19 +00:00
github-actions[bot]	a928467188	docs: auto-update api.md [skip ci]	2026-01-18 22:55:41 +00:00
Mervin Praison	8285afe789	Release v3.9.21	2026-01-18 22:55:28 +00:00
Mervin Praison	b529110246	Release v3.9.20	2026-01-18 22:46:06 +00:00
Mervin Praison	2a004bc382	Release v3.9.19	2026-01-18 22:18:17 +00:00
Mervin Praison	b3fecacb2b	Release v3.9.18	2026-01-18 21:18:40 +00:00
Mervin Praison	6924077e36	Release v3.9.17	2026-01-18 20:22:41 +00:00
Mervin Praison	63101d7323	Release v3.9.16	2026-01-18 00:06:30 +00:00
Mervin Praison	e9540b2a92	Release v3.9.15	2026-01-18 00:03:09 +00:00
Mervin Praison	75c1c62cec	Release v3.9.14	2026-01-17 23:47:18 +00:00
Mervin Praison	de4f251a02	Release v3.9.13	2026-01-17 23:45:53 +00:00
github-actions[bot]	d4858b4d5c	docs: auto-update api.md [skip ci]	2026-01-17 23:31:46 +00:00
Mervin Praison	03ca92a7d5	Release v3.9.12	2026-01-17 23:31:32 +00:00
Mervin Praison	cca65dcdab	Release v3.9.11	2026-01-17 22:02:52 +00:00
github-actions[bot]	93844d9509	docs: auto-update api.md [skip ci]	2026-01-17 21:12:18 +00:00
Mervin Praison	0849db227d	Release v3.9.10	2026-01-17 21:12:06 +00:00
github-actions[bot]	914d34e57b	docs: auto-update api.md [skip ci]	2026-01-17 16:42:13 +00:00
Mervin Praison	be66a5e4e1	Release v3.9.9	2026-01-17 16:42:00 +00:00
github-actions[bot]	20a19f7958	docs: auto-update api.md [skip ci]	2026-01-17 07:49:09 +00:00
Mervin Praison	4128a67e10	Release v3.9.8	2026-01-17 07:48:54 +00:00
Mervin Praison	9d29c796c7	Release v3.9.7	2026-01-16 12:05:38 +00:00
Mervin Praison	f058ce018f	Release v3.9.6	2026-01-16 09:18:27 +00:00
Mervin Praison	09671d4bd3	Release v3.9.5	2026-01-16 08:00:39 +00:00