Release v2.3.24

- Add branching support with next_steps and branch_condition fields
- Add loop support with loop_over and loop_var for iterating over variables
- Add on_task_start and on_task_complete callbacks to PraisonAIAgents
- Add variables parameter for global variable substitution across tasks
- Add per-step agent creation from agent_config when no agent assigned
- Add task-level variable substitution in task descriptions
- Refactor workflow

.github/actions/claude-code-action/action.yml

@@ -86,13 +86,29 @@ runs:
     - name: Extract GitHub Context and Create Prompt
       shell: bash
       id: prepare_context
+      env:
+        # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+        EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
+        EVENT_ISSUE_TITLE: ${{ github.event.issue.title }}
+        EVENT_ISSUE_BODY: ${{ github.event.issue.body }}
+        EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+        EVENT_PR_TITLE: ${{ github.event.pull_request.title }}
+        EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+        EVENT_REVIEW_BODY: ${{ github.event.review.body }}
+        EVENT_ASSIGNEE_LOGIN: ${{ github.event.assignee.login }}
+        INPUT_TRIGGER_PHRASE: ${{ inputs.trigger_phrase }}
+        INPUT_ASSIGNEE_TRIGGER: ${{ inputs.assignee_trigger }}
+        INPUT_DIRECT_PROMPT: ${{ inputs.direct_prompt }}
+        EVENT_ACTION: ${{ github.event.action }}
+        EVENT_NAME: ${{ github.event_name }}
+        REPO_NAME: ${{ github.repository }}
       run: |
-        echo "🔍 Extracting GitHub context from event: ${{ github.event_name }}"
+        echo "🔍 Extracting GitHub context from event: $EVENT_NAME"
         
         # Function to check for trigger phrase
         check_trigger() {
           local text="$1"
-          local trigger="${{ inputs.trigger_phrase }}"
+          local trigger="$INPUT_TRIGGER_PHRASE"
           if [[ "$text" == *"$trigger"* ]]; then
             return 0
           fi
@@ -104,11 +120,11 @@ runs:
         USER_REQUEST=""
         CONTEXT_INFO=""
         
-        case "${{ github.event_name }}" in
+        case "$EVENT_NAME" in
           "issue_comment")
-            COMMENT_BODY="${{ github.event.comment.body }}"
-            ISSUE_TITLE="${{ github.event.issue.title }}"
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
             
             if check_trigger "$COMMENT_BODY"; then
               TRIGGER_FOUND="true"
@@ -118,9 +134,9 @@ runs:
             ;;
             
           "pull_request_review_comment")
-            COMMENT_BODY="${{ github.event.comment.body }}"
-            PR_TITLE="${{ github.event.pull_request.title }}"
-            PR_NUMBER="${{ github.event.pull_request.number }}"
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
             
             if check_trigger "$COMMENT_BODY"; then
               TRIGGER_FOUND="true"
@@ -130,9 +146,9 @@ runs:
             ;;
             
           "pull_request_review")
-            REVIEW_BODY="${{ github.event.review.body }}"
-            PR_TITLE="${{ github.event.pull_request.title }}"
-            PR_NUMBER="${{ github.event.pull_request.number }}"
+            REVIEW_BODY="$EVENT_REVIEW_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
             
             if check_trigger "$REVIEW_BODY"; then
               TRIGGER_FOUND="true"
@@ -142,17 +158,17 @@ runs:
             ;;
             
           "issues")
-            ISSUE_BODY="${{ github.event.issue.body }}"
-            ISSUE_TITLE="${{ github.event.issue.title }}"
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+            ISSUE_BODY="$EVENT_ISSUE_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
             
             if check_trigger "$ISSUE_TITLE" || check_trigger "$ISSUE_BODY"; then
               TRIGGER_FOUND="true"
               USER_REQUEST="$ISSUE_BODY"
               CONTEXT_INFO="Issue #$ISSUE_NUMBER: $ISSUE_TITLE"
-            elif [[ "${{ github.event.action }}" == "assigned" && -n "${{ inputs.assignee_trigger }}" ]]; then
-              ASSIGNEE="${{ github.event.assignee.login }}"
-              if [[ "$ASSIGNEE" == "${{ inputs.assignee_trigger }}" ]]; then
+            elif [[ "$EVENT_ACTION" == "assigned" && -n "$INPUT_ASSIGNEE_TRIGGER" ]]; then
+              ASSIGNEE="$EVENT_ASSIGNEE_LOGIN"
+              if [[ "$ASSIGNEE" == "$INPUT_ASSIGNEE_TRIGGER" ]]; then
                 TRIGGER_FOUND="true"
                 USER_REQUEST="$ISSUE_BODY"
                 CONTEXT_INFO="Issue #$ISSUE_NUMBER assigned to $ASSIGNEE: $ISSUE_TITLE"
@@ -162,9 +178,9 @@ runs:
         esac
         
         # Check for direct prompt override
-        if [[ -n "${{ inputs.direct_prompt }}" ]]; then
+        if [[ -n "$INPUT_DIRECT_PROMPT" ]]; then
           TRIGGER_FOUND="true"
-          USER_REQUEST="${{ inputs.direct_prompt }}"
+          USER_REQUEST="$INPUT_DIRECT_PROMPT"
           CONTEXT_INFO="Automated GitHub workflow"
         fi
         
@@ -181,9 +197,9 @@ runs:
         cat > /tmp/claude-action/github-context-prompt.txt << EOF
         You are Claude Code, an AI assistant helping with GitHub workflows and code.
         
-        Repository: ${{ github.repository }}
+        Repository: $REPO_NAME
         Context: $CONTEXT_INFO
-        Event: ${{ github.event_name }}
+        Event: $EVENT_NAME
         
         User Request:
         $USER_REQUEST

.github/workflows/gemini-issue-review.yml

@@ -46,12 +46,16 @@ jobs:
         id: issue_data
         env:
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+          # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
         run: |
           # Get issue number from event or context
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
-          elif [ "${{ github.event_name }}" = "issues" ]; then
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
+          elif [ "$EVENT_NAME" = "issues" ]; then
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
           else
             echo "Unable to determine issue number"
             exit 1
@@ -62,8 +66,8 @@ jobs:
           
           # Extract additional instructions from comment if triggered by comment
           ADDITIONAL_INSTRUCTIONS=""
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            COMMENT_BODY="${{ github.event.comment.body }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
             ADDITIONAL_INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed -n 's/.*@gemini[[:space:]]*\(.*\)/\1/p' | head -1)
           fi
           

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

@@ -55,21 +55,27 @@ jobs:
         id: get_pr
         env:
           GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+          # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_INPUTS_PR_NUMBER: ${{ github.event.inputs.pr_number }}
+          EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+          EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            PR_NUMBER=${{ github.event.inputs.pr_number }}
-          elif [ "${{ github.event_name }}" = "issue_comment" ]; then
-            PR_NUMBER=${{ github.event.issue.number }}
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            PR_NUMBER=$EVENT_INPUTS_PR_NUMBER
+          elif [ "$EVENT_NAME" = "issue_comment" ]; then
+            PR_NUMBER=$EVENT_ISSUE_NUMBER
           else
-            PR_NUMBER=${{ github.event.pull_request.number }}
+            PR_NUMBER=$EVENT_PR_NUMBER
           fi
           
           echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
           
           # Extract additional instructions from comment (if triggered by comment)
           ADDITIONAL_INSTRUCTIONS=""
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            COMMENT_BODY="${{ github.event.comment.body }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
             ADDITIONAL_INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed 's/.*@gemini//' | xargs)
           fi
           echo "additional_instructions=$ADDITIONAL_INSTRUCTIONS" >> "$GITHUB_OUTPUT"

.github/workflows/test-comprehensive.yml

@@ -27,6 +27,9 @@ jobs:
   comprehensive-test:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      OPENAI_MODEL_NAME: gpt-4o-mini
     strategy:
       matrix:
         python-version: ["3.11"]
@@ -55,11 +58,13 @@ jobs:
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
-    - name: Set environment variables
+    - name: Verify 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
+        if [ -n "$OPENAI_API_KEY" ]; then
+          echo "✅ OPENAI_API_KEY is set (length: ${#OPENAI_API_KEY})"
+        else
+          echo "⚠️ OPENAI_API_KEY is NOT set"
+        fi
 
     - name: Run Comprehensive Test Suite
       run: |

.github/workflows/test-core.yml

@@ -34,7 +34,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
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
@@ -262,7 +262,7 @@ jobs:
         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
+        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'

.github/workflows/unittest.yml

@@ -27,7 +27,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
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
@@ -489,7 +489,7 @@ jobs:
 
     - name: Run Legacy Example Tests
       run: |
-        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings
+        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

docker/Dockerfile

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.2.84" \
+    "praisonai>=2.3.24" \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

docker/README.md

@@ -121,7 +121,7 @@ healthcheck:
 ## 📦 Package Versions
 
 All Docker images use consistent, up-to-date versions:
-- PraisonAI: `>=2.2.84`
+- PraisonAI: `>=2.2.95`
 - PraisonAI Agents: `>=0.0.92`
 - Python: `3.11-slim`
 
@@ -218,7 +218,7 @@ docker-compose up -d
 ### Version Pinning
 To use specific versions, update the Dockerfile:
 ```dockerfile
-RUN pip install "praisonai==2.2.84" "praisonaiagents==0.0.92"
+RUN pip install "praisonai==2.2.95" "praisonaiagents==0.0.92"
 ```
 
 ## 🌐 Production Deployment

docker/docker-compose.dev.yml

@@ -137,22 +137,11 @@ services:
       POSTGRES_USER: praisonai
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-praisonai_dev_pass}
     volumes:
-   database:
-     image: postgres:15-alpine
-     environment:
-       POSTGRES_DB: praisonai_dev
-       POSTGRES_USER: praisonai
-       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-praisonai_dev_pass}
-     volumes:
-       - postgres_data:/var/lib/postgresql/data
-     read_only: true
-     tmpfs:
-       - /tmp
-       - /var/tmp
-     ports:
-       - "5432:5432"
-     networks:
       - postgres_data:/var/lib/postgresql/data
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /var/tmp
     ports:
       - "5432:5432"
     networks:

examples/context/00_agent_fast_context_basic.py

