Release v2.4.4

- Check for @pytest.mark.integration marker
- Check if test file is in integration/ directory
- This prevents conftest from overriding real API keys with 'test-key'

.gitignore

@@ -77,4 +77,7 @@ agents/praisonaiagents/praisonaiagents.egg-info
 .qodo
 CopilotKit*
 .gemini
-issue_details.json
+issue_details.json
+
+# MCP Registry tokens
+.mcpregistry_*

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.3.30" \
+    "praisonai>=2.4.4" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

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

docker/Dockerfile.serve

@@ -0,0 +1,25 @@
+# Dockerfile for PraisonAI Serve API
+# Deploy to Railway, Render, Fly.io, or any container platform
+#
+# Build: docker build -f Dockerfile.serve -t praisonai-serve .
+# Run:   docker run -p 8005:8005 -e OPENAI_API_KEY=sk-xxx praisonai-serve
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+RUN pip install --no-cache-dir praisonai praisonaiagents
+
+# Copy agents configuration
+COPY agents.yaml .
+
+# Expose the API port
+EXPOSE 8005
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8005/health || exit 1
+
+# Start the API server
+CMD ["praisonai", "serve", "agents.yaml", "--host", "0.0.0.0", "--port", "8005"]

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.3.30" \
+    "praisonai>=2.4.4" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/README.md

