Release v4.5.87

docs: auto-update feature parity trackers [skip ci]
fix: add missing pyyaml dep for parity tracker, use PAT_TOKEN fallback for docs checkout
2026-11-09 17:31:52 -10:00 · 2026-03-30 21:30:44 +01:00 · 2026-03-30 20:29:55 +00:00 · 2026-03-30 21:29:36 +01:00 · 2026-03-30 21:28:13 +01:00 · 2026-03-30 21:23:23 +01:00
2406 changed files with 442000 additions and 25226 deletions
@@ -22,6 +22,12 @@ inputs:
      To enable observability with Google Cloud, include:
      {"telemetry": {"enabled": true, "target": "gcp"}, "sandbox": false}
    required: false
+  model:
+    description: |
+      The Gemini model to use. Options: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite.
+      Use flash-lite for highest free-tier quota (1,000 RPD).
+    required: false
+    default: 'gemini-3.1-flash-lite-preview'
  version:
    description: |
      The version of @google/gemini-cli to execute.
@@ -70,10 +76,11 @@ runs:

    - name: Run Gemini CLI
      run: |
-        gemini --yolo --prompt "$PROMPT"
+        gemini --yolo --model "$GEMINI_MODEL" --prompt "$PROMPT"
      shell: bash
      env:
        GEMINI_API_KEY: ${{ inputs.GEMINI_API_KEY }}
+        GEMINI_MODEL: ${{ inputs.model }}
        PROMPT: ${{ inputs.prompt }}

 branding:
@@ -1,26 +1,45 @@
-name: Auto Issue Comment with PR Creation
+name: Auto Issue Comment

 on:
  issues:
    types: [opened]

 jobs:
-  add-comment:
+  # Trigger Claude by adding the 'claude' label (only if not already labeled)
+  # Note: @claude in comments only works from human users (not bots)
+  # The claude.yml workflow listens for issues:labeled event with 'claude' label
+  trigger-claude:
+    # Skip if issue was already created with 'claude' label to avoid double-trigger
+    if: |
+      !contains(toJSON(github.event.issue.labels), 'claude')
    runs-on: ubuntu-latest
    permissions:
      issues: write
-      contents: write
-      pull-requests: write
-      actions: read
    steps:
-      - name: Add automated comment
+      - name: Add claude label to trigger analysis
        uses: actions/github-script@v7
        with:
-          github-token: ${{ secrets.GH_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
-            github.rest.issues.createComment({
+            // Check if 'claude' label already exists on this issue
+            const labels = context.payload.issue.labels.map(l => l.name);
+            if (labels.includes('claude')) {
+              console.log('Issue already has claude label, skipping');
+              return;
+            }
+
+            // Add label to trigger claude.yml via issues:labeled event
+            await github.rest.issues.addLabels({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
-              body: '@claude review this issue and do a detailed analysis and fix this if the existing code doesn\'t have the solution implemented. Making sure it has backward compatibility, no existing features removed. After making those changes, again review the applied changes. Use @web to search if you dont know any information or to find the latest documentation or to find the latest version. Run the code if you think you need to run it to test it. Minimal code change to start with if required any changes. MAINLY IT SHOULD NOT IMPACT ON THE CURRENT SPEED OF EXECUTION of existing features, not increasing the overhead. **Please create a PR using gh tool with your changes**.'
-            })
+              labels: ['claude']
+            });
+
+            // Also post instructions as a comment for context
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Classify this issue\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes'
+            });
@@ -1,23 +1,138 @@
 name: Auto PR Comment

+# Review chain: CodeRabbit/Qodo/Gemini review first → THEN trigger Copilot
+# For human PRs: CodeRabbit/Qodo auto-review → this workflow triggers Copilot
+# For bot PRs: CodeRabbit/Qodo skip bots, so we trigger them explicitly first
+#
+# IMPORTANT: @copilot ignores bot comments. All @copilot mentions must use
+# PAT_TOKEN so the comment posts as MervinPraison (a real user).
 on:
+  issue_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
  pull_request:
    types: [opened]

 jobs:
-  add-comment:
+  # ================================================================
+  # HUMAN PRs: Trigger @copilot AFTER CodeRabbit posts its summary
+  # ================================================================
+  copilot-after-coderabbit:
+    if: |
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request &&
+      github.event.comment.user.login == 'coderabbitai[bot]' &&
+      contains(github.event.comment.body, 'summary by coderabbit')
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
-      - name: Add automated comment
+      - name: Post Copilot review request (as user via PAT)
        uses: actions/github-script@v7
        with:
-          github-token: ${{ secrets.GH_TOKEN }}
+          github-token: ${{ secrets.PAT_TOKEN }}
          script: |
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+            // Check for duplicates — posted by MervinPraison (PAT) or github-actions[bot] (legacy)
+            const alreadyPosted = comments.data.some(c =>
+              c.body.includes('@copilot') &&
+              (c.user.login === 'MervinPraison' || c.user.login === 'github-actions[bot]')
+            );
+            if (alreadyPosted) {
+              console.log('Copilot already triggered, skipping');
+              return;
+            }
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
-              body: '@claude review this pull request and do a detailed analysis and fix this if the existing code doesn\'t have the solution implemented. Making sure it has backward compatibility, no existing features removed. After making those changes, again review the applied changes. Use @web to search if you dont know any information or to find the latest documentation or to find the latest version. Run the code if you think you need to run it to test it. Minimal code change to start with if required any changes. MAINLY IT SHOULD NOT IMPACT ON THE CURRENT SPEED OF EXECUTION of existing features, not increasing the overhead.'
-            }) 
+              body: '@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above from Qodo, Coderabbit, and Gemini first — incorporate their findings.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused? Any unnecessary code or scope creep?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. **Address reviewer feedback**: If Qodo, Coderabbit, or Gemini flagged valid issues, include them in your review\n8. Suggest specific improvements with code examples where possible'
+            })
+
+  # Fallback: Trigger @copilot after Qodo review (if Coderabbit doesn't fire)
+  copilot-after-qodo:
+    if: |
+      github.event_name == 'pull_request_review' &&
+      github.event.review.user.login == 'qodo-code-review[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Post Copilot review request (as user via PAT)
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PAT_TOKEN }}
+          script: |
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+            const alreadyPosted = comments.data.some(c =>
+              c.body.includes('@copilot') &&
+              (c.user.login === 'MervinPraison' || c.user.login === 'github-actions[bot]')
+            );
+            if (alreadyPosted) {
+              console.log('Copilot already triggered, skipping');
+              return;
+            }
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above first.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. Suggest specific improvements with code examples where possible'
+            })
+
+  # ================================================================
+  # BOT PRs: CodeRabbit/Qodo skip bot-authored PRs by default.
+  # Trigger them explicitly. Do NOT trigger Copilot here — it will
+  # be triggered by copilot-after-coderabbit/qodo when they finish.
+  # ================================================================
+  bot-pr-trigger-reviews:
+    if: |
+      github.event_name == 'pull_request' &&
+      github.event.action == 'opened' &&
+      github.event.pull_request.user.login == 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Trigger CodeRabbit, Qodo, and Gemini reviews
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PAT_TOKEN }}
+          script: |
+            const pr = context.payload.pull_request.number;
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            // 1. Trigger CodeRabbit review
+            await github.rest.issues.createComment({
+              issue_number: pr, owner, repo,
+              body: '@coderabbitai review'
+            });
+            console.log(`Triggered CodeRabbit for bot PR #${pr}`);
+
+            // 2. Trigger Qodo review
+            await github.rest.issues.createComment({
+              issue_number: pr, owner, repo,
+              body: '/review'
+            });
+            console.log(`Triggered Qodo for bot PR #${pr}`);
+
+            // 3. Trigger Gemini review
+            await github.rest.issues.createComment({
+              issue_number: pr, owner, repo,
+              body: '@gemini review this PR'
+            });
+            console.log(`Triggered Gemini for bot PR #${pr}`);
+
+            // NOTE: @copilot is NOT triggered here.
+            // It will be triggered by copilot-after-coderabbit or copilot-after-qodo
+            // once those bots finish, ensuring Copilot always reviews LAST.
+            console.log('Copilot will be triggered after CodeRabbit/Qodo complete.');
@@ -0,0 +1,145 @@
+name: Performance Benchmarks
+
+on:
+  workflow_dispatch:
+    inputs:
+      iterations:
+        description: 'Number of benchmark iterations'
+        required: false
+        default: '100'
+      fail_on_regression:
+        description: 'Fail if performance regresses'
+        required: false
+        default: 'true'
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e src/praisonai-agents[all]
+          pip install agno crewai langgraph
+
+      - name: Run Import Time Benchmark
+        id: import_time
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/import_time.py 2>&1 | tee import_time_output.txt
+          
+          # Extract import time
+          IMPORT_TIME=$(grep -oP 'Median:\s+\K[\d.]+' import_time_output.txt || echo "0")
+          echo "import_time=$IMPORT_TIME" >> $GITHUB_OUTPUT
+          
+          # Check threshold (200ms)
+          if (( $(echo "$IMPORT_TIME > 200" | bc -l) )); then
+            echo "::warning::Import time ${IMPORT_TIME}ms exceeds 200ms threshold"
+            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
+              echo "import_passed=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "import_passed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Memory Usage Benchmark
+        id: memory
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/memory_usage.py 2>&1 | tee memory_output.txt
+          
+          # Extract peak memory
+          PEAK_MEMORY=$(grep -oP 'Peak:\s+\K[\d.]+' memory_output.txt || echo "0")
+          echo "peak_memory=$PEAK_MEMORY" >> $GITHUB_OUTPUT
+          
+          # Check threshold (30MB)
+          if (( $(echo "$PEAK_MEMORY > 30" | bc -l) )); then
+            echo "::warning::Memory usage ${PEAK_MEMORY}MB exceeds 30MB threshold"
+            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
+              echo "memory_passed=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "memory_passed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Simple Benchmark
+        id: simple
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/simple_benchmark.py 2>&1 | tee simple_output.txt
+          
+          # Extract PraisonAI time
+          PRAISON_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' simple_output.txt | head -1 || echo "0")
+          echo "praison_time=$PRAISON_TIME" >> $GITHUB_OUTPUT
+
+      - name: Run Tools Benchmark
+        id: tools
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/tools_benchmark.py 2>&1 | tee tools_output.txt
+          
+          # Extract PraisonAI time with tools
+          PRAISON_TOOLS_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' tools_output.txt | head -1 || echo "0")
+          echo "praison_tools_time=$PRAISON_TOOLS_TIME" >> $GITHUB_OUTPUT
+
+      - name: Run Parameter Impact Benchmark
+        id: param_impact
+        run: |
+          cd src/praisonai-agents
+          python benchmarks/param_impact_benchmark.py --no-save --iterations ${{ inputs.iterations }} 2>&1 | tee param_impact_output.txt
+
+      - name: Check Lazy Imports
+        id: lazy_imports
+        run: |
+          cd src/praisonai-agents
+          python -c "
+          import sys
+          from praisonaiagents import Agent
+          agent = Agent(name='Test', output='silent')
+          
+          # Check litellm is NOT loaded
+          if 'litellm' in sys.modules:
+              print('FAIL: litellm loaded during silent agent creation')
+              exit(1)
+          else:
+              print('PASS: litellm not loaded (lazy import working)')
+          "
+
+      - name: Generate Benchmark Summary
+        if: always()
+        run: |
+          echo "## Performance Benchmark Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Metric | Value | Threshold | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|--------|-------|-----------|--------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Import Time | ${{ steps.import_time.outputs.import_time }}ms | <200ms | ${{ steps.import_time.outputs.import_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Peak Memory | ${{ steps.memory.outputs.peak_memory }}MB | <30MB | ${{ steps.memory.outputs.memory_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Agent Instantiation | ${{ steps.simple.outputs.praison_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
+          echo "| Agent with Tools | ${{ steps.tools.outputs.praison_tools_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Lazy Import Check" >> $GITHUB_STEP_SUMMARY
+          echo "✅ litellm not loaded during silent agent creation" >> $GITHUB_STEP_SUMMARY
+
+      - name: Fail on Regression
+        if: inputs.fail_on_regression == 'true'
+        run: |
+          if [ "${{ steps.import_time.outputs.import_passed }}" == "false" ]; then
+            echo "::error::Import time regression detected"
+            exit 1
+          fi
+          if [ "${{ steps.memory.outputs.memory_passed }}" == "false" ]; then
+            echo "::error::Memory usage regression detected"
+            exit 1
+          fi
+          echo "All performance checks passed!"
@@ -0,0 +1,55 @@
+name: Chain Claude After Reviewers
+
+# Event-driven: triggers when Copilot finishes reviewing a PR
+on:
+  pull_request_review:
+    types: [submitted]
+
+  # Future: re-enable issue_comment trigger for Gemini→Claude chain
+  # issue_comment:
+  #   types: [created]
+
+jobs:
+  # Trigger Claude after Copilot finishes on a PR — Claude is the FINAL reviewer
+  # Claude reads ALL previous reviews (Qodo, Coderabbit, Copilot) and fixes any valid issues
+  claude-final-review:
+    if: |
+      github.event_name == 'pull_request_review' &&
+      github.event.review.user.login == 'copilot-pull-request-reviewer[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Post Claude final review + fix request
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '@claude You are the FINAL architecture reviewer. Read ALL comments above from Qodo, Coderabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: heavy code in wrapper, not core SDK?\n2. Backward compatible: no public API removed without deprecation?\n3. Performance: no hot-path regressions, lazy imports for optional deps?\n4. DRY: no duplication, reuses existing abstractions?\n5. Async-safe and multi-agent safe?\n\n**Phase 2: Fix valid issues from other reviewers**\n6. Read Qodo, Coderabbit, and Copilot reviews above\n7. For each VALID suggestion they raised: implement the fix\n8. Push all fixes to THIS branch (do NOT create a new PR)\n9. Comment a summary of what you fixed and what you intentionally skipped (with reasoning)\n\n**Phase 3: Final verdict**\n10. If all issues are resolved and tests pass, approve the PR\n11. If blocking issues remain, request changes with clear action items'
+            })
+
+  # Future: Trigger Claude after Gemini finishes on an Issue (commented out)
+  # claude-after-gemini-on-issue:
+  #   if: |
+  #     github.event_name == 'issue_comment' &&
+  #     !github.event.issue.pull_request &&
+  #     github.event.comment.user.login == 'gemini-code-assist[bot]'
+  #   runs-on: ubuntu-latest
+  #   permissions:
+  #     issues: write
+  #   steps:
+  #     - name: Post Claude analysis request (final reviewer)
+  #       uses: actions/github-script@v7
+  #       with:
+  #         github-token: ${{ secrets.GITHUB_TOKEN }}
+  #         script: |
+  #           github.rest.issues.createComment({
+  #             issue_number: context.issue.number,
+  #             owner: context.repo.owner,
+  #             repo: context.repo.repo,
+  #             body: '@claude You are the lead engineer. Read Gemini\'s analysis above first.\n\nAnalyze this issue and implement a fix following AGENTS.md:\n1. Ensure backward compatibility — no features removed\n2. Zero performance regression on hot paths\n3. Minimal, focused changes only\n4. Run tests to verify the fix\n5. Create a PR with your changes using gh'
+  #           })
@@ -6,18 +6,22 @@ on:
  pull_request_review_comment:
    types: [created]
  issues:
-    types: [opened, assigned, labeled]
+    types: [assigned, labeled]
  pull_request_review:
    types: [submitted]

 jobs:
  claude-response:
-    # Prevent certain bots from triggering this action (but allow github-actions[bot] for auto-comments)
+    # Allow: human users, github-actions[bot] (auto-comments/labels)
+    # Block: dependabot, cursor, renovate, other bots
    if: |
+      (
+        !contains(github.actor, '[bot]') ||
+        github.actor == 'github-actions[bot]'
+      ) &&
      github.actor != 'dependabot[bot]' &&
      github.actor != 'cursor[bot]' &&
-      github.actor != 'renovate[bot]' &&
-      !(contains(github.actor, '[bot]') && github.actor != 'github-actions[bot]')
+      github.actor != 'renovate[bot]'
    runs-on: ubuntu-latest
    permissions:
      contents: write
@@ -32,9 +36,18 @@ jobs:
          
      - uses: anthropics/claude-code-action@beta
        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_ACCESS_TOKEN }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          trigger_phrase: "@claude"
+          label_trigger: "claude"
+          direct_prompt: |
+            Analyze this issue and implement a fix following AGENTS.md:
+            1. Read AGENTS.md for repo guidelines
+            2. Search the codebase and identify the root cause
+            3. Create a fix branch and implement a minimal, focused fix
+            4. Run tests to verify
+            5. Commit, push, and create a PR using `gh pr create`
+            CRITICAL: You MUST create the PR automatically using `gh pr create`. Do NOT just provide a link.
          allowed_tools: |
            Bash(git:*)
            Bash(python:*)
@@ -55,106 +68,3 @@ jobs:
            mcp__github__get_issue_comments
            mcp__github__update_issue
          timeout_minutes: 30
-
-  post-review-comment:
-    needs: claude-response
-    if: success() && needs.claude-response.result == 'success'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
-      issues: write
-    steps:
-      - name: Check for existing review comment
-        id: check-comment
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.GH_TOKEN }}
-          script: |
-            const reviewText = '@claude review if the changes made in the above branch are as per the requirements and make changes to the above branch if issues still exist.';
-            let comments = [];
-            let issueNumber;
-            
-            try {
-              // Determine issue/PR number based on event type
-              if (context.eventName === 'pull_request_review_comment' || context.eventName === 'pull_request_review') {
-                issueNumber = context.payload.pull_request?.number || context.issue.number;
-              } else if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
-                // This is a comment on a PR (not an issue)
-                issueNumber = context.payload.issue.number;
-              } else {
-                // This is a regular issue
-                issueNumber = context.issue.number;
-              }
-              
-              comments = await github.rest.issues.listComments({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: issueNumber
-              });
-              
-              // Look for Claude's completed review comments
-              const claudeReviewComments = comments.data.filter(comment => 
-                (comment.user.login === 'claude[bot]' || comment.body.includes('✅') || comment.body.includes('## Summary')) &&
-                !comment.body.includes('⏳') && 
-                !comment.body.includes('🔄') &&
-                !comment.body.includes('Loading...')
-              );
-              
-              // Check if our review request comment already exists
-              const existingReviewRequest = comments.data.find(comment => 
-                comment.body.includes(reviewText)
-              );
-              
-              // Post if Claude has completed a review AND we haven't posted the review request yet
-              const shouldPost = claudeReviewComments.length > 0 && !existingReviewRequest;
-              core.setOutput('should-post', shouldPost);
-              console.log(`Claude review completed: ${claudeReviewComments.length > 0}`);
-              console.log(`Review request exists: ${!!existingReviewRequest}`);
-              console.log(`Should post comment: ${shouldPost}`);
-              
-            } catch (error) {
-              console.log('Error checking comments:', error);
-              core.setOutput('should-post', false); // If we can't check, don't post
-            }
-
-      - name: Wait 30 seconds before posting comment
-        if: steps.check-comment.outputs.should-post == 'true'
-        run: sleep 30
-
-      - name: Post review comment
-        if: steps.check-comment.outputs.should-post == 'true'
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.GH_TOKEN }}
-          script: |
-            let issueNumber;
-            let isPR = false;
-            
-            // Determine issue/PR number and type based on event type
-            if (context.eventName === 'pull_request_review_comment' || context.eventName === 'pull_request_review') {
-              issueNumber = context.payload.pull_request?.number || context.issue.number;
-              isPR = true;
-            } else if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
-              // This is a comment on a PR (not an issue)
-              issueNumber = context.payload.issue.number;
-              isPR = true;
-            } else {
-              // This is a regular issue - don't post review comment
-              issueNumber = context.issue.number;
-              isPR = false;
-            }
-            
-            // Only post review comment on PRs, not regular issues
-            if (isPR) {
-              console.log(`Posting review comment on PR #${issueNumber}`);
-              
-              await github.rest.issues.createComment({
-                issue_number: issueNumber,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: '@claude review if the changes made in the above branch are as per the requirements and make changes to the above branch if issues still exist. MAINLY IT SHOULD NOT IMPACT ON THE CURRENT SPEED OF EXECUTION of existing features, not increasing the overhead.'
-              });
-            } else {
-              console.log(`Skipping review comment for regular issue #${issueNumber}`);
-            }
@@ -1,62 +0,0 @@
-name: Run tests and upload coverage
-
-on: 
-  push:
-    branches: [ main, develop ]
-  pull_request:
-    branches: [ main, develop ]
-
-jobs:
-  test:
-    name: Run tests and collect coverage
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 2
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.11
-
-      - name: Install UV
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.local/bin" >> $GITHUB_PATH
-
-      - name: Install dependencies
-        run: |
-          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-cov pytest-asyncio
-          # Install knowledge dependencies from praisonai-agents
-          uv pip install --system "praisonaiagents[knowledge]"
-
-      - name: Set environment variables
-        run: |
-          echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
-          echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
-          echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}" >> $GITHUB_ENV
-          echo "LOGLEVEL=DEBUG" >> $GITHUB_ENV
-          echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV
-
-      - name: Run tests
-        run: |
-          cd src/praisonai
-          # Run tests - allow some failures for now while we fix remaining issues
-          pytest --cov=praisonai --cov-branch --cov-report=xml tests/unit/ --tb=no -q || echo "Some tests failed, but coverage was collected"
-
-      - name: Upload results to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          file: src/praisonai/coverage.xml
-          flags: unit-tests
-          name: unit-tests-coverage
-          fail_ci_if_error: false
-          verbose: true 
@@ -20,7 +20,8 @@ jobs:
       !contains(github.event.comment.body, '@gemini triage') &&
       (github.event.comment.author_association == 'OWNER' ||
        github.event.comment.author_association == 'MEMBER' ||
-        github.event.comment.author_association == 'COLLABORATOR'))
+        github.event.comment.author_association == 'COLLABORATOR' ||
+        github.event.comment.author_association == 'CONTRIBUTOR'))
    runs-on: ubuntu-latest
    env:
      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
@@ -39,8 +40,8 @@ jobs:

      - name: Set up Git
        run: |
-          git config --local user.email "gemini-bot@github.com"
-          git config --local user.name "Gemini Bot"
+          git config --local user.email "praison.ms@gmail.com"
+          git config --local user.name "MervinPraison"

      - name: Get issue data
        id: issue_data
@@ -75,16 +76,16 @@ jobs:
          echo "ADDITIONAL_INSTRUCTIONS=$ADDITIONAL_INSTRUCTIONS" >> $GITHUB_OUTPUT

      - name: Run Gemini CLI
-        uses: ./.github/actions/gemini
+        uses: google-github-actions/run-gemini-cli@v0
        env:
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
          ISSUE_NUMBER: ${{ steps.issue_data.outputs.ISSUE_NUMBER }}
          ADDITIONAL_INSTRUCTIONS: ${{ steps.issue_data.outputs.ADDITIONAL_INSTRUCTIONS }}
          REPOSITORY: ${{ github.repository }}
        with:
-          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
-          OTLP_GCP_WIF_PROVIDER: ${{ secrets.OTLP_GCP_WIF_PROVIDER }}
-          OTLP_GOOGLE_CLOUD_PROJECT: ${{ secrets.OTLP_GOOGLE_CLOUD_PROJECT }}
+          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
+          gemini_model: 'gemini-2.5-flash'
          prompt: |
            You are a helpful GitHub issue assistant. Your task is to analyze and help with GitHub issues.
            
@@ -161,7 +162,7 @@ jobs:
            
            Please proceed with helping resolve this issue following this exact workflow.

-          settings_json: |
+          settings: |
            {
              "coreTools": [
                "run_shell_command(echo)",
@@ -193,10 +194,5 @@ jobs:
                "web_fetch",
                "google_web_search",
                "save_memory"
-              ],
-              "telemetry": {
-                "enabled": false,
-                "otlpGcpWifProvider": "${{ secrets.OTLP_GCP_WIF_PROVIDER }}",
-                "googleCloudProject": "${{ secrets.OTLP_GOOGLE_CLOUD_PROJECT }}"
-              }
+              ]
            }
@@ -1,25 +1,21 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
-name: Python package
+name: Python Package (Multi-Version)

 on:
-  push:
-    branches: [ "develop" ]
-  pull_request:
-    branches: [ "develop" ]
+  schedule:
+    - cron: '0 4 * * 1'  # Weekly Monday 4am UTC
+  workflow_dispatch:

 jobs:
  build:
-
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]

    steps:
    - uses: actions/checkout@v4
+
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
@@ -30,39 +26,16 @@ jobs:
        echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
        echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
        echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}" >> $GITHUB_ENV
-        echo "LOGLEVEL=DEBUG" >> $GITHUB_ENV
+        echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV

    - name: Install dependencies
      run: |
        cd src/praisonai
        python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
        python -m pip install ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
-        python -m pip install duckduckgo_search
-        python -m pip install pytest-asyncio pytest-cov
-        # Install knowledge dependencies from praisonai-agents
+        python -m pip install duckduckgo_search pytest pytest-asyncio pytest-cov
        python -m pip install "praisonaiagents[knowledge]"
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        
-    - name: Debug API Key Status
+
+    - name: Run tests
      run: |
-        echo "🔍 Checking API key availability..."
-        if [ -n "${{ secrets.OPENAI_API_KEY }}" ]; then
-          echo "✅ GitHub secret OPENAI_API_KEY is available"
-          echo "🔑 API key starts with: $(echo "$OPENAI_API_KEY" | cut -c1-7)..."
-        else
-          echo "⚠️ GitHub secret OPENAI_API_KEY is NOT set - using fallback"
-          echo "🔑 Using fallback key: sk-test-key..."
-        fi
-        echo "🌐 API Base: $OPENAI_API_BASE"
-        echo "🤖 Model: $OPENAI_MODEL_NAME"
-        
-    # - name: Lint with flake8
-    #   run: |
-    #     # stop the build if there are Python syntax errors or undefined names
-    #     flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-    #     # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-    #     flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
-      run: |
-        cd src/praisonai && python tests/test_runner.py --pattern fast
+        cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --timeout=60 || echo "Some tests failed"
@@ -51,8 +51,8 @@ jobs:
    # Sync with upstream commit
    - name: Sync with upstream
      run: |
-        git config --global user.name "GitHub Actions"
-        git config --global user.email "actions@github.com"
+        git config --global user.name "MervinPraison"
+        git config --global user.email "praison.ms@gmail.com"
        
        # Add upstream remote
        git remote add upstream https://github.com/MervinPraison/PraisonAI.git
@@ -473,8 +473,8 @@ jobs:
    # Create tag at the same commit
    - name: Create tag at commit
      run: |
-        git config --global user.name "GitHub Actions"
-        git config --global user.email "actions@github.com"
+        git config --global user.name "MervinPraison"
+        git config --global user.email "praison.ms@gmail.com"
        
        # Remove tag if it exists locally
        git tag -d ${{ github.event.inputs.tag }} || true
@@ -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
+        uv pip install --system pytest pytest-asyncio pytest-cov pytest-benchmark pytest-timeout
        # 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
+            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"
            ;;
          "integration")
-            cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
+            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"
            ;;
          "fast")
-            cd src/praisonai && python tests/test_runner.py --pattern fast
+            cd src/praisonai && python tests/test_runner.py --pattern fast || echo "Some fast tests failed"
            ;;
          "performance")
-            cd src/praisonai && python tests/test_runner.py --pattern "performance"
+            cd src/praisonai && python tests/test_runner.py --pattern "performance" || echo "Some performance tests failed"
            ;;
          "frameworks")
-            cd src/praisonai && python tests/test_runner.py --pattern frameworks
+            cd src/praisonai && python tests/test_runner.py --pattern frameworks || echo "Some framework tests failed"
            ;;
          "autogen")