@@ -0,0 +1,89 @@
+"""
+Fast Context with Agent - 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.
+
+Fast Context provides:
+- 10-20x faster code search than traditional methods
+- Parallel execution (8 concurrent searches)
+- Automatic caching for repeated queries
+- Seamless integration with Agent workflows
+"""
+
+from praisonaiagents import Agent
+
+def main():
+    print("=" * 60)
+    print("Agent with Fast Context - Basic Example")
+    print("=" * 60)
+    
+    # Create an agent with Fast Context enabled
+    # This is the simplest configuration
+    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
+    )
+    
+    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}")
+    
+    # Use delegate_to_fast_context to search code
+    print("\n" + "-" * 60)
+    print("Searching for 'class Agent' in the codebase...")
+    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':")
+        print(f"  Files found: {result.total_files}")
+        print(f"  Search time: {result.search_time_ms}ms")
+        print(f"  From cache: {result.from_cache}")
+    
+    print("\n" + "=" * 60)
+    print("Fast Context makes code search instant for your agents!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/01_basic_fast_context.py

@@ -0,0 +1,84 @@
+"""
+Example 1: Basic Fast Context Usage
+
+This example demonstrates the basic usage of Fast Context for rapid code search.
+Fast Context is 10-20x faster than traditional sequential search because it:
+- Executes up to 8 tool calls in parallel
+- Limits search to 4 turns maximum
+- Uses a lightweight model optimized for search
+"""
+
+from praisonaiagents.context.fast import FastContext
+import time
+
+def main():
+    print("=" * 70)
+    print("Fast Context - Basic Usage Example")
+    print("=" * 70)
+    
+    # Create FastContext instance pointing to the praisonai-agents codebase
+    fc = FastContext(
+        workspace_path="/Users/praison/praisonai-package/src/praisonai-agents"
+    )
+    
+    # Example 1: Simple pattern search
+    print("\n1. Simple Pattern Search")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result = fc.search("def chat")
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Query: 'def chat'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms (total: {elapsed:.0f}ms)")
+    print(f"   Turns used: {result.turns_used}")
+    print(f"   Tool calls: {result.total_tool_calls}")
+    
+    if result.files:
+        print("\n   Top matches:")
+        for f in result.files[:3]:
+            print(f"   - {f.path}")
+            for lr in f.line_ranges[:2]:
+                print(f"     Lines {lr.start}-{lr.end}")
+    
+    # Example 2: Search for class definitions
+    print("\n2. Search for Class Definitions")
+    print("-" * 40)
+    
+    result = fc.search("class Agent")
+    print(f"   Query: 'class Agent'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms")
+    
+    if result.files:
+        print("\n   Files containing 'class Agent':")
+        for f in result.files[:5]:
+            print(f"   - {f.path} (relevance: {f.relevance_score:.2f})")
+    
+    # Example 3: Search for imports
+    print("\n3. Search for Specific Imports")
+    print("-" * 40)
+    
+    result = fc.search("from typing import")
+    print(f"   Query: 'from typing import'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms")
+    
+    # Example 4: Get formatted context string
+    print("\n4. Get Formatted Context for Agent")
+    print("-" * 40)
+    
+    context = fc.get_context_for_agent("authentication", max_files=3)
+    print(f"   Context length: {len(context)} characters")
+    print(f"   Preview:")
+    preview = context[:300].replace('\n', '\n   ')
+    print(f"   {preview}...")
+    
+    print("\n" + "=" * 70)
+    print("Fast Context provides rapid, parallel code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/02_parallel_vs_sequential.py

@@ -0,0 +1,113 @@
+"""
+Example 2: Parallel vs Sequential Search Comparison
+
+This example demonstrates the speed advantage of Fast Context's parallel
+execution compared to traditional sequential search.
+
+Key insight: Fast Context executes up to 8 searches simultaneously,
+making it 5-10x faster for complex queries.
+"""
+
+import time
+import os
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.search_tools import grep_search, glob_search
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def sequential_search(queries: list) -> dict:
+    """Traditional sequential search - one query at a time."""
+    results = {}
+    for query in queries:
+        results[query] = grep_search(
+            search_path=WORKSPACE,
+            pattern=query,
+            max_results=20
+        )
+    return results
+
+
+def parallel_search_with_fast_context(queries: list) -> dict:
+    """Fast Context parallel search - multiple queries at once."""
+    fc = FastContext(workspace_path=WORKSPACE)
+    results = {}
+    for query in queries:
+        result = fc.search(query)
+        results[query] = result
+    return results
+
+
+def main():
+    print("=" * 70)
+    print("Parallel vs Sequential Search Comparison")
+    print("=" * 70)
+    
+    # Define multiple search queries
+    queries = [
+        "def __init__",
+        "class Agent",
+        "async def",
+        "import logging",
+        "from typing",
+    ]
+    
+    print(f"\nSearching for {len(queries)} patterns in the codebase...")
+    print(f"Workspace: {WORKSPACE}")
+    
+    # Sequential search
+    print("\n1. Sequential Search (Traditional)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    seq_results = sequential_search(queries)
+    seq_time = (time.perf_counter() - start) * 1000
+    
+    total_seq_matches = sum(len(r) for r in seq_results.values())
+    print(f"   Total matches: {total_seq_matches}")
+    print(f"   Time: {seq_time:.0f}ms")
+    
+    # Fast Context search (with caching disabled for fair comparison)
+    print("\n2. Fast Context Search (Parallel)")
+    print("-" * 40)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    
+    start = time.perf_counter()
+    fc_results = {}
+    for query in queries:
+        fc_results[query] = fc.search(query)
+    fc_time = (time.perf_counter() - start) * 1000
+    
+    total_fc_matches = sum(r.total_files for r in fc_results.values())
+    print(f"   Total files found: {total_fc_matches}")
+    print(f"   Time: {fc_time:.0f}ms")
+    
+    # Comparison
+    print("\n3. Comparison")
+    print("-" * 40)
+    
+    speedup = seq_time / fc_time if fc_time > 0 else float('inf')
+    print(f"   Sequential: {seq_time:.0f}ms")
+    print(f"   Fast Context: {fc_time:.0f}ms")
+    print(f"   Speedup: {speedup:.1f}x faster")
+    
+    # Detailed results
+    print("\n4. Results by Query")
+    print("-" * 40)
+    
+    for query in queries:
+        seq_count = len(seq_results[query])
+        fc_count = fc_results[query].total_files
+        fc_ms = fc_results[query].search_time_ms
+        print(f"   '{query}':")
+        print(f"      Sequential: {seq_count} matches")
+        print(f"      Fast Context: {fc_count} files in {fc_ms}ms")
+    
+    print("\n" + "=" * 70)
+    print(f"Fast Context is {speedup:.1f}x faster due to parallel execution!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/03_caching_performance.py

@@ -0,0 +1,132 @@
+"""
+Example 3: Caching Performance Demonstration
+
+This example shows how Fast Context's caching dramatically improves
+performance for repeated queries.
+
+Key benefits:
+- First query: Full search execution
+- Subsequent queries: Instant cache hit (0ms search time)
+- Configurable TTL (time-to-live)
+"""
+
+import time
+from praisonaiagents.context.fast import FastContext
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Fast Context Caching Performance")
+    print("=" * 70)
+    
+    # Create FastContext with caching enabled
+    fc = FastContext(
+        workspace_path=WORKSPACE,
+        cache_enabled=True,
+        cache_ttl=300  # 5 minutes
+    )
+    
+    query = "def execute"
+    
+    print(f"\nQuery: '{query}'")
+    print(f"Cache TTL: 300 seconds")
+    
+    # First search - cache miss
+    print("\n1. First Search (Cache Miss)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result1 = fc.search(query)
+    elapsed1 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result1.total_files}")
+    print(f"   From cache: {result1.from_cache}")
+    print(f"   Search time: {result1.search_time_ms}ms")
+    print(f"   Total time: {elapsed1:.1f}ms")
+    
+    # Second search - cache hit
+    print("\n2. Second Search (Cache Hit)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result2 = fc.search(query)
+    elapsed2 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result2.total_files}")
+    print(f"   From cache: {result2.from_cache}")
+    print(f"   Search time: {result2.search_time_ms}ms")
+    print(f"   Total time: {elapsed2:.1f}ms")
+    
+    # Third search - still cached
+    print("\n3. Third Search (Still Cached)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result3 = fc.search(query)
+    elapsed3 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result3.total_files}")
+    print(f"   From cache: {result3.from_cache}")
+    print(f"   Total time: {elapsed3:.1f}ms")
+    
+    # Clear cache and search again
+    print("\n4. After Cache Clear")
+    print("-" * 40)
+    
+    fc.clear_cache()
+    print("   Cache cleared!")
+    
+    start = time.perf_counter()
+    result4 = fc.search(query)
+    elapsed4 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result4.total_files}")
+    print(f"   From cache: {result4.from_cache}")
+    print(f"   Search time: {result4.search_time_ms}ms")
+    print(f"   Total time: {elapsed4:.1f}ms")
+    
+    # Performance comparison
+    print("\n5. Performance Summary")
+    print("-" * 40)
+    
+    cache_speedup = elapsed1 / elapsed2 if elapsed2 > 0 else float('inf')
+    
+    print(f"   First search (no cache): {elapsed1:.1f}ms")
+    print(f"   Cached searches: ~{elapsed2:.1f}ms")
+    print(f"   Cache speedup: {cache_speedup:.0f}x faster")
+    
+    # Multiple different queries
+    print("\n6. Multiple Query Caching")
+    print("-" * 40)
+    
+    queries = ["class Agent", "async def", "import os", "def __init__"]
+    
+    # First pass - populate cache
+    print("   First pass (populating cache):")
+    start = time.perf_counter()
+    for q in queries:
+        fc.search(q)
+    first_pass = (time.perf_counter() - start) * 1000
+    print(f"   Time: {first_pass:.0f}ms")
+    
+    # Second pass - all cached
+    print("   Second pass (all cached):")
+    start = time.perf_counter()
+    for q in queries:
+        r = fc.search(q)
+        assert r.from_cache, f"Expected cache hit for '{q}'"
+    second_pass = (time.perf_counter() - start) * 1000
+    print(f"   Time: {second_pass:.1f}ms")
+    
+    multi_speedup = first_pass / second_pass if second_pass > 0 else float('inf')
+    print(f"   Speedup: {multi_speedup:.0f}x faster")
+    
+    print("\n" + "=" * 70)
+    print("Caching provides instant results for repeated queries!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/04_agent_integration.py

@@ -0,0 +1,112 @@
+"""
+Example 4: Agent Integration with Fast Context
+
+This example shows how to use Fast Context integrated with the Agent class
+for automatic code search delegation.
+
+Benefits:
+- Seamless integration with existing Agent workflows
+- Automatic context injection for code-related queries
+- Configurable via Agent parameters or environment variables
+"""
+
+from praisonaiagents import Agent
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Agent Integration with Fast Context")
+    print("=" * 70)
+    
+    # Create an agent with Fast Context enabled
+    print("\n1. Creating Agent with Fast Context")
+    print("-" * 40)
+    
+    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
+    )
+    
+    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}")
+    
+    # Use delegate_to_fast_context for code search
+    print("\n2. Delegating Code Search to Fast Context")
+    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)
+        
+        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")
+        
+        for f in result.files[:3]:
+            print(f"   - {f.path}")
+    
+    # Show configuration options
+    print("\n4. 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("\n   Environment variables:")
+    print("   - FAST_CONTEXT_MODEL")
+    print("   - FAST_CONTEXT_MAX_TURNS")
+    print("   - FAST_CONTEXT_PARALLELISM")
+    print("   - FAST_CONTEXT_TIMEOUT")
+    print("   - FAST_CONTEXT_CACHE")
+    print("   - FAST_CONTEXT_CACHE_TTL")
+    
+    print("\n" + "=" * 70)
+    print("Fast Context integrates seamlessly with Agent for code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/05_file_and_symbol_indexing.py

@@ -0,0 +1,121 @@
+"""
+Example 5: File and Symbol Indexing
+
+This example demonstrates the file and symbol indexing capabilities
+that power Fast Context's rapid search.
+
+Features:
+- FileIndexer: Index file metadata for fast lookups
+- SymbolIndexer: Extract code symbols (functions, classes, imports)
+- Support for Python, JavaScript, TypeScript, Go, Rust, Java
+"""
+
+import time
+from praisonaiagents.context.fast.indexer import (
+    FileIndexer,
+    SymbolIndexer,
+    SymbolType
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("File and Symbol Indexing")
+    print("=" * 70)
+    
+    # File Indexer
+    print("\n1. File Indexer")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    file_indexer = FileIndexer(workspace_path=WORKSPACE)
+    file_count = file_indexer.index()
+    file_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Indexed {file_count} files in {file_time:.0f}ms")
+    
+    stats = file_indexer.get_stats()
+    print(f"   Total size: {stats['total_size_mb']} MB")
+    print(f"   Extensions: {list(stats['extensions'].keys())[:5]}")
+    
+    # Find files by pattern
+    print("\n   Finding files by pattern:")
+    py_files = file_indexer.find_by_pattern("**/*.py")
+    print(f"   - Python files (*.py): {len(py_files)}")
+    
+    agent_files = file_indexer.find_by_pattern("**/agent*.py")
+    print(f"   - Agent files (agent*.py): {len(agent_files)}")
+    
+    # Find files by name
+    print("\n   Finding files by name:")
+    init_files = file_indexer.find_by_name("__init__.py", exact=True)
+    print(f"   - __init__.py files: {len(init_files)}")
+    
+    agent_matches = file_indexer.find_by_name("agent")
+    print(f"   - Files containing 'agent': {len(agent_matches)}")
+    
+    # Symbol Indexer
+    print("\n2. Symbol Indexer")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    symbol_indexer = SymbolIndexer(workspace_path=WORKSPACE)
+    symbol_count = symbol_indexer.index()
+    symbol_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Indexed {symbol_count} symbols in {symbol_time:.0f}ms")
+    
+    stats = symbol_indexer.get_stats()
+    print(f"   Files indexed: {stats['total_files']}")
+    print(f"   Symbols by type:")
+    for sym_type, count in stats['by_type'].items():
+        print(f"      - {sym_type}: {count}")
+    
+    # Find symbols by name
+    print("\n   Finding symbols by name:")
+    
+    agent_symbols = symbol_indexer.find_by_name("Agent", exact=True)
+    print(f"   - 'Agent' (exact): {len(agent_symbols)} symbols")
+    for sym in agent_symbols[:3]:
+        print(f"      {sym.symbol_type.value}: {sym.name} in {sym.file_path}:{sym.line_number}")
+    
+    chat_symbols = symbol_indexer.find_by_name("chat")
+    print(f"   - 'chat' (partial): {len(chat_symbols)} symbols")
+    for sym in chat_symbols[:3]:
+        print(f"      {sym.symbol_type.value}: {sym.name} in {sym.file_path}:{sym.line_number}")
+    
+    # Find symbols by type
+    print("\n   Finding symbols by type:")
+    
+    classes = symbol_indexer.find_by_type(SymbolType.CLASS)
+    print(f"   - Classes: {len(classes)}")
+    for cls in classes[:5]:
+        print(f"      class {cls.name} in {cls.file_path}:{cls.line_number}")
+    
+    functions = symbol_indexer.find_by_type(SymbolType.FUNCTION)
+    print(f"   - Functions: {len(functions)}")
+    
+    methods = symbol_indexer.find_by_type(SymbolType.METHOD)
+    print(f"   - Methods: {len(methods)}")
+    
+    imports = symbol_indexer.find_by_type(SymbolType.IMPORT)
+    print(f"   - Imports: {len(imports)}")
+    
+    # Performance comparison
+    print("\n3. Performance Summary")
+    print("-" * 40)
+    
+    print(f"   File indexing: {file_time:.0f}ms for {file_count} files")
+    print(f"   Symbol indexing: {symbol_time:.0f}ms for {symbol_count} symbols")
+    print(f"   Files per second: {file_count / (file_time / 1000):.0f}")
+    print(f"   Symbols per second: {symbol_count / (symbol_time / 1000):.0f}")
+    
+    print("\n" + "=" * 70)
+    print("Indexing enables instant lookups for files and symbols!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/06_context_injection.py

@@ -0,0 +1,163 @@
+"""
+Example 6: Context Injection for Agents
+
+This example demonstrates how Fast Context results can be formatted
+and injected into agent prompts for better code understanding.
+
+Features:
+- Multiple format styles (markdown, xml, plain)
+- Token budget management
+- Precision over recall (avoid context pollution)
+"""
+
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.context_injector import (
+    ContextInjector,
+    InjectionConfig,
+    inject_fast_context
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Context Injection for Agents")
+    print("=" * 70)
+    
+    # Search for code
+    fc = FastContext(workspace_path=WORKSPACE)
+    result = fc.search("class Agent")
+    
+    print(f"\nSearch results: {result.total_files} files found")
+    
+    # Markdown format (default)
+    print("\n1. Markdown Format")
+    print("-" * 40)
+    
+    config_md = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        max_lines_per_file=20,
+        format_style="markdown",
+        include_line_numbers=True,
+        include_file_content=True,
+        prioritize_precision=True
+    )
+    
+    injector_md = ContextInjector(config_md)
+    md_context = injector_md.format_context(result)
+    
+    print(f"   Format: Markdown")
+    print(f"   Length: {len(md_context)} chars (~{len(md_context)//4} tokens)")
+    print(f"   Preview:")
+    for line in md_context.split('\n')[:10]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # XML format
+    print("\n2. XML Format")
+    print("-" * 40)
+    
+    config_xml = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        format_style="xml",
+        prioritize_precision=True
+    )
+    
+    injector_xml = ContextInjector(config_xml)
+    xml_context = injector_xml.format_context(result)
+    
+    print(f"   Format: XML")
+    print(f"   Length: {len(xml_context)} chars")
+    print(f"   Preview:")
+    for line in xml_context.split('\n')[:10]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # Plain text format
+    print("\n3. Plain Text Format")
+    print("-" * 40)
+    
+    config_plain = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        format_style="plain"
+    )
+    
+    injector_plain = ContextInjector(config_plain)
+    plain_context = injector_plain.format_context(result)
+    
+    print(f"   Format: Plain")
+    print(f"   Length: {len(plain_context)} chars")
+    print(f"   Preview:")
+    for line in plain_context.split('\n')[:8]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # Inject into prompts
+    print("\n4. Injecting into Prompts")
+    print("-" * 40)
+    
+    system_prompt = "You are a helpful code assistant."
+    user_message = "Explain how the Agent class works."
+    
+    injected = inject_fast_context(
+        result=result,
+        system_prompt=system_prompt,
+        user_message=user_message,
+        max_tokens=1500,
+        format_style="markdown"
+    )
+    
+    print(f"   Original system prompt: {len(system_prompt)} chars")
+    print(f"   Injected system prompt: {len(injected['system_prompt'])} chars")
+    print(f"   User message unchanged: {injected['user_message'] == user_message}")
+    
+    # Token budget management
+    print("\n5. Token Budget Management")
+    print("-" * 40)
+    
+    budgets = [500, 1000, 2000, 4000]
+    
+    for budget in budgets:
+        config = InjectionConfig(max_tokens=budget, max_files=10)
+        injector = ContextInjector(config)
+        context = injector.format_context(result)
+        estimated_tokens = len(context) // 4
+        print(f"   Budget: {budget} tokens -> {len(context)} chars (~{estimated_tokens} tokens)")
+    
+    # Precision mode
+    print("\n6. Precision vs Recall")
+    print("-" * 40)
+    
+    # High precision (fewer, more relevant results)
+    config_precision = InjectionConfig(
+        max_tokens=2000,
+        max_files=5,
+        prioritize_precision=True
+    )
+    injector_precision = ContextInjector(config_precision)
+    precision_context = injector_precision.format_context(result)
+    
+    # Lower precision (more results)
+    config_recall = InjectionConfig(
+        max_tokens=2000,
+        max_files=10,
+        prioritize_precision=False
+    )
+    injector_recall = ContextInjector(config_recall)
+    recall_context = injector_recall.format_context(result)
+    
+    print(f"   High precision mode: {len(precision_context)} chars")
+    print(f"   High recall mode: {len(recall_context)} chars")
+    print(f"   Precision mode is more focused for better agent understanding")
+    
+    print("\n" + "=" * 70)
+    print("Context injection formats search results for optimal agent use!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/07_search_tools_demo.py

@@ -0,0 +1,213 @@
+"""
+Example 7: Search Tools Deep Dive
+
+This example demonstrates the individual search tools that power Fast Context:
+- grep_search: Pattern-based search with regex support
+- glob_search: File pattern matching
+- read_file: Read file contents with line ranges
+- list_directory: Directory listing with filtering
+"""
+
+import time
+from praisonaiagents.context.fast.search_tools import (
+    grep_search,
+    glob_search,
+    read_file,
+    list_directory
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Search Tools Deep Dive")
+    print("=" * 70)
+    
+    # grep_search
+    print("\n1. grep_search - Pattern Search")
+    print("-" * 40)
+    
+    # Simple pattern
+    start = time.perf_counter()
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern="def __init__",
+        max_results=10
+    )
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Pattern: 'def __init__'")
+    print(f"   Matches: {len(results)}")
+    print(f"   Time: {elapsed:.0f}ms")
+    if results:
+        print(f"   First match: {results[0]['path']}:{results[0]['line_number']}")
+    
+    # Regex pattern
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern=r"class \w+Agent",
+        is_regex=True,
+        max_results=10
+    )
+    print(f"\n   Regex: 'class \\w+Agent'")
+    print(f"   Matches: {len(results)}")
+    for r in results[:3]:
+        print(f"   - {r['path']}:{r['line_number']}: {r['content'][:50]}...")
+    
+    # Case sensitive
+    results_sensitive = grep_search(
+        search_path=WORKSPACE,
+        pattern="Agent",
+        case_sensitive=True,
+        max_results=50
+    )
+    results_insensitive = grep_search(
+        search_path=WORKSPACE,
+        pattern="agent",
+        case_sensitive=False,
+        max_results=50
+    )
+    print(f"\n   Case sensitive 'Agent': {len(results_sensitive)} matches")
+    print(f"   Case insensitive 'agent': {len(results_insensitive)} matches")
+    
+    # With context lines
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern="class Agent:",
+        context_lines=2,
+        max_results=3
+    )
+    print(f"\n   With 2 context lines:")
+    if results:
+        print(f"   {results[0]['path']}:")
+        if results[0].get('context'):
+            for line in results[0]['context'].split('\n')[:5]:
+                print(f"      {line[:60]}")
+    
+    # glob_search
+    print("\n2. glob_search - File Pattern Matching")
+    print("-" * 40)
+    
+    # Find Python files
+    start = time.perf_counter()
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/*.py",
+        max_results=100
+    )
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Pattern: '**/*.py'")
+    print(f"   Files found: {len(results)}")
+    print(f"   Time: {elapsed:.0f}ms")
+    
+    # Find specific files
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/agent*.py",
+        max_results=20
+    )
+    print(f"\n   Pattern: '**/agent*.py'")
+    print(f"   Files found: {len(results)}")
+    for r in results[:5]:
+        print(f"   - {r['path']} ({r['size']} bytes)")
+    
+    # Find test files
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/test_*.py",
+        max_results=50
+    )
+    print(f"\n   Pattern: '**/test_*.py'")
+    print(f"   Test files: {len(results)}")
+    
+    # read_file
+    print("\n3. read_file - Read File Contents")
+    print("-" * 40)
+    
+    # Read entire file
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/__init__.py",
+        max_lines=20
+    )
+    
+    print(f"   File: praisonaiagents/__init__.py")
+    print(f"   Success: {result['success']}")
+    print(f"   Lines: {result.get('total_lines', 'N/A')}")
+    if result['success']:
+        lines = result['content'].split('\n')[:5]
+        print(f"   Preview:")
+        for line in lines:
+            print(f"      {line[:60]}")
+    
+    # Read specific line range
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/agent/agent.py",
+        start_line=1,
+        end_line=20
+    )
+    
+    print(f"\n   File: agent/agent.py (lines 1-20)")
+    print(f"   Success: {result['success']}")
+    if result['success']:
+        lines = result['content'].split('\n')[:5]
+        print(f"   Preview:")
+        for line in lines:
+            print(f"      {line[:60]}")
+    
+    # Read with context
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/agent/agent.py",
+        start_line=100,
+        end_line=105,
+        context_lines=3
+    )
+    
+    print(f"\n   File: agent/agent.py (lines 100-105 with 3 context lines)")
+    print(f"   Success: {result['success']}")
+    
+    # list_directory
+    print("\n4. list_directory - Directory Listing")
+    print("-" * 40)
+    
+    # List root
+    result = list_directory(
+        dir_path=WORKSPACE,
+        recursive=False,
+        max_entries=20
+    )
+    
+    print(f"   Directory: {WORKSPACE}")
+    print(f"   Success: {result['success']}")
+    print(f"   Entries: {len(result.get('entries', []))}")
+    
+    dirs = [e for e in result.get('entries', []) if e.get('is_dir')]
+    files = [e for e in result.get('entries', []) if not e.get('is_dir')]
+    print(f"   Directories: {len(dirs)}")
+    print(f"   Files: {len(files)}")
+    
+    # List recursive with depth limit
+    result = list_directory(
+        dir_path=f"{WORKSPACE}/praisonaiagents",
+        recursive=True,
+        max_depth=2,
+        max_entries=50
+    )
+    
+    print(f"\n   Directory: praisonaiagents (recursive, depth=2)")
+    print(f"   Entries: {len(result.get('entries', []))}")
+    
+    # Show directory structure
+    print(f"   Structure:")
+    for entry in result.get('entries', [])[:10]:
+        prefix = "📁" if entry.get('is_dir') else "📄"
+        print(f"      {prefix} {entry['name']}")
+    
+    print("\n" + "=" * 70)
+    print("These search tools power Fast Context's rapid code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/08_comprehensive_benchmark.py

@@ -0,0 +1,227 @@
+"""
+Example 8: Comprehensive Benchmark
+
+This example provides a comprehensive benchmark comparing Fast Context
+performance against traditional search approaches.
+
+Metrics measured:
+- Search latency
+- Throughput (queries per second)
+- Cache effectiveness
+- Parallel execution speedup
+"""
+
+import time
+import statistics
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.search_tools import grep_search
+from praisonaiagents.context.fast.indexer import FileIndexer, SymbolIndexer
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def benchmark_search_latency():
+    """Benchmark search latency."""
+    print("\n1. Search Latency Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    
+    queries = [
+        "def __init__",
+        "class Agent",
+        "import logging",
+        "async def",
+        "from typing import",
+    ]
+    
+    # Warm up
+    fc.search("warmup")
+    
+    # Benchmark each query
+    latencies = []
+    for query in queries:
+        times = []
+        for _ in range(3):  # 3 runs per query
+            start = time.perf_counter()
+            fc.search(query)
+            elapsed = (time.perf_counter() - start) * 1000
+            times.append(elapsed)
+        
+        avg = statistics.mean(times)
+        latencies.append(avg)
+        print(f"   '{query}': {avg:.1f}ms (min: {min(times):.1f}, max: {max(times):.1f})")
+    
+    print(f"\n   Average latency: {statistics.mean(latencies):.1f}ms")
+    print(f"   Median latency: {statistics.median(latencies):.1f}ms")
+    print(f"   P95 latency: {sorted(latencies)[int(len(latencies)*0.95)]:.1f}ms")
+
+
+def benchmark_throughput():
+    """Benchmark queries per second."""
+    print("\n2. Throughput Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=True)
+    
+    queries = ["def", "class", "import", "return", "if", "for", "while", "try"]
+    
+    # Cold run (no cache)
+    fc.clear_cache()
+    start = time.perf_counter()
+    for query in queries:
+        fc.search(query)
+    cold_time = time.perf_counter() - start
+    cold_qps = len(queries) / cold_time
+    
+    print(f"   Cold (no cache):")
+    print(f"      Queries: {len(queries)}")
+    print(f"      Time: {cold_time*1000:.0f}ms")
+    print(f"      Throughput: {cold_qps:.1f} queries/second")
+    
+    # Warm run (cached)
+    start = time.perf_counter()
+    for _ in range(10):  # 10 iterations
+        for query in queries:
+            fc.search(query)
+    warm_time = time.perf_counter() - start
+    warm_qps = (len(queries) * 10) / warm_time
+    
+    print(f"\n   Warm (cached):")
+    print(f"      Queries: {len(queries) * 10}")
+    print(f"      Time: {warm_time*1000:.0f}ms")
+    print(f"      Throughput: {warm_qps:.0f} queries/second")
+    
+    print(f"\n   Cache speedup: {warm_qps/cold_qps:.0f}x")
+
+
+def benchmark_cache_effectiveness():
+    """Benchmark cache hit rate and speedup."""
+    print("\n3. Cache Effectiveness Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=True)
+    fc.clear_cache()
+    
+    queries = ["Agent", "chat", "memory", "tool", "execute"]
+    
+    # First pass - cache misses
+    miss_times = []
+    for query in queries:
+        start = time.perf_counter()
+        result = fc.search(query)
+        elapsed = (time.perf_counter() - start) * 1000
+        miss_times.append(elapsed)
+        assert not result.from_cache
+    
+    # Second pass - cache hits
+    hit_times = []
+    for query in queries:
+        start = time.perf_counter()
+        result = fc.search(query)
+        elapsed = (time.perf_counter() - start) * 1000
+        hit_times.append(elapsed)
+        assert result.from_cache
+    
+    avg_miss = statistics.mean(miss_times)
+    avg_hit = statistics.mean(hit_times)
+    
+    print(f"   Cache miss (first query): {avg_miss:.1f}ms avg")
+    print(f"   Cache hit (repeat query): {avg_hit:.2f}ms avg")
+    print(f"   Cache speedup: {avg_miss/avg_hit:.0f}x faster")
+    print(f"   Time saved per cached query: {avg_miss - avg_hit:.1f}ms")
+
+
+def benchmark_parallel_execution():
+    """Benchmark parallel vs sequential execution."""
+    print("\n4. Parallel Execution Benchmark")
+    print("-" * 50)
+    
+    queries = ["def", "class", "import", "return", "async"]
+    
+    # Sequential (one at a time)
+    start = time.perf_counter()
+    for query in queries:
+        grep_search(WORKSPACE, query, max_results=20)
+    seq_time = (time.perf_counter() - start) * 1000
+    
+    # Parallel (Fast Context)
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    start = time.perf_counter()
+    for query in queries:
+        fc.search(query)
+    par_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Sequential: {seq_time:.0f}ms")
+    print(f"   Parallel (Fast Context): {par_time:.0f}ms")
+    print(f"   Speedup: {seq_time/par_time:.1f}x")
+
+
+def benchmark_indexing():
+    """Benchmark indexing performance."""
+    print("\n5. Indexing Performance Benchmark")
+    print("-" * 50)
+    
+    # File indexing
+    start = time.perf_counter()
+    file_indexer = FileIndexer(workspace_path=WORKSPACE)
+    file_count = file_indexer.index()
+    file_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   File Indexer:")
+    print(f"      Files: {file_count}")
+    print(f"      Time: {file_time:.0f}ms")
+    print(f"      Rate: {file_count/(file_time/1000):.0f} files/second")
+    
+    # Symbol indexing
+    start = time.perf_counter()
+    symbol_indexer = SymbolIndexer(workspace_path=WORKSPACE)
+    symbol_count = symbol_indexer.index()
+    symbol_time = (time.perf_counter() - start) * 1000
+    
+    print(f"\n   Symbol Indexer:")
+    print(f"      Symbols: {symbol_count}")
+    print(f"      Time: {symbol_time:.0f}ms")
+    print(f"      Rate: {symbol_count/(symbol_time/1000):.0f} symbols/second")
+    
+    # Lookup performance
+    start = time.perf_counter()
+    for _ in range(100):
+        file_indexer.find_by_pattern("**/*.py")
+    lookup_time = (time.perf_counter() - start) * 1000
+    
+    print(f"\n   Lookup Performance:")
+    print(f"      100 pattern lookups: {lookup_time:.1f}ms")
+    print(f"      Per lookup: {lookup_time/100:.2f}ms")
+
+
+def main():
+    print("=" * 70)
+    print("Fast Context Comprehensive Benchmark")
+    print("=" * 70)
+    print(f"\nWorkspace: {WORKSPACE}")
+    
+    benchmark_search_latency()
+    benchmark_throughput()
+    benchmark_cache_effectiveness()
+    benchmark_parallel_execution()
+    benchmark_indexing()
+    
+    print("\n" + "=" * 70)
+    print("Summary")
+    print("=" * 70)
+    print("""
+   Fast Context provides:
+   ✓ Sub-100ms search latency for most queries
+   ✓ 100+ queries/second with caching
+   ✓ 100x+ speedup for cached queries
+   ✓ 2-5x speedup from parallel execution
+   ✓ 1000+ files/second indexing rate
+   
+   These benchmarks demonstrate why Fast Context is ideal for
+   rapid code search in AI agent workflows.
+""")
+
+
+if __name__ == "__main__":
+    main()

examples/cookbooks/Finance_Market_Job_Agents/Ai_Job_Hunting_Assistant.ipynb

@@ -29,7 +29,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {
     "colab": {
      "base_uri": "https://localhost:8080/"
@@ -71,7 +71,6 @@
     "import pandas as pd\n",
     "\n",
     "print(\"📦 Dependencies installed!\")\n",
-    "print(\"🔄 Converting from AGNO → PraisonAI\")\n",
     "print(\"🎯 Building Job Hunting Agent System\")"
    ]
   },

examples/cookbooks/Finance_Market_Job_Agents/Home_Buying_Real_Estate_Agent.ipynb

@@ -156,7 +156,7 @@
     "  - Property comparison\n",
     "  - Cost of living and taxes\n",
     "  - First-time homebuyer guidance\n",
-    "llm: gpt-4o\n",
+    "llm: gpt-5-nano\n",
     "verbosity: true\n",
     "format: markdown\n",
     "\"\"\"\n"
@@ -188,7 +188,7 @@
     "Help users evaluate neighborhoods, estimate mortgage payments, compare homes, and understand homeownership costs.\n",
     "Explain clearly, format in markdown, and be friendly but professional.\n",
     "\"\"\",\n",
-    "    llm=\"gpt-4o\",\n",
+    "    llm=\"gpt-5-nano\",\n",
     "    verbose=True,\n",
     "    markdown=True\n",
     ")\n"

examples/cookbooks/Health_Fitness_Agents/Air_Quality_Analysis_Agent.ipynb

@@ -311,7 +311,7 @@
      "data": {
       "text/html": [
        "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭───────────────────────────────────────────────────── Task ──────────────────────────────────────────────────────╮</span>\n",
-       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> You are an expert health advisor using the GPT-4o Mini model.                                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> You are an expert health advisor using the gpt-5-nano Mini model.                                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
        "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
        "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"background-color: #272822\">                                                                                                               </span> <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
        "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"background-color: #272822\"> </span><span style=\"color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #272822\">Based on the following air quality conditions in Mumbai, Maharashtra, India:</span><span style=\"background-color: #272822\">                                  </span> <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
@@ -340,7 +340,7 @@
       ],
       "text/plain": [
        "\u001b[36m╭─\u001b[0m\u001b[36m────────────────────────────────────────────────────\u001b[0m\u001b[36m Task \u001b[0m\u001b[36m─────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
-       "\u001b[36m│\u001b[0m You are an expert health advisor using the GPT-4o Mini model.                                                   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m You are an expert health advisor using the gpt-5-nano Mini model.                                                   \u001b[36m│\u001b[0m\n",
        "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
        "\u001b[36m│\u001b[0m \u001b[48;2;39;40;34m                                                                                                               \u001b[0m \u001b[36m│\u001b[0m\n",
        "\u001b[36m│\u001b[0m \u001b[48;2;39;40;34m \u001b[0m\u001b[38;2;248;248;242;48;2;39;40;34mBased on the following air quality conditions in Mumbai, Maharashtra, India:\u001b[0m\u001b[48;2;39;40;34m                                 \u001b[0m\u001b[48;2;39;40;34m \u001b[0m \u001b[36m│\u001b[0m\n",
@@ -519,7 +519,7 @@
     "    aqi_data = aqi_data.data  # Convert to dict\n",
     "\n",
     "    prompt = f\"\"\"\n",
-    "    You are an expert health advisor using the GPT-4o Mini model.\n",
+    "    You are an expert health advisor using the gpt-5-nano Mini model.\n",
     "\n",
     "    Based on the following air quality conditions in {user_city}, {user_state}, {user_country}:\n",
     "    - Overall AQI: {aqi_data.get('aqi', 'N/A')}\n",

examples/cookbooks/Research_Knowledge_QA_Agents/Crypto_Research_Agent_Intelligence_Agent.ipynb

@@ -152,7 +152,7 @@
     "  - Evaluate risk factors\n",
     "  - Identify scams or red flags\n",
     "  - Summarize project fundamentals\n",
-    "llm: gpt-4o\n",
+    "llm: gpt-5-nano\n",
     "verbosity: true\n",
     "format: markdown\n",
     "\"\"\"\n"
@@ -184,7 +184,7 @@
     "and market trends. Provide critical insight into legitimacy, potential growth, and associated risks.\n",
     "Use markdown formatting and structure your research clearly.\n",
     "\"\"\",\n",
-    "    llm=\"gpt-4o\",\n",
+    "    llm=\"gpt-5-nano\",\n",
     "    verbose=True,\n",
     "    markdown=True\n",
     ")\n"

examples/cookbooks/SocialMedia_Content_Agents/Ai_Meme_Creator_Agent.ipynb

@@ -627,7 +627,7 @@
     "            )\n",
     "        else:  # OpenAI\n",
     "            llm = ChatOpenAI(\n",
-    "                model=\"gpt-4o\",\n",
+    "                model=\"gpt-5-nano\",\n",
     "                api_key=api_key,\n",
     "                temperature=0.0\n",
     "            )\n",

examples/cookbooks/SocialMedia_Content_Agents/YouTube_Influencer_Intelligence_Agent.ipynb

@@ -153,7 +153,7 @@
     "  - Spot content patterns and trends\n",
     "  - Recommend growth strategies\n",
     "  - Detect potential monetization methods\n",
-    "llm: gpt-4o\n",
+    "llm: gpt-5-nano\n",
     "verbosity: true\n",
     "format: markdown\n",
     "\"\"\"\n"
@@ -184,7 +184,7 @@
     "You are a YouTube intelligence analyst. Your job is to research a specific channel, niche, or influencer topic.\n",
     "Provide growth recommendations, engagement analysis, trending strategies, and monetization tips. Format in markdown.\n",
     "\"\"\",\n",
-    "    llm=\"gpt-4o\",\n",
+    "    llm=\"gpt-5-nano\",\n",
     "    verbose=True,\n",
     "    markdown=True\n",
     ")\n"

examples/cookbooks/Travel_Planning_Agents/Intelligent_Travel_Planning_Agent.ipynb

@@ -136,7 +136,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "{'name': 'Travel Research Agent', 'description': 'A world-class travel researcher that searches for destinations, activities, and accommodations', 'instructions': ['Given a travel destination and number of days, generate 3 relevant search terms', 'Search the web for each term using web_search tool', 'Analyze results and return 10 most relevant findings', 'Focus on activities, accommodations, attractions, and local insights', 'Ensure high-quality, accurate information', 'Use travel_budget_calculator to estimate costs'], 'tools': ['web_search', 'travel_budget_calculator'], 'model': 'gpt-4o', 'temperature': 0.7}\n"
+      "{'name': 'Travel Research Agent', 'description': 'A world-class travel researcher that searches for destinations, activities, and accommodations', 'instructions': ['Given a travel destination and number of days, generate 3 relevant search terms', 'Search the web for each term using web_search tool', 'Analyze results and return 10 most relevant findings', 'Focus on activities, accommodations, attractions, and local insights', 'Ensure high-quality, accurate information', 'Use travel_budget_calculator to estimate costs'], 'tools': ['web_search', 'travel_budget_calculator'], 'model': 'gpt-5-nano', 'temperature': 0.7}\n"
      ]
     }
    ],
@@ -156,7 +156,7 @@
     "tools:\n",
     "  - web_search\n",
     "  - travel_budget_calculator\n",
-    "model: gpt-4o\n",
+    "model: gpt-5-nano\n",
     "temperature: 0.7\n",
     "\"\"\"\n",
     "\n",

examples/cookbooks/Travel_Planning_Agents/VoiGno_Restaurant_Agent_PraisonAI.ipynb

@@ -17,7 +17,7 @@
     "id": "Y9FkDzt1lF47"
    },
    "source": [
-    "This notebook implements a conversational restaurant booking assistant using the Praison AI Agent framework. It handles natural interruptions such as modifying guest count or changing time mid-conversation. Built for Google Colab Free Tier, it uses OpenAI's GPT-4o model and follows a YAML-based agent design for clarity and modularity."
+    "This notebook implements a conversational restaurant booking assistant using the Praison AI Agent framework. It handles natural interruptions such as modifying guest count or changing time mid-conversation. Built for Google Colab Free Tier, it uses OpenAI's gpt-5-nano model and follows a YAML-based agent design for clarity and modularity."
    ]
   },
   {
@@ -135,7 +135,7 @@
     "  - Context management\n",
     "  - Handling mid-conversation changes\n",
     "  - Summarizing confirmed reservations\n",
-    "llm: gpt-4o\n",
+    "llm: gpt-5-nano\n",
     "verbosity: true\n",
     "format: markdown\n",
     "\"\"\"\n"
@@ -167,7 +167,7 @@
     "manage corrections like “change to 3 guests” or “move to 8 PM,”\n",
     "confirm the details once the user is satisfied. Respond in markdown.\n",
     "\"\"\",\n",
-    "    llm=\"gpt-4o\",\n",
+    "    llm=\"gpt-5-nano\",\n",
     "    verbose=True,\n",
     "    markdown=True\n",
     ")\n"

examples/cookbooks/rag_examples/agentic_rag/PraisonAI_RecipeAgent.ipynb

@@ -0,0 +1,481 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "LJRJRQtFTagH"
+   },
+   "source": [
+    "# AI RAG Agent with Web Access using PraisonAI"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "Ph4RVTBCTcmB"
+   },
+   "source": [
+    "This notebook demonstrates how to build a Retrieval-Augmented Generation (RAG) agent with web access using GPT-4o and PraisonAI. The agent specializes in Thai recipes and can search the web for additional information."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "tMxfwPPATy_o"
+   },
+   "source": [
+    "This RAG agent:\n",
+    "*   Creates an AI assistant specialized in Thai recipes and cooking\n",
+    "*   Has access to a PDF knowledge base about Thai recipes\n",
+    "*   Can search the web using DuckDuckGo for additional information\n",
+    "*   Provides comprehensive answers about Thai cuisine\n",
+    "*   Uses PraisonAI framework for agent management"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "h68oMaCITmqt"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Dhivya-Bharathy/PraisonAI/blob/main/examples/cookbooks/rag_examples/agentic_rag/PraisonAI_RecipeAgent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "cAdzoWXJUMfF"
+   },
+   "source": [
+    "# Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "9D-2TlOrUNcu"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install praisonaiagents openai requests"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "yY-4-kEIUW40"
+   },
+   "source": [
+    "# Set Up API Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "f5bhQ05yUX6J",
+    "outputId": "dcf9d0d9-332e-4136-9289-4c39d898005c"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Enter your OpenAI API key: ··········\n",
+      "✅ API key set successfully!\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "\n",
+    "# Set your OpenAI API key here\n",
+    "os.environ['OPENAI_API_KEY'] = 'Enter your api key here'\n",
+    "\n",
+    "# Or use this method to input it securely\n",
+    "from getpass import getpass\n",
+    "api_key = getpass('Enter your OpenAI API key: ')\n",
+    "os.environ['OPENAI_API_KEY'] = api_key\n",
+    "\n",
+    "print(\"✅ API key set successfully!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "Eh0j-SegUi13"
+   },
+   "source": [
+    "# Tools"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "Z1A9oifIUkQN",
+    "outputId": "9be78226-36fa-43c4-865d-2f7e6e2ba9de"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "✅ Tools imported successfully!\n"
+     ]
+    }
+   ],
+   "source": [
+    "from praisonaiagents import Agent\n",
+    "import requests\n",
+    "import tempfile\n",
+    "from pathlib import Path\n",
+    "\n",
+    "print(\"✅ Tools imported successfully!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "efnnREHXUnYA"
+   },
+   "source": [
+    "# YAML Prompt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "kcM14-yQUqG-",
+    "outputId": "c5b6288d-a789-4a93-e20c-1d285370b667"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "✅ Agent instructions configured!\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Agent configuration and instructions\n",
+    "AGENT_INSTRUCTIONS = \"\"\"\n",
+    "You are a helpful AI assistant specialized in Thai recipes and cooking.\n",
+    "\n",
+    "You have access to a PDF knowledge base about Thai recipes from: https://phi-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf\n",
+    "\n",
+    "You can also search the web for additional information about Thai cooking, ingredients, and techniques.\n",
+    "\n",
+    "When answering questions:\n",
+    "1. Use your knowledge about Thai cuisine to provide helpful information\n",
+    "2. If needed, search the web for additional details, current information, or clarification\n",
+    "3. Provide comprehensive, helpful answers about Thai cuisine\n",
+    "4. Always be informative and helpful about Thai cooking!\n",
+    "\n",
+    "You can use the internet_search function to search the web when needed.\n",
+    "\n",
+    "Focus on providing practical cooking advice, ingredient information, and authentic Thai recipe guidance.\n",
+    "\"\"\"\n",
+    "\n",
+    "print(\"✅ Agent instructions configured!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "MCBRcXFJUulY"
+   },
+   "source": [
+    "# Main"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "YaRLbgMmUvXv",
+    "outputId": "8ed8d9f8-85a7-48de-ccc6-f617cd672a85"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🤖 Thai Recipe RAG Agent created successfully!\n",
+      "The agent is ready to answer questions about Thai cooking.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Create the RAG agent\n",
+    "rag_agent = Agent(\n",
+    "    instructions=AGENT_INSTRUCTIONS,\n",
+    "    llm=\"gpt-4o\",\n",
+    "    markdown=True,\n",
+    "    verbose=True\n",
+    ")\n",
+    "\n",
+    "print(\"🤖 Thai Recipe RAG Agent created successfully!\")\n",
+    "print(\"The agent is ready to answer questions about Thai cooking.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "QvZM94pGU0IX"
+   },
+   "source": [
+    "# Test the Agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 1000,
+     "referenced_widgets": [
+      "47739975c9f04ee5b4e69e8f445cbeda",
+      "08888d583cba4c01b3fdf8f30b06ca4f"
+     ]
+    },
+    "id": "QPdrleKxU1VN",
+    "outputId": "a71a86cd-eff8-4309-9b50-173a30066c90"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🤔 Question: What are the essential ingredients for Thai cooking?\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╭─ </span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8; font-weight: bold\">Agent Info</span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\"> ────────────────────────────────────────────────────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #ff9b9b; text-decoration-color: #ff9b9b; font-weight: bold\">👤 Agent:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Agent</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #b4b4b3; text-decoration-color: #b4b4b3; font-weight: bold\">Role:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Assistant</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[38;2;210;227;200m╭─\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[1;38;2;210;227;200mAgent Info\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[38;2;210;227;200m───────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[38;2;210;227;200m─╮\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;255;155;155m👤 Agent:\u001b[0m \u001b[38;2;255;229;229mAgent\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;180;180;179mRole:\u001b[0m \u001b[38;2;255;229;229mAssistant\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "47739975c9f04ee5b4e69e8f445cbeda",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"></pre>\n"
+      ],
+      "text/plain": []
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\">\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #7f7f7f; text-decoration-color: #7f7f7f\">Response generated in 8.4s</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[2mResponse generated in 8.4s\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭───────────────────────────────────────────────────── Task ──────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> What are the essential ingredients for Thai cooking?                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m────────────────────────────────────────────────────\u001b[0m\u001b[36m Task \u001b[0m\u001b[36m─────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m What are the essential ingredients for Thai cooking?                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭─────────────────────────────────────────────────── Response ────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour,  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  1 </span><span style=\"font-weight: bold\">Fish Sauce (Nam Pla)</span>: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking,   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>used to add depth of flavor.                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  2 </span><span style=\"font-weight: bold\">Lime Juice</span>: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  3 </span><span style=\"font-weight: bold\">Chilies</span>: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>certain recipes.                                                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  4 </span><span style=\"font-weight: bold\">Lemongrass</span>: A citrusy, fragrant herb that is often used in soups, curries, and teas.                        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  5 </span><span style=\"font-weight: bold\">Galangal</span>: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.         <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  6 </span><span style=\"font-weight: bold\">Kaffir Lime Leaves</span>: They add a distinct, zesty citrus aroma and flavor to Thai dishes.                      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  7 </span><span style=\"font-weight: bold\">Coconut Milk</span>: Adds richness and creaminess, commonly used in curries and desserts.                          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  8 </span><span style=\"font-weight: bold\">Palm Sugar</span>: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  9 </span><span style=\"font-weight: bold\">Tamarind Paste</span>: Provides a sour element to many dishes, particularly pad Thai and some sauces.              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 10 </span><span style=\"font-weight: bold\">Thai Basil</span>: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 11 </span><span style=\"font-weight: bold\">Coriander (Cilantro)</span>: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>sauces and stocks.                                                                                          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 12 </span><span style=\"font-weight: bold\">Shrimp Paste</span>: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>dishes.                                                                                                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> These ingredients are commonly used in combination to create the complex and rich flavors characteristic of     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> of Thai dishes.                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m──────────────────────────────────────────────────\u001b[0m\u001b[36m Response \u001b[0m\u001b[36m───────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour,  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  1 \u001b[0m\u001b[1mFish Sauce (Nam Pla)\u001b[0m: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking,   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mused to add depth of flavor.                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  2 \u001b[0m\u001b[1mLime Juice\u001b[0m: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  3 \u001b[0m\u001b[1mChilies\u001b[0m: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mcertain recipes.                                                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  4 \u001b[0m\u001b[1mLemongrass\u001b[0m: A citrusy, fragrant herb that is often used in soups, curries, and teas.                        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  5 \u001b[0m\u001b[1mGalangal\u001b[0m: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.         \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  6 \u001b[0m\u001b[1mKaffir Lime Leaves\u001b[0m: They add a distinct, zesty citrus aroma and flavor to Thai dishes.                      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  7 \u001b[0m\u001b[1mCoconut Milk\u001b[0m: Adds richness and creaminess, commonly used in curries and desserts.                          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  8 \u001b[0m\u001b[1mPalm Sugar\u001b[0m: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  9 \u001b[0m\u001b[1mTamarind Paste\u001b[0m: Provides a sour element to many dishes, particularly pad Thai and some sauces.              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 10 \u001b[0m\u001b[1mThai Basil\u001b[0m: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 11 \u001b[0m\u001b[1mCoriander (Cilantro)\u001b[0m: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0msauces and stocks.                                                                                          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 12 \u001b[0m\u001b[1mShrimp Paste\u001b[0m: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mdishes.                                                                                                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m These ingredients are commonly used in combination to create the complex and rich flavors characteristic of     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m of Thai dishes.                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "�� Answer: Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour, sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:\n",
+      "\n",
+      "1. **Fish Sauce (Nam Pla)**: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking, used to add depth of flavor.\n",
+      "\n",
+      "2. **Lime Juice**: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.\n",
+      "\n",
+      "3. **Chilies**: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for certain recipes.\n",
+      "\n",
+      "4. **Lemongrass**: A citrusy, fragrant herb that is often used in soups, curries, and teas.\n",
+      "\n",
+      "5. **Galangal**: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.\n",
+      "\n",
+      "6. **Kaffir Lime Leaves**: They add a distinct, zesty citrus aroma and flavor to Thai dishes.\n",
+      "\n",
+      "7. **Coconut Milk**: Adds richness and creaminess, commonly used in curries and desserts.\n",
+      "\n",
+      "8. **Palm Sugar**: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.\n",
+      "\n",
+      "9. **Tamarind Paste**: Provides a sour element to many dishes, particularly pad Thai and some sauces.\n",
+      "\n",
+      "10. **Thai Basil**: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.\n",
+      "\n",
+      "11. **Coriander (Cilantro)**: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to sauces and stocks.\n",
+      "\n",
+      "12. **Shrimp Paste**: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of dishes.\n",
+      "\n",
+      "These ingredients are commonly used in combination to create the complex and rich flavors characteristic of Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity of Thai dishes.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Test question 1: Basic Thai cooking\n",
+    "question1 = \"What are the essential ingredients for Thai cooking?\"\n",
+    "print(f\"🤔 Question: {question1}\")\n",
+    "\n",
+    "try:\n",
+    "    response1 = rag_agent.start(question1)\n",
+    "    print(f\"�� Answer: {response1}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"❌ Error: {e}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

