Release v2.5.2

- Add praisonai/db/ module that was being ignored by *.db pattern
- This fixes ModuleNotFoundError: No module named 'praisonai.db' in CI tests

.github/workflows/docker-publish.yml

@@ -1,45 +1,54 @@
-name: Daily Publish Docker
+name: Publish Docker
 
 on:
-  push:
-    branches:
-      - main
-  schedule:
-    - cron: '0 0 * * *'
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Docker image tag (default: latest)'
+        required: false
+        default: 'latest'
 
 jobs:
-  check-and-build:
+  build-and-push:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
     
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Check last commit time
-        id: check_commit
-        run: |
-          last_commit_time=$(git log -1 --format=%ct)
-          current_time=$(date +%s)
-          time_diff=$((current_time - last_commit_time))
-          if [ $time_diff -ge 120 ] && [ $time_diff -lt 240 ]; then
-            echo "should_run=true" >> $GITHUB_OUTPUT
-          else
-            echo "should_run=false" >> $GITHUB_OUTPUT
-          fi
+        uses: actions/checkout@v4
 
       - name: Set up Docker Buildx
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/setup-buildx-action@v1
+        uses: docker/setup-buildx-action@v3
 
-      - name: Log in to the GitHub Container Registry
-        if: steps.check_commit.outputs.should_run == 'true'
-        run: echo ${{ secrets.GH_TOKEN }} | docker login ghcr.io -u USERNAME --password-stdin
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/mervinpraison/praisonai
+          tags: |
+            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }}
+            type=raw,value=${{ github.event.inputs.tag || 'latest' }},enable=${{ github.event_name == 'workflow_dispatch' }}
 
       - name: Build and push Docker image
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v5
         with:
           context: .
           file: ./docker/Dockerfile
           push: true
-          tags: ghcr.io/mervinpraison/praisonai:latest
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

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

docker/Dockerfile

@@ -14,9 +14,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN mkdir -p /root/.praison
 
 # Install Python packages (using latest versions)
+# Note: praisonai is installed from PyPI - remove version pin to use latest available
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.3.13" \
+    praisonai \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.13" \
+    "praisonai>=2.5.2" \
     "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.13" \
+    "praisonai>=2.5.2" \
     "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.13" \
+    "praisonai>=2.5.2" \
     "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/async_runs/README.py

@@ -0,0 +1,35 @@
+"""
+Async Runs Examples
+===================
+
+This directory contains examples for the PraisonAI Async Jobs API.
+
+Examples:
+---------
+1. sdk_submit_poll_result.py - Python SDK example for submit/poll/result
+2. cli_submit_poll_result.sh - Bash/curl example for submit/poll/result
+3. idempotency.sh - Demonstrates idempotency key usage
+4. cancel.sh - Demonstrates job cancellation
+5. sse_stream.sh - Demonstrates SSE streaming
+
+Prerequisites:
+--------------
+1. Set OPENAI_API_KEY environment variable
+2. Start the jobs server:
+   
+   cd /path/to/praisonai-package/src/praisonai
+   python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory
+
+3. Run examples:
+   
+   python sdk_submit_poll_result.py
+   bash cli_submit_poll_result.sh
+   bash idempotency.sh
+   bash cancel.sh
+   bash sse_stream.sh
+
+Environment Variables:
+----------------------
+- OPENAI_API_KEY: Required for agent execution
+- PRAISONAI_BASE_URL: API server URL (default: http://127.0.0.1:8005)
+"""

examples/async_runs/cancel.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# CLI Example: Cancel a Running Job
+#
+# This example demonstrates how to cancel a running job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cancel.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Job Cancellation Example"
+echo "============================================================"
+
+# Submit a long-running job
+echo ""
+echo "1. Submitting a job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "Write a detailed essay about the history of computing."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# Wait briefly
+echo ""
+echo "2. Waiting 1 second..."
+sleep 1
+
+# Cancel the job
+echo ""
+echo "3. Cancelling job..."
+CANCEL_RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs/$JOB_ID/cancel")
+STATUS=$(echo "$CANCEL_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+echo "   Status after cancel: $STATUS"
+
+# Verify cancellation
+echo ""
+echo "4. Verification:"
+if [ "$STATUS" = "cancelled" ]; then
+    echo "   ✓ SUCCESS: Job was cancelled"
+else
+    echo "   ℹ Job status: $STATUS (may have completed before cancel)"
+fi
+
+echo ""
+echo "============================================================"
+echo "Cancellation example completed!"
+echo "============================================================"

examples/async_runs/cli_submit_poll_result.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# CLI Example: Submit, Poll, and Get Result for Async Jobs
+#
+# This example demonstrates how to use the PraisonAI CLI to:
+# 1. Submit an async job
+# 2. Check job status
+# 3. Get the result
+#
+# Requirements:
+# - OPENAI_API_KEY environment variable set
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cli_submit_poll_result.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Async Jobs CLI Example"
+echo "============================================================"
+
+# Check if server is running
+echo ""
+echo "Checking server health..."
+if ! curl -s "$API_URL/health" > /dev/null 2>&1; then
+    echo "✗ Server not available at $API_URL"
+    echo "  Start the server with: python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory"
+    exit 1
+fi
+echo "✓ Server is healthy"
+
+# 1. Submit a job
+echo ""
+echo "1. Submitting job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "What is 2+2? Answer with just the number."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# 2. Poll for status
+echo ""
+echo "2. Polling for status..."
+while true; do
+    STATUS_RESPONSE=$(curl -s "$API_URL/api/v1/runs/$JOB_ID")
+    STATUS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+    PROGRESS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['progress']['percentage'])")
+    
+    echo "   Status: $STATUS | Progress: ${PROGRESS}%"
+    
+    if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
+        break
+    fi
+    
+    sleep 2
+done
+
+# 3. Get result
+echo ""
+echo "3. Getting result..."
+if [ "$STATUS" = "succeeded" ]; then
+    RESULT=$(curl -s "$API_URL/api/v1/runs/$JOB_ID/result")
+    echo "   Result: $(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['result'])")"
+    echo "   Duration: $(echo "$RESULT" | python3 -c "import sys,json; print(f\"{json.load(sys.stdin)['duration_seconds']:.2f}s\")")"
+else
+    echo "   Job did not succeed: $STATUS"
+fi
+
+echo ""
+echo "============================================================"
+echo "Example completed!"
+echo "============================================================"