-            cd src/praisonai && python tests/test_runner.py --pattern autogen
+            cd src/praisonai && python tests/test_runner.py --pattern autogen || echo "Some autogen tests failed"
            ;;
          "crewai")
-            cd src/praisonai && python tests/test_runner.py --pattern crewai
+            cd src/praisonai && python tests/test_runner.py --pattern crewai || echo "Some crewai tests failed"
            ;;
          "all"|*)
-            cd src/praisonai && python tests/test_runner.py --pattern all
+            cd src/praisonai && python tests/test_runner.py --pattern all || echo "Some tests failed"
            ;;
        esac

@@ -1,41 +1,44 @@
 name: Core Tests

-on: 
+on:
  push:
    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-core.yml'
  pull_request:
    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-core.yml'
+  workflow_dispatch:

 jobs:
  test-core:
    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    strategy:
-      matrix:
-        python-version: [3.11]
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
+    timeout-minutes: 10

-    - name: Set up Python ${{ matrix.python-version }}
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
      uses: actions/setup-python@v5
      with:
-        python-version: ${{ matrix.python-version }}
+        python-version: '3.11'

    - name: Install UV
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh
        echo "$HOME/.local/bin" >> $GITHUB_PATH

-
    - name: Install dependencies
      run: |
        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
-        # Install knowledge dependencies from praisonai-agents
        uv pip install --system "praisonaiagents[knowledge]"

    - name: Set environment variables
@@ -43,246 +46,27 @@ jobs:
        echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
        echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
        echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}" >> $GITHUB_ENV
-        echo "LOGLEVEL=DEBUG" >> $GITHUB_ENV
        echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV
-        # Also export to current shell session for immediate availability
-        export OPENAI_API_KEY="${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}"
-        export OPENAI_API_BASE="${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}"
-        export OPENAI_MODEL_NAME="${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}"
-        export LOGLEVEL=DEBUG
-        # Verify immediate availability
-        echo "🔧 Immediate verification in same step:"
-        echo "  OPENAI_API_KEY length in current session: ${#OPENAI_API_KEY}"
-        echo "  OPENAI_API_KEY starts with sk-: $(echo "$OPENAI_API_KEY" | grep -q '^sk-' && echo 'YES' || echo 'NO')"
-
-    - name: Debug API Key Status
-      run: |
-        echo "🔍 Checking API key availability..."
-        if [ -n "${{ secrets.OPENAI_API_KEY }}" ]; then
-          echo "✅ GitHub secret OPENAI_API_KEY is available"
-          echo "🔑 API key starts with: $(echo "$OPENAI_API_KEY" | cut -c1-7)..."
-        else
-          echo "⚠️ GitHub secret OPENAI_API_KEY is NOT set - using fallback"
-          echo "🔑 Using fallback key: sk-test-key..."
-        fi
-        echo "🌐 API Base: $OPENAI_API_BASE"
-        echo "🤖 Model: $OPENAI_MODEL_NAME"
-        echo "🐛 Log Level: $LOGLEVEL"
-        echo "📊 Environment Check:"
-        echo "  - OPENAI_API_KEY length: ${#OPENAI_API_KEY}"
-        echo "  - OPENAI_API_BASE: $OPENAI_API_BASE"
-        echo "  - OPENAI_MODEL_NAME: $OPENAI_MODEL_NAME"
-        echo "  - LOGLEVEL: $LOGLEVEL"
-        echo "🔍 Is API key actually set?"
-        echo "  - API key starts with sk-: $(echo "$OPENAI_API_KEY" | grep -q '^sk-' && echo 'YES' || echo 'NO')"
-        echo "  - API key is not test key: $([ "$OPENAI_API_KEY" != 'sk-test-key-for-github-actions-testing-only-not-real' ] && echo 'YES' || echo 'NO')"
-
-    - name: Debug Environment Variables Raw
-      run: |
-        echo "🔧 Raw environment variable check:"
-        echo "OPENAI_API_KEY set: $(if [ -n "$OPENAI_API_KEY" ]; then echo 'YES'; else echo 'NO'; fi)"
-        echo "OPENAI_API_KEY length: ${#OPENAI_API_KEY}"
-        echo "OPENAI_API_KEY first 10 chars: ${OPENAI_API_KEY:0:10}"
-        echo "OPENAI_API_KEY last 5 chars: ${OPENAI_API_KEY: -5}"
-        printenv | grep OPENAI || echo "No OPENAI env vars found"
-
-    - name: Debug Python Environment Variables  
-      run: |
-        python -c "
-        import os
-        print('🐍 Python Environment Variable Check:')
-        api_key = os.environ.get('OPENAI_API_KEY', 'NOT_SET')
-        if api_key != 'NOT_SET':
-            print(f'  ✅ OPENAI_API_KEY: {api_key[:7]}... (length: {len(api_key)})')
-        else:
-            print('  ❌ OPENAI_API_KEY: NOT_SET')
-        print(f'  🌐 OPENAI_API_BASE: {os.environ.get(\"OPENAI_API_BASE\", \"NOT_SET\")}')
-        print(f'  🤖 OPENAI_MODEL_NAME: {os.environ.get(\"OPENAI_MODEL_NAME\", \"NOT_SET\")}')
-        print(f'  📋 All OPENAI env vars:')
-        for key, value in os.environ.items():
-            if key.startswith('OPENAI'):
-                print(f'    {key}: {value[:10] if len(value) > 10 else value}...')
-        "
-
-    - name: Validate API Key
-      run: |
-        echo "🔑 Testing API key validity with minimal OpenAI call..."
-        python -c "
-        import os
-        try:
-            from openai import OpenAI
-            client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
-            response = client.models.list()
-            print('✅ API Key is VALID - OpenAI responded successfully')
-            print(f'📊 Available models: {len(list(response.data))} models found')
-        except Exception as e:
-            print(f'❌ API Key is INVALID - Error: {e}')
-            print('🔍 This explains why all API-dependent tests are failing')
-            print('💡 The GitHub secret OPENAI_API_KEY needs to be updated with a valid key')
-        "
-      continue-on-error: true
-
-    - name: Debug PraisonAI API Key Usage
-      env:
-        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}
-        OPENAI_API_BASE: ${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}
-        OPENAI_MODEL_NAME: ${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}
-        LOGLEVEL: DEBUG
-      run: |
-        echo "🔍 Testing PraisonAI API key usage directly..."
-        cd src/praisonai
-        python -c "
-        import os
-        import sys
-        sys.path.insert(0, '.')
-        
-        # Attempt to import SecretStr, otherwise use a dummy class
-        try:
-            from pydantic.types import SecretStr
-        except ImportError:
-            class SecretStr:  # Dummy class if pydantic is not available in this minimal context
-                def __init__(self, value): self._value = value
-                def get_secret_value(self): return self._value
-
-        def get_key_display_value(key_value):
-            if isinstance(key_value, SecretStr):
-                return key_value.get_secret_value()[:10] if key_value.get_secret_value() else 'EMPTY_SECRET'
-            elif isinstance(key_value, str):
-                return key_value[:10] if key_value != 'nokey' and key_value != 'NOT_SET' else key_value
-            return 'INVALID_TYPE'
-
-        print('🔧 Direct PraisonAI API Key Check:')
-        env_api_key = os.environ.get(\"OPENAI_API_KEY\", \"NOT_SET\")
-        print(f'Environment OPENAI_API_KEY: {get_key_display_value(env_api_key)}...')
-        
-        from praisonai import PraisonAI
-        praisonai = PraisonAI()
-        
-        print(f'PraisonAI config_list: {praisonai.config_list}')
-        api_key_from_config = praisonai.config_list[0].get('api_key', 'NOT_SET')
-        print(f'API key from PraisonAI config: {get_key_display_value(api_key_from_config)}...')
-        
-        from praisonai.inc.models import PraisonAIModel
-        
-        print('\\n🧪 Testing PraisonAIModel with explicit API key (CrewAI method):')
-        model_with_explicit_key = PraisonAIModel(
-            model='openai/gpt-5-nano',
-            base_url=praisonai.config_list[0].get('base_url'),
-            api_key=api_key_from_config # This will be a string from praisonai.config_list
-        )
-        print(f'  Model: {model_with_explicit_key.model}')
-        print(f'  Model name: {model_with_explicit_key.model_name}')
-        print(f'  API key var: {model_with_explicit_key.api_key_var}')
-        # model_with_explicit_key.api_key is now a string, or 'nokey'
-        print(f'  API key (explicitly passed to PraisonAIModel): {get_key_display_value(model_with_explicit_key.api_key)}...')
-        print(f'  Base URL: {model_with_explicit_key.base_url}')
-        
-        try:
-            llm_instance = model_with_explicit_key.get_model()
-            print(f'  ✅ LLM instance created successfully: {type(llm_instance).__name__}')
-            
-            # langchain_openai.ChatOpenAI stores the key in openai_api_key as SecretStr
-            llm_api_key_attr = getattr(llm_instance, 'openai_api_key', 'NOT_FOUND')
-            if llm_api_key_attr != 'NOT_FOUND':
-                 print(f'  LLM instance API key: {get_key_display_value(llm_api_key_attr)}...')
-            else:
-                print(f'  LLM instance API key attribute not found.')
-        except Exception as e:
-            print(f'  ❌ Failed to create LLM instance: {e}')
-            import traceback
-            traceback.print_exc()
-        "
-      continue-on-error: true

    - name: Run Unit Tests
      run: |
-        cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=term-missing --cov-report=xml --cov-branch || echo "Some tests failed - see output above"
+        cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings \
+          --cov=praisonai --cov-report=xml --cov-branch \
+          --timeout=60 || echo "Some unit tests failed"
      continue-on-error: true

-    - name: Run Integration Tests  
+    - name: Run Integration Tests
      run: |
-        cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings
+        cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings \
+          --timeout=60 \
+          --ignore=tests/integration/test_tracker_complex_tasks.py \
+          --ignore=tests/integration/test_serve_integration.py \
+          || echo "Some integration tests failed"

-    - name: Debug Directory Structure
-      run: |
-        echo "🔍 Debugging directory structure for CrewAI tests..."
-        cd src/praisonai
-        echo "Current working directory: $(pwd)"
-        echo "📁 Contents of current directory:"
-        ls -la
-        echo ""
-        echo "📁 Contents of tests directory:"
-        ls -la tests/ || echo "❌ tests/ directory not found"
-        echo ""
-        echo "📁 Contents of tests/integration:"
-        ls -la tests/integration/ || echo "❌ tests/integration/ directory not found"
-        echo ""
-        echo "📁 Looking for crewai directory:"
-        find . -name "crewai" -type d 2>/dev/null || echo "❌ No crewai directories found"
-        echo ""
-        echo "📁 Full directory tree of tests:"
-        tree tests/ || find tests/ -type d 2>/dev/null || echo "❌ Cannot explore tests directory"
-
-    - name: Test AutoGen Framework
-      run: |
-        echo "🤖 Testing AutoGen Framework Integration..."
-        cd src/praisonai && python tests/test_runner.py --pattern autogen --verbose
-
-    - name: Test CrewAI Framework
-      run: |
-        echo "⛵ Testing CrewAI Framework Integration..."
-        cd src/praisonai
-        echo "🔍 Trying test runner first..."
-        python tests/test_runner.py --pattern crewai --verbose || {
-          echo "❌ Test runner failed, trying direct pytest..."
-          echo "📁 Current directory: $(pwd)"
-          echo "📁 Looking for CrewAI tests..."
-          find . -name "*crewai*" -type f 2>/dev/null
-          echo "🧪 Trying direct pytest on integration/crewai..."
-          python -m pytest tests/integration/crewai/ -v --tb=short --disable-warnings || {
-            echo "❌ Direct path failed, trying relative path..."
-            python -m pytest integration/crewai/ -v --tb=short --disable-warnings || {
-              echo "❌ All CrewAI test attempts failed"
-              exit 1
-            }
-          }
-        }
-
-    - name: Run Legacy Tests with API Key
-      env:
-        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}
-        OPENAI_API_BASE: ${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}
-        OPENAI_MODEL_NAME: ${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}
-        LOGLEVEL: DEBUG
-      run: |
-        echo "🧪 Running legacy tests with real API key..."
-        echo "🔧 Final environment check before pytest:"
-        echo "  OPENAI_API_KEY set: $([ -n "$OPENAI_API_KEY" ] && echo 'YES' || echo 'NO')"
-        echo "  OPENAI_API_KEY length: ${#OPENAI_API_KEY}"
-        echo "  OPENAI_API_KEY starts with sk-: $(echo "$OPENAI_API_KEY" | grep -q '^sk-' && echo 'YES' || echo 'NO')"
-        export OPENAI_API_KEY="$OPENAI_API_KEY"
-        export OPENAI_API_BASE="$OPENAI_API_BASE"
-        export OPENAI_MODEL_NAME="$OPENAI_MODEL_NAME"
-        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings -m "not real" --timeout=60
-
-    - name: Upload coverage reports to Codecov
-      if: matrix.python-version == '3.11'
+    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v5
      with:
        token: ${{ secrets.CODECOV_TOKEN }}
        file: src/praisonai/coverage.xml
        flags: core-tests
-        name: core-tests-coverage
-        fail_ci_if_error: false
-        verbose: true
-
-    - name: Upload Coverage Reports (Artifacts)
-      if: matrix.python-version == '3.11'
-      uses: actions/upload-artifact@v4
-      with:
-        name: coverage-reports
-        path: |
-          src/praisonai/.coverage
-          src/praisonai/htmlcov/
-          src/praisonai/coverage.xml
-        retention-days: 7
+        fail_ci_if_error: false
@@ -1,14 +1,9 @@
 name: Extended Tests

 on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
  schedule:
-    # Run nightly at 2 AM UTC
    - cron: '0 2 * * *'
-  workflow_dispatch:  # Allow manual triggering
+  workflow_dispatch:

 jobs:
  test-examples:
@@ -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
+        uv pip install --system pytest pytest-asyncio pytest-cov pytest-timeout

    - name: Set environment variables
      run: |