examples/cookbooks/rag_examples/agentic_rag/agentic_rag_gpt5_praisonai_agents.ipynb

@@ -0,0 +1,556 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "EA8l4cSVl3Lx"
+   },
+   "source": [
+    "# Agentic RAG with GPT-5 - Colab Notebook"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "I-8nOxJ2l7nO"
+   },
+   "source": [
+    "This Colab notebook sets up a Streamlit app using PraisonAI Agents framework.\n",
+    "It allows you to interact with an AI agent powered by GPT-5 for Q&A.\n",
+    "Currently, the knowledge base functionality is disabled due to compatibility issues."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "g5I1tMkxmDQe"
+   },
+   "source": [
+    "- GPT-5 Integration (via OpenAI API)\n",
+    "- Streamlit Web App\n",
+    "- Agent Framework: PraisonAI Agents\n",
+    "- Markdown-formatted responses"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "yeEno7U0q2U_"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Dhivya-Bharathy/PraisonAI/blob/main/examples/cookbooks/Qwen2.5_InstructionAgent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "WV2GnzZCmGBR"
+   },
+   "source": [
+    "# Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "20wAadXemJ0k"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install praisonaiagents python-dotenv streamlit"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "l71uCRarndvy"
+   },
+   "source": [
+    "# Set API Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "id": "brfc-ZZKnfre"
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "load_dotenv()\n",
+    "\n",
+    "OPENAI_API_KEY = \"Enter your api key here\"\n",
+    "\n",
+    "os.environ[\"OPENAI_API_KEY\"] = OPENAI_API_KEY\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "d1fGzyQCn1aQ"
+   },
+   "source": [
+    "# Tools and Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "id": "GcNPLkZXntIS"
+   },
+   "outputs": [],
+   "source": [
+    "import streamlit as st\n",
+    "from praisonaiagents import Agent\n",
+    "\n",
+    "# YAML Prompt Configuration\n",
+    "agent_config = {\n",
+    "    \"name\": \"Knowledge Agent\",\n",
+    "    \"instructions\": [\n",
+    "        \"You are a helpful AI assistant. Answer questions based on your general knowledge.\",\n",
+    "        \"Provide clear, well-structured answers in markdown format.\",\n",
+    "        \"Use proper markdown formatting with headers, lists, and emphasis where appropriate.\",\n",
+    "        \"Structure your response with clear sections and bullet points when helpful.\",\n",
+    "    ],\n",
+    "    \"llm\": \"gpt-5-nano\",\n",
+    "    \"markdown\": True,\n",
+    "    \"verbose\": True\n",
+    "}\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "jkmrh0gIn_4a"
+   },
+   "source": [
+    "# Initialize Agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "id": "qaJvf8RyoAsB"
+   },
+   "outputs": [],
+   "source": [
+    "def create_agent():\n",
+    "    \"\"\"Create an agent with reasoning capabilities\"\"\"\n",
+    "    return Agent(\n",
+    "        name=agent_config[\"name\"],\n",
+    "        instructions=agent_config[\"instructions\"],\n",
+    "        llm=agent_config[\"llm\"],\n",
+    "        markdown=agent_config[\"markdown\"],\n",
+    "        verbose=agent_config[\"verbose\"]\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "kvGJh3bbqTmh"
+   },
+   "source": [
+    "# Main Function"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 1000,
+     "referenced_widgets": [
+      "ad296d97510246de8eb0138ce8a8a166",
+      "f6e502b3dca442f0ae6c5739f5a6d159"
+     ]
+    },
+    "id": "_QyxzqKKqUrW",
+    "outputId": "97be7e02-b034-4004-e9e3-56337e3f2887"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "�� Initializing Agentic RAG with GPT-5...\n",
+      "📚 Loading agent...\n",
+      "✅ Agent loaded successfully!\n",
+      "\n",
+      "🎯 Example queries you can try:\n",
+      "1. What is PraisonAI and how do Agents work?\n",
+      "2. What are Teams in PraisonAI and how do they work?\n",
+      "3. Give me a step-by-step guide to building a RAG system.\n",
+      "4. What are AI Agents?\n",
+      "\n",
+      "============================================================\n",
+      "\n",
+      "🤔 Enter your question (or 'quit' to exit):\n",
+      "> What is PraisonAI and how do Agents work?\n",
+      "🔍 Processing your question...\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╭─ </span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8; font-weight: bold\">Agent Info</span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\"> ────────────────────────────────────────────────────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #ff9b9b; text-decoration-color: #ff9b9b; font-weight: bold\">👤 Agent:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Knowledge Agent</span>                                                                                      <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #b4b4b3; text-decoration-color: #b4b4b3; font-weight: bold\">Role:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Assistant</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[38;2;210;227;200m╭─\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[1;38;2;210;227;200mAgent Info\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[38;2;210;227;200m───────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[38;2;210;227;200m─╮\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;255;155;155m👤 Agent:\u001b[0m \u001b[38;2;255;229;229mKnowledge Agent\u001b[0m                                                                                      \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;180;180;179mRole:\u001b[0m \u001b[38;2;255;229;229mAssistant\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "ad296d97510246de8eb0138ce8a8a166",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"></pre>\n"
+      ],
+      "text/plain": []
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\">\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #7f7f7f; text-decoration-color: #7f7f7f\">Response generated in 9.4s</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[2mResponse generated in 9.4s\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭───────────────────────────────────────────────────── Task ──────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> What is PraisonAI and how do Agents work?                                                                       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m────────────────────────────────────────────────────\u001b[0m\u001b[36m Task \u001b[0m\u001b[36m─────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m What is PraisonAI and how do Agents work?                                                                       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭─────────────────────────────────────────────────── Response ────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┃                                             <span style=\"font-weight: bold\">What is PraisonAI?</span>                                              ┃ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> productivity. It typically involves developing AI models that can assist in various tasks, automate processes,  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> and provide insights based on data analysis.                                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                            <span style=\"font-weight: bold; text-decoration: underline\">Key Features of PraisonAI</span>                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Task Automation</span>: Automates repetitive tasks, allowing users to focus on more strategic activities.           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Data Insights</span>: Analyzes large sets of data to provide actionable insights.                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Natural Language Processing</span>: Enables users to interact with the AI through natural language, making it       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>user-friendly.                                                                                               <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Customizable Solutions</span>: Tailors AI applications to meet specific user needs across various industries.       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┃                                      <span style=\"font-weight: bold\">How Do Agents Work in PraisonAI?</span>                                       ┃ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> functions. Here’s how they typically operate:                                                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                               <span style=\"font-weight: bold; text-decoration: underline\">1. Types of Agents</span>                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Reactive Agents</span>: Respond to the current environment without internal memory. They act solely based on        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>current inputs.                                                                                              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Deliberative Agents</span>: Have a model of their environment, plan their actions, and retain memories of past      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>interactions.                                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Learning Agents</span>: Improve their performance over time through experience, adapting to new information.        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                           <span style=\"font-weight: bold; text-decoration: underline\">2. Functionality of Agents</span>                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Task Execution</span>: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>customer support.                                                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Interaction</span>: They often interact with users through chat interfaces or APIs, providing a seamless user       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>experience.                                                                                                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Integration</span>: Can be integrated with other systems or software to enhance functionality, such as CRM systems, <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>databases, or other AI tools.                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Continuous Learning</span>: Agents may utilize machine learning algorithms to adapt and evolve based on user        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>interactions and data received.                                                                              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                           <span style=\"font-weight: bold; text-decoration: underline\">3. Benefits of Using Agents</span>                                           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Increased Efficiency</span>: Automate routine tasks to reduce workload.                                             <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">24/7 Availability</span>: Provide consistent support and functionality without downtime.                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Scalability</span>: Easily scale operations by deploying more agents as needed.                                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Data-Driven Decisions</span>: Use data insights to inform strategy and operations.                                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                   <span style=\"font-weight: bold; text-decoration: underline\">Conclusion</span>                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> they are simple reactive agents or complex learning entities, their design focuses on making operations         <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> smoother and more effective.                                                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m──────────────────────────────────────────────────\u001b[0m\u001b[36m Response \u001b[0m\u001b[36m───────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┃                                             \u001b[1mWhat is PraisonAI?\u001b[0m                                              ┃ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m productivity. It typically involves developing AI models that can assist in various tasks, automate processes,  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m and provide insights based on data analysis.                                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                            \u001b[1;4mKey Features of PraisonAI\u001b[0m                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mTask Automation\u001b[0m: Automates repetitive tasks, allowing users to focus on more strategic activities.           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mData Insights\u001b[0m: Analyzes large sets of data to provide actionable insights.                                   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mNatural Language Processing\u001b[0m: Enables users to interact with the AI through natural language, making it       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0muser-friendly.                                                                                               \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mCustomizable Solutions\u001b[0m: Tailors AI applications to meet specific user needs across various industries.       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┃                                      \u001b[1mHow Do Agents Work in PraisonAI?\u001b[0m                                       ┃ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m functions. Here’s how they typically operate:                                                                   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                               \u001b[1;4m1. \u001b[0m\u001b[1;4mTypes of Agents\u001b[0m                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mReactive Agents\u001b[0m: Respond to the current environment without internal memory. They act solely based on        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mcurrent inputs.                                                                                              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mDeliberative Agents\u001b[0m: Have a model of their environment, plan their actions, and retain memories of past      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0minteractions.                                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mLearning Agents\u001b[0m: Improve their performance over time through experience, adapting to new information.        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                           \u001b[1;4m2. \u001b[0m\u001b[1;4mFunctionality of Agents\u001b[0m                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mTask Execution\u001b[0m: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mcustomer support.                                                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mInteraction\u001b[0m: They often interact with users through chat interfaces or APIs, providing a seamless user       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mexperience.                                                                                                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mIntegration\u001b[0m: Can be integrated with other systems or software to enhance functionality, such as CRM systems, \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mdatabases, or other AI tools.                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mContinuous Learning\u001b[0m: Agents may utilize machine learning algorithms to adapt and evolve based on user        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0minteractions and data received.                                                                              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                           \u001b[1;4m3. \u001b[0m\u001b[1;4mBenefits of Using Agents\u001b[0m                                           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mIncreased Efficiency\u001b[0m: Automate routine tasks to reduce workload.                                             \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1m24/7 Availability\u001b[0m: Provide consistent support and functionality without downtime.                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mScalability\u001b[0m: Easily scale operations by deploying more agents as needed.                                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mData-Driven Decisions\u001b[0m: Use data insights to inform strategy and operations.                                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                   \u001b[1;4mConclusion\u001b[0m                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m they are simple reactive agents or complex learning entities, their design focuses on making operations         \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m smoother and more effective.                                                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "💡 Answer:\n",
+      "========================================\n",
+      "# What is PraisonAI?\n",
+      "\n",
+      "PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business productivity. It typically involves developing AI models that can assist in various tasks, automate processes, and provide insights based on data analysis.\n",
+      "\n",
+      "## Key Features of PraisonAI\n",
+      "\n",
+      "- **Task Automation**: Automates repetitive tasks, allowing users to focus on more strategic activities.\n",
+      "- **Data Insights**: Analyzes large sets of data to provide actionable insights.\n",
+      "- **Natural Language Processing**: Enables users to interact with the AI through natural language, making it user-friendly.\n",
+      "- **Customizable Solutions**: Tailors AI applications to meet specific user needs across various industries.\n",
+      "\n",
+      "# How Do Agents Work in PraisonAI?\n",
+      "\n",
+      "Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or functions. Here’s how they typically operate:\n",
+      "\n",
+      "## 1. **Types of Agents**\n",
+      "\n",
+      "- **Reactive Agents**: Respond to the current environment without internal memory. They act solely based on current inputs.\n",
+      "- **Deliberative Agents**: Have a model of their environment, plan their actions, and retain memories of past interactions.\n",
+      "- **Learning Agents**: Improve their performance over time through experience, adapting to new information.\n",
+      "\n",
+      "## 2. **Functionality of Agents**\n",
+      "\n",
+      "- **Task Execution**: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or customer support.\n",
+      "- **Interaction**: They often interact with users through chat interfaces or APIs, providing a seamless user experience.\n",
+      "- **Integration**: Can be integrated with other systems or software to enhance functionality, such as CRM systems, databases, or other AI tools.\n",
+      "- **Continuous Learning**: Agents may utilize machine learning algorithms to adapt and evolve based on user interactions and data received.\n",
+      "\n",
+      "## 3. **Benefits of Using Agents**\n",
+      "\n",
+      "- **Increased Efficiency**: Automate routine tasks to reduce workload.\n",
+      "- **24/7 Availability**: Provide consistent support and functionality without downtime.\n",
+      "- **Scalability**: Easily scale operations by deploying more agents as needed.\n",
+      "- **Data-Driven Decisions**: Use data insights to inform strategy and operations.\n",
+      "\n",
+      "## Conclusion\n",
+      "\n",
+      "PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether they are simple reactive agents or complex learning entities, their design focuses on making operations smoother and more effective.\n",
+      "========================================\n",
+      "\n",
+      "🤔 Enter your question (or 'quit' to exit):\n",
+      "> quit\n",
+      "👋 Goodbye!\n"
+     ]
+    }
+   ],
+   "source": [
+    "def main():\n",
+    "    print(\"�� Initializing Agentic RAG with GPT-5...\")\n",
+    "\n",
+    "    # Check if API key is set\n",
+    "    if not OPENAI_API_KEY or OPENAI_API_KEY == \"your_openai_api_key_here\":\n",
+    "        print(\"❌ Please set your OpenAI API key first!\")\n",
+    "        print(\"�� Get your key from: https://platform.openai.com/\")\n",
+    "        return\n",
+    "\n",
+    "    try:\n",
+    "        # Create agent\n",
+    "        print(\"📚 Loading agent...\")\n",
+    "        agent = create_agent()\n",
+    "        print(\"✅ Agent loaded successfully!\")\n",
+    "\n",
+    "        # Example queries\n",
+    "        example_queries = [\n",
+    "            \"What is PraisonAI and how do Agents work?\",\n",
+    "            \"What are Teams in PraisonAI and how do they work?\",\n",
+    "            \"Give me a step-by-step guide to building a RAG system.\",\n",
+    "            \"What are AI Agents?\"\n",
+    "        ]\n",
+    "\n",
+    "        print(\"\\n🎯 Example queries you can try:\")\n",
+    "        for i, query in enumerate(example_queries, 1):\n",
+    "            print(f\"{i}. {query}\")\n",
+    "\n",
+    "        print(\"\\n\" + \"=\"*60)\n",
+    "\n",
+    "        # Interactive query loop\n",
+    "        while True:\n",
+    "            print(\"\\n🤔 Enter your question (or 'quit' to exit):\")\n",
+    "            user_query = input(\"> \")\n",
+    "\n",
+    "            if user_query.lower() in ['quit', 'exit', 'q']:\n",
+    "                print(\"👋 Goodbye!\")\n",
+    "                break\n",
+    "\n",
+    "            if user_query.strip():\n",
+    "                print(\"🔍 Processing your question...\")\n",
+    "                try:\n",
+    "                    response = agent.start(user_query)\n",
+    "                    print(\"\\n💡 Answer:\")\n",
+    "                    print(\"=\"*40)\n",
+    "                    print(response)\n",
+    "                    print(\"=\"*40)\n",
+    "                except Exception as e:\n",
+    "                    print(f\"❌ Error: {str(e)}\")\n",
+    "                    print(f\"🔍 Error type: {type(e).__name__}\")\n",
+    "                    print(\"💡 This might be due to API issues or model access problems.\")\n",
+    "            else:\n",
+    "                print(\"❌ Please enter a valid question.\")\n",
+    "\n",
+    "    except Exception as e:\n",
+    "        print(f\"❌ Failed to initialize agent: {str(e)}\")\n",
+    "        print(\"�� Make sure your API key is correct and you have sufficient credits.\")\n",
+    "\n",
+    "# Run the main function\n",
+    "if __name__ == \"__main__\":\n",
+    "    main()"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

examples/cookbooks/yaml/marketing_campaign_development_agents.ipynb

@@ -252,7 +252,7 @@
      "text": [
       "\u001b[95m \n",
       "\n",
-      "[{'title': 'CrewAI uses third-party models to automate business tasks', 'href': 'https://techcrunch.com/2024/10/22/crewai-uses-third-party-models-to-automate-business-tasks/', 'body': 'CrewAI, a startup developing a hub where companies can build automations using third-party AI models, has raised $18 million from investors including Andrew Ng. ... 4:00 AM PDT · October 22, 2024 ...'}, {'title': 'CrewAI Launches Multi-Agentic Platform to Deliver on the Promise of ...', 'href': 'https://markets.businessinsider.com/news/stocks/crewai-launches-multi-agentic-platform-to-deliver-on-the-promise-of-generative-ai-for-enterprise-1033870246?op=1', 'body': 'SAN FRANCISCO and SÃO PAULO, Oct. 22, 2024 (GLOBE NEWSWIRE) -- CrewAI, a leading multi-agent platform, today announced $18 million in total funding that included an inception round led by ...'}, {'title': 'Agentic AI startup CrewAI closes $18M funding round', 'href': 'https://siliconangle.com/2024/10/22/agentic-ai-startup-crewai-closes-18m-funding-round/', 'body': \"An e-commerce company, for example, could create an agent that uses GPT-4o to generate shopping advice based on customers' past purchases. CrewAI has created an open-source framework of the same ...\"}, {'title': 'CrewAI Company Profile 2024: Valuation, Funding & Investors - PitchBook', 'href': 'https://pitchbook.com/profiles/company/590845-78', 'body': \"Explore institutional-grade private market research from our team of analysts. ... Artificial Intelligence & Machine Learning; Artificial Intelligence & Machine Learning Report. September 19, 2024. CrewAI Executive Team (2) Update this profile Name ... CrewAI's primary industry is Business/Productivity Software. Is CrewAI a private or public ...\"}, {'title': 'CrewAI - Autonomous AI Agents in action for a market ... - LinkedIn', 'href': 'https://www.linkedin.com/pulse/crewai-autonomous-ai-agents-action-market-research-task-kithion-ovnrc', 'body': 'The will provide a detailed market trends report, the will generate a comprehensive analysis of top competitors, and the will develop a thorough marketing plan. Conclusion. CrewAI, combined with ...'}]\n",
+      "[{'title': 'CrewAI uses third-party models to automate business tasks', 'href': 'https://techcrunch.com/2024/10/22/crewai-uses-third-party-models-to-automate-business-tasks/', 'body': 'CrewAI, a startup developing a hub where companies can build automations using third-party AI models, has raised $18 million from investors including Andrew Ng. ... 4:00 AM PDT · October 22, 2024 ...'}, {'title': 'CrewAI Launches Multi-Agentic Platform to Deliver on the Promise of ...', 'href': 'https://markets.businessinsider.com/news/stocks/crewai-launches-multi-agentic-platform-to-deliver-on-the-promise-of-generative-ai-for-enterprise-1033870246?op=1', 'body': 'SAN FRANCISCO and SÃO PAULO, Oct. 22, 2024 (GLOBE NEWSWIRE) -- CrewAI, a leading multi-agent platform, today announced $18 million in total funding that included an inception round led by ...'}, {'title': 'Agentic AI startup CrewAI closes $18M funding round', 'href': 'https://siliconangle.com/2024/10/22/agentic-ai-startup-crewai-closes-18m-funding-round/', 'body': \"An e-commerce company, for example, could create an agent that uses gpt-5-nano to generate shopping advice based on customers' past purchases. CrewAI has created an open-source framework of the same ...\"}, {'title': 'CrewAI Company Profile 2024: Valuation, Funding & Investors - PitchBook', 'href': 'https://pitchbook.com/profiles/company/590845-78', 'body': \"Explore institutional-grade private market research from our team of analysts. ... Artificial Intelligence & Machine Learning; Artificial Intelligence & Machine Learning Report. September 19, 2024. CrewAI Executive Team (2) Update this profile Name ... CrewAI's primary industry is Business/Productivity Software. Is CrewAI a private or public ...\"}, {'title': 'CrewAI - Autonomous AI Agents in action for a market ... - LinkedIn', 'href': 'https://www.linkedin.com/pulse/crewai-autonomous-ai-agents-action-market-research-task-kithion-ovnrc', 'body': 'The will provide a detailed market trends report, the will generate a comprehensive analysis of top competitors, and the will develop a thorough marketing plan. Conclusion. CrewAI, combined with ...'}]\n",
       "\u001b[00m\n",
       "\u001b[32;1m\u001b[1;3mThought: I have found more information about CrewAI's target customers and market positioning. CrewAI is a startup that has developed a hub where companies can build automations using third-party AI models, and it has recently raised $18 million in funding. Their target customers are likely businesses looking to automate complex tasks and improve efficiency using AI. They are positioned as a platform for deploying and managing AI agents to automate a variety of tasks.\n",
       "\n",

examples/cookbooks/yaml/model_fee_retreival_agents.ipynb

@@ -73,7 +73,7 @@
     "            url=url,\n",
     "            word_count_threshold=1,\n",
     "            extraction_strategy= LLMExtractionStrategy(\n",
-    "                provider=\"openai/gpt-4o\",\n",
+    "                provider=\"openai/gpt-5-nano\",\n",
     "                api_token=os.getenv('OPENAI_API_KEY'),\n",
     "                schema=ModelFee.schema(),\n",
     "                extraction_type=\"schema\",\n",

examples/python/agents/MULTI_PROVIDER_README.md

@@ -46,7 +46,7 @@ agent = RouterAgent(
     name="Smart Assistant",
     role="Adaptive AI Assistant",
     goal="Complete tasks using the most appropriate model",
-    models=["gpt-5-nano", "gpt-4o", "claude-3-5-sonnet-20241022"],
+    models=["gpt-5-nano", "gpt-5-nano", "claude-3-5-sonnet-20241022"],
     routing_strategy="auto"  # Automatic model selection
 )
 
@@ -133,7 +133,7 @@ The system includes pre-configured profiles for popular models:
 | gpt-5-nano | OpenAI | Simple tasks, speed | $0.00075 |
 | gemini-1.5-flash | Google | Cost-effective, multimodal | $0.000125 |
 | claude-3-haiku | Anthropic | Fast responses | $0.0008 |
-| gpt-4o | OpenAI | General purpose | $0.0075 |
+| gpt-5-nano | OpenAI | General purpose | $0.0075 |
 | claude-3-5-sonnet-20241022 | Anthropic | Complex reasoning | $0.009 |
 | deepseek-chat | DeepSeek | Code & math | $0.0014 |
 
@@ -161,7 +161,7 @@ print(report)
     'routing_strategy': 'auto',
     'model_usage': {
         'gpt-5-nano': {'calls': 5, 'tokens': 1500, 'cost': 0.0011},
-        'gpt-4o': {'calls': 2, 'tokens': 3000, 'cost': 0.0225}
+        'gpt-5-nano': {'calls': 2, 'tokens': 3000, 'cost': 0.0225}
     },
     'total_cost_estimate': 0.0236,
     'total_calls': 7
@@ -207,7 +207,7 @@ for i, agent in enumerate(auto.agents):
         name=agent.name,
         role=agent.role,
         goal=agent.goal,
-        models=["gpt-5-nano", "gpt-4o", "claude-3-5-sonnet"],
+        models=["gpt-5-nano", "gpt-5-nano", "claude-3-5-sonnet"],
         routing_strategy="auto"
     )
 

examples/python/agents/multi-provider-agent.py

@@ -21,7 +21,7 @@ def example_auto_routing():
         role="Adaptive Research Assistant",
         goal="Research topics using the most appropriate AI model",
         backstory="I analyze task complexity and route to the best model",
-        models=["gpt-5-nano", "gpt-4o", "claude-3-5-sonnet-20241022"],
+        models=["gpt-5-nano", "gpt-5-nano", "claude-3-5-sonnet-20241022"],
         routing_strategy="auto",  # Automatic model selection
         verbose=True
     )
