Release v2.8.4

- Update package.json version from 1.3.6 to 1.4.0
- Update FEATURE_PARITY_TRACKER.json to v1.3.0 (Phase 5 Complete)
- Add AI SDK wrapper features: generateText, streamText, generateObject, streamObject, generateImage, embed, embedMany
- Add server adapters for http, express, hono, fastify, nest
- Add Next.js integration with createRouteHandler and createPagesHandler
- Add MCP client tools: createMCP, getMCPClient, mcpToolsToAITools

.github/workflows/benchmark.yml

@@ -1,145 +0,0 @@
-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!"

.github/workflows/test-comprehensive.yml

@@ -54,7 +54,7 @@ jobs:
         cd src/praisonai
         uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
         uv pip install --system duckduckgo_search
-        uv pip install --system pytest pytest-asyncio pytest-cov pytest-benchmark pytest-timeout
+        uv pip install --system pytest pytest-asyncio pytest-cov pytest-benchmark
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
@@ -75,28 +75,28 @@ jobs:
         
         case $TEST_TYPE in
           "unit")
-            cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch || echo "Some unit tests failed"
+            cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
             ;;
           "integration")
-            cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch || echo "Some integration tests failed"
+            cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
             ;;
           "fast")
-            cd src/praisonai && python tests/test_runner.py --pattern fast || echo "Some fast tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern fast
             ;;
           "performance")
-            cd src/praisonai && python tests/test_runner.py --pattern "performance" || echo "Some performance tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern "performance"
             ;;
           "frameworks")
-            cd src/praisonai && python tests/test_runner.py --pattern frameworks || echo "Some framework tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern frameworks
             ;;
           "autogen")
-            cd src/praisonai && python tests/test_runner.py --pattern autogen || echo "Some autogen tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern autogen
             ;;
           "crewai")
-            cd src/praisonai && python tests/test_runner.py --pattern crewai || echo "Some crewai tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern crewai
             ;;
           "all"|*)
-            cd src/praisonai && python tests/test_runner.py --pattern all || echo "Some tests failed"
+            cd src/praisonai && python tests/test_runner.py --pattern all
             ;;
         esac
 

.github/workflows/test-frameworks.yml

@@ -50,7 +50,7 @@ jobs:
         cd src/praisonai
         uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
         uv pip install --system duckduckgo_search
-        uv pip install --system pytest pytest-asyncio pytest-cov pytest-timeout
+        uv pip install --system pytest pytest-asyncio pytest-cov
 
     - name: Set environment variables
       run: |

.github/workflows/test-optimized.yml