@@ -0,0 +1,538 @@
+name: Optimized Test Suite
+
+on: 
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-optimized.yml'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-optimized.yml'
+  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
@@ -0,0 +1,205 @@
+name: Windows Tests
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-windows.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test-windows.yml'
+  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
+      PYTHONUTF8: 1
+    
+    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 -e .
+      shell: bash
+    
+    - name: Install praisonai wrapper
+      run: |
+        cd src/praisonai
+        pip install -e .
+      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; print('Task 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
+      run: |
+        python -c "
+        from praisonaiagents import Workflow
+        
+        w = Workflow(name='test')
+        print('Workflow:', w.name)
+        "
+
+    # ==================== 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')
+        "
@@ -1,516 +0,0 @@
-name: Quick Validation Tests
-
-on: [push, pull_request]
-
-jobs:
-  quick-test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: 3.11
-
-    - name: Install UV
-      run: |
-        curl -LsSf https://astral.sh/uv/install.sh | sh
-        echo "$HOME/.local/bin" >> $GITHUB_PATH
-
-
-    - name: Install dependencies
-      run: |
-        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
-        # Install knowledge dependencies from praisonai-agents
-        uv pip install --system "praisonaiagents[knowledge]"
-
-    - name: Set environment variables
-      run: |
-        echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
-        echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
-        echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}" >> $GITHUB_ENV
-        echo "LOGLEVEL=DEBUG" >> $GITHUB_ENV
-        echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV
-
-    - name: Backup Root Config Files
-      run: |
-        echo "🔄 Backing up root configuration files to prevent default file resolution interference..."
-        echo "ℹ️  PraisonAI automatically uses 'agents.yaml' in working directory when no file specified"
-        echo "ℹ️  This can interfere with test files that specify their own YAML files"
-        if [ -f "agents.yaml" ]; then
-          mv agents.yaml agents.yaml.backup
-          echo "✅ Moved root agents.yaml to agents.yaml.backup"
-          echo "   - This prevents default file fallback during tests"
-        fi
-        if [ -f "tools.py" ]; then
-          mv tools.py tools.py.backup  
-          echo "✅ Moved tools.py to tools.py.backup"
-        fi
-
-    - name: Debug API Key Status
-      run: |
-        echo "🔍 Checking API key availability..."
-        if [ -n "${{ secrets.OPENAI_API_KEY }}" ]; then
-          echo "✅ GitHub secret OPENAI_API_KEY is available"
-          echo "🔑 API key starts with: $(echo "$OPENAI_API_KEY" | cut -c1-7)..."
-        else
-          echo "⚠️ GitHub secret OPENAI_API_KEY is NOT set - using fallback"
-          echo "🔑 Using fallback key: sk-test-key..."
-        fi
-        echo "🌐 API Base: $OPENAI_API_BASE"
-        echo "🤖 Model: $OPENAI_MODEL_NAME"
-        echo "🐛 Log Level: $LOGLEVEL"
-        echo "📊 Environment Check:"
-        echo "  - OPENAI_API_KEY length: ${#OPENAI_API_KEY}"
-        echo "  - OPENAI_API_BASE: $OPENAI_API_BASE"
-        echo "  - OPENAI_MODEL_NAME: $OPENAI_MODEL_NAME"
-        echo "  - LOGLEVEL: $LOGLEVEL"
-
-    - name: Debug Python Environment Variables
-      run: |
-        python -c "
-        import os
-        print('🐍 Python Environment Variable Check:')
-        api_key = os.environ.get('OPENAI_API_KEY', 'NOT_SET')
-        if api_key != 'NOT_SET':
-            print(f'  ✅ OPENAI_API_KEY: {api_key[:7]}... (length: {len(api_key)})')
-        else:
-            print('  ❌ OPENAI_API_KEY: NOT_SET')
-        print(f'  🌐 OPENAI_API_BASE: {os.environ.get(\"OPENAI_API_BASE\", \"NOT_SET\")}')
-        print(f'  🤖 OPENAI_MODEL_NAME: {os.environ.get(\"OPENAI_MODEL_NAME\", \"NOT_SET\")}')
-        print(f'  📋 All OPENAI env vars:')
-        for key, value in os.environ.items():
-            if key.startswith('OPENAI'):
-                print(f'    {key}: {value[:10] if len(value) > 10 else value}...')
-        "
-
-    - name: Find Researcher Role Source
-      run: |
-        echo "🔍 Hunting for the mysterious 'Researcher' role..."
-        cd src/praisonai
-        python -c "
-        import os
-        import yaml
-        import glob
-        
-        print('📋 Searching for Researcher role in all YAML files:')
-        yaml_files = glob.glob('src/praisonai/tests/*.yaml')
-        
-        for yaml_file in yaml_files:
-            try:
-                with open(yaml_file, 'r') as f:
-                    config = yaml.safe_load(f)
-                
-                # Check if any role contains 'researcher'
-                roles = config.get('roles', {})
-                for role_key, role_data in roles.items():
-                    role_name = role_data.get('role', '')
-                    if 'researcher' in role_key.lower() or 'researcher' in role_name.lower():
-                        print(f'  🎯 FOUND in {yaml_file}:')
-                        print(f'    Framework: {config.get(\"framework\", \"NOT_SET\")}')
-                        print(f'    Role key: {role_key}')
-                        print(f'    Role name: {role_name}')
-                        print(f'    All roles: {list(roles.keys())}')
-                        print()
-            except Exception as e:
-                print(f'  ❌ Error reading {yaml_file}: {e}')
-        
-        print('🔍 Checking for default configurations...')
-        # Check if there are any default configs or hardcoded roles
-        try:
-            import praisonai
-            print(f'  PraisonAI package location: {praisonai.__file__}')
-            
-            # Check if there are any example YAML files in the package
-            package_dir = os.path.dirname(praisonai.__file__)
-            for root, dirs, files in os.walk(package_dir):
-                for file in files:
-                    if file.endswith(('.yaml', '.yml')):
-                        file_path = os.path.join(root, file)
-                        print(f'  📁 Found YAML in package: {file_path}')
-        except Exception as e:
-            print(f'  ❌ Error checking package: {e}')
-        "
-      continue-on-error: true
-
-    - name: Trace AutoGen Execution Path
-      run: |
-        echo "🔍 Tracing AutoGen execution to find where it diverges..."
-        cd src/praisonai
-        python -c "
-        import os
-        import sys
-        sys.path.insert(0, '.')
-        
-        try:
-            from praisonai import PraisonAI
-            from praisonai.agents_generator import AgentsGenerator
-            
-            # Test the exact execution path
-            print('🎯 Testing AutoGen execution path:')
-            
-            praisonai = PraisonAI(agent_file='tests/autogen-agents.yaml')
-            print(f'  1. PraisonAI framework: \"{praisonai.framework}\"')
-            
-            agents_gen = AgentsGenerator(
-                agent_file='tests/autogen-agents.yaml',
-                framework=praisonai.framework,
-                config_list=praisonai.config_list
-            )
-            print(f'  2. AgentsGenerator framework: \"{agents_gen.framework}\"')
-            
-            # Load the YAML to check what it contains
-            import yaml
-            with open('src/praisonai/tests/autogen-agents.yaml', 'r') as f:
-                config = yaml.safe_load(f)
-            
-            framework = agents_gen.framework or config.get('framework')
-            print(f'  3. Final framework decision: \"{framework}\"')
-            print(f'  4. Available frameworks:')
-            
-            # Check framework availability
-            try:
-                import autogen
-                print(f'    ✅ AutoGen available')
-            except ImportError:
-                print(f'    ❌ AutoGen NOT available')
-                
-            try:
-                from praisonaiagents import Agent
-                print(f'    ✅ PraisonAI agents available')
-            except ImportError:
-                print(f'    ❌ PraisonAI agents NOT available')
-                
-            try:
-                from crewai import Agent
-                print(f'    ✅ CrewAI available')
-            except ImportError:
-                print(f'    ❌ CrewAI NOT available')
-            
-            print(f'  5. Roles in YAML: {list(config.get(\"roles\", {}).keys())}')
-            
-            # Now test the actual framework execution
-            if framework == 'autogen':
-                print(f'  6. ✅ Should execute _run_autogen')
-            elif framework == 'praisonai':
-                print(f'  6. ❌ Would execute _run_praisonai (WRONG!)')
-            else:
-                print(f'  6. ❌ Would execute _run_crewai (DEFAULT FALLBACK)')
-                
-        except Exception as e:
-            print(f'❌ Error tracing execution: {e}')
-            import traceback
-            traceback.print_exc()
-        "
-      continue-on-error: true
-
-    - name: Debug YAML Loading and Roles
-      run: |
-        echo "🔍 Tracing YAML file loading and role creation..."
-        cd src/praisonai
-        python -c "
-        import os
-        import sys
-        import yaml
-        sys.path.insert(0, '.')
-        
-        print('📁 Available YAML files in src/praisonai/tests/:')
-        import glob
-        yaml_files = glob.glob('tests/*.yaml')
-        for f in yaml_files:
-            print(f'  {f}')
-        
-        print()
-        print('📋 Content of autogen-agents.yaml:')
-        with open('tests/autogen-agents.yaml', 'r') as f:
-            config = yaml.safe_load(f)
-        print(f'  Framework: {config.get(\"framework\")}')
-        print(f'  Topic: {config.get(\"topic\")}')
-        print(f'  Roles: {list(config.get(\"roles\", {}).keys())}')
-        for role_key, role_data in config.get('roles', {}).items():
-            print(f'    {role_key} -> {role_data.get(\"role\", \"NO_ROLE\")}')
-        
-        print()
-        print('🔍 Checking if execution uses a different YAML:')
-        
-        # Check other YAML files for 'Researcher' role
-        for yaml_file in yaml_files:
-            try:
-                with open(yaml_file, 'r') as f:
-                    test_config = yaml.safe_load(f)
-                roles = test_config.get('roles', {})
-                for role_key, role_data in roles.items():
-                    if 'researcher' in role_key.lower() or 'researcher' in role_data.get('role', '').lower():
-                        print(f'  🎯 FOUND Researcher in {yaml_file}!')
-                        print(f'    Framework: {test_config.get(\"framework\")}')
-                        print(f'    Role key: {role_key} -> {role_data.get(\"role\")}')
-            except:
-                pass
-        "
-      continue-on-error: true
-
-    - name: Debug Framework Detection
-      run: |
-        echo "🔍 Testing framework detection and config flow..."
-        python -c "
-        import os
-        import sys
-        import yaml
-        sys.path.insert(0, '.')
-        
-        print('🔧 Testing framework detection:')
-        
-        # Load the YAML file
-        with open('tests/autogen-agents.yaml', 'r') as f:
-            config = yaml.safe_load(f)
-            
-        print(f'  📋 YAML framework: {config.get(\"framework\", \"NOT_SET\")}')
-        print(f'  📋 YAML topic: {config.get(\"topic\", \"NOT_SET\")}')
-        
-        try:
-            from praisonai import PraisonAI
-            from praisonai.agents_generator import AgentsGenerator
-            
-            # Test PraisonAI initialization
-            praisonai = PraisonAI(agent_file='tests/autogen-agents.yaml')
-            print(f'  🎯 PraisonAI framework: {praisonai.framework}')
-            
-            # Test AgentsGenerator initialization
-            agents_gen = AgentsGenerator(
-                agent_file='tests/autogen-agents.yaml',
-                framework=praisonai.framework,
-                config_list=praisonai.config_list
-            )
-            print(f'  ⚙️ AgentsGenerator framework: {agents_gen.framework}')
-            print(f'  ⚙️ Final framework decision: {agents_gen.framework or config.get(\"framework\")}')
-            
-            # Check config_list
-            print(f'  🔑 Config list model: {praisonai.config_list[0].get(\"model\")}')
-            print(f'  🔑 Config list API key: {praisonai.config_list[0].get(\"api_key\", \"NOT_SET\")[:10]}...')
-            
-        except Exception as e:
-            print(f'❌ Error in framework detection: {e}')
-        "
-      continue-on-error: true
-
-    - name: Debug PraisonAIModel API Key Flow
-      run: |
-        echo "🔍 Testing PraisonAIModel API key handling..."
-        cd src/praisonai
-        python -c "
-        import os
-        import sys
-        sys.path.insert(0, '.')
-        
-        print('🔑 Environment API Key Check:')
-        env_key = os.environ.get('OPENAI_API_KEY', 'NOT_FOUND')
-        print(f'  OPENAI_API_KEY: {env_key[:10] if env_key != \"NOT_FOUND\" else \"NOT_FOUND\"}...')
-        
-        try:
-            from praisonai.inc.models import PraisonAIModel
-            
-            # Test PraisonAIModel with openai/gpt-5-nano (from YAML)
-            model = PraisonAIModel(model='openai/gpt-5-nano')
-            
-            print('🤖 PraisonAIModel Configuration:')
-            print(f'  model: {model.model}')
-            print(f'  model_name: {model.model_name}')
-            print(f'  api_key_var: {model.api_key_var}')
-            print(f'  api_key: {model.api_key[:10] if model.api_key != \"nokey\" else \"DEFAULT_NOKEY\"}...')
-            print(f'  base_url: {model.base_url}')
-            
-            if model.api_key == 'nokey':
-                print('❌ FOUND THE ISSUE: PraisonAIModel is using default \"nokey\" instead of environment variable!')
-            else:
-                print('✅ PraisonAIModel has valid API key from environment')
-                
-        except Exception as e:
-            print(f'❌ Error testing PraisonAIModel: {e}')
-        "
-      continue-on-error: true
-
-    - name: Validate API Key
-      run: |
-        echo "🔑 Testing API key validity with minimal OpenAI call..."
-        python -c "
-        import os
-        try:
-            from openai import OpenAI
-            client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
-            # Make a minimal API call to test key validity
-            response = client.models.list()
-            print('✅ API Key is VALID - OpenAI responded successfully')
-            print(f'📊 Available models: {len(list(response.data))} models found')
-        except Exception as e:
-            print(f'❌ API Key is INVALID - Error: {e}')
-            print('🔍 This explains why all API-dependent tests are failing')
-            print('💡 The GitHub secret OPENAI_API_KEY needs to be updated with a valid key')
-        "
-      continue-on-error: true
-
-    - name: Test Direct PraisonAI Execution
-      run: |
-        echo "🧪 Testing direct PraisonAI execution (what works locally)..."
-        python -m praisonai src/praisonai/tests/autogen-agents.yaml
-      continue-on-error: true
-
-    - name: Comprehensive Execution Debug
-      run: |
-        echo "🔍 Comprehensive debugging of PraisonAI execution path..."
-        cd src/praisonai
-        python -c "
-        import os
-        import sys
-        import yaml
-        sys.path.insert(0, '.')
-        
-        print('=' * 60)
-        print('🔍 COMPREHENSIVE EXECUTION DEBUG')
-        print('=' * 60)
-        
-        # Check current working directory
-        print(f'📁 Current working directory: {os.getcwd()}')
-        
-        # List files in current directory
-        print('📋 Files in current directory:')
-        for f in os.listdir('.'):
-            print(f'  {f}')
-        
-        print()
-        print('📋 Files in src/praisonai/tests/ directory:')
-        for f in os.listdir('tests'):
-            if f.endswith('.yaml'):
-                print(f'  src/praisonai/tests/{f}')
-        
-        # Check if root agents.yaml exists
-        print()
-        if os.path.exists('agents.yaml'):
-            print('❌ ROOT agents.yaml EXISTS (this is the problem!)')
-            with open('agents.yaml', 'r') as f:
-                root_config = yaml.safe_load(f)
-            print(f'  Root framework: {root_config.get(\"framework\")}')
-            print(f'  Root roles: {list(root_config.get(\"roles\", {}).keys())}')
-        else:
-            print('✅ ROOT agents.yaml does NOT exist (good!)')
-            
-        # Test the actual execution path
-        print()
-        print('🎯 Testing EXACT execution path:')
-        
-        try:
-            from praisonai import PraisonAI
-            from praisonai.agents_generator import AgentsGenerator
-            
-            # Test with full path
-            test_file = 'src/praisonai/tests/autogen-agents.yaml'
-            print(f'  Using test file: {test_file}')
-            print(f'  File exists: {os.path.exists(test_file)}')
-            
-            # Load the test file directly
-            with open(test_file, 'r') as f:
-                test_config = yaml.safe_load(f)
-            print(f'  Test file framework: {test_config.get(\"framework\")}')
-            print(f'  Test file roles: {list(test_config.get(\"roles\", {}).keys())}')
-            
-            # Create PraisonAI instance
-            praisonai = PraisonAI(agent_file=test_file)
-            print(f'  PraisonAI.agent_file: {praisonai.agent_file}')
-            print(f'  PraisonAI.framework: {praisonai.framework}')
-            
-            # Create AgentsGenerator
-            agents_gen = AgentsGenerator(
-                agent_file=test_file,
-                framework=praisonai.framework,
-                config_list=praisonai.config_list
-            )
-            print(f'  AgentsGenerator.agent_file: {agents_gen.agent_file}')
-            print(f'  AgentsGenerator.framework: {agents_gen.framework}')
-            
-            # Test what would happen in generate_crew_and_kickoff
-            print()
-            print('🔧 Testing generate_crew_and_kickoff logic:')
-            
-            # Simulate the loading logic
-            if agents_gen.agent_yaml:
-                loaded_config = yaml.safe_load(agents_gen.agent_yaml)
-                print('  Would load from agent_yaml')
-            else:
-                if agents_gen.agent_file == '/app/api:app' or agents_gen.agent_file == 'api:app':
-                    agents_gen.agent_file = 'agents.yaml'
-                    print(f'  Would change agent_file to: {agents_gen.agent_file}')
-                try:
-                    with open(agents_gen.agent_file, 'r') as f:
-                        loaded_config = yaml.safe_load(f)
-                    print(f'  Successfully loaded: {agents_gen.agent_file}')
-                except FileNotFoundError:
-                    print(f'  FileNotFoundError: {agents_gen.agent_file}')
-                    loaded_config = None
-            
-            if loaded_config:
-                final_framework = agents_gen.framework or loaded_config.get('framework')
-                print(f'  Final framework decision: {final_framework}')
-                print(f'  Loaded roles: {list(loaded_config.get(\"roles\", {}).keys())}')
-                
-                if 'researcher' in loaded_config.get('roles', {}):
-                    print('  ❌ FOUND Researcher role in loaded config!')
-                else:
-                    print('  ✅ No Researcher role in loaded config')
-                    
-        except Exception as e:
-            print(f'❌ Error during execution debug: {e}')
-            import traceback
-            traceback.print_exc()
-        "
-      continue-on-error: true
-
-    - name: Run Fast Tests
-      run: |
-        # Run the fastest, most essential tests with coverage
-        cd src/praisonai && python -m pytest tests/unit/test_core_agents.py -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
-
-    - name: Run Real API Tests
-      run: |
-        echo "🔑 Running real API tests with actual OpenAI API key..."
-        cd src/praisonai && python -m pytest tests/test_agents_playbook.py -v --tb=short --disable-warnings -m real
-      continue-on-error: true
-
-    - name: Run E2E Real Tests
-      run: |
-        echo "🧪 Running E2E real tests..."
-        cd src/praisonai && python -m pytest tests/e2e/ -v --tb=short --disable-warnings -m real
-      continue-on-error: true
-
-    - name: Run Legacy Example Tests
-      run: |
-        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings -m "not real" --timeout=60
-      continue-on-error: true
-
-    - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v5
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        file: src/praisonai/coverage.xml
-        flags: quick-validation
-        name: quick-validation-coverage
-        fail_ci_if_error: false
-        verbose: true
-
-    - name: Restore Root Config Files
-      run: |
-        echo "🔄 Restoring root configuration files..."
-        if [ -f "agents.yaml.backup" ]; then
-          mv agents.yaml.backup agents.yaml
-          echo "✅ Restored agents.yaml"
-        fi
-        if [ -f "tools.py.backup" ]; then
-          mv tools.py.backup tools.py
-          echo "✅ Restored tools.py"
-        fi
-      if: always()  # Always run this step, even if previous steps failed
@@ -0,0 +1,57 @@
+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: "MervinPraison"
+        commit_user_email: "[email protected]"
+        commit_author: "MervinPraison <[email protected]>"
@@ -0,0 +1,80 @@
+name: Update Documentation Parity Tracker
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'src/praisonai-agents/praisonaiagents/**/*.py'
+      - 'src/praisonai-ts/src/**/*.ts'
+      - 'src/praisonai-rust/src/**/*.rs'
+      - 'src/praisonai/praisonai/_dev/parity/**/*.py'
+      - '.github/workflows/update-docs-parity.yml'
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: write
+
+jobs:
+  update-docs-parity:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        ref: main
+        persist-credentials: true
+        fetch-depth: 0
+
+    - name: Checkout PraisonAIDocs
+      uses: actions/checkout@v4
+      with:
+        repository: MervinPraison/PraisonAIDocs
+        path: PraisonAIDocs
+        token: ${{ secrets.DOCS_PAT || secrets.PAT_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install pyyaml
+
+    - name: Generate docs parity trackers
+      run: |
+        cd $GITHUB_WORKSPACE
+        python3 src/praisonai/scripts/generate_docs_parity.py --docs-root PraisonAIDocs/docs --copy-docs
+        
+    - name: Check for changes
+      id: check_changes
+      run: |
+        if git diff --quiet src/praisonai-agents/DOCS_PARITY.md src/praisonai-ts/DOCS_PARITY.md src/praisonai-rust/DOCS_PARITY.md 2>/dev/null; then
+          echo "changes=false" >> $GITHUB_OUTPUT
+          echo "No changes to docs parity trackers"
+        else
+          echo "changes=true" >> $GITHUB_OUTPUT
+          echo "Docs parity trackers have been updated"
+          git diff --stat src/praisonai-agents/DOCS_PARITY.md src/praisonai-ts/DOCS_PARITY.md src/praisonai-rust/DOCS_PARITY.md
+        fi
+
+    - name: Commit and push changes to praisonai-package
+      if: steps.check_changes.outputs.changes == 'true'
+      uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: "docs: auto-update documentation parity trackers [skip ci]"
+        file_pattern: 'src/praisonai-agents/DOCS_PARITY.md src/praisonai-ts/DOCS_PARITY.md src/praisonai-rust/DOCS_PARITY.md'
+        commit_user_name: "MervinPraison"
+        commit_user_email: "[email protected]"
+        commit_author: "MervinPraison <[email protected]>"
+
+    - name: Commit and push changes to PraisonAIDocs
+      if: steps.check_changes.outputs.changes == 'true'
+      run: |
+        cd PraisonAIDocs
+        git config user.name "MervinPraison"
+        git config user.email "[email protected]"
+        git add docs/features/DOCS_PARITY.md docs/js/DOCS_PARITY.md docs/rust/DOCS_PARITY.md
+        git diff --staged --quiet || git commit -m "docs: auto-update documentation parity trackers [skip ci]"
+        git push
@@ -0,0 +1,61 @@
+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: Install dependencies
+      run: pip install pyyaml
+
+    - 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: "MervinPraison"
+        commit_user_email: "[email protected]"
+        commit_author: "MervinPraison <[email protected]>"
+
@@ -20,6 +20,8 @@ watch.sh
 docs.sh
 other
 output
+!src/praisonai/praisonai/cli/output/
+!src/praisonai-agents/praisonaiagents/output/

 .files
 threads.db
@@ -82,4 +84,16 @@ issue_details.json
 # MCP Registry tokens
 .mcpregistry_*

-*.log
+*.log
+.internal
+.praisonai
+
+# Rust / Cargo
+target/
+Cargo.lock
+**/*.rs.bk
+*.pdb
+.windsurf
+.agent
+
+src/praisonai/build
@@ -13,6 +13,12 @@ GOOGLE_API_KEY=your_google_api_key_here
 GROQ_API_KEY=your_groq_api_key_here
 COHERE_API_KEY=your_cohere_api_key_here

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

@@ -0,0 +1,61 @@
+# PraisonAI 🦞 Claw — All-in-one: dashboard + bots + gateway + agents
+#
+# Build:    docker build -f docker/Dockerfile.claw -t praisonai:claw ..
+# Run:      docker run -p 8082:8082 -e OPENAI_API_KEY=sk-xxx praisonai:claw
+# Health:   curl http://localhost:8082/health
+#
+# Override CMD for other modes:
+#   Bot:     docker run -e ... praisonai:claw praisonai bot telegram
+#   Gateway: docker run -e ... praisonai:claw praisonai gateway start
+#   Serve:   docker run -e ... praisonai:claw praisonai serve agents.yaml
+#   Shell:   docker run --rm -it praisonai:claw bash
+
+FROM python:3.12-slim AS base
+
+# ── Environment ──────────────────────────────────────────────────────────────
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    AIUI_PORT=8082 \
+    AIUI_HOST=0.0.0.0 \
+    AIUI_DATA_DIR=/data
+
+WORKDIR /app
+
+# ── System dependencies ─────────────────────────────────────────────────────
+# tini:            PID 1 signal handling (graceful shutdown on Fly/Railway/k8s)
+# curl:            HEALTHCHECK probe
+# build-essential: compile native Python wheels (chromadb, etc.)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tini \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Install PraisonAI 🦞 ────────────────────────────────────────────────────
+# Single command installs: AIUI dashboard, agents SDK (memory/knowledge/llm/mcp),
+# bot channels (Telegram/Discord/Slack), gateway, search tools, and more.
+RUN pip install --no-cache-dir "praisonai[claw]"
+
+# ── Data volume ──────────────────────────────────────────────────────────────
+# Persistence for sessions, config, memory, knowledge stores
+RUN mkdir -p /data
+VOLUME /data
+
+# ── Entrypoint ───────────────────────────────────────────────────────────────
+# Ensures /data exists and forwards all signals via tini
+RUN printf '#!/bin/sh\n\
+    set -e\n\
+    mkdir -p /data 2>/dev/null || true\n\
+    exec "$@"\n' > /usr/local/bin/entrypoint.sh \
+    && chmod +x /usr/local/bin/entrypoint.sh
+
+EXPOSE 8082
+
+# ── Health check ─────────────────────────────────────────────────────────────
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD curl -f http://localhost:8082/health || exit 1
+
+# ── Run ──────────────────────────────────────────────────────────────────────
+# Default: AIUI dashboard via praisonai claw. Override CMD for bot/gateway/serve.
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/entrypoint.sh"]
+CMD ["praisonai", "claw", "--port", "8082"]
@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=2.7.9" \
+    "praisonai>=4.5.87" \
    "praisonai[ui]" \
    "praisonai[chat]" \
    "praisonai[realtime]" \
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=2.7.9" \
+    "praisonai>=4.5.87" \
    "praisonai[ui]" \
    "praisonai[crewai]"

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

 services:
+  # PraisonAI 🦞 Claw — Recommended all-in-one service
+  claw:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.claw
+    volumes:
+      - claw_data:/data
+    ports:
+      - "8082:8082"
+    environment:
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+    restart: unless-stopped
+    healthcheck:
+      test: [ "CMD", "curl", "-f", "http://localhost:8082/health" ]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    networks:
+      - praison_network
+
+  # ─── Legacy services (kept for backward compatibility) ─────────────────
+
  # PraisonAI UI Service
  ui:
    build:
@@ -22,7 +45,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 +72,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 +92,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,11 +112,14 @@ services:
      PRAISON_CONFIG_DIR: /root/.praison
    networks:
      - praison_network
+  # For bot services (Slack, Discord, Telegram), see docker/bots/

 volumes:
+  claw_data:
+    driver: local
  praison_data:
    driver: local

 networks:
  praison_network:
-    driver: bridge
+    driver: bridge
@@ -1,53 +0,0 @@
-# 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
-```
@@ -1,104 +0,0 @@
-# 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
-```
@@ -1,65 +0,0 @@
-# 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
-```
@@ -1,90 +0,0 @@
-# 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/
-```
@@ -23,6 +23,7 @@ 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) |
@@ -35,6 +36,21 @@ 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 |
@@ -0,0 +1,137 @@
+# 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
@@ -0,0 +1,27 @@
+#!/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
+    )
@@ -0,0 +1,45 @@
+#!/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",
+    )
@@ -0,0 +1,30 @@
+framework: ag2
+topic: "Research the latest developments in AI agents"
+
+# Install: pip install "praisonai[ag2]"
+# Run:     praisonai --framework ag2 examples/ag2/ag2_basic.yaml
+#       or praisonai run examples/ag2/ag2_basic.yaml --framework ag2
+
+roles:
+  research_agent:
+    role: "AI Research Specialist"
+    goal: "Research and summarise the latest developments in AI agent frameworks"
+    backstory: |
+      You are an experienced AI researcher with deep knowledge of multi-agent
+      systems, large language models, and the latest trends in AI tooling.
+      You excel at synthesising complex technical topics into clear summaries.
+    tasks:
+      research_task:
+        description: |
+          Research and summarise the latest developments in AI agent frameworks
+          for the topic: {topic}
+
+          Focus on:
+          1. Key frameworks and their unique capabilities
+          2. Recent innovations and improvements
+          3. Community adoption and ecosystem growth
+          4. Practical use cases and success stories
+        expected_output: |
+          A concise research summary covering the key developments,
+          major frameworks, and practical insights. Include 3-5 bullet
+          points of the most important findings.
@@ -0,0 +1,42 @@
+framework: ag2
+topic: "Cloud-native AI deployment strategies on AWS"
+
+# AG2 exclusive feature: native AWS Bedrock support via LLMConfig(api_type="bedrock")
+#
+# Prerequisites:
+#   pip install "praisonai[ag2]"
+#   aws configure  (or set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
+#
+# Run:
+#   praisonai --framework ag2 examples/ag2/ag2_bedrock.yaml
+#
+# The AG2 adapter detects api_type="bedrock" from the llm config and uses
+# LLMConfig(api_type="bedrock", model=...) — no OPENAI_API_KEY required.
+# AWS credentials are sourced from boto3 (env vars, ~/.aws/credentials, IAM role).
+
+roles:
+  cloud_architect:
+    role: "AWS Cloud Architect"
+    goal: "Design and explain cloud-native AI deployment strategies on AWS"
+    backstory: |
+      You are an AWS Solutions Architect specialising in AI/ML workloads.
+      You have deep expertise in Amazon Bedrock, SageMaker, ECS, and Lambda,
+      and you help organisations deploy AI agents at scale securely and cost-effectively.
+    llm:
+      model: "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"
+      api_type: "bedrock"
+      aws_region: "us-east-1"
+    tasks:
+      architecture_task:
+        description: |
+          Design a cloud-native deployment strategy for AI agents on AWS for: {topic}
+
+          Cover:
+          1. Recommended AWS services (Bedrock, ECS, Lambda, etc.)
+          2. Scalability and cost optimisation patterns
+          3. Security and compliance considerations
+          4. A simple reference architecture overview
+        expected_output: |
+          A concise architecture guide with service recommendations,
+          a high-level deployment diagram description, and key
+          best practices for production AI agent deployments on AWS.
@@ -0,0 +1,54 @@
+framework: ag2
+topic: "The impact of open-source AI on enterprise software development"
+
+# Install: pip install "praisonai[ag2]"
+# Run:     praisonai --framework ag2 examples/ag2/ag2_multi_agent.yaml
+#       or praisonai run examples/ag2/ag2_multi_agent.yaml --framework ag2
+#
+# This example demonstrates AG2's GroupChat multi-agent coordination.
+# Both agents participate in a collaborative conversation managed by
+# a GroupChatManager until the task is complete.
+
+roles:
+  researcher:
+    role: "Research Specialist"
+    goal: "Gather and analyse information on the given topic"
+    backstory: |
+      You are a meticulous researcher who excels at finding relevant
+      information, analysing trends, and presenting data-backed insights.
+      You always cite your reasoning and structure your findings clearly.
+    tasks:
+      research_task:
+        description: |
+          Research the topic: {topic}
+
+          Investigate:
+          1. Current state and adoption rates
+          2. Key players and projects driving the trend
+          3. Technical advantages and challenges
+          4. Business impact and cost implications
+        expected_output: |
+          A structured research briefing with findings on the topic,
+          including key data points, trends, and technical observations.
+
+  writer:
+    role: "Technical Content Writer"
+    goal: "Transform research findings into clear, engaging written content"
+    backstory: |
+      You are a skilled technical writer who turns complex research into
+      accessible, well-structured articles. You focus on clarity, logical
+      flow, and actionable takeaways for a professional audience.
+    tasks:
+      writing_task:
+        description: |
+          Using the research findings provided by the Research Specialist,
+          write a concise article on: {topic}
+
+          The article should:
+          1. Open with a compelling hook
+          2. Present key findings logically
+          3. Include practical implications for developers
+          4. Close with a forward-looking conclusion
+        expected_output: |
+          A 400-500 word article suitable for a technical blog,
+          with clear sections, professional tone, and concrete takeaways.
@@ -0,0 +1,244 @@
+"""
+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)
@@ -0,0 +1,135 @@
+"""
+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())
@@ -0,0 +1,31 @@
+# Approval Examples
+
+Minimal examples showing how to route tool-execution approvals through
+different backends.
+
+## Quick Start
+
+```bash
+pip install praisonaiagents praisonai[bot]
+export OPENAI_API_KEY=sk-...
+```
+
+| Backend  | Script               | Extra env vars                                   |
+|----------|-----------------------|--------------------------------------------------|
+| Slack    | `slack_approval.py`   | `SLACK_BOT_TOKEN`, `SLACK_CHANNEL`               |
+| Telegram | `telegram_approval.py`| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`         |
+| Discord  | `discord_approval.py` | `DISCORD_BOT_TOKEN`, `DISCORD_CHANNEL_ID`        |
+| HTTP     | `http_approval.py`    | *(none — opens a local web dashboard)*           |
+| Agent    | `agent_approval.py`   | *(none — AI reviewer agent decides)*             |
+
+## SSL Verification
+
+For corporate proxy / CA issues, Discord and Telegram backends support
+optional SSL bypass:
+
+```bash
+export PRAISONAI_DISCORD_SSL_VERIFY=false
+export PRAISONAI_TELEGRAM_SSL_VERIFY=false
+```
+
+Default is `true` (secure).
@@ -0,0 +1,26 @@
+"""
+Agent Approval Example
+======================
+Uses an AI agent as an automated reviewer to approve/deny tool calls.
+
+Requires:
+    pip install praisonaiagents
+    export OPENAI_API_KEY=sk-...
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.approval import AgentApproval
+from praisonaiagents.tools.shell_tools import execute_command
+
+reviewer = AgentApproval(
+    instructions="Only approve read-only commands like 'ls' or 'cat'. Deny destructive commands.",
+)
+
+agent = Agent(
+    name="DevOps",
+    instructions="You are a DevOps assistant. Use shell tools when asked.",
+    tools=[execute_command],
+    approval=reviewer,
+)
+
+agent.start("List files in the current directory")
@@ -0,0 +1,24 @@
+"""
+Discord Approval Example
+========================
+Routes tool approvals to a Discord channel.
+
+Requires:
+    pip install praisonaiagents praisonai[bot]
+    export DISCORD_BOT_TOKEN=MTIz...
+    export DISCORD_CHANNEL_ID=1234567890
+    export OPENAI_API_KEY=sk-...
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.shell_tools import execute_command
+from praisonai.bots import DiscordApproval
+
+agent = Agent(
+    name="DevOps",
+    instructions="You are a DevOps assistant. Use shell tools when asked.",
+    tools=[execute_command],
+    approval=DiscordApproval(),
+)
+
+agent.start("List files in the current directory")
@@ -0,0 +1,22 @@
+"""
+HTTP Approval Example
+=====================
+Opens a local web dashboard for tool approvals.
+
+Requires:
+    pip install praisonaiagents praisonai[bot]
+    export OPENAI_API_KEY=sk-...
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.shell_tools import execute_command
+from praisonai.bots import HTTPApproval
+
+agent = Agent(
+    name="DevOps",
+    instructions="You are a DevOps assistant. Use shell tools when asked.",
+    tools=[execute_command],
+    approval=HTTPApproval(),
+)
+
+agent.start("List files in the current directory")
@@ -0,0 +1,24 @@
+"""
+Slack Approval Example
+======================
+Routes tool approvals to a Slack channel.
+
+Requires:
+    pip install praisonaiagents praisonai[bot]
+    export SLACK_BOT_TOKEN=xoxb-...
+    export SLACK_CHANNEL=C0123456789
+    export OPENAI_API_KEY=sk-...
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.shell_tools import execute_command
+from praisonai.bots import SlackApproval
+
+agent = Agent(
+    name="DevOps",
+    instructions="You are a DevOps assistant. Use shell tools when asked.",
+    tools=[execute_command],
+    approval=SlackApproval(),
+)
+
+agent.start("List files in the current directory")
@@ -0,0 +1,24 @@
+"""
+Telegram Approval Example
+=========================
+Routes tool approvals to a Telegram chat.
+
+Requires:
+    pip install praisonaiagents praisonai[bot]
+    export TELEGRAM_BOT_TOKEN=123456:ABC-...
+    export TELEGRAM_CHAT_ID=987654321
+    export OPENAI_API_KEY=sk-...
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.shell_tools import execute_command
+from praisonai.bots import TelegramApproval
+
+agent = Agent(
+    name="DevOps",
+    instructions="You are a DevOps assistant. Use shell tools when asked.",
+    tools=[execute_command],
+    approval=TelegramApproval(),
+)
+
+agent.start("List files in the current directory")
@@ -2,10 +2,10 @@
 """
 Basic Background Tasks Example for PraisonAI Agents.

-This example demonstrates how to use the background task system to:
-1. Run tasks asynchronously
-2. Track task progress
-3. Cancel running tasks
+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
 4. Handle task completion

 Usage:
@@ -13,71 +13,73 @@ Usage:
 """

 import asyncio
-import time
-
+from praisonaiagents import Agent
 from praisonaiagents.background import BackgroundRunner, BackgroundConfig, TaskStatus


 async def main():
    print("=" * 60)
-    print("Background Tasks Demo")
+    print("Agent-Centric Background Tasks Demo")
    print("=" * 60)
    
-    # Create a background runner with config
-    config = BackgroundConfig(max_concurrent_tasks=3)
-    runner = BackgroundRunner(config=config)
+    # 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}")
    
    # Define some example tasks
-    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 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"
    
-    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"
+    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}"
    
-    # Submit tasks
-    print("\n--- Submitting Tasks ---")
+    # Submit tasks via background runner
+    print("\n--- Submitting Background Tasks ---")
    
-    task1 = await runner.submit(slow_task, args=(1.0, "quick-job"), name="task1")
-    print(f"✅ Submitted task 1: {task1.id[:8]}")
+    task1 = await runner.submit(
+        research_task, 
+        args=("AI trends 2025",), 
+        name="research_ai"
+    )
+    print(f"✅ Submitted research task: {task1.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]}")
+    task2 = await runner.submit(
+        analysis_task, 
+        args=("market data",), 
+        name="analyze_market"
+    )
+    print(f"✅ Submitted analysis task: {task2.id[:8]}")
    
    # List all tasks
    print("\n--- Task Status ---")
    for task in runner.tasks:
        print(f"  [{task.id[:8]}] {task.status.value}")
    
-    # 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}")
-    
-    # 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 ---")
+    # Wait for tasks to complete
+    print("\n--- Waiting for Tasks ---")
+    await task1.wait(timeout=10.0)
    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}")
+    # Final results
+    print("\n--- Results ---")
+    for task in [task1, task2]:
+        status = "✅" if task.status == TaskStatus.COMPLETED else "❌"
+        print(f"  {status} {task.result}")
    
    # Cleanup
    runner.clear_completed()
@@ -0,0 +1,23 @@
+"""Calculator with Tests - Editor Output Example.
+
+Builds a calculator module, writes unit tests, runs them, generates a
+coverage-style report, and reads it back.
+"""
+from praisonaiagents import Agent
+from praisonaiagents.tools import (
+    write_file, read_file, execute_command
+)
+
+agent = Agent(
+    instructions="You are a helpful coding assistant.",
+    output="editor",
+    tools=[write_file, read_file, execute_command],
+    approval=True,
+)
+agent.start(
+    "Build a mini calculator - create /tmp/calculator.py with add, subtract, "
+    "multiply, divide functions, write unit tests in /tmp/test_calculator.py "
+    "using unittest, run the tests to make sure they pass, then generate a "
+    "coverage-style report in /tmp/calc_report.md listing which functions were "
+    "tested and read it back"
+)
@@ -0,0 +1,22 @@
+"""Fibonacci Generator - Editor Output Example.
+
+Creates a Fibonacci script, runs it, writes a summary, and reads back
+both files to verify everything looks good.
+"""
+from praisonaiagents import Agent
+from praisonaiagents.tools import (
+    write_file, read_file, execute_command, list_directory
+)
+
+agent = Agent(
+    instructions="You are a helpful coding assistant.",
+    output="editor",
+    tools=[write_file, read_file, execute_command, list_directory],
+    approval=True,
+)
+agent.start(
+    "Create a Python file at /tmp/fibonacci.py that generates the first 20 "
+    "Fibonacci numbers, run it to verify the output is correct, then write "
+    "a summary to /tmp/fib_summary.md explaining the algorithm you used and "
+    "the output, finally read back both files to confirm everything looks good"
+)
@@ -0,0 +1,36 @@
+"""Multi-Step Research - Editor Output Example.
+
+Researches Python frameworks, creates comparison code, runs it, writes a
+markdown report, reads it back, lists files, and gets system info.
+"""
+from praisonaiagents import Agent
+from praisonaiagents.tools import (
+    write_file, read_file, execute_command, list_directory, get_system_info
+)
+
+try:
+    from praisonaiagents.tools import web_search
+    tools = [web_search, write_file, read_file, execute_command,
+             list_directory, get_system_info]
+except ImportError:
+    tools = [write_file, read_file, execute_command,
+             list_directory, get_system_info]
+
+agent = Agent(
+    instructions="You are a helpful research assistant.",
+    output="editor",
+    tools=tools,
+    approval=True,
+)
+agent.start(
+    "Research the top 3 Python web frameworks (Django, FastAPI, Flask), then: "
+    "1) Search the web for each framework's latest version and key features, "
+    "2) Create a file called /tmp/framework_comparison.py that contains a "
+    "Python dictionary with the comparison data, "
+    "3) Execute the code to verify the dictionary is valid, "
+    "4) Write a markdown report to /tmp/framework_report.md summarizing your "
+    "findings in a table format, "
+    "5) Read back the report file to verify it was written correctly, "
+    "6) List the files in /tmp to confirm both files exist, "
+    "7) Get system info to note what OS this report was generated on"
+)
@@ -0,0 +1,21 @@
+"""System Audit - Editor Output Example.
+
+Runs system commands, gathers info, writes a report, and reads it back.
+"""
+from praisonaiagents import Agent
+from praisonaiagents.tools import (
+    write_file, read_file, execute_command
+)
+
+agent = Agent(
+    instructions="You are a helpful system administration assistant.",
+    output="editor",
+    tools=[write_file, read_file, execute_command],
+    approval=True,
+)
+agent.start(
+    "Investigate my system - get the current date, check disk usage, find out "
+    "what Python version is installed, list running processes sorted by memory, "
+    "then write all findings to /tmp/system_audit.md as a neat report and read "
+    "it back to verify"
+)
@@ -0,0 +1,28 @@
+"""Weather Search - Editor Output Example.
+
+Searches for weather, creates JSON data, writes a parser script, executes
+it, and lists created files.
+"""
+from praisonaiagents import Agent
+from praisonaiagents.tools import (
+    write_file, execute_command, list_directory
+)
+
+try:
+    from praisonaiagents.tools import web_search
+    tools = [web_search, write_file, execute_command, list_directory]
+except ImportError:
+    tools = [write_file, execute_command, list_directory]
+
+agent = Agent(
+    instructions="You are a helpful research assistant.",
+    output="editor",
+    tools=tools,
+    approval=True,
+)
+agent.start(
+    "Search the web for the current weather in Tokyo, create a JSON file at "
+    "/tmp/weather_data.json with the findings, then write a Python script at "
+    "/tmp/parse_weather.py that reads the JSON and prints a formatted weather "
+    "report, execute the script, and list all files you created in /tmp"
+)
@@ -0,0 +1,146 @@
+#!/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()
@@ -0,0 +1,43 @@
+"""
+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!")
@@ -2,12 +2,14 @@
 Embeddings Capability Example

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

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

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

+# Same thing using embedding() alias
+print("\n=== Single Text Embedding (using embedding alias) ===")
+result = embedding(
+    input="Hello, world!",
+    model="text-embedding-3-small"
+)
+print(f"Embedding dimensions: {len(result.embeddings[0])}")
+
 # Multiple text embeddings
 print("\n=== Multiple Text Embeddings ===")
 result = embed(
@@ -25,3 +35,12 @@ result = embed(
 print(f"Number of embeddings: {len(result.embeddings)}")
 for i, emb in enumerate(result.embeddings):
    print(f"  Text {i+1}: {len(emb)} dimensions")
+
+# With custom dimensions (for models that support it)
+print("\n=== Custom Dimensions ===")
+result = embed(
+    input="Hello world",
+    model="text-embedding-3-large",
+    dimensions=256
+)
+print(f"Reduced dimensions: {len(result.embeddings[0])}")
@@ -163,7 +163,7 @@ def main():
            list_all_templates_tool,
            get_template_details_tool
        ],
-        verbose=True
+        output="verbose"  # Use new consolidated param
    )
    
    # Example queries
@@ -2,10 +2,10 @@
 """
 Basic Checkpoints Example for PraisonAI Agents.

-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
+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
 4. Restore to a previous checkpoint

 Usage:
@@ -16,6 +16,7 @@ import asyncio
 import tempfile
 from pathlib import Path

+from praisonaiagents import Agent
 from praisonaiagents.checkpoints import CheckpointService


@@ -23,7 +24,7 @@ async def main():
    # Create a temporary workspace for demonstration
    with tempfile.TemporaryDirectory() as workspace:
        print("=" * 60)
-        print("Shadow Git Checkpointing Demo")
+        print("Agent-Centric Checkpointing Demo")
        print("=" * 60)
        print(f"\nWorkspace: {workspace}")
        
@@ -32,24 +33,34 @@ async def main():
        test_file.write_text("# Initial content\nprint('Hello, World!')\n")
        print(f"\n✅ Created initial file: {test_file.name}")
        
-        # Initialize the checkpoint service
-        service = CheckpointService(workspace_dir=workspace)
+        # 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}")
        
        try:
            # Initialize the shadow git repository
            print("\n--- Initializing Checkpoint Service ---")
-            await service.initialize()
+            await checkpoint_service.initialize()
            print("✅ Shadow git repository initialized")
            
            # Save first checkpoint
            print("\n--- Saving Checkpoint 1: Initial State ---")
-            result1 = await service.save("Initial state")
+            result1 = await checkpoint_service.save("Initial state")
            print(f"✅ Checkpoint saved: {result1.checkpoint.id[:8]}")
            print(f"   Message: {result1.checkpoint.message}")
            
-            # Make some changes
-            print("\n--- Making Changes ---")
-            test_file.write_text("# Modified content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
+            # 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")
            print("✅ Modified example.py")
            
            # Create a new file
@@ -58,38 +69,32 @@ async def main():
            print("✅ Created utils.py")
            
            # Save second checkpoint
-            print("\n--- Saving Checkpoint 2: After Changes ---")
-            result2 = await service.save("Added features")
+            print("\n--- Saving Checkpoint 2: After Refactoring ---")
+            result2 = await checkpoint_service.save("Added features")
            print(f"✅ Checkpoint saved: {result2.checkpoint.id[:8]}")
            
            # List all checkpoints
            print("\n--- Listing All Checkpoints ---")
-            checkpoints = await service.list_checkpoints()
-            for i, cp in enumerate(checkpoints, 1):
-                print(f"  {i}. [{cp.id[:8]}] {cp.message} ({cp.timestamp})")
+            checkpoints_list = await checkpoint_service.list_checkpoints()
+            for i, cp in enumerate(checkpoints_list, 1):
+                print(f"  {i}. [{cp.id[:8]}] {cp.message}")
            
            # Show diff
-            print("\n--- Current Diff (uncommitted changes) ---")
-            diff = await service.diff()
+            print("\n--- Current Diff ---")
+            diff = await checkpoint_service.diff()
            if diff.files:
                for f in diff.files:
                    print(f"  {f.status}: {f.path}")
            else:
                print("  No uncommitted changes")
            
-            # 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}")
+            # Make more changes
+            test_file.write_text("# Bad changes\nprint('This will be reverted')\n")
+            print("\n✅ Made problematic changes to example.py")
            
            # Restore to checkpoint 2
            print(f"\n--- Restoring to Checkpoint: {result2.checkpoint.id[:8]} ---")
-            await service.restore(result2.checkpoint.id)
+            await checkpoint_service.restore(result2.checkpoint.id)
            print("✅ Restored successfully!")
            
            # Verify restoration
@@ -0,0 +1,5 @@
+#!/bin/bash
+# Calculator with tests: code + unit tests + test execution + coverage report
+# Tests: multiple file creation, test execution, report generation, file reading
+
+praisonai "Build a mini calculator - create /tmp/calculator.py with add, subtract, multiply, divide functions, write unit tests in /tmp/test_calculator.py using unittest, run the tests to make sure they pass, then generate a coverage-style report in /tmp/calc_report.md listing which functions were tested and read it back" --trust
@@ -0,0 +1,5 @@
+#!/bin/bash
+# Fibonacci generator: code creation, execution, documentation, verification
+# Tests: file creation, code execution, markdown writing, file reading
+
+praisonai "Create a Python file at /tmp/fibonacci.py that generates the first 20 Fibonacci numbers, run it to verify the output is correct, then write a summary to /tmp/fib_summary.md explaining the algorithm you used and the output, finally read back both files to confirm everything looks good" --trust
@@ -0,0 +1,5 @@
+#!/bin/bash
+# Multi-step research: web search, file creation, code execution, reporting
+# Tests: web search, file write, code execution, markdown report, file read, directory listing, system info
+
+praisonai "Research the top 3 Python web frameworks (Django, FastAPI, Flask), then: 1) Search the web for each framework's latest version and key features, 2) Create a file called /tmp/framework_comparison.py that contains a Python dictionary with the comparison data, 3) Execute the code to verify the dictionary is valid, 4) Write a markdown report to /tmp/framework_report.md summarizing your findings in a table format, 5) Read back the report file to verify it was written correctly, 6) List the files in /tmp to confirm both files exist, 7) Get system info to note what OS this report was generated on, 8) Analyze the Python code you wrote for any issues, 9) Format the Python code properly, 10) Finally search for any recent news about Python 3.13 features" --trust
@@ -0,0 +1,5 @@
+#!/bin/bash
+# System audit: multiple command executions, report generation
+# Tests: command execution (date, disk, python, processes), file creation, file reading
+
+praisonai "Investigate my system - get the current date, check disk usage, find out what Python version is installed, list running processes sorted by memory, then write all findings to /tmp/system_audit.md as a neat report and read it back to verify" --trust
@@ -0,0 +1,5 @@
+#!/bin/bash
+# Todo app: multi-file app creation, execution, documentation, verification
+# Tests: multiple file creation, code execution, markdown docs, directory listing
+
+praisonai "Write a todo list app at /tmp/todo.py with functions to add, remove, and list tasks stored in /tmp/todos.json, run the script with some sample tasks added, then create documentation at /tmp/todo_docs.md explaining usage with examples, and verify all three files exist" --trust
@@ -0,0 +1,5 @@
+#!/bin/bash
+# Weather search: web search, JSON creation, Python script, execution
+# Tests: web search, JSON file creation, Python scripting, code execution, directory listing
+
+praisonai "Search the web for the current weather in Tokyo, create a JSON file at /tmp/weather_data.json with the findings, then write a Python script at /tmp/parse_weather.py that reads the JSON and prints a formatted weather report, execute the script, and list all files you created in /tmp" --trust
@@ -2,140 +2,114 @@
 """
 Basic Context Compaction Example for PraisonAI Agents.

-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
+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

 Usage:
    python basic_compaction.py
 """

-from praisonaiagents.compaction import (
-    ContextCompactor, CompactionConfig, CompactionStrategy, CompactionResult
-)
+from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig


 def main():
    print("=" * 60)
-    print("Context Compaction Demo")
+    print("Agent-Centric Context Compaction Demo")
    print("=" * 60)
    
    # ==========================================================================
-    # Sample Messages
+    # Available Strategies
    # ==========================================================================
-    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)]"},
+    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"),
    ]
    
-    print(f"\n--- Original Messages ---")
-    print(f"  Message count: {len(messages)}")
+    for name, desc in strategies:
+        print(f"  {name}: {desc}")
    
    # ==========================================================================
-    # Basic Compaction
+    # Agent with Context Compaction via context= param
    # ==========================================================================
-    print("\n--- Basic Compaction (Truncate Strategy) ---")
+    print("\n--- Creating Agent with Context Compaction ---")
    
-    compactor = ContextCompactor(
-        max_tokens=50,  # Low limit to trigger compaction
-        strategy=CompactionStrategy.TRUNCATE,
-        preserve_system=True,
-        preserve_recent=2
+    # 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",
+        )
    )
    
-    # 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%}")
+    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}")
    
    # ==========================================================================
-    # Sliding Window Strategy
+    # Different Strategy Examples via context= param
    # ==========================================================================
-    print("\n--- Sliding Window Strategy ---")
+    print("\n--- Strategy Examples ---")
    
-    compactor = ContextCompactor(
-        max_tokens=50,
-        strategy=CompactionStrategy.SLIDING,
-        preserve_system=True,
-        preserve_recent=3
+    # Sliding window strategy
+    sliding_agent = Agent(
+        name="SlidingAgent",
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="sliding_window",
+        )
    )
+    print(f"  Sliding: strategy={sliding_agent.context_manager.config.strategy}")
    
-    compacted, result = compactor.compact(messages)
-    
-    print(f"  Messages kept: {result.messages_kept}")
-    print(f"  Messages removed: {result.messages_removed}")
-    print(f"  Strategy: {result.strategy_used.value}")
-    
-    # ==========================================================================
-    # Summarize Strategy
-    # ==========================================================================
-    print("\n--- Summarize Strategy ---")
-    
-    compactor = ContextCompactor(
-        max_tokens=50,
-        strategy=CompactionStrategy.SUMMARIZE,
-        preserve_system=True,
-        preserve_recent=2
+    # 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)
-    
-    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
+    # Smart strategy
+    smart_agent = Agent(
+        name="SmartAgent",
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="smart",
+        )
    )
-    
-    compacted, result = compactor.compact(messages)
-    
-    print(f"  Was compacted: {result.was_compacted}")
-    print(f"  Messages unchanged: {len(compacted) == len(messages)}")
+    print(f"  Smart: strategy={smart_agent.context_manager.config.strategy}")
    
    # ==========================================================================
-    # Result Serialization
+    # Context Manager Stats Demo
    # ==========================================================================
-    print("\n--- Result Serialization ---")
+    print("\n--- Context Manager Stats Demo ---")
    
-    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}")
+    # 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")
    
    print("\n" + "=" * 60)
    print("Demo Complete!")
@@ -22,7 +22,7 @@ custom_modes = {
 }

 # Create handler with verbose output
-handler = CompareHandler(verbose=True)
+handler = CompareHandler(output="verbose")

 # Example: Manually create comparison results for analysis
 # (useful for testing without API calls)
@@ -22,7 +22,7 @@ modes = parse_modes("basic,tools,planning")
 print(f"\nParsed modes: {modes}")

 # Create compare handler
-handler = CompareHandler(verbose=True)
+handler = CompareHandler(output="verbose")

 # Compare modes (this will run actual agent calls)
 # Uncomment to run:
@@ -0,0 +1,96 @@
+# 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
+```
@@ -0,0 +1,23 @@
+"""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)
@@ -0,0 +1,17 @@
+"""
+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)
@@ -0,0 +1,55 @@
+"""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}")
@@ -0,0 +1,12 @@
+"""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)
@@ -0,0 +1,17 @@
+"""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)
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,23 @@
+"""
+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)
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,16 @@
+"""
+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)
@@ -0,0 +1,26 @@
+"""
+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)
@@ -0,0 +1,28 @@
+"""
+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)
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,24 @@
+"""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)
@@ -0,0 +1,16 @@
+"""
+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)
@@ -0,0 +1,13 @@
+"""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)
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,33 @@
+"""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
@@ -0,0 +1,18 @@
+"""
+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)
@@ -0,0 +1,22 @@
+"""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)
@@ -0,0 +1,32 @@
+"""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}")
@@ -1,87 +1,71 @@
 """
-Fast Context with Agent - Basic Example
+Fast Context - Basic Example

-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 rapid code search capabilities.
+Use it directly from the context module for code search.

-Fast Context provides:
+FastContext provides:
 - 10-20x faster code search than traditional methods
 - Parallel execution (8 concurrent searches)
 - Automatic caching for repeated queries
- Seamless integration with Agent workflows
+
+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(...)).
 """

 from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig

 def main():
    print("=" * 60)
-    print("Agent with Fast Context - Basic Example")
+    print("Agent with Context Management - Basic Example")
    print("=" * 60)
    
-    # Create an agent with Fast Context enabled
-    # This is the simplest configuration
+    # Create an agent with context management enabled
+    # This is the recommended way to use context features
    agent = Agent(
        name="CodeAssistant",
        instructions="You are a helpful code assistant.",
-        fast_context=True,  # Enable Fast Context
-        fast_context_path=".",  # Search in current directory
-        verbose=False
+        context=True,  # Enable context management with defaults
    )
    
-    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}")
+    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}")
    
-    # Use delegate_to_fast_context to search code
+    # For FastContext code search, use the module directly
    print("\n" + "-" * 60)
-    print("Searching for 'class Agent' in the codebase...")
+    print("Using FastContext for code search...")
    print("-" * 60)
    
-    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':")
+    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':")
        print(f"  Files found: {result.total_files}")
        print(f"  Search time: {result.search_time_ms}ms")
-        print(f"  From cache: {result.from_cache}")
+        
+        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("\n" + "=" * 60)
-    print("Fast Context makes code search instant for your agents!")
+    print("Context management is now unified via context= param!")
    print("=" * 60)


@@ -0,0 +1,59 @@
+"""
+Basic Context Management Example
+
+Demonstrates enabling context management with ContextConfig.
+This manages token budgets, auto-compaction, and prevents context overflow.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import ContextConfig, OptimizerStrategy
+
+# Example 1: Enable context with defaults
+agent_basic = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant",
+    context=True  # Auto-compact at 80% utilization
+)
+
+# Example 2: Custom configuration
+agent_custom = Agent(
+    name="CustomAgent",
+    instructions="You are a helpful assistant with custom context settings",
+    context=ContextConfig(
+        auto_compact=True,
+        compact_threshold=0.8,      # Trigger at 80% utilization
+        strategy=OptimizerStrategy.SMART,
+        output_reserve=8000,        # Reserve tokens for output
+        keep_recent_turns=5,        # Always keep last 5 turns
+        tool_output_max=10000,      # Max tokens per tool output
+    )
+)
+
+# Example 3: Sliding window strategy
+agent_sliding = Agent(
+    name="SlidingAgent",
+    instructions="You are a helpful assistant using sliding window",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SLIDING_WINDOW,
+        keep_recent_turns=10,       # Keep last 10 turns
+    )
+)
+
+if __name__ == "__main__":
+    print("=== Basic Context Example ===")
+    print("Context management is automatically enabled.")
+    print()
+    
+    # Test basic agent
+    result = agent_basic.chat("Hello! What is 2 + 2?")
+    print(f"Response: {result}")
+    print()
+    
+    # Show context config
+    print("=== Context Configuration ===")
+    config = ContextConfig(
+        auto_compact=True,
+        compact_threshold=0.8,
+        strategy=OptimizerStrategy.SMART,
+    )
+    print(f"Config: {config.to_dict()}")
@@ -0,0 +1,71 @@
+"""
+Session Tracking Example
+
+Demonstrates tracking conversation state (goal, plan, progress) across turns.
+Inspired by Agno's SessionContextStore pattern.
+"""
+
+from praisonaiagents.context import SessionContextTracker
+
+# Create session tracker
+tracker = SessionContextTracker(
+    session_id="user123",
+    track_summary=True,
+    track_goal=True,
+    track_plan=True,
+    track_progress=True,
+)
+
+# Set the user's goal
+tracker.update_goal("Build a Python web application with Flask")
+
+# Define the plan
+tracker.update_plan([
+    "Create Flask project structure",
+    "Add routes for API endpoints",
+    "Implement database models",
+    "Add authentication",
+    "Write tests",
+    "Deploy to cloud"
+])
+
+# Mark completed steps
+tracker.add_progress("Created Flask project structure")
+tracker.add_progress("Added routes for API endpoints")
+
+# Update summary
+tracker.update_summary(
+    "User is building a Flask web app. Completed project setup and API routes. "
+    "Next: implement database models."
+)
+
+if __name__ == "__main__":
+    print("=== Session Tracking Example ===")
+    print()
+    
+    # Show current state
+    print(f"Session ID: {tracker.session_id}")
+    print(f"Goal: {tracker.goal}")
+    print(f"Plan: {tracker.plan}")
+    print(f"Progress: {tracker.progress}")
+    print()
+    
+    # Get context string (simple format)
+    print("=== Context String ===")
+    print(tracker.to_context_string())
+    print()
+    
+    # Get system prompt section (XML format with guidelines)
+    print("=== System Prompt Section ===")
+    print(tracker.to_system_prompt_section())
+    print()
+    
+    # Export to dict for persistence
+    print("=== Export as Dict ===")
+    data = tracker.to_dict()
+    print(f"Exported: {data.keys()}")
+    print()
+    
+    # Recreate from dict
+    new_tracker = SessionContextTracker.from_dict(data)
+    print(f"Restored goal: {new_tracker.goal}")
@@ -0,0 +1,81 @@
+"""
+Multi-Memory Aggregation Example
+
+Demonstrates concurrent fetching from multiple context sources.
+Inspired by CrewAI's ContextualMemory pattern.
+"""
+
+import asyncio
+from praisonaiagents.context import ContextAggregator, create_aggregator_from_config
+
+# Example 1: Basic aggregator with mock sources
+def mock_memory_search(query: str) -> str:
+    """Mock memory search - returns recent conversation context."""
+    return f"[Memory] User previously asked about: {query}. They prefer Python."
+
+def mock_knowledge_search(query: str) -> str:
+    """Mock knowledge search - returns facts from knowledge base."""
+    return f"[Knowledge] Relevant facts: Python is a high-level programming language."
+
+def mock_rag_retrieve(query: str) -> str:
+    """Mock RAG retrieval - returns document chunks."""
+    return f"[RAG] Retrieved: Documentation about {query} from the codebase."
+
+# Create aggregator
+aggregator = ContextAggregator(
+    max_tokens=4000,
+    separator="\n\n---\n\n",
+    include_source_labels=True
+)
+
+# Register sources with priorities (lower = higher priority)
+aggregator.register_source("memory", mock_memory_search, priority=10)
+aggregator.register_source("knowledge", mock_knowledge_search, priority=20)
+aggregator.register_source("rag", mock_rag_retrieve, priority=30)
+
+async def demo_async():
+    """Demo async aggregation."""
+    print("=== Async Aggregation ===")
+    result = await aggregator.aggregate("Python web development")
+    print(f"Sources used: {result.sources_used}")
+    print(f"Tokens used: {result.tokens_used}")
+    print(f"Fetch times: {result.fetch_times}")
+    print()
+    print("Context:")
+    print(result.context)
+    return result
+
+def demo_sync():
+    """Demo sync aggregation."""
+    print("=== Sync Aggregation ===")
+    result = aggregator.aggregate_sync("Flask API development")
+    print(f"Sources used: {result.sources_used}")
+    print(f"Tokens used: {result.tokens_used}")
+    print()
+    print("Context:")
+    print(result.context)
+    return result
+
+if __name__ == "__main__":
+    print("=== Multi-Memory Aggregation Example ===")
+    print()
+    
+    # Show registered sources
+    print(f"Registered sources: {aggregator.sources}")
+    print()
+    
+    # Demo sync aggregation
+    demo_sync()
+    print()
+    
+    # Demo async aggregation
+    asyncio.run(demo_async())
+    print()
+    
+    # Demo selective sources
+    print("=== Selective Sources ===")
+    result = aggregator.aggregate_sync(
+        "Find database info",
+        sources=["memory", "knowledge"]  # Only use these
+    )
+    print(f"Sources used: {result.sources_used}")
@@ -1,103 +1,98 @@
 """
-Example 4: Agent Integration with Fast Context
+Example 4: Agent Integration with Context Management

-This example shows how to use Fast Context integrated with the Agent class
-for automatic code search delegation.
+This example shows how to use context management with the Agent class.
+Context management is now unified via the context= parameter.

 Benefits:
 - Seamless integration with existing Agent workflows
- Automatic context injection for code-related queries
- Configurable via Agent parameters or environment variables
+- Automatic token tracking and optimization
+- Configurable via context= parameter with ManagerConfig
 """

 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 Fast Context")
+    print("Agent Integration with Context Management")
    print("=" * 70)
    
-    # Create an agent with Fast Context enabled
-    print("\n1. Creating Agent with Fast Context")
+    # Create an agent with context management enabled
+    print("\n1. Creating Agent with Context Management")
    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 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
+        instructions="You are a helpful code assistant.",
+        context=config,
+        output="silent"
    )
    
    print(f"   Agent name: {agent.name}")
-    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}")
+    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}")
    
-    # Use delegate_to_fast_context for code search
-    print("\n2. Delegating Code Search to Fast Context")
+    # For FastContext code search, use the module directly
+    print("\n2. Using FastContext for Code Search")
    print("-" * 40)
    
-    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)
+    try:
+        from praisonaiagents.context.fast import FastContext
        
-        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")
+        fc = FastContext(
+            workspace_path=WORKSPACE,
+            model="gpt-4o-mini",
+            max_turns=4,
+            max_parallel=8,
+            timeout=30.0,
+        )
        
-        for f in result.files[:3]:
-            print(f"   - {f.path}")
+        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}")
    
    # Show configuration options
-    print("\n4. Configuration Options")
+    print("\n3. Configuration Options")
    print("-" * 40)
    
-    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("   Agent context= parameter:")
+    print("   - context=True                   # Enable with defaults")
+    print("   - context=ManagerConfig(...)     # Custom configuration")
+    print("   - context=False                  # Disabled (default)")
    
-    print("\n   Environment variables:")
-    print("   - FAST_CONTEXT_MODEL")
-    print("   - FAST_CONTEXT_MAX_TURNS")
+    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("   - FAST_CONTEXT_PARALLELISM")
    print("   - FAST_CONTEXT_TIMEOUT")
    print("   - FAST_CONTEXT_CACHE")
@@ -0,0 +1,76 @@
+"""
+Compaction Strategies Example
+
+Demonstrates different context compaction strategies.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import ContextConfig, OptimizerStrategy
+
+# Strategy 1: TRUNCATE - Fast, removes oldest messages
+agent_truncate = Agent(
+    name="TruncateAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.TRUNCATE,
+        compact_threshold=0.8,
+    )
+)
+
+# Strategy 2: SLIDING_WINDOW - Keeps recent N turns
+agent_sliding = Agent(
+    name="SlidingAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SLIDING_WINDOW,
+        keep_recent_turns=10,
+    )
+)
+
+# Strategy 3: SMART - Importance-based (default)
+agent_smart = Agent(
+    name="SmartAgent",
+    instructions="You are a helpful assistant",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.SMART,  # Default
+        compact_threshold=0.8,
+    )
+)
+
+# Strategy 4: PRUNE_TOOLS - Truncate old tool outputs
+agent_prune = Agent(
+    name="PruneAgent",
+    instructions="You are a helpful assistant with tools",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.PRUNE_TOOLS,
+        tool_output_max=5000,  # Max tokens per tool output
+    )
+)
+
+# Strategy 5: NON_DESTRUCTIVE - Only prune tools, keep all history
+agent_safe = Agent(
+    name="SafeAgent",
+    instructions="You are a helpful assistant (safety-critical)",
+    context=ContextConfig(
+        strategy=OptimizerStrategy.NON_DESTRUCTIVE,
+    )
+)
+
+if __name__ == "__main__":
+    print("=== Compaction Strategies Example ===")
+    print()
+    
+    strategies = [
+        ("TRUNCATE", OptimizerStrategy.TRUNCATE, "Remove oldest messages"),
+        ("SLIDING_WINDOW", OptimizerStrategy.SLIDING_WINDOW, "Keep last N turns"),
+        ("SMART", OptimizerStrategy.SMART, "Importance-based (default)"),
+        ("PRUNE_TOOLS", OptimizerStrategy.PRUNE_TOOLS, "Truncate tool outputs"),
+        ("NON_DESTRUCTIVE", OptimizerStrategy.NON_DESTRUCTIVE, "Only prune tools"),
+    ]
+    
+    for name, strategy, description in strategies:
+        print(f"  {name:20} - {description}")
+    
+    print()
+    print("Usage:")
+    print("  context=ContextConfig(strategy=OptimizerStrategy.SLIDING_WINDOW)")