@@ -0,0 +1,49 @@
+# PraisonAI Examples
+
+This folder contains examples for PraisonAI. For detailed documentation, visit [docs.praison.ai](https://docs.praison.ai).
+
+## Structure
+
+```
+examples/
+├── python/           # Python examples
+│   ├── agents/       # Agent examples (single, multi, router, etc.)
+│   ├── workflows/    # Workflow patterns (routing, parallel, loop)
+│   ├── tools/        # Custom tools examples
+│   ├── mcp/          # MCP protocol examples
+│   ├── memory/       # Memory and sessions
+│   ├── code/         # Code editing and external CLI tools
+│   └── ...
+├── yaml/             # YAML workflow examples
+└── cookbooks/        # Complete use-case examples
+```
+
+## Quick Links
+
+| Category | Examples | Docs |
+|----------|----------|------|
+| **Agents** | [python/agents/](python/agents/) | [📖](https://docs.praison.ai/concepts/agents) |
+| **Workflows** | [python/workflows/](python/workflows/) | [📖](https://docs.praison.ai/features/workflows) |
+| **Model Router** | [python/agents/router-agent-cost-optimization.py](python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/features/model-router) |
+| **MCP** | [python/mcp/](python/mcp/) | [📖](https://docs.praison.ai/mcp) |
+| **Memory** | [python/memory/](python/memory/) | [📖](https://docs.praison.ai/concepts/memory) |
+| **Tools** | [python/tools/](python/tools/) | [📖](https://docs.praison.ai/tools) |
+| **Code** | [python/code/](python/code/) | [📖](https://docs.praison.ai/code) |
+| **YAML** | [yaml/](yaml/) | [📖](https://docs.praison.ai/features/yaml-workflows) |
+
+## Running Examples
+
+```bash
+# Install PraisonAI
+pip install praisonai
+
+# Set API key
+export OPENAI_API_KEY=your_key_here
+
+# Run an example
+python examples/python/agents/single-agent.py
+```
+
+## CLI Commands
+
+See the main [README.md](../README.md#-cli--no-code-interface) for all CLI commands.

examples/background/basic_background.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Basic Background Tasks Example for PraisonAI Agents.
+
+This example demonstrates how to use the background task system to:
+1. Run tasks asynchronously
+2. Track task progress
+3. Cancel running tasks
+4. Handle task completion
+
+Usage:
+    python basic_background.py
+"""
+
+import asyncio
+import time
+
+from praisonaiagents.background import BackgroundRunner, BackgroundConfig, TaskStatus
+
+
+async def main():
+    print("=" * 60)
+    print("Background Tasks Demo")
+    print("=" * 60)
+    
+    # Create a background runner with config
+    config = BackgroundConfig(max_concurrent_tasks=3)
+    runner = BackgroundRunner(config=config)
+    
+    # Define some example tasks
+    def slow_task(duration: float, name: str) -> str:
+        """A slow task that simulates work."""
+        print(f"  🔄 Task '{name}' starting (will take {duration}s)")
+        time.sleep(duration)
+        return f"Task '{name}' completed after {duration}s"
+    
+    async def async_task(duration: float, name: str) -> str:
+        """An async task that simulates work."""
+        print(f"  🔄 Async task '{name}' starting (will take {duration}s)")
+        await asyncio.sleep(duration)
+        return f"Async task '{name}' completed after {duration}s"
+    
+    # Submit tasks
+    print("\n--- Submitting Tasks ---")
+    
+    task1 = await runner.submit(slow_task, args=(1.0, "quick-job"), name="task1")
+    print(f"✅ Submitted task 1: {task1.id[:8]}")
+    
+    task2 = await runner.submit(slow_task, args=(2.0, "medium-job"), name="task2")
+    print(f"✅ Submitted task 2: {task2.id[:8]}")
+    
+    task3 = await runner.submit(async_task, args=(1.5, "async-job"), name="task3")
+    print(f"✅ Submitted async task 3: {task3.id[:8]}")
+    
+    # List all tasks
+    print("\n--- Task Status ---")
+    for task in runner.tasks:
+        print(f"  [{task.id[:8]}] {task.status.value}")
+    
+    # Wait for task 1 to complete
+    print("\n--- Waiting for Task 1 ---")
+    await task1.wait(timeout=5.0)
+    print(f"✅ Task 1 result: {task1.result}")
+    
+    # Check status of all tasks
+    print("\n--- Updated Task Status ---")
+    for task in [task1, task2, task3]:
+        status = "✅" if task.status == TaskStatus.COMPLETED else "🔄"
+        print(f"  {status} [{task.id[:8]}] {task.status.value}")
+    
+    # Wait for all remaining tasks
+    print("\n--- Waiting for All Tasks ---")
+    await task2.wait(timeout=10.0)
+    await task3.wait(timeout=10.0)
+    
+    # Final status
+    print("\n--- Final Results ---")
+    for task in [task1, task2, task3]:
+        if task.result:
+            print(f"  ✅ {task.result}")
+    
+    # Cleanup
+    runner.clear_completed()
+    print("\n✅ Cleared completed tasks")
+    
+    print("\n" + "=" * 60)
+    print("Demo Complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/checkpoints/basic_checkpoints.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Basic Checkpoints Example for PraisonAI Agents.
+
+This example demonstrates how to use the shadow git checkpointing system to:
+1. Save checkpoints before making changes
+2. List available checkpoints
+3. View diffs between checkpoints
+4. Restore to a previous checkpoint
+
+Usage:
+    python basic_checkpoints.py
+"""
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from praisonaiagents.checkpoints import CheckpointService
+
+
+async def main():
+    # Create a temporary workspace for demonstration
+    with tempfile.TemporaryDirectory() as workspace:
+        print("=" * 60)
+        print("Shadow Git Checkpointing Demo")
+        print("=" * 60)
+        print(f"\nWorkspace: {workspace}")
+        
+        # Create some initial files
+        test_file = Path(workspace) / "example.py"
+        test_file.write_text("# Initial content\nprint('Hello, World!')\n")
+        print(f"\n✅ Created initial file: {test_file.name}")
+        
+        # Initialize the checkpoint service
+        service = CheckpointService(workspace_dir=workspace)
+        
+        try:
+            # Initialize the shadow git repository
+            print("\n--- Initializing Checkpoint Service ---")
+            await service.initialize()
+            print("✅ Shadow git repository initialized")
+            
+            # Save first checkpoint
+            print("\n--- Saving Checkpoint 1: Initial State ---")
+            result1 = await service.save("Initial state")
+            print(f"✅ Checkpoint saved: {result1.checkpoint.id[:8]}")
+            print(f"   Message: {result1.checkpoint.message}")
+            
+            # Make some changes
+            print("\n--- Making Changes ---")
+            test_file.write_text("# Modified content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
+            print("✅ Modified example.py")
+            
+            # Create a new file
+            new_file = Path(workspace) / "utils.py"
+            new_file.write_text("def helper():\n    return 'I help!'\n")
+            print("✅ Created utils.py")
+            
+            # Save second checkpoint
+            print("\n--- Saving Checkpoint 2: After Changes ---")
+            result2 = await service.save("Added features")
+            print(f"✅ Checkpoint saved: {result2.checkpoint.id[:8]}")
+            
+            # List all checkpoints
+            print("\n--- Listing All Checkpoints ---")
+            checkpoints = await service.list_checkpoints()
+            for i, cp in enumerate(checkpoints, 1):
+                print(f"  {i}. [{cp.id[:8]}] {cp.message} ({cp.timestamp})")
+            
+            # Show diff
+            print("\n--- Current Diff (uncommitted changes) ---")
+            diff = await service.diff()
+            if diff.files:
+                for f in diff.files:
+                    print(f"  {f.status}: {f.path}")
+            else:
+                print("  No uncommitted changes")
+            
+            # Make more changes to show diff
+            test_file.write_text("# Even more changes\nprint('This will be reverted')\n")
+            print("\n✅ Made more changes to example.py")
+            
+            diff = await service.diff()
+            print("\n--- New Diff ---")
+            if diff.files:
+                for f in diff.files:
+                    print(f"  {f.status}: {f.path}")
+            
+            # Restore to checkpoint 2
+            print(f"\n--- Restoring to Checkpoint: {result2.checkpoint.id[:8]} ---")
+            await service.restore(result2.checkpoint.id)
+            print("✅ Restored successfully!")
+            
+            # Verify restoration
+            content = test_file.read_text()
+            print(f"\n--- Verified Content After Restore ---")
+            print(content)
+            
+        except Exception as e:
+            print(f"\n❌ Error: {e}")
+            raise
+        
+        print("\n" + "=" * 60)
+        print("Demo Complete!")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/cli/persistence_commands.md

@@ -0,0 +1,93 @@
+# Persistence CLI Commands
+
+## Quick Reference
+
+```bash
+# Check database connectivity
+praisonai persistence doctor \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --state-url redis://localhost:6379
+
+# Run agent with persistence
+praisonai persistence run \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --session-id my-session
+
+# Resume a session
+praisonai persistence resume \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --session-id my-session
+
+# Export session to file
+praisonai persistence export \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --session-id my-session \
+  --output session_backup.jsonl
+
+# Import session from file
+praisonai persistence import \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --file session_backup.jsonl
+
+# Check schema status
+praisonai persistence status \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --state-url redis://localhost:6379
+
+# Apply migrations
+praisonai persistence migrate \
+  --conversation-url postgresql://localhost:5432/praisonai \
+  --state-url redis://localhost:6379
+```
+
+## Environment Variables
+
+Instead of CLI flags, you can use environment variables:
+
+```bash
+export PRAISON_CONVERSATION_URL=postgresql://localhost:5432/praisonai
+export PRAISON_STATE_URL=redis://localhost:6379
+export PRAISON_KNOWLEDGE_URL=http://localhost:6333
+
+# Then run without URL flags
+praisonai persistence doctor
+praisonai persistence status
+```
+
+## Docker Setup
+
+```bash
+# Start all services
+docker run -d --name praison-postgres \
+  -e POSTGRES_PASSWORD=praison123 \
+  -e POSTGRES_DB=praisonai \
+  -p 5432:5432 postgres:16
+
+docker run -d --name praison-redis \
+  -p 6379:6379 redis:7
+
+docker run -d --name praison-qdrant \
+  -p 6333:6333 -p 6334:6334 qdrant/qdrant
+
+# Verify
+docker ps
+```
+
+## Example Workflow
+
+```bash
+# 1. Start services
+docker-compose up -d
+
+# 2. Check connectivity
+praisonai persistence doctor
+
+# 3. Run agent
+praisonai persistence run --session-id demo-session
+
+# 4. Export for backup
+praisonai persistence export --session-id demo-session --output backup.jsonl
+
+# 5. Import to another environment
+praisonai persistence import --file backup.jsonl
+```

examples/cli/persistence_end_to_end.md

@@ -0,0 +1,124 @@
+# PraisonAI Persistence CLI - End-to-End Guide
+
+This guide demonstrates the CLI commands for database persistence.
+
+## Prerequisites
+
+```bash
+pip install "praisonai[tools]"
+
+# Start Docker containers
+docker run -d --name praison-postgres -p 5432:5432 \
+    -e POSTGRES_PASSWORD=praison123 \
+    -e POSTGRES_DB=praisonai \
+    postgres:16
+
+docker run -d --name praison-qdrant -p 6333:6333 qdrant/qdrant
+docker run -d --name praison-redis -p 6379:6379 redis:7
+```
+
+## 1. Doctor Command - Validate Connectivity
+
+```bash
+# Check all stores
+praisonai persistence doctor \
+    --conversation-url "postgresql://postgres:praison123@localhost:5432/praisonai" \
+    --knowledge-url "http://localhost:6333" \
+    --state-url "redis://localhost:6379"
+```
+
+**Expected Output:**
+```
+==================================================
+PraisonAI Persistence Doctor
+==================================================
+
+[Conversation Store] Testing: postgresql://postgres:****@localhost:5432/praisonai
+  ✅ Connected (postgres)
+
+[Knowledge Store] Testing: http://localhost:6333
+  ✅ Connected (qdrant)
+
+[State Store] Testing: redis://localhost:6379
+  ✅ Connected (redis)
+
+==================================================
+Results: 3/3 stores connected successfully
+==================================================
+```
+
+## 2. Run Command - Execute Agent with Persistence
+
+```bash
+# Run agent with persistence (dry-run first)
+praisonai persistence run \
+    --session-id "cli-demo-001" \
+    --conversation-url "postgresql://postgres:praison123@localhost:5432/praisonai" \
+    --dry-run \
+    "Hello, my name is Bob"
+
+# Actually run it
+praisonai persistence run \
+    --session-id "cli-demo-001" \
+    --conversation-url "postgresql://postgres:praison123@localhost:5432/praisonai" \
+    "Hello, my name is Bob"
+```
+
+**Expected Output:**
+```
+[Session: cli-demo-001]
+Agent: Hello Bob! Nice to meet you. How can I help you today?
+```
+
+## 3. Resume Command - Continue a Session
+
+```bash
+# Show history
+praisonai persistence resume \
+    --session-id "cli-demo-001" \
+    --conversation-url "postgresql://postgres:praison123@localhost:5432/praisonai" \
+    --show-history
+
+# Continue conversation
+praisonai persistence resume \
+    --session-id "cli-demo-001" \
+    --conversation-url "postgresql://postgres:praison123@localhost:5432/praisonai" \
+    --continue "What's my name?"
+```
+
+**Expected Output:**
+```
+[Session: cli-demo-001]
+Messages in history: 2
+
+--- Conversation History ---
+[USER] Hello, my name is Bob
+[ASSISTANT] Hello Bob! Nice to meet you...
+--- End History ---
+
+Agent: Your name is Bob!
+```
+
+## Environment Variables
+
+Instead of passing URLs on command line, use environment variables:
+
+```bash
+export PRAISON_CONVERSATION_URL="postgresql://postgres:praison123@localhost:5432/praisonai"
+export PRAISON_KNOWLEDGE_URL="http://localhost:6333"
+export PRAISON_STATE_URL="redis://localhost:6379"
+export OPENAI_API_KEY="your-key"
+
+# Now commands are simpler
+praisonai persistence doctor --all
+praisonai persistence run --session-id "my-session" "Hello!"
+```
+
+## Full CLI Reference
+
+```
+praisonai persistence --help
+praisonai persistence doctor --help
+praisonai persistence run --help
+praisonai persistence resume --help
+```

examples/compaction/basic_compaction.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Basic Context Compaction Example for PraisonAI Agents.
+
+This example demonstrates how to use context compaction to:
+1. Manage conversation context length
+2. Use different compaction strategies
+3. Track compaction results
+4. Preserve important messages
+
+Usage:
+    python basic_compaction.py
+"""
+
+from praisonaiagents.compaction import (
+    ContextCompactor, CompactionConfig, CompactionStrategy, CompactionResult
+)
+
+
+def main():
+    print("=" * 60)
+    print("Context Compaction Demo")
+    print("=" * 60)
+    
+    # ==========================================================================
+    # Sample Messages
+    # ==========================================================================
+    messages = [
+        {"role": "system", "content": "You are a helpful AI assistant."},
+        {"role": "user", "content": "Hello! Can you help me with Python?"},
+        {"role": "assistant", "content": "Of course! I'd be happy to help you with Python. What would you like to know?"},
+        {"role": "user", "content": "How do I read a file in Python?"},
+        {"role": "assistant", "content": "To read a file in Python, you can use the built-in open() function. Here's an example:\n\nwith open('filename.txt', 'r') as f:\n    content = f.read()\n\nThis opens the file, reads its content, and automatically closes it."},
+        {"role": "user", "content": "What about writing to a file?"},
+        {"role": "assistant", "content": "To write to a file, use the 'w' mode:\n\nwith open('filename.txt', 'w') as f:\n    f.write('Hello, World!')\n\nUse 'a' mode to append instead of overwriting."},
+        {"role": "user", "content": "Can you explain list comprehensions?"},
+        {"role": "assistant", "content": "List comprehensions are a concise way to create lists. Instead of:\n\nresult = []\nfor x in range(10):\n    result.append(x * 2)\n\nYou can write:\n\nresult = [x * 2 for x in range(10)]"},
+    ]
+    
+    print(f"\n--- Original Messages ---")
+    print(f"  Message count: {len(messages)}")
+    
+    # ==========================================================================
+    # Basic Compaction
+    # ==========================================================================
+    print("\n--- Basic Compaction (Truncate Strategy) ---")
+    
+    compactor = ContextCompactor(
+        max_tokens=50,  # Low limit to trigger compaction
+        strategy=CompactionStrategy.TRUNCATE,
+        preserve_system=True,
+        preserve_recent=2
+    )
+    
+    # Check stats before
+    stats = compactor.get_stats(messages)
+    print(f"  Total tokens: {stats['total_tokens']}")
+    print(f"  Max tokens: {stats['max_tokens']}")
+    print(f"  Needs compaction: {stats['needs_compaction']}")
+    
+    # Compact
+    compacted, result = compactor.compact(messages)
+    
+    print(f"\n  After compaction:")
+    print(f"    Messages: {len(messages)} -> {len(compacted)}")
+    print(f"    Tokens: {result.original_tokens} -> {result.compacted_tokens}")
+    print(f"    Saved: {result.tokens_saved} tokens")
+    print(f"    Compression: {result.compression_ratio:.1%}")
+    
+    # ==========================================================================
+    # Sliding Window Strategy
+    # ==========================================================================
+    print("\n--- Sliding Window Strategy ---")
+    
+    compactor = ContextCompactor(
+        max_tokens=50,
+        strategy=CompactionStrategy.SLIDING,
+        preserve_system=True,
+        preserve_recent=3
+    )
+    
+    compacted, result = compactor.compact(messages)
+    
+    print(f"  Messages kept: {result.messages_kept}")
+    print(f"  Messages removed: {result.messages_removed}")
+    print(f"  Strategy: {result.strategy_used.value}")
+    
+    # ==========================================================================
+    # Summarize Strategy
+    # ==========================================================================
+    print("\n--- Summarize Strategy ---")
+    
+    compactor = ContextCompactor(
+        max_tokens=50,
+        strategy=CompactionStrategy.SUMMARIZE,
+        preserve_system=True,
+        preserve_recent=2
+    )
+    
+    compacted, result = compactor.compact(messages)
+    
+    print(f"  Messages kept: {result.messages_kept}")
+    print(f"  Strategy: {result.strategy_used.value}")
+    
+    # Show what messages remain
+    print(f"\n  Remaining message roles:")
+    for msg in compacted:
+        role = msg.get("role", "unknown")
+        content_preview = msg.get("content", "")[:50]
+        print(f"    [{role}] {content_preview}...")
+    
+    # ==========================================================================
+    # No Compaction Needed
+    # ==========================================================================
+    print("\n--- No Compaction Needed ---")
+    
+    compactor = ContextCompactor(
+        max_tokens=10000,  # High limit
+        strategy=CompactionStrategy.TRUNCATE
+    )
+    
+    compacted, result = compactor.compact(messages)
+    
+    print(f"  Was compacted: {result.was_compacted}")
+    print(f"  Messages unchanged: {len(compacted) == len(messages)}")
+    
+    # ==========================================================================
+    # Result Serialization
+    # ==========================================================================
+    print("\n--- Result Serialization ---")
+    
+    compactor = ContextCompactor(max_tokens=50)
+    _, result = compactor.compact(messages)
+    
+    data = result.to_dict()
+    print(f"  Original tokens: {data['original_tokens']}")
+    print(f"  Compacted tokens: {data['compacted_tokens']}")
+    print(f"  Compression ratio: {data['compression_ratio']:.2f}")
+    
+    print("\n" + "=" * 60)
+    print("Demo Complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/compare/cli_compare_advanced.py

@@ -0,0 +1,85 @@
+"""
+CLI Compare Example - Advanced Usage
+
+This example demonstrates advanced comparison features including
+custom mode configurations and result analysis.
+"""
+
+from praisonai.cli.features.compare import (
+    CompareHandler,
+    CompareResult,
+    ModeResult,
+    get_mode_config,
+    save_compare_result,
+    format_comparison_table,
+)
+
+# Create custom mode configurations
+custom_modes = {
+    "fast": {"llm": "gpt-4o-mini"},
+    "accurate": {"llm": "gpt-4o", "planning": True},
+    "research": {"research": True, "web_search": True},
+}
+
+# Create handler with verbose output
+handler = CompareHandler(verbose=True)
+
+# Example: Manually create comparison results for analysis
+# (useful for testing without API calls)
+mock_result = CompareResult(
+    query="What are the latest AI trends?",
+    comparisons=[
+        ModeResult(
+            mode="basic",
+            output="AI trends include LLMs, multimodal models, and agents.",
+            execution_time_ms=1234.5,
+            model_used="gpt-4o-mini",
+            tools_used=[]
+        ),
+        ModeResult(
+            mode="tools",
+            output="Based on recent search results, AI trends in 2024 include...",
+            execution_time_ms=2567.8,
+            model_used="gpt-4o-mini",
+            tools_used=["internet_search"]
+        ),
+        ModeResult(
+            mode="research",
+            output="Comprehensive research shows that AI trends...",
+            execution_time_ms=5432.1,
+            model_used="gpt-4o-mini",
+            tools_used=["internet_search", "web_scraper"]
+        ),
+    ]
+)
+
+# Get summary statistics
+summary = mock_result.get_summary()
+print("Comparison Summary:")
+print(f"  Fastest mode: {summary['fastest']} ({summary['fastest_time_ms']:.1f}ms)")
+print(f"  Slowest mode: {summary['slowest']} ({summary['slowest_time_ms']:.1f}ms)")
+
+# Format as table
+print("\n" + format_comparison_table(mock_result))
+
+# Convert to JSON for storage
+print("\nJSON Output:")
+print(mock_result.to_json())
+
+# Save to file
+# save_compare_result(mock_result, "advanced_comparison.json")
+
+print("\n--- CLI Usage Examples ---")
+print("""
+# Basic comparison
+praisonai "What is AI?" --compare "basic,tools"
+
+# Compare with specific model
+praisonai "Explain quantum computing" --compare "basic,planning,research" --model gpt-4o
+
+# Save results to file
+praisonai "Latest tech news" --compare "basic,tools,web_search" --compare-output results.json
+
+# Verbose output
+praisonai "Write a poem" --compare "basic,planning" --verbose
+""")

examples/compare/cli_compare_basic.py

@@ -0,0 +1,45 @@
+"""
+CLI Compare Example - Basic Usage
+
+This example demonstrates how to compare different CLI modes programmatically.
+"""
+
+from praisonai.cli.features.compare import (
+    CompareHandler,
+    get_mode_config,
+    list_available_modes,
+    parse_modes,
+)
+
+# List all available comparison modes
+print("Available modes:")
+for mode in list_available_modes():
+    config = get_mode_config(mode)
+    print(f"  - {mode}: {config}")
+
+# Parse modes from comma-separated string
+modes = parse_modes("basic,tools,planning")
+print(f"\nParsed modes: {modes}")
+
+# Create compare handler
+handler = CompareHandler(verbose=True)
+
+# Compare modes (this will run actual agent calls)
+# Uncomment to run:
+# result = handler.compare(
+#     query="What is artificial intelligence?",
+#     modes=["basic", "tools"],
+#     model="gpt-4o-mini"
+# )
+# handler.print_result(result)
+
+# Save results to file
+# result = handler.execute(
+#     query="Explain machine learning",
+#     modes_str="basic,planning",
+#     output_path="comparison_results.json"
+# )
+
+print("\nTo run comparison via CLI:")
+print('  praisonai "What is AI?" --compare "basic,tools,planning"')
+print('  praisonai "What is AI?" --compare "basic,research" --compare-output results.json')

examples/cookbooks/yaml/data_collector_scheduled.yaml

@@ -0,0 +1,23 @@
+# Example: Data Collection Agent with 30-minute Schedule
+# Collects and analyzes data every 30 minutes
+
+framework: praisonai
+
+agents:
+  - name: "Data Collector"
+    role: "Data Analysis Specialist"
+    goal: "Collect and analyze market data at regular intervals"
+    instructions: |
+      You are a data analysis specialist focused on collecting and analyzing
+      market trends and metrics. Provide actionable insights from the data.
+    tools:
+      - search_tool
+    verbose: false
+
+task: "Collect latest market data and identify key trends"
+
+# Schedule: Every 30 minutes with immediate execution
+schedule:
+  interval: "*/30m"
+  max_retries: 5
+  run_immediately: true

examples/cookbooks/yaml/news_monitor_scheduled.yaml

@@ -0,0 +1,53 @@
+# Example: 24/7 AI News Monitor with Scheduler
+# This agent runs continuously at regular intervals to monitor AI news
+
+framework: praisonai
+
+agents:
+  - name: "AI News Monitor"
+    role: "Technology News Analyst"
+    goal: "Monitor and summarize the latest AI developments"
+    instructions: |
+      You are an expert technology news analyst specializing in AI and machine learning.
+      Your job is to search for the latest AI news, identify the most important developments,
+      and provide clear, concise summaries with sources.
+      
+      Focus on:
+      - Major AI product launches
+      - Research breakthroughs
+      - Industry trends
+      - Policy and regulation updates
+    tools:
+      - search_tool
+    verbose: true
+
+# Task to execute on each scheduled run
+task: |
+  Search for the latest AI news from the past 24 hours.
+  Provide the top 3 most important stories with:
+  1. Headline
+  2. Brief summary (2-3 sentences)
+  3. Source URL
+  4. Why it's significant
+
+# Schedule configuration
+schedule:
+  # Interval options:
+  # - "hourly" - Every hour
+  # - "daily" - Every 24 hours
+  # - "*/30m" - Every 30 minutes
+  # - "*/6h" - Every 6 hours
+  # - "3600" - Custom seconds
+  interval: "hourly"
+  
+  # Maximum retry attempts if execution fails
+  max_retries: 3
+  
+  # Run immediately when scheduler starts (before first scheduled interval)
+  run_immediately: true
+
+# Optional: Variables for customization
+variables:
+  news_category: "AI and Machine Learning"
+  region: "Global"
+  time_range: "24 hours"

examples/eval/accuracy_example.py

@@ -0,0 +1,69 @@
+"""
+Accuracy Evaluation Example
+
+This example demonstrates how to evaluate agent output accuracy
+by comparing against expected outputs using LLM-as-judge.
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.eval import AccuracyEvaluator
+
+# Check if we have an API key
+has_api_key = os.getenv("OPENAI_API_KEY") is not None
+
+if has_api_key:
+    # Create a simple math tutor agent
+    agent = Agent(
+        instructions="You are a math tutor. Answer math questions concisely with just the number."
+    )
+
+    # Create accuracy evaluator
+    evaluator = AccuracyEvaluator(
+        agent=agent,
+        input_text="What is 2 + 2?",
+        expected_output="4",
+        num_iterations=3,  # Run 3 times for statistical significance
+        verbose=True
+    )
+
+    # Run evaluation
+    result = evaluator.run(print_summary=True)
+
+    # Check results
+    print(f"\nAverage Score: {result.avg_score}/10")
+    print(f"Passed: {result.passed}")
+else:
+    print("⚠️  No OPENAI_API_KEY found. Using mock evaluation...")
+    
+    # Create evaluator without agent for mock testing
+    evaluator = AccuracyEvaluator(
+        func=lambda x: "4",  # Mock function
+        input_text="What is 2 + 2?",
+        expected_output="4",
+        num_iterations=1,
+        verbose=True
+    )
+    
+    # Test with mock output
+    try:
+        result = evaluator.run(print_summary=True)
+        print(f"\nMock Average Score: {result.avg_score}/10")
+        print(f"Mock Passed: {result.passed}")
+    except Exception as e:
+        print(f"Mock evaluation failed: {e}")
+        print("This is expected without an API key")
+
+# You can also evaluate pre-generated outputs
+print("\n--- Testing pre-generated output evaluation ---")
+output = "The answer is 4"
+
+if has_api_key:
+    try:
+        result2 = evaluator.evaluate_output(output, print_summary=True)
+        print(f"Pre-generated output score: {result2.avg_score}/10")
+    except Exception as e:
+        print(f"Pre-generated evaluation failed: {e}")
+else:
+    print("⚠️  Skipping pre-generated evaluation (no API key)")
+    print("To run full evaluation, set OPENAI_API_KEY environment variable")

examples/eval/batch_example.py

@@ -0,0 +1,105 @@
+"""
+Batch Evaluation Example
+
+This example demonstrates how to run batch evaluations
+from a JSON test file.
+"""
+
+import os
+import json
+import tempfile
+from praisonaiagents.eval import AccuracyEvaluator
+
+# Check if we have an API key
+has_api_key = os.getenv("OPENAI_API_KEY") is not None
+
+# Create a test file with multiple test cases
+test_cases = [
+    {
+        "input": "What is 2 + 2?",
+        "expected": "4"
+    },
+    {
+        "input": "What is the capital of France?",
+        "expected": "Paris"
+    },
+    {
+        "input": "What color is the sky?",
+        "expected": "Blue"
+    }
+]
+
+# Save test cases to a temporary file
+with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+    json.dump(test_cases, f)
+    test_file = f.name
+
+print(f"Test file created: {test_file}")
+print(f"Running {len(test_cases)} test cases...")
+
+if has_api_key:
+    # You can use the CLI for batch evaluation:
+    # praisonai eval batch --agent agents.yaml --test-file tests.json --batch-type accuracy
+
+    # Or programmatically:
+    from praisonaiagents import Agent
+
+    agent = Agent(
+        instructions="You are a helpful assistant. Answer questions concisely."
+    )
+
+    results = []
+    for i, test_case in enumerate(test_cases):
+        print(f"\nTest {i + 1}: {test_case['input']}")
+        
+        evaluator = AccuracyEvaluator(
+            agent=agent,
+            input_text=test_case["input"],
+            expected_output=test_case["expected"],
+            num_iterations=1
+        )
+        
+        result = evaluator.run()
+        results.append({
+            "input": test_case["input"],
+            "expected": test_case["expected"],
+            "score": result.avg_score,
+            "passed": result.passed
+        })
+        
+        print(f"  Score: {result.avg_score}/10")
+        print(f"  Passed: {result.passed}")
+
+    # Summary
+    passed = sum(1 for r in results if r["passed"])
+    print(f"\n{'='*50}")
+    print(f"Summary: {passed}/{len(results)} tests passed")
+    print(f"Pass Rate: {passed/len(results):.1%}")
+else:
+    print("⚠️  No OPENAI_API_KEY found. Running mock batch evaluation...")
+    
+    # Mock evaluation without API key
+    results = []
+    for i, test_case in enumerate(test_cases):
+        print(f"\nTest {i + 1}: {test_case['input']}")
+        
+        # Mock result (all would fail without API key)
+        mock_score = 0.0
+        mock_passed = False
+        
+        results.append({
+            "input": test_case["input"],
+            "expected": test_case["expected"],
+            "score": mock_score,
+            "passed": mock_passed
+        })
+        
+        print(f"  Score: {mock_score}/10 (mock)")
+        print(f"  Passed: {mock_passed} (expected without API key)")
+
+    # Summary
+    passed = sum(1 for r in results if r["passed"])
+    print(f"\n{'='*50}")
+    print(f"Summary: {passed}/{len(results)} tests passed (mock evaluation)")
+    print(f"Pass Rate: {passed/len(results):.1%}")
+    print("\nTo run real batch evaluation, set OPENAI_API_KEY environment variable")

examples/eval/criteria_example.py

@@ -0,0 +1,82 @@
+"""
+Criteria Evaluation Example
+
+This example demonstrates how to evaluate agent outputs
+against custom criteria using LLM-as-judge.
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.eval import CriteriaEvaluator
+
+# Check if we have an API key
+has_api_key = os.getenv("OPENAI_API_KEY") is not None
+
+if has_api_key:
+    print("--- Testing Criteria Evaluation with Agent ---")
+    # Create a customer service agent
+    agent = Agent(
+        instructions="You are a friendly customer service agent. Be helpful and empathetic."
+    )
+
+    # Create criteria evaluator with numeric scoring
+    evaluator = CriteriaEvaluator(
+        criteria="Response is helpful, empathetic, and provides a clear solution",
+        agent=agent,
+        input_text="I'm frustrated because my order hasn't arrived yet.",
+        scoring_type="numeric",  # Score 1-10
+        threshold=7.0,           # Pass if score >= 7
+        num_iterations=2,
+        verbose=True
+    )
+
+    # Run evaluation
+    result = evaluator.run(print_summary=True)
+
+    print("\nNumeric Scoring Results:")
+    print(f"  Average Score: {result.avg_score}/10")
+    print(f"  Pass Rate: {result.pass_rate:.1%}")
+    print(f"  Passed: {result.passed}")
+
+    # Binary scoring example (pass/fail)
+    print("\n--- Testing Binary Scoring ---")
+    binary_evaluator = CriteriaEvaluator(
+        criteria="Response does not contain any offensive language",
+        agent=agent,
+        input_text="Tell me a joke",
+        scoring_type="binary",  # Pass or Fail
+        verbose=True
+    )
+
+    binary_result = binary_evaluator.run(print_summary=True)
+    
+    # With on_fail callback
+    print("\n--- Testing Failure Callback ---")
+    def handle_failure(score):
+        print(f"ALERT: Evaluation failed with score {score.score}")
+        print(f"Reasoning: {score.reasoning}")
+
+    callback_evaluator = CriteriaEvaluator(
+        criteria="Response is professional and helpful",
+        agent=agent,
+        input_text="Help me",
+        on_fail=handle_failure,
+        threshold=8.0
+    )
+
+    callback_evaluator.run()
+else:
+    print("⚠️  No OPENAI_API_KEY found. Skipping agent-based criteria evaluation...")
+
+# Test pre-generated output evaluation (doesn't need agent)
+print("\n--- Testing Pre-generated Output Evaluation ---")
+if has_api_key:
+    output = "I understand your frustration. Let me check on your order right away."
+    try:
+        result2 = evaluator.evaluate_output(output, print_summary=True)
+        print(f"Pre-generated output score: {result2.avg_score}/10")
+    except Exception as e:
+        print(f"Pre-generated evaluation failed: {e}")
+else:
+    print("⚠️  Skipping pre-generated evaluation (no API key)")
+    print("To run full evaluation, set OPENAI_API_KEY environment variable")

examples/eval/performance_example.py

@@ -0,0 +1,59 @@
+"""
+Performance Evaluation Example
+
+This example demonstrates how to benchmark agent performance
+by measuring runtime and memory usage across multiple iterations.
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.eval import PerformanceEvaluator
+
+# Check if we have an API key
+has_api_key = os.getenv("OPENAI_API_KEY") is not None
+
+if has_api_key:
+    print("--- Testing Agent Performance ---")
+    # Create a simple agent
+    agent = Agent(
+        instructions="You are a helpful assistant. Answer questions briefly."
+    )
+
+    # Create performance evaluator
+    evaluator = PerformanceEvaluator(
+        agent=agent,
+        input_text="What is the capital of France?",
+        num_iterations=10,  # Run 10 benchmark iterations
+        warmup_runs=2,      # 2 warmup runs before measurement
+        track_memory=True,  # Track memory usage
+        verbose=True
+    )
+
+    # Run evaluation
+    result = evaluator.run(print_summary=True)
+
+    # Access detailed metrics
+    print("\nAgent Performance Results:")
+    print(f"  Average Time: {result.avg_run_time:.4f}s")
+    print(f"  Min Time: {result.min_run_time:.4f}s")
+    print(f"  Max Time: {result.max_run_time:.4f}s")
+    print(f"  Median Time: {result.median_run_time:.4f}s")
+    print(f"  P95 Time: {result.p95_run_time:.4f}s")
+    print(f"  Avg Memory: {result.avg_memory:.2f} MB")
+else:
+    print("⚠️  No OPENAI_API_KEY found. Skipping agent performance test...")
+
+# You can also benchmark any function
+def my_function():
+    import time
+    time.sleep(0.1)
+    return "done"
+
+func_evaluator = PerformanceEvaluator(
+    func=my_function,
+    num_iterations=5,
+    warmup_runs=1,
+    track_memory=False
+)
+
+func_result = func_evaluator.run(print_summary=True)

examples/eval/reliability_example.py

@@ -0,0 +1,72 @@
+"""
+Reliability Evaluation Example
+
+This example demonstrates how to verify that agents call
+the expected tools during execution.
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.eval import ReliabilityEvaluator
+
+
+def search_web(query: str) -> str:
+    """Search the web for information."""
+    return f"Search results for: {query}"
+
+
+def calculate(expression: str) -> str:
+    """Calculate a math expression."""
+    return str(eval(expression))
+
+
+# Check if we have an API key
+has_api_key = os.getenv("OPENAI_API_KEY") is not None
+
+if has_api_key:
+    print("--- Testing Agent Tool Call Reliability ---")
+    # Create an agent with tools
+    agent = Agent(
+        instructions="You are a helpful assistant with access to search and calculator tools.",
+        tools=[search_web, calculate]
+    )
+
+    # Create reliability evaluator
+    evaluator = ReliabilityEvaluator(
+        agent=agent,
+        input_text="Search for the weather in Paris and calculate 25 * 4",
+        expected_tools=["search_web", "calculate"],  # Tools that should be called
+        forbidden_tools=["delete_file"],  # Tools that should NOT be called
+        verbose=True
+    )
+
+    # Run evaluation
+    result = evaluator.run(print_summary=True)
+
+    # Check results
+    print("\nAgent Reliability Results:")
+    print(f"  Passed: {result.passed}")
+    print(f"  Pass Rate: {result.pass_rate:.1%}")
+else:
+    print("⚠️  No OPENAI_API_KEY found. Skipping agent reliability test...")
+    print("Agent would fail to call tools without API key (expected behavior)")
+
+# You can also evaluate pre-recorded tool calls (doesn't need API key)
+print("\n--- Testing Pre-recorded Tool Call Evaluation ---")
+# Create a mock agent for tool call evaluation
+mock_agent = Agent(instructions="Mock agent")
+evaluator = ReliabilityEvaluator(
+    agent=mock_agent,
+    expected_tools=["search_web", "calculate"],  # Tools that should be called
+    forbidden_tools=["delete_file"],  # Tools that should NOT be called
+    verbose=True
+)
+
+result2 = evaluator.evaluate_tool_calls(
+    actual_tools=["search_web", "calculate"],
+    print_summary=True
+)
+
+print("\nPre-recorded Tool Call Results:")
+print(f"  Passed: {result2.passed}")
+print(f"  Pass Rate: {result2.pass_rate:.1%}")

examples/hooks/basic_hooks.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+Basic Hooks Example for PraisonAI Agents.
+
+This example demonstrates how to use the hooks system to:
+1. Log tool calls before execution
+2. Block dangerous operations
+3. Add context to agent responses
+4. Monitor session lifecycle
+
+Usage:
+    python basic_hooks.py
+"""
+
+import asyncio
+from praisonaiagents import Agent
+from praisonaiagents.hooks import (
+    HookRegistry, HookRunner, HookEvent, HookResult,
+    BeforeToolInput, AfterToolInput
+)
+
+
+def main():
+    # Create a hook registry
+    registry = HookRegistry()
+    
+    # ==========================================================================
+    # Hook 1: Log all tool calls
+    # ==========================================================================
+    @registry.on(HookEvent.BEFORE_TOOL)
+    def log_tool_calls(event_data: BeforeToolInput) -> HookResult:
+        """Log every tool call before execution."""
+        print(f"\n📝 [LOG] Tool: {event_data.tool_name}")
+        print(f"   Input: {event_data.tool_input}")
+        return HookResult.allow()
+    
+    # ==========================================================================
+    # Hook 2: Block dangerous file operations (using function logic)
+    # ==========================================================================
+    @registry.on(HookEvent.BEFORE_TOOL)
+    def block_delete_operations(event_data: BeforeToolInput) -> HookResult:
+        """Block any delete or remove operations."""
+        dangerous_keywords = ['delete', 'remove', 'rm', 'unlink']
+        tool_lower = event_data.tool_name.lower()
+        
+        if any(kw in tool_lower for kw in dangerous_keywords):
+            print(f"\n🚫 [BLOCKED] Dangerous operation: {event_data.tool_name}")
+            return HookResult.deny(
+                f"Operation '{event_data.tool_name}' is blocked by security policy"
+            )
+        return HookResult.allow()
+    
+    # ==========================================================================
+    # Hook 3: Require confirmation for write operations
+    # ==========================================================================
+    @registry.on(HookEvent.BEFORE_TOOL)
+    def confirm_write_operations(event_data: BeforeToolInput) -> HookResult:
+        """Request confirmation for write operations."""
+        write_keywords = ['write', 'save', 'create', 'update']
+        tool_lower = event_data.tool_name.lower()
+        
+        if any(kw in tool_lower for kw in write_keywords):
+            print(f"\n⚠️  [CONFIRM] Write operation: {event_data.tool_name}")
+            # In a real scenario, you might prompt the user here
+            # For this example, we'll auto-approve
+            return HookResult.allow("Auto-approved for demo")
+        return HookResult.allow()
+    
+    # ==========================================================================
+    # Hook 4: Add timing information after tool execution
+    # ==========================================================================
+    @registry.on(HookEvent.AFTER_TOOL)
+    def log_tool_completion(event_data: AfterToolInput) -> HookResult:
+        """Log tool completion with timing."""
+        print(f"\n✅ [DONE] Tool: {event_data.tool_name}")
+        print(f"   Duration: {event_data.execution_time_ms:.2f}ms")
+        if event_data.tool_error:
+            print(f"   Error: {event_data.tool_error}")
+        return HookResult.allow()
+    
+    # ==========================================================================
+    # Test the hooks
+    # ==========================================================================
+    print("=" * 60)
+    print("Testing Hooks System")
+    print("=" * 60)
+    
+    runner = HookRunner(registry)
+    
+    # Test 1: Normal tool call (should be logged and allowed)
+    print("\n--- Test 1: Normal read operation ---")
+    input1 = BeforeToolInput(
+        session_id="test",
+        cwd="/tmp",
+        event_name="before_tool",
+        timestamp="2024-01-01T00:00:00",
+        tool_name="read_file",
+        tool_input={"path": "/tmp/test.txt"}
+    )
+    results = asyncio.run(runner.execute(HookEvent.BEFORE_TOOL, input1))
+    print(f"Result: {'ALLOWED' if not HookRunner.is_blocked(results) else 'BLOCKED'}")
+    
+    # Test 2: Delete operation (should be blocked)
+    print("\n--- Test 2: Delete operation ---")
+    input2 = BeforeToolInput(
+        session_id="test",
+        cwd="/tmp",
+        event_name="before_tool",
+        timestamp="2024-01-01T00:00:00",
+        tool_name="delete_file",
+        tool_input={"path": "/important/data.txt"}
+    )
+    results = asyncio.run(runner.execute(HookEvent.BEFORE_TOOL, input2))
+    print(f"Result: {'ALLOWED' if not HookRunner.is_blocked(results) else 'BLOCKED'}")
+    if HookRunner.is_blocked(results):
+        print(f"Reason: {HookRunner.get_blocking_reason(results)}")
+    
+    # Test 3: Write operation (should be confirmed)
+    print("\n--- Test 3: Write operation ---")
+    input3 = BeforeToolInput(
+        session_id="test",
+        cwd="/tmp",
+        event_name="before_tool",
+        timestamp="2024-01-01T00:00:00",
+        tool_name="write_file",
+        tool_input={"path": "/tmp/output.txt", "content": "Hello"}
+    )
+    results = asyncio.run(runner.execute(HookEvent.BEFORE_TOOL, input3))
+    print(f"Result: {'ALLOWED' if not HookRunner.is_blocked(results) else 'BLOCKED'}")
+    
+    # Show registered hooks
+    print("\n" + "=" * 60)
+    print("Registered Hooks:")
+    print("=" * 60)
+    for event, hooks in registry.list_hooks().items():
+        print(f"\n{event}:")
+        for hook in hooks:
+            print(f"  - {hook['name']} (matcher: {hook['matcher'] or '*'})")
+
+
+if __name__ == "__main__":
+    main()

examples/multi_agent/multi_agent_persistence.py

@@ -0,0 +1,122 @@
+"""
+Multi-Agent Persistence Example
+
+Demonstrates how multiple agents can share or isolate conversation
+history using the persistence layer.
+"""
+
+from praisonai.persistence.factory import create_conversation_store, create_state_store
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+import uuid
+
+
+def main():
+    # Create stores
+    conv_store = create_conversation_store("sqlite", path=":memory:")
+    state_store = create_state_store("memory")
+    
+    print("=== Multi-Agent Persistence Demo ===\n")
+    
+    # Scenario 1: Shared session (agents collaborate)
+    print("--- Scenario 1: Shared Session ---")
+    shared_session_id = f"shared-{uuid.uuid4().hex[:8]}"
+    
+    session = ConversationSession(
+        session_id=shared_session_id,
+        user_id="user-123",
+        name="Shared Conversation"
+    )
+    conv_store.create_session(session)
+    
+    # Agent 1 (Researcher) adds context
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant",
+        content="[Researcher] I found relevant information about the topic.",
+        metadata={"agent_id": "researcher", "agent_role": "research"}
+    ))
+    
+    # Agent 2 (Writer) uses the context
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant", 
+        content="[Writer] Based on the research, here's a summary...",
+        metadata={"agent_id": "writer", "agent_role": "writing"}
+    ))
+    
+    # Agent 3 (Editor) reviews
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant",
+        content="[Editor] I've reviewed and polished the content.",
+        metadata={"agent_id": "editor", "agent_role": "editing"}
+    ))
+    
+    messages = conv_store.get_messages(shared_session_id)
+    print(f"Shared session has {len(messages)} messages from different agents")
+    for msg in messages:
+        agent = msg.metadata.get("agent_id", "unknown") if msg.metadata else "unknown"
+        print(f"  - {agent}: {msg.content[:50]}...")
+    
+    # Scenario 2: Isolated sessions (agents work independently)
+    print("\n--- Scenario 2: Isolated Sessions ---")
+    
+    agent_sessions = {}
+    for agent_name in ["planner", "executor", "validator"]:
+        session_id = f"{agent_name}-{uuid.uuid4().hex[:8]}"
+        agent_sessions[agent_name] = session_id
+        
+        conv_store.create_session(ConversationSession(
+            session_id=session_id,
+            agent_id=agent_name,
+            name=f"{agent_name.title()} Session"
+        ))
+        
+        # Each agent has its own conversation
+        conv_store.add_message(session_id, ConversationMessage(
+            role="user",
+            content=f"Task for {agent_name}"
+        ))
+        conv_store.add_message(session_id, ConversationMessage(
+            role="assistant",
+            content=f"[{agent_name.title()}] Processing task..."
+        ))
+    
+    print("Created isolated sessions for each agent:")
+    for agent, sid in agent_sessions.items():
+        msgs = conv_store.get_messages(sid)
+        print(f"  - {agent}: {len(msgs)} messages")
+    
+    # Scenario 3: Shared state across agents
+    print("\n--- Scenario 3: Shared State ---")
+    
+    # Agents share state for coordination
+    state_store.set("workflow:status", {"phase": "research", "progress": 0})
+    state_store.set("workflow:context", {"topic": "AI Agents", "deadline": "2024-12-31"})
+    
+    # Agent 1 updates progress
+    state = state_store.get("workflow:status")
+    state["progress"] = 33
+    state["phase"] = "writing"
+    state_store.set("workflow:status", state)
+    print(f"Agent 1 updated state: {state}")
+    
+    # Agent 2 reads and updates
+    state = state_store.get("workflow:status")
+    state["progress"] = 66
+    state["phase"] = "editing"
+    state_store.set("workflow:status", state)
+    print(f"Agent 2 updated state: {state}")
+    
+    # Agent 3 completes
+    state = state_store.get("workflow:status")
+    state["progress"] = 100
+    state["phase"] = "complete"
+    state_store.set("workflow:status", state)
+    print(f"Agent 3 completed: {state}")
+    
+    # Cleanup
+    conv_store.close()
+    state_store.close()
+    print("\n✅ Multi-agent persistence demo complete!")
+
+
+if __name__ == "__main__":
+    main()

examples/multi_agent/shared_db_session.py

@@ -0,0 +1,40 @@
+"""Multi-Agent Shared Session - DB Persistence Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_conversation_store
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+# Create shared session for multiple agents
+store = create_conversation_store("sqlite", path="/tmp/multi_agent.db")
+session_id = "shared-session-123"
+
+# Create session
+session = ConversationSession(session_id=session_id, agent_id="multi")
+try:
+    store.create_session(session)
+except Exception:
+    pass
+
+# Agent 1 writes
+msg1 = ConversationMessage(session_id=session_id, role="user", content="Agent1: Hello")
+store.add_message(session_id, msg1)
+msg2 = ConversationMessage(session_id=session_id, role="assistant", content="Agent1: Hi there!")
+store.add_message(session_id, msg2)
+
+# Agent 2 writes to same session
+msg3 = ConversationMessage(session_id=session_id, role="user", content="Agent2: What did Agent1 say?")
+store.add_message(session_id, msg3)
+msg4 = ConversationMessage(session_id=session_id, role="assistant", content="Agent2: Agent1 said Hello")
+store.add_message(session_id, msg4)
+
+# Verify both agents' messages are in session
+messages = store.get_messages(session_id)
+print(f"Total messages in shared session: {len(messages)}")
+assert len(messages) >= 4, "Should have messages from both agents"
+
+# Verify content
+contents = [m.content for m in messages]
+assert any("Agent1" in c for c in contents), "Should have Agent1 messages"
+assert any("Agent2" in c for c in contents), "Should have Agent2 messages"
+
+print("PASSED: Multi-agent shared session persistence")

examples/multi_agent/shared_session_wow.py

@@ -0,0 +1,16 @@
+"""Multi-Agent Shared Session Demo"""
+from praisonaiagents import Agent
+from praisonai.persistence import create_conversation_store
+
+store = create_conversation_store("sqlite", path="/tmp/multi_agent.db")
+
+agent1 = Agent(name="Researcher", llm="gpt-4o-mini", db=store, session_id="shared-session")
+agent2 = Agent(name="Writer", llm="gpt-4o-mini", db=store, session_id="shared-session")
+
+r1 = agent1.chat("Research topic: AI in healthcare. Key finding: reduces diagnosis time by 50%")
+print(f"Researcher: {r1[:50]}...")
+
+r2 = agent2.chat("Based on the research, what was the key finding?")
+print(f"Writer: {r2[:50]}...")
+assert "50" in r2 or "diagnosis" in r2.lower(), "Writer should see Researcher's context"
+print("PASSED: Multi-agent shared session works")

examples/observability/basic_usage.py

@@ -0,0 +1,48 @@
+"""
+Basic Observability Usage Example
+
+This example demonstrates how to use the observability module
+with PraisonAI agents.
+
+Usage:
+    # Set your provider's API key first
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    
+    python basic_usage.py
+"""
+
+from praisonai_tools.observability import obs
+from praisonaiagents import Agent
+
+# Initialize observability (auto-detects provider from env vars)
+obs.init()
+
+# Or specify a provider explicitly
+# obs.init(provider="langfuse", project_name="my-project")
+
+# Create an agent
+agent = Agent(
+    instructions="You are a helpful assistant.",
+    model="gpt-4o-mini",
+)
+
+# Use trace context manager for complete workflow tracing
+with obs.trace("chat-session", session_id="user-123"):
+    # Use span context manager for individual operations
+    with obs.span("user-query", kind=obs.SpanKind.AGENT):
+        response = agent.chat("What is the capital of France?")
+        print(response)
+
+# Log LLM calls manually if needed
+obs.log_llm_call(
+    model="gpt-4o-mini",
+    input_messages="What is 2+2?",
+    output="4",
+    input_tokens=10,
+    output_tokens=1,
+)
+
+# Check diagnostics
+print("\nDiagnostics:")
+print(obs.doctor())

examples/observability/langfuse_example.py

@@ -0,0 +1,48 @@
+"""
+Langfuse Integration Example
+
+This example shows how to use Langfuse for LLM observability.
+
+Setup:
+    1. Sign up at https://langfuse.com/
+    2. Get your API keys from the project settings
+    3. Set environment variables:
+       export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+       export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    4. Install dependencies:
+       pip install opentelemetry-sdk opentelemetry-exporter-otlp
+
+Usage:
+    python langfuse_example.py
+"""
+
+import os
+from praisonai_tools.observability import obs
+from praisonaiagents import Agent
+
+# Initialize Langfuse
+success = obs.init(
+    provider="langfuse",
+    project_name="praisonai-demo",
+)
+
+if not success:
+    print("Failed to initialize Langfuse. Check your API keys.")
+    print("Required: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY")
+    exit(1)
+
+print("Langfuse initialized successfully!")
+print(f"View traces at: https://cloud.langfuse.com/")
+
+# Create agent
+agent = Agent(
+    instructions="You are a helpful coding assistant.",
+    model="gpt-4o-mini",
+)
+
+# Run with tracing
+with obs.trace("coding-session", user_id="developer-1"):
+    response = agent.chat("Write a Python function to calculate fibonacci numbers")
+    print(response)
+
+print("\nCheck Langfuse dashboard for traces!")

examples/observability/mlflow_local_wow.py

@@ -0,0 +1,22 @@
+"""MLflow Local Observability Demo (no API key needed)"""
+import mlflow
+import time
+
+mlflow.set_tracking_uri("file:///tmp/mlflow_demo")
+mlflow.set_experiment("praisonai-demo")
+
+with mlflow.start_run(run_name="agent-trace"):
+    mlflow.log_param("agent_name", "Assistant")
+    mlflow.log_param("model", "gpt-4o-mini")
+    
+    # Simulate agent work
+    start = time.time()
+    time.sleep(0.1)
+    latency = time.time() - start
+    
+    mlflow.log_metric("latency_ms", latency * 1000)
+    mlflow.log_metric("tokens_used", 150)
+    
+    print(f"Logged run to MLflow: latency={latency*1000:.1f}ms")
+
+print("PASSED: MLflow local observability works")

examples/observability/multi_agent_tracing.py

@@ -0,0 +1,53 @@
+"""
+Multi-Agent Tracing Example
+
+This example shows how to trace multi-agent workflows with
+parent/child span relationships.
+
+Usage:
+    # Set your provider's API key
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    
+    python multi_agent_tracing.py
+"""
+
+from praisonai_tools.observability import obs
+from praisonai_tools.observability.base import SpanKind
+from praisonaiagents import Agent, PraisonAIAgents
+
+# Initialize observability
+obs.init()
+
+# Create agents
+researcher = Agent(
+    name="Researcher",
+    instructions="You research topics and provide detailed information.",
+    model="gpt-4o-mini",
+)
+
+writer = Agent(
+    name="Writer", 
+    instructions="You write clear, engaging content based on research.",
+    model="gpt-4o-mini",
+)
+
+# Trace the multi-agent workflow
+with obs.trace("content-creation", metadata={"workflow": "research-write"}):
+    
+    # Research phase
+    with obs.span("research-phase", kind=SpanKind.AGENT) as research_span:
+        research_span.attributes["agent"] = "Researcher"
+        research_result = researcher.chat("Research the benefits of AI in healthcare")
+    
+    # Writing phase  
+    with obs.span("writing-phase", kind=SpanKind.AGENT) as write_span:
+        write_span.attributes["agent"] = "Writer"
+        write_span.attributes["input_length"] = len(str(research_result))
+        final_content = writer.chat(f"Write a blog post based on: {research_result}")
+
+print("Final Content:")
+print(final_content)
+
+# Check trace info
+print("\nDiagnostics:", obs.doctor())

examples/persistence/knowledge_qdrant.py

@@ -0,0 +1,79 @@
+"""
+Qdrant Knowledge Store Example for PraisonAI.
+
+Demonstrates vector insert + search through the knowledge store.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Docker Setup:
+    docker run -d --name praison-qdrant -p 6333:6333 qdrant/qdrant
+
+Run:
+    python knowledge_qdrant.py
+
+Expected Output:
+    === Qdrant Knowledge Store Demo ===
+    Created collection: demo_knowledge
+    Inserted 3 documents
+    Search results: 2 documents found
+"""
+
+from praisonai.persistence.factory import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+import random
+
+# Create Qdrant knowledge store
+store = create_knowledge_store("qdrant", url="http://localhost:6333")
+
+collection_name = "demo_knowledge"
+dimension = 384  # Embedding dimension
+
+# Create collection
+print("=== Qdrant Knowledge Store Demo ===")
+if store.collection_exists(collection_name):
+    store.delete_collection(collection_name)
+
+store.create_collection(collection_name, dimension=dimension)
+print(f"Created collection: {collection_name}")
+
+# Create sample documents with embeddings
+random.seed(42)
+documents = [
+    KnowledgeDocument(
+        id="doc-1",
+        content="Python is a versatile programming language used for web development, data science, and AI.",
+        embedding=[random.random() for _ in range(dimension)],
+        metadata={"category": "programming", "language": "python"}
+    ),
+    KnowledgeDocument(
+        id="doc-2", 
+        content="Machine learning enables computers to learn patterns from data without explicit programming.",
+        embedding=[random.random() for _ in range(dimension)],
+        metadata={"category": "ai", "topic": "ml"}
+    ),
+    KnowledgeDocument(
+        id="doc-3",
+        content="PostgreSQL is a powerful open-source relational database system.",
+        embedding=[random.random() for _ in range(dimension)],
+        metadata={"category": "database", "type": "sql"}
+    ),
+]
+
+# Insert documents
+ids = store.insert(collection_name, documents)
+print(f"Inserted {len(ids)} documents")
+
+# Search for similar documents
+query_embedding = [random.random() for _ in range(dimension)]
+results = store.search(collection_name, query_embedding, limit=2)
+print(f"Search results: {len(results)} documents found")
+
+for doc in results:
+    print(f"  - {doc.id}: {doc.content[:50]}...")
+
+# Cleanup
+store.delete_collection(collection_name)
+store.close()
+
+print("\n=== Demo Complete ===")

examples/persistence/minimal_agent_db.py

@@ -0,0 +1,43 @@
+"""
+Minimal Agent with Database Persistence
+
+This is the simplest way to add persistence to your agent.
+Messages, runs, and traces are automatically saved.
+
+Run:
+    python minimal_agent_db.py
+
+Expected output:
+    - Agent responds to your question
+    - Data is persisted to PostgreSQL
+    - Session can be resumed later with same session_id
+"""
+
+from praisonaiagents import Agent, db
+
+# Create database connection (PostgreSQL + Redis)
+my_db = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai",
+    state_url="redis://localhost:6379"  # Optional: for state/tracing
+)
+
+# Create agent with persistence
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant. Be concise.",
+    db=my_db,
+    # session_id is optional - defaults to per-hour ID (YYYYMMDDHH-hash)
+    # Set explicitly for session continuity across runs:
+    session_id="my-persistent-session"
+)
+
+# Chat - messages are automatically persisted
+response = agent.chat("What is the capital of France?")
+print(f"Response: {response}")
+
+# Verify persistence
+data = my_db.export_session("my-persistent-session")
+print(f"\nMessages stored: {len(data.get('messages', []))}")
+
+# Clean up
+my_db.close()

examples/persistence/postgres_runs_traces.py

@@ -0,0 +1,61 @@
+"""
+PostgreSQL with Runs and Traces
+
+Demonstrates full persistence with run tracking and tracing.
+
+Run:
+    python postgres_runs_traces.py
+
+Expected output:
+    - Agent responds with tool usage
+    - Runs and traces are persisted
+    - Export shows full session data
+"""
+
+from praisonaiagents import Agent, db
+
+def get_weather(city: str) -> str:
+    """Get weather for a city."""
+    return f"Weather in {city}: Sunny, 72°F"
+
+# Create database with PostgreSQL + Redis
+my_db = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai",
+    state_url="redis://localhost:6379"
+)
+
+# Create agent with tools
+agent = Agent(
+    name="WeatherBot",
+    instructions="You help with weather. Use the get_weather tool when asked.",
+    tools=[get_weather],
+    db=my_db,
+    session_id="weather-session-001"
+)
+
+# First chat - triggers run tracking
+print("=== First Question ===")
+response1 = agent.chat("What's the weather in Tokyo?")
+print(f"Response: {response1}\n")
+
+# Second chat - same session, new run
+print("=== Second Question ===")
+response2 = agent.chat("How about New York?")
+print(f"Response: {response2}\n")
+
+# Export session data
+print("=== Session Data ===")
+data = my_db.export_session("weather-session-001")
+print(f"Session ID: {data.get('session_id')}")
+print(f"Messages: {len(data.get('messages', []))}")
+print(f"Agent: {data.get('agent_name')}")
+
+# Show messages
+print("\n=== Messages ===")
+for msg in data.get('messages', []):
+    role = msg.get('role', 'unknown')
+    content = msg.get('content', '')[:60]
+    print(f"  [{role}] {content}...")
+
+my_db.close()
+print("\n✅ Done")

examples/persistence/redis_state.py

@@ -0,0 +1,83 @@
+"""
+Redis State Store
+
+Use Redis for state management, tracing, and caching.
+
+Run:
+    python redis_state.py
+
+Expected output:
+    - State operations (set/get/delete)
+    - Tracing operations
+"""
+
+from praisonaiagents import db
+
+# Create Redis-only database (for state/tracing)
+redis_db = db.RedisDB(host="localhost", port=6379)
+
+print("=== Redis State Store ===")
+
+# Test state operations
+print("\n1. State Operations:")
+redis_db._init_stores()  # Initialize stores
+
+# Set a value
+redis_db._state_store.set("user:123:preferences", {
+    "theme": "dark",
+    "language": "en"
+})
+print("   Set user preferences")
+
+# Get the value
+prefs = redis_db._state_store.get("user:123:preferences")
+print(f"   Got preferences: {prefs}")
+
+# Set with TTL (expires in 60 seconds)
+redis_db._state_store.set("temp:token", "abc123", ttl=60)
+print("   Set temporary token (60s TTL)")
+
+# Delete
+redis_db._state_store.delete("user:123:preferences")
+print("   Deleted preferences")
+
+# Test tracing
+print("\n2. Tracing Operations:")
+
+# Start a trace
+trace_id = "trace-example-001"
+redis_db.on_trace_start(
+    trace_id=trace_id,
+    session_id="example-session",
+    agent_name="ExampleAgent",
+    metadata={"purpose": "demo"}
+)
+print(f"   Started trace: {trace_id}")
+
+# Add spans
+span_id = "span-llm-001"
+redis_db.on_span_start(
+    span_id=span_id,
+    trace_id=trace_id,
+    name="llm_call",
+    attributes={"model": "gpt-4", "temperature": 0.7}
+)
+print(f"   Started span: {span_id}")
+
+redis_db.on_span_end(
+    span_id=span_id,
+    status="ok",
+    attributes={"tokens": 150, "latency_ms": 450}
+)
+print(f"   Ended span: {span_id}")
+
+# End trace
+redis_db.on_trace_end(
+    trace_id=trace_id,
+    status="ok",
+    metadata={"total_spans": 1}
+)
+print(f"   Ended trace: {trace_id}")
+
+redis_db.close()
+print("\n✅ Done")

examples/persistence/session_resume.py

@@ -0,0 +1,66 @@
+"""
+Session Resume Example
+
+Demonstrates how to resume a conversation from a previous session.
+
+Run:
+    python session_resume.py
+
+Expected output:
+    - First run: Creates new session
+    - Second run: Resumes with history
+"""
+
+from praisonaiagents import Agent, db
+
+# Create database
+my_db = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai",
+    state_url="redis://localhost:6379"
+)
+
+SESSION_ID = "resume-demo-session"
+
+# Create agent with explicit session_id
+agent = Agent(
+    name="MemoryBot",
+    instructions="You remember our conversation. Be helpful and concise.",
+    db=my_db,
+    session_id=SESSION_ID
+)
+
+# Check if this is a new or resumed session
+data = my_db.export_session(SESSION_ID)
+existing_messages = len(data.get('messages', []))
+
+if existing_messages == 0:
+    print("=== NEW SESSION ===")
+    print("This is a new conversation.\n")
+    
+    response = agent.chat("My name is Alice and I love Python programming.")
+    print(f"Response: {response}\n")
+    
+    response = agent.chat("What's my favorite programming language?")
+    print(f"Response: {response}\n")
+else:
+    print(f"=== RESUMED SESSION ({existing_messages} previous messages) ===")
+    print("Continuing previous conversation.\n")
+    
+    # Show previous messages
+    print("Previous messages:")
+    for msg in data.get('messages', [])[:4]:
+        role = msg.get('role', 'unknown')
+        content = msg.get('content', '')[:60]
+        print(f"  [{role}] {content}...")
+    print()
+    
+    # Continue conversation
+    response = agent.chat("What's my name and what do I like?")
+    print(f"Response: {response}\n")
+
+# Show final state
+final_data = my_db.export_session(SESSION_ID)
+print(f"Total messages now: {len(final_data.get('messages', []))}")
+
+my_db.close()
+print("✅ Done")

examples/persistence/simple_db_agent.py

@@ -0,0 +1,63 @@
+"""
+Simple Database Persistence Example for PraisonAI Agents.
+
+This example shows how to enable automatic conversation persistence
+with just 2 lines of code.
+
+Requirements:
+    pip install "praisonai[tools]"
+    
+Docker Setup:
+    docker run -d --name praison-postgres -p 5432:5432 \
+        -e POSTGRES_PASSWORD=praison123 \
+        -e POSTGRES_DB=praisonai \
+        postgres:16
+
+Environment:
+    export OPENAI_API_KEY=your-key
+
+Run:
+    python simple_agent_postgres.py
+
+Expected Output:
+    === First Run ===
+    Agent: Nice to meet you, Alice! Python is a great choice...
+    Session ID: demo-session-001
+    Messages persisted: 2
+"""
+
+from praisonaiagents import Agent
+from praisonai.db import PostgresDB
+
+# Create database adapter
+db = PostgresDB(
+    host="localhost",
+    port=5432,
+    database="praisonai",
+    user="postgres",
+    password="praison123"
+)
+
+# Create agent with persistence enabled
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant. Keep responses brief.",
+    db=db,
+    session_id="demo-session-001",  # Same session_id = resume conversation
+    verbose=False
+)
+
+# Chat with persistence
+print("=== First Run ===")
+response = agent.chat("My name is Alice and I love Python programming.")
+print(f"Agent: {response}\n")
+
+# Show session info
+print(f"Session ID: {agent.session_id}")
+print(f"Messages in history: {len(agent.chat_history)}")
+
+# Close DB connection
+db.close()
+
+print("\n=== Session persisted! ===")
+print("Run again with same session_id to resume.")

examples/persistence/sqlite_local.py

@@ -0,0 +1,41 @@
+"""
+SQLite Local Database
+
+Use SQLite for simple local persistence without external services.
+
+Run:
+    python sqlite_local.py
+
+Expected output:
+    - Agent responds
+    - Data persisted to local SQLite file
+"""
+
+from praisonaiagents import Agent, db
+import tempfile
+import os
+
+# Create SQLite database (local file)
+db_path = os.path.join(tempfile.gettempdir(), "my_agent.db")
+my_db = db.SQLiteDB(path=db_path)
+
+print(f"Database: {db_path}")
+
+# Create agent
+agent = Agent(
+    name="LocalBot",
+    instructions="You are a helpful assistant.",
+    db=my_db,
+    session_id="local-session"
+)
+
+# Chat
+response = agent.chat("Hello! What can you help me with?")
+print(f"Response: {response}")
+
+# Verify
+data = my_db.export_session("local-session")
+print(f"\nMessages stored: {len(data.get('messages', []))}")
+
+my_db.close()
+print("✅ Done")

examples/persistence/state_redis.py

@@ -0,0 +1,67 @@
+"""
+Redis State Store Example for PraisonAI.
+
+Demonstrates set/get/delete + TTL operations.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Docker Setup:
+    docker run -d --name praison-redis -p 6379:6379 redis:7
+
+Run:
+    python state_redis.py
+
+Expected Output:
+    === Redis State Store Demo ===
+    Set key: session:user123:preferences
+    Get value: {'theme': 'dark', 'language': 'en'}
+    TTL remaining: 3600 seconds
+    Hash operations: {'name': 'Alice', 'role': 'admin'}
+"""
+
+from praisonai.persistence.factory import create_state_store
+
+# Create Redis state store
+store = create_state_store("redis", url="redis://localhost:6379")
+
+print("=== Redis State Store Demo ===")
+
+# Basic set/get
+key = "session:user123:preferences"
+value = {"theme": "dark", "language": "en", "notifications": True}
+
+store.set(key, value)
+print(f"Set key: {key}")
+
+retrieved = store.get(key)
+print(f"Get value: {retrieved}")
+
+# Set with TTL (expires in 1 hour)
+ttl_key = "session:user123:token"
+store.set(ttl_key, "abc123xyz", ttl=3600)
+remaining = store.ttl(ttl_key)
+print(f"TTL remaining: {remaining} seconds")
+
+# Hash operations (for structured data)
+hash_key = "user:123:profile"
+store.hset(hash_key, "name", "Alice")
+store.hset(hash_key, "role", "admin")
+store.hset(hash_key, "last_login", "2024-12-24")
+
+profile = store.hgetall(hash_key)
+print(f"Hash operations: {profile}")
+
+# Check existence
+exists = store.exists(key)
+print(f"Key exists: {exists}")
+
+# Delete keys
+store.delete(key)
+store.delete(ttl_key)
+store.delete(hash_key)
+print("Cleaned up test keys")
+
+store.close()
+
+print("\n=== Demo Complete ===")

examples/policy/basic_policy.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+Basic Policy Engine Example for PraisonAI Agents.
+
+This example demonstrates how to use the policy engine to:
+1. Create policies with rules
+2. Check if actions are allowed
+3. Block dangerous operations
+4. Use convenience policy creators
+
+Usage:
+    python basic_policy.py
+"""
+
+from praisonaiagents.policy import (
+    PolicyEngine, Policy, PolicyRule, PolicyAction, PolicyConfig,
+    create_deny_tools_policy, create_read_only_policy
+)
+
+
+def main():
+    print("=" * 60)
+    print("Policy Engine Demo")
+    print("=" * 60)
+    
+    # Create a policy engine
+    engine = PolicyEngine()
+    
+    # ==========================================================================
+    # Policy 1: Block dangerous tools
+    # ==========================================================================
+    print("\n--- Creating Policies ---")
+    
+    dangerous_tools_policy = Policy(
+        name="block_dangerous",
+        description="Block dangerous file operations",
+        rules=[
+            PolicyRule(
+                action=PolicyAction.DENY,
+                resource="tool:delete_*",
+                reason="Delete operations are blocked",
+                name="deny_delete"
+            ),
+            PolicyRule(
+                action=PolicyAction.DENY,
+                resource="tool:rm_*",
+                reason="Remove operations are blocked",
+                name="deny_rm"
+            ),
+        ],
+        priority=100
+    )
+    engine.add_policy(dangerous_tools_policy)
+    print(f"✅ Added policy: {dangerous_tools_policy.name}")
+    
+    # ==========================================================================
+    # Policy 2: Allow read operations
+    # ==========================================================================
+    read_policy = Policy(
+        name="allow_read",
+        description="Allow read operations",
+        rules=[
+            PolicyRule(
+                action=PolicyAction.ALLOW,
+                resource="tool:read_*",
+                name="allow_read"
+            ),
+            PolicyRule(
+                action=PolicyAction.ALLOW,
+                resource="tool:list_*",
+                name="allow_list"
+            ),
+        ]
+    )
+    engine.add_policy(read_policy)
+    print(f"✅ Added policy: {read_policy.name}")
+    
+    # ==========================================================================
+    # Test policy checks
+    # ==========================================================================
+    print("\n--- Testing Policy Checks ---")
+    
+    test_cases = [
+        ("tool:read_file", "Reading a file"),
+        ("tool:list_directory", "Listing directory"),
+        ("tool:delete_file", "Deleting a file"),
+        ("tool:rm_directory", "Removing directory"),
+        ("tool:write_file", "Writing a file"),
+    ]
+    
+    for resource, description in test_cases:
+        result = engine.check(resource, {})
+        status = "✅ ALLOWED" if result.allowed else "🚫 DENIED"
+        reason = f" ({result.reason})" if result.reason else ""
+        print(f"  {status}: {description}{reason}")
+    
+    # ==========================================================================
+    # Using convenience functions
+    # ==========================================================================
+    print("\n--- Using Convenience Functions ---")
+    
+    # Create a read-only policy
+    read_only = create_read_only_policy()
+    print(f"✅ Created read-only policy with {len(read_only.rules)} rules")
+    
+    # Create a deny tools policy
+    deny_tools = create_deny_tools_policy(
+        ["execute_*", "shell_*", "system_*"],
+        reason="System commands are blocked"
+    )
+    print(f"✅ Created deny-tools policy with {len(deny_tools.rules)} rules")
+    
+    # ==========================================================================
+    # Strict mode example
+    # ==========================================================================
+    print("\n--- Strict Mode Example ---")
+    
+    strict_engine = PolicyEngine(PolicyConfig(strict_mode=True))
+    
+    # In strict mode, unknown resources are denied
+    result = strict_engine.check("tool:unknown_operation", {})
+    print(f"  Unknown operation in strict mode: {'DENIED' if not result.allowed else 'ALLOWED'}")
+    
+    # ==========================================================================
+    # Policy serialization
+    # ==========================================================================
+    print("\n--- Policy Serialization ---")
+    
+    policy_dict = dangerous_tools_policy.to_dict()
+    print(f"  Serialized policy: {policy_dict['name']} with {len(policy_dict['rules'])} rules")
+    
+    # Recreate from dict
+    restored = Policy.from_dict(policy_dict)
+    print(f"  Restored policy: {restored.name}")
+    
+    print("\n" + "=" * 60)
+    print("Demo Complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/python/a2a/a2a-server.py

@@ -0,0 +1,53 @@
+"""
+PraisonAI A2A Server Example
+
+Expose a PraisonAI Agent as an A2A (Agent2Agent) Server.
+This enables other AI agents to discover and communicate with your agent.
+
+Run:
+    uvicorn a2a-server:app --reload
+
+Endpoints:
+    GET /.well-known/agent.json  - Agent Card for discovery
+    GET /status                   - Server status
+"""
+
+from praisonaiagents import Agent, A2A
+from fastapi import FastAPI
+
+# Create an agent with tools
+def search_web(query: str) -> str:
+    """Search the web for information."""
+    return f"Search results for: {query}"
+
+def calculate(expression: str) -> str:
+    """Calculate a mathematical expression."""
+    try:
+        return f"Result: {eval(expression)}"
+    except Exception:
+        return "Invalid expression"
+
+agent = Agent(
+    name="Research Assistant",
+    role="Research Analyst",
+    goal="Help users research topics and answer questions",
+    tools=[search_web, calculate]
+)
+
+# Expose as A2A Server
+a2a = A2A(
+    agent=agent,
+    url="http://localhost:8000/a2a",
+    version="1.0.0"
+)
+
+# Create FastAPI app
+app = FastAPI(
+    title="PraisonAI A2A Server",
+    description="A2A-compatible agent server"
+)
+app.include_router(a2a.get_router())
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/python/agents/autoagents_workflow_patterns.py

@@ -0,0 +1,132 @@
+"""
+AutoAgents Workflow Patterns Example
+
+This example demonstrates the new workflow auto-generation features:
+- Dynamic agent count based on task complexity
+- Multiple workflow patterns (sequential, parallel, routing, orchestrator-workers, evaluator-optimizer)
+- Pattern recommendation based on task keywords
+
+Documentation: https://docs.praison.ai/features/autoagents
+CLI Reference: https://docs.praison.ai/nocode/auto
+"""
+
+from praisonai.auto import AutoGenerator, WorkflowAutoGenerator
+import os
+import tempfile
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+print("=" * 60)
+print("AutoAgents Workflow Patterns Demo")
+print("=" * 60)
+
+# =============================================================================
+# Example 1: Dynamic Agent Count (Simple vs Complex Tasks)
+# =============================================================================
+print("\n📊 Example 1: Dynamic Agent Count")
+print("-" * 40)
+
+# Simple task - should create 1-2 agents
+with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+    simple_file = f.name
+
+simple_generator = AutoGenerator(
+    topic="Write a haiku about spring",
+    agent_file=simple_file,
+    framework="praisonai"
+)
+
+print("Simple task: 'Write a haiku about spring'")
+result = simple_generator.generate()
+print(f"Generated: {result}")
+
+# Complex task - should create 3-4 agents
+with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+    complex_file = f.name
+
+complex_generator = AutoGenerator(
+    topic="Research AI trends, analyze market data, write a comprehensive report with executive summary",
+    agent_file=complex_file,
+    framework="praisonai"
+)
+
+print("\nComplex task: 'Research AI trends, analyze market data...'")
+result = complex_generator.generate()
+print(f"Generated: {result}")
+
+# =============================================================================
+# Example 2: Pattern Recommendation
+# =============================================================================
+print("\n🎯 Example 2: Pattern Recommendation")
+print("-" * 40)
+
+test_tasks = [
+    ("Write a blog post", "sequential"),
+    ("Research from multiple sources simultaneously", "parallel"),
+    ("Classify and route customer requests", "routing"),
+    ("Comprehensive analysis and break down the problem", "orchestrator-workers"),
+    ("Refine and improve content quality", "evaluator-optimizer"),
+]
+
+for task, expected in test_tasks:
+    generator = WorkflowAutoGenerator(topic=task)
+    recommended = generator.recommend_pattern()
+    status = "✅" if recommended == expected else "⚠️"
+    print(f"{status} Task: '{task[:40]}...'")
+    print(f"   Recommended: {recommended}")
+
+# =============================================================================
+# Example 3: Generate Workflow with Specific Pattern
+# =============================================================================
+print("\n🔄 Example 3: Generate Workflows with Patterns")
+print("-" * 40)
+
+patterns = ["sequential", "parallel", "orchestrator-workers", "evaluator-optimizer"]
+
+for pattern in patterns:
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        workflow_file = f.name
+    
+    generator = WorkflowAutoGenerator(
+        topic="Create a market analysis report",
+        workflow_file=workflow_file
+    )
+    
+    print(f"\n📋 Pattern: {pattern}")
+    result = generator.generate(pattern=pattern)
+    print(f"   Generated: {result}")
+    
+    # Read and show structure
+    import yaml
+    with open(result, 'r') as f:
+        data = yaml.safe_load(f)
+    print(f"   Agents: {list(data.get('agents', {}).keys())}")
+    print(f"   Steps: {len(data.get('steps', []))}")
+
+# =============================================================================
+# Example 4: CLI Usage (for reference)
+# =============================================================================
+print("\n💻 Example 4: CLI Commands (for reference)")
+print("-" * 40)
+print("""
+# Auto-generate agents (dynamic count)
+praisonai --auto "Write a haiku about spring"
+
+# Auto-generate workflow with pattern
+praisonai workflow auto "Research and write a report" --pattern sequential
+praisonai workflow auto "Research from multiple sources" --pattern parallel
+praisonai workflow auto "Comprehensive market analysis" --pattern orchestrator-workers
+praisonai workflow auto "Refine content quality" --pattern evaluator-optimizer
+
+# With output file
+praisonai workflow auto "Customer support routing" --pattern routing --output support.yaml
+""")
+
+print("\n" + "=" * 60)
+print("✅ AutoAgents Workflow Patterns Demo Complete!")
+print("=" * 60)
+print("\nDocumentation: https://docs.praison.ai/features/autoagents")
+print("CLI Reference: https://docs.praison.ai/nocode/auto")

examples/python/cli/autonomy_modes_example.py

@@ -0,0 +1,38 @@
+"""
+Autonomy Modes Example for PraisonAI CLI.
+
+Control AI autonomy: suggest, auto_edit, full_auto.
+Docs: https://docs.praison.ai/cli/autonomy-modes
+"""
+
+from praisonai.cli.features import AutonomyModeHandler
+from praisonai.cli.features.autonomy_mode import ActionRequest, ActionType
+
+# Initialize with suggest mode (safest)
+handler = AutonomyModeHandler()
+manager = handler.initialize(mode="suggest")
+
+print(f"Current mode: {handler.get_mode()}")
+print("Available modes: suggest, auto_edit, full_auto")
+
+# Create an action request
+action = ActionRequest(
+    action_type=ActionType.FILE_WRITE,
+    description="Edit src/main.py to add logging",
+    details={"file": "src/main.py"}
+)
+
+# In suggest mode, this would require approval
+# For demo, we'll just show the action
+print(f"\nAction: {action.description}")
+print(f"Type: {action.action_type.value}")
+print("Would require approval in 'suggest' mode")
+
+# Change to auto_edit mode
+handler.set_mode("auto_edit")
+print(f"\nChanged to: {handler.get_mode()}")
+print("File edits now auto-approved, shell commands still require approval")
+
+# Get statistics
+stats = handler.get_stats()
+print(f"\nStats: {stats}")

examples/python/cli/cost_tracking_example.py

@@ -0,0 +1,34 @@
+"""
+Cost Tracking Example for PraisonAI CLI.
+
+Real-time token usage and cost monitoring.
+Docs: https://docs.praison.ai/cli/cost-tracking
+"""
+
+from praisonai.cli.features import CostTrackerHandler
+
+# Initialize tracker
+handler = CostTrackerHandler()
+tracker = handler.initialize(session_id="demo-session")
+
+# Track some requests
+handler.track_request("gpt-4o", input_tokens=1000, output_tokens=500)
+handler.track_request("gpt-4o-mini", input_tokens=2000, output_tokens=800)
+handler.track_request("claude-3-5-sonnet", input_tokens=1500, output_tokens=600)
+
+# Get totals
+print(f"Total tokens: {handler.get_tokens():,}")
+print(f"Total cost: ${handler.get_cost():.4f}")
+
+# Get detailed summary
+summary = handler.get_summary()
+print("\n=== Session Summary ===")
+print(f"Session ID: {summary['session_id']}")
+print(f"Total requests: {summary['total_requests']}")
+print(f"Input tokens: {summary['total_input_tokens']:,}")
+print(f"Output tokens: {summary['total_output_tokens']:,}")
+print(f"Total cost: ${summary['total_cost']:.4f}")
+print(f"Avg cost/request: ${summary['avg_cost_per_request']:.4f}")
+
+# Display formatted (uses Rich if available)
+handler.display_summary()

examples/python/cli/git_integration_example.py

@@ -0,0 +1,45 @@
+"""
+Git Integration Example for PraisonAI CLI.
+
+Auto-commit with AI messages, diff viewing, undo.
+Docs: https://docs.praison.ai/cli/git-integration
+"""
+
+from praisonai.cli.features import GitIntegrationHandler
+
+# Initialize
+handler = GitIntegrationHandler(verbose=True)
+git = handler.initialize(repo_path=".")
+
+# Check if it's a git repo
+if not git.is_repo:
+    print("Not a git repository!")
+    exit(1)
+
+# Show status
+print("=== Git Status ===")
+status = handler.show_status()
+print(f"Branch: {status.branch}")
+print(f"Staged: {len(status.staged_files)}")
+print(f"Modified: {len(status.modified_files)}")
+print(f"Untracked: {len(status.untracked_files)}")
+
+# Show diff (if any changes)
+if status.has_changes:
+    print("\n=== Diff ===")
+    diff = handler.show_diff()
+    if diff:
+        print(diff[:300] + "..." if len(diff) > 300 else diff)
+
+# Show recent commits
+print("\n=== Recent Commits ===")
+commits = handler.show_log(count=5)
+for c in commits:
+    print(f"  {c.short_hash} {c.message[:50]}")
+
+# To commit with AI message:
+# commit = handler.commit()  # Auto-generates message
+# commit = handler.commit(message="Custom message")
+
+# To undo last commit:
+# handler.undo(soft=True)  # Keeps changes staged

examples/python/cli/interactive_tui_example.py

@@ -0,0 +1,49 @@
+"""
+Interactive TUI Example for PraisonAI CLI.
+
+Rich terminal interface with completions and history.
+Docs: https://docs.praison.ai/cli/interactive-tui
+"""
+
+from praisonai.cli.features import InteractiveTUIHandler
+from praisonai.cli.features.interactive_tui import InteractiveConfig
+
+# Custom configuration
+config = InteractiveConfig(
+    prompt="ai> ",
+    multiline=True,
+    enable_completions=True,
+    show_status_bar=True
+)
+
+# Define callbacks
+def on_input(text):
+    """Handle regular input."""
+    return f"You said: {text}"
+
+def on_command(cmd):
+    """Handle slash commands."""
+    if cmd == "/exit":
+        return {"type": "exit"}
+    return {"type": "command", "message": f"Executed: {cmd}"}
+
+# Initialize
+handler = InteractiveTUIHandler()
+session = handler.initialize(
+    config=config,
+    on_input=on_input,
+    on_command=on_command
+)
+
+# Add commands for completion
+session.add_commands(["help", "exit", "cost", "model", "plan"])
+
+# Add symbols from codebase
+session.add_symbols(["MyClass", "my_function"])
+
+print("Interactive TUI initialized!")
+print("Commands available: /help, /exit, /cost, /model, /plan")
+print("Run handler.run() to start interactive session")
+
+# Uncomment to run interactive session:
+# handler.run()

examples/python/cli/repo_map_example.py

@@ -0,0 +1,24 @@
+"""
+Repository Map Example for PraisonAI CLI.
+
+Intelligent codebase mapping with symbol extraction.
+Docs: https://docs.praison.ai/cli/repo-map
+"""
+
+from praisonai.cli.features import RepoMapHandler
+
+# Initialize with current directory
+handler = RepoMapHandler(verbose=True)
+repo_map = handler.initialize(root=".")
+
+# Get the repository map
+print("=== Repository Map ===")
+map_str = handler.get_map()
+print(map_str[:500] if len(map_str) > 500 else map_str)
+print("..." if len(map_str) > 500 else "")
+
+# Refresh after file changes
+handler.refresh()
+
+# Get symbols for a specific file (if exists)
+# symbols = handler.get_context("MyClass")

examples/python/cli/sandbox_execution_example.py

@@ -0,0 +1,42 @@
+"""
+Sandbox Execution Example for PraisonAI CLI.
+
+Secure isolated command execution (--sandbox flag).
+Docs: https://docs.praison.ai/cli/sandbox-execution
+"""
+
+from praisonai.cli.features import SandboxExecutorHandler
+from praisonai.cli.features.sandbox_executor import SandboxMode
+
+# Initialize with basic sandbox
+handler = SandboxExecutorHandler(verbose=True)
+sandbox = handler.initialize(mode="basic")
+
+print(f"Sandbox mode: {handler.get_mode()}")
+print(f"Sandbox enabled: {handler.is_enabled}")
+
+# Execute a safe command
+print("\n=== Safe Command ===")
+result = handler.execute("echo 'Hello from sandbox!'")
+print(f"Success: {result.success}")
+print(f"Output: {result.stdout.strip()}")
+print(f"Sandboxed: {result.was_sandboxed}")
+
+# Try a blocked command
+print("\n=== Blocked Command ===")
+result = handler.execute("rm -rf /")
+print(f"Success: {result.success}")
+print(f"Violations: {result.policy_violations}")
+
+# Validate command before execution
+print("\n=== Command Validation ===")
+violations = handler.validate_command("sudo apt install something")
+if violations:
+    print(f"Command blocked: {violations}")
+else:
+    print("Command allowed")
+
+# Available modes
+print("\n=== Available Modes ===")
+for mode in SandboxMode:
+    print(f"  {mode.value}")

examples/python/cli/slash_commands_example.py

@@ -0,0 +1,51 @@
+"""
+Slash Commands Example for PraisonAI CLI.
+
+Demonstrates interactive slash commands like /help, /cost, /model.
+Docs: https://docs.praison.ai/cli/slash-commands
+"""
+
+from praisonai.cli.features import SlashCommandHandler
+from praisonai.cli.features.slash_commands import SlashCommand, CommandKind
+
+# Create handler
+handler = SlashCommandHandler()
+
+# Execute commands
+print("=== /help ===")
+result = handler.execute("/help")
+print(result.get("message", ""))
+
+print("\n=== /cost ===")
+result = handler.execute("/cost")
+print(result.get("message", ""))
+
+print("\n=== /model ===")
+result = handler.execute("/model")
+print(result.get("message", ""))
+
+# Check if input is a command
+print("\n=== Command Detection ===")
+print(f"/help is command: {handler.is_command('/help')}")
+print(f"hello is command: {handler.is_command('hello')}")
+
+# Get completions for auto-complete
+print("\n=== Completions for '/he' ===")
+completions = handler.get_completions("/he")
+print(completions)
+
+# Register custom command
+def my_custom_handler(args, context):
+    return {"type": "custom", "message": f"Custom command with args: {args}"}
+
+custom_cmd = SlashCommand(
+    name="mycommand",
+    description="My custom command",
+    handler=my_custom_handler,
+    kind=CommandKind.ACTION,
+    aliases=["mc"]
+)
+
+handler.register(custom_cmd)
+result = handler.execute("/mycommand arg1 arg2")
+print(f"\n=== Custom Command ===\n{result.get('message', '')}")

examples/python/code/claude_code_example.py

@@ -0,0 +1,34 @@
+"""
+Claude Code CLI Integration Example
+
+Demonstrates how to use Claude Code CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import ClaudeCodeIntegration
+
+async def main():
+    # Create Claude Code integration
+    claude = ClaudeCodeIntegration(
+        workspace=".",
+        output_format="json",
+        skip_permissions=True,
+        system_prompt="Be concise and follow best practices",
+        allowed_tools=["Read", "Write", "Bash"]
+    )
+    
+    # Check availability
+    print(f"Claude CLI available: {claude.is_available}")
+    print(f"Claude SDK available: {claude.sdk_available}")
+    
+    # Execute a coding task
+    result = await claude.execute("List all Python files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream output
+    print("\nStreaming output:")
+    async for event in claude.stream("Explain the project structure"):
+        print(event)
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/code_editing_example.py

@@ -0,0 +1,60 @@
+"""
+Code Editing Tools Example
+
+Demonstrates how to use PraisonAI's code editing tools with SEARCH/REPLACE diffs.
+"""
+
+from praisonai.code import (
+    set_workspace,
+    code_read_file,
+    code_write_file,
+    code_apply_diff,
+    code_list_files,
+    code_execute_command,
+    CODE_TOOLS
+)
+
+# Set workspace
+set_workspace(".")
+
+# List files
+print("Files in current directory:")
+files = code_list_files(".", recursive=False)
+for f in files:
+    print(f"  {f}")
+
+# Read a file
+print("\nReading example file:")
+try:
+    content = code_read_file("README.md", start_line=1, end_line=10)
+    print(content)
+except Exception as e:
+    print(f"  File not found: {e}")
+
+# Write a file
+print("\nWriting test file:")
+code_write_file("test_output.txt", "Hello from PraisonAI Code Tools!")
+print("  Created test_output.txt")
+
+# Apply a diff
+print("\nApplying diff:")
+diff = """
+<<<<<<< SEARCH
+Hello from PraisonAI Code Tools!
+=======
+Hello from PraisonAI Code Tools!
+This line was added by a diff.
+>>>>>>> REPLACE
+"""
+result = code_apply_diff("test_output.txt", diff)
+print(f"  {result}")
+
+# Execute command
+print("\nExecuting command:")
+output = code_execute_command("cat test_output.txt")
+print(f"  {output}")
+
+# Cleanup
+import os
+os.remove("test_output.txt")
+print("\nCleanup complete.")

examples/python/code/codex_cli_example.py

@@ -0,0 +1,36 @@
+"""
+Codex CLI Integration Example
+
+Demonstrates how to use OpenAI Codex CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import CodexCLIIntegration
+
+async def main():
+    # Create Codex CLI integration
+    codex = CodexCLIIntegration(
+        workspace=".",
+        full_auto=True,
+        sandbox="danger-full-access",
+        json_output=True
+    )
+    
+    # Check availability
+    print(f"Codex CLI available: {codex.is_available}")
+    print(f"Full Auto: {codex.full_auto}")
+    print(f"Sandbox: {codex.sandbox}")
+    
+    # Execute a coding task
+    result = await codex.execute("List files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream JSON events
+    print("\nStreaming events:")
+    async for event in codex.stream("Explain the project"):
+        event_type = event.get("type", "")
+        if event_type == "item.completed":
+            print(f"  {event}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/cursor_cli_example.py

@@ -0,0 +1,37 @@
+"""
+Cursor CLI Integration Example
+
+Demonstrates how to use Cursor CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import CursorCLIIntegration
+
+async def main():
+    # Create Cursor CLI integration
+    cursor = CursorCLIIntegration(
+        workspace=".",
+        output_format="json",
+        force=True,
+        model="gpt-5",
+        stream_partial=True
+    )
+    
+    # Check availability
+    print(f"Cursor CLI available: {cursor.is_available}")
+    print(f"Force mode: {cursor.force}")
+    print(f"Model: {cursor.model}")
+    
+    # Execute a coding task
+    result = await cursor.execute("List files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream output
+    print("\nStreaming output:")
+    async for event in cursor.stream("Explain the project"):
+        content = event.get("content", "")
+        if content:
+            print(content, end="", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/external_agents_example.py

@@ -0,0 +1,58 @@
+"""
+External Agents Integration Example
+
+Demonstrates how to use all external CLI integrations as agent tools.
+"""
+
+import asyncio
+from praisonai.integrations import (
+    ClaudeCodeIntegration,
+    GeminiCLIIntegration,
+    CodexCLIIntegration,
+    CursorCLIIntegration,
+    get_available_integrations
+)
+
+async def main():
+    # Check availability of all integrations
+    print("=== External CLI Integrations ===\n")
+    
+    availability = get_available_integrations()
+    print("Availability:")
+    for name, avail in availability.items():
+        status = "✅" if avail else "❌"
+        print(f"  {status} {name}")
+    
+    # Create integrations
+    print("\n--- Claude Code ---")
+    claude = ClaudeCodeIntegration(workspace=".", skip_permissions=True)
+    print(f"CLI: {claude.cli_command}")
+    print(f"Available: {claude.is_available}")
+    tool = claude.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Gemini CLI ---")
+    gemini = GeminiCLIIntegration(workspace=".", model="gemini-2.5-flash")
+    print(f"CLI: {gemini.cli_command}")
+    print(f"Available: {gemini.is_available}")
+    tool = gemini.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Codex CLI ---")
+    codex = CodexCLIIntegration(workspace=".", full_auto=True)
+    print(f"CLI: {codex.cli_command}")
+    print(f"Available: {codex.is_available}")
+    tool = codex.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Cursor CLI ---")
+    cursor = CursorCLIIntegration(workspace=".", force=True)
+    print(f"CLI: {cursor.cli_command}")
+    print(f"Available: {cursor.is_available}")
+    tool = cursor.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n=== All integrations ready ===")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/gemini_cli_example.py

@@ -0,0 +1,33 @@
+"""
+Gemini CLI Integration Example
+
+Demonstrates how to use Gemini CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import GeminiCLIIntegration
+
+async def main():
+    # Create Gemini CLI integration
+    gemini = GeminiCLIIntegration(
+        workspace=".",
+        model="gemini-2.5-flash",
+        output_format="json",
+        include_directories=["../lib", "../docs"]
+    )
+    
+    # Check availability
+    print(f"Gemini CLI available: {gemini.is_available}")
+    print(f"Model: {gemini.model}")
+    
+    # Execute a coding task
+    result = await gemini.execute("Analyze the code structure")
+    print(f"Result: {result}")
+    
+    # Execute with stats
+    result, stats = await gemini.execute_with_stats("Explain main.py")
+    print(f"Result: {result}")
+    print(f"Stats: {stats}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/general/auto_agents_example.py

@@ -1,11 +1,48 @@
+"""
+AutoAgents Example
+
+AutoAgents automatically creates and manages AI agents based on high-level instructions.
+It features dynamic agent count based on task complexity.
+
+Documentation: https://docs.praison.ai/features/autoagents
+CLI Reference: https://docs.praison.ai/nocode/auto
+
+New Features:
+- Dynamic agent count (1-4 based on task complexity)
+- Workflow patterns: sequential, parallel, routing, orchestrator-workers, evaluator-optimizer
+- Pattern recommendation based on task keywords
+- Tool preservation from LLM suggestions
+"""
+
 from praisonaiagents import AutoAgents
 from praisonaiagents.tools import duckduckgo
 
+# Basic usage - AutoAgents analyzes complexity and creates optimal agents
 agents = AutoAgents(
     instructions="Search for information about AI Agents",
     tools=[duckduckgo],
-    process="sequential",
-    verbose=True
+    process="sequential",  # or "hierarchical"
+    verbose=True,
+    max_agents=3  # Maximum number of agents to create
 )
 
-agents.start()
+result = agents.start()
+print(result)
+
+# =============================================================================
+# CLI Usage Examples (for reference)
+# =============================================================================
+# 
+# # Auto-generate agents (dynamic count based on complexity)
+# praisonai --auto "Write a haiku about spring"
+# praisonai --auto "Research AI trends, analyze data, write report"
+#
+# # Auto-generate workflow with specific pattern
+# praisonai workflow auto "Research and write" --pattern sequential
+# praisonai workflow auto "Research from multiple sources" --pattern parallel
+# praisonai workflow auto "Comprehensive analysis" --pattern orchestrator-workers
+# praisonai workflow auto "Refine content quality" --pattern evaluator-optimizer
+#
+# # With framework selection
+# praisonai --framework crewai --auto "Create a movie script"
+# praisonai --framework autogen --auto "Create a movie script"

examples/python/scheduled_agents/news_checker_agent.py

@@ -0,0 +1,115 @@
+"""
+24/7 News Checker Agent Example
+
+This example demonstrates how to create a continuously running agent
+that checks for AI news every hour and prints the results.
+
+Usage:
+    python news_checker_agent.py
+    
+The agent will:
+1. Run immediately on start
+2. Check for latest AI news every 1 hour
+3. Print results to console
+4. Continue running until stopped (Ctrl+C)
+"""
+
+import os
+import sys
+from datetime import datetime
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../..'))
+
+from praisonaiagents import Agent
+from praisonai.agent_scheduler import AgentScheduler
+from tools import search_tool
+
+
+def on_success(result):
+    """Callback function called when agent execution succeeds."""
+    print("\n" + "="*80)
+    print(f"✅ SUCCESS - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("="*80)
+    print(result)
+    print("="*80 + "\n")
+
+
+def on_failure(error):
+    """Callback function called when agent execution fails."""
+    print("\n" + "="*80)
+    print(f"❌ FAILURE - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("="*80)
+    print(f"Error: {error}")
+    print("="*80 + "\n")
+
+
+def main():
+    """Main function to set up and run the scheduled news checker agent."""
+    
+    print("\n🤖 Starting 24/7 News Checker Agent")
+    print("="*80)
+    
+    # Create the agent with web search capability
+    agent = Agent(
+        name="NewsChecker",
+        role="AI News Monitor",
+        goal="Monitor and summarize the latest AI and technology news",
+        backstory="""You are an expert AI news analyst who stays up-to-date 
+        with the latest developments in artificial intelligence, machine learning, 
+        and technology. You provide concise, accurate summaries of important news.""",
+        tools=[search_tool],
+        verbose=True
+    )
+    
+    # Define the task
+    task = """Search for the latest AI news from today. 
+    Focus on major developments, breakthroughs, or announcements.
+    Provide a summary of the top 3-5 most important news items.
+    Include the source and key details for each item."""
+    
+    # Create scheduler with callbacks
+    scheduler = AgentScheduler(
+        agent=agent,
+        task=task,
+        on_success=on_success,
+        on_failure=on_failure
+    )
+    
+    print(f"Agent: {agent.name}")
+    print(f"Task: {task}")
+    print(f"Schedule: Every 1 hour")
+    print("="*80)
+    print("\n⏰ Starting scheduler... (Press Ctrl+C to stop)\n")
+    
+    # Start the scheduler
+    # - "hourly" or "*/1h" = every 1 hour
+    # - run_immediately=True = run once before starting the schedule
+    scheduler.start(
+        schedule_expr="hourly",  # Run every hour
+        max_retries=3,           # Retry up to 3 times on failure
+        run_immediately=True     # Run immediately on start
+    )
+    
+    try:
+        # Keep the main thread alive
+        while scheduler.is_running:
+            import time
+            time.sleep(1)
+            
+    except KeyboardInterrupt:
+        print("\n\n🛑 Stopping scheduler...")
+        scheduler.stop()
+        
+        # Print final statistics
+        stats = scheduler.get_stats()
+        print("\n📊 Final Statistics:")
+        print(f"  Total Executions: {stats['total_executions']}")
+        print(f"  Successful: {stats['successful_executions']}")
+        print(f"  Failed: {stats['failed_executions']}")
+        print(f"  Success Rate: {stats['success_rate']:.1f}%")
+        print("\n✅ Agent stopped successfully\n")
+
+
+if __name__ == "__main__":
+    main()

examples/python/scheduled_agents/news_checker_live.py

@@ -0,0 +1,143 @@
+"""
+Live News Checker Agent - 24/7 Scheduled Agent
+
+This example demonstrates a real working agent that checks AI news
+every hour using the AgentScheduler with actual API calls.
+
+Requirements:
+    - OPENAI_API_KEY environment variable set
+    - praisonaiagents package installed
+    
+Usage:
+    python news_checker_live.py
+"""
+
+import os
+import sys
+from datetime import datetime
+
+# Add parent directory to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../..'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../../..'))
+
+from praisonaiagents import Agent
+from praisonai.scheduler import AgentScheduler
+
+# Import search_tool from root tools.py
+try:
+    from tools import search_tool
+except ImportError:
+    # Fallback: create inline search tool
+    from duckduckgo_search import DDGS
+    
+    def search_tool(query: str) -> list:
+        """Search the web using DuckDuckGo."""
+        try:
+            results = []
+            ddgs = DDGS()
+            for result in ddgs.text(keywords=query, max_results=5):
+                results.append({
+                    "title": result.get("title", ""),
+                    "url": result.get("href", ""),
+                    "snippet": result.get("body", ""),
+                })
+            return results
+        except Exception as e:
+            print(f"Search error: {e}")
+            return []
+
+
+def on_success(result):
+    """Callback when agent execution succeeds."""
+    print("\n" + "="*80)
+    print(f"✅ SUCCESS - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("="*80)
+    print(result)
+    print("="*80 + "\n")
+
+
+def on_failure(error):
+    """Callback when agent execution fails."""
+    print("\n" + "="*80)
+    print(f"❌ FAILURE - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("="*80)
+    print(f"Error: {error}")
+    print("="*80 + "\n")
+
+
+def main():
+    """Main function to run the scheduled news checker."""
+    
+    # Check for API key
+    if not os.getenv("OPENAI_API_KEY"):
+        print("❌ Error: OPENAI_API_KEY environment variable not set")
+        print("Please set it with: export OPENAI_API_KEY=your_key_here")
+        sys.exit(1)
+    
+    print("\n🤖 Starting 24/7 AI News Checker Agent")
+    print("="*80)
+    
+    # Create the agent with web search capability
+    agent = Agent(
+        name="AI News Monitor",
+        role="Technology News Analyst",
+        goal="Monitor and summarize the latest AI and technology news",
+        backstory="""You are an expert AI news analyst who stays up-to-date 
+        with the latest developments in artificial intelligence, machine learning, 
+        and technology. You provide concise, accurate summaries of important news.""",
+        tools=[search_tool],
+        verbose=True,
+        self_reflect=False  # Disable reflection for faster execution
+    )
+    
+    # Define the task
+    task = """Search for the latest AI news from today. 
+    Focus on major developments, breakthroughs, or announcements.
+    Provide a summary of the top 3 most important news items.
+    Include the source and key details for each item."""
+    
+    # Create scheduler with callbacks
+    scheduler = AgentScheduler(
+        agent=agent,
+        task=task,
+        on_success=on_success,
+        on_failure=on_failure
+    )
+    
+    print(f"Agent: {agent.name}")
+    print(f"Task: {task}")
+    print(f"Schedule: Every 1 hour")
+    print("="*80)
+    print("\n⏰ Starting scheduler... (Press Ctrl+C to stop)\n")
+    
+    # Start the scheduler
+    # For testing: use "*/2m" (every 2 minutes) instead of "hourly"
+    # For production: use "hourly"
+    scheduler.start(
+        schedule_expr="*/2m",  # Every 2 minutes for testing
+        max_retries=3,
+        run_immediately=True  # Run once immediately
+    )
+    
+    try:
+        # Keep the main thread alive
+        while scheduler.is_running:
+            import time
+            time.sleep(1)
+            
+    except KeyboardInterrupt:
+        print("\n\n🛑 Stopping scheduler...")
+        scheduler.stop()
+        
+        # Print final statistics
+        stats = scheduler.get_stats()
+        print("\n📊 Final Statistics:")
+        print(f"  Total Executions: {stats['total_executions']}")
+        print(f"  Successful: {stats['successful_executions']}")
+        print(f"  Failed: {stats['failed_executions']}")
+        print(f"  Success Rate: {stats['success_rate']:.1f}%")
+        print("\n✅ Agent stopped successfully\n")
+
+
+if __name__ == "__main__":
+    main()

examples/python/scheduled_agents/simple_test.py

@@ -0,0 +1,61 @@
+"""
+Simple test script for 24/7 Agent Scheduler
+
+This script demonstrates the basic usage of AgentScheduler
+for running agents periodically.
+
+Usage:
+    python simple_test.py
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../..'))
+
+from unittest.mock import Mock
+from praisonai.scheduler import AgentScheduler
+
+# Create a mock agent for testing
+mock_agent = Mock()
+mock_agent.name = "TestAgent"
+mock_agent.start = Mock(return_value="Test execution successful!")
+
+# Create scheduler
+scheduler = AgentScheduler(
+    agent=mock_agent,
+    task="Test task execution"
+)
+
+print("🤖 Testing AgentScheduler")
+print("=" * 60)
+
+# Test 1: Execute once
+print("\n✅ Test 1: Execute once")
+result = scheduler.execute_once()
+print(f"Result: {result}")
+
+# Test 2: Get stats
+print("\n✅ Test 2: Get statistics")
+stats = scheduler.get_stats()
+print(f"Stats: {stats}")
+
+# Test 3: Start scheduler (will run every 5 seconds)
+print("\n✅ Test 3: Start scheduler (*/5s)")
+scheduler.start("*/5s", run_immediately=True)
+
+import time
+print("Running for 12 seconds...")
+time.sleep(12)
+
+# Stop scheduler
+print("\n✅ Test 4: Stop scheduler")
+scheduler.stop()
+
+# Final stats
+print("\n📊 Final Statistics:")
+final_stats = scheduler.get_stats()
+for key, value in final_stats.items():
+    print(f"  {key}: {value}")
+
+print("\n✅ All tests passed!")
+print("=" * 60)

examples/run_all_examples.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Run all examples and collect PASS/SKIP/FAIL results."""
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+EXAMPLES_DIR = Path(__file__).parent
+RESULTS = []
+
+def run_example(path: Path) -> tuple:
+    """Run an example and return (name, status, reason)."""
+    name = f"{path.parent.name}/{path.name}"
+    try:
+        result = subprocess.run(
+            [sys.executable, str(path)],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            env={**os.environ, "PYTHONPATH": str(EXAMPLES_DIR.parent / "src")}
+        )
+        output = result.stdout + result.stderr
+        if "PASSED" in output:
+            return (name, "PASS", "")
+        elif "SKIPPED" in output:
+            return (name, "SKIP", output.split("SKIPPED:")[-1].strip()[:50])
+        elif result.returncode != 0:
+            error = output.strip().split("\n")[-1][:80]
+            return (name, "FAIL", error)
+        else:
+            return (name, "PASS", "")
+    except subprocess.TimeoutExpired:
+        return (name, "FAIL", "Timeout")
+    except Exception as e:
+        return (name, "FAIL", str(e)[:50])
+
+def main():
+    print("=" * 70)
+    print("EXAMPLE RUNNER - PASS/SKIP/FAIL SUMMARY")
+    print("=" * 70)
+    
+    # Find all example files
+    examples = []
+    for subdir in ["db", "vector", "observability", "multi_agent", "workflows"]:
+        subpath = EXAMPLES_DIR / subdir
+        if subpath.exists():
+            examples.extend(sorted(subpath.glob("*_wow.py")))
+    
+    print(f"\nFound {len(examples)} examples to run\n")
+    
+    for ex in examples:
+        name, status, reason = run_example(ex)
+        RESULTS.append((name, status, reason))
+        icon = {"PASS": "✅", "SKIP": "⏭️", "FAIL": "❌"}.get(status, "?")
+        reason_str = f" ({reason})" if reason else ""
+        print(f"{icon} {status:4} | {name:45} {reason_str}")
+    
+    # Summary
+    print("\n" + "=" * 70)
+    passed = sum(1 for _, s, _ in RESULTS if s == "PASS")
+    skipped = sum(1 for _, s, _ in RESULTS if s == "SKIP")
+    failed = sum(1 for _, s, _ in RESULTS if s == "FAIL")
+    print(f"SUMMARY: {passed} PASS | {skipped} SKIP | {failed} FAIL | {len(RESULTS)} TOTAL")
+    print("=" * 70)
+    
+    return 0 if failed == 0 else 1
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/scheduler/test_5sec_schedule.yaml

@@ -0,0 +1,14 @@
+framework: praisonai
+
+agents:
+  - name: "5 Second Timer"
+    role: "Timer Agent"
+    instructions: "Display the current time"
+    verbose: true
+
+task: "Show current time"
+
+schedule:
+  interval: "*/5s"
+  max_retries: 3
+  run_immediately: true

examples/scheduler/test_counter.yaml

@@ -0,0 +1,14 @@
+framework: praisonai
+
+agents:
+  - name: "Counter Agent"
+    role: "Counter"
+    instructions: "Count from 1 to 5, incrementing by 1 each time. Just output the numbers clearly."
+    verbose: true
+
+task: "Print numbers 1, 2, 3, 4, 5 (one number per line)"
+
+schedule:
+  interval: "*/5s"
+  max_retries: 3
+  run_immediately: true

examples/scheduler/test_counter_with_limits.yaml

@@ -0,0 +1,16 @@
+framework: praisonai
+
+agents:
+  - name: "Counter Agent with Limits"
+    role: "Counter"
+    instructions: "Count from 1 to 5, incrementing by 1 each time. Just output the numbers clearly."
+    verbose: true
+
+task: "Print numbers 1, 2, 3, 4, 5 (one number per line)"
+
+schedule:
+  interval: "*/5s"           # Run every 5 seconds
+  max_retries: 3             # Retry up to 3 times on failure
+  run_immediately: true      # Run once immediately on start
+  timeout: 30                # Max 30 seconds per execution
+  max_cost: 0.01             # Stop after spending $0.01 USD

examples/scheduler/test_default_budget.yaml

@@ -0,0 +1,15 @@
+framework: praisonai
+
+agents:
+  - name: "Budget Test Agent"
+    role: "Tester"
+    instructions: "Count from 1 to 3"
+    verbose: true
+
+task: "Print numbers 1, 2, 3"
+
+schedule:
+  interval: "*/3s"
+  max_retries: 2
+  run_immediately: true
+  # No max_cost specified - should default to $1.00

examples/skills/basic_skill_usage.py

@@ -0,0 +1,73 @@
+"""
+Basic Agent Skills Usage Example
+
+This example demonstrates how to use Agent Skills with PraisonAI Agents.
+Skills are modular capabilities that can be loaded and used by agents.
+"""
+
+from praisonaiagents import Agent, SkillManager
+
+# Example 1: Using SkillManager directly
+print("=" * 50)
+print("Example 1: Using SkillManager directly")
+print("=" * 50)
+
+# Create a skill manager
+manager = SkillManager()
+
+# Discover skills from a directory
+# This scans the directory for subdirectories containing SKILL.md files
+skill_count = manager.discover(["./pdf-processing"], include_defaults=False)
+print(f"Discovered {skill_count} skill(s)")
+
+# List available skills
+for skill in manager:
+    print(f"  - {skill.properties.name}: {skill.properties.description[:50]}...")
+
+# Generate prompt XML for system prompt injection
+prompt_xml = manager.to_prompt()
+print("\nGenerated prompt XML:")
+print(prompt_xml)
+
+# Example 2: Using skills with an Agent
+print("\n" + "=" * 50)
+print("Example 2: Using skills with an Agent")
+print("=" * 50)
+
+# Create an agent with skills
+# Skills are lazy-loaded only when accessed
+agent = Agent(
+    name="PDF Assistant",
+    instructions="You are a helpful assistant that can process PDF documents.",
+    skills=["./pdf-processing"],  # Direct skill paths
+)
+
+# Access the skill manager through the agent
+if agent.skill_manager:
+    print(f"Agent has {len(agent.skill_manager)} skill(s) loaded")
+    
+    # Get the skills prompt for system prompt injection
+    skills_prompt = agent.get_skills_prompt()
+    print("\nAgent skills prompt:")
+    print(skills_prompt)
+
+# Example 3: Discovering skills from multiple directories
+print("\n" + "=" * 50)
+print("Example 3: Using skills_dirs for discovery")
+print("=" * 50)
+
+# Create an agent that discovers skills from directories
+agent_with_discovery = Agent(
+    name="Multi-Skill Agent",
+    instructions="You are a versatile assistant with multiple skills.",
+    skills_dirs=["./"],  # Scan current directory for skill subdirectories
+)
+
+if agent_with_discovery.skill_manager:
+    print(f"Discovered {len(agent_with_discovery.skill_manager)} skill(s)")
+    for name in agent_with_discovery.skill_manager.skill_names:
+        print(f"  - {name}")
+
+print("\n" + "=" * 50)
+print("Examples complete!")
+print("=" * 50)

examples/skills/create_skill_example.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+Example: Creating Skills with PraisonAI CLI
+
+This example demonstrates how to create Agent Skills using the CLI.
+"""
+
+import subprocess
+import tempfile
+import os
+from pathlib import Path
+
+
+def example_create_skill_with_template():
+    """Create a skill using template mode (no API key required)."""
+    print("=" * 60)
+    print("Example 1: Create skill with template")
+    print("=" * 60)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = subprocess.run([
+            "praisonai", "skills", "create",
+            "--name", "my-template-skill",
+            "--description", "A skill for processing text files",
+            "--author", "example-team",
+            "--license", "MIT",
+            "--template",
+            "--output-dir", tmpdir
+        ], capture_output=True, text=True)
+        
+        print(result.stdout)
+        if result.returncode == 0:
+            skill_md = Path(tmpdir) / "my-template-skill" / "SKILL.md"
+            print(f"\nGenerated SKILL.md:\n{skill_md.read_text()[:500]}...")
+        else:
+            print(f"Error: {result.stderr}")
+
+
+def example_create_skill_with_ai():
+    """Create a skill using AI generation (requires API key)."""
+    print("\n" + "=" * 60)
+    print("Example 2: Create skill with AI generation")
+    print("=" * 60)
+    
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Skipping: OPENAI_API_KEY not set")
+        return
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = subprocess.run([
+            "praisonai", "skills", "create",
+            "--name", "csv-analyzer",
+            "--description", "Analyze CSV files and generate statistical reports",
+            "--output-dir", tmpdir
+        ], capture_output=True, text=True)
+        
+        print(result.stdout)
+        if result.returncode == 0:
+            skill_md = Path(tmpdir) / "csv-analyzer" / "SKILL.md"
+            print(f"\nGenerated SKILL.md:\n{skill_md.read_text()[:800]}...")
+            
+            # Check if script was generated
+            script_path = Path(tmpdir) / "csv-analyzer" / "scripts" / "skill.py"
+            if script_path.exists():
+                print(f"\nGenerated skill.py:\n{script_path.read_text()[:500]}...")
+
+
+def example_create_skill_with_script():
+    """Create a skill with auto-generated Python script."""
+    print("\n" + "=" * 60)
+    print("Example 3: Create skill with script")
+    print("=" * 60)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = subprocess.run([
+            "praisonai", "skills", "create",
+            "--name", "data-processor",
+            "--description", "Process and transform data files",
+            "--template",
+            "--script",
+            "--output-dir", tmpdir
+        ], capture_output=True, text=True)
+        
+        print(result.stdout)
+        if result.returncode == 0:
+            script_path = Path(tmpdir) / "data-processor" / "scripts" / "skill.py"
+            if script_path.exists():
+                print(f"\nGenerated skill.py:\n{script_path.read_text()}")
+
+
+if __name__ == "__main__":
+    example_create_skill_with_template()
+    example_create_skill_with_ai()
+    example_create_skill_with_script()

examples/skills/custom_skill_example.py

@@ -0,0 +1,163 @@
+"""
+Custom Skill Creation Example
+
+This example demonstrates how to programmatically create and validate
+custom Agent Skills using PraisonAI Agents.
+"""
+
+import tempfile
+from pathlib import Path
+
+from praisonaiagents.skills import (
+    SkillManager,
+    SkillLoader,
+    validate,
+    read_properties,
+)
+
+
+def create_custom_skill(
+    name: str,
+    description: str,
+    instructions: str,
+    base_dir: str = None
+) -> Path:
+    """Create a custom skill programmatically.
+    
+    Args:
+        name: Skill name (kebab-case)
+        description: What the skill does
+        instructions: Markdown instructions for the skill
+        base_dir: Directory to create skill in (default: temp dir)
+        
+    Returns:
+        Path to the created skill directory
+    """
+    if base_dir is None:
+        base_dir = tempfile.mkdtemp()
+    
+    skill_dir = Path(base_dir) / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create SKILL.md
+    skill_md_content = f"""---
+name: {name}
+description: {description}
+license: Apache-2.0
+metadata:
+  author: custom
+  version: "1.0"
+---
+
+{instructions}
+"""
+    (skill_dir / "SKILL.md").write_text(skill_md_content)
+    
+    # Create optional directories
+    (skill_dir / "scripts").mkdir(exist_ok=True)
+    (skill_dir / "references").mkdir(exist_ok=True)
+    (skill_dir / "assets").mkdir(exist_ok=True)
+    
+    return skill_dir
+
+
+def main():
+    print("=" * 60)
+    print("Custom Skill Creation Example")
+    print("=" * 60)
+    
+    # Create a custom skill
+    print("\n1. Creating a custom skill...")
+    
+    skill_path = create_custom_skill(
+        name="code-review",
+        description="Review code for best practices, bugs, and improvements. Use when asked to review or analyze code quality.",
+        instructions="""
+# Code Review Skill
+
+## Overview
+This skill enables thorough code review with focus on:
+- Code quality and readability
+- Potential bugs and edge cases
+- Performance considerations
+- Security vulnerabilities
+- Best practices adherence
+
+## Instructions
+
+When reviewing code:
+
+1. **Read the code carefully** - Understand the purpose and flow
+2. **Check for bugs** - Look for null checks, edge cases, error handling
+3. **Evaluate readability** - Variable names, comments, structure
+4. **Consider performance** - Time/space complexity, unnecessary operations
+5. **Security review** - Input validation, injection risks, data exposure
+6. **Suggest improvements** - Provide actionable recommendations
+
+## Output Format
+
+Structure your review as:
+- Summary: Brief overview of the code
+- Issues: List of problems found (severity: high/medium/low)
+- Suggestions: Recommended improvements
+- Positive aspects: What's done well
+"""
+    )
+    
+    print(f"   Created skill at: {skill_path}")
+    
+    # Validate the skill
+    print("\n2. Validating the skill...")
+    errors = validate(skill_path)
+    
+    if errors:
+        print("   Validation errors:")
+        for error in errors:
+            print(f"   - {error}")
+    else:
+        print("   ✓ Skill is valid!")
+    
+    # Load and inspect the skill
+    print("\n3. Loading skill properties...")
+    props = read_properties(skill_path)
+    print(f"   Name: {props.name}")
+    print(f"   Description: {props.description[:60]}...")
+    print(f"   License: {props.license}")
+    
+    # Use with SkillLoader for progressive loading
+    print("\n4. Using SkillLoader for progressive disclosure...")
+    loader = SkillLoader()
+    
+    # Level 1: Load metadata only
+    skill = loader.load_metadata(str(skill_path))
+    print(f"   Level 1 - Metadata loaded: {skill.properties.name}")
+    print(f"   Instructions loaded: {skill.is_activated}")
+    
+    # Level 2: Activate (load instructions)
+    loader.activate(skill)
+    print(f"   Level 2 - Activated: {skill.is_activated}")
+    print(f"   Instructions preview: {skill.instructions[:100]}...")
+    
+    # Use with SkillManager
+    print("\n5. Using with SkillManager...")
+    manager = SkillManager()
+    manager.add_skill(str(skill_path))
+    
+    # Generate prompt XML
+    prompt = manager.to_prompt()
+    print("   Generated prompt XML:")
+    print(prompt)
+    
+    # Clean up
+    print("\n6. Cleanup...")
+    import shutil
+    shutil.rmtree(skill_path.parent)
+    print("   Temporary files removed.")
+    
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/skills/multi_agent_example.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Example: Multi-Agent CLI Usage
+
+This example demonstrates how to use the praisonai agents command
+to define and run multiple agents from the command line.
+"""
+
+import subprocess
+import os
+
+
+def example_single_agent():
+    """Run a single agent with a simple task."""
+    print("=" * 60)
+    print("Example 1: Single Agent")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "assistant:Helper",
+        "--task", "What is the capital of France?"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+    if result.returncode != 0:
+        print(f"Error: {result.stderr}")
+
+
+def example_agent_with_tools():
+    """Run an agent with tools."""
+    print("\n" + "=" * 60)
+    print("Example 2: Agent with Tools")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "researcher:Research Analyst:internet_search",
+        "--task", "Find the latest news about renewable energy"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+def example_multiple_agents_sequential():
+    """Run multiple agents in sequential mode."""
+    print("\n" + "=" * 60)
+    print("Example 3: Multiple Agents (Sequential)")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "researcher:Research Analyst:internet_search",
+        "--agent", "writer:Content Writer:write_file",
+        "--task", "Research AI trends and write a brief summary"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+def example_multiple_agents_parallel():
+    """Run multiple agents in parallel mode."""
+    print("\n" + "=" * 60)
+    print("Example 4: Multiple Agents (Parallel)")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "analyst1:Market Analyst",
+        "--agent", "analyst2:Tech Analyst",
+        "--process", "parallel",
+        "--task", "Analyze the current state of AI industry"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+def example_with_custom_llm():
+    """Run agents with a custom LLM model."""
+    print("\n" + "=" * 60)
+    print("Example 5: Custom LLM Model")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "coder:Developer:execute_command",
+        "--llm", "gpt-4o-mini",
+        "--task", "Write a simple hello world Python script"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+def example_with_instructions():
+    """Run agents with additional instructions."""
+    print("\n" + "=" * 60)
+    print("Example 6: With Additional Instructions")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "run",
+        "--agent", "analyst:Data Analyst",
+        "--instructions", "Be concise and provide only key insights",
+        "--task", "Explain the benefits of using AI in healthcare"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+def example_list_tools():
+    """List available tools for agents."""
+    print("\n" + "=" * 60)
+    print("Example 7: List Available Tools")
+    print("=" * 60)
+    
+    result = subprocess.run([
+        "praisonai", "agents", "list"
+    ], capture_output=True, text=True)
+    
+    print(result.stdout)
+
+
+if __name__ == "__main__":
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Warning: OPENAI_API_KEY not set. Some examples may fail.")
+        print()
+    
+    # Run examples
+    example_list_tools()
+    example_single_agent()
+    # Uncomment to run more examples:
+    # example_agent_with_tools()
+    # example_multiple_agents_sequential()
+    # example_multiple_agents_parallel()
+    # example_with_custom_llm()
+    # example_with_instructions()

examples/skills/pdf-processing/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pdf-processing
+description: Process and extract information from PDF documents. Use this skill when the user asks to read, analyze, or extract data from PDF files.
+license: Apache-2.0
+compatibility: Works with PraisonAI Agents
+metadata:
+  author: praisonai
+  version: "1.0"
+---
+
+# PDF Processing Skill
+
+## Overview
+
+This skill enables agents to process PDF documents, extract text content, and analyze the information within them.
+
+## When to Use
+
+Activate this skill when:
+- User asks to read or analyze a PDF file
+- User needs to extract text from a PDF
+- User wants to summarize a PDF document
+- User needs to search for information within a PDF
+
+## Instructions
+
+1. First, verify the PDF file exists at the specified path
+2. Use appropriate tools to read the PDF content
+3. Extract text while preserving structure where possible
+4. For large PDFs, process in chunks to manage context
+5. Summarize or analyze based on user's specific request
+
+## Best Practices
+
+- Always confirm the file path before processing
+- Handle encrypted PDFs gracefully with appropriate error messages
+- For scanned PDFs, note that OCR may be required
+- Preserve important formatting like tables and lists

examples/thinking/basic_thinking.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Basic Thinking Budgets Example for PraisonAI Agents.
+
+This example demonstrates how to use thinking budgets to:
+1. Configure token budgets for extended thinking
+2. Use predefined budget levels
+3. Track thinking usage
+4. Adapt budgets based on complexity
+
+Usage:
+    python basic_thinking.py
+"""
+
+from praisonaiagents.thinking import (
+    ThinkingBudget, ThinkingConfig, ThinkingUsage, ThinkingTracker
+)
+from praisonaiagents.thinking.budget import BudgetLevel
+
+
+def main():
+    print("=" * 60)
+    print("Thinking Budgets Demo")
+    print("=" * 60)
+    
+    # ==========================================================================
+    # Budget Levels
+    # ==========================================================================
+    print("\n--- Budget Levels ---")
+    
+    levels = [
+        ("Minimal", ThinkingBudget.minimal()),
+        ("Low", ThinkingBudget.low()),
+        ("Medium", ThinkingBudget.medium()),
+        ("High", ThinkingBudget.high()),
+        ("Maximum", ThinkingBudget.maximum()),
+    ]
+    
+    for name, budget in levels:
+        print(f"  {name}: {budget.max_tokens:,} tokens")
+    
+    # ==========================================================================
+    # Custom Budget
+    # ==========================================================================
+    print("\n--- Custom Budget ---")
+    
+    custom_budget = ThinkingBudget(
+        max_tokens=12000,
+        min_tokens=2000,
+        adaptive=True,
+        max_time_seconds=120.0
+    )
+    print(f"  Max tokens: {custom_budget.max_tokens:,}")
+    print(f"  Min tokens: {custom_budget.min_tokens:,}")
+    print(f"  Adaptive: {custom_budget.adaptive}")
+    print(f"  Time limit: {custom_budget.max_time_seconds}s")
+    
+    # ==========================================================================
+    # Complexity-Based Scaling
+    # ==========================================================================
+    print("\n--- Complexity-Based Token Allocation ---")
+    
+    budget = ThinkingBudget(
+        max_tokens=16000,
+        min_tokens=2000,
+        adaptive=True
+    )
+    
+    complexities = [0.0, 0.25, 0.5, 0.75, 1.0]
+    for complexity in complexities:
+        tokens = budget.get_tokens_for_complexity(complexity)
+        bar = "█" * int(tokens / 1000)
+        print(f"  Complexity {complexity:.2f}: {tokens:,} tokens {bar}")
+    
+    # ==========================================================================
+    # Usage Tracking
+    # ==========================================================================
+    print("\n--- Usage Tracking ---")
+    
+    usage = ThinkingUsage(
+        budget_tokens=8000,
+        tokens_used=5000,
+        time_seconds=30.0,
+        budget_time=60.0
+    )
+    
+    print(f"  Tokens used: {usage.tokens_used:,} / {usage.budget_tokens:,}")
+    print(f"  Tokens remaining: {usage.tokens_remaining:,}")
+    print(f"  Utilization: {usage.token_utilization:.1%}")
+    print(f"  Over budget: {usage.is_over_budget}")
+    print(f"  Time remaining: {usage.time_remaining}s")
+    
+    # ==========================================================================
+    # Session Tracking
+    # ==========================================================================
+    print("\n--- Session Tracking ---")
+    
+    tracker = ThinkingTracker()
+    
+    # Simulate multiple thinking sessions
+    sessions = [
+        (8000, 4000, 20.0),
+        (8000, 6000, 35.0),
+        (16000, 12000, 60.0),
+        (8000, 9000, 45.0),  # Over budget
+    ]
+    
+    for budget_tokens, tokens_used, time_seconds in sessions:
+        session = tracker.start_session(budget_tokens=budget_tokens)
+        tracker.end_session(session, tokens_used=tokens_used, time_seconds=time_seconds)
+    
+    summary = tracker.get_summary()
+    print(f"  Total sessions: {summary['session_count']}")
+    print(f"  Total tokens used: {summary['total_tokens_used']:,}")
+    print(f"  Average tokens/session: {summary['average_tokens_per_session']:,.0f}")
+    print(f"  Average utilization: {summary['average_utilization']:.1%}")
+    print(f"  Over-budget sessions: {summary['over_budget_count']}")
+    
+    # ==========================================================================
+    # Serialization
+    # ==========================================================================
+    print("\n--- Serialization ---")
+    
+    budget = ThinkingBudget.from_level(BudgetLevel.HIGH)
+    data = budget.to_dict()
+    print(f"  Serialized: level={data['level']}, max_tokens={data['max_tokens']}")
+    
+    restored = ThinkingBudget.from_dict(data)
+    print(f"  Restored: {restored.max_tokens:,} tokens")
+    
+    print("\n" + "=" * 60)
+    print("Demo Complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/arxiv/tool.py

@@ -0,0 +1,44 @@
+"""ArXiv Tool Example.
+
+This example demonstrates how to use the ArXiv tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: No API key required!
+"""
+
+from praisonai_tools import ArxivTool
+
+
+def main():
+    # Initialize ArXiv tool (no API key needed)
+    arxiv = ArxivTool()
+    
+    # Example 1: Search ArXiv
+    print("=" * 60)
+    print("Example 1: Search ArXiv")
+    print("=" * 60)
+    
+    results = arxiv.search("transformer neural networks", max_results=3)
+    
+    if results and "error" in results[0]:
+        print(f"Error: {results[0]['error']}")
+    else:
+        print(f"Found {len(results)} papers:")
+        for paper in results:
+            print(f"\n  Title: {paper.get('title', 'N/A')[:60]}...")
+            authors = paper.get('authors', [])
+            if authors:
+                print(f"  Authors: {', '.join(authors[:2])}...")
+            print(f"  Published: {paper.get('published', 'N/A')}")
+            print(f"  PDF: {paper.get('pdf_url', 'N/A')}")
+    
+    print("\n✅ ArXiv tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/calculator/tool.py

@@ -0,0 +1,53 @@
+"""Calculator Tool Example.
+
+This example demonstrates how to use the Calculator tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: No API key required!
+"""
+
+from praisonai_tools import CalculatorTool
+
+
+def main():
+    # Initialize Calculator tool
+    calc = CalculatorTool()
+    
+    # Example 1: Basic arithmetic
+    print("=" * 60)
+    print("Example 1: Basic Arithmetic")
+    print("=" * 60)
+    
+    expressions = [
+        "2 + 2",
+        "10 * 5",
+        "100 / 4",
+        "2 ** 10",
+        "(10 + 5) * 2 - 3"
+    ]
+    
+    for expr in expressions:
+        result = calc.evaluate(expr)
+        print(f"  {expr} = {result.get('result', result)}")
+    
+    # Example 2: Percentage calculation
+    print("\n" + "=" * 60)
+    print("Example 2: Percentage Calculation")
+    print("=" * 60)
+    
+    result = calc.evaluate("250 * 0.15")
+    print(f"  15% of 250 = {result.get('result', result)}")
+    
+    result = calc.evaluate("1000 * (1 + 0.05) ** 3")
+    print(f"  $1000 at 5% for 3 years = ${result.get('result', 0):.2f}")
+    
+    print("\n✅ Calculator tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/duckduckgo/tool.py

@@ -0,0 +1,75 @@
+"""DuckDuckGo Search Tool Example.
+
+This example demonstrates how to use the DuckDuckGo search tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: No API key required!
+"""
+
+from praisonai_tools import DuckDuckGoTool
+
+
+def main():
+    # Initialize DuckDuckGo tool (no API key needed)
+    ddg = DuckDuckGoTool()
+    
+    # Example 1: Web search
+    print("=" * 60)
+    print("Example 1: Web Search")
+    print("=" * 60)
+    
+    results = ddg.search("Python programming best practices", max_results=3)
+    
+    if results and "error" in results[0]:
+        print(f"Error: {results[0]['error']}")
+    else:
+        print(f"Found {len(results)} results:")
+        for r in results:
+            print(f"  - {r['title']}")
+            print(f"    URL: {r['url']}")
+            print(f"    Snippet: {r['snippet'][:100]}...")
+            print()
+    
+    # Example 2: News search
+    print("=" * 60)
+    print("Example 2: News Search")
+    print("=" * 60)
+    
+    news = ddg.news("artificial intelligence", max_results=3)
+    
+    if news and "error" in news[0]:
+        print(f"Error: {news[0]['error']}")
+    else:
+        print(f"Found {len(news)} news articles:")
+        for n in news:
+            print(f"  - {n['title']}")
+            print(f"    Source: {n.get('source', 'N/A')}")
+            print(f"    Date: {n.get('date', 'N/A')}")
+            print()
+    
+    # Example 3: Image search
+    print("=" * 60)
+    print("Example 3: Image Search")
+    print("=" * 60)
+    
+    images = ddg.images("sunset landscape", max_results=3)
+    
+    if images and "error" in images[0]:
+        print(f"Error: {images[0]['error']}")
+    else:
+        print(f"Found {len(images)} images:")
+        for img in images:
+            print(f"  - {img['title']}")
+            print(f"    Image URL: {img['image_url'][:60]}...")
+            print()
+    
+    print("✅ DuckDuckGo tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/exa/tool.py

@@ -0,0 +1,48 @@
+"""Exa Search Tool Example.
+
+This example demonstrates how to use the Exa search tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+    export EXA_API_KEY=your_api_key
+
+Usage:
+    python tool.py
+"""
+
+import os
+from praisonai_tools import ExaTool
+
+
+def main():
+    # Check for API key
+    if not os.getenv("EXA_API_KEY"):
+        print("Error: EXA_API_KEY environment variable not set")
+        print("Get your API key from https://exa.ai/")
+        return
+    
+    # Initialize Exa tool
+    exa = ExaTool()
+    
+    # Example 1: Neural search
+    print("=" * 60)
+    print("Example 1: Neural Search")
+    print("=" * 60)
+    
+    results = exa.search("best practices for Python development", num_results=3)
+    
+    if results and "error" in results[0]:
+        print(f"Error: {results[0]['error']}")
+    else:
+        print(f"Found {len(results)} results:")
+        for r in results:
+            print(f"  - {r.get('title', 'N/A')[:50]}...")
+            print(f"    URL: {r.get('url', 'N/A')[:60]}...")
+            print(f"    Score: {r.get('score', 'N/A')}")
+            print()
+    
+    print("✅ Exa tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/firecrawl/tool.py

@@ -0,0 +1,45 @@
+"""Firecrawl Tool Example.
+
+This example demonstrates how to use the Firecrawl tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+    export FIRECRAWL_API_KEY=your_api_key
+
+Usage:
+    python tool.py
+"""
+
+import os
+from praisonai_tools import FirecrawlTool
+
+
+def main():
+    # Check for API key
+    if not os.getenv("FIRECRAWL_API_KEY"):
+        print("Error: FIRECRAWL_API_KEY environment variable not set")
+        print("Get your API key from https://firecrawl.dev/")
+        return
+    
+    # Initialize Firecrawl tool
+    firecrawl = FirecrawlTool()
+    
+    # Example 1: Scrape a page
+    print("=" * 60)
+    print("Example 1: Scrape a Page")
+    print("=" * 60)
+    
+    result = firecrawl.scrape("https://example.com")
+    
+    if "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        print(f"URL: {result.get('url', 'N/A')}")
+        markdown = result.get('markdown', '')
+        print(f"Content preview: {markdown[:300]}...")
+    
+    print("\n✅ Firecrawl tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/hackernews/tool.py

@@ -0,0 +1,42 @@
+"""Hacker News Tool Example.
+
+This example demonstrates how to use the Hacker News tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: No API key required!
+"""
+
+from praisonai_tools import HackerNewsTool
+
+
+def main():
+    # Initialize Hacker News tool
+    hn = HackerNewsTool()
+    
+    # Example 1: Get top stories
+    print("=" * 60)
+    print("Example 1: Top Stories")
+    print("=" * 60)
+    
+    stories = hn.get_top_stories(limit=5)
+    
+    if stories and "error" in stories[0]:
+        print(f"Error: {stories[0]['error']}")
+    else:
+        print(f"Found {len(stories)} top stories:")
+        for story in stories:
+            print(f"  - {story.get('title', 'N/A')[:50]}...")
+            print(f"    Score: {story.get('score', 'N/A')} | Comments: {story.get('descendants', 'N/A')}")
+            print(f"    URL: {story.get('url', 'N/A')[:60]}...")
+            print()
+    
+    print("✅ Hacker News tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/jina/tool.py

@@ -0,0 +1,40 @@
+"""Jina Reader Tool Example.
+
+This example demonstrates how to use the Jina Reader tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: Works without API key (with rate limits)
+"""
+
+from praisonai_tools import JinaTool
+
+
+def main():
+    # Initialize Jina tool (works without API key)
+    jina = JinaTool()
+    
+    # Example 1: Read a URL
+    print("=" * 60)
+    print("Example 1: Read URL Content")
+    print("=" * 60)
+    
+    result = jina.read("https://example.com")
+    
+    if "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        print(f"URL: {result.get('url', 'N/A')}")
+        print(f"Title: {result.get('title', 'N/A')}")
+        content = result.get('content', '')
+        print(f"Content preview: {content[:300]}...")
+    
+    print("\n✅ Jina tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/postgres/tool.py

@@ -0,0 +1,56 @@
+"""PostgreSQL Tool Example.
+
+This example demonstrates how to use the PostgreSQL tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+    Docker: docker run -d --name postgres -e POSTGRES_PASSWORD=praison123 -e POSTGRES_DB=praisonai -p 5432:5432 postgres:16
+
+Usage:
+    python tool.py
+"""
+
+from praisonai_tools import PostgresTool
+
+
+def main():
+    # Initialize PostgreSQL tool
+    pg = PostgresTool(
+        host="localhost",
+        port=5432,
+        database="praisonai",
+        user="postgres",
+        password="praison123"
+    )
+    
+    # Example 1: List tables
+    print("=" * 60)
+    print("Example 1: List Tables")
+    print("=" * 60)
+    
+    tables = pg.list_tables()
+    
+    if isinstance(tables, dict) and "error" in tables:
+        print(f"Error: {tables['error']}")
+    else:
+        print(f"Found {len(tables)} tables:")
+        for t in tables[:10]:
+            print(f"  - {t.get('table_name', t)}")
+    
+    # Example 2: Query
+    print("\n" + "=" * 60)
+    print("Example 2: Execute Query")
+    print("=" * 60)
+    
+    result = pg.query("SELECT version()")
+    
+    if isinstance(result, dict) and "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        print(f"PostgreSQL version: {result}")
+    
+    print("\n✅ PostgreSQL tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/serper/tool.py

@@ -0,0 +1,47 @@
+"""Serper Tool Example.
+
+This example demonstrates how to use the Serper (Google Search) tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+    export SERPER_API_KEY=your_api_key
+
+Usage:
+    python tool.py
+"""
+
+import os
+from praisonai_tools import SerperTool
+
+
+def main():
+    # Check for API key
+    if not os.getenv("SERPER_API_KEY"):
+        print("Error: SERPER_API_KEY environment variable not set")
+        print("Get your API key from https://serper.dev/")
+        return
+    
+    # Initialize Serper tool
+    serper = SerperTool()
+    
+    # Example 1: Web search
+    print("=" * 60)
+    print("Example 1: Google Web Search")
+    print("=" * 60)
+    
+    results = serper.search("Python programming tutorials", max_results=3)
+    
+    if results and "error" in results[0]:
+        print(f"Error: {results[0]['error']}")
+    else:
+        print(f"Found {len(results)} results:")
+        for r in results:
+            print(f"  - {r.get('title', 'N/A')[:50]}...")
+            print(f"    URL: {r.get('link', 'N/A')[:60]}...")
+            print()
+    
+    print("✅ Serper tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/tavily/tool.py

@@ -0,0 +1,57 @@
+"""Tavily Search Tool Example.
+
+This example demonstrates how to use the Tavily search tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+    export TAVILY_API_KEY=your_api_key
+
+Usage:
+    python tool.py
+"""
+
+import os
+from praisonai_tools import TavilyTool
+
+def main():
+    # Check for API key
+    if not os.getenv("TAVILY_API_KEY"):
+        print("Error: TAVILY_API_KEY environment variable not set")
+        print("Get your API key from https://tavily.com/")
+        return
+    
+    # Initialize Tavily tool
+    tavily = TavilyTool()
+    
+    # Example 1: Basic search
+    print("=" * 60)
+    print("Example 1: Basic Search")
+    print("=" * 60)
+    
+    results = tavily.search("What is quantum computing?", max_results=3)
+    
+    if "error" in results:
+        print(f"Error: {results['error']}")
+    else:
+        print(f"Query: {results.get('query')}")
+        if "answer" in results:
+            print(f"\nAI Answer: {results['answer'][:200]}...")
+        print(f"\nResults ({len(results.get('results', []))}):")
+        for r in results.get("results", []):
+            print(f"  - {r['title']}")
+            print(f"    URL: {r['url']}")
+            print(f"    Score: {r.get('score', 'N/A')}")
+    
+    # Example 2: Search context for RAG
+    print("\n" + "=" * 60)
+    print("Example 2: Search Context (for RAG)")
+    print("=" * 60)
+    
+    context = tavily.search_context("Python best practices 2024")
+    print(f"Context (first 300 chars): {context[:300]}...")
+    
+    print("\n✅ Tavily tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/tools/external/wikipedia/tool.py

@@ -0,0 +1,69 @@
+"""Wikipedia Tool Example.
+
+This example demonstrates how to use the Wikipedia tool with PraisonAI agents.
+
+Requirements:
+    pip install "praisonai[tools]"
+
+Usage:
+    python tool.py
+
+Note: No API key required!
+"""
+
+from praisonai_tools import WikipediaTool
+
+
+def main():
+    # Initialize Wikipedia tool (no API key needed)
+    wiki = WikipediaTool()
+    
+    # Example 1: Search Wikipedia
+    print("=" * 60)
+    print("Example 1: Search Wikipedia")
+    print("=" * 60)
+    
+    results = wiki.search("Python programming", max_results=5)
+    
+    if results and "error" in results[0]:
+        print(f"Error: {results[0]['error']}")
+    else:
+        print(f"Found {len(results)} results:")
+        for r in results:
+            print(f"  - {r['title']}")
+    
+    # Example 2: Get page summary
+    print("\n" + "=" * 60)
+    print("Example 2: Get Page Summary")
+    print("=" * 60)
+    
+    summary = wiki.summary("Artificial intelligence", sentences=3)
+    
+    if "error" in summary:
+        print(f"Error: {summary['error']}")
+    else:
+        print(f"Title: {summary['title']}")
+        print(f"Summary: {summary['summary'][:300]}...")
+    
+    # Example 3: Get full page
+    print("\n" + "=" * 60)
+    print("Example 3: Get Full Page")
+    print("=" * 60)
+    
+    page = wiki.get_page("Machine learning")
+    
+    if "error" in page:
+        print(f"Error: {page['error']}")
+        if "options" in page:
+            print(f"Options: {page['options'][:5]}")
+    else:
+        print(f"Title: {page['title']}")
+        print(f"URL: {page['url']}")
+        print(f"Categories: {page['categories'][:3]}")
+        print(f"Content preview: {page['content'][:200]}...")
+    
+    print("\n✅ Wikipedia tool working correctly!")
+
+
+if __name__ == "__main__":
+    main()

examples/vector/chroma_wow.py

@@ -0,0 +1,21 @@
+"""ChromaDB Vector Store - Basic Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+store = create_knowledge_store("chroma", path="/tmp/chroma_demo")
+try:
+    store.delete_collection("demo")
+except Exception:
+    pass
+store.create_collection("demo", dimension=1536)
+docs = [
+    KnowledgeDocument(id="1", content="Python is a programming language", embedding=[0.1]*1536),
+    KnowledgeDocument(id="2", content="JavaScript runs in browsers", embedding=[0.2]*1536)
+]
+store.insert("demo", docs)
+results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+print(f"Found: {len(results)} results")
+assert len(results) >= 1
+print("PASSED: ChromaDB vector store")

examples/vector/lancedb_real_wow.py

@@ -0,0 +1,31 @@
+"""LanceDB Vector Store - Local Test"""
+import sys
+import os
+import shutil
+
+try:
+    import lancedb
+except ImportError:
+    print("SKIPPED: LanceDB - lancedb not installed")
+    sys.exit(0)
+
+# Clean up previous test
+db_path = "/tmp/lancedb_test"
+if os.path.exists(db_path):
+    shutil.rmtree(db_path)
+
+db = lancedb.connect(db_path)
+
+# Create table with vectors
+data = [
+    {"id": "1", "text": "Machine learning is AI", "vector": [0.1] * 128},
+    {"id": "2", "text": "Deep learning uses neural nets", "vector": [0.2] * 128},
+]
+table = db.create_table("demo", data)
+
+# Search
+results = table.search([0.1] * 128).limit(1).to_list()
+print(f"Found: {len(results)} results")
+print(f"Top result: {results[0]['text'][:30]}...")
+assert len(results) >= 1
+print("PASSED: LanceDB vector store")

examples/vector/lancedb_wow.py

@@ -0,0 +1,20 @@
+"""LanceDB Vector Store - Basic Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+try:
+    from praisonai.persistence import create_knowledge_store
+    from praisonai.persistence.knowledge.base import KnowledgeDocument
+    
+    store = create_knowledge_store("lancedb", path="/tmp/lancedb_demo")
+    store.create_collection("demo", dimension=1536)
+    docs = [
+        KnowledgeDocument(id="doc1", content="The Eiffel Tower is in Paris", embedding=[0.1]*1536),
+        KnowledgeDocument(id="doc2", content="The Statue of Liberty is in New York", embedding=[0.2]*1536)
+    ]
+    store.insert("demo", docs)
+    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+    print(f"Found: {len(results)} results")
+    assert len(results) >= 1
+    print("PASSED: LanceDB vector store")
+except ImportError as e:
+    print(f"SKIPPED: LanceDB - {e}")

examples/vector/pgvector_real_wow.py

@@ -0,0 +1,59 @@
+"""PGVector Vector Store - Docker Test"""
+import sys
+import os
+
+# Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
+
+try:
+    import psycopg2
+except ImportError:
+    print("SKIPPED: PGVector - psycopg2 not installed")
+    sys.exit(0)
+
+try:
+    conn = psycopg2.connect(url)
+    cur = conn.cursor()
+    
+    # Ensure extension
+    cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+    conn.commit()
+    
+    # Create test table
+    cur.execute("DROP TABLE IF EXISTS test_vectors")
+    cur.execute("""
+        CREATE TABLE test_vectors (
+            id SERIAL PRIMARY KEY,
+            content TEXT,
+            embedding vector(128)
+        )
+    """)
+    conn.commit()
+    
+    # Insert vectors
+    cur.execute("""
+        INSERT INTO test_vectors (content, embedding) VALUES
+        ('Machine learning is AI', %s),
+        ('Deep learning uses neural nets', %s)
+    """, ([0.1] * 128, [0.2] * 128))
+    conn.commit()
+    
+    # Search (cosine similarity)
+    cur.execute("""
+        SELECT content, embedding <=> %s::vector AS distance
+        FROM test_vectors
+        ORDER BY distance
+        LIMIT 1
+    """, ([0.1] * 128,))
+    
+    row = cur.fetchone()
+    print(f"Top result: {row[0][:30]}... (distance: {row[1]:.4f})")
+    
+    # Cleanup
+    cur.execute("DROP TABLE test_vectors")
+    conn.commit()
+    conn.close()
+    
+    print("PASSED: PGVector vector store")
+except Exception as e:
+    print(f"SKIPPED: PGVector - {e}")

examples/vector/pgvector_wow.py

@@ -0,0 +1,23 @@
+"""PGVector Knowledge Store - Basic Test (requires Docker)"""
+import sys
+import os
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+# Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
+try:
+    store = create_knowledge_store("pgvector", url=url)
+    store.create_collection("demo", dimension=1536)
+    docs = [
+        KnowledgeDocument(id="1", content="Kubernetes orchestrates containers", embedding=[0.1]*1536),
+        KnowledgeDocument(id="2", content="Docker packages applications", embedding=[0.2]*1536)
+    ]
+    store.insert("demo", docs)
+    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+    print(f"Found: {len(results)} results")
+    assert len(results) >= 1
+    print("PASSED: PGVector vector store")
+except Exception as e:
+    print(f"SKIPPED: PGVector - {e}")

examples/vector/pinecone_wow.py

@@ -0,0 +1,27 @@
+"""Pinecone Vector Store - Real API Test"""
+import os
+import sys
+sys.path.insert(0, 'src/praisonai')
+
+# Requires: export PINECONE_API_KEY=...
+api_key = os.getenv("PINECONE_API_KEY")
+if not api_key:
+    print("SKIPPED: Pinecone - PINECONE_API_KEY not set")
+    sys.exit(0)
+
+from pinecone import Pinecone
+
+pc = Pinecone(api_key=api_key)
+indexes = pc.list_indexes()
+print(f"Pinecone connected! Found {len(list(indexes))} indexes")
+
+# Use existing 'test' index or create one
+index_name = "test"
+if index_name not in [idx.name for idx in pc.list_indexes()]:
+    print(f"SKIPPED: Pinecone - index '{index_name}' not found")
+    sys.exit(0)
+
+index = pc.Index(index_name)
+stats = index.describe_index_stats()
+print(f"Index '{index_name}' has {stats.total_vector_count} vectors")
+print("PASSED: Pinecone vector store")

examples/vector/qdrant_wow.py

@@ -0,0 +1,23 @@
+"""Qdrant Vector Store - Basic Test (requires Docker)"""
+import sys, os
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+# Docker: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
+url = os.getenv("QDRANT_URL", "http://localhost:6333")
+store = create_knowledge_store("qdrant", url=url)
+try:
+    store.delete_collection("demo")
+except Exception:
+    pass
+store.create_collection("demo", dimension=1536)
+docs = [
+    KnowledgeDocument(id="1", content="Machine learning is AI", embedding=[0.1]*1536),
+    KnowledgeDocument(id="2", content="Deep learning uses neural nets", embedding=[0.2]*1536)
+]
+store.insert("demo", docs)
+results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+print(f"Found: {len(results)} results")
+assert len(results) >= 1
+print("PASSED: Qdrant vector store")

examples/vector/weaviate_wow.py

@@ -0,0 +1,24 @@
+"""Weaviate Cloud Vector Store - Real API Test"""
+import os
+import sys
+
+# Requires: export WEAVIATE_URL=... and WEAVIATE_API_KEY=...
+weaviate_url = os.getenv("WEAVIATE_URL", "https://thhoyczshsawyt16ot3uw.c0.europe-west3.gcp.weaviate.cloud")
+weaviate_key = os.getenv("WEAVIATE_API_KEY")
+if not weaviate_key:
+    print("SKIPPED: Weaviate - WEAVIATE_API_KEY not set")
+    sys.exit(0)
+
+import weaviate
+from weaviate.classes.init import Auth
+
+client = weaviate.connect_to_weaviate_cloud(
+    cluster_url=weaviate_url,
+    auth_credentials=Auth.api_key(weaviate_key)
+)
+
+print(f"Weaviate connected: {client.is_ready()}")
+collections = client.collections.list_all()
+print(f"Found {len(collections)} collections")
+client.close()
+print("PASSED: Weaviate cloud vector store")

src/praisonai-agents/benchmarks/BENCHMARK_RESULTS.md

@@ -0,0 +1,35 @@
+# PraisonAI Agents - Benchmark Results
+
+**Generated:** 2025-12-18 14:40:22
+**Iterations:** 100
+**Test:** Agent instantiation (without tools)
+
+## Results
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **3.77** | **1.00x (fastest)** |
+| OpenAI Agents SDK | 5.26 | 1.39x |
+| Agno | 5.64 | 1.49x |
+| PraisonAI (LiteLLM) | 7.56 | 2.00x |
+| PydanticAI | 226.94 | 60.16x |
+| LangGraph | 4,558.71 | 1,209x |
+| CrewAI | 15,607.92 | 4,138x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| PydanticAI | 1.35.0 |
+| OpenAI Agents SDK | 0.6.3 |
+| LangGraph | 1.0.5 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```

src/praisonai-agents/benchmarks/EXECUTION_BENCHMARK_RESULTS.md

@@ -0,0 +1,31 @@
+# PraisonAI Agents - Real Execution Benchmark
+
+**Generated:** 2025-12-18 14:43:52
+**Model:** gpt-4o-mini
+**Iterations:** 3
+**Prompt:** "What is 2+2? Reply with just the number."
+
+## Results
+
+| Framework | Method | Avg Time | Relative |
+|-----------|--------|----------|----------|
+| **PraisonAI** | `agent.start()` | **0.45s** | **1.00x (fastest)** |
+| PraisonAI (LiteLLM) | `agent.start()` | 0.55s | 1.22x |
+| CrewAI | `crew.kickoff()` | 0.58s | 1.28x |
+| Agno | `agent.run()` | 0.92s | 2.05x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+export OPENAI_API_KEY=your_key
+cd praisonai-agents
+python benchmarks/execution_benchmark.py
+```

src/praisonai-agents/benchmarks/REAL_BENCHMARK_RESULTS.md

@@ -0,0 +1,72 @@
+# PraisonAI Agents - Real-World Execution Benchmark
+
+**Generated:** 2025-12-18 14:33:49
+**Model:** gpt-4o-mini
+**Iterations:** 3 per test
+
+## Results Summary
+
+| Test | PraisonAI (avg) | Agno (avg) | Difference |
+|------|-----------------|------------|------------|
+| Single Agent | 2.04s | 3.18s | PraisonAI 1.56x faster |
+| 2 Agents | 2.49s | 20.49s | PraisonAI 8.21x faster |
+| 3 Agents | 6.52s | 13.97s | PraisonAI 2.14x faster |
+
+## Detailed Results
+
+### praisonai_single
+- Average: 2.04s
+- Min: 1.95s
+- Max: 2.19s
+- Std Dev: 0.13s
+- Times: ['2.19s', '1.95s', '2.00s']
+
+### agno_single
+- Average: 3.18s
+- Min: 3.00s
+- Max: 3.51s
+- Std Dev: 0.28s
+- Times: ['3.51s', '3.00s', '3.04s']
+
+### praisonai_two_agents
+- Average: 2.49s
+- Min: 2.22s
+- Max: 2.65s
+- Std Dev: 0.24s
+- Times: ['2.65s', '2.22s', '2.62s']
+
+### agno_two_agents
+- Average: 20.49s
+- Min: 9.96s
+- Max: 35.05s
+- Std Dev: 13.02s
+- Times: ['16.46s', '9.96s', '35.05s']
+
+### praisonai_three_agents
+- Average: 6.52s
+- Min: 5.62s
+- Max: 7.39s
+- Std Dev: 0.88s
+- Times: ['5.62s', '6.54s', '7.39s']
+
+### agno_three_agents
+- Average: 13.97s
+- Min: 11.69s
+- Max: 15.32s
+- Std Dev: 1.99s
+- Times: ['14.91s', '11.69s', '15.32s']
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+
+## How to Reproduce
+
+```bash
+export OPENAI_API_KEY=your_key
+cd praisonai-agents
+python benchmarks/real_benchmark.py
+```

src/praisonai-agents/benchmarks/SIMPLE_BENCHMARK_RESULTS.md

@@ -0,0 +1,22 @@
+# PraisonAI Agents - Benchmark Results
+
+**Generated:** 2025-12-18 13:23:43
+
+## Agent Instantiation Time
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **4.16** | **1.00x (fastest)** |
+| OpenAI Agents SDK | 5.55 | 1.33x |
+| Agno | 5.58 | 1.34x |
+| PraisonAI (LiteLLM) | 8.52 | 2.05x |
+| PydanticAI | 225.87 | 54.25x |
+| LangGraph | 4,349.54 | 1,045x |
+| CrewAI | 15,911.11 | 3,821x |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```

src/praisonai-agents/benchmarks/TOOLS_BENCHMARK_RESULTS.md

@@ -0,0 +1,33 @@
+# PraisonAI Agents - Tools Benchmark Results
+
+**Generated:** 2025-12-18 14:40:35
+**Iterations:** 100
+**Test:** Agent instantiation WITH TOOLS
+
+## Results
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **3.24** | **1.00x (fastest)** |
+| Agno | 5.12 | 1.58x |
+| PraisonAI (LiteLLM) | 8.59 | 2.65x |
+| OpenAI Agents SDK | 279.95 | 86.44x |
+| LangGraph | 2,310.82 | 713x |
+| CrewAI | 15,773.44 | 4,870x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| OpenAI Agents SDK | 0.6.3 |
+| LangGraph | 1.0.5 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/tools_benchmark.py
+```

src/praisonai-agents/benchmarks/deep_profiling.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Deep Profiling Benchmark
+
+Profiles each step of agent initialization to identify performance bottlenecks.
+
+Key Optimizations Applied:
+1. Lazy RulesManager - filesystem operations deferred until first access
+2. Lazy os.getcwd() - fast_context_path resolved only when needed
+3. Lazy console initialization - Rich Console created on demand
+
+Usage:
+    python benchmarks/deep_profiling.py
+"""
+
+import time
+import tracemalloc
+import cProfile
+import pstats
+import io
+from typing import Literal, Callable, Dict, List
+from dataclasses import dataclass
+
+# ============================================================================
+# Timing Utilities
+# ============================================================================
+
+@dataclass
+class StepTiming:
+    name: str
+    duration_us: float  # microseconds
+    memory_kb: float    # kilobytes
+
+
+class StepProfiler:
+    """Profile individual steps during initialization"""
+    
+    def __init__(self):
+        self.steps: List[StepTiming] = []
+        self._start_time = None
+        self._start_memory = None
+    
+    def start_step(self, name: str):
+        tracemalloc.start()
+        self._start_time = time.perf_counter()
+        self._step_name = name
+    
+    def end_step(self):
+        end_time = time.perf_counter()
+        current, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        
+        duration_us = (end_time - self._start_time) * 1_000_000
+        memory_kb = peak / 1024
+        
+        self.steps.append(StepTiming(
+            name=self._step_name,
+            duration_us=duration_us,
+            memory_kb=memory_kb
+        ))
+    
+    def print_report(self, title: str):
+        print(f"\n{'='*70}")
+        print(f"STEP-BY-STEP PROFILING: {title}")
+        print(f"{'='*70}")
+        
+        total_time = sum(s.duration_us for s in self.steps)
+        total_memory = sum(s.memory_kb for s in self.steps)
+        
+        print(f"\n{'Step':<40} {'Time (μs)':<15} {'Memory (KB)':<15} {'% Time':<10}")
+        print("-" * 80)
+        
+        for step in sorted(self.steps, key=lambda x: x.duration_us, reverse=True):
+            pct = (step.duration_us / total_time * 100) if total_time > 0 else 0
+            print(f"{step.name:<40} {step.duration_us:<15.2f} {step.memory_kb:<15.2f} {pct:<10.1f}%")
+        
+        print("-" * 80)
+        print(f"{'TOTAL':<40} {total_time:<15.2f} {total_memory:<15.2f} {'100.0':<10}%")
+
+
+def time_function(func: Callable, iterations: int = 100) -> Dict:
+    """Time a function with detailed statistics"""
+    times = []
+    
+    # Warmup
+    for _ in range(10):
+        func()
+    
+    # Measure
+    for _ in range(iterations):
+        start = time.perf_counter()
+        func()
+        end = time.perf_counter()
+        times.append((end - start) * 1_000_000)  # Convert to microseconds
+    
+    return {
+        'avg': sum(times) / len(times),
+        'min': min(times),
+        'max': max(times),
+        'median': sorted(times)[len(times)//2]
+    }
+
+
+# ============================================================================
+# Profile PraisonAI Agent Initialization - Step by Step
+# ============================================================================
+
+def profile_praisonai_detailed():
+    """Profile each step of PraisonAI Agent initialization"""
+    print("\n" + "="*70)
+    print("DETAILED PROFILING: PraisonAI Agent")
+    print("="*70)
+    
+    profiler = StepProfiler()
+    
+    # Step 1: Import
+    profiler.start_step("1. Import praisonaiagents")
+    from praisonaiagents import Agent as PraisonAgent
+    profiler.end_step()
+    
+    # Step 2: Define tool
+    profiler.start_step("2. Define tool function")
+    def get_weather(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    profiler.end_step()
+    
+    # Step 3: Full instantiation
+    profiler.start_step("3. Full Agent instantiation")
+    agent = PraisonAgent(
+        name="Test Agent",
+        instructions="Be concise, reply with one sentence.",
+        llm="gpt-4o-mini",
+        tools=tools,
+        verbose=False
+    )
+    profiler.end_step()
+    
+    profiler.print_report("PraisonAI Agent")
+    
+    # Now profile the __init__ internals using cProfile
+    print("\n" + "="*70)
+    print("cProfile ANALYSIS: PraisonAI Agent.__init__")
+    print("="*70)
+    
+    pr = cProfile.Profile()
+    pr.enable()
+    
+    for _ in range(100):
+        agent = PraisonAgent(
+            name="Test Agent",
+            instructions="Be concise, reply with one sentence.",
+            llm="gpt-4o-mini",
+            tools=tools,
+            verbose=False
+        )
+    
+    pr.disable()
+    
+    # Print top 30 functions by cumulative time
+    s = io.StringIO()
+    ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
+    ps.print_stats(30)
+    print(s.getvalue())
+    
+    return agent
+
+
+# ============================================================================
+# Profile Agno Agent Initialization - Step by Step
+# ============================================================================
+
+def profile_agno_detailed():
+    """Profile each step of Agno Agent initialization"""
+    print("\n" + "="*70)
+    print("DETAILED PROFILING: Agno Agent")
+    print("="*70)
+    
+    profiler = StepProfiler()
+    
+    # Step 1: Import
+    profiler.start_step("1. Import agno")
+    from agno.agent import Agent as AgnoAgent
+    from agno.models.openai import OpenAIChat
+    profiler.end_step()
+    
+    # Step 2: Define tool
+    profiler.start_step("2. Define tool function")
+    def get_weather(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    profiler.end_step()
+    
+    # Step 3: Full instantiation
+    profiler.start_step("3. Full Agent instantiation")
+    agent = AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    profiler.end_step()
+    
+    profiler.print_report("Agno Agent")
+    
+    # Now profile the __init__ internals using cProfile
+    print("\n" + "="*70)
+    print("cProfile ANALYSIS: Agno Agent.__init__")
+    print("="*70)
+    
+    pr = cProfile.Profile()
+    pr.enable()
+    
+    for _ in range(100):
+        agent = AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    
+    pr.disable()
+    
+    # Print top 30 functions by cumulative time
+    s = io.StringIO()
+    ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
+    ps.print_stats(30)
+    print(s.getvalue())
+    
+    return agent
+
+
+# ============================================================================
+# Profile Individual Components of PraisonAI
+# ============================================================================
+
+def profile_praisonai_components():
+    """Profile individual components of PraisonAI Agent initialization"""
+    print("\n" + "="*70)
+    print("COMPONENT-LEVEL PROFILING: PraisonAI Agent")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    
+    def get_weather(city: Literal["nyc", "sf"]):
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    
+    # Test different configurations
+    configs = [
+        ("Minimal (no tools, no llm)", {"name": "Test", "verbose": False}),
+        ("With name only", {"name": "Test Agent", "verbose": False}),
+        ("With instructions", {"name": "Test", "instructions": "Be concise", "verbose": False}),
+        ("With llm (gpt-4o-mini)", {"name": "Test", "llm": "gpt-4o-mini", "verbose": False}),
+        ("With llm (openai/gpt-4o-mini)", {"name": "Test", "llm": "openai/gpt-4o-mini", "verbose": False}),
+        ("With tools", {"name": "Test", "tools": tools, "verbose": False}),
+        ("Full config (OpenAI SDK)", {"name": "Test", "instructions": "Be concise", "llm": "gpt-4o-mini", "tools": tools, "verbose": False}),
+        ("Full config (LiteLLM)", {"name": "Test", "instructions": "Be concise", "llm": "openai/gpt-4o-mini", "tools": tools, "verbose": False}),
+    ]
+    
+    print(f"\n{'Configuration':<40} {'Avg Time (μs)':<15} {'Min (μs)':<15} {'Max (μs)':<15}")
+    print("-" * 85)
+    
+    for name, config in configs:
+        def create_agent():
+            return PraisonAgent(**config)
+        
+        stats = time_function(create_agent, iterations=100)
+        print(f"{name:<40} {stats['avg']:<15.2f} {stats['min']:<15.2f} {stats['max']:<15.2f}")
+
+
+# ============================================================================
+# Compare Specific Operations
+# ============================================================================
+
+def compare_specific_operations():
+    """Compare specific operations between PraisonAI and Agno"""
+    print("\n" + "="*70)
+    print("OPERATION COMPARISON: PraisonAI vs Agno")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    from agno.agent import Agent as AgnoAgent
+    from agno.models.openai import OpenAIChat
+    
+    def get_weather(city: Literal["nyc", "sf"]):
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    
+    operations = []
+    
+    # Operation 1: Bare minimum instantiation
+    def praisonai_minimal():
+        return PraisonAgent(name="Test", verbose=False)
+    
+    def agno_minimal():
+        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"))
+    
+    praison_stats = time_function(praisonai_minimal, 100)
+    agno_stats = time_function(agno_minimal, 100)
+    operations.append(("Minimal instantiation", praison_stats['avg'], agno_stats['avg']))
+    
+    # Operation 2: With tools
+    def praisonai_with_tools():
+        return PraisonAgent(name="Test", tools=tools, verbose=False)
+    
+    def agno_with_tools():
+        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    
+    praison_stats = time_function(praisonai_with_tools, 100)
+    agno_stats = time_function(agno_with_tools, 100)
+    operations.append(("With tools", praison_stats['avg'], agno_stats['avg']))
+    
+    # Operation 3: Full config
+    def praisonai_full():
+        return PraisonAgent(
+            name="Test Agent",
+            instructions="Be concise",
+            llm="gpt-4o-mini",
+            tools=tools,
+            verbose=False
+        )
+    
+    def agno_full():
+        return AgnoAgent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            tools=tools,
+            instructions=["Be concise"]
+        )
+    
+    praison_stats = time_function(praisonai_full, 100)
+    agno_stats = time_function(agno_full, 100)
+    operations.append(("Full config", praison_stats['avg'], agno_stats['avg']))
+    
+    print(f"\n{'Operation':<30} {'PraisonAI (μs)':<18} {'Agno (μs)':<18} {'Ratio':<10}")
+    print("-" * 76)
+    
+    for op_name, praison_time, agno_time in operations:
+        ratio = praison_time / agno_time if agno_time > 0 else 0
+        print(f"{op_name:<30} {praison_time:<18.2f} {agno_time:<18.2f} {ratio:<10.1f}x")
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    import os
+    os.environ.setdefault("OPENAI_API_KEY", "sk-test")
+    
+    print("="*70)
+    print("PraisonAI Agents - Deep Profiling Benchmark")
+    print("="*70)
+    print("\nThis analysis identifies performance bottlenecks in agent initialization.\n")
+    
+    # Run all profiling
+    profile_praisonai_detailed()
+    profile_agno_detailed()
+    profile_praisonai_components()
+    compare_specific_operations()
+    
+    print("\n" + "="*70)
+    print("PROFILING COMPLETE")
+    print("="*70)

src/praisonai-agents/benchmarks/execution_benchmark.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Real Execution Benchmark
+
+Benchmarks ACTUAL agent execution with LLM API calls.
+Tests single agent running a simple task across frameworks.
+
+Usage:
+    export OPENAI_API_KEY=your_key
+    python benchmarks/execution_benchmark.py
+    python benchmarks/execution_benchmark.py --no-save
+    python benchmarks/execution_benchmark.py --iterations 5
+    python benchmarks/execution_benchmark.py --model gpt-4o --iterations 10
+"""
+
+import time
+import os
+import argparse
+from importlib.metadata import version as get_version
+
+# Defaults (can be overridden via CLI)
+DEFAULT_MODEL = "gpt-4o-mini"
+DEFAULT_ITERATIONS = 3
+DEFAULT_PROMPT = "What is 2+2? Reply with just the number."
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'CrewAI': 'crewai',
+    }
+    versions = {}
+    for name, pkg in packages.items():
+        try:
+            versions[name] = get_version(pkg)
+        except:
+            versions[name] = 'not installed'
+    return versions
+
+
+def benchmark_praisonai(model, iterations, prompt):
+    """Benchmark PraisonAI agent execution using agent.start()"""
+    from praisonaiagents import Agent
+    
+    print("\n--- PraisonAI ---")
+    print("Method: agent.start()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            name="Calculator",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm=model,
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_praisonai_litellm(model, iterations, prompt):
+    """Benchmark PraisonAI with LiteLLM backend using agent.start()"""
+    from praisonaiagents import Agent
+    
+    print("\n--- PraisonAI (LiteLLM) ---")
+    print("Method: agent.start()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            name="Calculator",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm=f"openai/{model}",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_agno(model, iterations, prompt):
+    """Benchmark Agno agent execution using agent.run()"""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    print("\n--- Agno ---")
+    print("Method: agent.run()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            model=OpenAIChat(id=model),
+            instructions=["You are a helpful assistant. Be very brief."],
+        )
+        
+        start = time.perf_counter()
+        response = agent.run(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        # Extract content from response
+        content = str(response.content)[:50] if hasattr(response, 'content') else str(response)[:50]
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {content}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_crewai(model, iterations, prompt):
+    """Benchmark CrewAI agent execution using crew.kickoff()"""
+    from crewai import Agent, Task, Crew
+    
+    print("\n--- CrewAI ---")
+    print("Method: crew.kickoff()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            role="Calculator",
+            goal="Answer math questions",
+            backstory="You are a helpful assistant.",
+            llm=model,
+            verbose=False
+        )
+        
+        task = Task(
+            description=prompt,
+            expected_output="A number",
+            agent=agent
+        )
+        
+        crew = Crew(
+            agents=[agent],
+            tasks=[task],
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = crew.kickoff()
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def save_results(results: dict, model: str, iterations: int, prompt: str):
+    """Save results to markdown file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), 'EXECUTION_BENCHMARK_RESULTS.md')
+    versions = get_package_versions()
+    
+    # Sort by time
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest = sorted_results[0][1]
+    
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Real Execution Benchmark\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Model:** {model}\n')
+        f.write(f'**Iterations:** {iterations}\n')
+        f.write(f'**Prompt:** "{prompt}"\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Method | Avg Time | Relative |\n')
+        f.write('|-----------|--------|----------|----------|\n')
+        
+        methods = {
+            'PraisonAI': 'agent.start()',
+            'PraisonAI (LiteLLM)': 'agent.start()',
+            'Agno': 'agent.run()',
+            'CrewAI': 'crew.kickoff()',
+        }
+        
+        for name, avg in sorted_results:
+            ratio = avg / fastest
+            method = methods.get(name, 'unknown')
+            if ratio == 1.0:
+                f.write(f'| **{name}** | `{method}` | **{avg:.2f}s** | **1.00x (fastest)** |\n')
+            else:
+                f.write(f'| {name} | `{method}` | {avg:.2f}s | {ratio:.2f}x |\n')
+        
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('export OPENAI_API_KEY=your_key\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/execution_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='PraisonAI Agents - Real Execution Benchmark')
+    parser.add_argument('--no-save', action='store_true', help='Do not save results to file')
+    parser.add_argument('--model', '-m', type=str, default=DEFAULT_MODEL, help=f'Model to use (default: {DEFAULT_MODEL})')
+    parser.add_argument('--iterations', '-i', type=int, default=DEFAULT_ITERATIONS, help=f'Number of iterations (default: {DEFAULT_ITERATIONS})')
+    parser.add_argument('--prompt', '-p', type=str, default=DEFAULT_PROMPT, help=f'Prompt to use (default: "{DEFAULT_PROMPT}")')
+    args = parser.parse_args()
+    
+    # Check API key
+    if not os.environ.get('OPENAI_API_KEY'):
+        print("ERROR: Set OPENAI_API_KEY environment variable")
+        exit(1)
+    
+    model = args.model
+    iterations = args.iterations
+    prompt = args.prompt
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Real Execution Benchmark')
+    print('=' * 60)
+    print(f'\nModel: {model}')
+    print(f'Iterations: {iterations}')
+    print(f'Prompt: "{prompt}"')
+    
+    versions = get_package_versions()
+    print('\nPackage versions:')
+    for pkg, ver in versions.items():
+        print(f'  {pkg}: {ver}')
+    
+    results = {}
+    
+    # Run benchmarks
+    try:
+        results['PraisonAI'] = benchmark_praisonai(model, iterations, prompt)
+    except Exception as e:
+        print(f"PraisonAI error: {e}")
+    
+    try:
+        results['PraisonAI (LiteLLM)'] = benchmark_praisonai_litellm(model, iterations, prompt)
+    except Exception as e:
+        print(f"PraisonAI (LiteLLM) error: {e}")
+    
+    try:
+        results['Agno'] = benchmark_agno(model, iterations, prompt)
+    except Exception as e:
+        print(f"Agno error: {e}")
+    
+    try:
+        results['CrewAI'] = benchmark_crewai(model, iterations, prompt)
+    except Exception as e:
+        print(f"CrewAI error: {e}")
+    
+    # Summary
+    print('\n' + '=' * 60)
+    print('SUMMARY')
+    print('=' * 60)
+    
+    if results:
+        sorted_results = sorted(results.items(), key=lambda x: x[1])
+        fastest = sorted_results[0][1]
+        
+        print(f"\n{'Framework':<25} {'Avg Time':<12} {'Relative':<10}")
+        print('-' * 47)
+        
+        for name, avg in sorted_results:
+            ratio = avg / fastest
+            print(f'{name:<25} {avg:<12.2f}s {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    
+    # Save results (unless --no-save)
+    if results and not args.no_save:
+        save_results(results, model, iterations, prompt)
+    elif args.no_save:
+        print('\nResults not saved (--no-save flag used)')

src/praisonai-agents/benchmarks/performance_benchmark.py

@@ -1,15 +1,11 @@
 """
-Performance Benchmark: PraisonAI vs Agno
-========================================
-This benchmark replicates Agno's methodology for measuring:
-1. Agent instantiation time
-2. Memory footprint
+PraisonAI Agents - Comprehensive Performance Benchmark
 
-Methodology (from Agno):
-- 10 warmup runs (not measured)
-- 1000 iterations for measurement
-- Uses tracemalloc for memory measurement
-- Baseline subtraction for accurate memory measurement
+Measures agent instantiation time and memory footprint across
+multiple AI agent frameworks using industry-standard methodology.
+
+Usage:
+    python benchmarks/performance_benchmark.py
 """
 
 import gc
@@ -137,10 +133,8 @@ def run_benchmark(func: Callable, name: str, iterations: int = 1000, warmup: int
 
 
 # ============================================================================
-# Test Functions - Matching Agno's benchmark methodology EXACTLY
+# Framework Imports
 # ============================================================================
-
-# Import at module level (like Agno does)
 from praisonaiagents import Agent as PraisonAgent
 from agno.agent import Agent as AgnoAgent
 from agno.models.openai import OpenAIChat
@@ -182,43 +176,38 @@ def get_weather(city: Literal["nyc", "sf"]):
         return "It's always sunny in sf"
 
 
-# Pre-create tools list (like Agno does)
 tools = [get_weather]
 
 
-# PraisonAI Agent instantiation - using OpenAI SDK directly (no prefix)
 def instantiate_praisonai_agent():
-    """Instantiate a PraisonAI agent with one tool (OpenAI SDK)"""
+    """Instantiate a PraisonAI agent with one tool."""
     return PraisonAgent(
         name="Test Agent",
         instructions="Be concise, reply with one sentence.",
-        llm="gpt-4o-mini",  # No prefix = OpenAI SDK directly
+        llm="gpt-4o-mini",
         tools=tools,
         verbose=False
     )
 
 
-# PraisonAI Agent instantiation - using LiteLLM (openai/ prefix)
 def instantiate_praisonai_litellm_agent():
-    """Instantiate a PraisonAI agent with one tool (LiteLLM)"""
+    """Instantiate a PraisonAI agent with LiteLLM backend."""
     return PraisonAgent(
         name="Test Agent",
         instructions="Be concise, reply with one sentence.",
-        llm="openai/gpt-4o-mini",  # openai/ prefix = LiteLLM
+        llm="openai/gpt-4o-mini",
         tools=tools,
         verbose=False
     )
 
 
-# Agno Agent instantiation - exact copy from Agno's benchmark
 def instantiate_agno_agent():
-    """Instantiate an Agno agent with one tool"""
+    """Instantiate an Agno agent with one tool."""
     return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
 
 
-# PydanticAI Agent instantiation
 def instantiate_pydantic_agent():
-    """Instantiate a PydanticAI agent with one tool"""
+    """Instantiate a PydanticAI agent with one tool."""
     agent = PydanticAgent("openai:gpt-4o-mini", system_prompt="Be concise, reply with one sentence.")
     @agent.tool_plain
     def get_weather_pydantic(city: Literal["nyc", "sf"]):
@@ -230,9 +219,8 @@ def instantiate_pydantic_agent():
     return agent
 
 
-# OpenAI Agents SDK instantiation
 def instantiate_openai_agents():
-    """Instantiate an OpenAI Agents SDK agent with one tool"""
+    """Instantiate an OpenAI Agents SDK agent with one tool."""
     return OpenAIAgent(
         name="Test agent",
         instructions="Be concise, reply with one sentence.",
@@ -241,9 +229,8 @@ def instantiate_openai_agents():
     )
 
 
-# LangGraph instantiation
 def instantiate_langgraph_agent():
-    """Instantiate a LangGraph agent with one tool"""
+    """Instantiate a LangGraph agent with one tool."""
     @langchain_tool
     def get_weather_lg(city: Literal["nyc", "sf"]):
         """Use this to get weather information."""
@@ -254,9 +241,8 @@ def instantiate_langgraph_agent():
     return create_react_agent(model=ChatOpenAI(model="gpt-4o-mini"), tools=[get_weather_lg])
 
 
-# CrewAI instantiation
 def instantiate_crewai_agent():
-    """Instantiate a CrewAI agent with one tool"""
+    """Instantiate a CrewAI agent with one tool."""
     @crewai_tool("Weather Tool")
     def get_weather_crew(city: Literal["nyc", "sf"]):
         """Use this to get weather information."""
@@ -273,20 +259,124 @@ def instantiate_crewai_agent():
     )
 
 
+def get_package_versions():
+    """Get version numbers for all benchmarked packages."""
+    from importlib.metadata import version as get_version
+    
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'PydanticAI': 'pydantic-ai',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_benchmark_results(results: dict, baseline):
+    """Save benchmark results to BENCHMARK_RESULTS.md and update README.md"""
+    import os
+    import re
+    from datetime import datetime
+    
+    benchmarks_dir = os.path.dirname(__file__)
+    filepath = os.path.join(benchmarks_dir, 'BENCHMARK_RESULTS.md')
+    
+    # Get package versions
+    versions = get_package_versions()
+    
+    display_names = {
+        'agno': 'Agno',
+        'praisonai': 'PraisonAI',
+        'praisonai_litellm': 'PraisonAI (LiteLLM)',
+        'pydantic': 'PydanticAI',
+        'openai_agents': 'OpenAI Agents SDK',
+        'langgraph': 'LangGraph',
+        'crewai': 'CrewAI'
+    }
+    
+    # Build table rows
+    table_rows = []
+    sorted_results = sorted(results.items(), key=lambda x: x[1].avg_run_time)
+    
+    for name, result in sorted_results:
+        display_name = display_names.get(name, name)
+        avg_us = result.avg_run_time * 1e6
+        ratio = result.avg_run_time / baseline.avg_run_time if baseline.avg_run_time > 0 else 0
+        
+        if name == 'praisonai':
+            table_rows.append(f'| **{display_name}** | **{avg_us:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg_us:,.2f}' if avg_us >= 1000 else f'{avg_us:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {display_name} | {avg_str} | {ratio_str} |')
+    
+    # Save to BENCHMARK_RESULTS.md
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write('**Methodology:** 10 warmup runs + 1000 measured iterations\n\n')
+        f.write('## Agent Instantiation Time\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/performance_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    
+    # Update README.md
+    readme_path = os.path.join(benchmarks_dir, '..', '..', '..', 'README.md')
+    if os.path.exists(readme_path):
+        with open(readme_path, 'r') as f:
+            content = f.read()
+        
+        new_table = '''| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+''' + '\n'.join(table_rows)
+        
+        pattern = r'(\| Framework \| Avg Time \(μs\) \| Relative \|\n\|[-|]+\|\n)(\|[^\n]+\|\n)+'
+        
+        if re.search(pattern, content):
+            content = re.sub(pattern, new_table + '\n', content)
+            
+            with open(readme_path, 'w') as f:
+                f.write(content)
+            
+            print(f'README.md updated: {readme_path}')
+
+
 if __name__ == "__main__":
     print("="*70)
-    print("PERFORMANCE BENCHMARK: Agent Instantiation (All Frameworks)")
+    print("PraisonAI Agents - Comprehensive Performance Benchmark")
     print("="*70)
     print("\nThis benchmark measures:")
     print("  1. Agent instantiation time (how fast an agent object is created)")
     print("  2. Memory footprint (how much memory an agent uses)")
-    print("\nMethodology (matching Agno's approach):")
+    print("\nMethodology:")
     print("  - 10 warmup runs (not measured)")
     print("  - 1000 measured iterations")
     print("  - tracemalloc for memory measurement")
     print("  - Baseline subtraction for accuracy")
     print("\nFrameworks available:")
-    print(f"  - PraisonAI: ✅")
+    print("  - PraisonAI: ✅")
     print(f"  - Agno: ✅")
     print(f"  - PydanticAI: {'✅' if PYDANTIC_AVAILABLE else '❌'}")
     print(f"  - OpenAI Agents SDK: {'✅' if OPENAI_AGENTS_AVAILABLE else '❌'}")
@@ -295,38 +385,23 @@ if __name__ == "__main__":
     
     results = {}
     
-    # Test Agno (baseline)
+    # Test PraisonAI first
     try:
         print("\n" + "="*70)
-        print("Testing Agno (baseline)")
-        print("="*70)
-        results['agno'] = run_benchmark(
-            instantiate_agno_agent,
-            "Agno Agent Instantiation",
-            iterations=1000,
-            warmup=10
-        )
-    except Exception as e:
-        print(f"Error testing Agno: {e}")
-    
-    # Test PraisonAI (OpenAI SDK - no prefix)
-    try:
-        print("\n" + "="*70)
-        print("Testing PraisonAI Agents (OpenAI SDK - llm='gpt-4o-mini')")
+        print("Testing PraisonAI Agents")
         print("="*70)
         results['praisonai'] = run_benchmark(
             instantiate_praisonai_agent,
-            "PraisonAI (OpenAI SDK)",
+            "PraisonAI",
             iterations=1000,
             warmup=10
         )
     except Exception as e:
-        print(f"Error testing PraisonAI (OpenAI SDK): {e}")
+        print(f"Error testing PraisonAI: {e}")
     
-    # Test PraisonAI (LiteLLM - openai/ prefix)
     try:
         print("\n" + "="*70)
-        print("Testing PraisonAI Agents (LiteLLM - llm='openai/gpt-4o-mini')")
+        print("Testing PraisonAI Agents (LiteLLM)")
         print("="*70)
         results['praisonai_litellm'] = run_benchmark(
             instantiate_praisonai_litellm_agent,
@@ -337,6 +412,20 @@ if __name__ == "__main__":
     except Exception as e:
         print(f"Error testing PraisonAI (LiteLLM): {e}")
     
+    # Test Agno
+    try:
+        print("\n" + "="*70)
+        print("Testing Agno")
+        print("="*70)
+        results['agno'] = run_benchmark(
+            instantiate_agno_agent,
+            "Agno",
+            iterations=1000,
+            warmup=10
+        )
+    except Exception as e:
+        print(f"Error testing Agno: {e}")
+    
     # Test PydanticAI
     if PYDANTIC_AVAILABLE:
         try:
@@ -399,28 +488,26 @@ if __name__ == "__main__":
     
     # Final Comparison Table
     print("\n" + "="*70)
-    print("FINAL COMPARISON TABLE")
+    print("RESULTS SUMMARY")
     print("="*70)
     
-    if 'agno' in results:
-        agno = results['agno']
+    if 'praisonai' in results:
+        baseline = results['praisonai']
         
-        print(f"\n{'Framework':<20} {'Avg Time (μs)':<15} {'Avg Memory (KiB)':<18} {'Time vs Agno':<15} {'Memory vs Agno':<15}")
-        print("-" * 83)
+        print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Avg Memory (KiB)':<18} {'Relative':<15}")
+        print("-" * 73)
         
         # Sort by time
         sorted_results = sorted(results.items(), key=lambda x: x[1].avg_run_time)
         
         for name, result in sorted_results:
-            time_ratio = result.avg_run_time / agno.avg_run_time if agno.avg_run_time > 0 else 0
-            memory_ratio = result.avg_memory_usage / agno.avg_memory_usage if agno.avg_memory_usage > 0 else 0
+            time_ratio = result.avg_run_time / baseline.avg_run_time if baseline.avg_run_time > 0 else 0
             
-            time_str = f"{time_ratio:.0f}x" if time_ratio > 1 else "1x (baseline)"
-            memory_str = f"{memory_ratio:.1f}x" if memory_ratio > 1 else "1x (baseline)"
+            time_str = f"{time_ratio:.2f}x"
             
             display_name = {
                 'agno': 'Agno',
-                'praisonai': 'PraisonAI (OpenAI)',
+                'praisonai': 'PraisonAI',
                 'praisonai_litellm': 'PraisonAI (LiteLLM)',
                 'pydantic': 'PydanticAI',
                 'openai_agents': 'OpenAI Agents SDK',
@@ -428,33 +515,9 @@ if __name__ == "__main__":
                 'crewai': 'CrewAI'
             }.get(name, name)
             
-            print(f"{display_name:<20} {result.avg_run_time*1e6:<15.2f} {result.avg_memory_usage*1024:<18.2f} {time_str:<15} {memory_str:<15}")
+            print(f"{display_name:<25} {result.avg_run_time*1e6:<15.2f} {result.avg_memory_usage*1024:<18.2f} {time_str:<15}")
         
         print("\n" + "="*70)
-        print("ANALYSIS")
-        print("="*70)
         
-        if 'praisonai' in results:
-            praisonai = results['praisonai']
-            time_ratio = praisonai.avg_run_time / agno.avg_run_time
-            memory_ratio = praisonai.avg_memory_usage / agno.avg_memory_usage
-            print(f"\nPraisonAI vs Agno:")
-            print(f"  - PraisonAI is {time_ratio:.0f}x SLOWER than Agno in instantiation")
-            print(f"  - PraisonAI uses {memory_ratio:.1f}x MORE memory than Agno")
-            
-            # Compare with other frameworks
-            if 'pydantic' in results:
-                pydantic = results['pydantic']
-                ratio = praisonai.avg_run_time / pydantic.avg_run_time
-                if ratio > 1:
-                    print(f"  - PraisonAI is {ratio:.1f}x SLOWER than PydanticAI")
-                else:
-                    print(f"  - PraisonAI is {1/ratio:.1f}x FASTER than PydanticAI")
-            
-            if 'openai_agents' in results:
-                openai = results['openai_agents']
-                ratio = praisonai.avg_run_time / openai.avg_run_time
-                if ratio > 1:
-                    print(f"  - PraisonAI is {ratio:.1f}x SLOWER than OpenAI Agents SDK")
-                else:
-                    print(f"  - PraisonAI is {1/ratio:.1f}x FASTER than OpenAI Agents SDK")
+        # Save results to files
+        save_benchmark_results(results, baseline)

src/praisonai-agents/benchmarks/real_benchmark.py

@@ -0,0 +1,481 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Real-World Execution Benchmark
+
+Benchmarks actual agent execution with LLM calls across frameworks.
+Tests single agent, 2-agent, and 3-agent workflows.
+
+Usage:
+    python benchmarks/real_benchmark.py
+"""
+
+import time
+import statistics
+import os
+from typing import Literal, List
+from dataclasses import dataclass, field
+from importlib.metadata import version as get_version
+
+# Ensure API key is set
+if not os.environ.get('OPENAI_API_KEY'):
+    print("ERROR: OPENAI_API_KEY environment variable not set")
+    exit(1)
+
+
+@dataclass
+class ExecutionResult:
+    """Execution benchmark results"""
+    times: List[float] = field(default_factory=list)
+    
+    @property
+    def avg_time(self) -> float:
+        return statistics.mean(self.times) if self.times else 0
+    
+    @property
+    def min_time(self) -> float:
+        return min(self.times) if self.times else 0
+    
+    @property
+    def max_time(self) -> float:
+        return max(self.times) if self.times else 0
+    
+    @property
+    def std_dev(self) -> float:
+        return statistics.stdev(self.times) if len(self.times) > 1 else 0
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+    }
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    return versions
+
+
+# ============================================================================
+# Tool Definitions
+# ============================================================================
+
+def get_weather(city: Literal["nyc", "sf"]) -> str:
+    """Get weather information for a city."""
+    if city == "nyc":
+        return "New York: Cloudy, 45°F, 60% humidity"
+    return "San Francisco: Sunny, 72°F, 40% humidity"
+
+
+def get_time(timezone: Literal["est", "pst"]) -> str:
+    """Get current time in a timezone."""
+    if timezone == "est":
+        return "Eastern Time: 2:30 PM"
+    return "Pacific Time: 11:30 AM"
+
+
+def calculate(expression: str) -> str:
+    """Calculate a math expression."""
+    try:
+        result = eval(expression)
+        return f"Result: {result}"
+    except Exception:
+        return "Error: Invalid expression"
+
+
+# ============================================================================
+# PraisonAI Benchmarks
+# ============================================================================
+
+def benchmark_praisonai_single(iterations: int = 3) -> ExecutionResult:
+    """Benchmark single PraisonAI agent execution."""
+    from praisonaiagents import Agent
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI single agent iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            name="Assistant",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start("What's the weather in NYC? Reply in one sentence.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_praisonai_two_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 2 PraisonAI agents working together."""
+    from praisonaiagents import Agent, PraisonAIAgents
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI 2-agent iteration {i+1}/{iterations}...")
+        
+        researcher = Agent(
+            name="Researcher",
+            role="Research Assistant",
+            goal="Gather weather information",
+            instructions="Get weather data and pass to reporter. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        reporter = Agent(
+            name="Reporter",
+            role="News Reporter",
+            goal="Create weather report",
+            instructions="Create a one-sentence weather summary.",
+            llm="gpt-4o-mini",
+            verbose=False
+        )
+        
+        agents = PraisonAIAgents(
+            agents=[researcher, reporter],
+            process="sequential",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agents.start("Get NYC weather and create a brief report.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_praisonai_three_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 3 PraisonAI agents working together."""
+    from praisonaiagents import Agent, PraisonAIAgents
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI 3-agent iteration {i+1}/{iterations}...")
+        
+        weather_agent = Agent(
+            name="WeatherAgent",
+            role="Weather Specialist",
+            goal="Get weather data",
+            instructions="Fetch weather information. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        time_agent = Agent(
+            name="TimeAgent",
+            role="Time Specialist",
+            goal="Get time information",
+            instructions="Fetch timezone information. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_time],
+            verbose=False
+        )
+        
+        summarizer = Agent(
+            name="Summarizer",
+            role="Summary Writer",
+            goal="Combine information",
+            instructions="Create a one-sentence summary combining weather and time.",
+            llm="gpt-4o-mini",
+            verbose=False
+        )
+        
+        agents = PraisonAIAgents(
+            agents=[weather_agent, time_agent, summarizer],
+            process="sequential",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agents.start("Get NYC weather and EST time, then summarize.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+# ============================================================================
+# Agno Benchmarks
+# ============================================================================
+
+def benchmark_agno_single(iterations: int = 3) -> ExecutionResult:
+    """Benchmark single Agno agent execution."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno single agent iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["You are a helpful assistant. Be very brief."],
+            tools=[get_weather],
+        )
+        
+        start = time.perf_counter()
+        response = agent.run("What's the weather in NYC? Reply in one sentence.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_agno_two_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 2 Agno agents working together (using Team)."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    from agno.team import Team
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno 2-agent iteration {i+1}/{iterations}...")
+        
+        researcher = Agent(
+            name="Researcher",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Get weather data. Be brief."],
+            tools=[get_weather],
+        )
+        
+        reporter = Agent(
+            name="Reporter",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Create a one-sentence weather summary."],
+        )
+        
+        team = Team(
+            members=[researcher, reporter],
+            model=OpenAIChat(id="gpt-4o-mini"),
+        )
+        
+        start = time.perf_counter()
+        response = team.run("Get NYC weather and create a brief report.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_agno_three_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 3 Agno agents working together."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    from agno.team import Team
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno 3-agent iteration {i+1}/{iterations}...")
+        
+        weather_agent = Agent(
+            name="WeatherAgent",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Fetch weather information. Be brief."],
+            tools=[get_weather],
+        )
+        
+        time_agent = Agent(
+            name="TimeAgent",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Fetch timezone information. Be brief."],
+            tools=[get_time],
+        )
+        
+        summarizer = Agent(
+            name="Summarizer",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Create a one-sentence summary combining weather and time."],
+        )
+        
+        team = Team(
+            members=[weather_agent, time_agent, summarizer],
+            model=OpenAIChat(id="gpt-4o-mini"),
+        )
+        
+        start = time.perf_counter()
+        response = team.run("Get NYC weather and EST time, then summarize.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+# ============================================================================
+# Save Results
+# ============================================================================
+
+def save_results(results: dict, versions: dict):
+    """Save benchmark results to file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), 'REAL_BENCHMARK_RESULTS.md')
+    
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Real-World Execution Benchmark\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write('**Model:** gpt-4o-mini\n')
+        f.write('**Iterations:** 3 per test\n\n')
+        
+        f.write('## Results Summary\n\n')
+        f.write('| Test | PraisonAI (avg) | Agno (avg) | Difference |\n')
+        f.write('|------|-----------------|------------|------------|\n')
+        
+        tests = ['single', 'two_agents', 'three_agents']
+        test_names = ['Single Agent', '2 Agents', '3 Agents']
+        
+        for test, name in zip(tests, test_names):
+            praison_key = f'praisonai_{test}'
+            agno_key = f'agno_{test}'
+            
+            if praison_key in results and agno_key in results:
+                praison_avg = results[praison_key].avg_time
+                agno_avg = results[agno_key].avg_time
+                
+                if praison_avg < agno_avg:
+                    diff = f'PraisonAI {agno_avg/praison_avg:.2f}x faster'
+                else:
+                    diff = f'Agno {praison_avg/agno_avg:.2f}x faster'
+                
+                f.write(f'| {name} | {praison_avg:.2f}s | {agno_avg:.2f}s | {diff} |\n')
+        
+        f.write('\n## Detailed Results\n\n')
+        
+        for key, result in results.items():
+            f.write(f'### {key}\n')
+            f.write(f'- Average: {result.avg_time:.2f}s\n')
+            f.write(f'- Min: {result.min_time:.2f}s\n')
+            f.write(f'- Max: {result.max_time:.2f}s\n')
+            f.write(f'- Std Dev: {result.std_dev:.2f}s\n')
+            f.write(f'- Times: {[f"{t:.2f}s" for t in result.times]}\n\n')
+        
+        f.write('## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('export OPENAI_API_KEY=your_key\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/real_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    print("="*70)
+    print("PraisonAI Agents - Real-World Execution Benchmark")
+    print("="*70)
+    print("\nThis benchmark measures actual agent execution time including:")
+    print("  - LLM API calls")
+    print("  - Tool execution")
+    print("  - Multi-agent coordination")
+    print("\nModel: gpt-4o-mini")
+    print("Iterations: 3 per test")
+    
+    versions = get_package_versions()
+    print(f"\nPackage versions:")
+    for pkg, ver in versions.items():
+        print(f"  {pkg}: {ver}")
+    
+    results = {}
+    
+    # Single Agent Tests
+    print("\n" + "="*70)
+    print("SINGLE AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI single agent...")
+    results['praisonai_single'] = benchmark_praisonai_single()
+    
+    print("\nTesting Agno single agent...")
+    results['agno_single'] = benchmark_agno_single()
+    
+    # 2-Agent Tests
+    print("\n" + "="*70)
+    print("2-AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI 2 agents...")
+    results['praisonai_two_agents'] = benchmark_praisonai_two_agents()
+    
+    print("\nTesting Agno 2 agents (Team)...")
+    results['agno_two_agents'] = benchmark_agno_two_agents()
+    
+    # 3-Agent Tests
+    print("\n" + "="*70)
+    print("3-AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI 3 agents...")
+    results['praisonai_three_agents'] = benchmark_praisonai_three_agents()
+    
+    print("\nTesting Agno 3 agents (Team)...")
+    results['agno_three_agents'] = benchmark_agno_three_agents()
+    
+    # Summary
+    print("\n" + "="*70)
+    print("RESULTS SUMMARY")
+    print("="*70)
+    
+    print(f"\n{'Test':<20} {'PraisonAI (avg)':<18} {'Agno (avg)':<15} {'Difference':<20}")
+    print("-" * 73)
+    
+    tests = [
+        ('Single Agent', 'praisonai_single', 'agno_single'),
+        ('2 Agents', 'praisonai_two_agents', 'agno_two_agents'),
+        ('3 Agents', 'praisonai_three_agents', 'agno_three_agents'),
+    ]
+    
+    for name, praison_key, agno_key in tests:
+        praison_avg = results[praison_key].avg_time
+        agno_avg = results[agno_key].avg_time
+        
+        if praison_avg < agno_avg:
+            diff = f'PraisonAI {agno_avg/praison_avg:.2f}x faster'
+        else:
+            diff = f'Agno {praison_avg/agno_avg:.2f}x faster'
+        
+        print(f"{name:<20} {praison_avg:<18.2f}s {agno_avg:<15.2f}s {diff:<20}")
+    
+    print("\n" + "="*70)
+    
+    # Save results
+    save_results(results, versions)

src/praisonai-agents/benchmarks/response_benchmark.py

@@ -1,8 +1,10 @@
 """
-Response Time Benchmark: PraisonAI vs Agno
-==========================================
-This benchmark measures actual LLM response time with gpt-4o-mini.
-This is the real-world performance that matters most.
+PraisonAI Agents - Response Time Benchmark
+
+Measures actual LLM response time with gpt-4o-mini across frameworks.
+
+Usage:
+    python benchmarks/response_benchmark.py
 """
 
 import time
@@ -153,10 +155,10 @@ def benchmark_agno_with_tool(iterations: int = 5) -> ResponseResult:
 
 if __name__ == "__main__":
     print("="*70)
-    print("RESPONSE TIME BENCHMARK: PraisonAI vs Agno")
+    print("PraisonAI Agents - Response Time Benchmark")
     print("="*70)
-    print("\nUsing model: gpt-4o-mini")
-    print("This measures actual end-to-end response time including:")
+    print("\nModel: gpt-4o-mini")
+    print("Measures end-to-end response time including:")
     print("  - Agent instantiation")
     print("  - API call to OpenAI")
     print("  - Response processing")
@@ -227,13 +229,7 @@ if __name__ == "__main__":
         print(f"{'With Tool Calling':<30} {p_time:<20.3f}s {a_time:<20.3f}s {ratio:.2f}x")
     
     print("\n" + "="*70)
-    print("ANALYSIS")
+    print("NOTE")
     print("="*70)
-    print("\nNote: Response time is dominated by OpenAI API latency.")
-    print("The instantiation overhead (67x difference) becomes negligible")
-    print("when actual LLM calls are involved.")
-    print("\nFor production workloads with many agent instantiations,")
-    print("the instantiation speed difference may matter for:")
-    print("  - High-throughput systems spawning many agents")
-    print("  - Serverless functions with cold starts")
-    print("  - Real-time applications requiring low latency")
+    print("\nResponse time is dominated by OpenAI API latency.")
+    print("Agent instantiation overhead is negligible in real-world usage.")

src/praisonai-agents/benchmarks/results.console

@@ -0,0 +1,194 @@
+❯ python benchmarks/performance_benchmark.py
+/Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/_warning_patch.py:47: UserWarning: Mixing V1 models and V2 models (or constructs, like `TypeAdapter`) is not supported. Please upgrade `Settings` to V2.
+  _original_warn(message, category, stacklevel, source)
+[13:04:15] INFO     [13:04:15]          config.py:50
+                    config.py:50 INFO               
+                    Using config path:              
+                    /Users/praison/.con             
+                    fig/crewai/settings             
+                    .json                           
+======================================================================
+PraisonAI Agents - Comprehensive Performance Benchmark
+======================================================================
+
+This benchmark measures:
+  1. Agent instantiation time (how fast an agent object is created)
+  2. Memory footprint (how much memory an agent uses)
+
+Methodology:
+  - 10 warmup runs (not measured)
+  - 1000 measured iterations
+  - tracemalloc for memory measurement
+  - Baseline subtraction for accuracy
+
+Frameworks available:
+  - PraisonAI: ✅
+  - Agno: ✅
+  - PydanticAI: ✅
+  - OpenAI Agents SDK: ✅
+  - LangGraph: ✅
+  - CrewAI: ✅
+
+======================================================================
+Testing PraisonAI Agents
+======================================================================
+
+============================================================
+Benchmarking: PraisonAI
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PraisonAI:
+  Average Time: 0.000003 seconds (3.20 μs)
+  Min Time:     0.000003 seconds
+  Max Time:     0.000025 seconds
+  Std Dev:      0.000001 seconds
+  Median Time:  0.000003 seconds
+  Avg Memory:   0.003678 MiB (3.77 KiB)
+
+======================================================================
+Testing PraisonAI Agents (LiteLLM)
+======================================================================
+
+============================================================
+Benchmarking: PraisonAI (LiteLLM)
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PraisonAI (LiteLLM):
+  Average Time: 0.000007 seconds (7.31 μs)
+  Min Time:     0.000007 seconds
+  Max Time:     0.000060 seconds
+  Std Dev:      0.000002 seconds
+  Median Time:  0.000007 seconds
+  Avg Memory:   0.006419 MiB (6.57 KiB)
+
+======================================================================
+Testing Agno
+======================================================================
+
+============================================================
+Benchmarking: Agno
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for Agno:
+  Average Time: 0.000005 seconds (5.30 μs)
+  Min Time:     0.000005 seconds
+  Max Time:     0.000039 seconds
+  Std Dev:      0.000002 seconds
+  Median Time:  0.000005 seconds
+  Avg Memory:   0.006599 MiB (6.76 KiB)
+
+======================================================================
+Testing PydanticAI
+======================================================================
+
+============================================================
+Benchmarking: PydanticAI Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PydanticAI Agent Instantiation:
+  Average Time: 0.000247 seconds (247.34 μs)
+  Min Time:     0.000218 seconds
+  Max Time:     0.000552 seconds
+  Std Dev:      0.000031 seconds
+  Median Time:  0.000237 seconds
+  Avg Memory:   0.028486 MiB (29.17 KiB)
+
+======================================================================
+Testing OpenAI Agents SDK
+======================================================================
+
+============================================================
+Benchmarking: OpenAI Agents SDK Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for OpenAI Agents SDK Instantiation:
+  Average Time: 0.000282 seconds (282.25 μs)
+  Min Time:     0.000247 seconds
+  Max Time:     0.001110 seconds
+  Std Dev:      0.000055 seconds
+  Median Time:  0.000263 seconds
+  Avg Memory:   0.029032 MiB (29.73 KiB)
+
+======================================================================
+Testing LangGraph
+======================================================================
+
+============================================================
+Benchmarking: LangGraph Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for LangGraph Agent Instantiation:
+  Average Time: 0.003200 seconds (3200.15 μs)
+  Min Time:     0.002808 seconds
+  Max Time:     0.116363 seconds
+  Std Dev:      0.003628 seconds
+  Median Time:  0.002972 seconds
+  Avg Memory:   0.207509 MiB (212.49 KiB)
+
+======================================================================
+Testing CrewAI
+======================================================================
+
+============================================================
+Benchmarking: CrewAI Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for CrewAI Agent Instantiation:
+  Average Time: 0.016772 seconds (16771.69 μs)
+  Min Time:     0.014404 seconds
+  Max Time:     0.091841 seconds
+  Std Dev:      0.003445 seconds
+  Median Time:  0.015816 seconds
+  Avg Memory:   0.065050 MiB (66.61 KiB)
+
+======================================================================
+RESULTS SUMMARY
+======================================================================
+
+Framework                 Avg Time (μs)   Avg Memory (KiB)   Relative       
+-------------------------------------------------------------------------
+PraisonAI                 3.20            3.77               1.00x          
+Agno                      5.30            6.76               1.66x          
+PraisonAI (LiteLLM)       7.31            6.57               2.28x          
+PydanticAI                247.34          29.17              77.25x         
+OpenAI Agents SDK         282.25          29.73              88.15x         
+LangGraph                 3200.15         212.49             999.46x        
+CrewAI                    16771.69        66.61              5238.06x       
+
+======================================================================
+❯ 

src/praisonai-agents/benchmarks/simple_benchmark.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Performance Benchmark
+
+Compares agent instantiation times across popular AI agent frameworks.
+
+Usage:
+    python benchmarks/simple_benchmark.py
+"""
+
+import time
+from typing import Literal
+
+
+ITERATIONS = 100
+
+
+def sample_tool(city: Literal['nyc', 'sf']):
+    """Sample tool for benchmark testing."""
+    if city == 'nyc':
+        return 'cloudy'
+    return 'sunny'
+
+
+def measure_instantiation(create_fn, iterations=ITERATIONS):
+    """Measure average instantiation time in microseconds."""
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        create_fn()
+        times.append((time.perf_counter() - start) * 1_000_000)
+    return sum(times) / len(times)
+
+
+def run_benchmark():
+    """Run the benchmark across all available frameworks (without tools)."""
+    results = {}
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Performance Benchmark')
+    print('=' * 60)
+    print(f'\nIterations: {ITERATIONS}')
+    print('Metric: Agent instantiation time (microseconds)\n')
+    
+    # PraisonAI (without tools)
+    print("Testing PraisonAI...")
+    from praisonaiagents import Agent as PraisonAgent
+    
+    results['PraisonAI'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='gpt-4o-mini', verbose=False)
+    )
+    
+    results['PraisonAI (LiteLLM)'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='openai/gpt-4o-mini', verbose=False)
+    )
+    
+    # Other frameworks for comparison
+    print("Testing other frameworks...")
+    
+    try:
+        from agno.agent import Agent as AgnoAgent
+        from agno.models.openai import OpenAIChat
+        results['Agno'] = measure_instantiation(
+            lambda: AgnoAgent(model=OpenAIChat(id='gpt-4o-mini'))
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from pydantic_ai import Agent as PydanticAgent
+        results['PydanticAI'] = measure_instantiation(
+            lambda: PydanticAgent('openai:gpt-4o-mini')
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from agents import Agent as OpenAIAgent
+        results['OpenAI Agents SDK'] = measure_instantiation(
+            lambda: OpenAIAgent(name='Test', model='gpt-4o-mini')
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from langchain_core.tools import tool as langchain_tool
+        from langchain_openai import ChatOpenAI
+        from langgraph.prebuilt import create_react_agent
+        
+        @langchain_tool
+        def get_weather_lg(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['LangGraph'] = measure_instantiation(
+            lambda: create_react_agent(model=ChatOpenAI(model='gpt-4o-mini'), tools=[get_weather_lg])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from crewai.agent import Agent as CrewAgent
+        from crewai.tools import tool as crewai_tool
+        
+        @crewai_tool("Weather Tool")
+        def get_weather_crew(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['CrewAI'] = measure_instantiation(
+            lambda: CrewAgent(
+                role='Weather Agent',
+                goal='Provide weather info',
+                backstory='A weather expert',
+                tools=[get_weather_crew],
+                verbose=False
+            )
+        )
+    except ImportError:
+        pass
+    
+    # Print results
+    print('\n' + '=' * 60)
+    print('RESULTS')
+    print('=' * 60)
+    
+    baseline = results.get('PraisonAI', 1)
+    print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Relative':<10}")
+    print('-' * 50)
+    
+    for name, avg in sorted(results.items(), key=lambda x: x[1]):
+        ratio = avg / baseline
+        print(f'{name:<25} {avg:<15.2f} {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    return results
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    from importlib.metadata import version as get_version
+    
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'PydanticAI': 'pydantic-ai',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_results(results: dict, filename: str = 'BENCHMARK_RESULTS.md'):
+    """Save benchmark results to a markdown file and update README."""
+    import os
+    import re
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), filename)
+    versions = get_package_versions()
+    
+    # Find the fastest result (baseline)
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest_time = sorted_results[0][1] if sorted_results else 1
+    
+    # Build the table rows
+    table_rows = []
+    for name, avg in sorted_results:
+        ratio = avg / fastest_time
+        if ratio == 1.0:
+            table_rows.append(f'| **{name}** | **{avg:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg:,.2f}' if avg >= 1000 else f'{avg:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {name} | {avg_str} | {ratio_str} |')
+    
+    # Save to BENCHMARK_RESULTS.md
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Iterations:** {ITERATIONS}\n')
+        f.write('**Test:** Agent instantiation (without tools)\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/simple_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    
+    # Also update the main README.md
+    readme_path = os.path.join(os.path.dirname(__file__), '..', '..', '..', 'README.md')
+    if os.path.exists(readme_path):
+        update_readme(readme_path, table_rows)
+    
+    return filepath
+
+
+def update_readme(readme_path: str, table_rows: list):
+    """Update the performance section in README.md with latest results."""
+    import re
+    
+    with open(readme_path, 'r') as f:
+        content = f.read()
+    
+    # Build the new table
+    new_table = '''| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+''' + '\n'.join(table_rows)
+    
+    # Pattern to match the performance table
+    pattern = r'(\| Framework \| Avg Time \(μs\) \| Relative \|\n\|[-|]+\|\n)(\|[^\n]+\|\n)+'
+    
+    if re.search(pattern, content):
+        content = re.sub(pattern, new_table + '\n', content)
+        
+        with open(readme_path, 'w') as f:
+            f.write(content)
+        
+        print(f'README.md updated: {readme_path}')
+
+
+if __name__ == '__main__':
+    results = run_benchmark()
+    save_results(results)

src/praisonai-agents/benchmarks/tools_benchmark.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Tools Benchmark
+
+Compares agent instantiation times WITH TOOLS across frameworks.
+
+Usage:
+    python benchmarks/tools_benchmark.py
+"""
+
+import time
+from typing import Literal
+from importlib.metadata import version as get_version
+
+
+ITERATIONS = 100
+
+
+def sample_tool(city: Literal['nyc', 'sf']):
+    """Sample tool for benchmark testing."""
+    if city == 'nyc':
+        return 'cloudy'
+    return 'sunny'
+
+
+def measure_instantiation(create_fn, iterations=ITERATIONS):
+    """Measure average instantiation time in microseconds."""
+    times = []
+    
+    # Warmup
+    for _ in range(10):
+        create_fn()
+    
+    # Measure
+    for _ in range(iterations):
+        start = time.perf_counter()
+        create_fn()
+        elapsed = time.perf_counter() - start
+        times.append(elapsed * 1_000_000)  # Convert to microseconds
+    
+    return sum(times) / len(times)
+
+
+def run_benchmark():
+    """Run the benchmark across all available frameworks WITH TOOLS."""
+    tools = [sample_tool]
+    results = {}
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Tools Benchmark')
+    print('=' * 60)
+    print(f'\nIterations: {ITERATIONS}')
+    print('Metric: Agent instantiation time WITH TOOLS (microseconds)\n')
+    
+    # PraisonAI with tools
+    print("Testing PraisonAI...")
+    from praisonaiagents import Agent as PraisonAgent
+    
+    results['PraisonAI'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='gpt-4o-mini', tools=tools, verbose=False)
+    )
+    
+    results['PraisonAI (LiteLLM)'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='openai/gpt-4o-mini', tools=tools, verbose=False)
+    )
+    
+    # Other frameworks with tools
+    print("Testing other frameworks...")
+    
+    try:
+        from agno.agent import Agent as AgnoAgent
+        from agno.models.openai import OpenAIChat
+        results['Agno'] = measure_instantiation(
+            lambda: AgnoAgent(model=OpenAIChat(id='gpt-4o-mini'), tools=tools)
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from agents import Agent as OpenAIAgent, function_tool
+        results['OpenAI Agents SDK'] = measure_instantiation(
+            lambda: OpenAIAgent(name='Test', model='gpt-4o-mini', tools=[function_tool(sample_tool)])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from langchain_core.tools import tool as langchain_tool
+        from langchain_openai import ChatOpenAI
+        from langgraph.prebuilt import create_react_agent
+        
+        @langchain_tool
+        def get_weather_lg(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['LangGraph'] = measure_instantiation(
+            lambda: create_react_agent(model=ChatOpenAI(model='gpt-4o-mini'), tools=[get_weather_lg])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from crewai.agent import Agent as CrewAgent
+        from crewai.tools import tool as crewai_tool
+        
+        @crewai_tool("Weather Tool")
+        def get_weather_crew(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['CrewAI'] = measure_instantiation(
+            lambda: CrewAgent(
+                role='Weather Agent',
+                goal='Provide weather info',
+                backstory='A weather expert',
+                tools=[get_weather_crew],
+                verbose=False
+            )
+        )
+    except ImportError:
+        pass
+    
+    # Print results
+    print('\n' + '=' * 60)
+    print('RESULTS (WITH TOOLS)')
+    print('=' * 60)
+    
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    baseline = sorted_results[0][1] if sorted_results else 1
+    
+    print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Relative':<10}")
+    print('-' * 50)
+    
+    for name, avg in sorted_results:
+        ratio = avg / baseline
+        print(f'{name:<25} {avg:<15.2f} {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    return results
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_results(results: dict, filename: str = 'TOOLS_BENCHMARK_RESULTS.md'):
+    """Save benchmark results to a markdown file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), filename)
+    versions = get_package_versions()
+    
+    # Find the fastest result (baseline)
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest_time = sorted_results[0][1] if sorted_results else 1
+    
+    # Build the table rows
+    table_rows = []
+    for name, avg in sorted_results:
+        ratio = avg / fastest_time
+        if ratio == 1.0:
+            table_rows.append(f'| **{name}** | **{avg:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg:,.2f}' if avg >= 1000 else f'{avg:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {name} | {avg_str} | {ratio_str} |')
+    
+    # Save to file
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Tools Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Iterations:** {ITERATIONS}\n')
+        f.write('**Test:** Agent instantiation WITH TOOLS\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/tools_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    return filepath
+
+
+if __name__ == '__main__':
+    results = run_benchmark()
+    save_results(results)