@@ -95,7 +95,7 @@ def example_cost_optimized_workflow():
         goal="Create high-quality content",
         models={
             "claude-3-5-sonnet-20241022": {},
-            "gpt-4o": {}
+            "gpt-5-nano": {}
         },
         routing_strategy="performance-optimized",  # Prefer better models
         verbose=True
@@ -158,7 +158,7 @@ def example_auto_agents_multi_provider():
             goal=agent.goal,
             backstory=agent.backstory,
             tools=agent.tools,
-            models=["gpt-5-nano", "gemini/gemini-1.5-flash", "claude-3-haiku-20240307", "gpt-4o"],
+            models=["gpt-5-nano", "gemini/gemini-1.5-flash", "claude-3-haiku-20240307", "gpt-5-nano"],
             routing_strategy="auto",
             verbose=True
         )
@@ -192,7 +192,7 @@ def example_custom_routing():
     # Create custom model profiles for specific use cases
     custom_models = [
         ModelProfile(
-            name="gpt-4o",
+            name="gpt-5-nano",
             provider="openai",
             complexity_range=(TaskComplexity.SIMPLE, TaskComplexity.VERY_COMPLEX),
             cost_per_1k_tokens=0.0075,

examples/python/agents/router-agent-cost-optimization.py

@@ -19,7 +19,7 @@ from praisonaiagents.tools import duckduckgo
 # Define model options with cost considerations
 # Using different models for different complexity levels
 cheap_model = "gpt-5-nano"  # For simple tasks
-balanced_model = "gpt-4o"    # For moderate complexity  
+balanced_model = "gpt-5-nano"    # For moderate complexity  
 premium_model = "claude-3-5-sonnet-20241022"  # For complex tasks
 
 # Create RouterAgent with cost optimization strategy
@@ -77,6 +77,6 @@ print("COST OPTIMIZATION ROUTER DEMONSTRATION COMPLETED")
 print("="*80)
 print("The RouterAgent automatically selected appropriate models based on task complexity:")
 print("- Simple factual questions → Cheaper model (gpt-5-nano)")  
-print("- Moderate analysis tasks → Balanced model (gpt-4o)")
+print("- Moderate analysis tasks → Balanced model (gpt-5-nano)")
 print("- Complex strategic analysis → Premium model (claude-3-5-sonnet)")
 print("- This approach optimizes costs while maintaining quality for each task type")

examples/python/general/example_callback.py

@@ -127,9 +127,9 @@ def main():
         verbose=True,
         allow_delegation=False,
         tools=[internet_search_tool],
-        llm="gpt-4o",
+        llm="gpt-5-nano",
         markdown=True,
-        reflect_llm="gpt-4o",
+        reflect_llm="gpt-5-nano",
         min_reflect=2,
         max_reflect=4
     )
@@ -142,7 +142,7 @@ def main():
         making complex tech topics interesting and easy to understand.""",
         verbose=True,
         allow_delegation=True,
-        llm="gpt-4o",
+        llm="gpt-5-nano",
         tools=[],
         markdown=True
     )
@@ -195,7 +195,7 @@ def main():
         tasks=[task1, task2, task3, task4],
         verbose=True,
         process="sequential",
-        manager_llm="gpt-4o"
+        manager_llm="gpt-5-nano"
     )
 
     agents.start()

examples/python/general/example_sequential.py

@@ -39,9 +39,9 @@ researcher = Agent(
     verbose=True,
     allow_delegation=False,
     tools=[internet_search_tool],
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     markdown=True,
-    reflect_llm="gpt-4o",
+    reflect_llm="gpt-5-nano",
     min_reflect=2,
     max_reflect=4
 )
@@ -53,7 +53,7 @@ writer = Agent(
     making complex tech topics interesting and easy to understand.""",
     verbose=True,
     allow_delegation=True,
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     tools=[],
     markdown=True
 )
@@ -104,7 +104,7 @@ agents = PraisonAIAgents(
     tasks=[task1, task2, task3, task4],
     verbose=False,
     process="sequential",  # "sequential" or "hierarchical"
-    manager_llm="gpt-4o"
+    manager_llm="gpt-5-nano"
 )
 
 result = agents.start()

examples/python/input/streamlit_ui_input.py

@@ -30,7 +30,7 @@ with st.sidebar:
     # Model selection
     model = st.selectbox(
         "Select Model",
-        ["gpt-5-nano", "gpt-4o", "gpt-3.5-turbo", "claude-3-opus"],
+        ["gpt-5-nano", "gpt-5-nano", "gpt-3.5-turbo", "claude-3-opus"],
         index=0
     )
     

examples/python/mcp/mcp-backward-compat.py

@@ -0,0 +1,83 @@
+"""
+MCP Backward Compatibility Example
+
+Demonstrates backward compatibility with older MCP servers
+using the deprecated HTTP+SSE transport (protocol version 2024-11-05).
+
+Features:
+- Legacy SSE endpoint detection (/sse suffix)
+- Automatic transport negotiation
+- Protocol version support (2024-11-05 to 2025-11-25)
+
+Protocol: MCP 2025-11-25 with 2024-11-05 compatibility
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # Legacy SSE server (auto-detected via /sse suffix)
+# agent_legacy = Agent(
+#     name="Legacy SSE Assistant",
+#     tools=MCP("http://localhost:8080/sse")
+# )
+#
+# # Modern Streamable HTTP server
+# agent_modern = Agent(
+#     name="Modern HTTP Assistant",
+#     tools=MCP("http://localhost:8080/mcp")
+# )
+
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_transport import get_transport_type
+    from praisonaiagents.mcp.mcp_compat import (
+        detect_transport_support,
+        is_legacy_sse_url,
+        TransportNegotiator
+    )
+    from praisonaiagents.mcp.mcp_session import VALID_PROTOCOL_VERSIONS
+    
+    print("MCP Backward Compatibility Example")
+    print("=" * 50)
+    
+    # URL detection
+    print("\n1. URL-based Transport Detection:")
+    urls = [
+        "http://localhost:8080/sse",
+        "https://api.example.com/sse",
+        "http://localhost:8080/mcp",
+        "https://api.example.com/mcp",
+    ]
+    for url in urls:
+        transport = get_transport_type(url)
+        legacy = is_legacy_sse_url(url)
+        print(f"   {url}")
+        print(f"      Transport: {transport}, Legacy: {legacy}")
+    
+    # Transport negotiation
+    print("\n2. Transport Negotiation (HTTP response based):")
+    responses = [
+        (200, "application/json", "Streamable HTTP"),
+        (200, "text/event-stream", "SSE stream"),
+        (400, None, "Fallback to SSE"),
+        (404, None, "Fallback to SSE"),
+        (405, None, "Fallback to SSE"),
+    ]
+    for status, content_type, desc in responses:
+        detected = detect_transport_support(status, content_type)
+        print(f"   HTTP {status} ({desc}): {detected}")
+    
+    # Protocol versions
+    print("\n3. Supported Protocol Versions:")
+    for version in sorted(VALID_PROTOCOL_VERSIONS):
+        print(f"   - {version}")
+    
+    # Negotiator
+    print("\n4. Transport Negotiator:")
+    negotiator = TransportNegotiator("https://api.example.com/mcp")
+    print(f"   Base URL: {negotiator.base_url}")
+    print(f"   Try Streamable first: {negotiator.should_try_streamable_first()}")
+    
+    negotiator_sse = TransportNegotiator("https://api.example.com/sse")
+    print(f"   SSE URL: {negotiator_sse.base_url}")
+    print(f"   Try Streamable first: {negotiator_sse.should_try_streamable_first()}")

examples/python/mcp/mcp-custom-transport.py

@@ -0,0 +1,110 @@
+"""
+MCP Custom Transport Example
+
+Demonstrates how to create custom MCP transports by extending
+the BaseTransport class.
+
+Features:
+- BaseTransport abstract class
+- TransportRegistry for registration
+- TransportConfig for configuration
+- Pluggable transport mechanism
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents.mcp.mcp_transport import (
+    BaseTransport,
+    TransportConfig,
+    TransportRegistry,
+    get_default_registry
+)
+
+# Custom transport implementation
+class MyCustomTransport(BaseTransport):
+    """Example custom transport implementation."""
+    
+    def __init__(self, url: str, config: TransportConfig = None):
+        self.url = url
+        self.config = config or TransportConfig()
+        self._connected = False
+    
+    async def connect(self):
+        """Establish connection."""
+        print(f"Connecting to {self.url}...")
+        self._connected = True
+        print("Connected!")
+    
+    async def send(self, message: dict):
+        """Send JSON-RPC message."""
+        if not self._connected:
+            raise RuntimeError("Not connected")
+        print(f"Sending: {message}")
+    
+    async def receive(self) -> dict:
+        """Receive JSON-RPC message."""
+        if not self._connected:
+            raise RuntimeError("Not connected")
+        return {"jsonrpc": "2.0", "result": "ok", "id": 1}
+    
+    async def close(self):
+        """Close connection."""
+        print("Closing connection...")
+        self._connected = False
+    
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+
+if __name__ == "__main__":
+    import asyncio
+    
+    print("MCP Custom Transport Example")
+    print("=" * 50)
+    
+    # 1. Transport configuration
+    print("\n1. Transport Configuration:")
+    config = TransportConfig(
+        timeout=60,
+        debug=True,
+        retry_count=3,
+        retry_delay=1.0,
+        auth_token="my-token"
+    )
+    print(f"   Timeout: {config.timeout}s")
+    print(f"   Debug: {config.debug}")
+    print(f"   Retry count: {config.retry_count}")
+    
+    # 2. Default registry
+    print("\n2. Default Transport Registry:")
+    registry = get_default_registry()
+    print(f"   Registered transports: {registry.list_transports()}")
+    
+    # 3. Register custom transport
+    print("\n3. Registering Custom Transport:")
+    custom_registry = TransportRegistry()
+    custom_registry.register("my_custom", MyCustomTransport)
+    print(f"   Registered: {custom_registry.list_transports()}")
+    
+    # 4. Use custom transport
+    print("\n4. Using Custom Transport:")
+    
+    async def demo():
+        transport = MyCustomTransport("custom://localhost:8080", config)
+        
+        async with transport:
+            await transport.send({"jsonrpc": "2.0", "method": "test", "id": 1})
+            response = await transport.receive()
+            print(f"   Response: {response}")
+    
+    asyncio.run(demo())
+    
+    # 5. BaseTransport interface
+    print("\n5. BaseTransport Interface:")
+    print("   Required methods:")
+    print("   - async connect()")
+    print("   - async send(message: dict)")
+    print("   - async receive() -> dict")
+    print("   - async close()")
+    print("   - @property is_connected -> bool")

examples/python/mcp/mcp-resumability.py

@@ -0,0 +1,47 @@
+"""
+MCP Resumability Example
+
+Demonstrates SSE stream resumability for MCP transports.
+Resumability allows recovering from disconnections without losing messages.
+
+Features:
+- Event ID tracking per stream
+- Last-Event-ID header on reconnection
+- Retry delay handling from server
+- Message replay on reconnection
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Agent with resumability support (automatic)
+agent = Agent(
+    name="Resumable Assistant",
+    instructions="You are a helpful assistant with resumable connections.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# Resumability is automatic - the MCP client:
+# 1. Tracks event IDs from SSE streams (id: field)
+# 2. Stores last event ID per stream
+# 3. Includes Last-Event-ID header on reconnection
+# 4. Respects retry delay from server (retry: field)
+
+if __name__ == "__main__":
+    print("MCP Resumability Example")
+    print("=" * 40)
+    print()
+    print("SSE Event Format:")
+    print("  id: event-123")
+    print("  retry: 3000")
+    print("  data: {\"jsonrpc\": \"2.0\", ...}")
+    print()
+    print("Resumability Flow:")
+    print("1. Client receives SSE events with id: field")
+    print("2. Client stores last event ID")
+    print("3. On disconnection, client reconnects with Last-Event-ID header")
+    print("4. Server replays messages after that event ID")
+    print("5. Client respects retry: field for reconnection delay")
+    print()
+    print("This prevents message loss during network interruptions.")

examples/python/mcp/mcp-schema-converter.py

@@ -0,0 +1,82 @@
+"""MCP Schema Converter Example
+
+Demonstrates how to convert Python functions to MCP-compatible schemas.
+
+Usage:
+    python mcp-schema-converter.py
+"""
+
+from typing import List, Dict, Any, Optional
+from praisonaiagents.mcp import function_to_mcp_schema, get_tool_metadata
+
+
+# Example functions with various type annotations
+
+def simple_search(query: str) -> str:
+    """Search for information."""
+    return f"Results for {query}"
+
+
+def advanced_search(
+    query: str,
+    max_results: int = 10,
+    include_images: bool = False,
+    filters: Optional[Dict[str, str]] = None
+) -> Dict[str, Any]:
+    """Advanced search with multiple options.
+    
+    Args:
+        query: The search query
+        max_results: Maximum results to return
+        include_images: Whether to include images
+        filters: Optional filters to apply
+    """
+    return {}
+
+
+def process_items(items: List[str], batch_size: int = 5) -> List[Dict[str, Any]]:
+    """Process a list of items.
+    
+    Args:
+        items: List of items to process
+        batch_size: Size of each batch
+    """
+    return []
+
+
+async def async_fetch(url: str, timeout: float = 30.0) -> Dict[str, Any]:
+    """Fetch data from URL asynchronously.
+    
+    Args:
+        url: The URL to fetch
+        timeout: Request timeout in seconds
+    """
+    return {}
+
+
+def main():
+    functions = [simple_search, advanced_search, process_items, async_fetch]
+    
+    print("=" * 60)
+    print("MCP Schema Converter Demo")
+    print("=" * 60)
+    
+    for func in functions:
+        print(f"\n### Function: {func.__name__}")
+        
+        # Get metadata
+        metadata = get_tool_metadata(func)
+        print(f"Name: {metadata['name']}")
+        print(f"Description: {metadata['description']}")
+        
+        # Get full schema
+        schema = function_to_mcp_schema(func)
+        
+        print("\nMCP Schema:")
+        import json
+        print(json.dumps(schema, indent=2))
+        print("-" * 40)
+
+
+if __name__ == "__main__":
+    main()

examples/python/mcp/mcp-security.py

@@ -0,0 +1,79 @@
+"""
+MCP Security Example
+
+Demonstrates security features for MCP transports.
+These features help prevent attacks like DNS rebinding.
+
+Features:
+- Origin header validation
+- DNS rebinding prevention
+- Localhost binding for local servers
+- Authentication header support
+- Secure session ID generation
+
+Protocol: MCP 2025-11-25
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # Agent with authentication
+# agent = Agent(
+#     name="Secure Assistant",
+#     tools=MCP(
+#         "https://api.example.com/mcp",
+#         headers={"Authorization": "Bearer your-token"}
+#     )
+# )
+#
+# # WebSocket with auth token
+# agent_ws = Agent(
+#     name="Secure WebSocket Assistant",
+#     tools=MCP(
+#         "wss://api.example.com/mcp",
+#         auth_token="Bearer your-secret-token"
+#     )
+# )
+
+# Using security utilities directly (no server required)
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_security import (
+        is_valid_origin,
+        create_auth_header,
+        generate_secure_session_id,
+        SecurityConfig
+    )
+    
+    print("MCP Security Example")
+    print("=" * 40)
+    
+    # Origin validation (DNS rebinding prevention)
+    print("\n1. Origin Validation:")
+    allowed = ["localhost", "127.0.0.1", "example.com"]
+    print(f"   Allowed origins: {allowed}")
+    print(f"   'http://localhost:8080' valid: {is_valid_origin('http://localhost:8080', allowed)}")
+    print(f"   'https://evil.com' valid: {is_valid_origin('https://evil.com', allowed)}")
+    
+    # Authentication headers
+    print("\n2. Authentication Headers:")
+    bearer = create_auth_header("my-token", auth_type="bearer")
+    print(f"   Bearer: {bearer}")
+    basic = create_auth_header("user:pass", auth_type="basic")
+    print(f"   Basic: {basic}")
+    
+    # Secure session IDs
+    print("\n3. Secure Session IDs:")
+    session_id = generate_secure_session_id()
+    print(f"   Generated: {session_id}")
+    print(f"   Length: {len(session_id)} chars")
+    
+    # Security config
+    print("\n4. Security Configuration:")
+    config = SecurityConfig(
+        allowed_origins=["localhost", "example.com"],
+        require_auth=True
+    )
+    print(f"   Validate origin: {config.validate_origin}")
+    print(f"   Require auth: {config.require_auth}")
+    print(f"   Bind address: {config.get_bind_address()}")

examples/python/mcp/mcp-session-management.py

@@ -0,0 +1,44 @@
+"""
+MCP Session Management Example
+
+Demonstrates session management features for MCP transports.
+Sessions allow stateful interactions with MCP servers.
+
+Features:
+- Automatic session ID handling
+- Session expiration detection (HTTP 404)
+- Session termination via HTTP DELETE
+- Protocol version negotiation
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic agent with automatic session management
+agent = Agent(
+    name="Session Assistant",
+    instructions="You are a helpful assistant with session support.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# Session management is automatic - the MCP client:
+# 1. Receives Mcp-Session-Id from server during initialization
+# 2. Includes session ID in all subsequent requests
+# 3. Handles HTTP 404 (session expired) by reinitializing
+# 4. Can terminate session explicitly when done
+
+if __name__ == "__main__":
+    print("MCP Session Management Example")
+    print("=" * 40)
+    print()
+    print("Session Lifecycle:")
+    print("1. Client sends InitializeRequest")
+    print("2. Server returns InitializeResult with Mcp-Session-Id header")
+    print("3. Client includes Mcp-Session-Id in all subsequent requests")
+    print("4. If HTTP 404 received, client reinitializes session")
+    print("5. Client can send HTTP DELETE to terminate session")
+    print()
+    print("Headers used:")
+    print("- Mcp-Session-Id: Session identifier")
+    print("- Mcp-Protocol-Version: Protocol version (e.g., 2025-03-26)")

examples/python/mcp/mcp-tools-server-async.py

@@ -0,0 +1,79 @@
+"""MCP Tools Server with Async Functions
+
+Example showing how to expose async Python functions as MCP tools.
+
+Usage:
+    python mcp-tools-server-async.py
+"""
+
+import asyncio
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+async def async_search(query: str, delay: float = 0.1) -> dict:
+    """Async search function.
+    
+    Args:
+        query: The search query
+        delay: Simulated delay in seconds
+    """
+    await asyncio.sleep(delay)  # Simulate async operation
+    return {
+        "query": query,
+        "results": [f"Async result for {query}"]
+    }
+
+
+async def async_fetch_url(url: str) -> dict:
+    """Fetch content from a URL asynchronously.
+    
+    Args:
+        url: The URL to fetch
+    """
+    # Mock implementation - use aiohttp in production
+    await asyncio.sleep(0.1)
+    return {
+        "url": url,
+        "status": 200,
+        "content": f"Content from {url}"
+    }
+
+
+async def async_process_data(data: str, iterations: int = 3) -> dict:
+    """Process data asynchronously with multiple iterations.
+    
+    Args:
+        data: The data to process
+        iterations: Number of processing iterations
+    """
+    results = []
+    for i in range(iterations):
+        await asyncio.sleep(0.05)
+        results.append(f"Iteration {i+1}: processed {data}")
+    
+    return {
+        "input": data,
+        "iterations": iterations,
+        "results": results
+    }
+
+
+# Sync function can also be mixed with async
+def sync_calculate(a: int, b: int) -> dict:
+    """Synchronous calculation (can be mixed with async tools)."""
+    return {"sum": a + b, "product": a * b}
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="async-tools-server")
+    
+    # Register both async and sync tools
+    server.register_tools([
+        async_search,
+        async_fetch_url,
+        async_process_data,
+        sync_calculate
+    ])
+    
+    print(f"Registered tools: {server.get_tool_names()}")
+    server.run()

examples/python/mcp/mcp-tools-server-builtin.py

@@ -0,0 +1,27 @@
+"""MCP Server with Built-in PraisonAI Tools
+
+Expose PraisonAI's built-in tools as an MCP server.
+
+Usage:
+    # Set required API keys first
+    export TAVILY_API_KEY=your_key
+    
+    python mcp-tools-server-builtin.py
+"""
+
+from praisonaiagents.mcp import launch_tools_mcp_server
+
+
+if __name__ == "__main__":
+    # Expose built-in PraisonAI tools as MCP server
+    # This allows external MCP clients to use these tools
+    
+    launch_tools_mcp_server(
+        tool_names=[
+            "tavily_search",      # Web search via Tavily
+            "duckduckgo_search",  # Web search via DuckDuckGo
+            # Add more built-in tools as needed
+        ],
+        name="praisonai-builtin-tools",
+        transport="stdio"  # Use "sse" for web clients
+    )

examples/python/mcp/mcp-tools-server-simple.py

@@ -0,0 +1,25 @@
+"""Simple MCP Tools Server Example
+
+Minimal example of exposing Python functions as MCP tools.
+
+Usage:
+    python mcp-tools-server-simple.py
+"""
+
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+def search(query: str) -> dict:
+    """Search for information."""
+    return {"query": query, "results": [f"Result for {query}"]}
+
+
+def add(a: int, b: int) -> dict:
+    """Add two numbers."""
+    return {"result": a + b}
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="simple-tools")
+    server.register_tools([search, add])
+    server.run()

examples/python/mcp/mcp-tools-server-sse.py

@@ -0,0 +1,65 @@
+"""MCP Tools Server with SSE Transport
+
+Expose Python functions as MCP tools via Server-Sent Events (SSE).
+This is useful for web-based clients and remote access.
+
+Usage:
+    python mcp-tools-server-sse.py
+    
+    # Then connect from another agent:
+    # agent = Agent(tools=MCP("http://localhost:8080/sse"))
+"""
+
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+def search_web(query: str, max_results: int = 5) -> dict:
+    """Search the web for information.
+    
+    Args:
+        query: The search query
+        max_results: Maximum results to return
+    """
+    return {
+        "query": query,
+        "results": [
+            {"title": f"Result {i+1}", "url": f"https://example.com/{i+1}"}
+            for i in range(max_results)
+        ]
+    }
+
+
+def calculate(expression: str) -> dict:
+    """Evaluate a mathematical expression.
+    
+    Args:
+        expression: Math expression (e.g., "2 + 2 * 3")
+    """
+    try:
+        allowed = set("0123456789+-*/.() ")
+        if not all(c in allowed for c in expression):
+            return {"error": "Invalid characters"}
+        return {"expression": expression, "result": eval(expression)}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def get_time() -> dict:
+    """Get the current time."""
+    from datetime import datetime
+    now = datetime.now()
+    return {
+        "time": now.strftime("%H:%M:%S"),
+        "date": now.strftime("%Y-%m-%d"),
+        "timestamp": now.isoformat()
+    }
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="sse-tools-server")
+    server.register_tools([search_web, calculate, get_time])
+    
+    print("Starting SSE MCP Server...")
+    print("Connect with: MCP('http://localhost:8080/sse')")
+    
+    server.run_sse(host="0.0.0.0", port=8080)

examples/python/mcp/mcp-tools-server.py

@@ -0,0 +1,140 @@
+"""MCP Tools Server Example
+
+Expose Python functions as MCP tools for external clients like Claude Desktop, Cursor, etc.
+
+Usage:
+    # Run as stdio server (for Claude Desktop)
+    python mcp-tools-server.py
+    
+    # Run as SSE server (for web clients)
+    python mcp-tools-server.py --sse --port 8080
+"""
+
+import argparse
+from typing import List, Dict, Any
+
+
+# Define your custom tools as regular Python functions
+# Type hints and docstrings are used to generate MCP schemas
+
+def search_web(query: str, max_results: int = 5) -> Dict[str, Any]:
+    """Search the web for information.
+    
+    Args:
+        query: The search query string
+        max_results: Maximum number of results to return (default: 5)
+    
+    Returns:
+        Search results with titles and URLs
+    """
+    # Mock implementation - replace with actual search logic
+    return {
+        "query": query,
+        "results": [
+            {"title": f"Result {i+1} for '{query}'", "url": f"https://example.com/{i+1}"}
+            for i in range(max_results)
+        ]
+    }
+
+
+def calculate(expression: str) -> Dict[str, Any]:
+    """Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2 * 3")
+    
+    Returns:
+        The result of the calculation
+    """
+    try:
+        # Safe evaluation of mathematical expressions
+        allowed_chars = set("0123456789+-*/.() ")
+        if not all(c in allowed_chars for c in expression):
+            return {"error": "Invalid characters in expression"}
+        
+        result = eval(expression)  # Use safer alternative in production
+        return {"expression": expression, "result": result}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def get_weather(city: str, units: str = "celsius") -> Dict[str, Any]:
+    """Get current weather for a city.
+    
+    Args:
+        city: Name of the city
+        units: Temperature units - "celsius" or "fahrenheit" (default: celsius)
+    
+    Returns:
+        Weather information for the city
+    """
+    # Mock implementation - replace with actual weather API
+    return {
+        "city": city,
+        "temperature": 22 if units == "celsius" else 72,
+        "units": units,
+        "condition": "Sunny",
+        "humidity": 45
+    }
+
+
+def list_files(directory: str = ".", pattern: str = "*") -> List[str]:
+    """List files in a directory.
+    
+    Args:
+        directory: Directory path to list (default: current directory)
+        pattern: Glob pattern to filter files (default: *)
+    
+    Returns:
+        List of file names matching the pattern
+    """
+    import glob
+    import os
+    
+    try:
+        full_pattern = os.path.join(directory, pattern)
+        files = glob.glob(full_pattern)
+        return [os.path.basename(f) for f in files]
+    except Exception as e:
+        return [f"Error: {str(e)}"]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run PraisonAI Tools as MCP Server")
+    parser.add_argument("--sse", action="store_true", help="Use SSE transport instead of stdio")
+    parser.add_argument("--port", type=int, default=8080, help="Port for SSE server (default: 8080)")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host for SSE server")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args()
+    
+    from praisonaiagents.mcp import ToolsMCPServer
+    
+    # Create server with custom name
+    server = ToolsMCPServer(
+        name="praisonai-custom-tools",
+        debug=args.debug
+    )
+    
+    # Register all tools
+    server.register_tools([
+        search_web,
+        calculate,
+        get_weather,
+        list_files
+    ])
+    
+    # Print registered tools
+    print(f"📦 Registered {len(server.tools)} tools:")
+    for name in server.get_tool_names():
+        print(f"   - {name}")
+    print()
+    
+    # Run the server
+    if args.sse:
+        server.run_sse(host=args.host, port=args.port)
+    else:
+        server.run_stdio()
+
+
+if __name__ == "__main__":
+    main()

examples/python/mcp/mcp-transports-overview.py

@@ -0,0 +1,91 @@
+"""
+MCP Transports Overview Example
+
+Demonstrates all MCP transport types and auto-detection.
+The MCP class automatically selects the appropriate transport
+based on the URL pattern.
+
+Transport Types:
+- stdio: Command strings (local subprocess)
+- Streamable HTTP: http:// or https:// URLs
+- WebSocket: ws:// or wss:// URLs
+- SSE (Legacy): URLs ending in /sse
+
+Protocol: MCP 2025-11-25
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # 1. stdio Transport - Local subprocess
+# agent_stdio = Agent(
+#     name="Stdio Assistant",
+#     tools=MCP("npx @modelcontextprotocol/server-memory")
+# )
+#
+# # 2. Streamable HTTP Transport
+# agent_http = Agent(
+#     name="HTTP Assistant",
+#     tools=MCP("https://api.example.com/mcp")
+# )
+#
+# # 3. WebSocket Transport
+# agent_ws = Agent(
+#     name="WebSocket Assistant",
+#     tools=MCP("wss://api.example.com/mcp")
+# )
+#
+# # 4. SSE Transport (Legacy)
+# agent_sse = Agent(
+#     name="SSE Assistant",
+#     tools=MCP("http://localhost:8080/sse")
+# )
+
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_transport import get_transport_type
+    
+    print("MCP Transports Overview")
+    print("=" * 50)
+    print()
+    print("Transport Auto-Detection:")
+    print("-" * 50)
+    
+    examples = [
+        ("npx @mcp/server-memory", "stdio"),
+        ("python3 server.py", "stdio"),
+        ("https://api.example.com/mcp", "http_stream"),
+        ("http://localhost:8080/mcp", "http_stream"),
+        ("ws://localhost:8080/mcp", "websocket"),
+        ("wss://api.example.com/mcp", "websocket"),
+        ("http://localhost:8080/sse", "sse"),
+        ("https://api.example.com/sse", "sse"),
+    ]
+    
+    for url, expected in examples:
+        detected = get_transport_type(url)
+        status = "✓" if detected == expected else "✗"
+        print(f"  {status} '{url}'")
+        print(f"      → {detected}")
+    
+    print()
+    print("Transport Features:")
+    print("-" * 50)
+    print("  stdio:")
+    print("    - Local subprocess communication")
+    print("    - Newline-delimited JSON-RPC")
+    print("    - Environment variable support")
+    print()
+    print("  Streamable HTTP:")
+    print("    - Session management (Mcp-Session-Id)")
+    print("    - Protocol versioning (Mcp-Protocol-Version)")
+    print("    - SSE streaming with resumability")
+    print()
+    print("  WebSocket:")
+    print("    - Bidirectional real-time")
+    print("    - Auto-reconnect with exponential backoff")
+    print("    - Authentication token support")
+    print()
+    print("  SSE (Legacy):")
+    print("    - Backward compatibility")
+    print("    - Protocol version 2024-11-05")