examples/async_runs/idempotency.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# CLI Example: Idempotency Key Usage
+#
+# This example demonstrates how idempotency keys prevent duplicate job submissions.
+# Submitting the same request with the same idempotency key returns the existing job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash idempotency.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+IDEM_KEY="example-idem-key-$(date +%s)"
+
+echo "============================================================"
+echo "PraisonAI Idempotency Key Example"
+echo "============================================================"
+
+# First submission
+echo ""
+echo "1. First submission with Idempotency-Key: $IDEM_KEY"
+RESPONSE1=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "What is 1+1?"}')
+
+JOB_ID1=$(echo "$RESPONSE1" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID1"
+
+# Second submission with same key
+echo ""
+echo "2. Second submission with SAME Idempotency-Key: $IDEM_KEY"
+RESPONSE2=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "Different prompt but same key"}')
+
+JOB_ID2=$(echo "$RESPONSE2" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID2"
+
+# Verify same job ID
+echo ""
+echo "3. Verification:"
+if [ "$JOB_ID1" = "$JOB_ID2" ]; then
+    echo "   ✓ SUCCESS: Same job ID returned (no duplicate created)"
+else
+    echo "   ✗ FAILURE: Different job IDs returned"
+    exit 1
+fi
+
+echo ""
+echo "============================================================"
+echo "Idempotency example completed!"
+echo "============================================================"

examples/async_runs/sdk_submit_poll_result.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+SDK Example: Submit, Poll, and Get Result for Async Jobs
+
+This example demonstrates how to use the PraisonAI Jobs SDK to:
+1. Submit an async job
+2. Poll for status
+3. Get the result
+
+Requirements:
+- OPENAI_API_KEY environment variable set
+- Jobs server running on http://127.0.0.1:8005
+
+Usage:
+    python sdk_submit_poll_result.py
+"""
+
+import os
+import time
+import httpx
+
+# Configuration
+API_URL = os.getenv("PRAISONAI_BASE_URL", "http://127.0.0.1:8005")
+POLL_INTERVAL = 2  # seconds
+
+
+def submit_job(prompt: str, idempotency_key: str = None) -> dict:
+    """Submit a job and return the response."""
+    headers = {}
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    
+    with httpx.Client(timeout=30.0) as client:
+        response = client.post(
+            f"{API_URL}/api/v1/runs",
+            json={"prompt": prompt},
+            headers=headers if headers else None
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def get_status(job_id: str) -> dict:
+    """Get job status."""
+    with httpx.Client(timeout=30.0) as client:
+        response = client.get(f"{API_URL}/api/v1/runs/{job_id}")
+        response.raise_for_status()
+        return response.json()
+
+
+def get_result(job_id: str) -> dict:
+    """Get job result."""
+    with httpx.Client(timeout=30.0) as client:
+        response = client.get(f"{API_URL}/api/v1/runs/{job_id}/result")
+        response.raise_for_status()
+        return response.json()
+
+
+def wait_for_completion(job_id: str, max_wait: int = 120) -> dict:
+    """Poll until job completes."""
+    start = time.time()
+    while time.time() - start < max_wait:
+        status = get_status(job_id)
+        print(f"  Status: {status['status']} | Progress: {status['progress']['percentage']:.0f}%")
+        
+        if status["status"] in ("succeeded", "failed", "cancelled"):
+            return status
+        
+        # Honor retry_after if present
+        wait_time = status.get("retry_after") or POLL_INTERVAL
+        time.sleep(wait_time)
+    
+    raise TimeoutError(f"Job {job_id} did not complete within {max_wait}s")
+
+
+def main():
+    print("=" * 60)
+    print("PraisonAI Async Jobs SDK Example")
+    print("=" * 60)
+    
+    # Check if server is running
+    try:
+        with httpx.Client(timeout=5.0) as client:
+            health = client.get(f"{API_URL}/health")
+            health.raise_for_status()
+            print(f"✓ Server healthy: {health.json()['status']}")
+    except Exception as e:
+        print(f"✗ Server not available at {API_URL}: {e}")
+        print("  Start the server with: python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory")
+        return
+    
+    # 1. Submit a job
+    print("\n1. Submitting job...")
+    prompt = "What is the capital of France? Answer in one word."
+    result = submit_job(prompt)
+    job_id = result["job_id"]
+    print(f"   Job ID: {job_id}")
+    print(f"   Status: {result['status']}")
+    print(f"   Poll URL: {result['poll_url']}")
+    
+    # 2. Wait for completion
+    print("\n2. Waiting for completion...")
+    final_status = wait_for_completion(job_id)
+    print(f"   Final status: {final_status['status']}")
+    
+    # 3. Get result
+    if final_status["status"] == "succeeded":
+        print("\n3. Getting result...")
+        result = get_result(job_id)
+        print(f"   Result: {result['result']}")
+        print(f"   Duration: {result['duration_seconds']:.2f}s")
+    else:
+        print(f"\n3. Job did not succeed: {final_status.get('error', 'Unknown error')}")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/async_runs/sse_stream.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# CLI Example: SSE Streaming
+#
+# This example demonstrates how to stream job progress via Server-Sent Events.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash sse_stream.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI SSE Streaming Example"
+echo "============================================================"
+
+# Submit a job
+echo ""
+echo "1. Submitting job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "Count from 1 to 5."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# Stream progress
+echo ""
+echo "2. Streaming progress (Ctrl+C to stop)..."
+echo "   Connecting to: $API_URL/api/v1/runs/$JOB_ID/stream"
+echo ""
+
+# Use curl to stream SSE events (timeout after 60s)
+curl -s -N --max-time 60 "$API_URL/api/v1/runs/$JOB_ID/stream" | while read -r line; do
+    if [[ "$line" == data:* ]]; then
+        data="${line#data: }"
+        if [ "$data" = "[DONE]" ]; then
+            echo "   Stream completed"
+            break
+        fi
+        echo "   Event: $data"
+    fi
+done
+
+echo ""
+echo "============================================================"
+echo "Streaming example completed!"
+echo "============================================================"

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/Finance_Market_Job_Agents/Ai_Job_Hunting_Assistant.ipynb

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

examples/cookbooks/yaml/aws_bedrock_agents.yaml

@@ -1,10 +1,10 @@
 framework: crewai
 topic: "Technology Research and Content Creation using AWS Bedrock"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   research_specialist:
     role: "Research Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are an experienced technology researcher with deep expertise in analyzing 
       emerging technologies and market trends. You excel at gathering comprehensive 
       information from various sources and synthesizing it into actionable insights.
@@ -35,7 +35,7 @@ roles:
 
   content_creator:
     role: "Technical Content Creator"
-    backstory: |
+    instructions:  # Canonical |
       You are a skilled technical writer and content creator who specializes in 
       translating complex technology concepts into engaging, accessible content 
       for various audiences including developers, business leaders, and end users.
@@ -64,7 +64,7 @@ roles:
 
   quality_reviewer:
     role: "Content Quality Reviewer"
-    backstory: |
+    instructions:  # Canonical |
       You are a meticulous editor and quality assurance specialist with extensive 
       experience in technical content review. You ensure accuracy, clarity, and 
       consistency while maintaining the intended tone and message.

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/cookbooks/yaml/secondary_market_research_agents.yaml

@@ -8,10 +8,10 @@ variables:
   industry: "Electric Vehicles"
   research_focus: "comprehensive market analysis"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   market_overview_specialist:
     role: "Market Overview Specialist" 
-    backstory: |
+    instructions:  # Canonical |
       You are a seasoned market research analyst with 10+ years of experience 
       in analyzing market dynamics, trends, and growth patterns across various 
       industries. You excel at synthesizing complex market data into clear, 
@@ -64,7 +64,7 @@ roles:
 
   competitive_intelligence_analyst:
     role: "Competitive Intelligence Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a competitive intelligence expert specializing in analyzing 
       competitive landscapes, market positioning, and strategic intelligence. 
       You have deep expertise in competitor analysis, market share assessment, 
@@ -119,7 +119,7 @@ roles:
 
   financial_performance_analyst:
     role: "Financial Performance Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a financial analyst with expertise in corporate finance, 
       financial statement analysis, and industry benchmarking. You specialize 
       in analyzing financial performance metrics, trends, and comparative 
@@ -173,7 +173,7 @@ roles:
 
   growth_opportunities_researcher:
     role: "Growth Opportunities Researcher"
-    backstory: |
+    instructions:  # Canonical |
       You are a strategic business analyst specializing in identifying growth 
       opportunities, market expansion strategies, and emerging business models. 
       You excel at spotting trends, gaps, and untapped potential in markets 
@@ -228,7 +228,7 @@ roles:
 
   risk_assessment_specialist:
     role: "Risk Assessment Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are a risk management expert with extensive experience in identifying, 
       analyzing, and assessing business risks across various industries. You 
       specialize in market risks, competitive threats, regulatory challenges, 
@@ -287,7 +287,7 @@ roles:
 
   research_report_synthesizer:
     role: "Research Report Synthesizer"
-    backstory: |
+    instructions:  # Canonical |
       You are an expert business report writer and analyst with extensive 
       experience in synthesizing complex research findings into clear, 
       actionable business intelligence reports. You excel at creating 

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/middleware/basic_middleware.py

@@ -0,0 +1,55 @@
+"""
+Basic Middleware Example - PraisonAI Agents
+
+Demonstrates before/after hooks and wrap decorators for model and tool calls.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.hooks import (
+    before_model, after_model, wrap_model_call,
+    before_tool, after_tool, wrap_tool_call,
+    InvocationContext, ModelRequest, ModelResponse
+)
+
+# Simple tool for demonstration
+@tool
+def get_weather(city: str) -> str:
+    """Get weather for a city."""
+    return f"Sunny, 22°C in {city}"
+
+# Before model hook - adds context
+@before_model
+def add_context(request: ModelRequest) -> ModelRequest:
+    print(f"[before_model] Adding context to request")
+    return request
+
+# After model hook - logs response
+@after_model  
+def log_response(response: ModelResponse) -> ModelResponse:
+    print(f"[after_model] Response received")
+    return response
+
+# Wrap tool call - retry on error
+@wrap_tool_call
+def retry_on_error(tool_call, call_next):
+    print(f"[wrap_tool_call] Executing tool")
+    try:
+        return call_next(tool_call)
+    except Exception as e:
+        print(f"[wrap_tool_call] Retrying after error: {e}")
+        return call_next(tool_call)
+
+# Create agent with hooks
+agent = Agent(
+    name="WeatherBot",
+    instructions="You help with weather queries.",
+    tools=[get_weather],
+    hooks=[add_context, log_response, retry_on_error]
+)
+
+if __name__ == "__main__":
+    # Test the tool directly
+    result = get_weather("London")
+    print(f"Weather: {result}")
+    
+    print("\n✓ Middleware example complete")

examples/middleware/configurable_model.py

@@ -0,0 +1,31 @@
+"""
+Configurable Model Example - PraisonAI Agents
+
+Demonstrates runtime model switching without recreating the agent.
+"""
+
+from praisonaiagents import Agent
+
+# Create agent with configurable model enabled
+agent = Agent(
+    name="FlexBot",
+    instructions="You are a helpful assistant.",
+    llm="gpt-4o-mini",
+    llm_config={"configurable": True}
+)
+
+if __name__ == "__main__":
+    # Default model call
+    print("Using default model (gpt-4o-mini)...")
+    # response = agent.chat("Say hello in 5 words")
+    
+    # Override model per-call
+    print("\nOverriding to different model...")
+    # response = agent.chat("Say hello in 5 words", config={"model": "gpt-4o"})
+    
+    # Override temperature
+    print("\nOverriding temperature...")
+    # response = agent.chat("Say hello creatively", config={"temperature": 0.9})
+    
+    print("\n✓ Configurable model example complete")
+    print("Note: Uncomment agent.chat() calls to run with API key")

examples/middleware/injected_state.py

@@ -0,0 +1,50 @@
+"""
+Injected State Example - PraisonAI Agents
+
+Demonstrates injecting agent state into tools without exposing it in the schema.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.tools import Injected
+from praisonaiagents.tools.injected import AgentState, with_injection_context
+
+# Tool with injected state - state param is NOT in the public schema
+@tool
+def show_context(query: str, state: Injected[dict]) -> str:
+    """Show the current agent context."""
+    session_id = state.get('session_id', 'unknown')
+    agent_id = state.get('agent_id', 'unknown')
+    return f"Query: {query}, Session: {session_id}, Agent: {agent_id}"
+
+# Create agent with the tool
+agent = Agent(
+    name="ContextBot",
+    instructions="You help show context information.",
+    tools=[show_context],
+    session_id="my-session-123"
+)
+
+if __name__ == "__main__":
+    # Verify injected param is not in schema
+    schema = show_context.get_schema()
+    params = schema['function']['parameters']['properties']
+    print(f"Schema params: {list(params.keys())}")
+    assert 'state' not in params, "state should NOT be in schema"
+    print("✓ 'state' correctly excluded from schema")
+    
+    # Test with manual injection context
+    mock_state = AgentState(
+        agent_id="test-agent",
+        run_id="run-1",
+        session_id="session-abc"
+    )
+    
+    with with_injection_context(mock_state):
+        result = show_context(query="hello")
+        print(f"Result: {result}")
+    
+    # Test via agent.execute_tool
+    result = agent.execute_tool("show_context", {"query": "test"})
+    print(f"Agent result: {result}")
+    
+    print("\n✓ Injected state example complete")

examples/middleware/rate_limiter.py

@@ -0,0 +1,29 @@
+"""
+Rate Limiter Example - PraisonAI Agents
+
+Demonstrates token bucket rate limiting for LLM API calls.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.llm import RateLimiter
+
+# Create rate limiter: 60 requests per minute
+limiter = RateLimiter(requests_per_minute=60, burst=5)
+
+# Create agent with rate limiter
+agent = Agent(
+    name="RateLimitedBot",
+    instructions="You are a helpful assistant.",
+    rate_limiter=limiter
+)
+
+if __name__ == "__main__":
+    print(f"Rate limiter: {limiter}")
+    print(f"Available tokens: {limiter.available_tokens}")
+    
+    # Demonstrate rate limiting
+    for i in range(3):
+        limiter.acquire()
+        print(f"Request {i+1} acquired, tokens left: {limiter.available_tokens:.1f}")
+    
+    print("\n✓ Rate limiter example complete")

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,71 @@
+"""
+Qdrant Knowledge Store - Agent-First Example
+
+Demonstrates using Qdrant for knowledge-based RAG with an Agent.
+
+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:
+    Agent responds using knowledge from documents
+"""
+
+from praisonaiagents import Agent
+import tempfile
+import os
+import shutil
+
+# Create sample knowledge document
+sample_doc = """
+# AI and Programming Guide
+
+## Python Programming
+Python is a versatile programming language used for web development, data science, and AI.
+It has a simple syntax and extensive libraries.
+
+## Machine Learning
+Machine learning enables computers to learn patterns from data without explicit programming.
+Common frameworks include TensorFlow, PyTorch, and scikit-learn.
+
+## Databases
+PostgreSQL is a powerful open-source relational database system.
+It supports both SQL and JSON data types.
+"""
+
+# Save to temp file
+temp_dir = tempfile.mkdtemp()
+doc_path = os.path.join(temp_dir, "guide.txt")
+with open(doc_path, "w") as f:
+    f.write(sample_doc)
+
+print("=== Qdrant Knowledge Store Demo (Agent-First) ===")
+
+# Agent-first approach: use knowledge parameter with Qdrant
+agent = Agent(
+    name="KnowledgeAssistant",
+    instructions="You are a helpful assistant with access to technical documentation.",
+    knowledge=[doc_path],
+    knowledge_config={
+        "vector_store": "qdrant",
+        "url": "http://localhost:6333"
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What programming language is good for AI?")
+print(f"Response: {response}")
+
+# Cleanup
+shutil.rmtree(temp_dir)
+
+print("\n=== Demo Complete ===")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence.factory import create_knowledge_store
+# store = create_knowledge_store("qdrant", url="http://localhost:6333")

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,46 @@
+"""
+Redis State Store - Agent-First Example
+
+Use Redis for state management with an Agent.
+
+Docker Setup:
+    docker run -d --name redis -p 6379:6379 redis:7
+
+Run:
+    python redis_state.py
+
+Expected output:
+    Agent responds with state persisted to Redis
+"""
+
+from praisonaiagents import Agent, db
+
+print("=== Redis State Store (Agent-First) ===")
+
+# Agent-first approach: use db parameter with Redis state store
+my_db = db(
+    database_url="sqlite:///conversations.db",  # Conversations
+    state_url="redis://localhost:6379"          # State/tracing
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    db=my_db,
+    session_id="redis-state-session"
+)
+
+# Chat - state is automatically managed via Redis
+response = agent.chat("Hello! Remember my name is Alice.")
+print(f"Response: {response}")
+
+# Second message to test state
+response2 = agent.chat("What is my name?")
+print(f"Response: {response2}")
+
+my_db.close()
+print("\n✅ Done")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonaiagents import db
+# redis_db = db.RedisDB(host="localhost", port=6379)

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,58 @@
+"""
+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, db
+
+# Create database adapter (simplified import)
+db_instance = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai"
+)
+
+# Create agent with persistence enabled
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant. Keep responses brief.",
+    db=db_instance,
+    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_instance.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,46 @@
+"""
+Redis State Store - Agent-First Example
+
+Use Redis for state management with an Agent.
+
+Docker Setup:
+    docker run -d --name praison-redis -p 6379:6379 redis:7
+
+Run:
+    python state_redis.py
+
+Expected Output:
+    Agent responds with state persisted to Redis
+"""
+
+from praisonaiagents import Agent, db
+
+print("=== Redis State Store (Agent-First) ===")
+
+# Agent-first approach: use db parameter with Redis state store
+my_db = db(
+    database_url="sqlite:///conversations.db",  # Conversations
+    state_url="redis://localhost:6379"          # State/tracing
+)
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    db=my_db,
+    session_id="redis-state-example"
+)
+
+# Chat - state is automatically managed via Redis
+response = agent.chat("Hello! Remember my favorite color is blue.")
+print(f"Response: {response}")
+
+# Second message to test state
+response2 = agent.chat("What is my favorite color?")
+print(f"Response: {response2}")
+
+my_db.close()
+print("\n=== Demo Complete ===")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence.factory import create_state_store
+# store = create_state_store("redis", url="redis://localhost:6379")

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/knowledge/advanced-knowledge-management.py

@@ -15,6 +15,7 @@ Features demonstrated:
 from praisonaiagents import Agent
 import tempfile
 import os
+import shutil
 
 # Create a sample knowledge document for demonstration
 sample_document = """
@@ -91,38 +92,15 @@ doc_path = os.path.join(temp_dir, "ai_healthcare_guide.txt")
 with open(doc_path, "w") as f:
     f.write(sample_document)
 
-# Create an agent with advanced knowledge management configuration
+# Create an agent with knowledge management
 knowledge_agent = Agent(
     name="AdvancedKnowledgeAgent",
     role="Healthcare AI Knowledge Expert", 
     goal="Provide comprehensive answers about AI in healthcare using advanced knowledge retrieval",
     backstory="You are an expert in healthcare AI with access to comprehensive knowledge bases and advanced retrieval capabilities.",
     
-    # Advanced knowledge configuration
+    # Knowledge configuration - simple and working
     knowledge=[doc_path],
-    knowledge_config={
-        "vector_store": {
-            "provider": "chroma",
-            "collection_name": "healthcare_ai_knowledge"
-        },
-        "chunking": {
-            "strategy": "semantic",  # Advanced semantic chunking
-            "chunk_size": 500,       # Optimal chunk size for retrieval
-            "chunk_overlap": 50,     # Overlap for context preservation
-            "separators": ["\n\n", "\n", ".", "!", "?"]  # Smart separators
-        },
-        "retrieval": {
-            "search_type": "similarity",
-            "k": 5,  # Retrieve top 5 most relevant chunks
-            "score_threshold": 0.7,  # Minimum relevance score
-            "rerank": True  # Enable reranking for better results
-        },
-        "embedding": {
-            "provider": "openai",
-            "model": "text-embedding-3-small",  # Efficient embedding model
-            "dimensions": 1536
-        }
-    },
     
     instructions="""You are an expert in healthcare AI. Use the knowledge base to provide 
     comprehensive, accurate answers. Always cite specific information from the documents 
@@ -180,7 +158,6 @@ relationship_result = knowledge_agent.start(
 print(f"Relationship analysis result:\n{relationship_result}\n")
 
 # Clean up temporary files
-import shutil
 shutil.rmtree(temp_dir)
 
 print("="*80)

examples/python/mcp/multiple-mcp-servers.py

@@ -0,0 +1,108 @@
+"""
+Multiple MCP Servers Example
+
+This example demonstrates how to use multiple MCP servers with a single agent.
+You can combine different MCP servers (time, memory, filesystem, etc.) along
+with regular Python functions as tools.
+
+Requirements:
+- pip install praisonaiagents
+- uvx (for mcp-server-time)
+- npx (for @modelcontextprotocol servers)
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.mcp import MCP
+
+
+def my_custom_tool(query: str) -> str:
+    """
+    A custom Python function that can be used alongside MCP tools.
+    
+    Args:
+        query: The search query
+        
+    Returns:
+        A formatted result string
+    """
+    return f"Custom tool result for: {query}"
+
+
+def main():
+    # Example 1: Single MCP server (basic usage)
+    print("=" * 60)
+    print("Example 1: Single MCP Server")
+    print("=" * 60)
+    
+    agent_single = Agent(
+        name="TimeAgent",
+        instructions="You are a helpful assistant that can tell time.",
+        tools=MCP("uvx mcp-server-time")
+    )
+    
+    response = agent_single.start("What time is it in Tokyo?")
+    print(f"Response: {response}\n")
+    
+    # Example 2: Multiple MCP servers
+    print("=" * 60)
+    print("Example 2: Multiple MCP Servers")
+    print("=" * 60)
+    
+    agent_multi = Agent(
+        name="MultiMCPAgent",
+        instructions="""You are a helpful assistant with access to multiple tools:
+        - Time tools for getting current time and converting timezones
+        - Memory tools for storing and retrieving information
+        Use the appropriate tool based on the user's request.""",
+        tools=[
+            MCP("uvx mcp-server-time"),                     # Time tools
+            MCP("npx @modelcontextprotocol/server-memory"), # Memory tools
+        ]
+    )
+    
+    response = agent_multi.start("What time is it in New York and London?")
+    print(f"Response: {response}\n")
+    
+    # Example 3: Multiple MCP servers + custom functions
+    print("=" * 60)
+    print("Example 3: MCP Servers + Custom Functions")
+    print("=" * 60)
+    
+    agent_mixed = Agent(
+        name="MixedToolsAgent",
+        instructions="""You are a helpful assistant with access to:
+        - Time tools for timezone operations
+        - A custom search tool for general queries
+        Choose the right tool for each task.""",
+        tools=[
+            MCP("uvx mcp-server-time"),  # MCP server
+            my_custom_tool                # Regular Python function
+        ]
+    )
+    
+    response = agent_mixed.start("What time is it in Paris?")
+    print(f"Response: {response}\n")
+    
+    # Example 4: MCP with environment variables
+    print("=" * 60)
+    print("Example 4: MCP with Environment Variables")
+    print("=" * 60)
+    
+    # Note: Replace with your actual API key
+    # agent_with_env = Agent(
+    #     name="SearchAgent",
+    #     instructions="You can search the web for information.",
+    #     tools=[
+    #         MCP(
+    #             command="npx",
+    #             args=["-y", "@modelcontextprotocol/server-brave-search"],
+    #             env={"BRAVE_API_KEY": "your-api-key-here"}
+    #         ),
+    #         MCP("uvx mcp-server-time")
+    #     ]
+    # )
+    print("(Skipped - requires BRAVE_API_KEY)")
+
+
+if __name__ == "__main__":
+    main()

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/python/tools/e2b/agents.yaml

@@ -1,8 +1,8 @@
 framework: praisonai
 topic: crawl and extract all data from each url from this page https://news.ycombinator.com/
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   web_scraper:
-    backstory: An expert in data extraction from websites, adept at navigating and
+    instructions:  # Canonical An expert in data extraction from websites, adept at navigating and
       retrieving detailed information.
     goal: Extract URLs from the source page
     role: Web Scraper
@@ -15,7 +15,7 @@ roles:
     tools:
     - 'code_interpret'
   url_data_extractor:
-    backstory: Specializes in crawling websites to gather comprehensive data, ensuring
+    instructions:  # Canonical Specializes in crawling websites to gather comprehensive data, ensuring
       nothing is missed from each link.
     goal: Crawl each URL for data extraction
     role: URL Data Extractor
@@ -29,7 +29,7 @@ roles:
     tools:
     - 'code_interpret'
   data_organizer:
-    backstory: Known for keen attention to detail, capable of structuring vast amounts
+    instructions:  # Canonical Known for keen attention to detail, capable of structuring vast amounts
       of information into usable formats efficiently.
     goal: Organize extracted data into a structured format
     role: Data Organizer

examples/python/workflows/simple_workflow.py

@@ -0,0 +1,38 @@
+"""
+Simple Agentic Workflow Example
+
+Demonstrates using Agent instances directly as workflow steps.
+Each agent processes the input and passes output to the next agent.
+"""
+
+from praisonaiagents import Agent, Workflow
+
+# Create agents with specific roles
+researcher = Agent(
+    name="Researcher",
+    role="Research Analyst",
+    goal="Research and provide information about topics",
+    instructions="You are a research analyst. Provide concise, factual information."
+)
+
+writer = Agent(
+    name="Writer", 
+    role="Content Writer",
+    goal="Write engaging content based on research",
+    instructions="You are a content writer. Write clear, engaging content based on the research provided."
+)
+
+# Create workflow with agents as steps
+workflow = Workflow(
+    name="Simple Agentic Pipeline",
+    steps=[researcher, writer]
+)
+
+if __name__ == "__main__":
+    # Run workflow - agents process sequentially
+    result = workflow.start(
+        "What are the key benefits of AI agents?",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")

examples/python/workflows/simple_workflow_non_agentic.py

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

examples/python/workflows/task_callbacks.py

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

examples/python/workflows/workflow_branching.py

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

examples/python/workflows/workflow_checkpoints.py

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

examples/python/workflows/workflow_conditional.py

@@ -0,0 +1,83 @@
+"""
+Agentic Conditional Workflow Example
+
+Demonstrates using should_run to conditionally execute agent steps
+based on input or previous results.
+"""
+
+from praisonaiagents import Agent, Workflow, WorkflowStep
+
+# Condition functions
+def is_technical(ctx) -> bool:
+    """Only run technical review for technical content."""
+    keywords = ["code", "programming", "algorithm", "database", "api"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
+
+def needs_creative(ctx) -> bool:
+    """Only run creative enhancement for creative content."""
+    keywords = ["story", "poem", "creative", "write", "narrative"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
+
+# Create agents
+analyzer = Agent(
+    name="Analyzer",
+    role="Content Analyzer",
+    goal="Analyze and process content",
+    instructions="Analyze the given content and provide insights."
+)
+
+tech_reviewer = Agent(
+    name="TechReviewer",
+    role="Technical Reviewer",
+    goal="Review technical content",
+    instructions="Review the technical aspects and provide technical feedback."
+)
+
+creative_enhancer = Agent(
+    name="CreativeEnhancer",
+    role="Creative Enhancer",
+    goal="Enhance creative content",
+    instructions="Enhance the creative aspects and make it more engaging."
+)
+
+finalizer = Agent(
+    name="Finalizer",
+    role="Content Finalizer",
+    goal="Finalize the content",
+    instructions="Provide the final polished version of the content."
+)
+
+# Create workflow with conditional steps
+workflow = Workflow(
+    name="Conditional Agentic Pipeline",
+    steps=[
+        analyzer,  # Always runs
+        WorkflowStep(
+            name="tech_review",
+            agent=tech_reviewer,
+            should_run=is_technical  # Only runs for technical content
+        ),
+        WorkflowStep(
+            name="creative_enhance",
+            agent=creative_enhancer,
+            should_run=needs_creative  # Only runs for creative content
+        ),
+        finalizer  # Always runs
+    ]
+)
+
+if __name__ == "__main__":
+    # Test 1: Technical content
+    print("=== Test 1: Technical Content ===")
+    result = workflow.start("Review this Python code for best practices", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
+    
+    # Test 2: Creative content
+    print("=== Test 2: Creative Content ===")
+    result = workflow.start("Write a short story about a robot", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
+    
+    # Test 3: General content (neither technical nor creative)
+    print("=== Test 3: General Content ===")
+    result = workflow.start("What is the weather like today?", verbose=True)
+    print(f"Output: {result['output'][:200]}...")

examples/python/workflows/workflow_conditional_non_agentic.py

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

examples/python/workflows/workflow_early_stop.py

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

examples/python/workflows/workflow_loop_csv.py

@@ -0,0 +1,59 @@
+"""
+Agentic Loop with CSV Workflow Example
+
+Demonstrates iterating over a CSV file with an agent processing each row.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file content
+csv_content = """topic,description
+AI Ethics,Ethical considerations in artificial intelligence
+Machine Learning,Algorithms that learn from data
+Neural Networks,Computing systems inspired by biological neural networks
+Natural Language Processing,AI understanding human language"""
+
+# Create processor agent
+processor = Agent(
+    name="TopicProcessor",
+    role="Topic Analyst",
+    goal="Analyze and explain topics",
+    instructions="Provide a brief, insightful analysis of the given topic."
+)
+
+# Create summarizer agent
+summarizer = Agent(
+    name="Summarizer",
+    role="Results Summarizer",
+    goal="Summarize all processed results",
+    instructions="Create a comprehensive summary of all the analyzed topics."
+)
+
+if __name__ == "__main__":
+    # Create temp CSV file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(csv_content)
+        csv_path = f.name
+    
+    try:
+        print("=== Testing Agentic Loop with CSV ===\n")
+        print(f"Processing CSV: {csv_path}\n")
+        
+        # Create workflow with loop over CSV
+        workflow = Workflow(
+            name="CSV Topic Processor",
+            steps=[
+                loop(processor, from_csv=csv_path),
+                summarizer
+            ]
+        )
+        
+        result = workflow.start("Analyze these AI topics", verbose=True)
+        
+        print(f"\nFinal Summary:\n{result['output']}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_csv_non_agentic.py

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

examples/python/workflows/workflow_loop_list.py

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

examples/python/workflows/workflow_loops.py

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

examples/python/workflows/workflow_mixed_steps.py

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

examples/python/workflows/workflow_parallel.py

@@ -0,0 +1,56 @@
+"""
+Agentic Parallel Workflow Example
+
+Demonstrates running multiple agents concurrently and
+combining their results with an aggregator agent.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import parallel
+
+# Create parallel research agents
+market_researcher = Agent(
+    name="MarketResearcher",
+    role="Market Research Analyst",
+    goal="Research market trends and opportunities",
+    instructions="Analyze market trends. Provide concise market insights."
+)
+
+competitor_researcher = Agent(
+    name="CompetitorResearcher", 
+    role="Competitive Intelligence Analyst",
+    goal="Research competitor strategies",
+    instructions="Analyze competitors. Provide key competitive insights."
+)
+
+customer_researcher = Agent(
+    name="CustomerResearcher",
+    role="Customer Research Analyst", 
+    goal="Research customer needs and behaviors",
+    instructions="Analyze customer segments. Provide customer insights."
+)
+
+# Create aggregator agent
+aggregator = Agent(
+    name="Aggregator",
+    role="Research Synthesizer",
+    goal="Synthesize research findings",
+    instructions="Combine all research findings into a comprehensive summary."
+)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research Pipeline",
+    steps=[
+        parallel([market_researcher, competitor_researcher, customer_researcher]),
+        aggregator
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Parallel Workflow ===\n")
+    
+    # Run workflow - all researchers work in parallel, then aggregator summarizes
+    result = workflow.start("Research the AI industry", verbose=True)
+    
+    print(f"\nFinal Summary:\n{result['output']}")

examples/python/workflows/workflow_parallel_non_agentic.py

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

examples/python/workflows/workflow_repeat.py

@@ -0,0 +1,53 @@
+"""
+Agentic Evaluator-Optimizer (Repeat) Workflow Example
+
+Demonstrates the evaluator-optimizer pattern where an agent
+generates content and another evaluates it, repeating until approved.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import repeat
+
+# Create generator agent
+generator = Agent(
+    name="Generator",
+    role="Content Generator",
+    goal="Generate high-quality content",
+    instructions="Generate content based on the topic. Improve based on feedback if provided."
+)
+
+# Create evaluator agent  
+evaluator = Agent(
+    name="Evaluator",
+    role="Content Evaluator",
+    goal="Evaluate and provide feedback on content",
+    instructions="Evaluate the content quality. If good, respond with 'APPROVED'. Otherwise provide specific feedback for improvement."
+)
+
+# Evaluation function to check if content is approved
+def is_approved(ctx) -> bool:
+    return "approved" in ctx.previous_result.lower()
+
+# Create workflow with evaluator-optimizer pattern
+workflow = Workflow(
+    name="Evaluator-Optimizer Pipeline",
+    steps=[
+        generator,  # First, generate content
+        repeat(
+            evaluator,  # Evaluate and provide feedback
+            until=is_approved,
+            max_iterations=3
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Evaluator-Optimizer Workflow ===\n")
+    
+    # Run optimization workflow
+    result = workflow.start(
+        "Write a compelling product description for an AI assistant",
+        verbose=True
+    )
+    
+    print(f"\nFinal Result:\n{result['output']}")

examples/python/workflows/workflow_repeat_non_agentic.py

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

examples/python/workflows/workflow_routing.py

@@ -0,0 +1,65 @@
+"""
+Agentic Routing Workflow Example
+
+Demonstrates decision-based routing where an agent classifier
+routes to specialized handler agents based on the request type.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import route
+
+# Create classifier agent
+classifier = Agent(
+    name="Classifier",
+    role="Request Classifier",
+    goal="Classify incoming requests",
+    instructions="Classify the request. Respond with ONLY 'technical', 'creative', or 'general'."
+)
+
+# Create specialized handler agents
+tech_agent = Agent(
+    name="TechExpert",
+    role="Technical Expert",
+    goal="Handle technical questions",
+    instructions="You are a technical expert. Provide detailed technical answers."
+)
+
+creative_agent = Agent(
+    name="CreativeWriter",
+    role="Creative Writer", 
+    goal="Handle creative requests",
+    instructions="You are a creative writer. Write engaging, creative content."
+)
+
+general_agent = Agent(
+    name="GeneralAssistant",
+    role="General Assistant",
+    goal="Handle general requests",
+    instructions="You are a helpful assistant. Provide clear, helpful responses."
+)
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Agentic Router",
+    steps=[
+        classifier,
+        route({
+            "technical": [tech_agent],
+            "creative": [creative_agent],
+            "default": [general_agent]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Routing Workflow ===\n")
+    
+    # Test 1: Technical question
+    print("--- Technical Request ---")
+    result = workflow.start("How does machine learning work?", verbose=True)
+    print(f"Result: {result['output'][:200]}...\n")
+    
+    # Test 2: Creative request
+    print("--- Creative Request ---")
+    result = workflow.start("Write a poem about the ocean", verbose=True)
+    print(f"Result: {result['output'][:200]}...")

examples/python/workflows/workflow_routing_non_agentic.py

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

examples/python/workflows/workflow_with_agents.py

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

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