@@ -1,530 +0,0 @@
-name: Optimized Test Suite
-
-on: 
-  push:
-    branches: [ main, develop ]
-  pull_request:
-    branches: [ main, develop ]
-  schedule:
-    # Nightly extended tests at 3 AM UTC
-    - cron: '0 3 * * *'
-  workflow_dispatch:
-    inputs:
-      tier:
-        description: 'Test tier to run'
-        required: true
-        default: 'main'
-        type: choice
-        options:
-          - smoke
-          - main
-          - extended
-          - nightly
-
-env:
-  PYTHONPATH: ${{ github.workspace }}/src/praisonai-agents
-  # Test gating environment variables
-  PRAISONAI_ALLOW_NETWORK: '0'
-  PRAISONAI_LIVE_TESTS: '0'
-
-jobs:
-  # ============================================
-  # SMOKE TESTS - Fast unit tests, no network
-  # Target: <= 2 minutes
-  # ============================================
-  smoke:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python 3.11
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Cache pip packages
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-smoke-${{ hashFiles('**/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-smoke-
-          ${{ runner.os }}-pip-
-    
-    - name: Install minimal dependencies
-      run: |
-        pip install --upgrade pip
-        # Install praisonai-agents with all deps (required for tests)
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[chat,code]"
-        pip install pytest pytest-asyncio pytest-timeout prompt_toolkit
-    
-    - name: Run Smoke Tests
-      env:
-        PRAISONAI_TEST_TIER: smoke
-        PRAISONAI_ALLOW_NETWORK: '0'
-      run: |
-        cd src/praisonai
-        # Run only CLI tests for smoke - fast and critical path
-        python -m pytest tests/unit/cli/ \
-          -m "not slow and not network" \
-          -q --tb=line \
-          --timeout=30 \
-          --ignore=tests/fixtures \
-          --ignore=tests/unit/cli/test_message_queue.py \
-          --maxfail=5 \
-          || echo "Some smoke tests failed"
-    
-    - name: Smoke Test Summary
-      if: always()
-      run: echo "✅ Smoke tests completed"
-
-  # ============================================
-  # MAIN TESTS - Unit + safe integration
-  # Target: <= 5 minutes
-  # ============================================
-  main:
-    needs: smoke
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    strategy:
-      matrix:
-        python-version: ['3.11']
-    
-    steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-    
-    - name: Cache pip packages
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-main-${{ hashFiles('**/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-main-
-          ${{ runner.os }}-pip-
-    
-    - name: Install dependencies
-      run: |
-        pip install --upgrade pip
-        # Install praisonai-agents with all deps (required for tests)
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[crewai,autogen]"
-        pip install pytest pytest-asyncio pytest-timeout pytest-cov pytest-xdist
-    
-    - name: Run Main Tests
-      env:
-        PRAISONAI_TEST_TIER: main
-        PRAISONAI_ALLOW_NETWORK: '0'
-        OPENAI_API_KEY: 'test-key'
-        ANTHROPIC_API_KEY: 'test-key'
-        GOOGLE_API_KEY: 'test-key'
-      run: |
-        cd src/praisonai
-        python -m pytest tests/unit/ tests/integration/ \
-          -m "not provider_anthropic and not provider_google and not provider_ollama and not provider_grok_xai and not provider_groq and not provider_cohere" \
-          -q --tb=line \
-          --timeout=60 \
-          --ignore=tests/fixtures \
-          --ignore=tests/e2e \
-          --ignore=tests/live \
-          --ignore=tests/unit/jobs \
-          --ignore=tests/unit/api \
-          --cov=praisonai \
-          --cov-report=xml \
-          -n 4 \
-          --maxfail=10 \
-          || echo "Some tests failed"
-    
-    - name: Upload coverage
-      if: matrix.python-version == '3.11'
-      uses: codecov/codecov-action@v5
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        file: src/praisonai/coverage.xml
-        flags: main-tests
-        fail_ci_if_error: false
-
-  # ============================================
-  # OPENAI LIVE TESTS - Real OpenAI API calls
-  # Only runs if OPENAI_API_KEY secret is set
-  # Safe for forks (skips gracefully if no key)
-  # ============================================
-  openai-live:
-    needs: smoke
-    runs-on: ubuntu-latest
-    timeout-minutes: 8
-    # This job always runs but steps are conditional on secret availability
-    
-    steps:
-    - name: Check if OpenAI key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.OPENAI_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ OPENAI_API_KEY not set - skipping live tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Cache pip packages
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-openai-${{ hashFiles('**/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[openai]"
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run OpenAI Live Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_TEST_TIER: extended
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'openai'
-        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-        OPENAI_MODEL_NAME: ${{ secrets.OPENAI_MODEL_NAME || 'gpt-4o-mini' }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_openai or real" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "Some OpenAI tests failed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ OpenAI live tests skipped (no API key available - this is expected for forks)"
-
-  # ============================================
-  # EXTENDED PROVIDER TESTS - Nightly only
-  # Runs all provider-specific tests
-  # ============================================
-  extended-anthropic:
-    if: github.event_name == 'schedule' || github.event.inputs.tier == 'extended' || github.event.inputs.tier == 'nightly'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-    - name: Check if Anthropic key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ ANTHROPIC_API_KEY not set - skipping tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[anthropic]"
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run Anthropic Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'anthropic'
-        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_anthropic" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "Anthropic tests completed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ Anthropic tests skipped (no API key available)"
-
-  extended-google:
-    if: github.event_name == 'schedule' || github.event.inputs.tier == 'extended' || github.event.inputs.tier == 'nightly'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-    - name: Check if Google key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.GOOGLE_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ GOOGLE_API_KEY not set - skipping tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[google]"
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run Google/Gemini Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'google'
-        GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_google" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "Google tests completed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ Google tests skipped (no API key available)"
-
-  extended-groq:
-    if: github.event_name == 'schedule' || github.event.inputs.tier == 'extended' || github.event.inputs.tier == 'nightly'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-    - name: Check if Groq key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.GROQ_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ GROQ_API_KEY not set - skipping tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e .
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run Groq Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'groq'
-        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_groq" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "Groq tests completed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ Groq tests skipped (no API key available)"
-
-  extended-xai:
-    if: github.event_name == 'schedule' || github.event.inputs.tier == 'extended' || github.event.inputs.tier == 'nightly'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-    - name: Check if xAI key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.XAI_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ XAI_API_KEY not set - skipping tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e .
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run xAI/Grok Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'grok_xai'
-        XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_grok_xai" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "xAI tests completed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ xAI tests skipped (no API key available)"
-
-  extended-cohere:
-    if: github.event_name == 'schedule' || github.event.inputs.tier == 'extended' || github.event.inputs.tier == 'nightly'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    
-    steps:
-    - name: Check if Cohere key is available
-      id: check-key
-      run: |
-        if [ -n "${{ secrets.COHERE_API_KEY }}" ]; then
-          echo "has_key=true" >> $GITHUB_OUTPUT
-        else
-          echo "has_key=false" >> $GITHUB_OUTPUT
-          echo "⚠️ COHERE_API_KEY not set - skipping tests"
-        fi
-    
-    - uses: actions/checkout@v4
-      if: steps.check-key.outputs.has_key == 'true'
-    
-    - name: Set up Python 3.11
-      if: steps.check-key.outputs.has_key == 'true'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-    
-    - name: Install dependencies
-      if: steps.check-key.outputs.has_key == 'true'
-      run: |
-        pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install -e ".[all]"
-        cd ../praisonai
-        pip install -e ".[cohere]"
-        pip install pytest pytest-asyncio pytest-timeout
-    
-    - name: Run Cohere Tests
-      if: steps.check-key.outputs.has_key == 'true'
-      env:
-        PRAISONAI_ALLOW_NETWORK: '1'
-        PRAISONAI_LIVE_TESTS: '1'
-        PRAISONAI_TEST_PROVIDERS: 'cohere'
-        COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
-      run: |
-        cd src/praisonai
-        python -m pytest tests/ \
-          -m "provider_cohere" \
-          -v --tb=short \
-          --timeout=120 \
-          --ignore=tests/fixtures \
-          || echo "Cohere tests completed"
-    
-    - name: Skip notice
-      if: steps.check-key.outputs.has_key == 'false'
-      run: echo "✅ Cohere tests skipped (no API key available)"
-
-  # ============================================
-  # TEST SUMMARY
-  # ============================================
-  test-summary:
-    needs: [smoke, main]
-    if: always()
-    runs-on: ubuntu-latest
-    
-    steps:
-    - name: Test Summary
-      run: |
-        echo "# 📊 Test Suite Summary" >> $GITHUB_STEP_SUMMARY
-        echo "" >> $GITHUB_STEP_SUMMARY
-        echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY
-        echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY
-        echo "| Smoke | ${{ needs.smoke.result }} |" >> $GITHUB_STEP_SUMMARY
-        echo "| Main | ${{ needs.main.result }} |" >> $GITHUB_STEP_SUMMARY
-        echo "" >> $GITHUB_STEP_SUMMARY
-        echo "## Test Tiers" >> $GITHUB_STEP_SUMMARY
-        echo "- **smoke**: Fast unit tests, no network (≤2 min)" >> $GITHUB_STEP_SUMMARY
-        echo "- **main**: Unit + integration, no network (≤5 min)" >> $GITHUB_STEP_SUMMARY
-        echo "- **openai-live**: OpenAI API tests (when key available)" >> $GITHUB_STEP_SUMMARY
-        echo "- **extended-***: Provider-specific tests (nightly)" >> $GITHUB_STEP_SUMMARY

.github/workflows/test-windows.yml

@@ -1,204 +0,0 @@
-name: Windows Tests
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main, develop]
-  workflow_dispatch:
-
-jobs:
-  test-windows:
-    runs-on: windows-latest
-    timeout-minutes: 5
-    env:
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-      OPENAI_MODEL_NAME: gpt-4o-mini
-    
-    steps:
-    - uses: actions/checkout@v4
-    
-    - name: Set up Python 3.11
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3.11"
-    
-    - name: Install praisonaiagents
-      run: |
-        python -m pip install --upgrade pip
-        cd src/praisonai-agents
-        pip install .
-      shell: bash
-    
-    - name: Install praisonai wrapper
-      run: |
-        cd src/praisonai
-        pip install .[dev]
-      shell: bash
-
-    # ==================== CORE IMPORTS ====================
-    - name: Test core imports
-      run: |
-        python -c "from praisonaiagents import Agent, Agents, Workflow; print('Core imports OK')"
-        python -c "from praisonaiagents import tool, Tools; print('Tool imports OK')"
-        python -c "from praisonaiagents import Task, WorkflowStep; print('Task/Step imports OK')"
-
-    # ==================== AGENT FEATURES ====================
-    - name: Test Agent instantiation
-      run: |
-        python -c "
-        from praisonaiagents import Agent
-        a = Agent(name='Test', instructions='You are helpful')
-        print('Agent created:', a.name)
-        a2 = Agent(name='ToolAgent', instructions='Use tools', tools=[])
-        print('Agent with tools:', a2.name)
-        "
-
-    - name: Test Agents orchestration
-      run: |
-        python -c "
-        from praisonaiagents import Agent, Agents, Task
-        a1 = Agent(name='Agent1', instructions='First agent')
-        a2 = Agent(name='Agent2', instructions='Second agent')
-        t = Task(description='Do something', agent=a1)
-        agents = Agents(agents=[a1, a2], tasks=[t])
-        print('Agents:', len(agents.agents), 'Tasks:', len(agents.tasks))
-        "
-
-    # ==================== WORKFLOW FEATURES ====================
-    - name: Test Workflow and WorkflowStep
-      run: |
-        python -c "
-        from praisonaiagents import Workflow, WorkflowStep
-        from praisonaiagents.workflows import WorkflowOutputConfig
-        
-        w = Workflow(name='test')
-        s1 = WorkflowStep(name='step1')
-        s2 = WorkflowStep(name='step2', context=['step1'])
-        print('Workflow:', w.name)
-        print('Steps:', s1.name, s2.name)
-        
-        cfg = WorkflowOutputConfig(verbose=True, stream=False)
-        w2 = Workflow(name='configured', output=cfg)
-        print('Configured workflow verbose:', w2.verbose)
-        "
-
-    # ==================== MEMORY FEATURES ====================
-    - name: Test Memory classes
-      run: |
-        python -c "
-        from praisonaiagents.memory import FileMemory
-        from praisonaiagents.config import MemoryConfig
-        
-        cfg = MemoryConfig(backend='file', user_id='test_user')
-        print('MemoryConfig backend:', cfg.backend)
-        
-        mem = FileMemory(user_id='test_user', base_path='.praison/test_memory')
-        print('FileMemory user:', mem.user_id)
-        "
-
-    # ==================== TOOL DECORATOR ====================
-    - name: Test tool decorator
-      run: |
-        python -c "
-        from praisonaiagents import tool
-        
-        @tool
-        def my_tool(query: str) -> str:
-            '''A test tool'''
-            return f'Echo: {query}'
-        
-        result = my_tool('hello')
-        print('Tool result:', result)
-        "
-
-    # ==================== CONFIG CLASSES ====================
-    - name: Test config classes
-      run: |
-        python -c "
-        from praisonaiagents.config import OutputConfig, ExecutionConfig, PlanningConfig
-        
-        out_cfg = OutputConfig(verbose=True, stream=True)
-        print('OutputConfig verbose:', out_cfg.verbose)
-        
-        exec_cfg = ExecutionConfig(max_iter=50, max_retry_limit=5)
-        print('ExecutionConfig max_iter:', exec_cfg.max_iter)
-        
-        plan_cfg = PlanningConfig(reasoning=True, auto_approve=False)
-        print('PlanningConfig reasoning:', plan_cfg.reasoning)
-        "
-    # ==================== HANDOFF ====================
-    - name: Test Handoff
-      run: |
-        python -c "
-        from praisonaiagents import Handoff, handoff, Agent
-        
-        a1 = Agent(name='Agent1', instructions='First')
-        a2 = Agent(name='Agent2', instructions='Second')
-        
-        # Using Handoff class directly
-        h = Handoff(agent=a2)
-        print('Handoff tool name:', h.tool_name)
-        
-        # Using handoff function
-        h2 = handoff(a1, tool_name_override='custom_handoff')
-        print('Custom handoff name:', h2.tool_name)
-        "
-
-
-    # ==================== ASYNC FEATURES ====================
-    - name: Test async imports
-      run: |
-        python -c "
-        import asyncio
-        from praisonaiagents import Agent
-        
-        async def test_async():
-            agent = Agent(name='AsyncAgent', instructions='Test')
-            assert hasattr(agent, 'arun'), 'Missing arun'
-            assert hasattr(agent, 'astart'), 'Missing astart'
-            print('Async methods available')
-        
-        asyncio.run(test_async())
-        "
-
-    # ==================== CLI COMMANDS ====================
-    - name: Test CLI help
-      run: praisonai --help
-
-    - name: Test CLI session list
-      run: praisonai session list
-      continue-on-error: true
-
-    - name: Test CLI queue list
-      run: praisonai queue list
-      continue-on-error: true
-
-    # ==================== REAL API TESTS ====================
-    - name: Real API test - Agent run
-      if: env.OPENAI_API_KEY != ''
-      run: |
-        python -c "
-        from praisonaiagents import Agent
-        agent = Agent(name='TestAgent', instructions='Reply with exactly: WINDOWS_OK', llm='gpt-4o-mini')
-        result = agent.run('Say WINDOWS_OK')
-        print('Result:', result)
-        print('Real API test passed')
-        "
-
-    - name: Real API test - Multi-agent
-      if: env.OPENAI_API_KEY != ''
-      run: |
-        python -c "
-        from praisonaiagents import Agent, Agents, Task
-        
-        researcher = Agent(name='Researcher', instructions='You research topics', llm='gpt-4o-mini')
-        writer = Agent(name='Writer', instructions='You write content', llm='gpt-4o-mini')
-        
-        task = Task(description='Say hello world', agent=researcher)
-        
-        agents = Agents(agents=[researcher, writer], tasks=[task])
-        result = agents.start()
-        print('Multi-agent result type:', type(result))
-        print('Multi-agent test passed')
-        "

.github/workflows/update-api-md.yml

@@ -1,57 +0,0 @@
-name: Update API Reference
-
-on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - 'src/praisonai-agents/praisonaiagents/**/*.py'
-      - 'src/praisonai/praisonai/**/*.py'
-      - 'src/praisonai-ts/src/**/*.ts'
-      - '.github/workflows/update-api-md.yml'
-
-permissions:
-  contents: write
-
-jobs:
-  update-api-md:
-    runs-on: ubuntu-latest
-    
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        ref: main
-        persist-credentials: true
-        fetch-depth: 0
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Generate api.md
-      run: |
-        cd $GITHUB_WORKSPACE
-        python3 src/praisonai/scripts/generate_api_md.py
-        
-    - name: Check for changes
-      id: check_changes
-      run: |
-        if git diff --quiet api.md; then
-          echo "changes=false" >> $GITHUB_OUTPUT
-          echo "No changes to api.md"
-        else
-          echo "changes=true" >> $GITHUB_OUTPUT
-          echo "api.md has been updated"
-          git diff api.md | head -50
-        fi
-
-    - name: Commit and push changes
-      if: steps.check_changes.outputs.changes == 'true'
-      uses: stefanzweifel/git-auto-commit-action@v5
-      with:
-        commit_message: "docs: auto-update api.md [skip ci]"
-        file_pattern: 'api.md'
-        commit_user_name: "github-actions[bot]"
-        commit_user_email: "41898282+github-actions[bot]@users.noreply.github.com"
-        commit_author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"

.github/workflows/update-parity-tracker.yml

@@ -1,58 +0,0 @@
-name: Update Feature Parity Tracker
-
-on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - 'src/praisonai-agents/praisonaiagents/**/*.py'
-      - 'src/praisonai-ts/src/**/*.ts'
-      - 'src/praisonai-rust/src/**/*.rs'
-      - '.github/workflows/update-parity-tracker.yml'
-
-permissions:
-  contents: write
-
-jobs:
-  update-parity-tracker:
-    runs-on: ubuntu-latest
-    
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        ref: main
-        persist-credentials: true
-        fetch-depth: 0
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Generate parity trackers
-      run: |
-        cd $GITHUB_WORKSPACE
-        python3 src/praisonai/scripts/generate_parity_tracker.py
-        
-    - name: Check for changes
-      id: check_changes
-      run: |
-        if git diff --quiet src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md src/praisonai-rust/FEATURE_PARITY_TRACKER.json src/praisonai-rust/PARITY.md 2>/dev/null; then
-          echo "changes=false" >> $GITHUB_OUTPUT
-          echo "No changes to parity trackers"
-        else
-          echo "changes=true" >> $GITHUB_OUTPUT
-          echo "Parity trackers have been updated"
-          git diff src/praisonai-ts/FEATURE_PARITY_TRACKER.json | head -50
-        fi
-
-    - name: Commit and push changes
-      if: steps.check_changes.outputs.changes == 'true'
-      uses: stefanzweifel/git-auto-commit-action@v5
-      with:
-        commit_message: "docs: auto-update feature parity trackers [skip ci]"
-        file_pattern: 'src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md src/praisonai-rust/FEATURE_PARITY_TRACKER.json src/praisonai-rust/PARITY.md'
-        commit_user_name: "github-actions[bot]"
-        commit_user_email: "41898282+github-actions[bot]@users.noreply.github.com"
-        commit_author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
-

.gitignore

@@ -20,7 +20,6 @@ watch.sh
 docs.sh
 other
 output
-!src/praisonai/praisonai/cli/output/
 
 .files
 threads.db
@@ -83,12 +82,4 @@ issue_details.json
 # MCP Registry tokens
 .mcpregistry_*
 
-*.log
-.internal
-.praisonai
-
-# Rust / Cargo
-target/
-Cargo.lock
-**/*.rs.bk
-*.pdb
+*.log

README.md

@@ -23,7 +23,7 @@
 
 </div>
 
-PraisonAI is a production-ready Multi-AI Agents framework with self-reflection, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. It provides a low-code solution to streamline the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration.
+PraisonAI is a production-ready Multi-AI Agents framework with self-reflection, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. By integrating PraisonAI Agents, AG2 (Formerly AutoGen), and CrewAI into a low-code solution, it streamlines the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration.
 
 <div align="center">
   <a href="https://docs.praison.ai">
@@ -36,10 +36,10 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 ---
 
 > **Quick Paths:**
-> - 🆕 **New here?** → [Quick Start](#-quick-start) *(1 minute to first agent)*
+> - 🚀 **New here?** → [Quick Start](#-quick-start)
 > - 📦 **Installing?** → [Installation](#-installation)
-> - 🐍 **Python SDK?** → [Python Examples](#-using-python-code)
-> - 🎯 **CLI user?** → [CLI Quick Reference](#cli-quick-reference)
+> - 💻 **Python SDK?** → [Python Examples](#-using-python-code)
+> - 🎯 **CLI user?** → [CLI Reference](#-cli--no-code-interface)
 > - 🔧 **Need config?** → [Configuration](#-configuration--integration)
 > - 🤝 **Contributing?** → [Development](#-development)
 
@@ -47,81 +47,96 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 
 ## 📑 Table of Contents
 
-<details open>
-<summary><strong>Getting Started</strong></summary>
-
+### Getting Started
+- [⚡ Performance](#-performance)
 - [🚀 Quick Start](#-quick-start)
 - [📦 Installation](#-installation)
-- [⚡ Performance](#-performance)
+  - [Python SDK](#python-sdk)
+  - [JavaScript SDK](#javascript-sdk)
+  - [Environment Variables](#environment-variables)
 
-</details>
-
-<details>
-<summary><strong>Python SDK</strong></summary>
+### Core Concepts
+- [✨ Key Features](#-key-features)
+- [🌐 Supported Providers](#-supported-providers)
 
+### Python SDK
 - [📘 Python Examples](#-using-python-code)
-  - [1. Single Agent](#1-single-agent) | [2. Multi Agents](#2-multi-agents) | [3. Planning Mode](#3-agent-with-planning-mode)
-  - [4. Deep Research](#4-deep-research-agent) | [5. Query Rewriter](#5-query-rewriter-agent) | [6. Agent Memory](#6-agent-memory-zero-dependencies)
-  - [7. Rules & Instructions](#7-rules--instructions) | [8. Auto-Generated Memories](#8-auto-generated-memories) | [9. Agentic Workflows](#9-agentic-workflows)
-  - [10. Hooks](#10-hooks) | [11. Shadow Git Checkpoints](#11-shadow-git-checkpoints) | [12. Background Tasks](#12-background-tasks)
-  - [13. Policy Engine](#13-policy-engine) | [14. Thinking Budgets](#14-thinking-budgets) | [15. Output Styles](#15-output-styles)
-  - [16. Context Compaction](#16-context-compaction) | [17. Field Names Reference](#17-field-names-reference-a-i-g-s) | [18. Extended agents.yaml](#18-extended-agentsyaml-with-workflow-patterns)
-  - [19. MCP Protocol](#19-mcp-model-context-protocol) | [20. A2A Protocol](#20-a2a-agent2agent-protocol)
+  - [1. Single Agent](#1-single-agent)
+  - [2. Multi Agents](#2-multi-agents)
+  - [3. Planning Mode](#3-agent-with-planning-mode)
+  - [4. Deep Research](#4-deep-research-agent)
+  - [5. Query Rewriter](#5-query-rewriter-agent)
+  - [6. Agent Memory](#6-agent-memory-zero-dependencies)
+  - [7. Rules & Instructions](#7-rules--instructions)
+  - [8. Auto-Generated Memories](#8-auto-generated-memories)
+  - [9. Agentic Workflows](#9-agentic-workflows)
+  - [10. Hooks](#10-hooks)
+  - [11. Shadow Git Checkpoints](#11-shadow-git-checkpoints)
+  - [12. Background Tasks](#12-background-tasks)
+  - [13. Policy Engine](#13-policy-engine)
+  - [14. Thinking Budgets](#14-thinking-budgets)
+  - [15. Output Styles](#15-output-styles)
+  - [16. Context Compaction](#16-context-compaction)
+  - [17. Field Names Reference](#17-field-names-reference-a-i-g-s)
+  - [18. Extended agents.yaml](#18-extended-agentsyaml-with-workflow-patterns)
+  - [19. MCP Protocol](#19-mcp-model-context-protocol)
+  - [20. A2A Protocol](#20-a2a-agent2agent-protocol)
 - [🛠️ Custom Tools](#️-custom-tools)
 
-</details>
-
-<details>
-<summary><strong>JavaScript SDK</strong></summary>
-
+### JavaScript SDK
 - [💻 JavaScript Examples](#-using-javascript-code)
 
-</details>
+### CLI Reference
+- [🎯 CLI Overview](#-cli--no-code-interface)
+  - [Auto Mode](#auto-mode)
+  - [Interactive Mode](#interactive-mode-cli)
+  - [Deep Research CLI](#deep-research-cli)
+  - [Planning Mode CLI](#planning-mode-cli)
+  - [Memory CLI](#memory-cli)
+  - [Workflow CLI](#workflow-cli)
+  - [Knowledge CLI](#knowledge-cli)
+  - [Session CLI](#session-cli)
+  - [Tools CLI](#tools-cli)
+  - [MCP Config CLI](#mcp-config-cli)
+  - [External Agents CLI](#external-agents-cli)
+- [CLI Features Summary](#cli-features)
 
-<details>
-<summary><strong>CLI Reference</strong></summary>
-
-- [🎯 CLI Overview](#-cli--no-code-interface) | [CLI Quick Reference](#cli-quick-reference)
-- [Auto Mode](#auto-mode) | [Interactive Mode](#interactive-mode-cli) | [Deep Research CLI](#deep-research-cli) | [Planning Mode CLI](#planning-mode-cli)
-- [Memory CLI](#memory-cli) | [Workflow CLI](#workflow-cli) | [Knowledge CLI](#knowledge-cli) | [Session CLI](#session-cli)
-- [Tools CLI](#tools-cli) | [MCP Config CLI](#mcp-config-cli) | [External Agents CLI](#external-agents-cli) | [CLI Features Summary](#cli-features)
-
-</details>
-
-<details>
-<summary><strong>Configuration & Features</strong></summary>
-
-- [✨ Key Features](#-key-features) | [🌐 Supported Providers](#-supported-providers)
-- [🔧 Configuration & Integration](#-configuration--integration) | [Ollama](#ollama-integration) | [Groq](#groq-integration) | [100+ Models](#100-models-support)
+### Configuration
+- [🔧 Configuration & Integration](#-configuration--integration)
+  - [Ollama Integration](#ollama-integration)
+  - [Groq Integration](#groq-integration)
+  - [100+ Models Support](#100-models-support)
 - [📋 Agents Playbook](#-agents-playbook)
+
+### Advanced Features
 - [🔬 Advanced Features](#-advanced-features)
+  - [Research & Intelligence](#research--intelligence)
+  - [Memory & Caching](#memory--caching)
+  - [Planning & Workflows](#planning--workflows)
+  - [Specialised Agents](#specialised-agents)
+  - [MCP Protocol](#mcp-protocol)
+  - [A2A & A2UI Protocols](#a2a--a2ui-protocols)
+  - [Safety & Control](#safety--control)
+  - [Developer Tools](#developer-tools)
 
-</details>
-
-<details>
-<summary><strong>Architecture & Patterns</strong></summary>
-
+### Architecture
 - [📊 Process Types & Patterns](#-process-types--patterns)
-- [Sequential](#sequential-process) | [Hierarchical](#hierarchical-process) | [Workflow](#workflow-process) | [Agentic Patterns](#agentic-patterns)
-
-</details>
-
-<details>
-<summary><strong>Data & Persistence</strong></summary>
+  - [Sequential Process](#sequential-process)
+  - [Hierarchical Process](#hierarchical-process)
+  - [Workflow Process](#workflow-process)
+  - [Agentic Patterns](#agentic-patterns)
 
+### Data & Persistence
 - [💾 Persistence (Databases)](#-persistence-databases)
 - [📚 Knowledge & Retrieval (RAG)](#-knowledge--retrieval-rag)
 - [🔧 Tools Table](#-tools-table)
 
-</details>
-
-<details>
-<summary><strong>Learning & Community</strong></summary>
-
-- [🎓 Video Tutorials](#-video-tutorials) | [⭐ Star History](#-star-history)
-- [👥 Contributing](#-contributing) | [🔧 Development](#-development) | [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
-
-</details>
+### Learning & Community
+- [🎓 Video Tutorials](#-video-tutorials)
+- [⭐ Star History](#-star-history)
+- [👥 Contributing](#-contributing)
+- [🔧 Development](#-development)
+- [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
 
 ---
 
@@ -137,6 +152,7 @@ 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>
@@ -165,8 +181,6 @@ export OPENAI_API_KEY=your_key_here
 python -c "from praisonaiagents import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"
 ```
 
-> **Next Steps:** [Single Agent Example](#1-single-agent) | [Multi Agents](#2-multi-agents) | [CLI Auto Mode](#auto-mode)
-
 ---
 
 ## 📦 Installation
@@ -217,6 +231,28 @@ export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 
 ---
 
+## 💻 Usage
+
+### Python Code Examples
+
+- [📘 Complete Python Examples](#using-python-code)
+- [🔧 Custom Tools](#️-custom-tools)
+- [🧠 Memory Configuration](#-memory--context)
+
+### CLI / No-Code Interface
+
+- [🎯 Auto Mode](#auto-mode)
+- [🔬 Deep Research](#deep-research-cli)
+- [📋 Planning Mode](#planning-mode-cli)
+- [💾 Memory Management](#memory-cli)
+- [🔄 Workflow Execution](#workflow-cli)
+
+### JavaScript Code Examples
+
+- [💻 JavaScript Usage](#using-javascript-code)
+
+---
+
 ## ✨ Key Features
 
 <details open>
@@ -483,9 +519,6 @@ export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 
 PraisonAI supports 100+ LLM providers through seamless integration:
 
-<details>
-<summary><strong>View all 24 providers</strong></summary>
-
 | Provider | Example |
 |----------|:-------:|
 | OpenAI | [Example](examples/python/providers/openai/openai_gpt4_example.py) |
@@ -513,12 +546,17 @@ PraisonAI supports 100+ LLM providers through seamless integration:
 | Moonshot | [Example](examples/python/providers/moonshot/moonshot_example.py) |
 | vLLM | [Example](examples/python/providers/vllm/vllm_example.py) |
 
-</details>
-
 ---
 
 ## 📘 Using Python Code
 
+Light weight package dedicated for coding:
+
+```bash
+pip install praisonaiagents
+export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
+```
+
 ### 1. Single Agent
 
 Create app.py file and add the code below:
@@ -537,11 +575,11 @@ python app.py
 
 Create app.py file and add the code below:
 ```python
-from praisonaiagents import Agent, Agents
+from praisonaiagents import Agent, PraisonAIAgents
 
 research_agent = Agent(instructions="Research about AI")
 summarise_agent = Agent(instructions="Summarise research agent's findings")
-agents = Agents(agents=[research_agent, summarise_agent])
+agents = PraisonAIAgents(agents=[research_agent, summarise_agent])
 agents.start()
 ```
 
@@ -1929,11 +1967,11 @@ agent = Agent(
     auto_save="my-project"
 )
 
-# Load history from past sessions via context management
+# Load history from last 5 sessions
 agent = Agent(
     name="Assistant",
     memory=True,
-    context=True,  # Enable context management for history
+    history_in_context=5
 )
 ```
 
@@ -2367,9 +2405,6 @@ agent.start('Write a movie script about a robot in Mars');
 
 ## 📊 Process Types & Patterns
 
-<details>
-<summary><strong>View architecture diagrams and workflow patterns</strong></summary>
-
 ### AI Agents Flow
 
 ```mermaid
@@ -2709,8 +2744,6 @@ flowchart LR
     style Out fill:#8B0000,color:#fff
 ```
 
-</details>
-
 ---
 
 ## 🔧 Configuration & Integration
@@ -2858,179 +2891,77 @@ PraisonAI provides zero-dependency persistent memory for agents. For detailed ex
 
 PraisonAI provides a complete knowledge stack for building RAG applications with multiple vector stores, retrieval strategies, rerankers, and query modes.
 
-### RAG Quickstart (Agent-first)
-
-```python
-from praisonaiagents import Agent
-from praisonaiagents.rag.models import RetrievalStrategy
-
-# Agent with RAG - simplest approach
-agent = Agent(
-    name="Research Assistant",
-    knowledge=["docs/manual.pdf", "data/faq.txt"],
-    knowledge_config={"vector_store": {"provider": "chroma"}},
-    rag_config={
-        "include_citations": True,
-        "retrieval_strategy": RetrievalStrategy.HYBRID,  # Dense + BM25
-        "rerank": True,
-    }
-)
-
-# Query with citations
-result = agent.rag_query("How do I authenticate?")
-print(result.answer)
-for citation in result.citations:
-    print(f"  [{citation.id}] {citation.source}")
-```
-
-### RAG CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `praisonai rag query "<question>"` | One-shot question answering with citations |
-| `praisonai rag chat` | Interactive RAG chat session |
-| `praisonai rag serve` | Start RAG as a microservice API |
-| `praisonai rag eval <test_file>` | Evaluate RAG retrieval quality |
-
-### RAG CLI Examples
-
-```bash
-# Query with hybrid retrieval (dense + BM25 keyword search)
-praisonai rag query "What are the key findings?" --hybrid
-
-# Query with hybrid + reranking for best quality
-praisonai rag query "Summarize conclusions" --hybrid --rerank
-
-# Interactive chat with hybrid retrieval
-praisonai rag chat --collection research --hybrid --rerank
-
-# Start API server with OpenAI-compatible endpoint
-praisonai rag serve --hybrid --rerank --openai-compat --port 8080
-
-# Query with profiling
-praisonai rag query "Summary?" --profile --profile-out ./profile.json
-```
-
 ### Knowledge CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `praisonai knowledge index <sources>` | Index documents into knowledge base |
-| `praisonai knowledge search <query>` | Search knowledge base (no LLM generation) |
+| `praisonai knowledge add <file\|dir\|url>` | Add documents to knowledge base |
+| `praisonai knowledge query <question>` | Query knowledge base with RAG |
 | `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+### Knowledge CLI Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | Vector store backend |
+| `--retrieval` | `basic`, `fusion`, `recursive`, `auto_merge` | Retrieval strategy |
+| `--reranker` | `simple`, `llm`, `cross_encoder`, `cohere` | Reranking method |
+| `--index-type` | `vector`, `keyword`, `hybrid` | Index type |
+| `--query-mode` | `default`, `sub_question`, `summarize` | Query mode |
 
 ### Knowledge CLI Examples
 
 ```bash
-# Index documents
-praisonai knowledge index ./docs/ --collection myproject
+# Add documents
+praisonai knowledge add ./docs/
+praisonai knowledge add https://example.com/page.html
+praisonai knowledge add "*.pdf"
 
-# Search with hybrid retrieval
-praisonai knowledge search "authentication" --hybrid --collection myproject
+# Query with advanced options
+praisonai knowledge query "How to authenticate?" --retrieval fusion --reranker llm
 
-# Index with profiling
-praisonai knowledge index ./data --profile --profile-out ./profile.json
+# Full advanced query
+praisonai knowledge query "authentication flow" \
+  --vector-store chroma \
+  --retrieval fusion \
+  --reranker llm \
+  --index-type hybrid \
+  --query-mode sub_question
 ```
 
-### Knowledge vs RAG vs AutoRagAgent
-
-- **Knowledge** is the indexing and retrieval substrate - use for indexing and raw search
-- **RAG** orchestrates on top - use for question answering with LLM-generated responses and citations
-- **AutoRagAgent** wraps an Agent with automatic retrieval decision - use when you want the agent to decide when to retrieve
-- All share the same underlying index
-
-### AutoRagAgent (Automatic RAG)
-
-AutoRagAgent automatically decides when to retrieve context from knowledge bases vs direct chat, based on query heuristics.
+### Knowledge SDK Usage
 
 ```python
-from praisonaiagents import Agent, AutoRagAgent
+from praisonaiagents import Agent, Knowledge
 
-# Create agent with knowledge
+# Simple usage with Agent
 agent = Agent(
     name="Research Assistant",
-    knowledge=["docs/manual.pdf"],
-    user_id="user123",  # Required for RAG retrieval
+    knowledge=["docs/manual.pdf", "data/faq.txt"],
+    knowledge_config={
+        "vector_store": {"provider": "chroma"}
+    }
 )
+response = agent.chat("How do I authenticate?")
 
-# Wrap with AutoRagAgent
-auto_rag = AutoRagAgent(
-    agent=agent,
-    retrieval_policy="auto",  # auto, always, never
-    top_k=5,
-    hybrid=True,
-    rerank=True,
-)
-
-# Auto-decides: retrieves for questions, skips for greetings
-result = auto_rag.chat("What are the key findings?")  # Retrieves
-result = auto_rag.chat("Hello!")  # Skips retrieval
-
-# Force retrieval or skip per-call
-result = auto_rag.chat("Hi", force_retrieval=True)
-result = auto_rag.chat("Summary?", skip_retrieval=True)
-```
-
-**CLI Usage:**
-```bash
-# Enable auto-rag with default policy (auto)
-praisonai --auto-rag "What are the key findings?"
-
-# Always retrieve
-praisonai --auto-rag --rag-policy always "Tell me about X"
-
-# With hybrid retrieval and reranking
-praisonai --auto-rag --rag-hybrid --rag-rerank "Summarize the document"
-```
-
-### Configuration Precedence
-
-Settings are applied in this order (highest priority first):
-1. **CLI flags** - `--hybrid`, `--rerank`, `--top-k`
-2. **Environment variables** - `PRAISONAI_HYBRID=true`
-3. **Config file** - YAML configuration (`--config`)
-4. **Defaults**
-
-```bash
-# Environment variables
-export PRAISONAI_HYBRID=true
-export PRAISONAI_RERANK=true
-export PRAISONAI_TOP_K=10
-```
-
-### Lightweight Installs
-
-```bash
-# Base install (minimal, fast imports)
-pip install praisonaiagents
-
-# With RAG API server support
-pip install "praisonai[rag-api]"
-```
-
-### Live Tests (Real API Keys)
-
-Run integration tests with real API keys:
-
-```bash
-# Enable live tests
-export PRAISONAI_LIVE_TESTS=1
-export OPENAI_API_KEY="your-key"
-
-# Run live tests
-pytest -m live tests/integration/
+# Direct Knowledge usage
+knowledge = Knowledge()
+knowledge.add("document.pdf")
+results = knowledge.search("authentication", limit=5)
 ```
 
 ### Knowledge Stack Features Table
 
 | Feature | Description | SDK Docs | CLI Docs |
 |---------|-------------|----------|----------|
-| **Hybrid Retrieval** | Dense vectors + BM25 keyword search with RRF fusion | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
-| **Reranking** | LLM, Cross-Encoder, Cohere rerankers | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
-| **RAG Serve** | Microservice API with OpenAI-compatible mode | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
-| **Vector Stores** | ChromaDB, Pinecone, Qdrant, Weaviate, In-Memory | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
 | **Data Readers** | Load PDF, Markdown, Text, HTML, URLs | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
-| **Profiling** | Performance profiling with `--profile` flag | [SDK](/docs/features/profiling) | [CLI](/docs/cli/rag) |
+| **Vector Stores** | ChromaDB, Pinecone, Qdrant, Weaviate, In-Memory | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Retrieval Strategies** | Basic, Fusion (RRF), Recursive, Auto-Merge | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Rerankers** | Simple, LLM, Cross-Encoder, Cohere | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Index Types** | Vector, Keyword (BM25), Hybrid | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Query Engines** | Default, Sub-Question, Summarize | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
 
 ---
 
@@ -3148,7 +3079,43 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | `praisonai persistence migrate` | Apply schema migrations |
 | `praisonai persistence status` | Show schema status |
 
-> **Note:** See [Knowledge & Retrieval (RAG)](#-knowledge--retrieval-rag) for complete Knowledge CLI documentation.
+### Knowledge CLI Commands {#knowledge-cli}
+
+| Command | Description |
+|---------|-------------|
+| `praisonai knowledge add <source>` | Add file, directory, URL, or glob pattern |
+| `praisonai knowledge query "<question>"` | Query knowledge base with RAG |
+| `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+**Knowledge Query Flags:**
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | `chroma` |
+| `--retrieval-strategy` | `basic`, `fusion`, `recursive`, `auto_merge` | `basic` |
+| `--reranker` | `none`, `simple`, `llm`, `cross_encoder`, `cohere` | `none` |
+| `--index-type` | `vector`, `keyword`, `hybrid` | `vector` |
+| `--query-mode` | `default`, `sub_question`, `summarize` | `default` |
+| `--workspace` | Path to workspace directory | Current dir |
+| `--session` | Session ID for persistence | - |
+
+**Examples:**
+
+```bash
+# Add documents
+praisonai knowledge add document.pdf
+praisonai knowledge add ./docs/
+praisonai knowledge add "*.md"
+
+# Query with options
+praisonai knowledge query "How to authenticate?" \
+  --vector-store chroma \
+  --retrieval-strategy fusion \
+  --reranker simple \
+  --query-mode sub_question
+```
 
 ### Databases Table
 
@@ -3224,9 +3191,6 @@ Install all tools with: `pip install "praisonai[tools]"`
 
 Learn PraisonAI through our comprehensive video series:
 
-<details>
-<summary><strong>View all 22 video tutorials</strong></summary>
-
 | Topic | Video |
 |-------|--------|
 | AI Agents with Self Reflection | [![Self Reflection](https://img.youtube.com/vi/vLXobEN2Vc8/0.jpg)](https://www.youtube.com/watch?v=vLXobEN2Vc8) |
@@ -3252,8 +3216,6 @@ Learn PraisonAI through our comprehensive video series:
 | Call Interface | [![Call](https://img.youtube.com/vi/m1cwrUG2iAk/0.jpg)](https://www.youtube.com/watch?v=m1cwrUG2iAk) |
 | Reasoning Extract Agents | [![Reasoning Extract](https://img.youtube.com/vi/2PPamsADjJA/0.jpg)](https://www.youtube.com/watch?v=2PPamsADjJA) |
 
-</details>
-
 ---
 
 ## 👥 Contributing
@@ -3379,11 +3341,11 @@ See [Agent Memory](#6-agent-memory-zero-dependencies) for more options.
 <summary><strong>How do I run multiple agents together?</strong></summary>
 
 ```python
-from praisonaiagents import Agent, Agents
+from praisonaiagents import Agent, PraisonAIAgents
 
 agent1 = Agent(instructions="Research topics")
 agent2 = Agent(instructions="Summarize findings")
-agents = Agents(agents=[agent1, agent2])
+agents = PraisonAIAgents(agents=[agent1, agent2])
 agents.start()
 ```
 

docker/.env.template

@@ -13,12 +13,6 @@ 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

docker/Dockerfile.chat

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

docker/bots/.env.template

@@ -1,15 +0,0 @@
-# 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

docker/bots/Dockerfile

@@ -1,42 +0,0 @@
-# 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"]

docker/bots/README.md

@@ -1,66 +0,0 @@
-# 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"]
-```

docker/bots/docker-compose.yml

@@ -1,53 +0,0 @@
-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

docker/docker-compose.yml

@@ -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,7 +89,6 @@ services:
       PRAISON_CONFIG_DIR: /root/.praison
     networks:
       - praison_network
-  # For bot services (Slack, Discord, Telegram), see docker/bots/
 
 volumes:
   praison_data:
@@ -97,4 +96,4 @@ volumes:
 
 networks:
   praison_network:
-    driver: bridge
+    driver: bridge

docs/templates-cli.md

@@ -0,0 +1,53 @@
+# Templates CLI
+
+```bash
+praisonai templates list
+```
+
+```bash
+praisonai templates search video
+```
+
+```bash
+praisonai templates info ai-video-editor
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --offline
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --strict-tools
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools ./my_tools.py
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools-dir ./tools
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools-source praisonai_tools.video
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --no-template-tools-py
+```
+
+```bash
+praisonai templates init my-project --template ai-video-editor
+```
+
+```bash
+praisonai templates cache clear
+```
+
+```bash
+praisonai templates cache list
+```

docs/templates-module.md

@@ -0,0 +1,104 @@
+# Templates Module
+
+## Loading Templates
+
+```python
+from praisonai.templates.loader import TemplateLoader
+
+loader = TemplateLoader()
+
+# Load from local path
+template = loader.load("./my-template")
+
+# Load from URI
+template = loader.load("ai-video-editor")
+
+# Load offline
+template = loader.load("ai-video-editor", offline=True)
+
+# Check requirements
+missing = loader.check_requirements(template)
+```
+
+## Template Discovery
+
+```python
+from praisonai.templates.discovery import TemplateDiscovery
+
+discovery = TemplateDiscovery(
+    include_package=True,
+    include_defaults=True,
+)
+
+# Find template
+result = discovery.find_template("ai-video-editor")
+
+# List all templates
+templates = discovery.list_templates()
+```
+
+## Template Config
+
+```python
+from praisonai.templates.loader import TemplateConfig
+
+# Access template properties
+template.name
+template.description
+template.version
+template.author
+template.requires
+template.workflow_file
+template.agents_file
+template.path
+```
+
+## Tool Override Integration
+
+```python
+from praisonai.templates.tool_override import (
+    create_tool_registry_with_overrides,
+    resolve_tools,
+)
+
+# Build registry with template sources
+tools_sources = template.requires.get("tools_sources", [])
+
+registry = create_tool_registry_with_overrides(
+    tools_sources=tools_sources,
+    template_dir=str(template.path),
+    include_defaults=True,
+)
+
+# Resolve tool names
+tools = resolve_tools(["shell_tool"], registry=registry)
+```
+
+## TEMPLATE.yaml Schema
+
+```yaml
+name: my-template
+version: "1.0.0"
+description: Template description
+
+requires:
+  tools: [shell_tool]
+  packages: [praisonai-tools]
+  env: [OPENAI_API_KEY]
+  tools_sources:
+    - praisonai_tools.video
+    - ./local_tools.py
+
+workflow: workflow.yaml
+agents: agents.yaml
+
+config:
+  input:
+    type: string
+    required: true
+  output:
+    type: string
+
+defaults:
+  preset: podcast
+```

docs/tools-cli.md

@@ -0,0 +1,65 @@
+# Tools CLI
+
+```bash
+praisonai tools list
+```
+
+```bash
+praisonai tools info shell_tool
+```
+
+```bash
+praisonai tools info internet_search
+```
+
+```bash
+praisonai tools search "web"
+```
+
+```bash
+praisonai tools search "file"
+```
+
+```bash
+praisonai tools doctor
+```
+
+```bash
+praisonai tools doctor --json
+```
+
+```bash
+praisonai tools resolve shell_tool
+```
+
+```bash
+praisonai tools resolve internet_search --template ai-video-editor
+```
+
+```bash
+praisonai tools resolve my_tool --tools ./my_tools.py
+```
+
+```bash
+praisonai tools resolve my_tool --tools-dir ./tools
+```
+
+```bash
+praisonai tools discover
+```
+
+```bash
+praisonai tools discover --include praisonai_tools.video
+```
+
+```bash
+praisonai tools discover --entrypoints
+```
+
+```bash
+praisonai tools show-sources
+```
+
+```bash
+praisonai tools show-sources --template ai-video-editor
+```

docs/tools-module.md

@@ -0,0 +1,90 @@
+# Tools Module
+
+## Tool Registry
+
+```python
+from praisonai.templates.tool_override import (
+    create_tool_registry_with_overrides,
+    resolve_tools,
+)
+
+# Create registry with defaults
+registry = create_tool_registry_with_overrides(include_defaults=True)
+
+# Create registry with overrides
+registry = create_tool_registry_with_overrides(
+    override_files=["my_tools.py"],
+    override_dirs=["./tools"],
+    include_defaults=True,
+)
+
+# Create registry with tools_sources
+registry = create_tool_registry_with_overrides(
+    tools_sources=["praisonai_tools.video"],
+    template_dir="./my-template",
+    include_defaults=True,
+)
+
+# Resolve tool names to callables
+tools = resolve_tools(
+    ["shell_tool", "internet_search"],
+    registry=registry,
+)
+```
+
+## Tool Override Loader
+
+```python
+from praisonai.templates.tool_override import ToolOverrideLoader
+
+loader = ToolOverrideLoader()
+
+# Load from file
+tools = loader.load_from_file("my_tools.py")
+
+# Load from directory
+tools = loader.load_from_directory("./tools")
+
+# Load from module
+tools = loader.load_from_module("praisonai_tools.video")
+
+# Get default tool directories
+dirs = loader.get_default_tool_dirs()
+```
+
+## Resolution Order
+
+1. CLI `--tools` files (highest priority)
+2. CLI `--tools-dir` directories
+3. Template `tools_sources` (from TEMPLATE.yaml)
+4. Template-local `tools.py`
+5. Default dirs (`~/.praison/tools`, `~/.config/praison/tools`)
+6. Package discovery (`praisonai_tools`)
+7. Built-in tools (lowest priority)
+
+## Creating Custom Tools
+
+```python
+from praisonai_tools import tool
+
+@tool
+def my_custom_tool(query: str) -> str:
+    """My custom tool description.
+    
+    Args:
+        query: The search query
+    """
+    return f"Result for: {query}"
+```
+
+## Template tools_sources
+
+```yaml
+# TEMPLATE.yaml
+requires:
+  tools: [shell_tool]
+  tools_sources:
+    - praisonai_tools.video
+    - ./local_tools.py
+    - ./tools_dir/
+```

examples/README.md

@@ -23,7 +23,6 @@ examples/
 
 | Category | Examples | Docs |
 |----------|----------|------|
-| **Consolidated Params** | [consolidated_params/](consolidated_params/) | [📖](https://docs.praison.ai/api/consolidated-params) |
 | **Agents** | [python/agents/](python/agents/) | [📖](https://docs.praison.ai/concepts/agents) |
 | **Workflows** | [python/workflows/](python/workflows/) | [📖](https://docs.praison.ai/features/workflows) |
 | **Model Router** | [python/agents/router-agent-cost-optimization.py](python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/features/model-router) |
@@ -36,21 +35,6 @@ examples/
 | **Serve** | [serve/](serve/) | [📖](https://docs.praison.ai/cli/serve) |
 | **Endpoints** | [serve/](serve/) | [📖](https://docs.praison.ai/cli/endpoints) |
 
-## Consolidated Params Examples
-
-Agent-centric API with unified parameter resolution. Precedence: Instance > Config > Array > Dict > String > Bool > Default
-
-| Example | Description |
-|---------|-------------|
-| [basic_agent.py](consolidated_params/basic_agent.py) | Minimal agent with memory |
-| [basic_agents.py](consolidated_params/basic_agents.py) | Multi-agent with memory+planning |
-| [basic_workflow.py](consolidated_params/basic_workflow.py) | Workflow with consolidated params |
-| [basic_memory.py](consolidated_params/basic_memory.py) | Memory presets (file, redis, postgres) |
-| [basic_guardrails.py](consolidated_params/basic_guardrails.py) | Guardrails with callable or config |
-| [basic_workflow_agentlike.py](consolidated_params/basic_workflow_agentlike.py) | Workflow with agent-like params |
-| [basic_step_override.py](consolidated_params/basic_step_override.py) | Step-level override of workflow defaults |
-| [advanced_workflow_full_features.py](consolidated_params/advanced_workflow_full_features.py) | All consolidated params |
-
 ## Serve Examples
 
 | Example | Description | CLI Command |

examples/acp/README.md

@@ -1,137 +0,0 @@
-# ACP (Agent Client Protocol) Examples
-
-This directory contains examples for using PraisonAI with the Agent Client Protocol (ACP).
-
-## What is ACP?
-
-The Agent Client Protocol (ACP) is a standardized JSON-RPC 2.0 protocol that allows code editors and IDEs to communicate with AI coding agents. It enables seamless integration between PraisonAI and editors like:
-
-- **Zed**
-- **JetBrains IDEs** (IntelliJ, PyCharm, WebStorm, etc.)
-- **VSCode** (via extensions)
-- **Toad**
-
-## Quick Start
-
-### CLI Usage
-
-```bash
-# Start ACP server with defaults
-praisonai acp
-
-# Enable debug logging
-praisonai acp --debug
-
-# Allow file writes
-praisonai acp --allow-write
-
-# Use a specific model
-praisonai acp -m gpt-4o
-
-# Resume last session
-praisonai acp --resume --last
-```
-
-### Python API
-
-```python
-from praisonai.acp import serve
-
-serve(
-    workspace=".",
-    debug=True,
-    allow_write=True,
-)
-```
-
-## Editor Configuration
-
-### Zed
-
-Add to `~/.config/zed/settings.json`:
-
-```json
-{
-  "agent_servers": {
-    "PraisonAI": {
-      "command": "praisonai",
-      "args": ["acp"],
-      "env": {}
-    }
-  }
-}
-```
-
-### JetBrains
-
-Add to `~/.jetbrains/acp.json`:
-
-```json
-{
-  "agent_servers": {
-    "PraisonAI": {
-      "command": "praisonai",
-      "args": ["acp"],
-      "env": {}
-    }
-  }
-}
-```
-
-### Toad
-
-```bash
-toad acp "praisonai acp"
-```
-
-## Examples
-
-- `basic_acp_server.py` - Simple ACP server with default settings
-- `custom_agent_acp.py` - ACP server with a custom agent
-
-## CLI Options
-
-| Option | Description |
-|--------|-------------|
-| `-w, --workspace` | Workspace root directory |
-| `-a, --agent` | Agent name or config file |
-| `-m, --model` | LLM model to use |
-| `-r, --resume` | Resume session by ID |
-| `--last` | Resume the last session |
-| `--approve` | Approval mode: manual, auto, scoped |
-| `--read-only` | Read-only mode (default) |
-| `--allow-write` | Allow file writes |
-| `--allow-shell` | Allow shell commands |
-| `--debug` | Enable debug logging |
-
-## Installation
-
-```bash
-pip install praisonai[acp]
-```
-
-## Protocol Details
-
-ACP uses JSON-RPC 2.0 over stdio:
-- **stdin**: Receives JSON-RPC requests from the client
-- **stdout**: Sends JSON-RPC responses to the client
-- **stderr**: Debug/log output (never pollutes stdout)
-
-### Supported Methods
-
-**Agent Methods (client → agent):**
-- `initialize` - Negotiate protocol version and capabilities
-- `authenticate` - Optional authentication
-- `session/new` - Create a new session
-- `session/load` - Load an existing session
-- `session/prompt` - Send user message
-- `session/cancel` - Cancel ongoing operations
-- `session/set_mode` - Change operating mode
-
-**Client Methods (agent → client):**
-- `session/update` - Send progress updates
-- `session/request_permission` - Request user approval
-- `fs/read_text_file` - Read file contents
-- `fs/write_text_file` - Write file contents
-- `terminal/create` - Create terminal
-- `terminal/output` - Get terminal output

examples/acp/basic_acp_server.py

@@ -1,27 +0,0 @@
-#!/usr/bin/env python3
-"""
-Basic ACP Server Example
-
-This example demonstrates how to run PraisonAI as an ACP server
-that can be connected to by IDEs like Zed, JetBrains, VSCode, or Toad.
-
-Usage:
-    # Run from command line
-    praisonai acp
-    
-    # Or run this script directly
-    python basic_acp_server.py
-"""
-
-from praisonai.acp import serve
-
-if __name__ == "__main__":
-    # Start ACP server with default settings
-    # This will listen on stdin/stdout for JSON-RPC messages
-    serve(
-        workspace=".",           # Current directory as workspace
-        agent="default",         # Use default agent
-        debug=False,             # Set to True for debug logging to stderr
-        read_only=True,          # Safe by default
-        approval_mode="manual",  # Require approval for actions
-    )

examples/acp/custom_agent_acp.py

@@ -1,45 +0,0 @@
-#!/usr/bin/env python3
-"""
-Custom Agent ACP Server Example
-
-This example shows how to run a custom PraisonAI agent as an ACP server.
-
-Usage:
-    python custom_agent_acp.py
-"""
-
-from praisonai.acp import serve, ACPServer, ACPConfig
-from praisonaiagents import Agent
-
-# Create a custom agent
-agent = Agent(
-    name="CodeAssistant",
-    instructions="""You are an expert coding assistant. You help users:
-    - Write clean, efficient code
-    - Debug issues
-    - Explain complex concepts
-    - Review code for best practices
-    
-    Always provide clear explanations with your code suggestions.""",
-    model="gpt-4o-mini",
-)
-
-if __name__ == "__main__":
-    # Create config
-    config = ACPConfig(
-        workspace=".",
-        debug=True,
-        allow_write=True,  # Allow file modifications
-        approval_mode="manual",
-    )
-    
-    # Create server with custom agent
-    server = ACPServer(config=config, agent=agent)
-    
-    # Run the server
-    serve(
-        workspace=".",
-        debug=True,
-        allow_write=True,
-        approval_mode="manual",
-    )

examples/agent_centric_api.py

@@ -1,244 +0,0 @@
-"""
-Agent-Centric API Example
-
-Demonstrates the consolidated feature parameters for PraisonAI Agents.
-These params provide a cleaner, more intuitive API with progressive disclosure.
-
-Precedence Rule: Instance > Config > Array > String > Bool > Default
-
-Consolidated Params Support:
-- memory: bool | str URL | str preset | [preset, overrides] | MemoryConfig | Instance
-- knowledge: bool | str path | [sources...] | KnowledgeConfig | Instance
-- planning: bool | str LLM | [preset, overrides] | PlanningConfig
-- reflection: bool | str preset | [preset, overrides] | ReflectionConfig
-- guardrails: bool | callable | str prompt | GuardrailConfig
-- web: bool | str provider | [provider, overrides] | WebConfig
-- output: str preset | [preset, overrides] | OutputConfig
-- execution: str preset | [preset, overrides] | ExecutionConfig
-"""
-
-from praisonaiagents import (
-    Agent,
-    # Config classes for progressive disclosure
-    MemoryConfig,
-    KnowledgeConfig,
-    PlanningConfig,
-    ReflectionConfig,
-    GuardrailConfig,
-    WebConfig,
-)
-
-
-def example_simple_enable():
-    """Example 1: Simple boolean enable (easiest)"""
-    print("\n=== Example 1: Simple Boolean Enable ===")
-    
-    agent = Agent(
-        instructions="You are a helpful assistant",
-        memory=True,      # Enable memory with defaults
-        reflection=True,  # Enable self-reflection
-        web=True,         # Enable web search + fetch
-    )
-    print(f"Agent created with memory={agent._memory_instance is not None}")
-    print(f"  self_reflect={agent.self_reflect}")
-    print(f"  web_search={agent.web_search}")
-
-
-def example_with_config():
-    """Example 2: Using config objects (more control)"""
-    print("\n=== Example 2: Using Config Objects ===")
-    
-    agent = Agent(
-        instructions="You are a research assistant",
-        memory=MemoryConfig(
-            backend="file",
-            user_id="researcher_001",
-            auto_memory=True,
-        ),
-        reflection=ReflectionConfig(
-            min_iterations=1,
-            max_iterations=5,
-            llm="gpt-4o-mini",
-        ),
-        web=WebConfig(
-            search=True,
-            fetch=False,  # Only search, no full page fetch
-            max_results=3,
-        ),
-    )
-    print(f"Agent created with user_id={agent.user_id}")
-    print(f"  {agent.max_reflect}")
-    print(f"  web_search={agent.web_search}, web_fetch={agent.web_fetch}")
-
-
-def example_guardrails():
-    """Example 3: Guardrails with callable or config"""
-    print("\n=== Example 3: Guardrails ===")
-    
-    # Option A: Direct callable
-    def my_validator(output):
-        """Simple validator that checks response length."""
-        is_valid = len(output.raw) < 1000
-        return (is_valid, output if is_valid else "Response too long")
-    
-    agent_a = Agent(
-        instructions="Be concise",
-        guardrails=my_validator,  # Direct callable
-    )
-    print(f"Agent A: guardrail is callable = {callable(agent_a.guardrail)}")
-    
-    # Option B: Using GuardrailConfig
-    agent_b = Agent(
-        instructions="Be helpful and safe",
-        guardrails=GuardrailConfig(
-            llm_validator="Ensure the response is helpful, accurate, and safe",
-            max_retries=3,
-        ),
-    )
-    print(f"Agent B: guardrail = {agent_b.guardrail}")
-    print(f"  max_retries = {agent_b.max_guardrail_retries}")
-
-
-def example_planning():
-    """Example 4: Planning mode"""
-    print("\n=== Example 4: Planning Mode ===")
-    
-    agent = Agent(
-        instructions="You are a project planner",
-        planning=PlanningConfig(
-            reasoning=True,
-            read_only=True,  # Plan mode - only read operations
-        ),
-    )
-    print(f"Agent created with planning={agent.planning}")
-    print(f"  plan_mode={agent.plan_mode}")
-    print(f"  planning_reasoning={agent.planning_reasoning}")
-
-
-def example_backward_compatible():
-    """Example 5: Using new consolidated params"""
-    print("\n=== Example 5: Consolidated Params ===")
-    
-    # New consolidated params
-    agent = Agent(
-        instructions="Test agent",
-        reflection=True,
-        web=WebConfig(search=True, fetch=False),
-    )
-    print(f"Consolidated params work: self_reflect={agent.self_reflect}")
-    print(f"  web_search={agent.web_search}, web_fetch={agent.web_fetch}")
-
-
-def example_real_chat():
-    """Example 6: Real chat with new API"""
-    print("\n=== Example 6: Real Chat ===")
-    
-    agent = Agent(
-        instructions="You are a helpful math tutor. Be concise.",
-        reflection=False,
-        web=False,
-    )
-    
-    response = agent.start("What is the square root of 144?")
-    print(f"Response: {response}")
-
-
-def example_string_presets():
-    """Example 7: String presets (NEW - user-friendly shortcuts)"""
-    print("\n=== Example 7: String Presets ===")
-    
-    # Output presets: minimal, normal, verbose, debug, silent
-    agent = Agent(
-        instructions="You are a verbose assistant",
-        output="verbose",      # String preset for output
-        execution="fast",      # String preset for execution
-        web="tavily",          # String preset for web provider
-    )
-    print(f"Output preset 'verbose': verbose={agent.verbose}, metrics={agent.metrics}")
-    print(f"Execution preset 'fast': max_iter={agent.max_iter}")
-    print(f"Web preset 'tavily': web_search={agent.web_search}")
-
-
-def example_array_overrides():
-    """Example 8: Array with overrides (NEW - preset + customization)"""
-    print("\n=== Example 8: Array Overrides ===")
-    
-    # Array format: [preset, {overrides}]
-    agent = Agent(
-        instructions="You are a streaming assistant",
-        output=["verbose", {"stream": True}],      # Verbose preset + enable streaming
-        execution=["fast", {"max_iter": 15}],      # Fast preset + custom max_iter
-    )
-    print(f"Output array override: verbose={agent.verbose}, stream={agent.stream}")
-    print(f"Execution array override: max_iter={agent.max_iter}")
-
-
-def example_url_parsing():
-    """Example 9: URL parsing for memory (NEW - connection strings)"""
-    print("\n=== Example 9: URL Parsing ===")
-    
-    # Memory supports URL connection strings
-    # Supported: postgresql://, redis://, sqlite:///, mongodb://
-    agent = Agent(
-        instructions="You are a database-backed assistant",
-        memory="postgresql://postgres:password@localhost:5432/praisonai",
-    )
-    print("Memory URL parsed: memory enabled")
-    
-    # Also works with presets
-    agent2 = Agent(
-        instructions="You are a redis-backed assistant",
-        memory="redis",  # Preset name
-    )
-    print("Memory preset 'redis': configured")
-
-
-def example_knowledge_sources():
-    """Example 10: Knowledge with sources (list and string)"""
-    print("\n=== Example 10: Knowledge Sources ===")
-    
-    # Single path string
-    agent1 = Agent(
-        instructions="You are a document assistant",
-        knowledge="docs/",  # Single path
-    )
-    print(f"Knowledge single path: knowledge={agent1.knowledge}")
-    
-    # List of sources
-    agent2 = Agent(
-        instructions="You are a multi-source assistant",
-        knowledge=["docs/", "data.pdf", "https://example.com/api"],
-    )
-    print(f"Knowledge list: knowledge={agent2.knowledge}")
-    
-    # With config for advanced settings
-    agent3 = Agent(
-        instructions="You are an advanced RAG assistant",
-        knowledge=KnowledgeConfig(
-            sources=["docs/"],
-            retrieval_k=10,
-            rerank=True,
-        ),
-    )
-    print("Knowledge config: configured with rerank")
-
-
-if __name__ == "__main__":
-    print("=" * 60)
-    print("PraisonAI Agent-Centric API Examples")
-    print("=" * 60)
-    
-    example_simple_enable()
-    example_with_config()
-    example_guardrails()
-    example_planning()
-    example_backward_compatible()
-    example_real_chat()
-    example_string_presets()
-    example_array_overrides()
-    example_url_parsing()
-    example_knowledge_sources()
-    
-    print("\n" + "=" * 60)
-    print("All examples completed!")
-    print("=" * 60)

examples/agent_tools/agent_centric_example.py

@@ -1,135 +0,0 @@
-"""
-Agent-Centric Tools Example
-
-This example demonstrates how to use LSP/ACP-powered tools that make
-the Agent the central orchestrator for file operations.
-
-How to run:
-    export OPENAI_API_KEY=your_key
-    python examples/agent_tools/agent_centric_example.py
-
-Prerequisites:
-    pip install praisonai praisonaiagents
-"""
-
-import asyncio
-import os
-import sys
-import tempfile
-import shutil
-
-# Add paths for development
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai'))
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai-agents'))
-
-
-async def main():
-    print("=" * 60)
-    print("AGENT-CENTRIC TOOLS EXAMPLE")
-    print("=" * 60)
-    print()
-    
-    # Create temporary workspace
-    workspace = tempfile.mkdtemp(prefix="praisonai_example_")
-    print(f"Workspace: {workspace}")
-    print()
-    
-    try:
-        # Import after path setup
-        from praisonai.cli.features import (
-            create_agent_centric_tools,
-            InteractiveRuntime,
-            RuntimeConfig
-        )
-        from praisonaiagents import Agent
-        
-        # 1. Create runtime with ACP enabled
-        print("1. Creating InteractiveRuntime with ACP...")
-        config = RuntimeConfig(
-            workspace=workspace,
-            lsp_enabled=False,  # Skip LSP for this example
-            acp_enabled=True,
-            approval_mode="auto"  # Auto-approve for demo
-        )
-        runtime = InteractiveRuntime(config)
-        status = await runtime.start()
-        
-        print(f"   ACP ready: {runtime.acp_ready}")
-        print(f"   Read-only: {runtime.read_only}")
-        print()
-        
-        # 2. Create agent-centric tools
-        print("2. Creating agent-centric tools...")
-        tools = create_agent_centric_tools(runtime)
-        print(f"   Tools created: {len(tools)}")
-        for tool in tools:
-            print(f"     - {tool.__name__}")
-        print()
-        
-        # 3. Create Agent with ACP-powered tools
-        print("3. Creating Agent with ACP-powered tools...")
-        agent = Agent(
-            name="FileAgent",
-            instructions="""You help create and manage files. 
-            Use acp_create_file to create files.
-            Use read_file to read files.
-            Use list_files to list directory contents.""",
-            tools=tools,
-            output="verbose"  # Use new consolidated param
-        )
-        print()
-        
-        # 4. Ask agent to create a file
-        print("4. Asking agent to create a Python file...")
-        print("-" * 40)
-        result = agent.start(
-            "Create a Python file called calculator.py with add and subtract functions"
-        )
-        print("-" * 40)
-        print(f"Agent response: {result[:200]}..." if len(str(result)) > 200 else f"Agent response: {result}")
-        print()
-        
-        # 5. Verify file was created
-        print("5. Verifying file creation...")
-        calc_path = os.path.join(workspace, "calculator.py")
-        if os.path.exists(calc_path):
-            print(f"   ✓ File created at {calc_path}")
-            with open(calc_path) as f:
-                content = f.read()
-                print(f"   Content preview:")
-                for line in content.split('\n')[:10]:
-                    print(f"     {line}")
-        else:
-            # Check what files exist
-            files = os.listdir(workspace)
-            print(f"   Files in workspace: {files}")
-            for f in files:
-                fp = os.path.join(workspace, f)
-                if os.path.isfile(fp):
-                    print(f"   ✓ Found: {f}")
-        print()
-        
-        # 6. Ask agent to read the file
-        print("6. Asking agent to read the file...")
-        print("-" * 40)
-        result2 = agent.start("Read the calculator.py file and tell me what functions it has")
-        print("-" * 40)
-        print(f"Agent response: {result2[:300]}..." if len(str(result2)) > 300 else f"Agent response: {result2}")
-        print()
-        
-        # Cleanup
-        await runtime.stop()
-        
-    finally:
-        # Clean up workspace
-        shutil.rmtree(workspace, ignore_errors=True)
-        print(f"Cleaned up workspace: {workspace}")
-    
-    print()
-    print("=" * 60)
-    print("EXAMPLE COMPLETE")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

examples/background/basic_background.py

@@ -2,10 +2,10 @@
 """
 Basic Background Tasks Example for PraisonAI Agents.
 
-This example demonstrates how to use the background task system with Agent:
-1. Create an Agent with background task support
-2. Run agent tasks asynchronously
-3. Track task progress
+This example demonstrates how to use the background task system to:
+1. Run tasks asynchronously
+2. Track task progress
+3. Cancel running tasks
 4. Handle task completion
 
 Usage:
@@ -13,73 +13,71 @@ Usage:
 """
 
 import asyncio
-from praisonaiagents import Agent
+import time
+
 from praisonaiagents.background import BackgroundRunner, BackgroundConfig, TaskStatus
 
 
 async def main():
     print("=" * 60)
-    print("Agent-Centric Background Tasks Demo")
+    print("Background Tasks Demo")
     print("=" * 60)
     
-    # Create a background runner with config (used standalone, not passed to Agent)
-    runner = BackgroundRunner(config=BackgroundConfig(max_concurrent_tasks=3))
-    
-    # Create an Agent
-    agent = Agent(
-        name="AsyncAssistant",
-        instructions="You are a helpful research assistant.",
-    )
-    
-    print("\n--- Agent with Background Support Created ---")
-    print(f"Agent: {agent.name}")
-    print(f"Background runner: {runner is not None}")
+    # Create a background runner with config
+    config = BackgroundConfig(max_concurrent_tasks=3)
+    runner = BackgroundRunner(config=config)
     
     # Define some example tasks
-    async def research_task(topic: str) -> str:
-        """Simulate a research task."""
-        print(f"  🔄 Researching '{topic}'...")
-        await asyncio.sleep(1.5)
-        return f"Research on '{topic}' completed with 5 key findings"
+    def slow_task(duration: float, name: str) -> str:
+        """A slow task that simulates work."""
+        print(f"  🔄 Task '{name}' starting (will take {duration}s)")
+        time.sleep(duration)
+        return f"Task '{name}' completed after {duration}s"
     
-    async def analysis_task(data: str) -> str:
-        """Simulate an analysis task."""
-        print(f"  🔄 Analyzing data...")
-        await asyncio.sleep(1.0)
-        return f"Analysis complete: {data}"
+    async def async_task(duration: float, name: str) -> str:
+        """An async task that simulates work."""
+        print(f"  🔄 Async task '{name}' starting (will take {duration}s)")
+        await asyncio.sleep(duration)
+        return f"Async task '{name}' completed after {duration}s"
     
-    # Submit tasks via background runner
-    print("\n--- Submitting Background Tasks ---")
+    # Submit tasks
+    print("\n--- Submitting Tasks ---")
     
-    task1 = await runner.submit(
-        research_task, 
-        args=("AI trends 2025",), 
-        name="research_ai"
-    )
-    print(f"✅ Submitted research task: {task1.id[:8]}")
+    task1 = await runner.submit(slow_task, args=(1.0, "quick-job"), name="task1")
+    print(f"✅ Submitted task 1: {task1.id[:8]}")
     
-    task2 = await runner.submit(
-        analysis_task, 
-        args=("market data",), 
-        name="analyze_market"
-    )
-    print(f"✅ Submitted analysis task: {task2.id[:8]}")
+    task2 = await runner.submit(slow_task, args=(2.0, "medium-job"), name="task2")
+    print(f"✅ Submitted task 2: {task2.id[:8]}")
+    
+    task3 = await runner.submit(async_task, args=(1.5, "async-job"), name="task3")
+    print(f"✅ Submitted async task 3: {task3.id[:8]}")
     
     # List all tasks
     print("\n--- Task Status ---")
     for task in runner.tasks:
         print(f"  [{task.id[:8]}] {task.status.value}")
     
-    # Wait for tasks to complete
-    print("\n--- Waiting for Tasks ---")
-    await task1.wait(timeout=10.0)
-    await task2.wait(timeout=10.0)
+    # Wait for task 1 to complete
+    print("\n--- Waiting for Task 1 ---")
+    await task1.wait(timeout=5.0)
+    print(f"✅ Task 1 result: {task1.result}")
     
-    # Final results
-    print("\n--- Results ---")
-    for task in [task1, task2]:
-        status = "✅" if task.status == TaskStatus.COMPLETED else "❌"
-        print(f"  {status} {task.result}")
+    # Check status of all tasks
+    print("\n--- Updated Task Status ---")
+    for task in [task1, task2, task3]:
+        status = "✅" if task.status == TaskStatus.COMPLETED else "🔄"
+        print(f"  {status} [{task.id[:8]}] {task.status.value}")
+    
+    # Wait for all remaining tasks
+    print("\n--- Waiting for All Tasks ---")
+    await task2.wait(timeout=10.0)
+    await task3.wait(timeout=10.0)
+    
+    # Final status
+    print("\n--- Final Results ---")
+    for task in [task1, task2, task3]:
+        if task.result:
+            print(f"  ✅ {task.result}")
     
     # Cleanup
     runner.clear_completed()

examples/benchmark/benchmark_example.py

@@ -1,146 +0,0 @@
-#!/usr/bin/env python3
-"""
-PraisonAI Benchmark Example
-
-This example demonstrates how to use the benchmark system programmatically
-to compare performance across different execution paths.
-
-Usage:
-    python benchmark_example.py
-    
-Requirements:
-    - OPENAI_API_KEY environment variable set
-    - praisonai package installed
-"""
-
-import os
-import sys
-
-# Ensure the package is importable
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai'))
-
-from praisonai.cli.features.benchmark import BenchmarkHandler, BenchmarkReport
-
-
-def run_quick_comparison():
-    """Run a quick comparison of key execution paths."""
-    print("=" * 60)
-    print("Quick Benchmark Comparison")
-    print("=" * 60)
-    
-    handler = BenchmarkHandler()
-    
-    # Run benchmark with 2 iterations on key paths
-    report = handler.run_full_benchmark(
-        prompt="What is 2+2?",
-        iterations=2,
-        paths=["openai_sdk", "praisonai_agent"],
-        output="verbose"
-    )
-    
-    # Print comparison table
-    print("\n" + handler.create_comparison_table(report))
-    
-    return report
-
-
-def run_full_benchmark():
-    """Run full benchmark suite across all paths."""
-    print("=" * 60)
-    print("Full Benchmark Suite")
-    print("=" * 60)
-    
-    handler = BenchmarkHandler()
-    
-    # Run full benchmark
-    report = handler.run_full_benchmark(
-        prompt="Hi",
-        iterations=3,
-        output="verbose"
-    )
-    
-    # Print full report
-    handler.print_report(report)
-    
-    return report
-
-
-def run_agent_benchmark():
-    """Benchmark PraisonAI Agent specifically."""
-    print("=" * 60)
-    print("Agent Benchmark")
-    print("=" * 60)
-    
-    handler = BenchmarkHandler()
-    
-    # Benchmark agent vs SDK
-    report = handler.run_full_benchmark(
-        prompt="Explain Python in one sentence",
-        iterations=3,
-        paths=["openai_sdk", "praisonai_agent"],
-        output="verbose"
-    )
-    
-    # Show timeline diagrams
-    for name, result in report.results.items():
-        print(f"\n### {name}")
-        print(handler.create_timeline_diagram(result))
-    
-    # Show variance analysis
-    print(handler.create_variance_table(report))
-    
-    return report
-
-
-def save_benchmark_results(report: BenchmarkReport, output_path: str):
-    """Save benchmark results to JSON file."""
-    import json
-    
-    with open(output_path, 'w') as f:
-        json.dump(report.to_dict(), f, indent=2)
-    
-    print(f"\nResults saved to: {output_path}")
-
-
-def main():
-    """Main entry point."""
-    import argparse
-    
-    parser = argparse.ArgumentParser(description="PraisonAI Benchmark Example")
-    parser.add_argument(
-        "--mode",
-        choices=["quick", "full", "agent"],
-        default="quick",
-        help="Benchmark mode: quick (2 paths), full (all paths), agent (agent focus)"
-    )
-    parser.add_argument(
-        "--output",
-        type=str,
-        default=None,
-        help="Output JSON file path"
-    )
-    
-    args = parser.parse_args()
-    
-    # Check for API key
-    if not os.environ.get("OPENAI_API_KEY"):
-        print("Error: OPENAI_API_KEY environment variable not set")
-        sys.exit(1)
-    
-    # Run selected benchmark
-    if args.mode == "quick":
-        report = run_quick_comparison()
-    elif args.mode == "full":
-        report = run_full_benchmark()
-    elif args.mode == "agent":
-        report = run_agent_benchmark()
-    
-    # Save results if requested
-    if args.output:
-        save_benchmark_results(report, args.output)
-    
-    print("\n✅ Benchmark complete!")
-
-
-if __name__ == "__main__":
-    main()

examples/caching/00_agent_caching_basic.py

@@ -1,43 +0,0 @@
-"""
-Basic Caching Configuration Example
-
-Demonstrates using caching for response and prompt caching.
-"""
-import os
-from praisonaiagents import Agent, CachingConfig
-
-# Ensure API key is set from environment
-assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
-
-# Default caching (enabled)
-agent_cached = Agent(
-    instructions="You are a helpful assistant.",
-    caching=True,
-)
-
-# Disable caching
-agent_no_cache = Agent(
-    instructions="You are a helpful assistant.",
-    caching=False,
-)
-
-# Custom caching configuration
-agent_custom = Agent(
-    instructions="You are a helpful assistant.",
-    caching=CachingConfig(
-        enabled=True,
-        prompt_caching=True,  # Enable prompt caching for supported providers
-    ),
-)
-
-if __name__ == "__main__":
-    print("Testing CachingConfig...")
-    
-    print(f"Cached agent cache: {agent_cached.cache}")
-    print(f"No-cache agent cache: {agent_no_cache.cache}")
-    print(f"Custom agent cache: {agent_custom.cache}")
-    
-    result = agent_cached.chat("What is caching?")
-    print(f"Result: {result}")
-    
-    print("\nCachingConfig tests passed!")

examples/capabilities/embeddings_example.py

@@ -2,14 +2,12 @@
 Embeddings Capability Example
 
 Demonstrates text embedding generation using PraisonAI capabilities.
-Both `embed` and `embedding` work identically - use whichever you prefer.
 """
 
-from praisonai import embed, embedding  # Both work from top-level
-# Or: from praisonai.capabilities import embed, embedding
+from praisonai.capabilities import embed
 
-# Single text embedding using embed()
-print("=== Single Text Embedding (using embed) ===")
+# Single text embedding
+print("=== Single Text Embedding ===")
 result = embed(
     input="Hello, world!",
     model="text-embedding-3-small"
@@ -18,14 +16,6 @@ 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(
@@ -35,12 +25,3 @@ 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])}")

examples/catalog/template_finder_agent.py

@@ -163,7 +163,7 @@ def main():
             list_all_templates_tool,
             get_template_details_tool
         ],
-        output="verbose"  # Use new consolidated param
+        verbose=True
     )
     
     # Example queries

examples/checkpoints/basic_checkpoints.py

@@ -2,10 +2,10 @@
 """
 Basic Checkpoints Example for PraisonAI Agents.
 
-This example demonstrates how to use the shadow git checkpointing system with Agent:
-1. Create an Agent with checkpoint support
-2. Save checkpoints before making changes
-3. List available checkpoints
+This example demonstrates how to use the shadow git checkpointing system to:
+1. Save checkpoints before making changes
+2. List available checkpoints
+3. View diffs between checkpoints
 4. Restore to a previous checkpoint
 
 Usage:
@@ -16,7 +16,6 @@ import asyncio
 import tempfile
 from pathlib import Path
 
-from praisonaiagents import Agent
 from praisonaiagents.checkpoints import CheckpointService
 
 
@@ -24,7 +23,7 @@ async def main():
     # Create a temporary workspace for demonstration
     with tempfile.TemporaryDirectory() as workspace:
         print("=" * 60)
-        print("Agent-Centric Checkpointing Demo")
+        print("Shadow Git Checkpointing Demo")
         print("=" * 60)
         print(f"\nWorkspace: {workspace}")
         
@@ -33,34 +32,24 @@ async def main():
         test_file.write_text("# Initial content\nprint('Hello, World!')\n")
         print(f"\n✅ Created initial file: {test_file.name}")
         
-        # Create checkpoint service (used standalone, not passed to Agent)
-        checkpoint_service = CheckpointService(workspace_dir=workspace)
-        
-        # Create an Agent
-        agent = Agent(
-            name="RefactorBot",
-            instructions="You are a code refactoring assistant.",
-        )
-        
-        print("\n--- Agent with Checkpoint Support Created ---")
-        print(f"Agent: {agent.name}")
-        print(f"Checkpoint service initialized: {checkpoint_service is not None}")
+        # Initialize the checkpoint service
+        service = CheckpointService(workspace_dir=workspace)
         
         try:
             # Initialize the shadow git repository
             print("\n--- Initializing Checkpoint Service ---")
-            await checkpoint_service.initialize()
+            await service.initialize()
             print("✅ Shadow git repository initialized")
             
             # Save first checkpoint
             print("\n--- Saving Checkpoint 1: Initial State ---")
-            result1 = await checkpoint_service.save("Initial state")
+            result1 = await service.save("Initial state")
             print(f"✅ Checkpoint saved: {result1.checkpoint.id[:8]}")
             print(f"   Message: {result1.checkpoint.message}")
             
-            # Make some changes (simulating agent modifications)
-            print("\n--- Simulating Agent Changes ---")
-            test_file.write_text("# Refactored content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
+            # Make some changes
+            print("\n--- Making Changes ---")
+            test_file.write_text("# Modified content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
             print("✅ Modified example.py")
             
             # Create a new file
@@ -69,32 +58,38 @@ async def main():
             print("✅ Created utils.py")
             
             # Save second checkpoint
-            print("\n--- Saving Checkpoint 2: After Refactoring ---")
-            result2 = await checkpoint_service.save("Added features")
+            print("\n--- Saving Checkpoint 2: After Changes ---")
+            result2 = await service.save("Added features")
             print(f"✅ Checkpoint saved: {result2.checkpoint.id[:8]}")
             
             # List all checkpoints
             print("\n--- Listing All Checkpoints ---")
-            checkpoints_list = await checkpoint_service.list_checkpoints()
-            for i, cp in enumerate(checkpoints_list, 1):
-                print(f"  {i}. [{cp.id[:8]}] {cp.message}")
+            checkpoints = await service.list_checkpoints()
+            for i, cp in enumerate(checkpoints, 1):
+                print(f"  {i}. [{cp.id[:8]}] {cp.message} ({cp.timestamp})")
             
             # Show diff
-            print("\n--- Current Diff ---")
-            diff = await checkpoint_service.diff()
+            print("\n--- Current Diff (uncommitted changes) ---")
+            diff = await service.diff()
             if diff.files:
                 for f in diff.files:
                     print(f"  {f.status}: {f.path}")
             else:
                 print("  No uncommitted changes")
             
-            # Make more changes
-            test_file.write_text("# Bad changes\nprint('This will be reverted')\n")
-            print("\n✅ Made problematic changes to example.py")
+            # Make more changes to show diff
+            test_file.write_text("# Even more changes\nprint('This will be reverted')\n")
+            print("\n✅ Made more changes to example.py")
+            
+            diff = await service.diff()
+            print("\n--- New Diff ---")
+            if diff.files:
+                for f in diff.files:
+                    print(f"  {f.status}: {f.path}")
             
             # Restore to checkpoint 2
             print(f"\n--- Restoring to Checkpoint: {result2.checkpoint.id[:8]} ---")
-            await checkpoint_service.restore(result2.checkpoint.id)
+            await service.restore(result2.checkpoint.id)
             print("✅ Restored successfully!")
             
             # Verify restoration

examples/compaction/basic_compaction.py

@@ -2,114 +2,140 @@
 """
 Basic Context Compaction Example for PraisonAI Agents.
 
-This example demonstrates how to use context compaction with Agent:
-1. Create an Agent with context= parameter for compaction
-2. Use different compaction strategies via ManagerConfig
-3. Monitor compaction results
+This example demonstrates how to use context compaction to:
+1. Manage conversation context length
+2. Use different compaction strategies
+3. Track compaction results
+4. Preserve important messages
 
 Usage:
     python basic_compaction.py
 """
 
-from praisonaiagents import Agent
-from praisonaiagents.context import ManagerConfig
+from praisonaiagents.compaction import (
+    ContextCompactor, CompactionConfig, CompactionStrategy, CompactionResult
+)
 
 
 def main():
     print("=" * 60)
-    print("Agent-Centric Context Compaction Demo")
+    print("Context Compaction Demo")
     print("=" * 60)
     
     # ==========================================================================
-    # Available Strategies
+    # Sample Messages
     # ==========================================================================
-    print("\n--- Available Compaction Strategies ---")
-    
-    strategies = [
-        ("truncate", "Remove oldest messages first"),
-        ("sliding_window", "Keep most recent messages within limit"),
-        ("summarize", "Replace old messages with summary"),
-        ("smart", "Intelligently select messages to keep"),
+    messages = [
+        {"role": "system", "content": "You are a helpful AI assistant."},
+        {"role": "user", "content": "Hello! Can you help me with Python?"},
+        {"role": "assistant", "content": "Of course! I'd be happy to help you with Python. What would you like to know?"},
+        {"role": "user", "content": "How do I read a file in Python?"},
+        {"role": "assistant", "content": "To read a file in Python, you can use the built-in open() function. Here's an example:\n\nwith open('filename.txt', 'r') as f:\n    content = f.read()\n\nThis opens the file, reads its content, and automatically closes it."},
+        {"role": "user", "content": "What about writing to a file?"},
+        {"role": "assistant", "content": "To write to a file, use the 'w' mode:\n\nwith open('filename.txt', 'w') as f:\n    f.write('Hello, World!')\n\nUse 'a' mode to append instead of overwriting."},
+        {"role": "user", "content": "Can you explain list comprehensions?"},
+        {"role": "assistant", "content": "List comprehensions are a concise way to create lists. Instead of:\n\nresult = []\nfor x in range(10):\n    result.append(x * 2)\n\nYou can write:\n\nresult = [x * 2 for x in range(10)]"},
     ]
     
-    for name, desc in strategies:
-        print(f"  {name}: {desc}")
+    print(f"\n--- Original Messages ---")
+    print(f"  Message count: {len(messages)}")
     
     # ==========================================================================
-    # Agent with Context Compaction via context= param
+    # Basic Compaction
     # ==========================================================================
-    print("\n--- Creating Agent with Context Compaction ---")
+    print("\n--- Basic Compaction (Truncate Strategy) ---")
     
-    # Use context= parameter with ManagerConfig for compaction
-    agent = Agent(
-        name="LongChat",
-        instructions="You are a helpful assistant for extended conversations.",
-        context=ManagerConfig(
-            auto_compact=True,
-            compact_threshold=0.8,
-            strategy="sliding_window",
-        )
+    compactor = ContextCompactor(
+        max_tokens=50,  # Low limit to trigger compaction
+        strategy=CompactionStrategy.TRUNCATE,
+        preserve_system=True,
+        preserve_recent=2
     )
     
-    print(f"Agent: {agent.name}")
-    print(f"Context manager: {agent.context_manager is not None}")
-    if agent.context_manager:
-        print(f"Auto-compact: {agent.context_manager.config.auto_compact}")
-        print(f"Threshold: {agent.context_manager.config.compact_threshold}")
-        print(f"Strategy: {agent.context_manager.config.strategy}")
+    # Check stats before
+    stats = compactor.get_stats(messages)
+    print(f"  Total tokens: {stats['total_tokens']}")
+    print(f"  Max tokens: {stats['max_tokens']}")
+    print(f"  Needs compaction: {stats['needs_compaction']}")
+    
+    # Compact
+    compacted, result = compactor.compact(messages)
+    
+    print(f"\n  After compaction:")
+    print(f"    Messages: {len(messages)} -> {len(compacted)}")
+    print(f"    Tokens: {result.original_tokens} -> {result.compacted_tokens}")
+    print(f"    Saved: {result.tokens_saved} tokens")
+    print(f"    Compression: {result.compression_ratio:.1%}")
     
     # ==========================================================================
-    # Different Strategy Examples via context= param
+    # Sliding Window Strategy
     # ==========================================================================
-    print("\n--- Strategy Examples ---")
+    print("\n--- Sliding Window Strategy ---")
     
-    # Sliding window strategy
-    sliding_agent = Agent(
-        name="SlidingAgent",
-        instructions="You are helpful.",
-        context=ManagerConfig(
-            auto_compact=True,
-            strategy="sliding_window",
-        )
+    compactor = ContextCompactor(
+        max_tokens=50,
+        strategy=CompactionStrategy.SLIDING,
+        preserve_system=True,
+        preserve_recent=3
     )
-    print(f"  Sliding: strategy={sliding_agent.context_manager.config.strategy}")
     
-    # Summarize strategy
-    summarize_agent = Agent(
-        name="SummarizeAgent",
-        instructions="You are helpful.",
-        context=ManagerConfig(
-            auto_compact=True,
-            strategy="summarize",
-        )
-    )
-    print(f"  Summarize: strategy={summarize_agent.context_manager.config.strategy}")
+    compacted, result = compactor.compact(messages)
     
-    # Smart strategy
-    smart_agent = Agent(
-        name="SmartAgent",
-        instructions="You are helpful.",
-        context=ManagerConfig(
-            auto_compact=True,
-            strategy="smart",
-        )
-    )
-    print(f"  Smart: strategy={smart_agent.context_manager.config.strategy}")
+    print(f"  Messages kept: {result.messages_kept}")
+    print(f"  Messages removed: {result.messages_removed}")
+    print(f"  Strategy: {result.strategy_used.value}")
     
     # ==========================================================================
-    # Context Manager Stats Demo
+    # Summarize Strategy
     # ==========================================================================
-    print("\n--- Context Manager Stats Demo ---")
+    print("\n--- Summarize Strategy ---")
     
-    # Access context manager stats
-    if agent.context_manager:
-        stats = agent.context_manager.get_stats()
-        print(f"  Model: {stats.get('model', 'N/A')}")
-        print(f"  Model limit: {stats.get('model_limit', 'N/A')}")
-        print(f"  Output reserve: {stats.get('output_reserve', 'N/A')}")
-        print(f"  Usable budget: {stats.get('usable_budget', 'N/A')}")
-    else:
-        print("  Context manager not initialized")
+    compactor = ContextCompactor(
+        max_tokens=50,
+        strategy=CompactionStrategy.SUMMARIZE,
+        preserve_system=True,
+        preserve_recent=2
+    )
+    
+    compacted, result = compactor.compact(messages)
+    
+    print(f"  Messages kept: {result.messages_kept}")
+    print(f"  Strategy: {result.strategy_used.value}")
+    
+    # Show what messages remain
+    print(f"\n  Remaining message roles:")
+    for msg in compacted:
+        role = msg.get("role", "unknown")
+        content_preview = msg.get("content", "")[:50]
+        print(f"    [{role}] {content_preview}...")
+    
+    # ==========================================================================
+    # No Compaction Needed
+    # ==========================================================================
+    print("\n--- No Compaction Needed ---")
+    
+    compactor = ContextCompactor(
+        max_tokens=10000,  # High limit
+        strategy=CompactionStrategy.TRUNCATE
+    )
+    
+    compacted, result = compactor.compact(messages)
+    
+    print(f"  Was compacted: {result.was_compacted}")
+    print(f"  Messages unchanged: {len(compacted) == len(messages)}")
+    
+    # ==========================================================================
+    # Result Serialization
+    # ==========================================================================
+    print("\n--- Result Serialization ---")
+    
+    compactor = ContextCompactor(max_tokens=50)
+    _, result = compactor.compact(messages)
+    
+    data = result.to_dict()
+    print(f"  Original tokens: {data['original_tokens']}")
+    print(f"  Compacted tokens: {data['compacted_tokens']}")
+    print(f"  Compression ratio: {data['compression_ratio']:.2f}")
     
     print("\n" + "=" * 60)
     print("Demo Complete!")

examples/compare/cli_compare_advanced.py

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

examples/compare/cli_compare_basic.py

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

examples/consolidated_params/README.md

@@ -1,96 +0,0 @@
-# Consolidated Params Examples
-
-Examples demonstrating the **Agent-Centric API** with consolidated parameters.
-
-## Precedence Ladder
-
-```
-Instance > Config > Array > Dict > String > Bool > Default
-```
-
-## Quick Reference
-
-| Feature | Presets | Example |
-|---------|---------|---------|
-| `memory` | file, sqlite, redis, postgres, mem0, mongodb | `memory="sqlite"` |
-| `output` | minimal, normal, verbose, debug, silent | `output="verbose"` |
-| `execution` | fast, balanced, thorough, unlimited | `execution="balanced"` |
-| `planning` | reasoning, read_only, auto | `planning="reasoning"` |
-| `reflection` | minimal, standard, thorough | `reflection="standard"` |
-| `guardrails` | strict, permissive, safety | `guardrails="strict"` |
-| `web` | duckduckgo, tavily, google, bing, serper | `web="duckduckgo"` |
-| `context` | sliding_window, summarize, truncate | `context="sliding_window"` |
-| `autonomy` | suggest, auto_edit, full_auto | `autonomy="suggest"` |
-| `caching` | enabled, disabled, prompt | `caching="prompt"` |
-
-## Examples
-
-### Basic Examples (Single Feature)
-
-| File | Feature | Description |
-|------|---------|-------------|
-| `basic_agent.py` | Agent | Minimal agent with memory |
-| `basic_memory.py` | memory | SQLite memory preset |
-| `basic_output.py` | output | Verbose output preset |
-| `basic_execution.py` | execution | Execution control |
-| `basic_guardrails.py` | guardrails | Callable validator |
-| `basic_reflection.py` | reflection | Self-reflection preset |
-| `basic_web.py` | web | Web search preset |
-| `basic_planning.py` | planning | Planning preset |
-| `basic_autonomy.py` | autonomy | Autonomy preset |
-| `basic_caching.py` | caching | Caching preset |
-| `basic_knowledge.py` | knowledge | RAG with sources |
-| `basic_context.py` | context | Context management |
-| `basic_hooks.py` | hooks | Lifecycle callbacks |
-
-### Multi-Agent Examples
-
-| File | Description |
-|------|-------------|
-| `basic_agents.py` | Multi-agent with memory and planning |
-
-### Workflow Examples
-
-| File | Description |
-|------|-------------|
-| `basic_workflow.py` | Simple workflow with output preset |
-| `basic_workflow_agentlike.py` | Workflow with agent-like params |
-| `basic_step_override.py` | Step-level param overrides |
-| `advanced_workflow_full_features.py` | All consolidated params |
-
-### Advanced Examples
-
-| File | Description |
-|------|-------------|
-| `advanced_output_execution.py` | Combined output + execution |
-
-## Usage Forms
-
-Each consolidated param supports multiple input forms:
-
-```python
-# Bool - enable with defaults
-memory=True
-
-# String preset
-memory="sqlite"
-
-# Dict config
-memory={"backend": "sqlite", "user_id": "user123"}
-
-# Config instance
-memory=MemoryConfig(backend="sqlite", user_id="user123")
-
-# Array with overrides (for some params)
-guardrails=["strict", {"max_retries": 10}]
-```
-
-## Running Examples
-
-```bash
-# Set API key
-export OPENAI_API_KEY=your_key_here
-
-# Run any example
-python basic_agent.py
-```

examples/consolidated_params/advanced_memory.py

@@ -1,23 +0,0 @@
-"""Advanced memory example - with config and overrides."""
-from praisonaiagents import Agent, MemoryConfig
-
-# With full config
-agent = Agent(
-    instructions="You are a helpful assistant with memory.",
-    memory=MemoryConfig(
-        backend="redis",
-        user_id="user123",
-        session_id="session456",
-        auto_memory=True,
-    ),
-)
-
-# With array [preset, overrides]
-agent_override = Agent(
-    instructions="You are a helpful assistant.",
-    memory=["redis", {"user_id": "custom_user"}],
-)
-
-if __name__ == "__main__":
-    response = agent.chat("Remember that my favorite color is blue.")
-    print(response)

examples/consolidated_params/advanced_output_execution.py

@@ -1,17 +0,0 @@
-"""
-Advanced Output + Execution Example - Agent-Centric API
-
-Demonstrates preset + override array syntax.
-"""
-
-from praisonaiagents import Agent
-
-# Advanced: Preset with overrides using array syntax
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    output=["verbose", {"stream": True, "metrics": True}],
-    execution=["thorough", {"max_iter": 30}],
-)
-
-response = agent.start("Explain quantum computing in simple terms.")
-print(response)

examples/consolidated_params/advanced_workflow_full_features.py

@@ -1,55 +0,0 @@
-"""Advanced Workflow with all consolidated params configured."""
-from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
-from praisonaiagents.workflows.workflow_configs import (
-    WorkflowOutputConfig, WorkflowPlanningConfig, WorkflowMemoryConfig,
-)
-
-# Full-featured workflow with all consolidated params
-workflow = AgentFlow(
-    name="FullFeaturedWorkflow",
-    description="Demonstrates all agent-like consolidated params",
-    steps=[
-        Task(
-            name="researcher",
-            action="Research: {{input}}",
-            agent=Agent(instructions="You are a researcher."),
-            knowledge=["research_docs/"],  # Step-specific knowledge
-            web="duckduckgo",  # Use DuckDuckGo for this step
-        ),
-        Task(
-            name="analyzer",
-            action="Analyze the research",
-            agent=Agent(instructions="You are an analyst."),
-            reflection="thorough",  # Thorough reflection for analysis
-            guardrails="strict",  # Strict validation
-        ),
-        Task(
-            name="writer",
-            action="Write the final report",
-            agent=Agent(instructions="You are a writer."),
-            autonomy=True,  # Enable autonomy for writing
-        ),
-    ],
-    # Workflow-level consolidated params
-    output=WorkflowOutputConfig(output="verbose", stream=True),
-    planning=WorkflowPlanningConfig(enabled=True, reasoning=True),
-    memory=WorkflowMemoryConfig(backend="file"),
-    # Agent-like params
-    autonomy=True,
-    knowledge=["shared_docs/"],
-    guardrails=True,
-    web=True,
-    reflection=True,
-)
-
-if __name__ == "__main__":
-    print(f"Workflow: {workflow.name}")
-    print(f"Output verbose: {workflow._verbose}")
-    print(f"Planning enabled: {workflow._planning_enabled}")
-    print(f"Memory config: {workflow._memory_config}")
-    print(f"Autonomy: {workflow.autonomy}")
-    print(f"Knowledge: {workflow.knowledge}")
-    print(f"Guardrails: {workflow.guardrails}")
-    print(f"Web: {workflow.web}")
-    print(f"Reflection: {workflow.reflection}")

examples/consolidated_params/basic_agent.py

@@ -1,12 +0,0 @@
-"""Basic Agent example with consolidated params."""
-from praisonaiagents import Agent
-
-# Minimal agent with memory
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    memory=True,
-)
-
-if __name__ == "__main__":
-    response = agent.chat("Hello!")
-    print(response)

examples/consolidated_params/basic_agents.py

@@ -1,17 +0,0 @@
-"""Basic Agents (multi-agent) example with consolidated params."""
-from praisonaiagents import Agent, AgentTeam
-
-# Create agents
-writer = Agent(instructions="You write content.")
-editor = Agent(instructions="You edit content.")
-
-# Multi-agent with consolidated params
-agents = AgentTeam(
-    agents=[writer, editor],
-    memory=True,
-    planning=True,
-)
-
-if __name__ == "__main__":
-    result = agents.start("Write a haiku about AI")
-    print(result)

examples/consolidated_params/basic_autonomy.py

@@ -1,18 +0,0 @@
-"""
-Basic Autonomy Example - Agent-Centric API
-
-Demonstrates autonomy with consolidated params.
-Presets: suggest, auto_edit, full_auto
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable autonomy with preset
-agent = Agent(
-    instructions="You are an autonomous assistant.",
-    autonomy="suggest",  # Presets: suggest, auto_edit, full_auto
-)
-
-if __name__ == "__main__":
-    response = agent.start("Help me organize my project files.")
-    print(response)

examples/consolidated_params/basic_caching.py

@@ -1,23 +0,0 @@
-"""
-Basic Caching Example - Agent-Centric API
-
-Demonstrates caching with consolidated params.
-Presets: enabled, disabled, prompt
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable caching with preset
-agent = Agent(
-    instructions="You are a helpful assistant with caching enabled.",
-    caching="prompt",  # Presets: enabled, disabled, prompt
-)
-
-if __name__ == "__main__":
-    # First call - will cache
-    response = agent.start("What is the capital of France?")
-    print(response)
-    
-    # Second call - may use cache
-    response = agent.start("What is the capital of France?")
-    print(response)

examples/consolidated_params/basic_context.py

@@ -1,18 +0,0 @@
-"""
-Basic Context Example - Agent-Centric API
-
-Demonstrates context management with consolidated params.
-Presets: sliding_window, summarize, truncate
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable context management with preset
-agent = Agent(
-    instructions="You are a helpful assistant with context management.",
-    context="sliding_window",  # Presets: sliding_window, summarize, truncate
-)
-
-if __name__ == "__main__":
-    response = agent.start("Tell me a long story about a dragon.")
-    print(response)

examples/consolidated_params/basic_execution.py

@@ -1,16 +0,0 @@
-"""
-Basic Execution Example - Agent-Centric API
-
-Demonstrates execution preset usage.
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Use fast execution preset
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    execution="fast",  # Presets: fast, balanced, thorough, unlimited
-)
-
-response = agent.start("What is the capital of France?")
-print(response)

examples/consolidated_params/basic_guardrails.py

@@ -1,26 +0,0 @@
-"""
-Basic Guardrails Example - Agent-Centric API
-
-Demonstrates guardrails with callable validator.
-"""
-
-from praisonaiagents import Agent
-
-# Define a simple guardrail validator
-def validate_response(output):
-    """Validate that response doesn't contain forbidden words."""
-    forbidden = ["error", "fail", "cannot"]
-    text = str(output).lower()
-    for word in forbidden:
-        if word in text:
-            return (False, f"Response contains forbidden word: {word}")
-    return (True, output)
-
-# Basic: Use callable guardrail
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    guardrails=validate_response,
-)
-
-response = agent.start("What is 2 + 2?")
-print(response)

examples/consolidated_params/basic_hooks.py

@@ -1,28 +0,0 @@
-"""
-Basic Hooks Example - Agent-Centric API
-
-Demonstrates lifecycle hooks with consolidated params.
-Valid keys: on_step, on_tool_call, middleware
-"""
-
-from praisonaiagents import Agent
-
-# Define hook callbacks
-def on_step_callback(step_info):
-    print(f"Step: {step_info}")
-
-def on_tool_call_callback(tool_info):
-    print(f"Tool called: {tool_info}")
-
-# Basic: Enable hooks with dict
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    hooks={
-        "on_step": on_step_callback,
-        "on_tool_call": on_tool_call_callback,
-    },
-)
-
-if __name__ == "__main__":
-    response = agent.start("What is 2 + 2?")
-    print(response)

examples/consolidated_params/basic_knowledge.py

@@ -1,18 +0,0 @@
-"""
-Basic Knowledge (RAG) Example - Agent-Centric API
-
-Demonstrates knowledge with consolidated params.
-Supports: bool, list of sources, dict config, KnowledgeConfig
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable knowledge with list of sources
-agent = Agent(
-    instructions="You are a helpful assistant with document knowledge.",
-    knowledge=["docs/"],  # List of file/folder paths
-)
-
-if __name__ == "__main__":
-    response = agent.start("What does the documentation say about installation?")
-    print(response)

examples/consolidated_params/basic_memory.py

@@ -1,24 +0,0 @@
-"""Basic memory example - minimal usage."""
-from praisonaiagents import Agent
-
-# Simple enable (uses default file-based memory)
-agent = Agent(
-    instructions="You are a helpful assistant with memory.",
-    memory=True,
-)
-
-# With preset
-agent_redis = Agent(
-    instructions="You are a helpful assistant.",
-    memory="redis",  # Uses redis preset
-)
-
-# 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)

examples/consolidated_params/basic_output.py

@@ -1,16 +0,0 @@
-"""
-Basic Output Example - Agent-Centric API
-
-Demonstrates output preset usage.
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Use verbose output preset
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    output="verbose",  # Presets: minimal, normal, verbose, debug, silent
-)
-
-response = agent.start("What is 2 + 2?")
-print(response)

examples/consolidated_params/basic_output_execution.py

@@ -1,13 +0,0 @@
-"""Basic output and execution example."""
-from praisonaiagents import Agent
-
-# Simple preset usage
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    output="verbose",  # Preset: verbose output
-    execution="thorough",  # Preset: thorough execution
-)
-
-if __name__ == "__main__":
-    response = agent.chat("What is 2+2?")
-    print(response)

examples/consolidated_params/basic_planning.py

@@ -1,18 +0,0 @@
-"""
-Basic Planning Example - Agent-Centric API
-
-Demonstrates planning with consolidated params.
-Presets: reasoning, read_only, auto
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable planning with preset
-agent = Agent(
-    instructions="You are a strategic planner.",
-    planning="reasoning",  # Presets: reasoning, read_only, auto
-)
-
-if __name__ == "__main__":
-    response = agent.start("Plan a 3-day trip to Tokyo.")
-    print(response)

examples/consolidated_params/basic_reflection.py

@@ -1,18 +0,0 @@
-"""
-Basic Reflection Example - Agent-Centric API
-
-Demonstrates reflection (self-reflect) with consolidated params.
-Presets: minimal, standard, thorough
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable reflection with preset
-agent = Agent(
-    instructions="You are a helpful assistant that reflects on your answers.",
-    reflection="standard",  # Presets: minimal, standard, thorough
-)
-
-if __name__ == "__main__":
-    response = agent.start("Explain quantum computing in simple terms.")
-    print(response)

examples/consolidated_params/basic_step_override.py

@@ -1,33 +0,0 @@
-"""Basic example showing step-level override of workflow defaults."""
-from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
-
-# Workflow with defaults
-workflow = AgentFlow(
-    name="StepOverrideWorkflow",
-    steps=[
-        Task(
-            name="step1",
-            action="Process with workflow defaults",
-            agent=Agent(instructions="You are a processor."),
-            # Uses workflow-level web=True (inherited)
-        ),
-        Task(
-            name="step2",
-            action="Process with step override",
-            agent=Agent(instructions="You are a processor."),
-            # Override workflow default
-            web=False,  # Disable web for this step
-            reflection="thorough",  # Use thorough reflection preset
-        ),
-    ],
-    # Workflow defaults
-    web=True,
-    reflection=True,
-)
-
-if __name__ == "__main__":
-    print(f"Workflow web default: {workflow.web}")
-    print(f"Step1 web: {workflow.steps[0].web}")  # None (uses workflow default)
-    print(f"Step2 web: {workflow.steps[1].web}")  # False (overridden)
-    print(f"Step2 reflection: {workflow.steps[1].reflection}")  # thorough

examples/consolidated_params/basic_web.py

@@ -1,18 +0,0 @@
-"""
-Basic Web Search Example - Agent-Centric API
-
-Demonstrates web search with consolidated params.
-Presets: duckduckgo, tavily, google, bing, serper, search_only, fetch_only
-"""
-
-from praisonaiagents import Agent
-
-# Basic: Enable web search with preset
-agent = Agent(
-    instructions="You are a research assistant with web access.",
-    web="duckduckgo",  # Presets: duckduckgo, tavily, google, bing, serper
-)
-
-if __name__ == "__main__":
-    response = agent.start("What are the latest AI developments in 2024?")
-    print(response)

examples/consolidated_params/basic_workflow.py

@@ -1,22 +0,0 @@
-"""Basic workflow example with consolidated params."""
-from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
-
-# Create agents
-writer = Agent(instructions="You are a content writer.")
-editor = Agent(instructions="You are an editor.")
-
-# Create workflow with consolidated params
-workflow = AgentFlow(
-    name="Content Pipeline",
-    steps=[
-        Task(name="write", agent=writer, action="Write about {{topic}}"),
-        Task(name="edit", agent=editor, action="Edit the content", context=["write"]),
-    ],
-    output="verbose",
-    planning=True,
-)
-
-if __name__ == "__main__":
-    result = workflow.run(variables={"topic": "AI agents"})
-    print(result)

examples/consolidated_params/basic_workflow_agentlike.py

@@ -1,32 +0,0 @@
-"""Basic Workflow with Agent-like consolidated params."""
-from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
-
-# Workflow with agent-like params (knowledge, web, guardrails, reflection)
-workflow = AgentFlow(
-    name="AgentLikeWorkflow",
-    steps=[
-        Task(
-            name="researcher",
-            action="Research the topic: {{input}}",
-            agent=Agent(instructions="You are a researcher."),
-        ),
-        Task(
-            name="writer",
-            action="Write about the research findings",
-            agent=Agent(instructions="You are a writer."),
-        ),
-    ],
-    # Agent-like consolidated params
-    knowledge=["docs/"],  # Enable RAG
-    web=True,  # Enable web search
-    guardrails=True,  # Enable guardrails
-    reflection=True,  # Enable self-reflection
-)
-
-if __name__ == "__main__":
-    print(f"Workflow: {workflow.name}")
-    print(f"Knowledge: {workflow.knowledge}")
-    print(f"Web: {workflow.web}")
-    print(f"Guardrails: {workflow.guardrails}")
-    print(f"Reflection: {workflow.reflection}")

examples/context/00_agent_fast_context_basic.py

@@ -1,71 +1,87 @@
 """
-Fast Context - Basic Example
+Fast Context with Agent - Basic Example
 
-FastContext provides rapid code search capabilities.
-Use it directly from the context module for code search.
+This is the simplest way to use Fast Context with an Agent.
+Just set fast_context=True and the agent will automatically
+have access to rapid code search capabilities.
 
-FastContext provides:
+Fast Context provides:
 - 10-20x faster code search than traditional methods
 - Parallel execution (8 concurrent searches)
 - Automatic caching for repeated queries
-
-Note: FastContext is now accessed via the context module directly,
-not as Agent parameters. For context management with agents,
-use Agent(context=True) or Agent(context=ManagerConfig(...)).
+- Seamless integration with Agent workflows
 """
 
 from praisonaiagents import Agent
-from praisonaiagents.context import ManagerConfig
 
 def main():
     print("=" * 60)
-    print("Agent with Context Management - Basic Example")
+    print("Agent with Fast Context - Basic Example")
     print("=" * 60)
     
-    # Create an agent with context management enabled
-    # This is the recommended way to use context features
+    # Create an agent with Fast Context enabled
+    # This is the simplest configuration
     agent = Agent(
         name="CodeAssistant",
         instructions="You are a helpful code assistant.",
-        context=True,  # Enable context management with defaults
+        fast_context=True,  # Enable Fast Context
+        fast_context_path=".",  # Search in current directory
+        verbose=False
     )
     
-    print("\n✓ Agent created with context management enabled")
-    print(f"  - context_manager: {agent.context_manager is not None}")
-    if agent.context_manager:
-        print(f"  - auto_compact: {agent.context_manager.config.auto_compact}")
-        print(f"  - strategy: {agent.context_manager.config.strategy}")
+    print("\n✓ Agent created with Fast Context enabled")
+    print(f"  - fast_context_enabled: {agent.fast_context_enabled}")
+    print(f"  - fast_context_path: {agent.fast_context_path}")
+    print(f"  - fast_context_model: {agent.fast_context_model}")
     
-    # For FastContext code search, use the module directly
+    # Use delegate_to_fast_context to search code
     print("\n" + "-" * 60)
-    print("Using FastContext for code search...")
+    print("Searching for 'class Agent' in the codebase...")
     print("-" * 60)
     
-    try:
-        from praisonaiagents.context.fast import FastContext
-        
-        fc = FastContext(
-            workspace_path=".",
-            model="gpt-4o-mini",
-            max_turns=4,
-            max_parallel=8,
-        )
-        
-        result = fc.search("class Agent")
-        print(f"\n✓ Search for 'class Agent':")
+    context = agent.delegate_to_fast_context("class Agent")
+    
+    if context:
+        print(f"\n✓ Found relevant code!")
+        print(f"  Context length: {len(context)} characters")
+        print("\nPreview of found context:")
+        print("-" * 40)
+        # Show first 500 characters
+        preview = context[:500]
+        print(preview)
+        if len(context) > 500:
+            print("...")
+    else:
+        print("\n✗ No relevant code found")
+    
+    # Another search example
+    print("\n" + "-" * 60)
+    print("Searching for 'def chat' in the codebase...")
+    print("-" * 60)
+    
+    context = agent.delegate_to_fast_context("def chat")
+    
+    if context:
+        print(f"\n✓ Found relevant code!")
+        print(f"  Context length: {len(context)} characters")
+    else:
+        print("\n✗ No relevant code found")
+    
+    # Access FastContext directly for more control
+    print("\n" + "-" * 60)
+    print("Direct FastContext access for advanced usage...")
+    print("-" * 60)
+    
+    fc = agent.fast_context
+    if fc:
+        result = fc.search("import")
+        print(f"\n✓ Direct search for 'import':")
         print(f"  Files found: {result.total_files}")
         print(f"  Search time: {result.search_time_ms}ms")
-        
-        if result.total_files > 0:
-            context = fc.get_context_for_agent("class Agent")
-            print(f"  Context length: {len(context)} characters")
-    except ImportError:
-        print("\n⚠ FastContext not available (optional feature)")
-    except Exception as e:
-        print(f"\n⚠ FastContext search failed: {e}")
+        print(f"  From cache: {result.from_cache}")
     
     print("\n" + "=" * 60)
-    print("Context management is now unified via context= param!")
+    print("Fast Context makes code search instant for your agents!")
     print("=" * 60)
 
 

examples/context/01_basic_context.py

@@ -1,59 +0,0 @@
-"""
-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()}")

examples/context/02_session_tracking.py

@@ -1,71 +0,0 @@
-"""
-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}")

examples/context/03_multi_memory.py

@@ -1,81 +0,0 @@
-"""
-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}")

examples/context/04_agent_integration.py

@@ -1,98 +1,103 @@
 """
-Example 4: Agent Integration with Context Management
+Example 4: Agent Integration with Fast Context
 
-This example shows how to use context management with the Agent class.
-Context management is now unified via the context= parameter.
+This example shows how to use Fast Context integrated with the Agent class
+for automatic code search delegation.
 
 Benefits:
 - Seamless integration with existing Agent workflows
-- Automatic token tracking and optimization
-- Configurable via context= parameter with ManagerConfig
+- Automatic context injection for code-related queries
+- Configurable via Agent parameters or environment variables
 """
 
 from praisonaiagents import Agent
-from praisonaiagents.context import ManagerConfig
 
 WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
 
 
 def main():
     print("=" * 70)
-    print("Agent Integration with Context Management")
+    print("Agent Integration with Fast Context")
     print("=" * 70)
     
-    # Create an agent with context management enabled
-    print("\n1. Creating Agent with Context Management")
+    # Create an agent with Fast Context enabled
+    print("\n1. Creating Agent with Fast Context")
     print("-" * 40)
     
-    config = ManagerConfig(
-        auto_compact=True,
-        compact_threshold=0.8,
-        strategy="smart",
-        monitor_enabled=True,
-        monitor_path="./context_debug.txt",
-    )
-    
     agent = Agent(
         name="CodeAssistant",
-        instructions="You are a helpful code assistant.",
-        context=config,
-        output="silent"
+        instructions="You are a helpful code assistant that can search and analyze code.",
+        fast_context=True,
+        fast_context_path=WORKSPACE,
+        fast_context_model="gpt-4o-mini",
+        fast_context_max_turns=4,
+        fast_context_parallelism=8,
+        fast_context_timeout=30.0,
+        verbose=False
     )
     
     print(f"   Agent name: {agent.name}")
-    print(f"   Context manager: {agent.context_manager is not None}")
-    if agent.context_manager:
-        print(f"   Auto-compact: {agent.context_manager.config.auto_compact}")
-        print(f"   Threshold: {agent.context_manager.config.compact_threshold}")
-        print(f"   Strategy: {agent.context_manager.config.strategy}")
+    print(f"   Fast Context enabled: {agent.fast_context_enabled}")
+    print(f"   Fast Context path: {agent.fast_context_path}")
+    print(f"   Fast Context model: {agent.fast_context_model}")
+    print(f"   Max turns: {agent.fast_context_max_turns}")
+    print(f"   Parallelism: {agent.fast_context_parallelism}")
     
-    # For FastContext code search, use the module directly
-    print("\n2. Using FastContext for Code Search")
+    # Use delegate_to_fast_context for code search
+    print("\n2. Delegating Code Search to Fast Context")
     print("-" * 40)
     
-    try:
-        from praisonaiagents.context.fast import FastContext
+    queries = [
+        "find the Agent class definition",
+        "search for authentication handlers",
+        "locate memory management code",
+    ]
+    
+    for query in queries:
+        print(f"\n   Query: '{query}'")
+        context = agent.delegate_to_fast_context(query)
         
-        fc = FastContext(
-            workspace_path=WORKSPACE,
-            model="gpt-4o-mini",
-            max_turns=4,
-            max_parallel=8,
-            timeout=30.0,
-        )
+        if context:
+            # Show preview of context
+            lines = context.split('\n')
+            preview_lines = lines[:5]
+            print(f"   Found context ({len(context)} chars):")
+            for line in preview_lines:
+                print(f"      {line[:60]}{'...' if len(line) > 60 else ''}")
+            if len(lines) > 5:
+                print(f"      ... and {len(lines) - 5} more lines")
+        else:
+            print("   No relevant code found")
+    
+    # Access the FastContext instance directly
+    print("\n3. Direct FastContext Access")
+    print("-" * 40)
+    
+    fc = agent.fast_context
+    if fc:
+        result = fc.search("def chat")
+        print(f"   Direct search for 'def chat':")
+        print(f"   Files found: {result.total_files}")
+        print(f"   Search time: {result.search_time_ms}ms")
         
-        queries = [
-            "find the Agent class definition",
-            "search for chat method",
-        ]
-        
-        for query in queries:
-            print(f"\n   Query: '{query}'")
-            result = fc.search(query)
-            print(f"   Files found: {result.total_files}")
-            print(f"   Search time: {result.search_time_ms}ms")
-            
-    except ImportError:
-        print("   FastContext not available (optional feature)")
-    except Exception as e:
-        print(f"   FastContext error: {e}")
+        for f in result.files[:3]:
+            print(f"   - {f.path}")
     
     # Show configuration options
-    print("\n3. Configuration Options")
+    print("\n4. Configuration Options")
     print("-" * 40)
     
-    print("   Agent context= parameter:")
-    print("   - context=True                   # Enable with defaults")
-    print("   - context=ManagerConfig(...)     # Custom configuration")
-    print("   - context=False                  # Disabled (default)")
+    print("   Agent parameters:")
+    print("   - fast_context=True              # Enable Fast Context")
+    print("   - fast_context_path='.'          # Workspace path")
+    print("   - fast_context_model='gpt-4o-mini'  # Search model")
+    print("   - fast_context_max_turns=4       # Max search turns")
+    print("   - fast_context_parallelism=8     # Parallel calls")
+    print("   - fast_context_timeout=30.0      # Timeout (seconds)")
     
-    print("\n   ManagerConfig options:")
-    print("   - auto_compact=True              # Auto-optimize context")
-    print("   - compact_threshold=0.8          # Trigger at 80%")
-    print("   - strategy='smart'               # Optimization strategy")
-    print("   - monitor_enabled=True           # Write snapshots")
-    print("   - monitor_path='./context.txt'   # Snapshot path")
+    print("\n   Environment variables:")
+    print("   - FAST_CONTEXT_MODEL")
+    print("   - FAST_CONTEXT_MAX_TURNS")
     print("   - FAST_CONTEXT_PARALLELISM")
     print("   - FAST_CONTEXT_TIMEOUT")
     print("   - FAST_CONTEXT_CACHE")

examples/context/04_compaction_strategies.py

@@ -1,76 +0,0 @@
-"""
-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)")

examples/context/05_monitoring.py

@@ -1,85 +0,0 @@
-"""
-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")

examples/context/09_context_budgeting.py

@@ -1,209 +0,0 @@
-#!/usr/bin/env python3
-"""
-Context Budgeting Example
-
-Demonstrates how to use context budgeting with Agent via context= param,
-and also shows low-level ContextBudgeter usage for advanced scenarios.
-
-Agent-Centric Quick Start:
-    from praisonaiagents import Agent
-    from praisonaiagents.context import ManagerConfig
-    
-    agent = Agent(
-        instructions="You are helpful.",
-        context=ManagerConfig(output_reserve=16000),  # Custom output reserve
-    )
-"""
-
-from praisonaiagents import Agent
-from praisonaiagents.context import (
-    ManagerConfig,
-    ContextBudgeter,
-    BudgetAllocation,
-    get_model_limit,
-    get_output_reserve,
-)
-
-
-def agent_centric_example():
-    """Agent-centric usage - recommended approach."""
-    print("=" * 60)
-    print("Agent-Centric Context Budgeting")
-    print("=" * 60)
-    
-    # Simple: Enable context management with defaults
-    agent = Agent(
-        instructions="You are a helpful assistant.",
-        context=True,
-    )
-    print(f"Agent with context=True created")
-    print(f"Context manager: {agent.context_manager is not None}")
-    
-    # Custom: Specify output reserve
-    agent2 = Agent(
-        instructions="You are a code assistant.",
-        context=ManagerConfig(output_reserve=16000),
-    )
-    print(f"Agent with custom output_reserve created")
-    if agent2.context_manager:
-        stats = agent2.context_manager.get_stats()
-        print(f"Output reserve: {stats.get('output_reserve', 'N/A')}")
-
-
-def main():
-    print("=" * 60)
-    print("Context Budgeting Example")
-    print("=" * 60)
-    
-    # Example 1: Basic budget allocation for GPT-4o-mini
-    print("\n1. Basic Budget Allocation (gpt-4o-mini)")
-    print("-" * 40)
-    
-    budgeter = ContextBudgeter(model="gpt-4o-mini")
-    budget = budgeter.allocate()
-    
-    print(f"Model: gpt-4o-mini")
-    print(f"Model Limit: {budget.model_limit:,} tokens")
-    print(f"Output Reserve: {budget.output_reserve:,} tokens")
-    print(f"Usable Context: {budget.usable:,} tokens")
-    
-    # Example 2: Different models have different limits
-    print("\n2. Model Comparison")
-    print("-" * 40)
-    
-    models = ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo", "claude-3-opus", "gemini-1.5-pro"]
-    
-    for model in models:
-        limit = get_model_limit(model)
-        reserve = get_output_reserve(model)
-        print(f"{model:20s}: {limit:>10,} tokens (reserve: {reserve:,})")
-    
-    # Example 3: Custom segment budgets
-    print("\n3. Custom Segment Budgets")
-    print("-" * 40)
-    
-    budgeter = ContextBudgeter(
-        model="gpt-4o",
-        system_prompt_budget=2000,
-        rules_budget=1000,
-        skills_budget=500,
-        memory_budget=5000,
-        tools_schema_budget=3000,
-    )
-    budget = budgeter.allocate()
-    
-    print(f"System prompt budget: 2,000 tokens")
-    print(f"Rules budget: 1,000 tokens")
-    print(f"Skills budget: 500 tokens")
-    print(f"Memory budget: 5,000 tokens")
-    print(f"Tools schema budget: 3,000 tokens")
-    print(f"Total usable: {budget.usable:,} tokens")
-    
-    # Example 4: Check for overflow
-    print("\n4. Overflow Detection")
-    print("-" * 40)
-    
-    budgeter = ContextBudgeter(model="gpt-4o-mini")
-    
-    # Simulate different usage levels
-    test_cases = [
-        ("Low usage", 10000),
-        ("Medium usage", 80000),
-        ("High usage", 100000),
-        ("Near limit", 110000),
-        ("Over limit", 130000),
-    ]
-    
-    for name, tokens in test_cases:
-        overflow = budgeter.check_overflow(tokens)
-        utilization = budgeter.get_utilization(tokens)
-        remaining = budgeter.get_remaining(tokens)
-        status = "⚠️ OVERFLOW" if overflow else "✓ OK"
-        print(f"{name:15s}: {tokens:>7,} tokens | {utilization:>5.1%} | {status}")
-    
-    # Example 5: Budget to dict for serialization
-    print("\n5. Budget Serialization")
-    print("-" * 40)
-    
-    budget_dict = budgeter.to_dict()
-    print(f"Budget as dict: {budget_dict}")
-    
-    # Example 6: Overflow handling strategies overview
-    print("\n6. Overflow Handling Strategies")
-    print("-" * 40)
-    strategies = [
-        ("truncate", "Remove oldest messages first", "Fast, simple", "Loses early context"),
-        ("sliding_window", "Keep N most recent messages", "Preserves recent", "Loses early context"),
-        ("prune_tools", "Truncate old tool outputs", "Keeps messages", "May lose tool details"),
-        ("summarize", "Replace old messages with summary", "Preserves meaning", "Slower, uses API"),
-        ("smart", "Combine strategies intelligently", "Best balance", "More complex"),
-    ]
-    print(f"{'Strategy':<15} | {'Description':<30} | {'Pros':<18} | {'Cons'}")
-    print("-" * 90)
-    for name, desc, pros, cons in strategies:
-        print(f"{name:<15} | {desc:<30} | {pros:<18} | {cons}")
-    
-    # Example 7: Simulated overflow playbook
-    print("\n7. Overflow Playbook (Thresholds → Actions)")
-    print("-" * 40)
-    playbook = [
-        (0.70, "INFO", "Monitor usage, no action needed"),
-        (0.80, "NOTICE", "Consider optimization soon"),
-        (0.90, "WARNING", "Trigger auto-compact if enabled"),
-        (0.95, "CRITICAL", "Aggressive optimization required"),
-        (1.00, "OVERFLOW", "Immediate truncation to prevent API error"),
-    ]
-    print(f"{'Usage':<8} | {'Level':<10} | {'Action'}")
-    print("-" * 60)
-    for threshold, level, action in playbook:
-        print(f"{threshold:>6.0%}   | {level:<10} | {action}")
-    
-    # Example 8: Strategy comparison table
-    print("\n8. Strategy Comparison")
-    print("-" * 40)
-    print("Strategy         | Preserves      | Loses          | Best For")
-    print("-" * 70)
-    print("truncate         | Recent msgs    | Old msgs       | Simple chats")
-    print("sliding_window   | Last N msgs    | Earlier msgs   | Long conversations")
-    print("prune_tools      | All messages   | Tool details   | Tool-heavy agents")
-    print("summarize        | Context meaning| Exact wording  | Important history")
-    print("smart            | Balanced       | Minimal        | Production use")
-    
-    # Example 9: Default strategy for interactive mode
-    print("\n9. Default Strategy: Interactive Mode")
-    print("-" * 40)
-    print("Interactive mode default: context=False (zero overhead)")
-    print("To enable context management in interactive mode:")
-    print("  praisonai chat --context  # Enable with defaults")
-    print("  Or in code:")
-    print("    agent = Agent(instructions='...', context=True)")
-    print("")
-    print("When enabled, defaults are:")
-    print("  - auto_compact: True")
-    print("  - compact_threshold: 0.8 (80% usage)")
-    print("  - strategy: smart")
-    print("  - output_reserve: model-specific (8K-16K)")
-    
-    # Example 10: Default strategy for auto-agents mode
-    print("\n10. Default Strategy: Auto-Agents Mode")
-    print("-" * 40)
-    print("Auto-agents mode default: context=False (zero overhead)")
-    print("To enable for multi-agent workflows:")
-    print("    from praisonaiagents import AgentTeam")
-    print("    agents = AgentTeam(agents=[...], context=True)")
-    print("")
-    print("Recommended config for long tasks:")
-    print("    context=ManagerConfig(")
-    print("        auto_compact=True,")
-    print("        compact_threshold=0.7,  # Earlier trigger for safety")
-    print("        strategy='smart',")
-    print("        output_reserve=16384,   # Larger reserve for complex outputs")
-    print("    )")
-    
-    print("\n" + "=" * 60)
-    print("✓ Context budgeting examples complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/10_context_monitoring.py

@@ -1,220 +0,0 @@
-#!/usr/bin/env python3
-"""
-Context Monitoring Example
-
-Demonstrates how to use context monitoring with Agent via context= param,
-and also shows low-level ContextMonitor usage for advanced scenarios.
-
-Agent-Centric Quick Start:
-    from praisonaiagents import Agent
-    from praisonaiagents.context import ManagerConfig
-    
-    agent = Agent(
-        instructions="You are helpful.",
-        context=ManagerConfig(
-            monitor_enabled=True,
-            monitor_path="./debug/context.json",
-        ),
-    )
-"""
-
-import os
-import tempfile
-from praisonaiagents import Agent
-from praisonaiagents.context import (
-    ManagerConfig,
-    ContextMonitor,
-    ContextLedger,
-    BudgetAllocation,
-    format_human_snapshot,
-    format_json_snapshot,
-    redact_sensitive,
-    ContextSnapshot,
-)
-
-
-def agent_centric_example():
-    """Agent-centric usage - recommended approach."""
-    print("=" * 60)
-    print("Agent-Centric Context Monitoring")
-    print("=" * 60)
-    
-    with tempfile.TemporaryDirectory() as tmpdir:
-        monitor_path = os.path.join(tmpdir, "context.json")
-        
-        agent = Agent(
-            instructions="You are a helpful assistant.",
-            context=ManagerConfig(
-                monitor_enabled=True,
-                monitor_path=monitor_path,
-                monitor_format="json",
-            ),
-        )
-        print(f"Agent with monitoring enabled")
-        print(f"Monitor path: {monitor_path}")
-        print(f"Context manager: {agent.context_manager is not None}")
-
-
-def main():
-    print("=" * 60)
-    print("Context Monitoring Example")
-    print("=" * 60)
-    
-    # Sample conversation for demonstration
-    messages = [
-        {"role": "system", "content": "You are a helpful AI assistant."},
-        {"role": "user", "content": "What is the weather like today?"},
-        {"role": "assistant", "content": "I don't have access to real-time weather data."},
-        {"role": "user", "content": "Can you help me write Python code?"},
-        {"role": "assistant", "content": "Of course! I'd be happy to help with Python."},
-    ]
-    
-    # Example 1: Basic monitoring setup
-    print("\n1. Basic Monitor Setup")
-    print("-" * 40)
-    
-    with tempfile.TemporaryDirectory() as tmpdir:
-        context_path = os.path.join(tmpdir, "context.txt")
-        
-        monitor = ContextMonitor(
-            enabled=True,
-            path=context_path,
-            format="human",
-            frequency="turn",
-        )
-        
-        print(f"Monitor enabled: {monitor.enabled}")
-        print(f"Output path: {context_path}")
-        print(f"Format: {monitor.format}")
-        
-        # Create sample ledger and budget
-        ledger = ContextLedger(
-            system_prompt=500,
-            history=2500,
-            tools_schema=300,
-            tool_outputs=1200,
-        )
-        
-        budget = BudgetAllocation(
-            model_limit=128000,
-            output_reserve=8000,
-        )
-        
-        # Write snapshot
-        result_path = monitor.snapshot(
-            ledger=ledger,
-            budget=budget,
-            messages=messages,
-            trigger="turn",
-        )
-        
-        print(f"\n✓ Snapshot written to: {result_path}")
-        
-        # Read and display
-        with open(context_path) as f:
-            content = f.read()
-        print(f"\nSnapshot preview ({len(content)} chars):")
-        print("-" * 40)
-        print(content[:500] + "..." if len(content) > 500 else content)
-    
-    # Example 2: JSON format
-    print("\n\n2. JSON Format Output")
-    print("-" * 40)
-    
-    with tempfile.TemporaryDirectory() as tmpdir:
-        json_path = os.path.join(tmpdir, "context.json")
-        
-        monitor = ContextMonitor(
-            enabled=True,
-            path=json_path,
-            format="json",
-        )
-        
-        monitor.snapshot(
-            ledger=ledger,
-            budget=budget,
-            messages=messages,
-            trigger="manual",
-        )
-        
-        with open(json_path) as f:
-            content = f.read()
-        
-        print(f"JSON snapshot ({len(content)} chars):")
-        print(content[:300] + "..." if len(content) > 300 else content)
-    
-    # Example 3: Sensitive data redaction
-    print("\n\n3. Sensitive Data Redaction")
-    print("-" * 40)
-    
-    sensitive_text = """
-    Here's my API key: sk-proj-abc123def456ghi789
-    And my password is: supersecret123
-    Database connection: postgresql://user:pass@localhost/db
-    """
-    
-    redacted = redact_sensitive(sensitive_text)
-    print("Original text contains sensitive data:")
-    print(f"  - API key pattern found: {'sk-proj-' in sensitive_text}")
-    print(f"  - Password pattern found: {'password' in sensitive_text.lower()}")
-    print("\nAfter redaction:")
-    print(redacted)
-    
-    # Example 4: Monitor frequency options
-    print("\n4. Monitor Frequency Options")
-    print("-" * 40)
-    
-    frequencies = ["turn", "tool_call", "manual", "overflow"]
-    
-    for freq in frequencies:
-        monitor = ContextMonitor(enabled=True, frequency=freq)
-        
-        # Check what triggers writing
-        triggers = {
-            "turn": monitor.should_write("turn"),
-            "tool_call": monitor.should_write("tool_call"),
-            "manual": monitor.should_write("manual"),
-            "overflow": monitor.should_write("overflow"),
-        }
-        
-        active = [k for k, v in triggers.items() if v]
-        print(f"Frequency '{freq}': writes on {active}")
-    
-    # Example 5: Snapshot data structure
-    print("\n5. Snapshot Data Structure")
-    print("-" * 40)
-    
-    snapshot = ContextSnapshot(
-        timestamp="2025-01-07T19:30:00Z",
-        session_id="example-session-123",
-        agent_name="ExampleAgent",
-        model_name="gpt-4o-mini",
-        budget=budget,
-        ledger=ledger,
-        utilization=0.45,
-        warnings=["Context usage at 45%"],
-    )
-    
-    print(f"Snapshot fields:")
-    print(f"  - timestamp: {snapshot.timestamp}")
-    print(f"  - session_id: {snapshot.session_id}")
-    print(f"  - agent_name: {snapshot.agent_name}")
-    print(f"  - model_name: {snapshot.model_name}")
-    print(f"  - utilization: {snapshot.utilization:.1%}")
-    print(f"  - warnings: {snapshot.warnings}")
-    
-    # Format as human-readable
-    human_output = format_human_snapshot(snapshot)
-    print(f"\nHuman-readable format ({len(human_output)} chars)")
-    
-    # Format as JSON
-    json_output = format_json_snapshot(snapshot)
-    print(f"JSON format ({len(json_output)} chars)")
-    
-    print("\n" + "=" * 60)
-    print("✓ Context monitoring examples complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/11_context_optimization.py

@@ -1,177 +0,0 @@
-#!/usr/bin/env python3
-"""
-Context Optimization Example
-
-Demonstrates how to use context optimization with Agent via context= param,
-and also shows low-level optimizer usage for advanced scenarios.
-
-Agent-Centric Quick Start:
-    from praisonaiagents import Agent
-    from praisonaiagents.context import ManagerConfig
-    
-    agent = Agent(
-        instructions="You are helpful.",
-        context=ManagerConfig(
-            auto_compact=True,
-            strategy="smart",  # truncate, sliding_window, summarize, smart
-        ),
-    )
-"""
-
-from praisonaiagents import Agent
-from praisonaiagents.context import (
-    ManagerConfig,
-    get_optimizer,
-    OptimizerStrategy,
-    TruncateOptimizer,
-    SlidingWindowOptimizer,
-    PruneToolsOptimizer,
-    SmartOptimizer,
-    estimate_messages_tokens,
-)
-
-
-def agent_centric_example():
-    """Agent-centric usage - recommended approach."""
-    print("=" * 60)
-    print("Agent-Centric Context Optimization")
-    print("=" * 60)
-    
-    # Enable auto-compaction with smart strategy
-    agent = Agent(
-        instructions="You are a helpful assistant.",
-        context=ManagerConfig(
-            auto_compact=True,
-            compact_threshold=0.8,
-            strategy="smart",
-        ),
-    )
-    print("Agent with auto-compaction enabled")
-    print(f"Strategy: smart")
-    print(f"Threshold: 0.8 (80% of context budget)")
-    print(f"Context manager: {agent.context_manager is not None}")
-
-
-def main():
-    print("=" * 60)
-    print("Context Optimization Example")
-    print("=" * 60)
-    
-    # Create sample conversation with tool calls
-    messages = [
-        {"role": "system", "content": "You are a helpful AI assistant with access to tools."},
-        {"role": "user", "content": "What's the weather in Paris?"},
-        {"role": "assistant", "content": "", "tool_calls": [{"id": "call_1", "function": {"name": "get_weather", "arguments": '{"city": "Paris"}'}}]},
-        {"role": "tool", "tool_call_id": "call_1", "content": "Weather in Paris: 15°C, partly cloudy, humidity 65%, wind 10 km/h from the west. Extended forecast shows temperatures ranging from 12-18°C over the next week with occasional rain expected on Thursday and Friday."},
-        {"role": "assistant", "content": "The weather in Paris is currently 15°C and partly cloudy."},
-        {"role": "user", "content": "What about London?"},
-        {"role": "assistant", "content": "", "tool_calls": [{"id": "call_2", "function": {"name": "get_weather", "arguments": '{"city": "London"}'}}]},
-        {"role": "tool", "tool_call_id": "call_2", "content": "Weather in London: 12°C, overcast with light drizzle, humidity 80%, wind 15 km/h from the southwest. Rain expected to continue throughout the day with temperatures dropping to 8°C overnight."},
-        {"role": "assistant", "content": "London is 12°C with light drizzle."},
-    ]
-    
-    # Add more history to simulate a long conversation
-    for i in range(10):
-        messages.append({"role": "user", "content": f"Question {i}: Can you explain concept number {i} in detail? " * 20})
-        messages.append({"role": "assistant", "content": f"Answer {i}: Here's a detailed explanation of concept {i}. " * 30})
-    
-    original_tokens = estimate_messages_tokens(messages)
-    print(f"\nOriginal conversation: {len(messages)} messages, ~{original_tokens} tokens")
-    
-    # Example 1: Truncate Optimizer
-    print("\n1. Truncate Optimizer")
-    print("-" * 40)
-    
-    optimizer = TruncateOptimizer()
-    result, stats = optimizer.optimize(messages, target_tokens=2000)
-    result_tokens = estimate_messages_tokens(result)
-    
-    print(f"Strategy: Remove oldest messages first")
-    print(f"Result: {len(messages)} -> {len(result)} messages")
-    print(f"Tokens: {original_tokens} -> {result_tokens}")
-    
-    # Example 2: Sliding Window Optimizer
-    print("\n2. Sliding Window Optimizer")
-    print("-" * 40)
-    
-    optimizer = SlidingWindowOptimizer()
-    result, stats = optimizer.optimize(messages, target_tokens=2000)
-    result_tokens = estimate_messages_tokens(result)
-    
-    print(f"Strategy: Keep most recent messages within window")
-    print(f"Result: {len(messages)} -> {len(result)} messages")
-    print(f"Tokens: {original_tokens} -> {result_tokens}")
-    
-    # Example 3: Prune Tools Optimizer
-    print("\n3. Prune Tools Optimizer")
-    print("-" * 40)
-    
-    optimizer = PruneToolsOptimizer()
-    result, stats = optimizer.optimize(messages, target_tokens=2000)
-    result_tokens = estimate_messages_tokens(result)
-    
-    print(f"Strategy: Truncate old tool outputs, preserve recent")
-    print(f"Result: {len(messages)} -> {len(result)} messages")
-    print(f"Tokens: {original_tokens} -> {result_tokens}")
-    
-    # Example 4: Smart Optimizer (combines strategies)
-    print("\n4. Smart Optimizer (Recommended)")
-    print("-" * 40)
-    
-    optimizer = SmartOptimizer()
-    result, stats = optimizer.optimize(messages, target_tokens=2000)
-    result_tokens = estimate_messages_tokens(result)
-    
-    print(f"Strategy: Intelligent combination of all strategies")
-    print(f"Result: {len(messages)} -> {len(result)} messages")
-    print(f"Tokens: {original_tokens} -> {result_tokens}")
-    print(f"Stats: {stats}")
-    
-    # Example 5: Using the factory function
-    print("\n5. Optimizer Factory")
-    print("-" * 40)
-    
-    strategies = [
-        OptimizerStrategy.TRUNCATE,
-        OptimizerStrategy.SLIDING_WINDOW,
-        OptimizerStrategy.PRUNE_TOOLS,
-        OptimizerStrategy.SMART,
-    ]
-    
-    for strategy in strategies:
-        optimizer = get_optimizer(strategy)
-        result, _ = optimizer.optimize(messages, target_tokens=3000)
-        result_tokens = estimate_messages_tokens(result)
-        print(f"{strategy.value:15s}: {len(messages)} -> {len(result)} msgs, ~{result_tokens} tokens")
-    
-    # Example 6: Tool call/result pair preservation
-    print("\n6. Tool Call/Result Pair Preservation")
-    print("-" * 40)
-    
-    tool_messages = [
-        {"role": "system", "content": "You are helpful."},
-        {"role": "user", "content": "Get data"},
-        {"role": "assistant", "content": "", "tool_calls": [{"id": "tc1"}]},
-        {"role": "tool", "tool_call_id": "tc1", "content": "Data result"},
-        {"role": "assistant", "content": "Here's the data."},
-    ]
-    
-    optimizer = SmartOptimizer()
-    result, _ = optimizer.optimize(tool_messages, target_tokens=100)
-    
-    # Check if tool pairs are preserved
-    tool_calls = [m for m in result if m.get("tool_calls")]
-    tool_results = [m for m in result if m.get("role") == "tool"]
-    
-    print(f"Original: {len(tool_messages)} messages")
-    print(f"Optimized: {len(result)} messages")
-    print(f"Tool calls preserved: {len(tool_calls)}")
-    print(f"Tool results preserved: {len(tool_results)}")
-    
-    print("\n" + "=" * 60)
-    print("✓ Context optimization examples complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/12_multi_agent_context.py

@@ -1,194 +0,0 @@
-#!/usr/bin/env python3
-"""
-Multi-Agent Context Isolation Example
-
-Demonstrates how to use multi-agent context with Agents via context= param,
-and also shows low-level MultiAgentLedger usage for advanced scenarios.
-
-Agent-Centric Quick Start:
-    from praisonaiagents import Agent, AgentTeam
-    from praisonaiagents.context import ManagerConfig
-    
-    agents = AgentTeam(
-        agents=[agent1, agent2],
-        context=ManagerConfig(policy="isolated"),  # or "shared"
-    )
-"""
-
-import os
-import tempfile
-from praisonaiagents import Agent, AgentTeam
-from praisonaiagents.context import (
-    ManagerConfig,
-    MultiAgentLedger,
-    MultiAgentMonitor,
-    ContextLedgerManager,
-    ContextMonitor,
-    ContextBudgeter,
-)
-
-
-def agent_centric_example():
-    """Agent-centric usage - recommended approach."""
-    print("=" * 60)
-    print("Agent-Centric Multi-Agent Context")
-    print("=" * 60)
-    
-    # Create agents with context enabled
-    researcher = Agent(
-        name="Researcher",
-        instructions="You are a research specialist.",
-        context=True,
-    )
-    writer = Agent(
-        name="Writer", 
-        instructions="You are a technical writer.",
-        context=True,
-    )
-    
-    # Multi-agent setup with isolated context policy
-    # (each agent maintains its own context)
-    print("Created agents with context=True")
-    print("Use AgentTeam(agents=[...], context=ManagerConfig(policy='isolated'))")
-    print("for multi-agent context isolation")
-
-
-def main():
-    print("=" * 60)
-    print("Multi-Agent Context Isolation Example")
-    print("=" * 60)
-    
-    # Example 1: Multi-Agent Ledger
-    print("\n1. Multi-Agent Ledger")
-    print("-" * 40)
-    
-    multi_ledger = MultiAgentLedger()
-    
-    # Get ledgers for different agents
-    researcher_ledger = multi_ledger.get_agent_ledger("researcher")
-    writer_ledger = multi_ledger.get_agent_ledger("writer")
-    reviewer_ledger = multi_ledger.get_agent_ledger("reviewer")
-    
-    # Track different context for each agent
-    researcher_ledger.track_system_prompt("You are a research specialist.")
-    researcher_ledger.track_history([
-        {"role": "user", "content": "Research AI trends"},
-        {"role": "assistant", "content": "Here are the latest AI trends..."},
-    ])
-    
-    writer_ledger.track_system_prompt("You are a technical writer.")
-    writer_ledger.track_history([
-        {"role": "user", "content": "Write an article about AI"},
-        {"role": "assistant", "content": "# AI in 2025\n\nArtificial Intelligence..."},
-    ])
-    
-    reviewer_ledger.track_system_prompt("You are a content reviewer.")
-    reviewer_ledger.track_history([
-        {"role": "user", "content": "Review this article"},
-        {"role": "assistant", "content": "The article is well-written..."},
-    ])
-    
-    # Check token usage per agent
-    print("Token usage per agent:")
-    for agent_id in multi_ledger.get_agent_ids():
-        ledger = multi_ledger.get_agent_ledger(agent_id)
-        print(f"  {agent_id}: {ledger.get_total()} tokens")
-    
-    # Get combined total
-    total = multi_ledger.get_combined_total()
-    print(f"\nTotal across all agents: {total} tokens")
-    
-    # Example 2: Multi-Agent Monitor
-    print("\n2. Multi-Agent Monitor")
-    print("-" * 40)
-    
-    with tempfile.TemporaryDirectory() as tmpdir:
-        multi_monitor = MultiAgentMonitor(base_path=tmpdir)
-        
-        # Get monitors for each agent
-        for agent_id in ["researcher", "writer", "reviewer"]:
-            monitor = multi_monitor.get_agent_monitor(agent_id)
-            print(f"Monitor for {agent_id}: {monitor.path}")
-        
-        # Enable all monitors
-        multi_monitor.enable_all()
-        print(f"\nAll monitors enabled: {multi_monitor.enabled}")
-        
-        # List all agent IDs
-        agent_ids = multi_monitor.get_agent_ids()
-        print(f"Monitored agents: {agent_ids}")
-    
-    # Example 3: Per-Agent Budgeting
-    print("\n3. Per-Agent Budgeting")
-    print("-" * 40)
-    
-    agents_config = {
-        "researcher": {"model": "gpt-4o", "role": "Research"},
-        "writer": {"model": "gpt-4o-mini", "role": "Writing"},
-        "reviewer": {"model": "gpt-4o-mini", "role": "Review"},
-    }
-    
-    for agent_id, config in agents_config.items():
-        budgeter = ContextBudgeter(model=config["model"])
-        budget = budgeter.allocate()
-        print(f"{agent_id} ({config['model']}): {budget.usable:,} usable tokens")
-    
-    # Example 4: Context Isolation Verification
-    print("\n4. Context Isolation Verification")
-    print("-" * 40)
-    
-    # Create fresh multi-ledger
-    isolated_ledger = MultiAgentLedger()
-    
-    # Agent A tracks some context
-    agent_a = isolated_ledger.get_agent_ledger("agent_a")
-    agent_a.track_system_prompt("Agent A system prompt")
-    agent_a.track_history([{"role": "user", "content": "Message for A"}])
-    
-    # Agent B tracks different context
-    agent_b = isolated_ledger.get_agent_ledger("agent_b")
-    agent_b.track_system_prompt("Agent B system prompt")
-    agent_b.track_history([{"role": "user", "content": "Message for B"}])
-    
-    # Verify isolation
-    print(f"Agent A tokens: {agent_a.get_total()}")
-    print(f"Agent B tokens: {agent_b.get_total()}")
-    print(f"Agents are isolated: {agent_a.get_total() != agent_b.get_total() or True}")
-    
-    # Verify they don't share state
-    agent_a_ledger = agent_a.get_ledger()
-    agent_b_ledger = agent_b.get_ledger()
-    print(f"Agent A system_prompt tokens: {agent_a_ledger.system_prompt}")
-    print(f"Agent B system_prompt tokens: {agent_b_ledger.system_prompt}")
-    
-    # Example 5: Shared Team Memory (Optional)
-    print("\n5. Shared Team Memory Pattern")
-    print("-" * 40)
-    
-    # For shared context, you can use a dedicated "team" ledger
-    team_ledger = MultiAgentLedger()
-    
-    # Shared team memory
-    shared = team_ledger.get_agent_ledger("shared_memory")
-    shared.track_system_prompt("Team goal: Complete the research project by Friday")
-    
-    # Individual agents can reference shared memory
-    agent1 = team_ledger.get_agent_ledger("agent1")
-    agent2 = team_ledger.get_agent_ledger("agent2")
-    
-    # Each agent has their own context plus can access shared
-    agent1.track_system_prompt("You are agent 1")
-    agent2.track_system_prompt("You are agent 2")
-    
-    print(f"Shared memory tokens: {shared.get_total()}")
-    print(f"Agent 1 tokens: {agent1.get_total()}")
-    print(f"Agent 2 tokens: {agent2.get_total()}")
-    print(f"Total team tokens: {team_ledger.get_combined_total()}")
-    
-    print("\n" + "=" * 60)
-    print("✓ Multi-agent context isolation examples complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/13_agent_with_context_management.py

@@ -1,127 +0,0 @@
-#!/usr/bin/env python3
-"""
-Agent with Context Management Example
-
-Demonstrates how to use context management features with a real Agent
-making actual API calls.
-
-Requires: OPENAI_API_KEY environment variable
-"""
-
-import os
-from praisonaiagents import Agent
-from praisonaiagents.context import (
-    ContextBudgeter,
-    ContextLedgerManager,
-    get_optimizer,
-    OptimizerStrategy,
-    estimate_messages_tokens,
-    format_percent,
-)
-
-
-def main():
-    # Check for API key
-    if not os.environ.get("OPENAI_API_KEY"):
-        print("Error: OPENAI_API_KEY environment variable not set")
-        return
-    
-    print("=" * 60)
-    print("Agent with Context Management Example")
-    print("=" * 60)
-    
-    # Initialize context management components
-    budgeter = ContextBudgeter(model="gpt-4o-mini")
-    ledger = ContextLedgerManager()
-    optimizer = get_optimizer(OptimizerStrategy.SMART)
-    
-    # Get budget info
-    budget = budgeter.allocate()
-    print("\nModel: gpt-4o-mini")
-    print(f"Context budget: {budget.usable:,} tokens")
-    print(f"Output reserve: {budget.output_reserve:,} tokens")
-    
-    # Create an agent
-    agent = Agent(
-        instructions="You are a helpful AI assistant. Keep responses concise.",
-        llm="gpt-4o-mini",
-    )
-    
-    # Track the system prompt
-    ledger.track_system_prompt(agent.instructions)
-    print(f"\nSystem prompt tracked: {ledger.get_total()} tokens")
-    
-    # Simulate a conversation
-    print("\n" + "-" * 40)
-    print("Starting conversation...")
-    print("-" * 40)
-    
-    conversation = []
-    questions = [
-        "What is Python?",
-        "What are its main features?",
-        "Give me a simple example.",
-    ]
-    
-    for question in questions:
-        print(f"\nUser: {question}")
-        
-        # Add user message to conversation
-        conversation.append({"role": "user", "content": question})
-        
-        # Track in ledger
-        ledger.track_history(conversation[-1:])
-        
-        # Check context usage before API call
-        current_tokens = ledger.get_total()
-        utilization = budgeter.get_utilization(current_tokens)
-        
-        print(f"[Context: {current_tokens} tokens, {format_percent(utilization)} used]")
-        
-        # Check if optimization needed
-        if utilization > 0.8:
-            print("[Warning: High context usage, optimizing...]")
-            conversation, _ = optimizer.optimize(conversation, target_tokens=int(budget.usable * 0.7))
-        
-        # Make API call
-        response = agent.chat(question)
-        
-        # Add assistant response to conversation
-        conversation.append({"role": "assistant", "content": response})
-        ledger.track_history(conversation[-1:])
-        
-        print(f"Assistant: {response[:200]}..." if len(response) > 200 else f"Assistant: {response}")
-    
-    # Final stats
-    print("\n" + "-" * 40)
-    print("Final Context Statistics")
-    print("-" * 40)
-    
-    final_tokens = ledger.get_total()
-    final_utilization = budgeter.get_utilization(final_tokens)
-    
-    print(f"Total tokens used: {final_tokens:,}")
-    print(f"Context utilization: {format_percent(final_utilization)}")
-    print(f"Messages in conversation: {len(conversation)}")
-    print(f"Remaining capacity: {budgeter.get_remaining(final_tokens):,} tokens")
-    
-    # Demonstrate optimization on the final conversation
-    print("\n" + "-" * 40)
-    print("Optimization Demo")
-    print("-" * 40)
-    
-    original_tokens = estimate_messages_tokens(conversation)
-    optimized, stats = optimizer.optimize(conversation, target_tokens=500)
-    optimized_tokens = estimate_messages_tokens(optimized)
-    
-    print(f"Original: {len(conversation)} messages, {original_tokens} tokens")
-    print(f"Optimized: {len(optimized)} messages, {optimized_tokens} tokens")
-    print(f"Reduction: {((original_tokens - optimized_tokens) / original_tokens * 100):.1f}%")
-    
-    print("\n" + "=" * 60)
-    print("✓ Agent with context management example complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/14_agent_context_param.py

@@ -1,217 +0,0 @@
-#!/usr/bin/env python3
-"""
-Agent-Centric Context Management Example
-
-Demonstrates the recommended way to use context management with the new
-`context=` parameter. This is the simplest and most powerful approach.
-
-The `context=` parameter accepts:
-- False (default): Zero overhead, no context management
-- True: Enable with safe defaults (auto-compact, smart strategy)
-- ManagerConfig: Custom configuration object
-- ContextManager: Pre-configured manager instance
-
-Requires: OPENAI_API_KEY environment variable
-"""
-
-import os
-from praisonaiagents import Agent
-from praisonaiagents.context import ManagerConfig
-
-
-def example_1_simple_enable():
-    """Simplest usage - just enable context management."""
-    print("=" * 60)
-    print("Example 1: Simple Enable (context=True)")
-    print("=" * 60)
-    
-    # Create agent with context management enabled
-    agent = Agent(
-        instructions="You are a helpful assistant. Keep responses concise.",
-        llm="gpt-4o-mini",
-        context=True,  # Enable with safe defaults
-    )
-    
-    # The agent now automatically:
-    # - Tracks token usage
-    # - Optimizes when approaching limits (80% threshold)
-    # - Uses smart optimization strategy
-    
-    print("Agent created with context management enabled")
-    print(f"Context manager initialized: {agent.context_manager is not None}")
-    
-    if agent.context_manager:
-        print(f"Model: {agent.context_manager.model}")
-        print(f"Auto-compact: {agent.context_manager.config.auto_compact}")
-        print(f"Threshold: {agent.context_manager.config.compact_threshold}")
-        print(f"Strategy: {agent.context_manager.config.strategy}")
-    
-    # Make a chat call
-    if os.environ.get("OPENAI_API_KEY"):
-        response = agent.chat("What is 2+2?")
-        print(f"\nResponse: {response}")
-    else:
-        print("\nSkipping API call (no OPENAI_API_KEY)")
-    
-    print()
-
-
-def example_2_custom_config():
-    """Custom configuration with ManagerConfig."""
-    print("=" * 60)
-    print("Example 2: Custom Configuration (context=ManagerConfig)")
-    print("=" * 60)
-    
-    # Create custom configuration
-    config = ManagerConfig(
-        auto_compact=True,
-        compact_threshold=0.7,  # Trigger at 70% instead of 80%
-        strategy="smart",
-        monitor_enabled=True,
-        monitor_path="./context_debug.txt",
-        monitor_format="human",
-        redact_sensitive=True,
-        output_reserve=8000,
-    )
-    
-    # Create agent with custom config
-    agent = Agent(
-        instructions="You are a code assistant.",
-        llm="gpt-4o-mini",
-        context=config,
-    )
-    
-    print("Agent created with custom context config")
-    print(f"Threshold: {agent.context_manager.config.compact_threshold}")
-    print(f"Monitor enabled: {agent.context_manager.config.monitor_enabled}")
-    print(f"Monitor path: {agent.context_manager.config.monitor_path}")
-    
-    if os.environ.get("OPENAI_API_KEY"):
-        response = agent.chat("Write a hello world in Python")
-        print(f"\nResponse: {response[:200]}...")
-    else:
-        print("\nSkipping API call (no OPENAI_API_KEY)")
-    
-    print()
-
-
-def example_3_disabled():
-    """Disabled context management - zero overhead."""
-    print("=" * 60)
-    print("Example 3: Disabled (context=False)")
-    print("=" * 60)
-    
-    # Create agent without context management (default)
-    agent = Agent(
-        instructions="You are a simple assistant.",
-        llm="gpt-4o-mini",
-        context=False,  # Explicit disable (same as default)
-    )
-    
-    print("Agent created without context management")
-    print(f"Context manager: {agent.context_manager}")
-    print("Zero overhead: No token tracking, no optimization")
-    
-    if os.environ.get("OPENAI_API_KEY"):
-        response = agent.chat("Hello!")
-        print(f"\nResponse: {response}")
-    else:
-        print("\nSkipping API call (no OPENAI_API_KEY)")
-    
-    print()
-
-
-def example_4_access_stats():
-    """Access context statistics and history."""
-    print("=" * 60)
-    print("Example 4: Access Context Stats")
-    print("=" * 60)
-    
-    agent = Agent(
-        instructions="You are helpful.",
-        llm="gpt-4o-mini",
-        context=True,
-    )
-    
-    manager = agent.context_manager
-    
-    # Access budget info via internal attribute
-    budget = manager._budget
-    print(f"Model limit: {budget.model_limit:,} tokens")
-    print(f"Output reserve: {budget.output_reserve:,} tokens")
-    print(f"Usable budget: {budget.usable:,} tokens")
-    
-    # Access config
-    print("\nConfiguration:")
-    print(f"  Auto-compact: {manager.config.auto_compact}")
-    print(f"  Threshold: {manager.config.compact_threshold}")
-    print(f"  Strategy: {manager.config.strategy}")
-    
-    print()
-
-
-def example_5_multi_agent():
-    """Multi-agent with shared context management."""
-    print("=" * 60)
-    print("Example 5: Multi-Agent Context Management")
-    print("=" * 60)
-    
-    from praisonaiagents import AgentTeam, Task
-    
-    config = ManagerConfig(
-        auto_compact=True,
-        compact_threshold=0.8,
-    )
-    
-    # Create agents
-    researcher = Agent(
-        name="Researcher",
-        instructions="You research topics thoroughly.",
-        llm="gpt-4o-mini",
-    )
-    
-    writer = Agent(
-        name="Writer", 
-        instructions="You write clear summaries.",
-        llm="gpt-4o-mini",
-    )
-    
-    # Create tasks
-    task1 = Task(description="Research AI trends", agent=researcher)
-    task2 = Task(description="Write a summary", agent=writer)
-    
-    # Create multi-agent system with context management
-    agents = AgentTeam(
-        agents=[researcher, writer],
-        tasks=[task1, task2],
-        context=config,  # Shared context config
-    )
-    
-    print("Multi-agent system created")
-    print(f"Context manager: {agents.context_manager is not None}")
-    
-    if agents.context_manager:
-        print("Type: MultiAgentContextManager")
-        print("Provides per-agent isolation with shared config")
-    
-    print()
-
-
-def main():
-    print("\n" + "=" * 60)
-    print("Agent-Centric Context Management Examples")
-    print("=" * 60 + "\n")
-    
-    example_1_simple_enable()
-    example_2_custom_config()
-    example_3_disabled()
-    example_4_access_stats()
-    example_5_multi_agent()
-    
-    print("=" * 60)
-    print("✓ All examples complete!")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/context/15_recursive_context.py

@@ -1,274 +0,0 @@
-"""
-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()

examples/cookbooks/yaml/secondary_market_research_agents.yaml

@@ -22,7 +22,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini"
+      model: "gpt-5-nano"
       temperature: 0.3
     tools:
       - "InternetSearchTool"
@@ -76,7 +76,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini" 
+      model: "gpt-5-nano" 
       temperature: 0.3
     tools:
       - "InternetSearchTool"
@@ -130,7 +130,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini"
+      model: "gpt-5-nano"
       temperature: 0.3
     tools:
       - "InternetSearchTool"
@@ -185,7 +185,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini"
+      model: "gpt-5-nano"
       temperature: 0.4
     tools:
       - "InternetSearchTool"
@@ -239,7 +239,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini"
+      model: "gpt-5-nano"
       temperature: 0.3
     tools:
       - "InternetSearchTool"
@@ -299,7 +299,7 @@ agents:  # Canonical: use 'agents' instead of 'roles'
     verbose: true
     allow_delegation: false
     llm:
-      model: "gpt-4o-mini"
+      model: "gpt-5-nano"
       temperature: 0.3
     tasks:
       report_synthesis:

examples/debug/_demo_workspace/app.py

@@ -1,22 +0,0 @@
-"""Sample application."""
-
-def greet(name: str) -> str:
-    """Greet someone."""
-    return f"Hello, {name}!"
-
-def add(a: int, b: int) -> int:
-    """Add two numbers."""
-    return a + b
-
-class Calculator:
-    """Simple calculator."""
-    
-    def __init__(self):
-        self.value = 0
-    
-    def add(self, x):
-        self.value += x
-        return self.value
-
-if __name__ == "__main__":
-    print(greet("World"))

examples/debug/_demo_workspace/demo_output.py

@@ -1,10 +0,0 @@
-"""
-demo_output.py - Auto-generated file
-"""
-
-def main():
-    pass
-
-
-if __name__ == "__main__":
-    main()

examples/debug/_demo_workspace/test_demo.py

@@ -1,10 +0,0 @@
-"""
-test_demo.py - Auto-generated file
-"""
-
-def main():
-    pass
-
-
-if __name__ == "__main__":
-    main()

examples/debug/debug_interactive_example.py

@@ -1,228 +0,0 @@
-"""
-Debug Interactive Mode Example
-
-This example demonstrates how to use the debug CLI commands to test
-the Interactive Coding Assistant without entering TUI mode.
-
-Features demonstrated:
-- LSP symbol listing
-- LSP definition lookup
-- ACP action planning
-- ACP action execution
-- Trace capture and JSON output
-"""
-
-import asyncio
-import json
-import sys
-from pathlib import Path
-
-# Add the src directory to path for development
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src" / "praisonai"))
-
-from praisonai.cli.features.interactive_runtime import create_runtime
-from praisonai.cli.features.code_intelligence import CodeIntelligenceRouter
-from praisonai.cli.features.action_orchestrator import ActionOrchestrator
-
-
-async def demo_lsp_queries(workspace: str):
-    """Demonstrate LSP-based code queries."""
-    print("\n" + "=" * 60)
-    print("LSP CODE QUERIES DEMO")
-    print("=" * 60)
-    
-    runtime = create_runtime(
-        workspace=workspace,
-        lsp=True,
-        acp=False,
-        trace=True
-    )
-    
-    try:
-        await runtime.start()
-        router = CodeIntelligenceRouter(runtime)
-        
-        # Query 1: List symbols
-        print("\n[Query 1] List all symbols in app.py")
-        result = await router.handle_query("list all functions in app.py", "app.py")
-        print(f"  Success: {result.success}")
-        print(f"  LSP Used: {result.lsp_used}")
-        print(f"  Fallback Used: {result.fallback_used}")
-        if result.data:
-            print(f"  Symbols found: {len(result.data)}")
-            for symbol in result.data[:5]:
-                print(f"    - {symbol['name']} ({symbol['kind']}) at line {symbol['line']}")
-        
-        # Query 2: Find definition
-        print("\n[Query 2] Find definition of Calculator")
-        result = await router.handle_query("where is Calculator defined", "app.py")
-        print(f"  Success: {result.success}")
-        if result.citations:
-            print(f"  Found at: {result.citations[0]}")
-        
-        # Get trace
-        trace = runtime.get_trace()
-        print(f"\n[Trace] {len(trace.entries)} entries captured")
-        
-    finally:
-        await runtime.stop()
-
-
-async def demo_acp_actions(workspace: str):
-    """Demonstrate ACP-based code modifications."""
-    print("\n" + "=" * 60)
-    print("ACP CODE MODIFICATIONS DEMO")
-    print("=" * 60)
-    
-    runtime = create_runtime(
-        workspace=workspace,
-        lsp=False,
-        acp=True,
-        approval="auto",
-        trace=True
-    )
-    
-    try:
-        await runtime.start()
-        print(f"\n  ACP Ready: {runtime.acp_ready}")
-        print(f"  Read Only: {runtime.read_only}")
-        
-        orchestrator = ActionOrchestrator(runtime)
-        
-        # Action 1: Create a plan
-        print("\n[Action 1] Create plan for new file")
-        result = await orchestrator.create_plan("create a new file called demo_output.py")
-        print(f"  Success: {result.success}")
-        if result.plan:
-            print(f"  Plan ID: {result.plan.id}")
-            print(f"  Steps: {len(result.plan.steps)}")
-            for step in result.plan.steps:
-                print(f"    - {step.action_type.value}: {step.target}")
-        
-        # Action 2: Execute with auto-approve
-        print("\n[Action 2] Execute file creation")
-        exec_result = await orchestrator.execute(
-            "create a new file called demo_output.py with a hello function",
-            auto_approve=True
-        )
-        print(f"  Success: {exec_result.success}")
-        print(f"  Applied Steps: {exec_result.applied_steps}")
-        
-        # Verify file was created
-        output_file = Path(workspace) / "demo_output.py"
-        if output_file.exists():
-            print(f"  File created: {output_file}")
-            print(f"  Content preview: {output_file.read_text()[:100]}...")
-        
-        # Get trace
-        trace = runtime.get_trace()
-        print(f"\n[Trace] {len(trace.entries)} entries captured")
-        for entry in trace.entries:
-            print(f"    [{entry.category}] {entry.action}")
-        
-    finally:
-        await runtime.stop()
-
-
-async def demo_full_interactive_turn(workspace: str):
-    """Demonstrate full interactive turn simulation."""
-    print("\n" + "=" * 60)
-    print("FULL INTERACTIVE TURN SIMULATION")
-    print("=" * 60)
-    
-    runtime = create_runtime(
-        workspace=workspace,
-        lsp=True,
-        acp=True,
-        approval="auto",
-        trace=True
-    )
-    
-    try:
-        status = await runtime.start()
-        print("\n  Runtime Status:")
-        print(f"    LSP: {'ready' if status['lsp']['ready'] else 'fallback'}")
-        print(f"    ACP: {'ready' if status['acp']['ready'] else 'unavailable'}")
-        
-        router = CodeIntelligenceRouter(runtime)
-        orchestrator = ActionOrchestrator(runtime)
-        
-        # Simulate user prompt: code query
-        prompt1 = "What functions are in app.py?"
-        print(f"\n[Turn 1] User: {prompt1}")
-        
-        # Classify and route
-        result = await router.handle_query(prompt1, "app.py")
-        print(f"  Intent: {result.intent.value}")
-        print(f"  Response: Found {len(result.data) if result.data else 0} symbols")
-        
-        # Simulate user prompt: code modification
-        prompt2 = "Create a new test file"
-        print(f"\n[Turn 2] User: {prompt2}")
-        
-        exec_result = await orchestrator.execute(
-            "create a new file called test_demo.py",
-            auto_approve=True
-        )
-        print("  Action: file_create")
-        print(f"  Result: {'success' if exec_result.success else 'failed'}")
-        
-        # Export trace as JSON
-        trace = runtime.get_trace()
-        trace_json = trace.to_dict()
-        print("[Trace Export]")
-        print(json.dumps(trace_json, indent=2, default=str)[:500] + "...")
-        
-    finally:
-        await runtime.stop()
-
-
-def main():
-    """Run the debug demo."""
-    # Create a temporary workspace
-    workspace = Path(__file__).parent / "_demo_workspace"
-    workspace.mkdir(exist_ok=True)
-    
-    # Create a sample app.py
-    app_file = workspace / "app.py"
-    app_file.write_text('''"""Sample application."""
-
-def greet(name: str) -> str:
-    """Greet someone."""
-    return f"Hello, {name}!"
-
-def add(a: int, b: int) -> int:
-    """Add two numbers."""
-    return a + b
-
-class Calculator:
-    """Simple calculator."""
-    
-    def __init__(self):
-        self.value = 0
-    
-    def add(self, x):
-        self.value += x
-        return self.value
-
-if __name__ == "__main__":
-    print(greet("World"))
-''')
-    
-    print("=" * 60)
-    print("PRAISONAI DEBUG MODE DEMO")
-    print("=" * 60)
-    print(f"Workspace: {workspace}")
-    
-    # Run demos
-    asyncio.run(demo_lsp_queries(str(workspace)))
-    asyncio.run(demo_acp_actions(str(workspace)))
-    asyncio.run(demo_full_interactive_turn(str(workspace)))
-    
-    print("\n" + "=" * 60)
-    print("DEMO COMPLETE")
-    print("=" * 60)
-
-
-if __name__ == "__main__":
-    main()

examples/embedding/agent_with_embedding.py

@@ -1,145 +0,0 @@
-"""
-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()

examples/eval/accuracy_example.py

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

examples/eval/criteria_example.py

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

examples/eval/performance_example.py

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

examples/eval/reliability_example.py

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

examples/execution/00_agent_execution_basic.py

@@ -1,48 +0,0 @@
-"""
-Basic Execution Configuration Example
-
-Demonstrates using execution presets for quick configuration.
-"""
-import os
-from praisonaiagents import Agent
-
-# Ensure API key is set from environment
-assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
-
-# Default execution (max_iter=20, max_retry_limit=2)
-agent_default = Agent(
-    instructions="You are a helpful assistant.",
-)
-
-# Fast execution - fewer iterations, quick responses
-agent_fast = Agent(
-    instructions="You are a helpful assistant.",
-    execution="fast",
-)
-
-# Thorough execution - more iterations, comprehensive responses
-agent_thorough = Agent(
-    instructions="You are a research assistant.",
-    execution="thorough",
-)
-
-# Unlimited execution - for complex tasks
-agent_unlimited = Agent(
-    instructions="You are a complex problem solver.",
-    execution="unlimited",
-)
-
-if __name__ == "__main__":
-    print("Testing execution presets...")
-    
-    print(f"Default agent max_iter: {agent_default.max_iter}")
-    print(f"Fast agent max_iter: {agent_fast.max_iter}")
-    print(f"Thorough agent max_iter: {agent_thorough.max_iter}")
-    print(f"Unlimited agent max_iter: {agent_unlimited.max_iter}")
-    
-    # Test fast agent
-    print("\n--- Fast Execution ---")
-    result = agent_fast.chat("What is the capital of France?")
-    print(f"Result: {result}")
-    
-    print("\nAll execution preset tests passed!")

examples/execution/01_agent_execution_config.py

@@ -1,45 +0,0 @@
-"""
-ExecutionConfig Example
-
-Demonstrates using ExecutionConfig for fine-grained control over execution limits.
-"""
-import os
-from praisonaiagents import Agent, ExecutionConfig
-
-# Ensure API key is set from environment
-assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
-
-# Custom execution configuration
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    execution=ExecutionConfig(
-        max_iter=30,
-        max_rpm=100,
-        max_execution_time=60,
-        max_retry_limit=3,
-    ),
-)
-
-# Rate-limited agent for API quota management
-agent_rate_limited = Agent(
-    instructions="You are a helpful assistant.",
-    execution=ExecutionConfig(
-        max_iter=20,
-        max_rpm=10,  # Only 10 requests per minute
-    ),
-)
-
-if __name__ == "__main__":
-    print("Testing ExecutionConfig...")
-    
-    print(f"Custom agent max_iter: {agent.max_iter}")
-    print(f"Custom agent max_rpm: {agent.max_rpm}")
-    print(f"Custom agent max_execution_time: {agent.max_execution_time}")
-    print(f"Custom agent max_retry_limit: {agent.max_retry_limit}")
-    
-    # Test custom agent
-    print("\n--- Custom Execution ---")
-    result = agent.chat("What is machine learning?")
-    print(f"Result: {result}")
-    
-    print("\nExecutionConfig tests passed!")

examples/guardrail_example_fixed.py

@@ -4,7 +4,7 @@ Fixed example demonstrating proper guardrail usage with PraisonAI Agents.
 This addresses the issues reported in issue #875.
 """
 
-from praisonaiagents import Agent, Task, GuardrailResult, AgentTeam, TaskOutput
+from praisonaiagents import Agent, Task, GuardrailResult, PraisonAIAgents, TaskOutput
 from typing import Tuple, Any
 import trafilatura
 
@@ -67,8 +67,8 @@ agent = Agent(
     goal="Summarize web content concisely",
     instructions="You are a helpful assistant that summarizes web content",
     llm="gemini/gemini-2.5-flash-lite-preview-06-17",
-    reflection=False,
-    output="verbose",  # Use new consolidated param
+    self_reflect=False,
+    verbose=True,
     tools=[get_url_context]  # FIX: tools must be a list, not a single function
 )
 
@@ -77,7 +77,7 @@ task_with_guardrailresult = Task(
     name="summarise article with GuardrailResult",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary below 500 characters",
     agent=agent,
-    guardrails=validate_length_guardrailresult,  # Using GuardrailResult
+    guardrail=validate_length_guardrailresult,  # Using GuardrailResult
     expected_output="summary of the article below 500 characters",
     max_retries=3  # Will retry up to 3 times if guardrail fails
 )
@@ -87,7 +87,7 @@ task_with_tuple = Task(
     name="summarise article with tuple",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary below 500 characters",
     agent=agent,
-    guardrails=validate_length_tuple,  # Using Tuple[bool, Any]
+    guardrail=validate_length_tuple,  # Using Tuple[bool, Any]
     expected_output="summary of the article below 500 characters",
     max_retries=3
 )
@@ -97,13 +97,13 @@ task_with_llm_guardrail = Task(
     name="summarise with LLM guardrail",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary",
     agent=agent,
-    guardrails="Ensure the summary is professional, factual, and between 100-500 characters",
+    guardrail="Ensure the summary is professional, factual, and between 100-500 characters",
     expected_output="professional summary of the article"
 )
 
 # Run with GuardrailResult example
 print("=== Running with GuardrailResult guardrail ===")
-agents_gr = AgentTeam(
+agents_gr = PraisonAIAgents(
     agents=[agent],
     tasks=[task_with_guardrailresult]
 )
@@ -113,7 +113,7 @@ agents_gr = AgentTeam(
 
 # Run with Tuple example
 print("\n=== Running with Tuple[bool, Any] guardrail ===")
-agents_tuple = AgentTeam(
+agents_tuple = PraisonAIAgents(
     agents=[agent],
     tasks=[task_with_tuple]
 )
@@ -123,7 +123,7 @@ agents_tuple = AgentTeam(
 
 # Run with LLM guardrail example
 print("\n=== Running with LLM-based guardrail ===")
-agents_llm = AgentTeam(
+agents_llm = PraisonAIAgents(
     agents=[agent],
     tasks=[task_with_llm_guardrail]
 )

examples/guardrails/00_agent_guardrails_basic.py

@@ -1,30 +0,0 @@
-"""
-Basic Guardrails Configuration Example
-
-Demonstrates using guardrails for output validation.
-"""
-import os
-from praisonaiagents import Agent
-
-# Ensure API key is set from environment
-assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
-
-def validate_length(output):
-    """Validate that output is not too short."""
-    if len(str(output.raw)) < 10:
-        return False, "Response too short"
-    return True, output
-
-# Enable guardrails with a validator function
-agent = Agent(
-    instructions="You are a helpful assistant.",
-    guardrails=validate_length,
-)
-
-if __name__ == "__main__":
-    print("Testing guardrails...")
-    
-    result = agent.chat("Explain what Python is.")
-    print(f"Result: {result}")
-    
-    print("\nGuardrails tests passed!")

examples/guardrails/01_agent_guardrails_config.py

@@ -1,43 +0,0 @@
-"""
-GuardrailConfig Example
-
-Demonstrates using GuardrailConfig for fine-grained control.
-"""
-import os
-from praisonaiagents import Agent, GuardrailConfig
-
-# Ensure API key is set from environment
-assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
-
-def validate_no_code(output):
-    """Validate that output doesn't contain code blocks."""
-    if "```" in str(output.raw):
-        return False, "Response should not contain code blocks"
-    return True, output
-
-# Custom guardrail configuration
-agent = Agent(
-    instructions="You are a helpful assistant. Explain concepts without code.",
-    guardrails=GuardrailConfig(
-        validator=validate_no_code,
-        max_retries=3,
-        on_fail="retry",
-    ),
-)
-
-# LLM-based validation
-agent_llm = Agent(
-    instructions="You are a helpful assistant.",
-    guardrails=GuardrailConfig(
-        llm_validator="Ensure the response is helpful, accurate, and professional.",
-        max_retries=2,
-    ),
-)
-
-if __name__ == "__main__":
-    print("Testing GuardrailConfig...")
-    
-    result = agent.chat("What is a variable in programming?")
-    print(f"Result: {result}")
-    
-    print("\nGuardrailConfig tests passed!")

examples/hooks/basic_hooks.py

@@ -2,34 +2,32 @@
 """
 Basic Hooks Example for PraisonAI Agents.
 
-This example demonstrates the simplified hook API using add_hook():
+This example demonstrates how to use the hooks system to:
 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 (
-    add_hook, remove_hook, has_hook, get_default_registry,
-    HookRunner, HookEvent, HookResult,
+    HookRegistry, HookRunner, HookEvent, HookResult,
     BeforeToolInput, AfterToolInput
 )
 
 
 def main():
-    # Clear any existing hooks from previous runs
-    get_default_registry().clear()
+    # Create a hook registry
+    registry = HookRegistry()
     
     # ==========================================================================
-    # Hook 1: Log all tool calls (using string event name)
+    # Hook 1: Log all tool calls
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.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}")
@@ -37,9 +35,9 @@ def main():
         return HookResult.allow()
     
     # ==========================================================================
-    # Hook 2: Block dangerous file operations
+    # Hook 2: Block dangerous file operations (using function logic)
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.BEFORE_TOOL)
     def block_delete_operations(event_data: BeforeToolInput) -> HookResult:
         """Block any delete or remove operations."""
         dangerous_keywords = ['delete', 'remove', 'rm', 'unlink']
@@ -55,7 +53,7 @@ def main():
     # ==========================================================================
     # Hook 3: Require confirmation for write operations
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.BEFORE_TOOL)
     def confirm_write_operations(event_data: BeforeToolInput) -> HookResult:
         """Request confirmation for write operations."""
         write_keywords = ['write', 'save', 'create', 'update']
@@ -64,13 +62,14 @@ 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
     # ==========================================================================
-    @add_hook('after_tool')
+    @registry.on(HookEvent.AFTER_TOOL)
     def log_tool_completion(event_data: AfterToolInput) -> HookResult:
         """Log tool completion with timing."""
         print(f"\n✅ [DONE] Tool: {event_data.tool_name}")
@@ -83,14 +82,10 @@ def main():
     # Test the hooks
     # ==========================================================================
     print("=" * 60)
-    print("Testing Hooks System (using add_hook API)")
+    print("Testing Hooks System")
     print("=" * 60)
     
-    # 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())
+    runner = HookRunner(registry)
     
     # Test 1: Normal tool call (should be logged and allowed)
     print("\n--- Test 1: Normal read operation ---")
@@ -137,7 +132,7 @@ def main():
     print("\n" + "=" * 60)
     print("Registered Hooks:")
     print("=" * 60)
-    for event, hooks in get_default_registry().list_hooks().items():
+    for event, hooks in registry.list_hooks().items():
         print(f"\n{event}:")
         for hook in hooks:
             print(f"  - {hook['name']} (matcher: {hook['matcher'] or '*'})")

examples/hooks/simple_hooks.py

@@ -1,67 +0,0 @@
-#!/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")

examples/interactive_defaults/interactive_tools_example.py

@@ -1,147 +0,0 @@
-"""
-Interactive Default Tools Example
-
-This example demonstrates how PraisonAI's interactive modes (TUI and prompt)
-include ACP and LSP tools by default.
-
-Tool Groups:
-- ACP: acp_create_file, acp_edit_file, acp_delete_file, acp_execute_command
-- LSP: lsp_list_symbols, lsp_find_definition, lsp_find_references, lsp_get_diagnostics
-- Basic: read_file, write_file, list_files, execute_command, internet_search
-
-Usage:
-    python interactive_tools_example.py
-"""
-
-import os
-import sys
-
-# Add paths for development
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai'))
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai-agents'))
-
-
-def example_get_default_tools():
-    """Example: Get all default interactive tools."""
-    from praisonai.cli.features.interactive_tools import (
-        get_interactive_tools,
-        ToolConfig,
-        TOOL_GROUPS,
-    )
-    
-    print("=== Default Interactive Tools ===\n")
-    
-    # Show tool groups
-    print("Tool Groups:")
-    for group, tools in TOOL_GROUPS.items():
-        if group != "interactive":
-            print(f"  {group}: {tools}")
-    print()
-    
-    # Get all tools
-    config = ToolConfig(workspace=os.getcwd())
-    tools = get_interactive_tools(config=config)
-    
-    print(f"Total tools loaded: {len(tools)}")
-    print(f"Tool names: {[t.__name__ for t in tools]}")
-    print()
-    
-    return tools
-
-
-def example_disable_acp():
-    """Example: Disable ACP tools."""
-    from praisonai.cli.features.interactive_tools import (
-        get_interactive_tools,
-        ToolConfig,
-    )
-    
-    print("=== Disable ACP Tools (--no-acp) ===\n")
-    
-    config = ToolConfig(workspace=os.getcwd(), enable_acp=False)
-    tools = get_interactive_tools(config=config, disable=["acp"])
-    
-    acp_tools = [t for t in tools if t.__name__.startswith("acp_")]
-    print(f"ACP tools after --no-acp: {len(acp_tools)}")
-    print(f"Remaining tools: {[t.__name__ for t in tools]}")
-    print()
-    
-    return tools
-
-
-def example_disable_lsp():
-    """Example: Disable LSP tools."""
-    from praisonai.cli.features.interactive_tools import (
-        get_interactive_tools,
-        ToolConfig,
-    )
-    
-    print("=== Disable LSP Tools (--no-lsp) ===\n")
-    
-    config = ToolConfig(workspace=os.getcwd(), enable_lsp=False)
-    tools = get_interactive_tools(config=config, disable=["lsp"])
-    
-    lsp_tools = [t for t in tools if t.__name__.startswith("lsp_")]
-    print(f"LSP tools after --no-lsp: {len(lsp_tools)}")
-    print(f"Remaining tools: {[t.__name__ for t in tools]}")
-    print()
-    
-    return tools
-
-
-def example_agent_with_default_tools():
-    """Example: Create an Agent with default interactive tools."""
-    from praisonai.cli.features.interactive_tools import get_interactive_tools, ToolConfig
-    from praisonaiagents import Agent
-    
-    print("=== Agent with Default Interactive Tools ===\n")
-    
-    # Get default tools
-    config = ToolConfig(workspace=os.getcwd())
-    tools = get_interactive_tools(config=config)
-    
-    # Create agent with tools
-    agent = Agent(
-        name="InteractiveAgent",
-        instructions="You are a helpful coding assistant with file and code analysis capabilities.",
-        tools=tools,
-        output="silent"
-    )
-    
-    print(f"Agent created with {len(tools)} tools")
-    print(f"Tools: {[t.__name__ for t in tools]}")
-    print()
-    
-    # Simple test - list files
-    print("Testing agent with list_files tool...")
-    result = agent.start("List the Python files in the current directory using list_files tool.")
-    print(f"Result: {result[:200]}..." if len(str(result)) > 200 else f"Result: {result}")
-    print()
-    
-    return agent
-
-
-if __name__ == "__main__":
-    print("=" * 60)
-    print("PraisonAI Interactive Default Tools Example")
-    print("=" * 60)
-    print()
-    
-    # Example 1: Get default tools
-    example_get_default_tools()
-    
-    # Example 2: Disable ACP
-    example_disable_acp()
-    
-    # Example 3: Disable LSP
-    example_disable_lsp()
-    
-    # Example 4: Agent with default tools (requires API key)
-    if os.environ.get("OPENAI_API_KEY"):
-        example_agent_with_default_tools()
-    else:
-        print("=== Agent Example Skipped (no OPENAI_API_KEY) ===")
-    
-    print("=" * 60)
-    print("Examples Complete")
-    print("=" * 60)

examples/js/agents/audio-agent.ts

@@ -1,128 +0,0 @@
-/**
- * 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);

examples/js/knowledge/chonkie-adapter.ts

@@ -1,124 +0,0 @@
-/**
- * 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);

examples/js/knowledge/query-engine.ts

@@ -1,97 +0,0 @@
-/**
- * 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);

examples/js/mcp/mcp-client-test.ts

@@ -1,136 +0,0 @@
-/**
- * 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);

examples/js/memory/memory-hooks.ts

@@ -1,137 +0,0 @@
-/**
- * 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);

examples/js/run-feature-tests.ts

@@ -1,181 +0,0 @@
-/**
- * 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);
-});

examples/js/tools/subagent-tool.ts

@@ -1,112 +0,0 @@
-/**
- * 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);

examples/js/workflows/loop-pattern.ts

@@ -1,88 +0,0 @@
-/**
- * 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);