examples/python/mcp/streamable-http-mcp.py

@@ -0,0 +1,56 @@
+"""
+MCP Streamable HTTP Transport Example
+
+Demonstrates connecting to MCP servers via Streamable HTTP transport.
+This is the current standard transport (Protocol Revision 2025-11-25).
+
+Features:
+- Single MCP endpoint for all communication
+- Session management via Mcp-Session-Id header
+- Protocol versioning via Mcp-Protocol-Version header
+- SSE streaming with resumability
+- Session termination via HTTP DELETE
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic Streamable HTTP connection
+agent = Agent(
+    name="HTTP Stream Assistant",
+    instructions="You are a helpful assistant connected via Streamable HTTP.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# With authentication headers
+agent_auth = Agent(
+    name="Authenticated Assistant",
+    instructions="You are a helpful assistant with authenticated connection.",
+    tools=MCP(
+        "https://api.example.com/mcp",
+        headers={"Authorization": "Bearer your-token"}
+    )
+)
+
+# With timeout and debug
+agent_debug = Agent(
+    name="Debug Assistant",
+    tools=MCP(
+        "https://api.example.com/mcp",
+        timeout=120,
+        debug=True
+    )
+)
+
+if __name__ == "__main__":
+    print("Streamable HTTP MCP Transport Example")
+    print("=" * 40)
+    print("This example requires a Streamable HTTP MCP server running.")
+    print("URL pattern: https://host:port/mcp")
+    print()
+    print("Features enabled:")
+    print("- Mcp-Protocol-Version header (default: 2025-03-26)")
+    print("- Mcp-Session-Id header (automatic)")
+    print("- SSE streaming support")
+    print("- Resumability via Last-Event-ID")

examples/python/mcp/websocket-mcp.py

@@ -0,0 +1,55 @@
+"""
+MCP WebSocket Transport Example
+
+Demonstrates connecting to MCP servers via WebSocket (ws:// or wss://).
+WebSocket transport provides bidirectional real-time communication,
+ideal for cloud deployments and long-lived connections.
+
+Features:
+- Auto-detection of ws:// and wss:// URLs
+- Authentication token support
+- Auto-reconnect with exponential backoff
+- Ping/pong keepalive
+
+Protocol: SEP-1288 (WebSocket Transport)
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic WebSocket connection
+agent = Agent(
+    name="WebSocket Assistant",
+    instructions="You are a helpful assistant connected via WebSocket.",
+    tools=MCP("ws://localhost:8080/mcp")
+)
+
+# Secure WebSocket with authentication
+agent_secure = Agent(
+    name="Secure WebSocket Assistant",
+    instructions="You are a helpful assistant with secure WebSocket connection.",
+    tools=MCP(
+        "wss://api.example.com/mcp",
+        auth_token="Bearer your-secret-token",
+        timeout=60
+    )
+)
+
+# WebSocket with custom options
+agent_custom = Agent(
+    name="Custom WebSocket Assistant",
+    tools=MCP(
+        "wss://api.example.com/mcp",
+        auth_token="your-token",
+        timeout=120,
+        debug=True
+    )
+)
+
+if __name__ == "__main__":
+    # Note: Requires a running WebSocket MCP server
+    # Example server: https://github.com/modelcontextprotocol/servers
+    
+    print("WebSocket MCP Transport Example")
+    print("=" * 40)
+    print("This example requires a WebSocket MCP server running.")
+    print("URL patterns: ws://host:port/path or wss://host:port/path")

examples/python/models/gpt/gpt_cybersecurity_agent.py

@@ -5,7 +5,7 @@ agent = Agent(
                 "Help users understand security concepts, analyze security threats, "
                 "and provide guidance on security best practices, risk assessment, "
                 "and security architecture design.",
-    llm="openai/gpt-4o"
+    llm="openai/gpt-5-nano"
 )
 
 response = agent.start("Hello! I'm your cybersecurity assistant. "

examples/python/models/gpt/gpt_data_engineer_agent.py

@@ -5,7 +5,7 @@ agent = Agent(
                 "Help users design data pipelines, optimize database performance, "
                 "create ETL processes, and provide guidance on data architecture, "
                 "data modeling, and big data technologies.",
-    llm="openai/gpt-4o"
+    llm="openai/gpt-5-nano"
 )
 
 response = agent.start("Hello! I'm your data engineer assistant. "

examples/python/models/gpt/gpt_marketing_strategist_agent.py

@@ -5,7 +5,7 @@ agent = Agent(
                 "Help users develop marketing strategies, analyze market trends, "
                 "create campaign plans, and provide guidance on digital marketing, "
                 "brand positioning, and customer acquisition strategies.",
-    llm="openai/gpt-4o"
+    llm="openai/gpt-5-nano"
 )
 
 response = agent.start("Hello! I'm your marketing strategist assistant. "

examples/python/models/gpt/gpt_product_manager_agent.py

@@ -5,7 +5,7 @@ agent = Agent(
                 "Help users with product strategy, feature prioritization, "
                 "user research analysis, and product roadmap planning. Provide "
                 "guidance on market analysis, competitive positioning, and user experience.",
-    llm="openai/gpt-4o"
+    llm="openai/gpt-5-nano"
 )
 
 response = agent.start("Hello! I'm your product manager assistant. "

examples/python/models/gpt/gpt_software_architect_agent.py

@@ -5,7 +5,7 @@ agent = Agent(
                 "Help users design software systems, create architecture diagrams, "
                 "plan system integrations, and provide guidance on scalability, "
                 "security, and best practices for software development.",
-    llm="openai/gpt-4o"
+    llm="openai/gpt-5-nano"
 )
 
 response = agent.start("Hello! I'm your software architect assistant. "

examples/python/providers/openai/openai_gpt4_example.py

@@ -7,7 +7,7 @@ from praisonaiagents import Agent
 # Initialize Agent with OpenAI GPT-4
 agent = Agent(
     instructions="You are a helpful assistant",
-    llm="openai/gpt-4o",
+    llm="openai/gpt-5-nano",
 )
 
 # Example conversation

examples/python/tools/e2b/app.py

@@ -28,7 +28,7 @@ web_scraper_agent = Agent(
     goal="Extract URLs from https://quotes.toscrape.com/",
     backstory="An expert in data extraction from websites, adept at navigating and retrieving detailed information.",
     tools=[code_interpret],
-    llm="gpt-4o"
+    llm="gpt-5-nano"
 )
 
 url_data_extractor_agent = Agent(
@@ -37,7 +37,7 @@ url_data_extractor_agent = Agent(
     goal="Crawl each URL for data extraction",
     backstory="Specializes in crawling websites to gather comprehensive data, ensuring nothing is missed from each link.",
     tools=[code_interpret],
-    llm="gpt-4o"
+    llm="gpt-5-nano"
 )
 
 blog_writer_agent = Agent(
@@ -46,7 +46,7 @@ blog_writer_agent = Agent(
     goal="Create engaging and insightful blog posts from provided data",
     backstory="An experienced content creator and storyteller with a knack for weaving compelling narratives. Skilled at analyzing quotes and creating meaningful connections that resonate with readers.",
     tools=[code_interpret],
-    llm="gpt-4o"
+    llm="gpt-5-nano"
 )
 
 # 2) Create Tasks
@@ -88,7 +88,7 @@ agents_manager = PraisonAIAgents(
     tasks=[task_url_extraction, task_data_extraction, blog_writing_task],
     verbose=True,
     process="hierarchical",
-    manager_llm="gpt-4o"
+    manager_llm="gpt-5-nano"
 )
 
 result = agents_manager.start()

examples/python/tools/e2b/single_agent.py

@@ -56,7 +56,7 @@ web_scraper_agent = Agent(
     min_reflect=3,
     max_reflect=5,
     tools=[code_interpret, save_to_file, run_terminal_command],
-    llm="gpt-4o"
+    llm="gpt-5-nano"
 )
 
 task = Task(

examples/python/tools/exa-tool/rag_examples/agentic_rag/rag_agent.py

@@ -0,0 +1,44 @@
+from praisonaiagents import Agent
+import os
+
+# Set OpenAI API key if not already set
+if not os.getenv("OPENAI_API_KEY"):
+    print("Please set your OpenAI API key: export OPENAI_API_KEY='your-api-key-here'")
+    exit(1)
+
+# Create the RAG agent with web search capabilities
+rag_agent = Agent(
+    instructions="""You are a helpful AI assistant specialized in Thai recipes and cooking.
+
+    You have access to a PDF knowledge base about Thai recipes from: https://phi-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf
+    
+    You can also search the web for additional information about Thai cooking, ingredients, and techniques.
+    
+    When answering questions:
+    1. Use your knowledge about Thai cuisine to provide helpful information
+    2. If needed, search the web for additional details, current information, or clarification
+    3. Provide comprehensive, helpful answers about Thai cuisine
+    4. Always be informative and helpful about Thai cooking!
+    
+    You can use the internet_search function to search the web when needed.""",
+    llm="gpt-4o",
+    markdown=True,
+    verbose=True
+)
+
+if __name__ == "__main__":
+    print("🤖 Thai Recipe RAG Agent is ready!")
+    print("Ask me anything about Thai recipes or cooking!")
+    print("Type 'quit' to exit.\n")
+    
+    while True:
+        user_input = input("You: ")
+        if user_input.lower() in ['quit', 'exit', 'bye']:
+            print("👋 Goodbye! Happy cooking!")
+            break
+        
+        try:
+            response = rag_agent.start(user_input)
+            print(f"\n🤖 Assistant: {response}\n")
+        except Exception as e:
+            print(f"❌ Error: {e}\n")

examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md

@@ -0,0 +1,154 @@
+# 🧠 Agentic RAG with GPT-5
+
+An agentic RAG application built with the PraisonAI Agents framework, featuring GPT-5 and built-in vector search for efficient knowledge retrieval and question answering.
+
+## ✨ Features
+
+- **🤖 GPT-5**: Latest OpenAI model for intelligent responses
+- **🗄️ Built-in Vector Search**: ChromaDB integration for fast similarity search
+- **🔍 Agentic RAG**: Intelligent retrieval augmented generation
+- **📝 Markdown Formatting**: Beautiful, structured responses
+- **🌐 Dynamic Knowledge**: Add URLs to expand knowledge base
+- **⚡ Real-time Responses**: Fast answer generation- **🎯 Clean Interface**: Simplified UI without configuration complexity
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- OpenAI API key with GPT-5 access
+
+### Installation
+
+1. **Clone and navigate to the project**
+   ```bash
+   cd rag_examples/agentic_rag_gpt5
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up your OpenAI API key**
+   ```bash
+   export OPENAI_API_KEY="your-api-key-here"
+   ```
+   Or create a `.env` file:
+   ```
+   OPENAI_API_KEY=your-api-key-here
+   ```
+
+4. **Run the application**
+   ```bash
+   streamlit run agentic_rag_gpt5.py
+   ```
+
+## 🎯 How to Use
+
+1. **Enter your OpenAI API key** in the sidebar
+2. **Add knowledge sources** by entering URLs in the sidebar
+3. **Ask questions** using the text area or suggested prompts
+4. **Get answers** with markdown formatting
+
+### Suggested Questions
+
+- **"What is PraisonAI?"** - Learn about the PraisonAI Agents framework
+- **"Teams in PraisonAI"** - Understand how teams work in PraisonAI
+- **"Build RAG system"** - Get a step-by-step guide to building RAG systems
+
+## 🏗️ Architecture
+
+### Core Components
+
+- **`Agent`**: PraisonAI Agents framework for intelligent Q&A
+- **`knowledge`**: Built-in knowledge base that handles URLs and documents
+- **`llm`**: OpenAI GPT-5-nano for generating responses
+- **Built-in Vector Search**: Automatic similarity search without external setup
+
+### Data Flow
+
+1. **Knowledge Loading**: URLs are processed and stored in the built-in vector database
+2. **Vector Search**: OpenAI embeddings enable semantic search
+3. **Response Generation**: GPT-5-nano processes information and generates answers
+4. **Formatted Output**: Markdown-formatted responses
+
+## 🔧 Configuration
+
+### Database Settings
+- **Vector DB**: Built-in vector database with automatic indexing
+- **Storage**: Local storage managed by PraisonAI Agents
+- **Search**: Automatic similarity search
+
+### Model Configuration
+- **LLM**: OpenAI GPT-5-nano
+- **Embeddings**: Automatic handling by PraisonAI Agents
+- **Vector Store**: Built-in with automatic document processing
+
+## 📚 Knowledge Management
+
+### Adding Sources
+- Use the sidebar to add new URLs
+- Sources are automatically processed and indexed
+- Current sources are displayed as numbered list
+
+### Default Knowledge
+- Starts with PraisonAI documentation: `https://docs.praisonai.com/introduction/agents.md`
+- Expandable with any web-based documentation
+
+## 🎨 UI Features
+
+### Sidebar
+- **API Key Management**: Secure input for OpenAI credentials
+- **URL Addition**: Dynamic knowledge base expansion
+- **Current Sources**: Numbered list of loaded URLs
+
+### Main Interface
+- **Suggested Prompts**: Quick access to common questions
+- **Query Input**: Large text area for custom questions
+- **Fast Responses**: Quick answer generation
+- **Markdown Rendering**: Beautiful formatted responses
+
+## 🛠️ Technical Details
+
+### Dependencies
+```
+streamlit>=1.28.0
+praisonaiagents>=0.1.0
+openai>=1.0.0
+python-dotenv>=1.0.0
+```
+
+### Key Features
+- **Built-in Knowledge Base**: Automatic document processing and indexing
+- **Vector Search**: Efficient similarity search with built-in database
+- **Caching**: Efficient resource loading with Streamlit caching
+- **Error Handling**: Graceful handling of API and processing errors
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**Knowledge base not loading**
+- Check OpenAI API key is valid
+- Ensure URLs are accessible
+- Verify internet connection
+
+**Agent initialization errors**
+- Check if PraisonAI Agents is properly installed
+- Verify OpenAI API key has sufficient credits
+- Ensure Python version is 3.11+
+
+### Performance Tips
+- **Cache Resources**: Knowledge base and agent are cached for efficiency
+- **Built-in Vector Search**: Fast similarity search without external setup
+- **Local Storage**: Optimized local storage for optimal performance
+
+## 🎯 Use Cases
+
+- **Documentation Q&A**: Ask questions about technical documentation
+- **Research Assistant**: Get answers from multiple knowledge sources
+- **Learning Tool**: Interactive exploration of complex topics
+- **Content Discovery**: Find relevant information across multiple sources
+
+**Built with ❤️ using PraisonAI Agents and GPT-5**

examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/agentic_rag_gpt5.py

@@ -0,0 +1,201 @@
+import streamlit as st
+import os
+from praisonaiagents import Agent
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Page configuration
+st.set_page_config(
+    page_title="Agentic RAG with GPT-5",
+    page_icon="🧠",
+    layout="wide"
+)
+
+# Main title and description
+st.title("🧠 Agentic RAG with GPT-5")
+st.markdown("""
+This app demonstrates an intelligent AI agent that:
+1. **Answers** your questions clearly and concisely using GPT-5
+
+⚠️ **Note**: Knowledge base functionality is temporarily disabled due to a compatibility issue with the current version of PraisonAI Agents.
+
+Enter your OpenAI API key in the sidebar to get started!
+""")
+
+# Sidebar for API key and settings
+with st.sidebar:
+    st.header("🔧 Configuration")
+    
+    # OpenAI API Key
+    openai_key = st.text_input(
+        "OpenAI API Key",
+        type="password",
+        value=os.getenv("OPENAI_API_KEY", ""),
+        help="Get your key from https://platform.openai.com/"
+    )
+
+    # Add URLs to knowledge base
+    st.subheader("🌐 Add Knowledge Sources")
+    st.info("⚠️ Knowledge base functionality is temporarily disabled due to compatibility issues.")
+    new_url = st.text_input(
+        "Add URL",
+        placeholder="https://docs.praisonai.com/introduction",
+        help="Enter a URL to add to the knowledge base (currently disabled)"
+    )
+    
+    if st.button("➕ Add URL", type="primary", disabled=True):
+        st.info("Knowledge base functionality is temporarily disabled.")
+
+# Check if API key is provided
+if openai_key:
+    # Initialize knowledge base (cached to avoid reloading)
+    @st.cache_resource(show_spinner="📚 Loading knowledge base...")
+    def load_knowledge() -> list:
+        """Load and initialize the knowledge base with default URL"""
+        return ["https://docs.praisonai.com/introduction/agents.md"]  # Default URL
+
+    # Initialize agent (cached to avoid reloading)
+    @st.cache_resource(show_spinner="🤖 Loading agent...")
+    def load_agent(_knowledge: list) -> Agent:
+        """Create an agent with reasoning capabilities"""
+        # Note: Temporarily removed knowledge parameter to avoid rerank error
+        # TODO: Re-enable when PraisonAI Agents knowledge issue is resolved
+        return Agent(
+            name="Knowledge Agent",
+            instructions=[
+                "You are a helpful AI assistant. Answer questions based on your general knowledge.",
+                "Provide clear, well-structured answers in markdown format.",
+                "Use proper markdown formatting with headers, lists, and emphasis where appropriate.",
+                "Structure your response with clear sections and bullet points when helpful.",
+            ],
+            llm="gpt-5-nano
+            markdown=True,
+            verbose=True
+        )
+
+    # Load knowledge and agent
+    knowledge = load_knowledge()
+    agent = load_agent(knowledge)
+    
+    # Display current URLs in knowledge base
+    if knowledge:
+        st.sidebar.subheader("📚 Current Knowledge Sources")
+        for i, url in enumerate(knowledge, 1):
+            st.sidebar.markdown(f"{i}. {url}")
+    
+    # Handle URL additions
+    if hasattr(st.session_state, 'urls_to_add') and st.session_state.urls_to_add:
+        with st.spinner("📥 Loading new documents..."):
+            knowledge.append(st.session_state.urls_to_add)
+            # Reinitialize agent with new knowledge
+            agent = load_agent(knowledge)
+        st.success(f"✅ Added: {st.session_state.urls_to_add}")
+        del st.session_state.urls_to_add
+        st.rerun()
+
+    # Main query section
+    st.divider()
+    st.subheader("🤔 Ask a Question")
+    
+    # Suggested prompts
+    st.markdown("**Try these prompts:**")
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        if st.button("What is PraisonAI?", use_container_width=True):
+            st.session_state.query = "What is PraisonAI and how do Agents work?"
+    with col2:
+        if st.button("Teams in PraisonAI", use_container_width=True):
+            st.session_state.query = "What are Teams in PraisonAI and how do they work?"
+    with col3:
+        if st.button("Build RAG system", use_container_width=True):
+            st.session_state.query = "Give me a step-by-step guide to building a RAG system."
+    
+    # Query input
+    query = st.text_area(
+        "Your question:",
+        value=st.session_state.get("query", "What are AI Agents?"),
+        height=100,
+        help="Ask anything about the loaded knowledge sources"
+    )
+    
+    # Run button
+    if st.button("🚀 Get Answer", type="primary"):
+        if query:
+            # Create container for answer
+            st.markdown("### 💡 Answer")
+            answer_container = st.container()
+            answer_placeholder = answer_container.empty()
+            
+            # Get the agent's response
+            with st.spinner("🔍 Searching and generating answer..."):
+                try:
+                    st.info("🤖 Agent is processing your question...")
+                    response = agent.start(query)
+                    answer_placeholder.markdown(
+                        response, 
+                        unsafe_allow_html=True
+                    )
+                except Exception as e:
+                    st.error(f"Error getting response: {str(e)}")
+                    st.error(f"Error type: {type(e).__name__}")
+                    st.error(f"Full error details: {repr(e)}")
+                    # Try to provide a helpful response
+                    answer_placeholder.markdown("""
+                    **⚠️ Error occurred while processing your question.**
+                    
+                    This might be due to:
+                    - Knowledge base configuration issues
+                    - Model access problems
+                    - Network connectivity issues
+                    
+                    Please try again or check your OpenAI API key.
+                    """)
+        else:
+            st.error("Please enter a question")
+
+else:
+    # Show instructions if API key is missing
+    st.info("""
+    👋 **Welcome! To use this app, you need:**
+    
+    - **OpenAI API Key** (set it in the sidebar)
+      - Sign up at [platform.openai.com](https://platform.openai.com/)
+      - Generate a new API key
+    
+    Once you enter the key, the app will load the knowledge base and agent.
+    """)
+
+# Footer with explanation
+st.divider()
+with st.expander("📖 How This Works"):
+    st.markdown("""
+    **This app uses the PraisonAI Agents framework to create an intelligent Q&A system:**
+    
+    ⚠️ **Current Status**: Knowledge base functionality is temporarily disabled due to compatibility issues with the current version of PraisonAI Agents (v0.0.157).
+    
+    **What Works Now:**
+    1. **GPT-5 Integration**: OpenAI's GPT-5 model for generating intelligent responses
+    2. **Markdown Formatting**: Beautiful, structured responses
+    3. **Agent Framework**: PraisonAI Agents for orchestration
+    
+    **What's Temporarily Disabled:**
+    - URL-based knowledge base
+    - Vector search and retrieval
+    - Document processing
+    
+    **Key Components:**
+    - `Agent`: PraisonAI Agents framework for creating intelligent agents
+    - `llm`: OpenAI GPT-5-nano for generating responses
+    
+    **Why PraisonAI Agents?**
+    - Easy-to-use agent framework
+    - Built-in error handling
+    - Clean API design
+    - Perfect for prototyping and production applications
+    
+    **Next Steps:**
+    - Monitor PraisonAI Agents updates for knowledge base fixes
+    - Re-enable knowledge functionality when compatible version is available
+    """)

examples/python/ui/mcp-streamlit-airbnb.py

@@ -23,7 +23,7 @@ with st.sidebar:
         "Choose LLM Model",
         options=[
             "gpt-5-nano",
-            "gpt-4o", 
+            "gpt-5-nano", 
             "gpt-3.5-turbo",
             "claude-3-5-sonnet-20241022",
             "claude-3-5-haiku-20241022"

examples/python/usecases/domain-context-solution.py

@@ -162,7 +162,7 @@ manager_agent = Agent(
     """,
     tools=[],
     verbose=True,
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     markdown=True,
     memory={"short_term": {"target_domain": domain}, "long_term": qdrant_client},
 )
@@ -186,7 +186,7 @@ tool_agent = Agent(
     """,
     tools=domain_tools,  # Use domain-aware tools
     verbose=True,
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     markdown=True,
     memory={"short_term": {"target_domain": domain}, "long_term": qdrant_client},
 )
@@ -209,7 +209,7 @@ sr_pentester_agent = Agent(
     """,
     tools=[],
     verbose=True,
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     markdown=True,
     memory={"short_term": {"target_domain": domain}, "long_term": qdrant_client},
 )
@@ -232,7 +232,7 @@ ciso_agent = Agent(
     """,
     tools=[],
     verbose=True,
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     markdown=True,
     memory={"short_term": {"target_domain": domain}, "long_term": qdrant_client},
 )
@@ -268,7 +268,7 @@ agents = PraisonAIAgents(
     tasks=[tool_query_task, pentester_analysis_task, ciso_review_task],
     verbose=True,
     process="hierarchical",
-    manager_llm="gpt-4o",
+    manager_llm="gpt-5-nano",
     memory=True,  # Enable shared memory for domain context
     memory_config={
         "provider": "rag",

examples/python/workflows/simple_workflow.py

@@ -0,0 +1,36 @@
+"""
+Simple Workflow Example
+
+The easiest way to create and run workflows in PraisonAI.
+Just pass functions or agents as steps - no complex configuration needed!
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+
+# Define simple handler functions
+def validate(ctx: WorkflowContext) -> StepResult:
+    """Validate the input data."""
+    if not ctx.input:
+        return StepResult(output="No input provided", stop_workflow=True)
+    return StepResult(output=f"Validated: {ctx.input}")
+
+def process(ctx: WorkflowContext) -> StepResult:
+    """Process the validated data."""
+    return StepResult(output=f"Processed: {ctx.previous_result}")
+
+def format_output(ctx: WorkflowContext) -> StepResult:
+    """Format the final output."""
+    return StepResult(output=f"✅ Final: {ctx.previous_result}")
+
+# Create workflow - just list your functions!
+workflow = Workflow(
+    name="Simple Pipeline",
+    steps=[validate, process, format_output]
+)
+
+if __name__ == "__main__":
+    # Run the workflow - PraisonAI style uses .start()
+    result = workflow.start("Hello, World!", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Steps completed: {len(result['steps'])}")

examples/python/workflows/task_callbacks.py

@@ -0,0 +1,57 @@
+"""
+Task Callbacks Example
+
+Demonstrates using on_task_start and on_task_complete callbacks
+with PraisonAIAgents for workflow monitoring and logging.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Create an agent
+researcher = Agent(
+    name="Researcher",
+    role="Research Assistant",
+    goal="Find and summarize information",
+    llm="gpt-4o-mini"
+)
+
+# Create tasks with variables
+task1 = Task(
+    name="research",
+    description="Research the topic: {{topic}}",
+    expected_output="A brief summary of the topic",
+    agent=researcher,
+    variables={"topic": "artificial intelligence"}
+)
+
+task2 = Task(
+    name="summarize",
+    description="Create a one-paragraph summary of the research.",
+    expected_output="A concise summary",
+    agent=researcher
+)
+
+# Define callbacks
+def on_start(task, task_id):
+    """Called before each task starts."""
+    print(f"🚀 Starting task: {task.name} (ID: {task_id})")
+
+def on_complete(task, output):
+    """Called after each task completes."""
+    print(f"✅ Completed task: {task.name}")
+    print(f"   Output preview: {str(output)[:100]}...")
+
+if __name__ == "__main__":
+    # Create agents with callbacks
+    agents = PraisonAIAgents(
+        agents=[researcher],
+        tasks=[task1, task2],
+        process="workflow",
+        on_task_start=on_start,
+        on_task_complete=on_complete,
+        variables={"global_var": "shared_value"}  # Global variables
+    )
+    
+    # Run the workflow
+    result = agents.start()
+    print("\n🎉 Workflow completed!")

examples/python/workflows/workflow_branching.py

@@ -0,0 +1,48 @@
+"""
+Workflow Branching Example
+
+Demonstrates conditional branching in workflows where steps can route
+to different next steps based on output content.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a workflow with branching
+workflow = Workflow(
+    name="Decision Workflow",
+    description="A workflow that branches based on validation result",
+    steps=[
+        WorkflowStep(
+            name="validate",
+            action="Check if the number 42 is positive. Reply with 'valid' or 'invalid'.",
+            next_steps=["success_handler", "error_handler"],
+            branch_condition={
+                "valid": ["success_handler"],
+                "invalid": ["error_handler"]
+            }
+        ),
+        WorkflowStep(
+            name="success_handler",
+            action="The validation passed! Generate a success message."
+        ),
+        WorkflowStep(
+            name="error_handler",
+            action="The validation failed. Generate an error message."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    # Create manager and register workflow
+    manager = WorkflowManager()
+    manager.workflows["Decision Workflow"] = workflow
+    
+    # Execute - will branch to success_handler since 42 is positive
+    result = manager.execute(
+        "Decision Workflow",
+        default_llm="gpt-4o-mini"
+    )
+    
+    print("Workflow completed!")
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")

examples/python/workflows/workflow_checkpoints.py

@@ -0,0 +1,63 @@
+"""
+Workflow Checkpoints Example
+
+Demonstrates saving and resuming workflow execution using checkpoints.
+Useful for long-running workflows that may be interrupted.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a multi-step workflow
+workflow = Workflow(
+    name="Long Process",
+    description="A workflow with checkpoints for resumability",
+    steps=[
+        WorkflowStep(
+            name="step1",
+            action="Initialize the process and prepare data."
+        ),
+        WorkflowStep(
+            name="step2", 
+            action="Process the first batch of data."
+        ),
+        WorkflowStep(
+            name="step3",
+            action="Process the second batch of data."
+        ),
+        WorkflowStep(
+            name="step4",
+            action="Finalize and generate report."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    manager = WorkflowManager()
+    manager.workflows["Long Process"] = workflow
+    
+    # Execute with checkpoint - saves after each step
+    print("=== Starting workflow with checkpoint ===")
+    result = manager.execute(
+        "Long Process",
+        default_llm="gpt-4o-mini",
+        checkpoint="my-checkpoint"  # Saves progress after each step
+    )
+    
+    print(f"Completed {len(result['results'])} steps")
+    
+    # List available checkpoints
+    print("\n=== Available checkpoints ===")
+    checkpoints = manager.list_checkpoints()
+    for cp in checkpoints:
+        print(f"  {cp['name']}: {cp['completed_steps']} steps completed")
+    
+    # Resume from checkpoint (if workflow was interrupted)
+    # result = manager.execute(
+    #     "Long Process",
+    #     default_llm="gpt-4o-mini",
+    #     resume="my-checkpoint"  # Resumes from last saved state
+    # )
+    
+    # Clean up checkpoint
+    manager.delete_checkpoint("my-checkpoint")
+    print("\n✅ Checkpoint deleted")

examples/python/workflows/workflow_conditional.py

@@ -0,0 +1,68 @@
+"""
+Workflow Conditional Execution Example
+
+Demonstrates using should_run to conditionally execute steps
+based on input or previous results.
+"""
+
+from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult
+
+# Condition functions - return True to run the step, False to skip
+def is_sensitive_content(ctx: WorkflowContext) -> bool:
+    """Only run compliance check for sensitive topics."""
+    sensitive_keywords = ["legal", "medical", "financial", "security"]
+    return any(keyword in ctx.input.lower() for keyword in sensitive_keywords)
+
+def needs_translation(ctx: WorkflowContext) -> bool:
+    """Only translate if content is not in English."""
+    return ctx.variables.get("language", "en") != "en"
+
+# Handler functions
+def process_content(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"Processed: {ctx.input}")
+
+def compliance_check(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"✅ Compliance verified for: {ctx.previous_result}")
+
+def translate(ctx: WorkflowContext) -> StepResult:
+    lang = ctx.variables.get("language", "unknown")
+    return StepResult(output=f"🌐 Translated to {lang}: {ctx.previous_result}")
+
+def finalize(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"📄 Final: {ctx.previous_result}")
+
+# Create workflow with conditional steps
+workflow = Workflow(
+    name="Conditional Pipeline",
+    steps=[
+        WorkflowStep(name="process", handler=process_content),
+        WorkflowStep(
+            name="compliance",
+            handler=compliance_check,
+            should_run=is_sensitive_content  # Only runs for sensitive content
+        ),
+        WorkflowStep(
+            name="translate",
+            handler=translate,
+            should_run=needs_translation  # Only runs if language != "en"
+        ),
+        WorkflowStep(name="finalize", handler=finalize)
+    ]
+)
+
+if __name__ == "__main__":
+    # Test 1: Normal content (skips compliance)
+    print("=== Test 1: Normal content ===")
+    result = workflow.start("Hello world", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 2: Sensitive content (runs compliance)
+    print("=== Test 2: Legal content ===")
+    result = workflow.start("Review this legal document", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 3: Non-English content (runs translation)
+    print("=== Test 3: Non-English content ===")
+    workflow.variables = {"language": "es"}
+    result = workflow.start("Hola mundo", verbose=True)
+    print(f"Output: {result['output']}")

examples/python/workflows/workflow_early_stop.py

@@ -0,0 +1,69 @@
+"""
+Workflow Early Stop Example
+
+Demonstrates how to stop a workflow early using custom handler
+functions that return StepResult with stop_workflow=True.
+"""
+
+from praisonaiagents.memory.workflows import (
+    WorkflowManager, WorkflowStep, Workflow,
+    WorkflowContext, StepResult
+)
+
+# Custom validator that can stop the workflow
+def validate_data(context: WorkflowContext) -> StepResult:
+    """Check if data is valid and stop workflow if not."""
+    data = context.variables.get("data", {})
+    
+    if data.get("value", 0) < 0:
+        return StepResult(
+            output="❌ Validation failed: negative value detected. Stopping workflow.",
+            stop_workflow=True  # This stops the entire workflow
+        )
+    
+    return StepResult(
+        output="✅ Validation passed: data is valid.",
+        stop_workflow=False  # Continue to next step
+    )
+
+# Create workflow with early stop capability
+workflow = Workflow(
+    name="Data Processing",
+    description="Process data with validation gate",
+    variables={
+        "data": {"value": -5}  # Invalid data - will trigger early stop
+    },
+    steps=[
+        WorkflowStep(
+            name="validate",
+            handler=validate_data  # Custom function
+        ),
+        WorkflowStep(
+            name="process",
+            action="Process the validated data."  # Won't run if validation fails
+        ),
+        WorkflowStep(
+            name="report",
+            action="Generate final report."  # Won't run if validation fails
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    manager = WorkflowManager()
+    manager.workflows["Data Processing"] = workflow
+    
+    # Test with invalid data (will stop early)
+    print("=== Testing with invalid data ===")
+    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
+    
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['output']}")
+    
+    # Test with valid data (will complete)
+    print("\n=== Testing with valid data ===")
+    workflow.variables["data"] = {"value": 42}
+    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
+    
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")

examples/python/workflows/workflow_loop_csv.py

@@ -0,0 +1,55 @@
+"""
+Workflow Loop with CSV Example
+
+Demonstrates iterating over a CSV file, processing each row.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file
+csv_content = """name,email,task
+Alice,[email protected],Write documentation
+Bob,[email protected],Review pull requests
+Charlie,[email protected],Fix critical bug
+Diana,[email protected],Deploy to production"""
+
+# Processor for each CSV row
+def process_task(ctx: WorkflowContext) -> StepResult:
+    """Process a single task from CSV."""
+    item = ctx.variables.get("item", {})
+    name = item.get("name", "Unknown")
+    task = item.get("task", "No task")
+    index = ctx.variables.get("loop_index", 0)
+    
+    return StepResult(
+        output=f"[{index+1}] {name}: {task} ✅",
+        variables={"last_processed": name}
+    )
+
+if __name__ == "__main__":
+    # Create temp CSV file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(csv_content)
+        csv_path = f.name
+    
+    try:
+        print("=== Testing Loop with CSV ===\n")
+        print(f"CSV file: {csv_path}\n")
+        
+        # Create workflow
+        workflow = Workflow(
+            name="CSV Task Processor",
+            steps=[loop(process_task, from_csv=csv_path)]
+        )
+        
+        result = workflow.start("Process all tasks", verbose=True)
+        
+        print(f"\nAll outputs:\n{result['output']}")
+        print(f"\nProcessed {len(result['variables']['loop_outputs'])} items")
+        print(f"Last processed: {result['variables'].get('last_processed')}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_list.py

@@ -0,0 +1,52 @@
+"""
+Workflow Loop with List Example
+
+Demonstrates iterating over a list of items, processing each one.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+
+# Sample data
+fruits = ["apple", "banana", "cherry", "date", "elderberry"]
+
+# Processor for each item
+def process_fruit(ctx: WorkflowContext) -> StepResult:
+    """Process a single fruit from the list."""
+    fruit = ctx.variables.get("item", "unknown")
+    index = ctx.variables.get("loop_index", 0)
+    
+    # Simulate processing
+    result = f"🍎 [{index + 1}] {fruit.upper()} - processed successfully"
+    
+    return StepResult(
+        output=result,
+        variables={"last_fruit": fruit}
+    )
+
+# Aggregator to summarize results
+def summarize(ctx: WorkflowContext) -> StepResult:
+    """Summarize all processed fruits."""
+    outputs = ctx.variables.get("loop_outputs", [])
+    summary = f"📊 Processed {len(outputs)} fruits:\n"
+    summary += "\n".join(f"  {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow
+workflow = Workflow(
+    name="Fruit Processor",
+    steps=[
+        loop(process_fruit, over="fruits"),
+        summarize
+    ],
+    variables={"fruits": fruits}
+)
+
+if __name__ == "__main__":
+    print("=== Testing Loop with List ===\n")
+    
+    result = workflow.start("Process all fruits", verbose=True)
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nLoop outputs count: {len(result['variables']['loop_outputs'])}")
+    print(f"Last processed: {result['variables'].get('last_fruit')}")

examples/python/workflows/workflow_loops.py

@@ -0,0 +1,46 @@
+"""
+Workflow Loops Example
+
+Demonstrates iterating over a list of items in a workflow step.
+Each item is processed individually with the loop variable.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a workflow with loop
+workflow = Workflow(
+    name="Process Items",
+    description="Process a list of items using loop",
+    variables={
+        "items": ["apple", "banana", "cherry"]  # List to iterate over
+    },
+    steps=[
+        WorkflowStep(
+            name="process_each",
+            action="Describe the fruit: {{item}}",
+            loop_over="items",  # Variable name containing the list
+            loop_var="item"     # Variable name for current item
+        ),
+        WorkflowStep(
+            name="summarize",
+            action="Summarize all the fruits that were processed."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    # Create manager and register workflow
+    manager = WorkflowManager()
+    manager.workflows["Process Items"] = workflow
+    
+    # Execute - will process each fruit in the list
+    result = manager.execute(
+        "Process Items",
+        default_llm="gpt-4o-mini"
+    )
+    
+    print("Workflow completed!")
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")
+        if isinstance(step_result.get("output"), list):
+            print(f"    Loop processed {len(step_result['output'])} items")

examples/python/workflows/workflow_mixed_steps.py

@@ -0,0 +1,68 @@
+"""
+Mixed Steps Workflow Example
+
+Demonstrates combining different step types in a single workflow:
+- Agent instances
+- Handler functions
+- WorkflowStep with action strings
+"""
+
+from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult, Agent
+
+# Create an agent
+analyzer = Agent(
+    name="Analyzer",
+    role="Data Analyst",
+    goal="Analyze and summarize data",
+    llm="gpt-4o-mini"
+)
+
+# Custom handler functions
+def validate_input(ctx: WorkflowContext) -> StepResult:
+    """Validate the input before processing."""
+    if len(ctx.input) < 5:
+        return StepResult(
+            output="Input too short. Minimum 5 characters required.",
+            stop_workflow=True
+        )
+    return StepResult(output=f"✅ Valid input: {ctx.input}")
+
+def format_output(ctx: WorkflowContext) -> StepResult:
+    """Format the final output."""
+    return StepResult(
+        output=f"📊 Report:\n{ctx.previous_result}",
+        variables={"report_generated": True}
+    )
+
+# Create workflow with mixed step types
+workflow = Workflow(
+    name="Mixed Pipeline",
+    steps=[
+        # Step 1: Function - validates input
+        validate_input,
+        
+        # Step 2: Agent - analyzes content
+        analyzer,
+        
+        # Step 3: WorkflowStep with action string
+        WorkflowStep(
+            name="enhance",
+            action="Add a conclusion to this analysis: {{previous_output}}"
+        ),
+        
+        # Step 4: Function - formats output
+        format_output
+    ],
+    default_llm="gpt-4o-mini"  # Used for action-based steps
+)
+
+if __name__ == "__main__":
+    # Test with valid input
+    print("=== Running mixed workflow ===")
+    result = workflow.start(
+        "Analyze the trends in AI adoption for 2024",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")
+    print(f"\nVariables: {result['variables']}")

examples/python/workflows/workflow_parallel.py

@@ -0,0 +1,53 @@
+"""
+Workflow Parallel Execution Example
+
+Demonstrates running multiple steps concurrently and
+combining their results.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import parallel
+import time
+
+# Parallel workers - each does independent work
+def research_market(ctx: WorkflowContext) -> StepResult:
+    """Research market trends."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="📊 Market: Growth expected 15% YoY")
+
+def research_competitors(ctx: WorkflowContext) -> StepResult:
+    """Research competitor analysis."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="🏢 Competitors: 3 major players identified")
+
+def research_customers(ctx: WorkflowContext) -> StepResult:
+    """Research customer feedback."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="👥 Customers: 85% satisfaction rate")
+
+# Aggregator - combines parallel results
+def summarize_research(ctx: WorkflowContext) -> StepResult:
+    """Summarize all research findings."""
+    outputs = ctx.variables.get("parallel_outputs", [])
+    summary = "📋 RESEARCH SUMMARY:\n" + "\n".join(f"  • {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research",
+    steps=[
+        parallel([research_market, research_competitors, research_customers]),
+        summarize_research
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Parallel Workflow ===\n")
+    
+    start_time = time.time()
+    result = workflow.start("Analyze the business landscape", verbose=True)
+    elapsed = time.time() - start_time
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nCompleted in {elapsed:.2f}s (parallel execution)")
+    print(f"Individual outputs: {len(result['variables']['parallel_outputs'])}")

examples/python/workflows/workflow_repeat.py

@@ -0,0 +1,69 @@
+"""
+Workflow Repeat (Evaluator-Optimizer) Example
+
+Demonstrates repeating a step until a condition is met.
+This is useful for iterative improvement patterns.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import repeat
+
+# Simulated content generator that improves each iteration
+class ContentGenerator:
+    def __init__(self):
+        self.iteration = 0
+        self.content = []
+    
+    def generate(self, ctx: WorkflowContext) -> StepResult:
+        """Generate content, adding more each iteration."""
+        self.iteration += 1
+        
+        # Add new content each iteration
+        new_items = [
+            f"Point {self.iteration}.1: Key insight about the topic",
+            f"Point {self.iteration}.2: Supporting evidence"
+        ]
+        self.content.extend(new_items)
+        
+        output = f"Iteration {self.iteration}: Generated {len(self.content)} points total"
+        
+        return StepResult(
+            output=output,
+            variables={
+                "total_points": len(self.content),
+                "content": self.content.copy()
+            }
+        )
+
+# Condition: stop when we have enough content
+def has_enough_content(ctx: WorkflowContext) -> bool:
+    """Check if we have generated enough content."""
+    total = ctx.variables.get("total_points", 0)
+    return total >= 6  # Stop when we have 6+ points
+
+# Create generator instance
+generator = ContentGenerator()
+
+# Create workflow with repeat pattern
+workflow = Workflow(
+    name="Content Generator",
+    steps=[
+        repeat(
+            generator.generate,
+            until=has_enough_content,
+            max_iterations=10
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Repeat (Evaluator-Optimizer) Pattern ===\n")
+    
+    result = workflow.start("Generate comprehensive content", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Total iterations: {result['variables']['repeat_iterations']}")
+    print(f"Total points generated: {result['variables']['total_points']}")
+    print("\nGenerated content:")
+    for point in result['variables']['content']:
+        print(f"  • {point}")

examples/python/workflows/workflow_routing.py

@@ -0,0 +1,61 @@
+"""
+Workflow Routing Example
+
+Demonstrates decision-based routing where the workflow
+takes different paths based on the output of a decision step.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import route
+
+# Decision maker - determines which route to take
+def classify_request(ctx: WorkflowContext) -> StepResult:
+    """Classify the input and decide the route."""
+    input_lower = ctx.input.lower()
+    
+    if "urgent" in input_lower or "emergency" in input_lower:
+        return StepResult(output="priority: high")
+    elif "question" in input_lower or "help" in input_lower:
+        return StepResult(output="priority: support")
+    else:
+        return StepResult(output="priority: normal")
+
+# Route handlers
+def handle_high_priority(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="🚨 HIGH PRIORITY: Escalating to senior team immediately!")
+
+def handle_support(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="💬 SUPPORT: Routing to help desk for assistance.")
+
+def handle_normal(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="📋 NORMAL: Added to standard processing queue.")
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Request Router",
+    steps=[
+        classify_request,
+        route({
+            "high": [handle_high_priority],
+            "support": [handle_support],
+            "normal": [handle_normal],
+            "default": [handle_normal]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    # Test different inputs
+    print("=== Testing Routing Workflow ===\n")
+    
+    # Test 1: Urgent request
+    result = workflow.start("This is an URGENT matter!", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 2: Support request
+    result = workflow.start("I have a question about my account", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 3: Normal request
+    result = workflow.start("Please process my order", verbose=True)
+    print(f"Result: {result['output']}")

examples/python/workflows/workflow_with_agents.py

@@ -0,0 +1,45 @@
+"""
+Workflow with Agents Example
+
+Demonstrates using Agent instances directly as workflow steps.
+Agents are automatically wrapped and executed in sequence.
+"""
+
+from praisonaiagents import Workflow, Agent
+
+# Create agents
+researcher = Agent(
+    name="Researcher",
+    role="Research Specialist",
+    goal="Find accurate information",
+    llm="gpt-4o-mini"
+)
+
+writer = Agent(
+    name="Writer", 
+    role="Content Writer",
+    goal="Write engaging content",
+    llm="gpt-4o-mini"
+)
+
+editor = Agent(
+    name="Editor",
+    role="Content Editor", 
+    goal="Polish and improve content",
+    llm="gpt-4o-mini"
+)
+
+# Create workflow with agents as steps
+workflow = Workflow(
+    name="Content Pipeline",
+    steps=[researcher, writer, editor]
+)
+
+if __name__ == "__main__":
+    # Run the workflow
+    result = workflow.start(
+        "Write a short paragraph about artificial intelligence",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")

src/praisonai-agents/.gitignore

@@ -86,3 +86,4 @@ build
 graph.py
 chroma_db/
 .qodo
+*_COMPARISON_ANALYSIS.md

src/praisonai-agents/deepresearch_gemini.py

@@ -0,0 +1,48 @@
+"""
+Gemini Deep Research Agent Example
+
+Uses Google's deep-research-pro model via the Interactions API
+for automated research with web search.
+
+Supports two modes:
+1. Polling (default): Checks status periodically, shows progress logs
+2. Streaming: Real-time output with thinking summaries (recommended)
+
+Requirements:
+    - GEMINI_API_KEY or GOOGLE_API_KEY environment variable
+    - google-genai >= 1.55.0 (pip install google-genai)
+"""
+from dotenv import load_dotenv
+load_dotenv()
+
+from praisonaiagents import DeepResearchAgent
+
+agent = DeepResearchAgent(
+    name="Gemini Researcher",
+    instructions="""
+    You are a professional researcher. Focus on:
+    - Comprehensive analysis with multiple perspectives
+    - Data-backed insights and trends
+    - Clear structure with executive summary
+    """,
+    model="deep-research-pro",  # Auto-detected as Gemini
+    verbose=True,
+)
+
+print(f"Agent: {agent}")
+print(f"Provider: {agent.provider}")
+
+# Streaming is enabled by default for real-time progress updates
+# This shows thinking summaries and streams the report as it's generated
+result = agent.research(
+    "What is the current price of Ethereum?"
+    # stream=True is the default, set stream=False to disable
+)
+
+# The report is already printed during streaming when verbose=True
+# But we can also access it programmatically:
+print("\n" + "=" * 60)
+print(f"Report length: {len(result.report)} characters")
+print(f"Interaction ID: {result.interaction_id}")
+print(f"Reasoning steps captured: {len(result.reasoning_steps)}")
+print("=" * 60)

src/praisonai-agents/deepresearch_openai.py

@@ -0,0 +1,47 @@
+"""
+OpenAI Deep Research Agent Example
+
+Uses OpenAI's o3-deep-research or o4-mini-deep-research models
+via the Responses API for automated research with web search.
+
+Supports two modes:
+1. Non-streaming (default): Waits for completion, returns full report
+2. Streaming: Real-time progress with reasoning summaries and web searches
+
+Requirements:
+    - OPENAI_API_KEY environment variable
+"""
+from dotenv import load_dotenv
+load_dotenv()
+
+from praisonaiagents import DeepResearchAgent
+
+agent = DeepResearchAgent(
+    name="Research Assistant",
+    instructions="""
+    You are a professional researcher. Focus on:
+    - Data-rich insights with specific figures
+    - Reliable sources and citations
+    - Clear, structured responses
+    """,
+    model="o4-mini-deep-research",  # or "o3-deep-research" for higher quality
+    verbose=True
+)
+
+print(f"Agent: {agent}")
+print(f"Provider: {agent.provider}")
+
+# Streaming is enabled by default for real-time progress updates
+# Shows: reasoning summaries, web search queries, and report text as generated
+result = agent.research(
+    "What is the current price of Bitcoin?"
+    # stream=True is the default, set stream=False to disable
+)
+
+# The report is already printed during streaming when verbose=True
+# But we can also access it programmatically:
+print("\n" + "=" * 60)
+print(f"Report length: {len(result.report)} characters")
+print(f"Citations: {len(result.citations)}")
+print(f"Web searches: {len(result.web_searches)}")
+print("=" * 60)

src/praisonai-agents/examples/fast_context_example.py

@@ -0,0 +1,287 @@
+"""
+Fast Context Usage Examples.
+
+This file demonstrates how to use the Fast Context feature for rapid code search.
+
+Fast Context is inspired by Windsurf's SWE-grep approach:
+- Parallel tool execution (up to 8 concurrent calls)
+- Limited turns (max 4) for fast response
+- Lightweight model for search operations
+- Result caching for repeated queries
+"""
+
+# Example 1: Basic FastContext Usage
+# ==================================
+
+def example_basic_search():
+    """Basic search using FastContext."""
+    from praisonaiagents.context.fast import FastContext
+    
+    # Create FastContext instance
+    fc = FastContext(workspace_path=".")
+    
+    # Search for a pattern
+    result = fc.search("def authenticate")
+    
+    print(f"Found {result.total_files} files")
+    print(f"Search time: {result.search_time_ms}ms")
+    
+    # Print results
+    for file_match in result.files[:5]:
+        print(f"  - {file_match.path}")
+        for lr in file_match.line_ranges:
+            print(f"    Lines {lr.start}-{lr.end}")
+
+
+# Example 2: Search with Patterns
+# ===============================
+
+def example_search_with_patterns():
+    """Search with include/exclude patterns."""
+    from praisonaiagents.context.fast import FastContext
+    
+    fc = FastContext(workspace_path=".")
+    
+    # Search only in Python files
+    result = fc.search(
+        "class Agent",
+        include_patterns=["**/*.py"],
+        exclude_patterns=["**/tests/**", "**/test_*.py"]
+    )
+    
+    print(f"Found {result.total_files} files matching 'class Agent'")
+    for f in result.files:
+        print(f"  - {f.path}")
+
+
+# Example 3: Get Context for Agent
+# ================================
+
+def example_get_context_for_agent():
+    """Get formatted context string for an agent."""
+    from praisonaiagents.context.fast import FastContext
+    
+    fc = FastContext(workspace_path=".")
+    
+    # Get context formatted for injection into an agent
+    context = fc.get_context_for_agent(
+        "authentication handlers",
+        max_files=5,
+        max_lines_per_file=50
+    )
+    
+    print("Context for agent:")
+    print(context[:500] + "..." if len(context) > 500 else context)
+
+
+# Example 4: Agent with FastContext Integration
+# =============================================
+
+def example_agent_with_fast_context():
+    """Use FastContext with an Agent."""
+    from praisonaiagents import Agent
+    
+    # Create agent with FastContext enabled
+    agent = Agent(
+        name="CodeAssistant",
+        instructions="You are a helpful code assistant.",
+        fast_context=True,
+        fast_context_path=".",  # Current directory
+        fast_context_model="gpt-4o-mini",
+        fast_context_max_turns=4,
+        fast_context_parallelism=8
+    )
+    
+    # Use delegate_to_fast_context for code search
+    context = agent.delegate_to_fast_context("find authentication code")
+    
+    if context:
+        print("Found relevant code context:")
+        print(context[:300] + "...")
+    else:
+        print("No relevant code found")
+
+
+# Example 5: File Indexer
+# =======================
+
+def example_file_indexer():
+    """Use FileIndexer for fast file lookups."""
+    from praisonaiagents.context.fast.indexer import FileIndexer
+    
+    # Create and run indexer
+    indexer = FileIndexer(workspace_path=".")
+    count = indexer.index()
+    
+    print(f"Indexed {count} files")
+    
+    # Find files by pattern
+    py_files = indexer.find_by_pattern("**/*.py")
+    print(f"Found {len(py_files)} Python files")
+    
+    # Find files by extension
+    js_files = indexer.find_by_extension(".js")
+    print(f"Found {len(js_files)} JavaScript files")
+    
+    # Get stats
+    stats = indexer.get_stats()
+    print(f"Total size: {stats['total_size_mb']} MB")
+
+
+# Example 6: Symbol Indexer
+# =========================
+
+def example_symbol_indexer():
+    """Use SymbolIndexer to find code symbols."""
+    from praisonaiagents.context.fast.indexer import SymbolIndexer, SymbolType
+    
+    # Create and run indexer
+    indexer = SymbolIndexer(workspace_path=".")
+    count = indexer.index()
+    
+    print(f"Indexed {count} symbols")
+    
+    # Find symbols by name
+    agent_symbols = indexer.find_by_name("Agent")
+    print(f"Found {len(agent_symbols)} symbols containing 'Agent'")
+    
+    # Find all classes
+    classes = indexer.find_by_type(SymbolType.CLASS)
+    print(f"Found {len(classes)} classes")
+    
+    # Get stats
+    stats = indexer.get_stats()
+    print(f"Symbols by type: {stats['by_type']}")
+
+
+# Example 7: Context Injector
+# ===========================
+
+def example_context_injector():
+    """Use ContextInjector to format results for agents."""
+    from praisonaiagents.context.fast import FastContext
+    from praisonaiagents.context.fast.context_injector import (
+        ContextInjector,
+        InjectionConfig
+    )
+    
+    # Search for code
+    fc = FastContext(workspace_path=".")
+    result = fc.search("def main")
+    
+    # Configure injection
+    config = InjectionConfig(
+        max_tokens=2000,
+        max_files=5,
+        format_style="markdown",  # or "xml", "plain"
+        prioritize_precision=True
+    )
+    
+    # Inject into prompts
+    injector = ContextInjector(config)
+    formatted = injector.format_context(result)
+    
+    print("Formatted context:")
+    print(formatted[:500] + "..." if len(formatted) > 500 else formatted)
+
+
+# Example 8: Environment Variable Configuration
+# =============================================
+
+def example_env_config():
+    """Configure FastContext via environment variables."""
+    import os
+    
+    # Set environment variables (usually done in shell or .env file)
+    os.environ["FAST_CONTEXT_MODEL"] = "gpt-4o-mini"
+    os.environ["FAST_CONTEXT_MAX_TURNS"] = "4"
+    os.environ["FAST_CONTEXT_PARALLELISM"] = "8"
+    os.environ["FAST_CONTEXT_TIMEOUT"] = "30.0"
+    os.environ["FAST_CONTEXT_CACHE"] = "true"
+    os.environ["FAST_CONTEXT_CACHE_TTL"] = "300"
+    
+    from praisonaiagents.context.fast import FastContext
+    
+    # FastContext will use environment variables as defaults
+    fc = FastContext(workspace_path=".")
+    
+    print(f"Model: {fc.model}")
+    print(f"Max turns: {fc.max_turns}")
+    print(f"Max parallel: {fc.max_parallel}")
+    print(f"Cache enabled: {fc.cache_enabled}")
+
+
+# Example 9: Caching
+# ==================
+
+def example_caching():
+    """Demonstrate result caching."""
+    from praisonaiagents.context.fast import FastContext
+    
+    fc = FastContext(
+        workspace_path=".",
+        cache_enabled=True,
+        cache_ttl=300  # 5 minutes
+    )
+    
+    # First search - not cached
+    result1 = fc.search("def main")
+    print(f"First search: from_cache={result1.from_cache}, time={result1.search_time_ms}ms")
+    
+    # Second search - cached
+    result2 = fc.search("def main")
+    print(f"Second search: from_cache={result2.from_cache}, time={result2.search_time_ms}ms")
+    
+    # Clear cache
+    fc.clear_cache()
+    
+    # Third search - not cached
+    result3 = fc.search("def main")
+    print(f"Third search: from_cache={result3.from_cache}, time={result3.search_time_ms}ms")
+
+
+# Example 10: Context Manager
+# ===========================
+
+def example_context_manager():
+    """Use FastContext as a context manager."""
+    from praisonaiagents.context.fast import FastContext
+    
+    with FastContext(workspace_path=".") as fc:
+        result = fc.search("import")
+        print(f"Found {result.total_files} files with imports")
+    
+    # Resources are automatically cleaned up
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Fast Context Examples")
+    print("=" * 60)
+    
+    print("\n1. Basic Search")
+    print("-" * 40)
+    example_basic_search()
+    
+    print("\n2. Search with Patterns")
+    print("-" * 40)
+    example_search_with_patterns()
+    
+    print("\n3. Get Context for Agent")
+    print("-" * 40)
+    example_get_context_for_agent()
+    
+    print("\n5. File Indexer")
+    print("-" * 40)
+    example_file_indexer()
+    
+    print("\n9. Caching")
+    print("-" * 40)
+    example_caching()
+    
+    print("\n10. Context Manager")
+    print("-" * 40)
+    example_context_manager()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed!")

src/praisonai-agents/examples/mcp_server_example.py

@@ -0,0 +1,144 @@
+"""Example: Expose custom tools as MCP server.
+
+This example demonstrates how to create an MCP server that exposes
+custom Python functions as MCP tools. These tools can then be used
+by any MCP client (Claude Desktop, Cursor, etc.).
+
+Usage:
+    # Run as stdio server (for Claude Desktop, etc.)
+    python mcp_server_example.py
+    
+    # Run as SSE server (for web clients)
+    python mcp_server_example.py --sse --port 8080
+"""
+
+import argparse
+from typing import List, Dict, Any
+
+
+# Define your custom tools as regular Python functions
+# Type hints and docstrings are used to generate MCP schemas
+
+def search_web(query: str, max_results: int = 5) -> Dict[str, Any]:
+    """Search the web for information.
+    
+    Args:
+        query: The search query string
+        max_results: Maximum number of results to return (default: 5)
+    
+    Returns:
+        Search results with titles and URLs
+    """
+    # This is a mock implementation - replace with actual search logic
+    return {
+        "query": query,
+        "results": [
+            {"title": f"Result {i+1} for '{query}'", "url": f"https://example.com/{i+1}"}
+            for i in range(max_results)
+        ]
+    }
+
+
+def calculate(expression: str) -> Dict[str, Any]:
+    """Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2 * 3")
+    
+    Returns:
+        The result of the calculation
+    """
+    try:
+        # Safe evaluation of mathematical expressions
+        # In production, use a proper math parser
+        allowed_chars = set("0123456789+-*/.() ")
+        if not all(c in allowed_chars for c in expression):
+            return {"error": "Invalid characters in expression"}
+        
+        result = eval(expression)  # Note: Use safer alternative in production
+        return {"expression": expression, "result": result}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def get_weather(city: str, units: str = "celsius") -> Dict[str, Any]:
+    """Get current weather for a city.
+    
+    Args:
+        city: Name of the city
+        units: Temperature units - "celsius" or "fahrenheit" (default: celsius)
+    
+    Returns:
+        Weather information for the city
+    """
+    # Mock implementation - replace with actual weather API
+    return {
+        "city": city,
+        "temperature": 22 if units == "celsius" else 72,
+        "units": units,
+        "condition": "Sunny",
+        "humidity": 45
+    }
+
+
+def list_files(directory: str = ".", pattern: str = "*") -> List[str]:
+    """List files in a directory.
+    
+    Args:
+        directory: Directory path to list (default: current directory)
+        pattern: Glob pattern to filter files (default: *)
+    
+    Returns:
+        List of file names matching the pattern
+    """
+    import glob
+    import os
+    
+    try:
+        full_pattern = os.path.join(directory, pattern)
+        files = glob.glob(full_pattern)
+        return [os.path.basename(f) for f in files]
+    except Exception as e:
+        return [f"Error: {str(e)}"]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run PraisonAI Tools as MCP Server")
+    parser.add_argument("--sse", action="store_true", help="Use SSE transport instead of stdio")
+    parser.add_argument("--port", type=int, default=8080, help="Port for SSE server (default: 8080)")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host for SSE server")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args()
+    
+    # Import MCP server components
+    from praisonaiagents.mcp import ToolsMCPServer
+    
+    # Create server with custom name
+    server = ToolsMCPServer(
+        name="praisonai-custom-tools",
+        debug=args.debug
+    )
+    
+    # Register all tools
+    server.register_tools([
+        search_web,
+        calculate,
+        get_weather,
+        list_files
+    ])
+    
+    # Print registered tools
+    print(f"📦 Registered {len(server.tools)} tools:")
+    for name in server.get_tool_names():
+        print(f"   - {name}")
+    print()
+    
+    # Run the server
+    if args.sse:
+        server.run_sse(host=args.host, port=args.port)
+    else:
+        server.run_stdio()
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/examples/plugin_template/README.md

@@ -0,0 +1,94 @@
+# PraisonAI Example Plugin
+
+This is a template for creating tool plugins for PraisonAI Agents.
+
+## Installation
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Or install from PyPI (after publishing)
+pip install praisonai-example-plugin
+```
+
+## Usage
+
+After installation, tools are automatically discovered:
+
+```python
+from praisonaiagents import Agent
+
+# Use tools by name - they're auto-discovered!
+agent = Agent(
+    name="Assistant",
+    tools=["example_greet", "example_math", "example_reverse"]
+)
+
+# Or import and use directly
+from praisonai_example_plugin import GreetTool, MathTool, reverse_text
+
+agent = Agent(
+    name="Assistant", 
+    tools=[GreetTool(), MathTool(), reverse_text]
+)
+```
+
+## Creating Your Own Plugin
+
+1. **Copy this template**
+2. **Rename the package** in `pyproject.toml` and `src/` directory
+3. **Add your tools** following the patterns in `__init__.py`
+4. **Update entry_points** in `pyproject.toml` to register your tools
+
+### Tool Patterns
+
+**Class-based tool:**
+```python
+from praisonaiagents import BaseTool
+
+class MyTool(BaseTool):
+    name = "my_tool"
+    description = "What this tool does"
+    
+    def run(self, param: str) -> str:
+        return f"Result: {param}"
+```
+
+**Decorator-based tool:**
+```python
+from praisonaiagents import tool
+
+@tool
+def my_function(param: str) -> str:
+    """What this function does."""
+    return f"Result: {param}"
+```
+
+### Registering Tools
+
+In `pyproject.toml`:
+```toml
+[project.entry-points."praisonaiagents.tools"]
+my_tool = "my_package:MyTool"
+my_function = "my_package:my_function"
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

src/praisonai-agents/examples/plugin_template/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "praisonai-example-plugin"
+version = "1.0.0"
+description = "Example plugin for PraisonAI Agents - demonstrates tool plugin development"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Your Name", email = "[email protected]"}
+]
+keywords = ["praisonai", "agents", "tools", "plugin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "praisonaiagents>=0.0.168",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+]
+
+# This is the key part - register your tools as entry points
+# The format is: tool_name = "module.path:ClassName" or "module.path:function_name"
+[project.entry-points."praisonaiagents.tools"]
+example_greet = "praisonai_example_plugin:GreetTool"
+example_math = "praisonai_example_plugin:MathTool"
+example_reverse = "praisonai_example_plugin:reverse_text"
+
+[project.urls]
+Homepage = "https://github.com/yourusername/praisonai-example-plugin"
+Documentation = "https://github.com/yourusername/praisonai-example-plugin#readme"
+Repository = "https://github.com/yourusername/praisonai-example-plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/praisonai-agents/examples/plugin_template/src/praisonai_example_plugin/__init__.py

@@ -0,0 +1,119 @@
+"""PraisonAI Example Plugin - Demonstrates how to create tool plugins.
+
+This package shows how external developers can create pip-installable
+tool plugins for PraisonAI Agents.
+
+Usage after installation:
+    from praisonaiagents import Agent
+    
+    # Tools are auto-discovered via entry_points!
+    agent = Agent(tools=["example_greet", "example_math"])
+    
+    # Or import directly
+    from praisonai_example_plugin import GreetTool, MathTool
+    agent = Agent(tools=[GreetTool(), MathTool()])
+"""
+
+from typing import Dict, Any
+from praisonaiagents import BaseTool, tool
+
+
+# =============================================================================
+# Class-Based Tools
+# =============================================================================
+
+class GreetTool(BaseTool):
+    """A tool that generates personalized greetings.
+    
+    This demonstrates a simple class-based tool with multiple parameters.
+    """
+    name = "example_greet"
+    description = "Generate a personalized greeting message"
+    version = "1.0.0"
+    
+    def run(self, name: str, greeting: str = "Hello", punctuation: str = "!") -> str:
+        """Generate a greeting.
+        
+        Args:
+            name: The name of the person to greet
+            greeting: The greeting word (default: "Hello")
+            punctuation: End punctuation (default: "!")
+            
+        Returns:
+            A formatted greeting string
+        """
+        return f"{greeting}, {name}{punctuation}"
+
+
+class MathTool(BaseTool):
+    """A tool for basic mathematical operations.
+    
+    Demonstrates returning structured data from a tool.
+    """
+    name = "example_math"
+    description = "Perform basic math operations: add, subtract, multiply, divide"
+    version = "1.0.0"
+    
+    def run(
+        self,
+        a: float,
+        b: float,
+        operation: str = "add"
+    ) -> Dict[str, Any]:
+        """Perform a math operation.
+        
+        Args:
+            a: First number
+            b: Second number  
+            operation: One of 'add', 'subtract', 'multiply', 'divide'
+            
+        Returns:
+            Dict containing result and operation details
+        """
+        ops = {
+            "add": ("+", lambda x, y: x + y),
+            "subtract": ("-", lambda x, y: x - y),
+            "multiply": ("*", lambda x, y: x * y),
+            "divide": ("/", lambda x, y: x / y if y != 0 else float('inf')),
+        }
+        
+        if operation not in ops:
+            return {"error": f"Unknown operation: {operation}. Use: {list(ops.keys())}"}
+        
+        symbol, func = ops[operation]
+        result = func(a, b)
+        
+        return {
+            "result": result,
+            "expression": f"{a} {symbol} {b} = {result}",
+            "operation": operation
+        }
+
+
+# =============================================================================
+# Decorator-Based Tools
+# =============================================================================
+
+@tool(name="example_reverse", description="Reverse a string of text")
+def reverse_text(text: str) -> str:
+    """Reverse the input text.
+    
+    Args:
+        text: The text to reverse
+        
+    Returns:
+        The reversed text
+    """
+    return text[::-1]
+
+
+# =============================================================================
+# Package Exports
+# =============================================================================
+
+__version__ = "1.0.0"
+__all__ = [
+    "GreetTool",
+    "MathTool", 
+    "reverse_text",
+]

src/praisonai-agents/openai-multiturn.py

@@ -0,0 +1,8 @@
+from praisonaiagents import Agent
+
+agent = Agent(
+    instructions="You are a helpful assistant",
+    llm="gpt-5-nano"
+)
+agent.start("Why sky is Blue?")
+agent.start("What was my previous question?")

src/praisonai-agents/openai-run.py

@@ -0,0 +1,14 @@
+from praisonaiagents import Agent
+import asyncio
+
+agent = Agent(
+    instructions="You are a helpful assistant",
+    llm="gpt-5-nano"
+)
+agent.run("Why sea is Blue?")
+
+async def main():
+    await agent.arun("Why sky is Blue?")    
+    await agent.arun("What was my previous question?")
+
+asyncio.run(main())

src/praisonai-agents/openai-sequential.py

@@ -22,7 +22,7 @@ def multiply(a: int, b: int) -> int:
 
 agent = Agent(
     instructions="You are a helpful assistant. You can use the tools provided to you to help the user.",
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     tools=[get_stock_price, multiply]
 )
 

src/praisonai-agents/planning_example.py

@@ -0,0 +1,34 @@
+"""Simple Planning Mode Example: Plan first, then execute todo items."""
+
+from praisonaiagents import Agent
+from praisonaiagents.planning import PlanningAgent, TodoList
+
+# Step 1: Create agents
+researcher = Agent(name="Researcher", role="Research Analyst", verbose=True)
+writer = Agent(name="Writer", role="Content Writer", verbose=True)
+
+# Step 2: Create a plan using PlanningAgent
+planner = PlanningAgent(llm="gpt-4o-mini", verbose=1)
+plan = planner.create_plan_sync(
+    request="Write a short article about the top 3 benefits of meditation",
+    agents=[researcher, writer],
+    context="Keep it concise"
+)
+
+# Step 3: Create todo list from the plan
+todo = TodoList.from_plan(plan)
+
+# Step 4: Execute each todo item one by one
+for item in todo.items:
+    todo.start(item.id)
+    
+    # Pick the right agent based on the item's assigned agent
+    if item.agent == "Researcher":
+        agent = researcher
+    else:
+        agent = writer
+    
+    # Execute the task
+    result = agent.chat(item.description)
+    
+    todo.complete(item.id)

src/praisonai-agents/planning_simple.py

@@ -0,0 +1,21 @@
+"""Simplest Planning Mode Example - Just enable planning=True"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Create agents
+researcher = Agent(name="Researcher", role="Research Analyst")
+writer = Agent(name="Writer", role="Content Writer")
+
+# Create tasks
+task1 = Task(description="Research the benefits of meditation", agent=researcher)
+task2 = Task(description="Write a short article about meditation benefits", agent=writer)
+
+# Run with planning enabled - that's it!
+agents = PraisonAIAgents(
+    agents=[researcher, writer],
+    tasks=[task1, task2],
+    planning=True,
+    auto_approve_plan=True  # Auto-approve the generated plan
+)
+
+agents.start()

src/praisonai-agents/praisonai-openai.py

@@ -22,7 +22,7 @@ def multiply(a: int, b: int) -> int:
 
 agent = Agent(
     instructions="You are a helpful assistant. You can use the tools provided to you to help the user.",
-    llm="gpt-4o",
+    llm="gpt-5-nano",
     tools=[get_stock_price, multiply]
 )
 

src/praisonai-agents/praisonaiagents/__init__.py

@@ -15,9 +15,33 @@ _logging.configure_root_logger()
 from .agent.agent import Agent
 from .agent.image_agent import ImageAgent
 from .agent.context_agent import ContextAgent, create_context_agent
+from .agent.deep_research_agent import (
+    DeepResearchAgent,
+    DeepResearchResponse,
+    Citation,
+    ReasoningStep,
+    WebSearchCall,
+    CodeExecutionStep,
+    MCPCall,
+    FileSearchCall,
+    Provider
+)
+from .agent.query_rewriter_agent import (
+    QueryRewriterAgent,
+    RewriteStrategy,
+    RewriteResult
+)
+from .agent.prompt_expander_agent import (
+    PromptExpanderAgent,
+    ExpandStrategy,
+    ExpandResult
+)
 from .agents.agents import PraisonAIAgents
 from .task.task import Task
 from .tools.tools import Tools
+from .tools.base import BaseTool, ToolResult, ToolValidationError, validate_tool
+from .tools.decorator import tool, FunctionTool
+from .tools.registry import get_registry, register_tool, get_tool, ToolRegistry
 from .agents.autoagents import AutoAgents
 from .knowledge.knowledge import Knowledge
 from .knowledge.chunking import Chunking
@@ -30,7 +54,57 @@ except ImportError:
     MCP = None
 from .session import Session
 from .memory.memory import Memory
+# Workflows - import from dedicated workflows module
+from .workflows import (
+    Workflow, WorkflowStep, WorkflowContext, StepResult,
+    Route, Parallel, Loop, Repeat,
+    route, parallel, loop, repeat,
+    Pipeline  # Alias for Workflow
+)
 from .guardrails import GuardrailResult, LLMGuardrail
+
+# Fast Context support (lazy loaded to avoid performance impact)
+def __getattr__(name):
+    """Lazy load FastContext to avoid impacting package load time."""
+    if name == "FastContext":
+        from praisonaiagents.context.fast import FastContext
+        return FastContext
+    elif name == "FastContextResult":
+        from praisonaiagents.context.fast import FastContextResult
+        return FastContextResult
+    elif name == "FileMatch":
+        from praisonaiagents.context.fast import FileMatch
+        return FileMatch
+    elif name == "LineRange":
+        from praisonaiagents.context.fast import LineRange
+        return LineRange
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+# Planning mode support
+try:
+    from .planning import (
+        Plan,
+        PlanStep,
+        TodoList,
+        TodoItem,
+        PlanStorage,
+        PlanningAgent,
+        ApprovalCallback,
+        READ_ONLY_TOOLS,
+        RESTRICTED_TOOLS,
+    )
+    _planning_available = True
+except ImportError:
+    _planning_available = False
+    Plan = None
+    PlanStep = None
+    TodoList = None
+    TodoItem = None
+    PlanStorage = None
+    PlanningAgent = None
+    ApprovalCallback = None
+    READ_ONLY_TOOLS = []
+    RESTRICTED_TOOLS = []
 from .agent.handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 # Flow display
 try:
@@ -154,6 +228,17 @@ __all__ = [
     'Agents',
     'Tools',
     'Task',
+    # Plugin system
+    'BaseTool',
+    'ToolResult',
+    'ToolValidationError',
+    'validate_tool',
+    'tool',
+    'FunctionTool',
+    'ToolRegistry',
+    'get_registry',
+    'register_tool',
+    'get_tool',
     'TaskOutput',
     'ReflectionOutput',
     'AutoAgents',
@@ -186,7 +271,22 @@ __all__ = [
     'disable_performance_mode',
     'cleanup_telemetry_resources',
     'MinimalTelemetry',
-    'TelemetryCollector'
+    'TelemetryCollector',
+    'DeepResearchAgent',
+    'DeepResearchResponse',
+    'Citation',
+    'ReasoningStep',
+    'WebSearchCall',
+    'CodeExecutionStep',
+    'MCPCall',
+    'FileSearchCall',
+    'Provider',
+    'QueryRewriterAgent',
+    'RewriteStrategy',
+    'RewriteResult',
+    'PromptExpanderAgent',
+    'ExpandStrategy',
+    'ExpandResult'
 ]
 
 # Add MCP to __all__ if available
@@ -197,3 +297,11 @@ if _mcp_available:
 if FlowDisplay is not None:
     __all__.extend(['FlowDisplay', 'track_workflow'])
 
+# Add FastContext exports (lazy loaded)
+__all__.extend([
+    'FastContext',
+    'FastContextResult',
+    'FileMatch',
+    'LineRange'
+])
+

src/praisonai-agents/praisonaiagents/agent/__init__.py

@@ -4,5 +4,52 @@ from .image_agent import ImageAgent
 from .context_agent import ContextAgent, create_context_agent
 from .handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 from .router_agent import RouterAgent
+from .deep_research_agent import (
+    DeepResearchAgent,
+    DeepResearchResponse,
+    Citation,
+    ReasoningStep,
+    WebSearchCall,
+    CodeExecutionStep,
+    MCPCall,
+    FileSearchCall,
+    Provider
+)
+from .query_rewriter_agent import (
+    QueryRewriterAgent,
+    RewriteStrategy,
+    RewriteResult
+)
+from .prompt_expander_agent import (
+    PromptExpanderAgent,
+    ExpandStrategy,
+    ExpandResult
+)
 
-__all__ = ['Agent', 'ImageAgent', 'ContextAgent', 'create_context_agent', 'Handoff', 'handoff', 'handoff_filters', 'RECOMMENDED_PROMPT_PREFIX', 'prompt_with_handoff_instructions', 'RouterAgent']
+__all__ = [
+    'Agent',
+    'ImageAgent',
+    'ContextAgent',
+    'create_context_agent',
+    'Handoff',
+    'handoff',
+    'handoff_filters',
+    'RECOMMENDED_PROMPT_PREFIX',
+    'prompt_with_handoff_instructions',
+    'RouterAgent',
+    'DeepResearchAgent',
+    'DeepResearchResponse',
+    'Citation',
+    'ReasoningStep',
+    'WebSearchCall',
+    'CodeExecutionStep',
+    'MCPCall',
+    'FileSearchCall',
+    'Provider',
+    'QueryRewriterAgent',
+    'RewriteStrategy',
+    'RewriteResult',
+    'PromptExpanderAgent',
+    'ExpandStrategy',
+    'ExpandResult'
+]

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -234,7 +234,23 @@ class Agent:
         max_guardrail_retries: int = 3,
         handoffs: Optional[List[Union['Agent', 'Handoff']]] = None,
         base_url: Optional[str] = None,
-        api_key: Optional[str] = None
+        api_key: Optional[str] = None,
+        web_search: Optional[Union[bool, Dict[str, Any]]] = None,
+        web_fetch: Optional[Union[bool, Dict[str, Any]]] = None,
+        prompt_caching: Optional[bool] = None,
+        claude_memory: Optional[Union[bool, Any]] = None,
+        plan_mode: bool = False,
+        planning: bool = False,
+        planning_tools: Optional[List[Any]] = None,
+        planning_reasoning: bool = False,
+        fast_context: bool = False,
+        fast_context_path: Optional[str] = None,
+        fast_context_model: str = "gpt-4o-mini",
+        fast_context_max_turns: int = 4,
+        fast_context_parallelism: int = 8,
+        fast_context_timeout: float = 30.0,
+        history_in_context: Optional[int] = None,
+        auto_save: Optional[str] = None
     ):
         """Initialize an Agent instance.
 
@@ -250,8 +266,8 @@ class Agent:
             instructions (Optional[str], optional): Direct instructions that override role, goal,
                 and backstory when provided. Used for simple, task-specific agents. Defaults to None.
             llm (Optional[Union[str, Any]], optional): Language model configuration. Can be a model
-                name string (e.g., "gpt-4o", "anthropic/claude-3-sonnet") or a configured LLM object.
-                Defaults to environment variable OPENAI_MODEL_NAME or "gpt-4o".
+                name string (e.g., "gpt-5-nano", "anthropic/claude-3-sonnet") or a configured LLM object.
+                Defaults to environment variable OPENAI_MODEL_NAME or "gpt-5-nano".
             tools (Optional[List[Any]], optional): List of tools, functions, or capabilities
                 available to the agent for task execution. Can include callables, tool objects,
                 or MCP instances. Defaults to None.
@@ -395,12 +411,16 @@ class Agent:
                     self.llm_instance = LLM(**llm_config)
                 else:
                     # Create LLM with model string and base_url
-                    model_name = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o')
+                    model_name = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-5-nano')
                     self.llm_instance = LLM(
                         model=model_name,
                         base_url=base_url,
                         api_key=api_key,
-                        metrics=metrics
+                        metrics=metrics,
+                        web_search=web_search,
+                        web_fetch=web_fetch,
+                        prompt_caching=prompt_caching,
+                        claude_memory=claude_memory
                     )
                 self._using_custom_llm = True
             except ImportError as e:
@@ -435,6 +455,10 @@ class Agent:
                 if api_key:
                     llm_params['api_key'] = api_key
                 llm_params['metrics'] = metrics
+                llm_params['web_search'] = web_search
+                llm_params['web_fetch'] = web_fetch
+                llm_params['prompt_caching'] = prompt_caching
+                llm_params['claude_memory'] = claude_memory
                 self.llm_instance = LLM(**llm_params)
                 self._using_custom_llm = True
                 
@@ -450,11 +474,20 @@ class Agent:
                 ) from e
         # Otherwise, fall back to OpenAI environment/name
         else:
-            self.llm = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o')
+            self.llm = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-5-nano')
         # Handle tools parameter - ensure it's always a list
         if callable(tools):
             # If a single function/callable is passed, wrap it in a list
             self.tools = [tools]
+        elif isinstance(tools, str):
+            # Single tool name string - resolve from registry
+            self.tools = self._resolve_tool_names([tools])
+        elif isinstance(tools, (list, tuple)):
+            # Check if list contains strings (tool names) that need resolution
+            if tools and all(isinstance(t, str) for t in tools):
+                self.tools = self._resolve_tool_names(tools)
+            else:
+                self.tools = list(tools)
         else:
             # Handle all falsy values (None, False, 0, "", etc.) by defaulting to empty list
             self.tools = tools or []
@@ -462,7 +495,8 @@ class Agent:
         self.max_iter = max_iter
         self.max_rpm = max_rpm
         self.max_execution_time = max_execution_time
-        self.memory = memory
+        self._memory_instance = None
+        self._init_memory(memory, user_id)
         self.verbose = verbose
         self.allow_delegation = allow_delegation
         self.step_callback = step_callback
@@ -487,7 +521,7 @@ class Agent:
         self.min_reflect = min_reflect
         self.reflect_prompt = reflect_prompt
         # Use the same model selection logic for reflect_llm
-        self.reflect_llm = reflect_llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o')
+        self.reflect_llm = reflect_llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-5-nano')
         self._console = None  # Lazy load console when needed
         
         # Initialize system prompt
@@ -502,6 +536,36 @@ Your Goal: {self.goal}
         # Store user_id
         self.user_id = user_id or "praison"
         self.reasoning_steps = reasoning_steps
+        self.plan_mode = plan_mode  # Read-only mode for planning
+        self.planning = planning  # Enable planning mode
+        self.planning_tools = planning_tools  # Tools for planning phase
+        self.planning_reasoning = planning_reasoning  # Enable reasoning during planning
+        self._planning_agent = None  # Lazy loaded PlanningAgent
+        self.web_search = web_search
+        self.web_fetch = web_fetch
+        self.prompt_caching = prompt_caching
+        self.claude_memory = claude_memory
+        
+        # Session management
+        self.history_in_context = history_in_context  # Number of past sessions to include
+        self.auto_save = auto_save  # Session name for auto-saving
+        
+        # Initialize rules manager for persistent context (like Cursor/Windsurf)
+        self._rules_manager = None
+        self._init_rules_manager()
+        
+        # Handle web_search fallback: inject DuckDuckGo tool for unsupported models
+        if web_search and not self._model_supports_web_search():
+            from ..tools.duckduckgo_tools import internet_search
+            # Check if internet_search is not already in tools
+            tool_names = [getattr(t, '__name__', str(t)) for t in self.tools]
+            if 'internet_search' not in tool_names and 'duckduckgo' not in tool_names:
+                self.tools.append(internet_search)
+                logging.info("Model does not support native web search. Added DuckDuckGo fallback tool.")
+        
+        # Log warning if web_fetch is enabled but model doesn't support it
+        if web_fetch and not self._model_supports_web_fetch():
+            logging.warning(f"Model '{self.llm}' does not support native web fetch. Web fetch will be ignored.")
         
         # Initialize guardrail settings
         self.guardrail = guardrail
@@ -533,6 +597,15 @@ Your Goal: {self.goal}
             self._knowledge_config = knowledge_config
             self.knowledge = None  # Will be initialized on first use
 
+        # Fast Context configuration (lazy loaded)
+        self.fast_context_enabled = fast_context
+        self.fast_context_path = fast_context_path or os.getcwd()
+        self.fast_context_model = fast_context_model
+        self.fast_context_max_turns = fast_context_max_turns
+        self.fast_context_parallelism = fast_context_parallelism
+        self.fast_context_timeout = fast_context_timeout
+        self._fast_context_instance = None  # Lazy loaded
+
     @property
     def console(self):
         """Lazily initialize Rich Console only when needed."""
@@ -567,13 +640,352 @@ Your Goal: {self.goal}
             self._agent_id = str(uuid.uuid4())
         return self._agent_id
     
+    def get_available_tools(self) -> List[Any]:
+        """
+        Get tools available to this agent, filtered by plan_mode if enabled.
+        
+        In plan_mode, only read-only tools are available to prevent
+        modifications during the planning phase.
+        
+        Returns:
+            List of available tools
+        """
+        if not self.plan_mode:
+            return self.tools
+            
+        # Filter to read-only tools only
+        from ..planning import READ_ONLY_TOOLS, RESTRICTED_TOOLS
+        
+        filtered_tools = []
+        for tool in self.tools:
+            tool_name = getattr(tool, '__name__', str(tool)).lower()
+            
+            # Check if tool is in restricted list
+            is_restricted = any(
+                restricted.lower() in tool_name 
+                for restricted in RESTRICTED_TOOLS
+            )
+            
+            if not is_restricted:
+                filtered_tools.append(tool)
+                
+        return filtered_tools
+    
+    def _model_supports_web_search(self) -> bool:
+        """
+        Check if the agent's model supports native web search via LiteLLM.
+        
+        Returns:
+            bool: True if the model supports native web search, False otherwise
+        """
+        from ..llm.model_capabilities import supports_web_search
+        
+        # Get the model name
+        if hasattr(self, 'llm_instance') and self.llm_instance:
+            model_name = self.llm_instance.model
+        elif hasattr(self, 'llm') and self.llm:
+            model_name = self.llm
+        else:
+            model_name = "gpt-5-nano"
+        
+        return supports_web_search(model_name)
+    
+    def _model_supports_web_fetch(self) -> bool:
+        """
+        Check if the agent's model supports web fetch via LiteLLM.
+        
+        Web fetch allows the model to retrieve full content from specific URLs.
+        Currently only supported by Anthropic Claude models.
+        
+        Returns:
+            bool: True if the model supports web fetch, False otherwise
+        """
+        from ..llm.model_capabilities import supports_web_fetch
+        
+        # Get the model name
+        if hasattr(self, 'llm_instance') and self.llm_instance:
+            model_name = self.llm_instance.model
+        elif hasattr(self, 'llm') and self.llm:
+            model_name = self.llm
+        else:
+            model_name = "gpt-5-nano"
+        
+        return supports_web_fetch(model_name)
+    
+    def _model_supports_prompt_caching(self) -> bool:
+        """
+        Check if the agent's model supports prompt caching via LiteLLM.
+        
+        Prompt caching allows caching parts of prompts to reduce costs and latency.
+        Supported by OpenAI, Anthropic, Bedrock, and Deepseek.
+        
+        Returns:
+            bool: True if the model supports prompt caching, False otherwise
+        """
+        from ..llm.model_capabilities import supports_prompt_caching
+        
+        # Get the model name
+        if hasattr(self, 'llm_instance') and self.llm_instance:
+            model_name = self.llm_instance.model
+        elif hasattr(self, 'llm') and self.llm:
+            model_name = self.llm
+        else:
+            model_name = "gpt-4o-mini"
+        
+        return supports_prompt_caching(model_name)
+    
+    @property
+    def fast_context(self):
+        """Lazily initialize FastContext instance when needed.
+        
+        Returns:
+            FastContext instance or None if not enabled
+        """
+        if not self.fast_context_enabled:
+            return None
+        
+        if self._fast_context_instance is None:
+            try:
+                from ..context.fast import FastContext
+                self._fast_context_instance = FastContext(
+                    workspace_path=self.fast_context_path,
+                    model=self.fast_context_model,
+                    max_turns=self.fast_context_max_turns,
+                    max_parallel=self.fast_context_parallelism,
+                    timeout=self.fast_context_timeout,
+                    verbose=self.verbose
+                )
+            except ImportError:
+                logging.warning("FastContext not available")
+                return None
+        
+        return self._fast_context_instance
+    
+    def delegate_to_fast_context(self, query: str) -> Optional[str]:
+        """Delegate a code search query to FastContext subagent.
+        
+        This method uses the FastContext subagent to rapidly search
+        the codebase and return relevant context.
+        
+        Args:
+            query: Natural language search query
+            
+        Returns:
+            Formatted context string or None if FastContext not available
+        """
+        if not self.fast_context_enabled or self.fast_context is None:
+            return None
+        
+        try:
+            result = self.fast_context.search(query)
+            if result.total_files > 0:
+                return self.fast_context.get_context_for_agent(query)
+            return None
+        except Exception as e:
+            logging.warning(f"FastContext search failed: {e}")
+            return None
+    
+    def _init_rules_manager(self):
+        """
+        Initialize RulesManager for persistent rules/instructions.
+        
+        Automatically discovers rules from:
+        - ~/.praison/rules/ (global)
+        - .praison/rules/ (workspace)
+        - Subdirectory rules
+        """
+        try:
+            from ..memory.rules_manager import RulesManager
+            import os
+            
+            # Get workspace path (current working directory)
+            workspace_path = os.getcwd()
+            
+            self._rules_manager = RulesManager(
+                workspace_path=workspace_path,
+                verbose=1 if self.verbose else 0
+            )
+            
+            # Log discovered rules
+            stats = self._rules_manager.get_stats()
+            if stats["total_rules"] > 0:
+                logging.debug(f"RulesManager: Discovered {stats['total_rules']} rules")
+        except ImportError:
+            logging.debug("RulesManager not available")
+            self._rules_manager = None
+        except Exception as e:
+            logging.debug(f"Could not initialize RulesManager: {e}")
+            self._rules_manager = None
+    
+    def get_rules_context(self, file_path: Optional[str] = None, include_manual: Optional[List[str]] = None) -> str:
+        """
+        Get rules context for the current conversation.
+        
+        Args:
+            file_path: Optional file path for glob-based rule matching
+            include_manual: Optional list of manual rule names to include (via @mention)
+            
+        Returns:
+            Formatted rules context string
+        """
+        if not self._rules_manager:
+            return ""
+        
+        return self._rules_manager.build_rules_context(
+            file_path=file_path,
+            include_manual=include_manual
+        )
+    
+    def _init_memory(self, memory, user_id: Optional[str] = None):
+        """
+        Initialize memory based on the memory parameter.
+        
+        Args:
+            memory: Can be:
+                - True: Use FileMemory with default settings
+                - False/None: No memory
+                - "file": Use FileMemory
+                - "sqlite": Use existing Memory class with SQLite
+                - dict: Configuration for memory
+                - Memory/FileMemory instance: Use directly
+            user_id: User identifier for memory isolation
+        """
+        self.memory = memory
+        
+        if memory is None or memory is False:
+            self._memory_instance = None
+            return
+        
+        # Determine user_id
+        mem_user_id = user_id or getattr(self, 'user_id', None) or "default"
+        
+        if memory is True or memory == "file":
+            # Use FileMemory (zero dependencies)
+            from ..memory.file_memory import FileMemory
+            self._memory_instance = FileMemory(
+                user_id=mem_user_id,
+                verbose=1 if getattr(self, 'verbose', False) else 0
+            )
+        elif isinstance(memory, str) and memory in ("sqlite", "chromadb", "mem0", "mongodb"):
+            # Use full Memory class with specific provider
+            try:
+                from ..memory.memory import Memory
+                config = {"provider": memory if memory != "sqlite" else "rag"}
+                self._memory_instance = Memory(config)
+            except ImportError:
+                logging.warning(f"Memory provider '{memory}' requires additional dependencies. Falling back to FileMemory.")
+                from ..memory.file_memory import FileMemory
+                self._memory_instance = FileMemory(user_id=mem_user_id)
+        elif isinstance(memory, dict):
+            # Configuration dict
+            provider = memory.get("provider", "file")
+            if provider == "file":
+                from ..memory.file_memory import FileMemory
+                self._memory_instance = FileMemory(
+                    user_id=memory.get("user_id", mem_user_id),
+                    config=memory
+                )
+            else:
+                try:
+                    from ..memory.memory import Memory
+                    self._memory_instance = Memory(memory)
+                except ImportError:
+                    logging.warning("Full Memory class requires additional dependencies. Falling back to FileMemory.")
+                    from ..memory.file_memory import FileMemory
+                    self._memory_instance = FileMemory(user_id=mem_user_id)
+        else:
+            # Assume it's already a memory instance
+            self._memory_instance = memory
+    
+    def get_memory_context(self, query: Optional[str] = None) -> str:
+        """
+        Get memory context for the current conversation.
+        
+        Args:
+            query: Optional query to focus the context
+            
+        Returns:
+            Formatted memory context string
+        """
+        if not self._memory_instance:
+            return ""
+        
+        if hasattr(self._memory_instance, 'get_context'):
+            return self._memory_instance.get_context(query=query)
+        
+        return ""
+    
+    def store_memory(self, content: str, memory_type: str = "short_term", **kwargs):
+        """
+        Store content in memory.
+        
+        Args:
+            content: Content to store
+            memory_type: Type of memory (short_term, long_term, entity, episodic)
+            **kwargs: Additional arguments for the memory method
+        """
+        if not self._memory_instance:
+            return
+        
+        if memory_type == "short_term" and hasattr(self._memory_instance, 'add_short_term'):
+            self._memory_instance.add_short_term(content, **kwargs)
+        elif memory_type == "long_term" and hasattr(self._memory_instance, 'add_long_term'):
+            self._memory_instance.add_long_term(content, **kwargs)
+        elif memory_type == "entity" and hasattr(self._memory_instance, 'add_entity'):
+            self._memory_instance.add_entity(content, **kwargs)
+        elif memory_type == "episodic" and hasattr(self._memory_instance, 'add_episodic'):
+            self._memory_instance.add_episodic(content, **kwargs)
+    
+    def _display_memory_info(self):
+        """Display memory information to user in a friendly format."""
+        if not self._memory_instance:
+            return
+        
+        # Only display once per chat session
+        if hasattr(self, '_memory_displayed') and self._memory_displayed:
+            return
+        self._memory_displayed = True
+        
+        stats = self._memory_instance.get_stats()
+        short_count = stats.get('short_term_count', 0)
+        long_count = stats.get('long_term_count', 0)
+        entity_count = stats.get('entity_count', 0)
+        storage_path = stats.get('storage_path', '')
+        
+        total_memories = short_count + long_count + entity_count
+        
+        if total_memories > 0:
+            from rich.panel import Panel
+            from rich.text import Text
+            
+            # Build memory info text
+            info_parts = []
+            if long_count > 0:
+                info_parts.append(f"💾 {long_count} long-term")
+            if short_count > 0:
+                info_parts.append(f"⚡ {short_count} short-term")
+            if entity_count > 0:
+                info_parts.append(f"👤 {entity_count} entities")
+            
+            memory_text = Text()
+            memory_text.append("🧠 Memory loaded: ", style="bold cyan")
+            memory_text.append(" | ".join(info_parts))
+            memory_text.append(f"\n📁 Storage: {storage_path}", style="dim")
+            
+            self.console.print(Panel(
+                memory_text,
+                title="[bold]Agent Memory[/bold]",
+                border_style="cyan",
+                expand=False
+            ))
+    
     @property
     def llm_model(self):
         """Unified property to get the LLM model regardless of configuration type.
         
         Returns:
             The LLM model/instance being used by this agent.
-            - For standard models: returns the model string (e.g., "gpt-4o")
+            - For standard models: returns the model string (e.g., "gpt-5-nano")
             - For custom LLM instances: returns the LLM instance object
             - For provider models: returns the LLM instance object
         """
@@ -583,7 +995,7 @@ Your Goal: {self.goal}
             return self.llm
         else:
             # Default fallback
-            return "gpt-4o"
+            return "gpt-5-nano"
 
     def _ensure_knowledge_processed(self):
         """Ensure knowledge is initialized and processed when first accessed."""
@@ -813,17 +1225,35 @@ Your Goal: {self.goal}
         if not self.use_system_prompt:
             return None
         
-        # Check cache first
-        tools_key = self._get_tools_cache_key(tools)
-        cache_key = f"{self.role}:{self.goal}:{tools_key}"
-        
-        if cache_key in self._system_prompt_cache:
-            return self._system_prompt_cache[cache_key]
+        # Check cache first (skip cache if memory is enabled since context is dynamic)
+        if not self._memory_instance:
+            tools_key = self._get_tools_cache_key(tools)
+            cache_key = f"{self.role}:{self.goal}:{tools_key}"
+            
+            if cache_key in self._system_prompt_cache:
+                return self._system_prompt_cache[cache_key]
+        else:
+            cache_key = None  # Don't cache when memory is enabled
             
         system_prompt = f"""{self.backstory}\n
 Your Role: {self.role}\n
 Your Goal: {self.goal}"""
         
+        # Add rules context if rules manager is enabled
+        if self._rules_manager:
+            rules_context = self.get_rules_context()
+            if rules_context:
+                system_prompt += f"\n\n## Rules (Guidelines you must follow)\n{rules_context}"
+        
+        # Add memory context if memory is enabled
+        if self._memory_instance:
+            memory_context = self.get_memory_context()
+            if memory_context:
+                system_prompt += f"\n\n## Memory (Information you remember about the user)\n{memory_context}"
+                # Display memory info to user if verbose
+                if self.verbose:
+                    self._display_memory_info()
+        
         # Add tool usage instructions if tools are available
         # Use provided tools or fall back to self.tools
         tools_to_use = tools if tools is not None else self.tools
@@ -853,9 +1283,9 @@ Your Goal: {self.goal}"""
             if tool_names:
                 system_prompt += f"\n\nYou have access to the following tools: {', '.join(tool_names)}. Use these tools when appropriate to help complete your tasks. Always use tools when they can help provide accurate information or perform actions."
         
-        # Cache the generated system prompt
+        # Cache the generated system prompt (only if cache_key is set, i.e., memory not enabled)
         # Simple cache size limit to prevent unbounded growth
-        if len(self._system_prompt_cache) < self._max_cache_size:
+        if cache_key and len(self._system_prompt_cache) < self._max_cache_size:
             self._system_prompt_cache[cache_key] = system_prompt
         return system_prompt
 
@@ -1008,6 +1438,31 @@ Your Goal: {self.goal}"""
             tools=self.tools
         )
 
+    def _resolve_tool_names(self, tool_names):
+        """Resolve tool names to actual tool instances from registry.
+        
+        Args:
+            tool_names: List of tool name strings
+            
+        Returns:
+            List of resolved tool instances
+        """
+        resolved = []
+        try:
+            from ..tools.registry import get_registry
+            registry = get_registry()
+            
+            for name in tool_names:
+                tool = registry.get(name)
+                if tool is not None:
+                    resolved.append(tool)
+                else:
+                    logging.warning(f"Tool '{name}' not found in registry")
+        except ImportError:
+            logging.warning("Tool registry not available, cannot resolve tool names")
+        
+        return resolved
+
     def _cast_arguments(self, func, arguments):
         """Cast arguments to their expected types based on function signature."""
         if not callable(func) or not arguments:
@@ -1105,13 +1560,31 @@ Your Goal: {self.goal}"""
         # Try to find the function in the agent's tools list first
         func = None
         for tool in self.tools if isinstance(self.tools, (list, tuple)) else []:
+            # Check for BaseTool instances (plugin system)
+            from ..tools.base import BaseTool
+            if isinstance(tool, BaseTool) and tool.name == function_name:
+                func = tool
+                break
+            # Check for FunctionTool (decorated functions)
+            if hasattr(tool, 'name') and getattr(tool, 'name', None) == function_name:
+                func = tool
+                break
             if (callable(tool) and getattr(tool, '__name__', '') == function_name) or \
                (inspect.isclass(tool) and tool.__name__ == function_name):
                 func = tool
                 break
         
         if func is None:
-            # If not found in tools, try globals and main
+            # Check the global tool registry for plugins
+            try:
+                from ..tools.registry import get_registry
+                registry = get_registry()
+                func = registry.get(function_name)
+            except ImportError:
+                pass
+        
+        if func is None:
+            # If not found in tools or registry, try globals and main
             func = globals().get(function_name)
             if not func:
                 import __main__
@@ -1119,6 +1592,12 @@ Your Goal: {self.goal}"""
 
         if func:
             try:
+                # BaseTool instances (plugin system) - call run() method
+                from ..tools.base import BaseTool
+                if isinstance(func, BaseTool):
+                    casted_arguments = self._cast_arguments(func.run, arguments)
+                    return func.run(**casted_arguments)
+                
                 # Langchain: If it's a class with run but not _run, instantiate and call run
                 if inspect.isclass(func) and hasattr(func, 'run') and not hasattr(func, '_run'):
                     instance = func()
@@ -2082,27 +2561,199 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
             display_error(f"Error in _achat_completion: {e}")
             return None
 
+    async def arun(self, prompt: str, **kwargs):
+        """Async alias for astart() method"""
+        return await self.astart(prompt, **kwargs)
+
     async def astart(self, prompt: str, **kwargs):
         """Async version of start method"""
         return await self.achat(prompt, **kwargs)
 
-    def run(self):
+    def run(self, prompt: str, **kwargs):
         """Alias for start() method"""
-        return self.start() 
+        return self.start(prompt, **kwargs)
+    
+    def _get_planning_agent(self):
+        """Lazy load PlanningAgent for planning mode."""
+        if self._planning_agent is None and self.planning:
+            from ..planning import PlanningAgent
+            self._planning_agent = PlanningAgent(
+                llm=self.llm if hasattr(self, 'llm') else (self.llm_instance.model if hasattr(self, 'llm_instance') else "gpt-4o-mini"),
+                tools=self.planning_tools,
+                reasoning=self.planning_reasoning,
+                verbose=1 if self.verbose else 0
+            )
+        return self._planning_agent
+    
+    def _start_with_planning(self, prompt: str, **kwargs):
+        """Execute with planning mode - creates plan then executes each step."""
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.markdown import Markdown
+        
+        console = Console()
+        
+        # Step 1: Create the plan
+        console.print("\n[bold blue]📋 PLANNING PHASE[/bold blue]")
+        console.print("[dim]Creating implementation plan...[/dim]\n")
+        
+        planner = self._get_planning_agent()
+        plan = planner.create_plan_sync(request=prompt, agents=[self])
+        
+        if not plan or not plan.steps:
+            console.print("[yellow]⚠️ Planning failed, falling back to direct execution[/yellow]")
+            return self.chat(prompt, **kwargs)
+        
+        # Display the plan
+        console.print(Panel(
+            Markdown(plan.to_markdown()),
+            title="[bold green]Generated Plan[/bold green]",
+            border_style="green"
+        ))
+        
+        # Step 2: Execute each step
+        console.print("\n[bold blue]🚀 EXECUTION PHASE[/bold blue]\n")
+        
+        results = []
+        context = ""
+        
+        for i, step in enumerate(plan.steps):
+            progress = (i + 1) / len(plan.steps)
+            bar_length = 30
+            filled = int(bar_length * progress)
+            bar = "█" * filled + "░" * (bar_length - filled)
+            
+            console.print(f"[dim]Progress: [{bar}] {progress * 100:.0f}%[/dim]")
+            console.print(f"\n[bold]📌 Step {i + 1}/{len(plan.steps)}:[/bold] {step.description[:60]}...")
+            
+            # Build prompt with context from previous steps
+            step_prompt = step.description
+            if context:
+                step_prompt = f"{step.description}\n\nContext from previous steps:\n{context}"
+            
+            # Execute the step
+            result = self.chat(step_prompt, **kwargs)
+            results.append({"step": i + 1, "description": step.description, "result": result})
+            
+            # Update context for next step (use full result, not truncated)
+            context += f"\n\nStep {i + 1} result: {result if result else 'No result'}"
+            
+            console.print(f"   [green]✅ Completed[/green]")
+        
+        console.print(f"\n[bold green]🎉 EXECUTION COMPLETE[/bold green]")
+        console.print(f"[dim]Progress: [{'█' * bar_length}] 100%[/dim]")
+        console.print(f"Completed {len(plan.steps)}/{len(plan.steps)} steps!\n")
+        
+        # Compile all results into a comprehensive final output
+        if len(results) > 1:
+            # Create a compilation prompt
+            all_results_text = "\n\n".join([
+                f"## Step {r['step']}: {r['description']}\n\n{r['result']}" 
+                for r in results
+            ])
+            
+            compilation_prompt = f"""You are tasked with compiling a comprehensive, detailed report from the following research steps.
+
+IMPORTANT: Write a DETAILED and COMPREHENSIVE report. Do NOT summarize or compress the information. 
+Include ALL relevant details, data, statistics, and findings from each step.
+Organize the information logically with clear sections and subsections.
+
+## Research Results to Compile:
+
+{all_results_text}
+
+## Instructions:
+1. Combine all the information into a single, well-organized document
+2. Preserve ALL details, numbers, statistics, and specific findings
+3. Use clear headings and subheadings
+4. Do not omit any important information
+5. Make it comprehensive and detailed
+
+Write the complete compiled report:"""
+            
+            console.print("\n[bold blue]📝 COMPILING FINAL REPORT[/bold blue]")
+            console.print("[dim]Creating comprehensive output from all steps...[/dim]\n")
+            
+            final_result = self.chat(compilation_prompt, **kwargs)
+            return final_result
+        
+        # Return the single result if only one step
+        return results[0]["result"] if results else None
 
     def start(self, prompt: str, **kwargs):
         """Start the agent with a prompt. This is a convenience method that wraps chat()."""
-        # Check if streaming is enabled (either from kwargs or agent's stream attribute)
-        stream_enabled = kwargs.get('stream', getattr(self, 'stream', False))
+        # Load history from past sessions if history_in_context is set
+        self._load_history_context()
         
-        if stream_enabled:
+        # Check if planning mode is enabled
+        if self.planning:
+            result = self._start_with_planning(prompt, **kwargs)
+        elif kwargs.get('stream', getattr(self, 'stream', False)):
             # Return a generator for streaming response
-            return self._start_stream(prompt, **kwargs)
+            result = self._start_stream(prompt, **kwargs)
         else:
             # Return regular chat response for backward compatibility
-            # Explicitly pass the resolved stream parameter to avoid chat() method default
-            kwargs['stream'] = stream_enabled
-            return self.chat(prompt, **kwargs)
+            kwargs['stream'] = False
+            result = self.chat(prompt, **kwargs)
+        
+        # Auto-save session if enabled
+        self._auto_save_session()
+        
+        return result
+    
+    def _load_history_context(self):
+        """Load history from past sessions into context if history_in_context is set."""
+        if not self.history_in_context or not self._memory_instance:
+            return
+        
+        try:
+            sessions = self._memory_instance.list_sessions()
+            if not sessions:
+                return
+            
+            # Get the last N sessions
+            sessions_to_load = sessions[:self.history_in_context]
+            
+            for session_info in reversed(sessions_to_load):
+                try:
+                    session_data = self._memory_instance.resume_session(session_info["name"])
+                    history = session_data.get("conversation_history", [])
+                    
+                    # Add history to chat_history with a marker
+                    for msg in history:
+                        if msg not in self.chat_history:
+                            # Mark as from history to avoid duplication
+                            msg_copy = msg.copy()
+                            msg_copy["_from_history"] = True
+                            self.chat_history.append(msg_copy)
+                except Exception:
+                    continue
+                    
+            if sessions_to_load:
+                logging.debug(f"Loaded history from {len(sessions_to_load)} past session(s)")
+        except Exception as e:
+            logging.debug(f"Error loading history context: {e}")
+    
+    def _auto_save_session(self):
+        """Auto-save session if auto_save is enabled."""
+        if not self.auto_save or not self._memory_instance:
+            return
+        
+        try:
+            # Filter out history markers before saving
+            clean_history = [
+                {k: v for k, v in msg.items() if k != "_from_history"}
+                for msg in self.chat_history
+            ]
+            
+            self._memory_instance.save_session(
+                name=self.auto_save,
+                conversation_history=clean_history,
+                metadata={"agent_name": self.name, "user_id": self.user_id}
+            )
+            logging.debug(f"Auto-saved session: {self.auto_save}")
+        except Exception as e:
+            logging.debug(f"Error auto-saving session: {e}")
 
     def _start_stream(self, prompt: str, **kwargs) -> Generator[str, None, None]:
         """Stream generator for real-time response chunks."""