Release v2.7.7

- Add doctor examples to main README with documentation link
- Sort checks by category in list_available_checks()
- Update registry method call from list_checks() to get_all_checks()
- Remove unused results variable in run_environment_checks()
- Fix f-string formatting in CI integration print statement

.github/workflows/test-quick-debug.yml

@@ -0,0 +1,68 @@
+name: Quick Debug Tests
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  debug-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+
+    - name: Install UV
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+    - name: Install dependencies
+      run: |
+        cd src/praisonai
+        uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
+        uv pip install --system duckduckgo_search
+        uv pip install --system pytest pytest-cov pytest-asyncio pytest-timeout
+        uv pip install --system "praisonaiagents[knowledge]"
+
+    - name: Set environment variables
+      run: |
+        echo "OPENAI_API_KEY=sk-test-key-for-github-actions-testing-only-not-real" >> $GITHUB_ENV
+        echo "OPENAI_API_BASE=https://api.openai.com/v1" >> $GITHUB_ENV
+        echo "OPENAI_MODEL_NAME=gpt-4o-mini" >> $GITHUB_ENV
+        echo "LOGLEVEL=WARNING" >> $GITHUB_ENV
+        echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV
+
+    - name: Run Unit Tests
+      id: pytest
+      run: |
+        cd src/praisonai
+        # Run pytest and save output, don't fail immediately
+        python -m pytest tests/unit/ -v --tb=short > test_output.txt 2>&1 || echo "TESTS_FAILED=true" >> $GITHUB_ENV
+        
+    - name: Show Test Results
+      if: always()
+      run: |
+        cd src/praisonai
+        echo "=========================================="
+        echo "=== FULL TEST OUTPUT ==="
+        echo "=========================================="
+        cat test_output.txt
+        echo ""
+        echo "=========================================="
+        echo "=== FAILED TESTS SUMMARY ==="
+        echo "=========================================="
+        grep "^FAILED" test_output.txt || echo "No FAILED lines"
+        echo ""
+        # Fail if tests failed
+        if [ "$TESTS_FAILED" = "true" ]; then
+          echo "Tests failed!"
+          exit 1
+        fi

README.md

@@ -2359,6 +2359,24 @@ agent = Agent(
 | 🌐 Web Search - Real-time search | [📖](https://docs.praison.ai/docs/cli/web-search) |
 | 📥 Web Fetch - URL content retrieval | [📖](https://docs.praison.ai/docs/cli/web-fetch) |
 | 💾 Prompt Caching - Cost reduction | [📖](https://docs.praison.ai/docs/cli/prompt-caching) |
+| 📦 Template Catalog - Browse & discover templates | [📖](https://docs.praison.ai/docs/cli/template-catalog) |
+
+### Template Catalog CLI
+
+| Command | Description |
+|---------|-------------|
+| `praisonai templates browse` | Open template catalog in browser |
+| `praisonai templates browse --print` | Print catalog URL only |
+| `praisonai templates validate` | Validate template YAML files |
+| `praisonai templates validate --source <dir>` | Validate specific directory |
+| `praisonai templates validate --strict` | Strict validation mode |
+| `praisonai templates validate --json` | JSON output format |
+| `praisonai templates catalog build` | Build catalog locally |
+| `praisonai templates catalog build --out <dir>` | Build to specific directory |
+| `praisonai templates catalog sync` | Sync template sources |
+| `praisonai templates catalog sync --source <name>` | Sync specific source |
+
+**Examples:** [examples/catalog/](examples/catalog/) | **Docs:** [Code](https://docs.praison.ai/docs/cli/template-catalog-code) | [CLI](https://docs.praison.ai/docs/cli/template-catalog)
 
 ---
 

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.7.0" \
+    "praisonai>=2.7.7" \
     "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.7.0" \
+    "praisonai>=2.7.7" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

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

examples/README.md

@@ -14,6 +14,7 @@ examples/
 │   ├── memory/       # Memory and sessions
 │   ├── code/         # Code editing and external CLI tools
 │   └── ...
+├── serve/            # Server and endpoints examples
 ├── yaml/             # YAML workflow examples
 └── cookbooks/        # Complete use-case examples
 ```
@@ -30,6 +31,23 @@ examples/
 | **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) |
+| **Doctor** | [doctor/](doctor/) | [📖](https://docs.praison.ai/cli/doctor) |
+| **Serve** | [serve/](serve/) | [📖](https://docs.praison.ai/cli/serve) |
+| **Endpoints** | [serve/](serve/) | [📖](https://docs.praison.ai/cli/endpoints) |
+
+## Serve Examples
+
+| Example | Description | CLI Command |
+|---------|-------------|-------------|
+| [unified_server.py](serve/unified_server.py) | All providers in one server | `praisonai serve unified` |
+| [agent_as_api_single.py](serve/agent_as_api_single.py) | Single agent HTTP API | `praisonai serve agents` |
+| [agents_as_api_router.py](serve/agents_as_api_router.py) | Multi-agent router API | `praisonai serve agents` |
+| [a2a_server_client.py](serve/a2a_server_client.py) | A2A protocol server | `praisonai serve a2a` |
+| [a2u_events_stream.py](serve/a2u_events_stream.py) | A2U event stream | `praisonai serve a2u` |
+| [mcp_http_server.py](serve/mcp_http_server.py) | MCP HTTP server | `praisonai serve mcp` |
+| [tools_as_mcp_server.py](serve/tools_as_mcp_server.py) | Tools as MCP server | `praisonai serve tools` |
+| [agent_launch_modes.py](serve/agent_launch_modes.py) | Agent.launch() API | Python only |
+| [endpoints_unified_client.py](serve/endpoints_unified_client.py) | Unified client | `praisonai endpoints` |
 
 ## Running Examples
 

examples/catalog/fetch_templates.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Example: Fetch and search PraisonAI templates from the catalog.
+
+This example demonstrates how to:
+- Fetch templates.json from the deployed catalog
+- Search templates by keyword
+- Filter by tags and requirements
+- Generate CLI commands
+"""
+
+import json
+import urllib.request
+from typing import List, Dict, Any, Optional
+
+CATALOG_URL = "https://mervinpraison.github.io/praisonai-template-catalog/data/templates.json"
+
+
+def fetch_catalog(url: str = CATALOG_URL) -> Dict[str, Any]:
+    """Fetch the template catalog from URL."""
+    try:
+        with urllib.request.urlopen(url, timeout=10) as response:
+            return json.loads(response.read().decode())
+    except Exception as e:
+        print(f"Failed to fetch catalog: {e}")
+        # Return empty catalog on failure
+        return {"version": "0.0.0", "count": 0, "templates": []}
+
+
+def search_templates(templates: List[Dict], query: str) -> List[Dict]:
+    """Search templates by name, description, or tags."""
+    query = query.lower()
+    results = []
+    for t in templates:
+        if (query in t.get("name", "").lower() or 
+            query in t.get("description", "").lower() or
+            any(query in tag.lower() for tag in t.get("tags", []))):
+            results.append(t)
+    return results
+
+
+def filter_by_tags(templates: List[Dict], tags: List[str]) -> List[Dict]:
+    """Filter templates that have all specified tags."""
+    return [
+        t for t in templates
+        if all(tag in t.get("tags", []) for tag in tags)
+    ]
+
+
+def filter_by_tool(templates: List[Dict], tool_name: str) -> List[Dict]:
+    """Filter templates that require a specific tool."""
+    return [
+        t for t in templates
+        if tool_name in t.get("requires", {}).get("tools", [])
+    ]
+
+
+def get_template(templates: List[Dict], name: str) -> Optional[Dict]:
+    """Get a template by name."""
+    for t in templates:
+        if t.get("name") == name:
+            return t
+    return None
+
+
+def generate_cli_command(template: Dict, action: str = "run") -> str:
+    """Generate CLI command for a template."""
+    name = template.get("name", "unknown")
+    if action == "run":
+        return f"praisonai templates run {name}"
+    elif action == "info":
+        return f"praisonai templates info {name}"
+    elif action == "init":
+        return f"praisonai templates init my-project --template {name}"
+    return f"praisonai templates {action} {name}"
+
+
+def print_template_summary(template: Dict):
+    """Print a summary of a template."""
+    print(f"\n{'='*60}")
+    print(f"Name: {template.get('name')}")
+    print(f"Version: {template.get('version')}")
+    print(f"Description: {template.get('description', '')[:100]}...")
+    print(f"Tags: {', '.join(template.get('tags', []))}")
+    
+    requires = template.get("requires", {})
+    if requires.get("tools"):
+        print(f"Tools: {', '.join(requires['tools'])}")
+    if requires.get("packages"):
+        print(f"Packages: {', '.join(requires['packages'])}")
+    if requires.get("env"):
+        print(f"Env vars: {', '.join(requires['env'])}")
+    
+    print(f"\nRun: {generate_cli_command(template, 'run')}")
+    print(f"{'='*60}")
+
+
+def main():
+    print("PraisonAI Template Catalog - Python Example")
+    print("-" * 45)
+    
+    # Fetch catalog
+    print("\n1. Fetching template catalog...")
+    catalog = fetch_catalog()
+    templates = catalog.get("templates", [])
+    
+    print(f"   Catalog version: {catalog.get('version', 'unknown')}")
+    print(f"   Total templates: {len(templates)}")
+    
+    if not templates:
+        print("   No templates found. The catalog may not be deployed yet.")
+        print("   Try building locally: praisonai templates catalog build")
+        return
+    
+    # List all templates
+    print("\n2. Available templates:")
+    for t in templates:
+        print(f"   - {t.get('name')} (v{t.get('version')})")
+    
+    # Search for video templates
+    print("\n3. Searching for 'video' templates...")
+    video_templates = search_templates(templates, "video")
+    print(f"   Found {len(video_templates)} video templates:")
+    for t in video_templates:
+        print(f"   - {t.get('name')}: {t.get('description', '')[:50]}...")
+    
+    # Filter by tool
+    print("\n4. Templates using 'shell_tool':")
+    shell_templates = filter_by_tool(templates, "shell_tool")
+    for t in shell_templates:
+        print(f"   - {t.get('name')}")
+    
+    # Get specific template details
+    if templates:
+        first_template = templates[0]
+        print(f"\n5. Template details for '{first_template.get('name')}':")
+        print_template_summary(first_template)
+    
+    # Generate CLI commands
+    print("\n6. CLI commands for all templates:")
+    for t in templates[:5]:  # First 5 only
+        print(f"   {generate_cli_command(t, 'run')}")
+    
+    print("\nDone!")
+
+
+if __name__ == "__main__":
+    main()

examples/catalog/fetch_templates.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Example: Fetch and search PraisonAI templates from the catalog.
+ * 
+ * This TypeScript example demonstrates how to:
+ * - Fetch templates.json from the deployed catalog
+ * - Search templates by keyword
+ * - Filter by tags and requirements
+ * - Generate CLI commands
+ */
+
+const CATALOG_URL = "https://mervinpraison.github.io/praisonai-template-catalog/data/templates.json";
+
+interface Template {
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  license?: string;
+  tags?: string[];
+  category?: string;
+  difficulty?: "beginner" | "intermediate" | "advanced";
+  requires?: {
+    tools?: string[];
+    packages?: string[];
+    env?: string[];
+  };
+}
+
+interface Catalog {
+  version: string;
+  generated_at: string;
+  count: number;
+  templates: Template[];
+}
+
+async function fetchCatalog(url: string = CATALOG_URL): Promise<Catalog> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch catalog: ${response.statusText}`);
+  }
+  return response.json();
+}
+
+function searchTemplates(templates: Template[], query: string): Template[] {
+  const q = query.toLowerCase();
+  return templates.filter(t =>
+    t.name.toLowerCase().includes(q) ||
+    t.description?.toLowerCase().includes(q) ||
+    t.tags?.some(tag => tag.toLowerCase().includes(q))
+  );
+}
+
+function filterByTags(templates: Template[], tags: string[]): Template[] {
+  return templates.filter(t =>
+    tags.every(tag => t.tags?.includes(tag))
+  );
+}
+
+function filterByTool(templates: Template[], toolName: string): Template[] {
+  return templates.filter(t =>
+    t.requires?.tools?.includes(toolName)
+  );
+}
+
+function getTemplate(templates: Template[], name: string): Template | undefined {
+  return templates.find(t => t.name === name);
+}
+
+function generateCLICommand(template: Template, action: string = "run"): string {
+  const name = template.name;
+  switch (action) {
+    case "run":
+      return `praisonai templates run ${name}`;
+    case "info":
+      return `praisonai templates info ${name}`;
+    case "init":
+      return `praisonai templates init my-project --template ${name}`;
+    default:
+      return `praisonai templates ${action} ${name}`;
+  }
+}
+
+function printTemplateSummary(template: Template): void {
+  console.log("\n" + "=".repeat(60));
+  console.log(`Name: ${template.name}`);
+  console.log(`Version: ${template.version}`);
+  console.log(`Description: ${template.description?.slice(0, 100)}...`);
+  console.log(`Tags: ${template.tags?.join(", ") || "none"}`);
+  
+  const requires = template.requires;
+  if (requires?.tools?.length) {
+    console.log(`Tools: ${requires.tools.join(", ")}`);
+  }
+  if (requires?.packages?.length) {
+    console.log(`Packages: ${requires.packages.join(", ")}`);
+  }
+  if (requires?.env?.length) {
+    console.log(`Env vars: ${requires.env.join(", ")}`);
+  }
+  
+  console.log(`\nRun: ${generateCLICommand(template, "run")}`);
+  console.log("=".repeat(60));
+}
+
+async function main(): Promise<void> {
+  console.log("PraisonAI Template Catalog - TypeScript Example");
+  console.log("-".repeat(45));
+  
+  // Fetch catalog
+  console.log("\n1. Fetching template catalog...");
+  let catalog: Catalog;
+  try {
+    catalog = await fetchCatalog();
+  } catch (error) {
+    console.log(`   Failed to fetch: ${error}`);
+    console.log("   The catalog may not be deployed yet.");
+    return;
+  }
+  
+  const templates = catalog.templates;
+  console.log(`   Catalog version: ${catalog.version}`);
+  console.log(`   Total templates: ${templates.length}`);
+  
+  if (templates.length === 0) {
+    console.log("   No templates found.");
+    return;
+  }
+  
+  // List all templates
+  console.log("\n2. Available templates:");
+  templates.forEach(t => {
+    console.log(`   - ${t.name} (v${t.version})`);
+  });
+  
+  // Search for video templates
+  console.log("\n3. Searching for 'video' templates...");
+  const videoTemplates = searchTemplates(templates, "video");
+  console.log(`   Found ${videoTemplates.length} video templates:`);
+  videoTemplates.forEach(t => {
+    console.log(`   - ${t.name}: ${t.description?.slice(0, 50)}...`);
+  });
+  
+  // Filter by tool
+  console.log("\n4. Templates using 'shell_tool':");
+  const shellTemplates = filterByTool(templates, "shell_tool");
+  shellTemplates.forEach(t => {
+    console.log(`   - ${t.name}`);
+  });
+  
+  // Get specific template details
+  if (templates.length > 0) {
+    const firstTemplate = templates[0];
+    console.log(`\n5. Template details for '${firstTemplate.name}':`);
+    printTemplateSummary(firstTemplate);
+  }
+  
+  // Generate CLI commands
+  console.log("\n6. CLI commands for all templates:");
+  templates.slice(0, 5).forEach(t => {
+    console.log(`   ${generateCLICommand(t, "run")}`);
+  });
+  
+  console.log("\nDone!");
+}
+
+main().catch(console.error);

examples/catalog/run_all_catalog_examples.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Run all catalog examples and report pass/fail status.
+
+Usage:
+    python run_all_catalog_examples.py
+    
+Environment variables:
+    OPENAI_API_KEY or PRAISONAI_OPENAI_API_KEY - Required for agent example
+    PRAISONAI_RUN_INTEGRATION - Set to "1" to run integration tests
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+def run_example(name: str, script: str, requires_api_key: bool = False) -> bool:
+    """Run an example script and return success status."""
+    print(f"\n{'='*60}")
+    print(f"Running: {name}")
+    print(f"Script: {script}")
+    print("="*60)
+    
+    # Check API key requirement
+    if requires_api_key:
+        api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("PRAISONAI_OPENAI_API_KEY")
+        run_integration = os.environ.get("PRAISONAI_RUN_INTEGRATION") == "1"
+        
+        if not api_key:
+            print(f"⏭️  SKIPPED: {name} (no API key)")
+            print("   Set OPENAI_API_KEY to run this example")
+            return True  # Not a failure, just skipped
+        
+        if not run_integration:
+            print(f"⏭️  SKIPPED: {name} (integration tests disabled)")
+            print("   Set PRAISONAI_RUN_INTEGRATION=1 to run")
+            return True
+    
+    script_path = SCRIPT_DIR / script
+    if not script_path.exists():
+        print(f"❌ FAILED: Script not found: {script_path}")
+        return False
+    
+    try:
+        result = subprocess.run(
+            [sys.executable, str(script_path)],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            cwd=str(SCRIPT_DIR)
+        )
+        
+        print(result.stdout)
+        if result.stderr:
+            print(f"STDERR: {result.stderr}")
+        
+        if result.returncode == 0:
+            print(f"✅ PASSED: {name}")
+            return True
+        else:
+            print(f"❌ FAILED: {name} (exit code {result.returncode})")
+            return False
+            
+    except subprocess.TimeoutExpired:
+        print(f"❌ FAILED: {name} (timeout)")
+        return False
+    except Exception as e:
+        print(f"❌ FAILED: {name} ({e})")
+        return False
+
+
+def main():
+    print("PraisonAI Template Catalog - Example Runner")
+    print("=" * 50)
+    
+    # Check environment
+    api_key = os.environ.get("OPENAI_API_KEY") or os.environ.get("PRAISONAI_OPENAI_API_KEY")
+    if api_key:
+        print(f"API key: present (...{api_key[-4:]})")
+    else:
+        print("API key: not set")
+    
+    run_integration = os.environ.get("PRAISONAI_RUN_INTEGRATION") == "1"
+    print(f"Integration tests: {'enabled' if run_integration else 'disabled'}")
+    
+    # Define examples
+    examples = [
+        ("Fetch Templates (Python)", "fetch_templates.py", False),
+        ("Template Finder Agent", "template_finder_agent.py", True),
+    ]
+    
+    # Run examples
+    results = []
+    for name, script, requires_key in examples:
+        success = run_example(name, script, requires_key)
+        results.append((name, success))
+    
+    # Summary
+    print("\n" + "=" * 60)
+    print("SUMMARY")
+    print("=" * 60)
+    
+    passed = sum(1 for _, s in results if s)
+    failed = sum(1 for _, s in results if not s)
+    
+    for name, success in results:
+        status = "✅ PASS" if success else "❌ FAIL"
+        print(f"  {status}: {name}")
+    
+    print(f"\nTotal: {passed} passed, {failed} failed")
+    
+    # Exit with appropriate code
+    sys.exit(0 if failed == 0 else 1)
+
+
+if __name__ == "__main__":
+    main()

examples/catalog/template_finder_agent.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+Example: Template Finder Agent
+
+An Agent()-centric example that uses an AI agent to find templates
+based on natural language queries.
+
+Requires: OPENAI_API_KEY environment variable
+"""
+
+import json
+import os
+import urllib.request
+
+CATALOG_URL = "https://mervinpraison.github.io/praisonai-template-catalog/data/templates.json"
+
+
+def fetch_templates() -> list:
+    """Fetch templates from catalog."""
+    try:
+        with urllib.request.urlopen(CATALOG_URL, timeout=10) as response:
+            data = json.loads(response.read().decode())
+            return data.get("templates", [])
+    except Exception:
+        return []
+
+
+def search_templates_tool(query: str) -> str:
+    """
+    Search templates by keyword.
+    
+    Args:
+        query: Search query (e.g., "video editing", "transcript", "data")
+    
+    Returns:
+        JSON string with matching templates
+    """
+    templates = fetch_templates()
+    query_lower = query.lower()
+    
+    results = []
+    for t in templates:
+        if (query_lower in t.get("name", "").lower() or
+            query_lower in t.get("description", "").lower() or
+            any(query_lower in tag.lower() for tag in t.get("tags", []))):
+            results.append({
+                "name": t.get("name"),
+                "description": t.get("description", "")[:100],
+                "tags": t.get("tags", []),
+                "cli_command": f"praisonai templates run {t.get('name')}"
+            })
+    
+    if not results:
+        return json.dumps({"message": "No templates found matching your query", "templates": []})
+    
+    return json.dumps({"count": len(results), "templates": results})
+
+
+def list_all_templates_tool() -> str:
+    """
+    List all available templates.
+    
+    Returns:
+        JSON string with all template names and descriptions
+    """
+    templates = fetch_templates()
+    
+    if not templates:
+        return json.dumps({"message": "No templates available", "templates": []})
+    
+    results = [
+        {"name": t.get("name"), "description": t.get("description", "")[:80]}
+        for t in templates
+    ]
+    
+    return json.dumps({"count": len(results), "templates": results})
+
+
+def get_template_details_tool(name: str) -> str:
+    """
+    Get detailed information about a specific template.
+    
+    Args:
+        name: Template name (e.g., "ai-video-editor")
+    
+    Returns:
+        JSON string with template details
+    """
+    templates = fetch_templates()
+    
+    for t in templates:
+        if t.get("name") == name:
+            return json.dumps({
+                "name": t.get("name"),
+                "version": t.get("version"),
+                "description": t.get("description"),
+                "author": t.get("author"),
+                "tags": t.get("tags", []),
+                "requires": t.get("requires", {}),
+                "cli_commands": {
+                    "run": f"praisonai templates run {name}",
+                    "info": f"praisonai templates info {name}",
+                    "init": f"praisonai templates init my-project --template {name}"
+                }
+            })
+    
+    return json.dumps({"error": f"Template '{name}' not found"})
+
+
+def check_api_key() -> bool:
+    """Check if API key is available."""
+    key = os.environ.get("OPENAI_API_KEY") or os.environ.get("PRAISONAI_OPENAI_API_KEY")
+    if key:
+        print(f"API key present: ...{key[-4:]}")
+        return True
+    return False
+
+
+def main():
+    print("PraisonAI Template Finder Agent")
+    print("=" * 40)
+    
+    # Check for API key
+    if not check_api_key():
+        print("\n⚠️  No API key found.")
+        print("Set OPENAI_API_KEY or PRAISONAI_OPENAI_API_KEY to use the agent.")
+        print("\nFalling back to direct tool usage:\n")
+        
+        # Demo the tools directly
+        print("1. Listing all templates:")
+        result = list_all_templates_tool()
+        data = json.loads(result)
+        for t in data.get("templates", [])[:5]:
+            print(f"   - {t['name']}: {t['description'][:50]}...")
+        
+        print("\n2. Searching for 'video' templates:")
+        result = search_templates_tool("video")
+        data = json.loads(result)
+        for t in data.get("templates", []):
+            print(f"   - {t['name']}")
+            print(f"     Run: {t['cli_command']}")
+        
+        return
+    
+    # Import Agent only if API key is available
+    try:
+        from praisonaiagents import Agent
+    except ImportError:
+        print("praisonaiagents not installed. Install with: pip install praisonaiagents")
+        return
+    
+    # Create the Template Finder Agent
+    agent = Agent(
+        name="Template Finder",
+        role="PraisonAI Template Expert",
+        goal="Help users find the right template for their needs",
+        backstory="""You are an expert on PraisonAI templates. You help users 
+        discover templates that match their requirements. You can search templates,
+        list all available templates, and provide detailed information about specific
+        templates. Always provide the CLI command to run the template.""",
+        tools=[
+            search_templates_tool,
+            list_all_templates_tool,
+            get_template_details_tool
+        ],
+        verbose=True
+    )
+    
+    # Example queries
+    queries = [
+        "Find me a template for editing videos",
+        "What templates are available for working with transcripts?",
+        "Show me details about the ai-video-editor template"
+    ]
+    
+    print("\nRunning Template Finder Agent...")
+    print("-" * 40)
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        print("-" * 40)
+        
+        try:
+            result = agent.start(query)
+            print(f"\n🤖 Response:\n{result}")
+        except Exception as e:
+            print(f"Error: {e}")
+        
+        print("\n" + "=" * 40)
+
+
+if __name__ == "__main__":
+    main()

examples/doctor/README.md

@@ -0,0 +1,65 @@
+# PraisonAI Doctor Examples
+
+Examples demonstrating the PraisonAI Doctor health check and diagnostics system.
+
+## CLI Examples
+
+| Command | Description |
+|---------|-------------|
+| `praisonai doctor` | Run all fast health checks |
+| `praisonai doctor --version` | Show doctor version |
+| `praisonai doctor --list-checks` | List all available checks |
+| `praisonai doctor env` | Check environment configuration |
+| `praisonai doctor config` | Validate configuration files |
+| `praisonai doctor tools` | Check tool availability |
+| `praisonai doctor db` | Check database drivers |
+| `praisonai doctor mcp` | Check MCP configuration |
+| `praisonai doctor obs` | Check observability providers |
+| `praisonai doctor skills` | Check agent skills |
+| `praisonai doctor memory` | Check memory storage |
+| `praisonai doctor permissions` | Check filesystem permissions |
+| `praisonai doctor network` | Check network connectivity |
+| `praisonai doctor performance` | Check import times |
+| `praisonai doctor ci` | CI mode with JSON output |
+| `praisonai doctor selftest` | Test agent functionality |
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output in JSON format |
+| `--format text\|json` | Output format |
+| `--output PATH` | Write report to file |
+| `--deep` | Enable deeper probes |
+| `--timeout SEC` | Per-check timeout |
+| `--strict` | Treat warnings as failures |
+| `--quiet` | Minimal output |
+| `--no-color` | Disable colors |
+| `--only IDS` | Only run these checks |
+| `--skip IDS` | Skip these checks |
+
+## Python Examples
+
+| File | Description |
+|------|-------------|
+| [basic_doctor.py](basic_doctor.py) | Programmatic health checks |
+| [ci_integration.py](ci_integration.py) | CI/CD pipeline integration |
+
+## Quick Start
+
+```bash
+# Run basic health checks
+praisonai doctor
+
+# Run with JSON output
+praisonai doctor --json
+
+# Run specific checks
+praisonai doctor --only python_version,openai_api_key
+
+# CI mode
+praisonai doctor ci
+
+# Save report to file
+praisonai doctor --output report.json
+```

examples/doctor/basic_doctor.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Basic Doctor Example - Programmatic health checks for PraisonAI
+
+This example demonstrates how to use the Doctor module programmatically
+to run health checks and diagnostics.
+"""
+
+import json
+import sys
+
+# Add the praisonai path for development
+sys.path.insert(0, '/Users/praison/praisonai-package/src/praisonai')
+
+from praisonai.cli.features.doctor import DoctorEngine
+from praisonai.cli.features.doctor.models import DoctorConfig, CheckCategory
+from praisonai.cli.features.doctor.registry import get_registry
+from praisonai.cli.features.doctor.checks import register_all_checks
+from praisonai.cli.features.doctor.formatters import get_formatter
+
+
+def run_basic_checks():
+    """Run basic health checks."""
+    print("=" * 60)
+    print("Running Basic Health Checks")
+    print("=" * 60)
+    
+    # Register all checks
+    register_all_checks()
+    
+    # Create config for fast checks only
+    config = DoctorConfig(
+        deep=False,
+        timeout=10.0,
+        strict=False,
+        quiet=False,
+    )
+    
+    # Create and run engine
+    engine = DoctorEngine(config)
+    report = engine.run()
+    
+    # Format and print results
+    formatter = get_formatter("text", no_color=True)
+    print(formatter.format_report(report))
+    
+    return report.exit_code
+
+
+def run_environment_checks():
+    """Run only environment checks."""
+    print("\n" + "=" * 60)
+    print("Running Environment Checks Only")
+    print("=" * 60)
+    
+    # Register all checks
+    register_all_checks()
+    
+    config = DoctorConfig(deep=False)
+    engine = DoctorEngine(config)
+    
+    # Run only environment category
+    engine.run_checks(categories=[CheckCategory.ENVIRONMENT])
+    report = engine.generate_report()
+    
+    formatter = get_formatter("text", no_color=True)
+    print(formatter.format_report(report))
+    
+    return report.exit_code
+
+
+def run_specific_checks():
+    """Run specific checks by ID."""
+    print("\n" + "=" * 60)
+    print("Running Specific Checks")
+    print("=" * 60)
+    
+    # Register all checks
+    register_all_checks()
+    
+    # Only run these specific checks
+    config = DoctorConfig(
+        only=["python_version", "openai_api_key", "os_info"]
+    )
+    
+    engine = DoctorEngine(config)
+    report = engine.run()
+    
+    formatter = get_formatter("text", no_color=True)
+    print(formatter.format_report(report))
+    
+    return report.exit_code
+
+
+def run_json_output():
+    """Run checks and get JSON output."""
+    print("\n" + "=" * 60)
+    print("Running Checks with JSON Output")
+    print("=" * 60)
+    
+    # Register all checks
+    register_all_checks()
+    
+    config = DoctorConfig(
+        only=["python_version", "os_info"],
+        format="json"
+    )
+    
+    engine = DoctorEngine(config)
+    report = engine.run()
+    
+    # Get JSON output
+    formatter = get_formatter("json")
+    json_output = formatter.format_report(report)
+    
+    # Parse and pretty print
+    data = json.loads(json_output)
+    print(json.dumps(data, indent=2))
+    
+    return report.exit_code
+
+
+def list_available_checks():
+    """List all available checks."""
+    print("\n" + "=" * 60)
+    print("Available Checks")
+    print("=" * 60)
+    
+    # Register all checks
+    register_all_checks()
+    
+    registry = get_registry()
+    checks = registry.get_all_checks()
+    
+    # Sort by category
+    checks.sort(key=lambda c: c.category.value)
+    
+    current_category = None
+    for check in checks:
+        if check.category != current_category:
+            current_category = check.category
+            print(f"\n  {current_category.value.upper()}:")
+        
+        deep_marker = " [deep]" if check.requires_deep else ""
+        print(f"    {check.id:30} {check.description}{deep_marker}")
+
+
+if __name__ == "__main__":
+    print("PraisonAI Doctor - Programmatic Usage Examples\n")
+    
+    # List available checks
+    list_available_checks()
+    
+    # Run basic checks
+    exit_code = run_basic_checks()
+    print(f"\nBasic checks exit code: {exit_code}")
+    
+    # Run environment checks only
+    exit_code = run_environment_checks()
+    print(f"\nEnvironment checks exit code: {exit_code}")
+    
+    # Run specific checks
+    exit_code = run_specific_checks()
+    print(f"\nSpecific checks exit code: {exit_code}")
+    
+    # Run with JSON output
+    exit_code = run_json_output()
+    print(f"\nJSON output exit code: {exit_code}")

examples/doctor/ci_integration.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+CI Integration Example - Using Doctor in CI/CD pipelines
+
+This example demonstrates how to integrate PraisonAI Doctor
+into CI/CD pipelines for automated health checks.
+"""
+
+import json
+import subprocess
+import sys
+
+
+def run_doctor_ci():
+    """Run doctor in CI mode and parse results."""
+    print("Running PraisonAI Doctor in CI mode...")
+    
+    result = subprocess.run(
+        [sys.executable, "-m", "praisonai", "doctor", "ci"],
+        capture_output=True,
+        text=True,
+        timeout=120
+    )
+    
+    # Parse JSON output
+    try:
+        report = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print("Error: Could not parse doctor output")
+        print(result.stdout)
+        print(result.stderr)
+        return 1
+    
+    # Print summary
+    summary = report.get("summary", {})
+    print("\nDoctor CI Results:")
+    print(f"  Total checks: {summary.get('total', 0)}")
+    print(f"  Passed: {summary.get('passed', 0)}")
+    print(f"  Warnings: {summary.get('warnings', 0)}")
+    print(f"  Failed: {summary.get('failed', 0)}")
+    print(f"  Skipped: {summary.get('skipped', 0)}")
+    print(f"  Errors: {summary.get('errors', 0)}")
+    print(f"\nExit code: {report.get('exit_code', -1)}")
+    
+    # Check for failures
+    if summary.get('failed', 0) > 0:
+        print("\nFailed checks:")
+        for check in report.get("results", []):
+            if check.get("status") == "fail":
+                print(f"  - {check.get('title')}: {check.get('message')}")
+                if check.get("remediation"):
+                    print(f"    Fix: {check.get('remediation')}")
+    
+    return result.returncode
+
+
+def run_specific_checks_ci():
+    """Run specific checks for CI."""
+    print("\nRunning specific checks for CI...")
+    
+    # Only run critical checks
+    critical_checks = [
+        "python_version",
+        "praisonai_package",
+        "openai_api_key",
+    ]
+    
+    result = subprocess.run(
+        [
+            sys.executable, "-m", "praisonai", "doctor",
+            "--json",
+            "--only", ",".join(critical_checks)
+        ],
+        capture_output=True,
+        text=True,
+        timeout=60
+    )
+    
+    try:
+        report = json.loads(result.stdout)
+        print(f"Critical checks: {report['summary']['passed']}/{report['summary']['total']} passed")
+        return result.returncode
+    except json.JSONDecodeError:
+        print("Error parsing output")
+        return 1
+
+
+def save_report_to_file():
+    """Save doctor report to a file for artifact upload."""
+    print("\nSaving doctor report to file...")
+    
+    result = subprocess.run(
+        [
+            sys.executable, "-m", "praisonai", "doctor",
+            "--json",
+            "--output", "/tmp/doctor-report.json"
+        ],
+        capture_output=True,
+        text=True,
+        timeout=120
+    )
+    
+    if result.returncode in [0, 1]:
+        print("Report saved to /tmp/doctor-report.json")
+        
+        # Read and display summary
+        with open("/tmp/doctor-report.json", "r") as f:
+            report = json.load(f)
+            print(f"Summary: {report['summary']}")
+    
+    return result.returncode
+
+
+if __name__ == "__main__":
+    print("PraisonAI Doctor - CI Integration Examples\n")
+    print("=" * 60)
+    
+    # Run CI mode
+    exit_code = run_doctor_ci()
+    
+    # Run specific checks
+    run_specific_checks_ci()
+    
+    # Save report
+    save_report_to_file()
+    
+    print(f"\nFinal exit code: {exit_code}")
+    sys.exit(exit_code)

examples/endpoints_example.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Endpoints Example
+
+This example demonstrates how to:
+1. Start the recipe server
+2. Use the endpoints CLI to interact with it
+3. Invoke recipes via HTTP
+
+Prerequisites:
+- pip install praisonai[serve]
+- Set OPENAI_API_KEY environment variable
+
+Usage:
+    # Terminal 1: Start server
+    praisonai recipe serve --port 8765
+
+    # Terminal 2: Run this example
+    python endpoints_example.py
+"""
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+import urllib.error
+
+# Configuration
+SERVER_URL = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+
+
+def check_server_health():
+    """Check if the server is running."""
+    try:
+        req = urllib.request.Request(f"{SERVER_URL}/health")
+        with urllib.request.urlopen(req, timeout=5) as response:
+            data = json.loads(response.read().decode())
+            return data.get("status") == "healthy"
+    except Exception:
+        return False
+
+
+def list_endpoints():
+    """List available endpoints using CLI."""
+    print("\n=== Listing Endpoints (CLI) ===")
+    result = subprocess.run(
+        ["python", "-m", "praisonai.cli.main", "endpoints", "list", "--format", "json"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        recipes = json.loads(result.stdout)
+        print(f"Found {len(recipes)} endpoints:")
+        for r in recipes:
+            print(f"  - {r['name']} ({r['version']}): {r.get('description', '')[:50]}")
+        return recipes
+    else:
+        print(f"Error: {result.stderr}")
+        return []
+
+
+def describe_endpoint(name: str):
+    """Describe an endpoint using CLI."""
+    print(f"\n=== Describing Endpoint: {name} ===")
+    result = subprocess.run(
+        ["python", "-m", "praisonai.cli.main", "endpoints", "describe", name, "--url", SERVER_URL],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        info = json.loads(result.stdout)
+        print(f"Name: {info.get('name')}")
+        print(f"Version: {info.get('version')}")
+        print(f"Description: {info.get('description')}")
+        return info
+    else:
+        print(f"Error: {result.stderr}")
+        return None
+
+
+def invoke_endpoint_cli(name: str, input_data: dict):
+    """Invoke an endpoint using CLI."""
+    print(f"\n=== Invoking Endpoint (CLI): {name} ===")
+    result = subprocess.run(
+        [
+            "python", "-m", "praisonai.cli.main", "endpoints", "invoke", name,
+            "--url", SERVER_URL,
+            "--input-json", json.dumps(input_data),
+            "--json",
+            "--dry-run",  # Use dry-run for example
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        response = json.loads(result.stdout)
+        print(f"Run ID: {response.get('run_id')}")
+        print(f"Status: {response.get('status')}")
+        return response
+    else:
+        print(f"Error: {result.stderr}")
+        return None
+
+
+def invoke_endpoint_http(name: str, input_data: dict):
+    """Invoke an endpoint using HTTP directly."""
+    print(f"\n=== Invoking Endpoint (HTTP): {name} ===")
+    
+    body = json.dumps({
+        "recipe": name,
+        "input": input_data,
+        "options": {"dry_run": True},
+    }).encode()
+    
+    req = urllib.request.Request(
+        f"{SERVER_URL}/v1/recipes/run",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            data = json.loads(response.read().decode())
+            print(f"Run ID: {data.get('run_id')}")
+            print(f"Status: {data.get('status')}")
+            print(f"Output: {data.get('output')}")
+            return data
+    except urllib.error.HTTPError as e:
+        print(f"HTTP Error: {e.code} - {e.read().decode()}")
+        return None
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Endpoints Example")
+    print("=" * 60)
+    
+    # Check if server is running
+    print("\n=== Checking Server Health ===")
+    if not check_server_health():
+        print(f"Server not running at {SERVER_URL}")
+        print("\nPlease start the server first:")
+        print("  praisonai recipe serve --port 8765")
+        sys.exit(1)
+    print("✓ Server is healthy")
+    
+    # List endpoints
+    recipes = list_endpoints()
+    if not recipes:
+        print("No recipes available")
+        sys.exit(1)
+    
+    # Use first available recipe
+    recipe_name = recipes[0]["name"]
+    
+    # Describe endpoint
+    describe_endpoint(recipe_name)
+    
+    # Invoke via CLI
+    invoke_endpoint_cli(recipe_name, {"query": "Hello from CLI"})
+    
+    # Invoke via HTTP
+    invoke_endpoint_http(recipe_name, {"query": "Hello from HTTP"})
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/mcp_server/README.md

@@ -0,0 +1,163 @@
+# PraisonAI MCP Server Examples
+
+This directory contains examples for running PraisonAI as an MCP (Model Context Protocol) server.
+
+## Overview
+
+PraisonAI can expose its capabilities via MCP protocol, allowing integration with:
+- Claude Desktop
+- Cursor
+- Windsurf
+- VSCode MCP clients
+- Any MCP-compatible client
+
+## Protocol Version
+
+These examples use MCP Protocol Version **2025-11-25**.
+
+## Examples
+
+### 1. STDIO Server (stdio_server.py)
+
+Run PraisonAI as an MCP server using STDIO transport (for Claude Desktop integration).
+
+```bash
+# Run directly
+python stdio_server.py
+
+# Or via CLI
+praisonai mcp serve --transport stdio
+```
+
+### 2. HTTP Stream Server (http_stream_server.py)
+
+Run PraisonAI as an MCP server using HTTP Stream transport.
+
+```bash
+# Run directly
+python http_stream_server.py
+
+# Or via CLI
+praisonai mcp serve --transport http-stream --port 8080
+```
+
+### 3. Custom Tools Server (custom_tools_server.py)
+
+Register custom tools and expose them via MCP.
+
+```bash
+python custom_tools_server.py
+```
+
+### 4. Client Example (mcp_client_example.py)
+
+Example of connecting to a PraisonAI MCP server as a client.
+
+```bash
+python mcp_client_example.py
+```
+
+## CLI Commands
+
+```bash
+# Start STDIO server
+praisonai mcp serve --transport stdio
+
+# Start HTTP Stream server
+praisonai mcp serve --transport http-stream --port 8080
+
+# Start with authentication
+praisonai mcp serve --transport http-stream --api-key YOUR_KEY
+
+# List available tools
+praisonai mcp list-tools
+
+# List available resources
+praisonai mcp list-resources
+
+# List available prompts
+praisonai mcp list-prompts
+
+# Generate client configuration
+praisonai mcp config-generate --client claude-desktop
+
+# Check server health
+praisonai mcp doctor
+```
+
+## Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "praisonai": {
+      "command": "praisonai",
+      "args": ["mcp", "serve", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor settings:
+
+```json
+{
+  "mcpServers": {
+    "praisonai": {
+      "command": "praisonai",
+      "args": ["mcp", "serve", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+## Environment Variables
+
+Set the following environment variables for full functionality:
+
+```bash
+export OPENAI_API_KEY=your_key
+export ANTHROPIC_API_KEY=your_key  # Optional
+export GOOGLE_API_KEY=your_key     # Optional
+```
+
+## Available Tools
+
+Run `praisonai mcp list-tools` to see all available tools, including:
+
+- `praisonai.chat.completion` - Chat with LLM
+- `praisonai.agent.chat` - Chat with an agent
+- `praisonai.agent.run` - Run a task with an agent
+- `praisonai.workflow.run` - Run a workflow
+- `praisonai.images.generate` - Generate images
+- `praisonai.audio.transcribe` - Transcribe audio
+- `praisonai.embed.create` - Create embeddings
+- `praisonai.memory.*` - Memory operations
+- `praisonai.knowledge.*` - Knowledge base operations
+- And many more...
+
+## Available Resources
+
+- `praisonai://memory/sessions` - List memory sessions
+- `praisonai://workflows` - List available workflows
+- `praisonai://tools` - List available tools
+- `praisonai://agents` - List agent configurations
+- `praisonai://knowledge/sources` - List knowledge sources
+- `praisonai://config` - Get current configuration
+- `praisonai://mcp/status` - Get MCP server status
+
+## Available Prompts
+
+- `deep-research` - Generate deep research prompts
+- `code-review` - Generate code review prompts
+- `workflow-auto` - Generate workflow auto-generation prompts
+- `guardrail-check` - Generate guardrail check prompts
+- `context-engineering` - Generate context engineering prompts
+- `eval-criteria` - Generate evaluation criteria prompts
+- `agent-instructions` - Generate agent instructions prompts

examples/mcp_server/custom_tools_server.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+Custom Tools MCP Server Example
+
+Register custom tools and expose them via MCP server.
+
+Usage:
+    python custom_tools_server.py
+"""
+
+
+def main():
+    """Run MCP server with custom tools."""
+    from praisonai.mcp_server.server import MCPServer
+    from praisonai.mcp_server.registry import register_tool, get_tool_registry
+    
+    # Register custom tools
+    @register_tool("custom.greet")
+    def greet(name: str) -> str:
+        """Greet a person by name."""
+        return f"Hello, {name}! Welcome to PraisonAI."
+    
+    @register_tool("custom.calculate")
+    def calculate(expression: str) -> str:
+        """Safely evaluate a mathematical expression."""
+        try:
+            # Only allow safe math operations
+            allowed = set("0123456789+-*/.(). ")
+            if not all(c in allowed for c in expression):
+                return "Error: Invalid characters in expression"
+            result = eval(expression)  # Safe due to character filtering
+            return f"Result: {result}"
+        except Exception as e:
+            return f"Error: {e}"
+    
+    @register_tool("custom.reverse")
+    def reverse_text(text: str) -> str:
+        """Reverse a text string."""
+        return text[::-1]
+    
+    @register_tool("custom.word_count")
+    def word_count(text: str) -> str:
+        """Count words in text."""
+        words = text.split()
+        return f"Word count: {len(words)}"
+    
+    # Show registered tools
+    registry = get_tool_registry()
+    tools = registry.list_all()
+    print(f"Registered {len(tools)} custom tools:")
+    for tool in tools:
+        print(f"  - {tool.name}: {tool.description}")
+    print()
+    
+    # Create and run server
+    server = MCPServer(
+        name="praisonai-custom",
+        version="1.0.0",
+        instructions="Custom tools MCP server example.",
+    )
+    
+    print("Starting MCP server on http://127.0.0.1:8080/mcp")
+    server.run(
+        transport="http-stream",
+        host="127.0.0.1",
+        port=8080,
+    )
+
+
+if __name__ == "__main__":
+    main()

examples/mcp_server/http_stream_server.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+HTTP Stream MCP Server Example
+
+Run PraisonAI as an MCP server using HTTP Stream transport.
+This transport is useful for web-based integrations.
+
+Usage:
+    python http_stream_server.py
+
+Or via CLI:
+    praisonai mcp serve --transport http-stream --port 8080
+"""
+
+
+def main():
+    """Run MCP server with HTTP Stream transport."""
+    from praisonai.mcp_server.server import MCPServer
+    from praisonai.mcp_server.adapters import register_all
+    
+    # Register all tools, resources, and prompts
+    register_all()
+    
+    # Create server
+    server = MCPServer(
+        name="praisonai",
+        version="1.0.0",
+        instructions="PraisonAI MCP Server - AI agent capabilities via MCP protocol.",
+    )
+    
+    # Run with HTTP Stream transport
+    server.run(
+        transport="http-stream",
+        host="127.0.0.1",
+        port=8080,
+        endpoint="/mcp",
+    )
+
+
+if __name__ == "__main__":
+    print("Starting PraisonAI MCP Server on http://127.0.0.1:8080/mcp")
+    print("Protocol Version: 2025-11-25")
+    print("Press Ctrl+C to stop")
+    main()

examples/mcp_server/mcp_client_example.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+MCP Client Example
+
+Example of connecting to a PraisonAI MCP server as a client.
+
+Prerequisites:
+    1. Start the MCP server first:
+       praisonai mcp serve --transport http-stream --port 8080
+    
+    2. Then run this client:
+       python mcp_client_example.py
+
+Environment Variables:
+    OPENAI_API_KEY - Required for chat completion tools
+"""
+
+import requests
+
+
+def main():
+    """Connect to MCP server and call tools."""
+    base_url = "http://127.0.0.1:8080/mcp"
+    session_id = None
+    
+    print("PraisonAI MCP Client Example")
+    print("=" * 40)
+    
+    # 1. Initialize connection
+    print("\n1. Initializing connection...")
+    init_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-11-25",
+            "capabilities": {},
+            "clientInfo": {
+                "name": "example-client",
+                "version": "1.0.0",
+            },
+        },
+    }
+    
+    response = requests.post(
+        base_url,
+        json=init_request,
+        headers={"Content-Type": "application/json"},
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        session_id = response.headers.get("MCP-Session-Id")
+        print(f"   Connected! Session ID: {session_id}")
+        print(f"   Server: {result.get('result', {}).get('serverInfo', {})}")
+        print(f"   Protocol: {result.get('result', {}).get('protocolVersion')}")
+    else:
+        print(f"   Error: {response.status_code}")
+        return
+    
+    # 2. Send initialized notification
+    print("\n2. Sending initialized notification...")
+    init_notification = {
+        "jsonrpc": "2.0",
+        "method": "notifications/initialized",
+    }
+    requests.post(
+        base_url,
+        json=init_notification,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    print("   Done")
+    
+    # 3. List available tools
+    print("\n3. Listing available tools...")
+    list_request = {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list",
+        "params": {},
+    }
+    
+    response = requests.post(
+        base_url,
+        json=list_request,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        tools = result.get("result", {}).get("tools", [])
+        print(f"   Found {len(tools)} tools")
+        for tool in tools[:5]:  # Show first 5
+            print(f"   - {tool.get('name')}")
+        if len(tools) > 5:
+            print(f"   ... and {len(tools) - 5} more")
+    
+    # 4. List available resources
+    print("\n4. Listing available resources...")
+    list_resources = {
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "resources/list",
+        "params": {},
+    }
+    
+    response = requests.post(
+        base_url,
+        json=list_resources,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        resources = result.get("result", {}).get("resources", [])
+        print(f"   Found {len(resources)} resources")
+        for res in resources:
+            print(f"   - {res.get('uri')}")
+    
+    # 5. List available prompts
+    print("\n5. Listing available prompts...")
+    list_prompts = {
+        "jsonrpc": "2.0",
+        "id": 4,
+        "method": "prompts/list",
+        "params": {},
+    }
+    
+    response = requests.post(
+        base_url,
+        json=list_prompts,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        prompts = result.get("result", {}).get("prompts", [])
+        print(f"   Found {len(prompts)} prompts")
+        for prompt in prompts:
+            print(f"   - {prompt.get('name')}")
+    
+    # 6. Read a resource
+    print("\n6. Reading MCP status resource...")
+    read_resource = {
+        "jsonrpc": "2.0",
+        "id": 5,
+        "method": "resources/read",
+        "params": {
+            "uri": "praisonai://mcp/status",
+        },
+    }
+    
+    response = requests.post(
+        base_url,
+        json=read_resource,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        contents = result.get("result", {}).get("contents", [])
+        if contents:
+            print(f"   Status: {contents[0].get('text', 'N/A')}")
+    
+    # 7. Get a prompt
+    print("\n7. Getting deep-research prompt...")
+    get_prompt = {
+        "jsonrpc": "2.0",
+        "id": 6,
+        "method": "prompts/get",
+        "params": {
+            "name": "deep-research",
+            "arguments": {
+                "topic": "AI agents",
+                "depth": "medium",
+            },
+        },
+    }
+    
+    response = requests.post(
+        base_url,
+        json=get_prompt,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        result = response.json()
+        messages = result.get("result", {}).get("messages", [])
+        if messages:
+            content = messages[0].get("content", {})
+            text = content.get("text", "") if isinstance(content, dict) else str(content)
+            print(f"   Prompt preview: {text[:100]}...")
+    
+    # 8. Ping
+    print("\n8. Pinging server...")
+    ping_request = {
+        "jsonrpc": "2.0",
+        "id": 7,
+        "method": "ping",
+        "params": {},
+    }
+    
+    response = requests.post(
+        base_url,
+        json=ping_request,
+        headers={
+            "Content-Type": "application/json",
+            "MCP-Session-Id": session_id,
+        },
+    )
+    
+    if response.status_code == 200:
+        print("   Pong!")
+    
+    print("\n" + "=" * 40)
+    print("MCP client example completed successfully!")
+
+
+if __name__ == "__main__":
+    main()

examples/mcp_server/stdio_server.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+STDIO MCP Server Example
+
+Run PraisonAI as an MCP server using STDIO transport.
+This is the recommended transport for Claude Desktop integration.
+
+Usage:
+    python stdio_server.py
+
+Or via CLI:
+    praisonai mcp serve --transport stdio
+"""
+
+
+def main():
+    """Run MCP server with STDIO transport."""
+    from praisonai.mcp_server.server import MCPServer
+    from praisonai.mcp_server.adapters import register_all
+    
+    # Register all tools, resources, and prompts
+    register_all()
+    
+    # Create and run server
+    server = MCPServer(
+        name="praisonai",
+        version="1.0.0",
+        instructions="PraisonAI MCP Server - AI agent capabilities via MCP protocol.",
+    )
+    
+    # Run with STDIO transport
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

examples/package_manager/README.md

@@ -0,0 +1,101 @@
+# Package Manager Example
+
+This example demonstrates how to use the PraisonAI package manager for installing and managing Python packages with security defaults.
+
+## Features Demonstrated
+
+- Installing packages with version constraints
+- Listing installed packages
+- Searching for packages on PyPI
+- Managing package index configuration
+- Security features (dependency confusion prevention)
+
+## Quick Start
+
+```bash
+# Run the example
+python package_manager_example.py
+```
+
+## CLI Commands
+
+### Install Packages
+
+```bash
+# Install a package
+praisonai install requests
+
+# Install with version constraint
+praisonai install "requests>=2.28"
+
+# Install multiple packages
+praisonai install requests httpx aiohttp
+
+# Upgrade existing package
+praisonai install requests --upgrade
+
+# JSON output
+praisonai install requests --json
+```
+
+### Uninstall Packages
+
+```bash
+# Uninstall a package
+praisonai uninstall requests
+
+# Uninstall without confirmation
+praisonai uninstall requests --yes
+```
+
+### List Packages
+
+```bash
+# List all installed packages
+praisonai package list
+
+# JSON output
+praisonai package list --json
+```
+
+### Search Packages
+
+```bash
+# Search PyPI
+praisonai package search langchain
+
+# JSON output
+praisonai package search langchain --json
+```
+
+### Index Configuration
+
+```bash
+# Show current index settings
+praisonai package index show --json
+
+# Set custom index
+praisonai package index set https://pypi.mycompany.com/simple
+
+# Reset to PyPI default
+praisonai package index set https://pypi.org/simple
+```
+
+## Security Features
+
+By default, only the primary index (PyPI) is used. Extra indexes are blocked to prevent dependency confusion attacks.
+
+```bash
+# This will FAIL (extra index not allowed by default)
+praisonai install mypackage --extra-index-url https://other.index.com/simple
+
+# Explicitly allow extra index (shows security warning)
+praisonai install mypackage \
+  --extra-index-url https://other.index.com/simple \
+  --allow-extra-index
+```
+
+## Environment Variables
+
+- `PRAISONAI_PACKAGE_INDEX_URL` - Override primary index URL
+- `PIP_INDEX_URL` - Fallback to pip's index URL

examples/package_manager/package_manager_example.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Package Manager Example
+
+This example demonstrates:
+1. Checking package index configuration
+2. Searching for packages on PyPI
+3. Listing installed packages
+4. Security features (safe defaults)
+
+Requirements:
+- praisonai installed
+- No external API keys required
+
+Note: This example does NOT actually install/uninstall packages
+to avoid modifying your environment. It demonstrates read-only
+operations and shows the commands for install/uninstall.
+"""
+
+import sys
+import json
+import subprocess
+
+
+def run_command(args, description):
+    """Run a praisonai command and display results."""
+    print(f"\n[{description}]")
+    print(f"Command: praisonai {' '.join(args)}")
+    print("-" * 40)
+    
+    result = subprocess.run(
+        ["python3", "-m", "praisonai"] + args,
+        capture_output=True,
+        text=True
+    )
+    
+    if result.returncode == 0:
+        try:
+            data = json.loads(result.stdout)
+            print(json.dumps(data, indent=2))
+            return data
+        except json.JSONDecodeError:
+            print(result.stdout)
+            return None
+    else:
+        print(f"Error (exit code {result.returncode}):")
+        print(result.stderr or result.stdout)
+        return None
+
+
+def main():
+    print("=" * 60)
+    print("PraisonAI Package Manager Example")
+    print("=" * 60)
+    print("\nThis example demonstrates package manager features.")
+    print("No packages will be installed or uninstalled.")
+    
+    # 1. Show index configuration
+    print("\n" + "=" * 60)
+    print("1. PACKAGE INDEX CONFIGURATION")
+    print("=" * 60)
+    
+    data = run_command(
+        ["package", "index", "show", "--json"],
+        "Show current index settings"
+    )
+    
+    if data:
+        print(f"\n✓ Primary index: {data.get('index_url', 'N/A')}")
+        print(f"✓ Extra indexes allowed: {data.get('allow_extra_index', False)}")
+    
+    # 2. Search for packages
+    print("\n" + "=" * 60)
+    print("2. SEARCH PACKAGES")
+    print("=" * 60)
+    
+    data = run_command(
+        ["package", "search", "requests", "--json"],
+        "Search for 'requests' package"
+    )
+    
+    if data and data.get("results"):
+        pkg = data["results"][0]
+        print(f"\n✓ Found: {pkg.get('name')} v{pkg.get('version')}")
+        print(f"  Summary: {pkg.get('summary', 'N/A')}")
+    
+    # 3. List installed packages (sample)
+    print("\n" + "=" * 60)
+    print("3. LIST INSTALLED PACKAGES")
+    print("=" * 60)
+    
+    data = run_command(
+        ["package", "list", "--json"],
+        "List installed packages"
+    )
+    
+    if data and data.get("packages"):
+        print(f"\n✓ Total packages: {len(data['packages'])}")
+        print("  Sample (first 5):")
+        for pkg in data["packages"][:5]:
+            print(f"    - {pkg['name']}=={pkg['version']}")
+    
+    # 4. Show install/uninstall commands (without executing)
+    print("\n" + "=" * 60)
+    print("4. INSTALL/UNINSTALL COMMANDS (NOT EXECUTED)")
+    print("=" * 60)
+    
+    print("\nTo install packages, use:")
+    print("  praisonai install requests")
+    print("  praisonai install 'requests>=2.28'")
+    print("  praisonai install requests httpx --upgrade")
+    
+    print("\nTo uninstall packages, use:")
+    print("  praisonai uninstall requests")
+    print("  praisonai uninstall requests --yes")
+    
+    # 5. Security features
+    print("\n" + "=" * 60)
+    print("5. SECURITY FEATURES")
+    print("=" * 60)
+    
+    print("\nDependency Confusion Prevention:")
+    print("  - By default, only PyPI is used as package source")
+    print("  - Extra index URLs are blocked unless explicitly allowed")
+    print("  - Use --allow-extra-index to enable (shows warning)")
+    
+    print("\nExample (blocked by default):")
+    print("  praisonai install pkg --extra-index-url https://other.index.com/simple")
+    print("  → Error: Extra index URLs not allowed")
+    
+    print("\nExample (explicitly allowed):")
+    print("  praisonai install pkg --extra-index-url https://other.index.com/simple --allow-extra-index")
+    print("  → Warning shown, then proceeds")
+    
+    print("\n" + "=" * 60)
+    print("Example completed!")
+    print("=" * 60)
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/performance/lazy_imports_example.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Example: Lazy Imports & Fast Startup
+
+Demonstrates how PraisonAI Agents uses lazy imports to achieve
+fast startup times and reduced memory usage.
+"""
+import sys
+import time
+
+
+def example_verify_lazy_imports():
+    """Verify that heavy dependencies are not loaded at import time."""
+    print("=" * 60)
+    print("Lazy Imports Verification")
+    print("=" * 60)
+    
+    # Clear any cached imports
+    heavy_deps = ['litellm', 'chromadb', 'mem0', 'requests']
+    for dep in heavy_deps:
+        for key in list(sys.modules.keys()):
+            if key.startswith(dep):
+                del sys.modules[key]
+    
+    # Measure import time
+    start = time.perf_counter()
+    import praisonaiagents
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"\nImport time: {elapsed:.1f}ms")
+    print(f"Target: <200ms")
+    print(f"Status: {'PASS' if elapsed < 200 else 'FAIL'}")
+    
+    # Check lazy imports
+    print("\nLazy Import Check:")
+    all_lazy = True
+    for dep in heavy_deps:
+        is_lazy = dep not in sys.modules
+        status = "LAZY (good)" if is_lazy else "EAGER (bad)"
+        print(f"  {dep}: {status}")
+        if not is_lazy:
+            all_lazy = False
+    
+    print(f"\nAll lazy: {'PASS' if all_lazy else 'FAIL'}")
+    return all_lazy
+
+
+def example_measure_memory():
+    """Measure memory usage after import."""
+    print("\n" + "=" * 60)
+    print("Memory Usage Measurement")
+    print("=" * 60)
+    
+    import tracemalloc
+    
+    # Clear modules
+    for key in list(sys.modules.keys()):
+        if key.startswith('praisonaiagents'):
+            del sys.modules[key]
+    
+    tracemalloc.start()
+    import praisonaiagents
+    current, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    
+    current_mb = current / 1024 / 1024
+    peak_mb = peak / 1024 / 1024
+    
+    print(f"\nCurrent memory: {current_mb:.1f}MB")
+    print(f"Peak memory: {peak_mb:.1f}MB")
+    print(f"Target: <30MB")
+    print(f"Status: {'PASS' if current_mb < 30 else 'WARN' if current_mb < 45 else 'FAIL'}")
+    
+    return current_mb < 45
+
+
+def example_specific_imports():
+    """Show how to use specific imports for best performance."""
+    print("\n" + "=" * 60)
+    print("Specific Imports Example")
+    print("=" * 60)
+    
+    # Good - specific imports are fast
+    print("\nGood practice - specific imports:")
+    print("  from praisonaiagents import Agent, Task")
+    
+    # Avoid - star imports load everything
+    print("\nAvoid - star imports load more:")
+    print("  from praisonaiagents import *")
+    
+    # Example of specific import
+    from praisonaiagents import Agent
+    print(f"\nAgent class loaded: {Agent.__name__}")
+
+
+if __name__ == "__main__":
+    print("PraisonAI Agents - Lazy Imports Example")
+    print("=" * 60)
+    
+    # Run examples
+    lazy_ok = example_verify_lazy_imports()
+    memory_ok = example_measure_memory()
+    example_specific_imports()
+    
+    print("\n" + "=" * 60)
+    print("Summary")
+    print("=" * 60)
+    print(f"Lazy imports: {'PASS' if lazy_ok else 'FAIL'}")
+    print(f"Memory usage: {'PASS' if memory_ok else 'FAIL'}")
+    print(f"Overall: {'PASS' if lazy_ok and memory_ok else 'FAIL'}")

examples/performance/lite_agent_example.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Example: Lite Agent (BYO-LLM)
+
+Demonstrates the lightweight praisonaiagents.lite subpackage
+that allows you to bring your own LLM client.
+"""
+import os
+
+
+def example_custom_llm():
+    """Example using a custom LLM function."""
+    print("=" * 60)
+    print("Example 1: Custom LLM Function")
+    print("=" * 60)
+    
+    from praisonaiagents.lite import LiteAgent
+    
+    # Define a simple mock LLM
+    def mock_llm(messages):
+        """A mock LLM that echoes the last message."""
+        last_msg = messages[-1]["content"] if messages else "No message"
+        return f"Echo: {last_msg}"
+    
+    agent = LiteAgent(
+        name="EchoAgent",
+        llm_fn=mock_llm,
+        instructions="You are a simple echo agent."
+    )
+    
+    response = agent.chat("Hello, world!")
+    print(f"Response: {response}")
+    print(f"Chat history length: {len(agent.chat_history)}")
+
+
+def example_openai_adapter():
+    """Example using the built-in OpenAI adapter."""
+    print("\n" + "=" * 60)
+    print("Example 2: OpenAI Adapter")
+    print("=" * 60)
+    
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Skipping: OPENAI_API_KEY not set")
+        return
+    
+    from praisonaiagents.lite import LiteAgent, create_openai_llm_fn
+    
+    # Create LLM function using OpenAI SDK directly
+    llm_fn = create_openai_llm_fn(model="gpt-4o-mini")
+    
+    agent = LiteAgent(
+        name="OpenAIAgent",
+        llm_fn=llm_fn,
+        instructions="You are a helpful assistant. Keep responses brief."
+    )
+    
+    response = agent.chat("What is 2+2?")
+    print(f"Response: {response}")
+
+
+def example_with_tools():
+    """Example using tools with LiteAgent."""
+    print("\n" + "=" * 60)
+    print("Example 3: Tools with LiteAgent")
+    print("=" * 60)
+    
+    from praisonaiagents.lite import LiteAgent, tool
+    
+    @tool
+    def add_numbers(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+    
+    @tool
+    def multiply_numbers(a: int, b: int) -> int:
+        """Multiply two numbers together."""
+        return a * b
+    
+    def mock_llm(messages):
+        return "The calculation result is ready."
+    
+    agent = LiteAgent(
+        name="MathAgent",
+        llm_fn=mock_llm,
+        tools=[add_numbers, multiply_numbers]
+    )
+    
+    # Execute tools directly
+    result1 = agent.execute_tool("add_numbers", a=5, b=3)
+    print(f"5 + 3 = {result1.output}")
+    print(f"Success: {result1.success}")
+    
+    result2 = agent.execute_tool("multiply_numbers", a=4, b=7)
+    print(f"4 * 7 = {result2.output}")
+    print(f"Success: {result2.success}")
+
+
+def example_thread_safety():
+    """Example demonstrating thread-safe operations."""
+    print("\n" + "=" * 60)
+    print("Example 4: Thread Safety")
+    print("=" * 60)
+    
+    import threading
+    from praisonaiagents.lite import LiteAgent
+    
+    counter = [0]
+    lock = threading.Lock()
+    
+    def counting_llm(messages):
+        with lock:
+            counter[0] += 1
+            return f"Response {counter[0]}"
+    
+    agent = LiteAgent(
+        name="ThreadSafeAgent",
+        llm_fn=counting_llm
+    )
+    
+    def worker(thread_id):
+        for i in range(5):
+            agent.chat(f"Message from thread {thread_id}, iteration {i}")
+    
+    threads = [
+        threading.Thread(target=worker, args=(i,))
+        for i in range(3)
+    ]
+    
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    
+    print(f"Total messages processed: {counter[0]}")
+    print(f"Chat history length: {len(agent.chat_history)}")
+    print("Thread safety test: PASS")
+
+
+if __name__ == "__main__":
+    print("PraisonAI Agents - Lite Package Examples")
+    print("=" * 60)
+    
+    example_custom_llm()
+    example_openai_adapter()
+    example_with_tools()
+    example_thread_safety()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed!")

examples/performance/run_all_examples.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+Runner for all performance examples.
+
+Usage:
+    # Run without real API (mock only)
+    python run_all_examples.py
+    
+    # Run with real API
+    RUN_REAL_KEY_TESTS=1 OPENAI_API_KEY=your-key python run_all_examples.py
+"""
+import os
+import sys
+import subprocess
+
+
+def run_example(name, script_path):
+    """Run an example script and report results."""
+    print(f"\n{'=' * 60}")
+    print(f"Running: {name}")
+    print("=" * 60)
+    
+    result = subprocess.run(
+        [sys.executable, script_path],
+        capture_output=True,
+        text=True,
+        env=os.environ.copy()
+    )
+    
+    print(result.stdout)
+    if result.stderr:
+        print(f"STDERR: {result.stderr}")
+    
+    return result.returncode == 0
+
+
+def main():
+    """Run all performance examples."""
+    print("PraisonAI Agents - Performance Examples Runner")
+    print("=" * 60)
+    
+    # Check environment
+    real_tests = os.environ.get("RUN_REAL_KEY_TESTS")
+    has_openai = bool(os.environ.get("OPENAI_API_KEY"))
+    
+    print(f"RUN_REAL_KEY_TESTS: {real_tests or 'not set'}")
+    print(f"OPENAI_API_KEY: {'set' if has_openai else 'not set'}")
+    
+    # Get script directory
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    
+    # Define examples
+    examples = [
+        ("Lazy Imports", os.path.join(script_dir, "lazy_imports_example.py")),
+        ("Lite Agent", os.path.join(script_dir, "lite_agent_example.py")),
+        ("Thread Safety", os.path.join(script_dir, "thread_safety_example.py")),
+    ]
+    
+    # Run examples
+    results = []
+    for name, path in examples:
+        if os.path.exists(path):
+            success = run_example(name, path)
+            results.append((name, success))
+        else:
+            print(f"Skipping {name}: {path} not found")
+            results.append((name, None))
+    
+    # Summary
+    print("\n" + "=" * 60)
+    print("Summary")
+    print("=" * 60)
+    
+    passed = 0
+    failed = 0
+    skipped = 0
+    
+    for name, success in results:
+        if success is None:
+            status = "SKIPPED"
+            skipped += 1
+        elif success:
+            status = "PASS"
+            passed += 1
+        else:
+            status = "FAIL"
+            failed += 1
+        print(f"  {name}: {status}")
+    
+    print(f"\nTotal: {passed} passed, {failed} failed, {skipped} skipped")
+    
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/performance/thread_safety_example.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Example: Thread-Safe Agent State
+
+Demonstrates thread-safe chat history and cache management
+in PraisonAI Agents.
+"""
+import os
+import threading
+import time
+
+
+def example_lite_agent_thread_safety():
+    """Demonstrate thread safety with LiteAgent."""
+    print("=" * 60)
+    print("Example 1: LiteAgent Thread Safety")
+    print("=" * 60)
+    
+    from praisonaiagents.lite import LiteAgent
+    
+    # Counter for tracking responses
+    response_count = [0]
+    count_lock = threading.Lock()
+    
+    def counting_llm(messages):
+        with count_lock:
+            response_count[0] += 1
+            return f"Response #{response_count[0]}"
+    
+    agent = LiteAgent(
+        name="ThreadSafeAgent",
+        llm_fn=counting_llm
+    )
+    
+    errors = []
+    
+    def worker(thread_id):
+        try:
+            for i in range(10):
+                agent.chat(f"Thread {thread_id}, message {i}")
+        except Exception as e:
+            errors.append(e)
+    
+    # Create and start threads
+    threads = [
+        threading.Thread(target=worker, args=(i,))
+        for i in range(5)
+    ]
+    
+    start = time.perf_counter()
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    elapsed = time.perf_counter() - start
+    
+    print(f"Threads: 5")
+    print(f"Messages per thread: 10")
+    print(f"Total messages: {response_count[0]}")
+    print(f"Chat history length: {len(agent.chat_history)}")
+    print(f"Errors: {len(errors)}")
+    print(f"Time: {elapsed:.2f}s")
+    print(f"Status: {'PASS' if len(errors) == 0 else 'FAIL'}")
+
+
+def example_agent_locks():
+    """Verify Agent class has proper locks."""
+    print("\n" + "=" * 60)
+    print("Example 2: Agent Lock Verification")
+    print("=" * 60)
+    
+    from praisonaiagents import Agent
+    
+    agent = Agent(
+        name="LockTestAgent",
+        instructions="Test agent",
+        verbose=False
+    )
+    
+    # Check for locks
+    has_history_lock = hasattr(agent, '_history_lock')
+    has_cache_lock = hasattr(agent, '_cache_lock')
+    
+    print(f"Has _history_lock: {has_history_lock}")
+    print(f"Has _cache_lock: {has_cache_lock}")
+    
+    # Verify lock types
+    if has_history_lock:
+        lock_type = type(agent._history_lock).__name__
+        print(f"_history_lock type: {lock_type}")
+    
+    if has_cache_lock:
+        lock_type = type(agent._cache_lock).__name__
+        print(f"_cache_lock type: {lock_type}")
+    
+    print(f"Status: {'PASS' if has_history_lock and has_cache_lock else 'FAIL'}")
+
+
+def example_concurrent_real_api():
+    """Demonstrate concurrent API calls (requires API key)."""
+    print("\n" + "=" * 60)
+    print("Example 3: Concurrent Real API Calls")
+    print("=" * 60)
+    
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Skipping: OPENAI_API_KEY not set")
+        return
+    
+    from praisonaiagents import Agent
+    
+    agent = Agent(
+        name="ConcurrentAgent",
+        instructions="Reply with one word only.",
+        llm="gpt-4o-mini",
+        verbose=False
+    )
+    
+    results = []
+    results_lock = threading.Lock()
+    errors = []
+    
+    def worker(thread_id):
+        try:
+            response = agent.chat(f"Say hello {thread_id}")
+            with results_lock:
+                results.append((thread_id, response))
+        except Exception as e:
+            errors.append(e)
+    
+    threads = [
+        threading.Thread(target=worker, args=(i,))
+        for i in range(3)
+    ]
+    
+    start = time.perf_counter()
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    elapsed = time.perf_counter() - start
+    
+    print(f"Concurrent requests: 3")
+    print(f"Successful responses: {len(results)}")
+    print(f"Errors: {len(errors)}")
+    print(f"Time: {elapsed:.2f}s")
+    print(f"Status: {'PASS' if len(errors) == 0 else 'FAIL'}")
+
+
+if __name__ == "__main__":
+    print("PraisonAI Agents - Thread Safety Examples")
+    print("=" * 60)
+    
+    example_lite_agent_thread_safety()
+    example_agent_locks()
+    example_concurrent_real_api()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed!")

examples/policy/README.md

@@ -0,0 +1,80 @@
+# Policy Packs Example
+
+This example demonstrates how to use PraisonAI policy packs for managing tool permissions, data policies, and execution modes.
+
+## Features Demonstrated
+
+- Creating and loading policy packs
+- Tool permission checking (allow/deny)
+- Policy modes (dev/prod)
+- Merging policies
+- Data and PII policies
+
+## Quick Start
+
+```bash
+python policy_example.py
+```
+
+## CLI Commands
+
+```bash
+# Show default policy
+praisonai recipe policy show
+
+# Show policy from file
+praisonai recipe policy show my-policy.yaml
+
+# Create policy template
+praisonai recipe policy init -o my-policy.yaml
+
+# Validate policy file
+praisonai recipe policy validate my-policy.yaml
+```
+
+## Policy File Format
+
+```yaml
+name: my-org-policy
+version: "1.0"
+
+tools:
+  allow:
+    - web.search
+    - db.query
+  deny:
+    - shell.exec
+    - file.write
+
+network:
+  allow_domains:
+    - api.openai.com
+  deny_domains:
+    - localhost
+
+pii:
+  mode: redact  # allow, deny, redact
+  fields:
+    - email
+    - phone
+
+data:
+  retention_days: 30
+  export_allowed: true
+
+modes:
+  dev:
+    allow_interactive_prompts: true
+    strict_tool_enforcement: false
+  prod:
+    allow_interactive_prompts: false
+    strict_tool_enforcement: true
+    require_auth: true
+```
+
+## Using Policy with Recipe Run
+
+```bash
+# Run with policy file
+praisonai recipe run my-recipe --policy my-policy.yaml --mode prod
+```

examples/policy/policy_example.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Policy Packs Example
+
+This example demonstrates:
+1. Creating and loading policy packs
+2. Tool permission checking
+3. Policy modes (dev/prod)
+4. Merging policies
+
+Prerequisites:
+- pip install praisonai
+
+Usage:
+    python policy_example.py
+"""
+
+import tempfile
+from pathlib import Path
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Policy Packs Example")
+    print("=" * 60)
+    
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        
+        # =====================================================
+        # Default Policies
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Default Policies")
+        print("=" * 40)
+        
+        from praisonai.recipe.policy import get_default_policy, PolicyPack, PolicyDeniedError
+        
+        print("\n1. Loading default dev policy...")
+        dev_policy = get_default_policy("dev")
+        print(f"   Name: {dev_policy.name}")
+        print(f"   Allowed tools: {len(dev_policy.allowed_tools)}")
+        print(f"   Denied tools: {len(dev_policy.denied_tools)}")
+        print(f"   PII mode: {dev_policy.pii_mode}")
+        
+        print("\n2. Loading default prod policy...")
+        prod_policy = get_default_policy("prod")
+        print(f"   Name: {prod_policy.name}")
+        print(f"   PII mode: {prod_policy.pii_mode}")
+        
+        # =====================================================
+        # Tool Permission Checking
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Tool Permission Checking")
+        print("=" * 40)
+        
+        print("\n3. Checking tool permissions...")
+        
+        # Check allowed tool
+        try:
+            dev_policy.check_tool("web.search")
+            print("   web.search: ✓ Allowed")
+        except PolicyDeniedError as e:
+            print(f"   web.search: ✗ Denied - {e}")
+        
+        # Check denied tool
+        try:
+            dev_policy.check_tool("shell.exec")
+            print("   shell.exec: ✓ Allowed")
+        except PolicyDeniedError:
+            print("   shell.exec: ✗ Denied")
+        
+        # Check another denied tool
+        try:
+            dev_policy.check_tool("file.write")
+            print("   file.write: ✓ Allowed")
+        except PolicyDeniedError:
+            print("   file.write: ✗ Denied")
+        
+        # =====================================================
+        # Custom Policy Pack
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Custom Policy Pack")
+        print("=" * 40)
+        
+        print("\n4. Creating custom policy pack...")
+        custom_policy = PolicyPack(
+            name="my-org-policy",
+            config={
+                "tools": {
+                    "allow": ["web.search", "db.query", "file.read"],
+                    "deny": ["shell.exec", "network.unrestricted"],
+                },
+                "network": {
+                    "allow_domains": ["api.openai.com", "api.anthropic.com"],
+                    "deny_domains": ["localhost", "127.0.0.1"],
+                },
+                "pii": {
+                    "mode": "redact",
+                    "fields": ["email", "phone", "ssn"],
+                },
+                "data": {
+                    "retention_days": 30,
+                    "export_allowed": True,
+                },
+                "modes": {
+                    "dev": {
+                        "allow_interactive_prompts": True,
+                        "strict_tool_enforcement": False,
+                    },
+                    "prod": {
+                        "allow_interactive_prompts": False,
+                        "strict_tool_enforcement": True,
+                        "require_auth": True,
+                    },
+                },
+            },
+        )
+        
+        print(f"   Name: {custom_policy.name}")
+        print(f"   Allowed tools: {list(custom_policy.allowed_tools)}")
+        print(f"   PII mode: {custom_policy.pii_mode}")
+        print(f"   Retention days: {custom_policy.retention_days}")
+        
+        # =====================================================
+        # Saving and Loading Policies
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Saving and Loading Policies")
+        print("=" * 40)
+        
+        print("\n5. Saving policy to file...")
+        policy_file = tmp_path / "my-policy.yaml"
+        custom_policy.save(policy_file)
+        print(f"   Saved to: {policy_file}")
+        
+        print("\n6. Loading policy from file...")
+        loaded_policy = PolicyPack.load(policy_file)
+        print(f"   Loaded: {loaded_policy.name}")
+        print(f"   PII mode: {loaded_policy.pii_mode}")
+        
+        # =====================================================
+        # Merging Policies
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Merging Policies")
+        print("=" * 40)
+        
+        print("\n7. Creating base and override policies...")
+        base_policy = PolicyPack(
+            name="base",
+            config={
+                "tools": {"allow": ["web.search"]},
+                "pii": {"mode": "allow"},
+            },
+        )
+        
+        override_policy = PolicyPack(
+            name="override",
+            config={
+                "tools": {"allow": ["db.query"]},
+                "pii": {"mode": "redact", "fields": ["email"]},
+            },
+        )
+        
+        print("\n8. Merging policies...")
+        merged = base_policy.merge(override_policy)
+        print(f"   Merged name: {merged.name}")
+        print(f"   Allowed tools: {list(merged.allowed_tools)}")
+        print(f"   PII mode: {merged.pii_mode}")
+        
+        # =====================================================
+        # Mode-Specific Configuration
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Mode-Specific Configuration")
+        print("=" * 40)
+        
+        print("\n9. Getting mode-specific config...")
+        dev_config = custom_policy.get_mode_config("dev")
+        prod_config = custom_policy.get_mode_config("prod")
+        
+        print("   Dev mode:")
+        print(f"     - Interactive prompts: {dev_config.get('allow_interactive_prompts')}")
+        print(f"     - Strict enforcement: {dev_config.get('strict_tool_enforcement')}")
+        
+        print("   Prod mode:")
+        print(f"     - Interactive prompts: {prod_config.get('allow_interactive_prompts')}")
+        print(f"     - Strict enforcement: {prod_config.get('strict_tool_enforcement')}")
+        print(f"     - Require auth: {prod_config.get('require_auth')}")
+        
+        # =====================================================
+        # Data Policy
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Data Policy")
+        print("=" * 40)
+        
+        print("\n10. Getting data policy...")
+        data_policy = custom_policy.get_data_policy()
+        print(f"   PII mode: {data_policy['pii']['mode']}")
+        print(f"   PII fields: {data_policy['pii']['fields']}")
+        print(f"   Retention days: {data_policy['retention_days']}")
+        print(f"   Export allowed: {data_policy['export_allowed']}")
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/recipes/creator_suite/.env.example

@@ -0,0 +1,11 @@
+# Creator Suite Examples - Environment Variables
+
+# Required for most features
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional - for web search in news crawler
+TAVILY_API_KEY=your_tavily_api_key_here
+
+# Optional - for additional LLM providers
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_API_KEY=your_google_api_key_here

examples/recipes/creator_suite/README.md

@@ -0,0 +1,77 @@
+# Creator Suite Examples
+
+Examples for the PraisonAI Creator Automation Suite - a complete toolkit for AI content creators.
+
+## Quick Start
+
+```bash
+# Set your API key
+export OPENAI_API_KEY=your_key_here
+
+# Run an example
+python news_crawler_example.py
+python script_writer_example.py
+python hook_generator_example.py
+python brief_generator_example.py
+```
+
+## Examples
+
+| Example | Description | API Key Required |
+|---------|-------------|------------------|
+| `news_crawler_example.py` | Crawl AI news from multiple sources | No (HN, arXiv) |
+| `script_writer_example.py` | Generate scripts for YouTube, X, LinkedIn | Yes (OpenAI) |
+| `hook_generator_example.py` | Generate attention-grabbing hooks | Yes (OpenAI) |
+| `brief_generator_example.py` | Generate news briefs | Yes (OpenAI) |
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and fill in your API keys:
+
+```bash
+cp .env.example .env
+```
+
+## Features Covered
+
+### News Intelligence Layer
+- AI News Crawler
+- AI News Deduper
+- AI Signal Ranker
+- AI Context Enricher
+- AI Brief Generator
+
+### Script & Story Layer
+- AI Script Writer
+- AI Angle Generator
+- AI Hook Generator
+- AI CTA Generator
+- AI Fact Checker
+
+### Capture & Screen Automation
+- AI Screenshot Capture
+- AI Screen Recorder
+- AI News Capture Pack
+
+### Video Generation
+- AI B-roll Builder
+- AI Voiceover Generator
+- AI Video Merger
+
+### Publishing & Distribution
+- AI Publisher Pack
+- AI Content Calendar
+- AI Post Copy Generator
+- AI Hashtag Optimizer
+
+### Feedback & Learning
+- AI Performance Analyzer
+- AI Comment Miner
+- AI A/B Hook Tester
+
+### Orchestrator
+- AI Daily News Show (end-to-end pipeline)
+
+## Documentation
+
+Full documentation: https://docs.praison.ai/docs/ai-tools/creator-suite/

examples/recipes/creator_suite/brief_generator_example.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+AI Brief Generator Example
+
+Demonstrates generating news briefs from articles.
+Requires: OPENAI_API_KEY
+"""
+
+import os
+import sys
+
+# Check for API key
+if not os.environ.get("OPENAI_API_KEY"):
+    print("ERROR: OPENAI_API_KEY environment variable required")
+    print("Set it with: export OPENAI_API_KEY=your_key")
+    sys.exit(1)
+
+# Add the Agent-Recipes templates to path
+sys.path.insert(0, '/Users/praison/Agent-Recipes/agent_recipes/templates/ai-brief-generator')
+
+from tools import generate_brief, extract_highlights
+
+
+def main():
+    print("=" * 60)
+    print("AI Brief Generator Example")
+    print("=" * 60)
+    
+    # Sample articles
+    articles = [
+        {
+            "title": "OpenAI Releases GPT-5 with Multimodal Capabilities",
+            "content": "OpenAI announced GPT-5 today with major improvements in reasoning, multimodal understanding, and reduced hallucinations.",
+            "source": "TechCrunch",
+            "url": "https://example.com/gpt5"
+        },
+        {
+            "title": "Google Gemini 2.0 Launches with Real-time Video Understanding",
+            "content": "Google unveiled Gemini 2.0 with breakthrough capabilities in real-time video analysis and native tool use.",
+            "source": "The Verge",
+            "url": "https://example.com/gemini2"
+        },
+        {
+            "title": "Anthropic Claude 4 Sets New Benchmarks",
+            "content": "Anthropic's Claude 4 achieves state-of-the-art results on coding, math, and reasoning benchmarks.",
+            "source": "Wired",
+            "url": "https://example.com/claude4"
+        }
+    ]
+    
+    # 1. Generate daily brief
+    print("\n1. Generating daily brief...")
+    brief = generate_brief(articles, format="daily", max_articles=3)
+    print(f"   Format: daily")
+    print(f"   Articles included: {brief.get('article_count', 0)}")
+    print(f"\n   Brief preview:\n   {brief.get('brief', '')[:500]}...")
+    
+    # 2. Extract highlights
+    print("\n2. Extracting highlights...")
+    highlights = extract_highlights(articles, num_highlights=3)
+    print(f"   Highlights:")
+    for h in highlights.get('highlights', []):
+        print(f"   - {h}")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/recipes/creator_suite/hook_generator_example.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+AI Hook Generator Example
+
+Demonstrates generating attention-grabbing hooks.
+Requires: OPENAI_API_KEY
+"""
+
+import os
+import sys
+
+# Check for API key
+if not os.environ.get("OPENAI_API_KEY"):
+    print("ERROR: OPENAI_API_KEY environment variable required")
+    print("Set it with: export OPENAI_API_KEY=your_key")
+    sys.exit(1)
+
+# Add the Agent-Recipes templates to path
+sys.path.insert(0, '/Users/praison/Agent-Recipes/agent_recipes/templates/ai-hook-generator')
+
+from tools import generate_hooks, rank_hooks
+
+
+def main():
+    print("=" * 60)
+    print("AI Hook Generator Example")
+    print("=" * 60)
+    
+    topic = "GPT-5 just released with groundbreaking capabilities"
+    
+    # 1. Generate hooks
+    print(f"\n1. Generating hooks for: '{topic}'")
+    hooks = generate_hooks(topic, num_variants=5)
+    print(f"   Generated {len(hooks.get('hooks', []))} hooks:")
+    
+    for hook in hooks.get('hooks', []):
+        print(f"\n   [{hook.get('style', 'unknown')}]")
+        print(f"   {hook.get('text', '')}")
+    
+    # 2. Rank hooks
+    print("\n2. Ranking hooks by engagement potential...")
+    ranked = rank_hooks(hooks.get('hooks', []))
+    best = ranked.get('best_hook', {})
+    print(f"\n   Best hook (score: {best.get('score', 0)}):")
+    print(f"   {best.get('text', '')}")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/recipes/creator_suite/news_crawler_example.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+AI News Crawler Example
+
+Demonstrates crawling AI news from multiple sources.
+"""
+
+import os
+import sys
+
+# Add the Agent-Recipes templates to path
+sys.path.insert(0, '/Users/praison/Agent-Recipes/agent_recipes/templates/ai-news-crawler')
+
+from tools import crawl_hackernews, crawl_reddit_ai, crawl_arxiv, crawl_ai_news
+
+
+def main():
+    print("=" * 60)
+    print("AI News Crawler Example")
+    print("=" * 60)
+    
+    # 1. Crawl HackerNews (no API key needed)
+    print("\n1. Crawling HackerNews...")
+    hn_articles = crawl_hackernews(max_articles=5, time_window_hours=48)
+    print(f"   Found {len(hn_articles)} articles from HackerNews")
+    for article in hn_articles[:3]:
+        print(f"   - {article.get('title', 'No title')[:60]}...")
+    
+    # 2. Crawl arXiv (no API key needed)
+    print("\n2. Crawling arXiv...")
+    arxiv_articles = crawl_arxiv(categories=["cs.AI", "cs.LG"], max_results=5)
+    print(f"   Found {len(arxiv_articles)} articles from arXiv")
+    for article in arxiv_articles[:3]:
+        print(f"   - {article.get('title', 'No title')[:60]}...")
+    
+    # 3. Full crawl from multiple sources
+    print("\n3. Full multi-source crawl...")
+    all_articles = crawl_ai_news(
+        sources=["hackernews", "arxiv"],
+        max_articles=10,
+        time_window_hours=48
+    )
+    print(f"   Total articles: {all_articles.get('total', 0)}")
+    print(f"   Sources crawled: {all_articles.get('sources_crawled', [])}")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/recipes/creator_suite/script_writer_example.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""
+AI Script Writer Example
+
+Demonstrates generating scripts for different platforms.
+Requires: OPENAI_API_KEY
+"""
+
+import os
+import sys
+
+# Check for API key
+if not os.environ.get("OPENAI_API_KEY"):
+    print("ERROR: OPENAI_API_KEY environment variable required")
+    print("Set it with: export OPENAI_API_KEY=your_key")
+    sys.exit(1)
+
+# Add the Agent-Recipes templates to path
+sys.path.insert(0, '/Users/praison/Agent-Recipes/agent_recipes/templates/ai-script-writer')
+
+from tools import write_youtube_script, write_short_script, write_thread
+
+
+def main():
+    print("=" * 60)
+    print("AI Script Writer Example")
+    print("=" * 60)
+    
+    topic = "AI agents are revolutionizing software development"
+    
+    # 1. YouTube Long-form Script
+    print("\n1. Generating YouTube long-form script...")
+    yt_script = write_youtube_script(
+        topic=topic,
+        target_length=180,
+        key_points=["automation", "productivity", "future of coding"]
+    )
+    print(f"   Format: {yt_script.get('format')}")
+    print(f"   Estimated duration: {yt_script.get('estimated_duration')}s")
+    print(f"   Script preview:\n   {yt_script.get('script', '')[:200]}...")
+    
+    # 2. YouTube Short Script
+    print("\n2. Generating YouTube Short script...")
+    short_script = write_short_script(topic, duration=30)
+    print(f"   Format: {short_script.get('format')}")
+    print(f"   Script:\n   {short_script.get('script', '')[:300]}...")
+    
+    # 3. X Thread
+    print("\n3. Generating X thread...")
+    thread = write_thread(topic, num_tweets=3)
+    print(f"   Thread ({len(thread.get('tweets', []))} tweets):")
+    for i, tweet in enumerate(thread.get('tweets', [])[:3], 1):
+        print(f"   Tweet {i}: {tweet[:80]}...")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/recipes/example_llm_recipes.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Example: LLM-based Recipes
+
+Demonstrates usage of LLM-powered recipes:
+- ai-blog-generator
+- ai-social-media-generator
+- ai-faq-generator
+- ai-sentiment-analyzer
+"""
+
+import os
+import sys
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    sys.exit(1)
+
+# Add recipe tools to path
+sys.path.insert(0, "/Users/praison/PraisonAI-tools/praisonai_tools/recipe_tools")
+
+from llm_tool import LLMTool, llm_complete
+
+
+def example_blog_generator():
+    """Generate a blog post."""
+    print("\n=== AI Blog Generator ===")
+    
+    llm = LLMTool(provider="openai", model="gpt-4o-mini")
+    
+    topic = "The Future of AI in Healthcare"
+    
+    response = llm.complete(
+        f"""Write a short blog post (3 paragraphs) about: {topic}
+        
+Include:
+- Engaging introduction
+- Key points
+- Call to action
+
+Format as markdown.""",
+        system="You are an expert blog writer specializing in technology topics.",
+        max_tokens=500,
+    )
+    
+    print(f"Topic: {topic}")
+    print(f"\nGenerated Blog Post:\n{response.content}")
+    print(f"\nTokens used: {response.usage.get('total_tokens', 'N/A')}")
+
+
+def example_social_media_generator():
+    """Generate social media posts."""
+    print("\n=== AI Social Media Generator ===")
+    
+    llm = LLMTool(provider="openai", model="gpt-4o-mini")
+    
+    content = "We just launched our new AI-powered productivity app!"
+    
+    response = llm.complete(
+        f"""Create social media posts for the following announcement:
+{content}
+
+Generate posts for:
+1. Twitter (280 chars max)
+2. LinkedIn (professional tone)
+3. Instagram (with emoji suggestions)
+
+Format each clearly.""",
+        system="You are a social media marketing expert.",
+        max_tokens=400,
+    )
+    
+    print(f"Content: {content}")
+    print(f"\nGenerated Posts:\n{response.content}")
+
+
+def example_faq_generator():
+    """Generate FAQ from content."""
+    print("\n=== AI FAQ Generator ===")
+    
+    llm = LLMTool(provider="openai", model="gpt-4o-mini")
+    
+    documentation = """
+    Our product is a cloud-based project management tool.
+    It supports team collaboration, task tracking, and reporting.
+    Pricing starts at $10/month per user.
+    We offer a 14-day free trial.
+    Integration with Slack, GitHub, and Jira is available.
+    """
+    
+    response = llm.complete(
+        f"""Based on this documentation, generate 5 FAQ questions and answers:
+
+{documentation}
+
+Format as:
+Q: [question]
+A: [answer]
+""",
+        system="You are a technical writer creating FAQ documentation.",
+        max_tokens=400,
+    )
+    
+    print(f"Generated FAQ:\n{response.content}")
+
+
+def example_sentiment_analyzer():
+    """Analyze sentiment in text."""
+    print("\n=== AI Sentiment Analyzer ===")
+    
+    llm = LLMTool(provider="openai", model="gpt-4o-mini")
+    
+    reviews = [
+        "This product is amazing! Best purchase ever.",
+        "Terrible experience. Would not recommend.",
+        "It's okay, nothing special but does the job.",
+    ]
+    
+    for review in reviews:
+        response = llm.complete(
+            f"""Analyze the sentiment of this text and respond with ONLY one word: POSITIVE, NEGATIVE, or NEUTRAL
+
+Text: {review}""",
+            max_tokens=10,
+        )
+        print(f"Review: {review[:50]}...")
+        print(f"Sentiment: {response.content.strip()}\n")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("LLM-Based Recipes Examples")
+    print("=" * 60)
+    
+    example_blog_generator()
+    example_social_media_generator()
+    example_faq_generator()
+    example_sentiment_analyzer()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed!")
+    print("=" * 60)

examples/recipes/run_all_recipes.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""
+Run All Recipes - Test harness for all Agent-Recipes.
+
+Runs each recipe in dry-run mode to verify CLI parity and run.json generation.
+Requires: OPENAI_API_KEY environment variable for integration tests.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import List
+
+# Recipe definitions
+RECIPES = [
+    "ai-audio-normalizer",
+    "ai-audio-splitter",
+    "ai-changelog-generator",
+    "ai-code-documenter",
+    "ai-csv-cleaner",
+    "ai-data-profiler",
+    "ai-dependency-auditor",
+    "ai-doc-translator",
+    "ai-folder-packager",
+    "ai-image-cataloger",
+    "ai-image-optimizer",
+    "ai-image-resizer",
+    "ai-json-to-csv",
+    "ai-markdown-to-pdf",
+    "ai-pdf-summarizer",
+    "ai-pdf-to-markdown",
+    "ai-podcast-cleaner",
+    "ai-repo-readme",
+    "ai-schema-generator",
+    "ai-screenshot-ocr",
+    "ai-sitemap-scraper",
+    "ai-slide-to-notes",
+    "ai-url-to-markdown",
+    "ai-video-editor",
+    "ai-video-thumbnails",
+    "ai-video-to-gif",
+]
+
+
+@dataclass
+class TestResult:
+    """Result of a recipe test."""
+    recipe: str
+    status: str  # pass, fail, skip
+    reason: str = ""
+    duration: float = 0.0
+
+
+def check_api_keys() -> dict:
+    """Check available API keys."""
+    keys = {
+        "OPENAI_API_KEY": bool(os.environ.get("OPENAI_API_KEY")),
+        "ANTHROPIC_API_KEY": bool(os.environ.get("ANTHROPIC_API_KEY")),
+        "GOOGLE_API_KEY": bool(os.environ.get("GOOGLE_API_KEY")),
+    }
+    return keys
+
+
+def check_external_deps() -> dict:
+    """Check external dependencies."""
+    import shutil
+    deps = {
+        "ffmpeg": shutil.which("ffmpeg") is not None,
+        "ffprobe": shutil.which("ffprobe") is not None,
+        "pdftotext": shutil.which("pdftotext") is not None,
+        "pandoc": shutil.which("pandoc") is not None,
+        "git": shutil.which("git") is not None,
+    }
+    return deps
+
+
+def run_recipe_dry_run(recipe: str, timeout: int = 30) -> TestResult:
+    """Run a recipe in dry-run mode."""
+    import time
+    start = time.time()
+    
+    try:
+        # Use praison templates run command with dry-run
+        cmd = ["praison", "templates", "run", recipe, "--dry-run", "dummy_input"]
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        
+        duration = time.time() - start
+        
+        if result.returncode == 0:
+            return TestResult(recipe, "pass", "dry-run completed", duration)
+        else:
+            # Check if it's a missing dependency error
+            stderr = result.stderr.lower()
+            if "not found" in stderr or "missing" in stderr:
+                return TestResult(recipe, "skip", f"Missing dependency: {result.stderr[:100]}", duration)
+            return TestResult(recipe, "fail", f"Exit code {result.returncode}: {result.stderr[:100]}", duration)
+            
+    except subprocess.TimeoutExpired:
+        return TestResult(recipe, "fail", "Timeout", timeout)
+    except FileNotFoundError:
+        return TestResult(recipe, "skip", "praison CLI not found", 0)
+    except Exception as e:
+        return TestResult(recipe, "fail", str(e), 0)
+
+
+def run_all_recipes(dry_run_only: bool = True) -> List[TestResult]:
+    """Run all recipes and collect results."""
+    results = []
+    
+    print("=" * 60)
+    print("RECIPE TEST HARNESS")
+    print("=" * 60)
+    
+    # Check prerequisites
+    keys = check_api_keys()
+    deps = check_external_deps()
+    
+    print("\nAPI Keys:")
+    for key, present in keys.items():
+        status = "✓" if present else "✗"
+        print(f"  {status} {key}")
+    
+    print("\nExternal Dependencies:")
+    for dep, present in deps.items():
+        status = "✓" if present else "✗"
+        print(f"  {status} {dep}")
+    
+    print("\n" + "=" * 60)
+    print(f"Running {len(RECIPES)} recipes (dry-run={dry_run_only})")
+    print("=" * 60 + "\n")
+    
+    for i, recipe in enumerate(RECIPES, 1):
+        print(f"[{i:2d}/{len(RECIPES)}] {recipe}...", end=" ", flush=True)
+        
+        if dry_run_only:
+            result = run_recipe_dry_run(recipe)
+        else:
+            # Full run would go here
+            result = run_recipe_dry_run(recipe)
+        
+        results.append(result)
+        
+        if result.status == "pass":
+            print(f"✓ ({result.duration:.1f}s)")
+        elif result.status == "skip":
+            print(f"⊘ SKIP: {result.reason}")
+        else:
+            print(f"✗ FAIL: {result.reason}")
+    
+    return results
+
+
+def print_summary(results: List[TestResult]):
+    """Print test summary."""
+    passed = sum(1 for r in results if r.status == "pass")
+    failed = sum(1 for r in results if r.status == "fail")
+    skipped = sum(1 for r in results if r.status == "skip")
+    
+    print("\n" + "=" * 60)
+    print("SUMMARY")
+    print("=" * 60)
+    print(f"  Passed:  {passed}")
+    print(f"  Failed:  {failed}")
+    print(f"  Skipped: {skipped}")
+    print(f"  Total:   {len(results)}")
+    
+    if failed > 0:
+        print("\nFailed recipes:")
+        for r in results:
+            if r.status == "fail":
+                print(f"  - {r.recipe}: {r.reason}")
+    
+    return failed == 0
+
+
+def main():
+    """Main entry point."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Run all Agent-Recipes tests")
+    parser.add_argument("--full", action="store_true", help="Run full tests (not just dry-run)")
+    parser.add_argument("--recipe", help="Run specific recipe only")
+    parser.add_argument("--json", action="store_true", help="Output JSON results")
+    args = parser.parse_args()
+    
+    if args.recipe:
+        results = [run_recipe_dry_run(args.recipe)]
+    else:
+        results = run_all_recipes(dry_run_only=not args.full)
+    
+    if args.json:
+        output = [{"recipe": r.recipe, "status": r.status, "reason": r.reason} for r in results]
+        print(json.dumps(output, indent=2))
+    else:
+        success = print_summary(results)
+        sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

examples/registry/README.md

@@ -0,0 +1,71 @@
+# Recipe Registry Example
+
+This example demonstrates how to use the PraisonAI recipe registry for publishing and pulling recipes via both local filesystem and HTTP server.
+
+## Features Demonstrated
+
+- Creating a local registry
+- Starting an HTTP registry server
+- Publishing recipes with token authentication
+- Listing and searching recipes
+- Pulling recipes from HTTP registry
+
+## Quick Start
+
+```bash
+# Run the HTTP registry example
+python http_registry_example.py
+```
+
+## HTTP Registry Server
+
+```bash
+# Start HTTP registry server
+praisonai registry serve --port 7777
+
+# Start with authentication
+praisonai registry serve --port 7777 --token mysecret
+
+# Check server status
+praisonai registry status --registry http://localhost:7777
+```
+
+## CLI Commands with HTTP Registry
+
+```bash
+# Publish to HTTP registry
+praisonai recipe publish ./my-recipe --registry http://localhost:7777 --json
+
+# Publish with token
+praisonai recipe publish ./my-recipe --registry http://localhost:7777 --token mysecret
+
+# Pull from HTTP registry
+praisonai recipe pull [email protected] --registry http://localhost:7777 -o ./recipes
+
+# List recipes from HTTP registry
+praisonai recipe list --registry http://localhost:7777 --json
+
+# Search HTTP registry
+praisonai recipe search "hello" --registry http://localhost:7777
+```
+
+## Local Registry Commands
+
+```bash
+# Publish to local registry (default)
+praisonai recipe publish ./my-recipe --json
+
+# Pull from local registry
+praisonai recipe pull [email protected] -o ./recipes
+
+# Use custom local path
+praisonai recipe publish ./my-recipe --registry /path/to/registry
+```
+
+## Environment Variables
+
+- `PRAISONAI_REGISTRY_TOKEN` - Default token for HTTP registry authentication
+
+## Default Registry Location
+
+By default, the local registry is stored at `~/.praison/registry`.

examples/registry/http_registry_example.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+HTTP Recipe Registry Example
+
+This example demonstrates:
+1. Starting an HTTP registry server programmatically
+2. Publishing recipes with token authentication
+3. Listing and searching recipes via HTTP
+4. Pulling recipes from HTTP registry
+
+Requirements:
+- praisonai installed
+- No external API keys required (local registry only)
+
+Environment Variables (optional):
+- PRAISONAI_REGISTRY_TOKEN: Token for authentication
+"""
+
+import sys
+import json
+import time
+import shutil
+import tarfile
+import tempfile
+import subprocess
+from pathlib import Path
+
+def create_sample_recipe(output_dir: Path) -> Path:
+    """Create a sample recipe for testing."""
+    recipe_dir = output_dir / "sample-agent"
+    recipe_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create manifest.json
+    manifest = {
+        "name": "sample-agent",
+        "version": "1.0.0",
+        "description": "A sample agent recipe for registry testing",
+        "tags": ["sample", "agent", "test"],
+        "author": "praison",
+        "files": ["recipe.yaml"]
+    }
+    (recipe_dir / "manifest.json").write_text(json.dumps(manifest, indent=2))
+    
+    # Create recipe.yaml
+    recipe_yaml = """
+name: sample-agent
+version: "1.0.0"
+description: A sample agent recipe
+
+agents:
+  - name: assistant
+    role: General Assistant
+    goal: Help users with their questions
+    instructions: You are a helpful assistant.
+
+tasks:
+  - name: respond
+    description: Respond to user query
+    agent: assistant
+"""
+    (recipe_dir / "recipe.yaml").write_text(recipe_yaml.strip())
+    
+    # Pack into .praison bundle
+    bundle_path = output_dir / "sample-agent-1.0.0.praison"
+    with tarfile.open(bundle_path, "w:gz") as tar:
+        for file in recipe_dir.iterdir():
+            tar.add(file, arcname=file.name)
+    
+    return bundle_path
+
+
+def start_registry_server(port: int, registry_path: Path, token: str = None):
+    """Start registry server in background process."""
+    cmd = [
+        sys.executable, "-c",
+        f"""
+import sys
+sys.path.insert(0, '/Users/praison/praisonai-package/src/praisonai')
+from praisonai.recipe.server import create_wsgi_app
+from wsgiref.simple_server import make_server, WSGIRequestHandler
+from pathlib import Path
+
+class QuietHandler(WSGIRequestHandler):
+    def log_message(self, format, *args):
+        pass
+
+app = create_wsgi_app(registry_path=Path("{registry_path}"), token={repr(token)})
+server = make_server("127.0.0.1", {port}, app, handler_class=QuietHandler)
+server.serve_forever()
+"""
+    ]
+    
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    return proc
+
+
+def main():
+    print("=" * 60)
+    print("HTTP Recipe Registry Example")
+    print("=" * 60)
+    
+    # Setup
+    work_dir = Path(tempfile.mkdtemp(prefix="registry_example_"))
+    registry_path = work_dir / "registry"
+    pulled_dir = work_dir / "pulled"
+    port = 7799
+    token = "example-secret-token"
+    
+    print(f"\nWork directory: {work_dir}")
+    print(f"Registry path: {registry_path}")
+    print(f"Server port: {port}")
+    print(f"Token: {'*' * len(token)} (redacted)")
+    
+    try:
+        # 1. Create sample recipe
+        print("\n[1] Creating sample recipe...")
+        bundle_path = create_sample_recipe(work_dir)
+        print(f"    ✓ Created bundle: {bundle_path.name}")
+        
+        # 2. Start HTTP registry server
+        print("\n[2] Starting HTTP registry server...")
+        server = start_registry_server(port, registry_path, token)
+        time.sleep(1)  # Wait for server to start
+        print(f"    ✓ Server running on http://127.0.0.1:{port}")
+        
+        # 3. Check health
+        print("\n[3] Checking server health...")
+        result = subprocess.run(
+            ["curl", "-s", f"http://127.0.0.1:{port}/healthz"],
+            capture_output=True, text=True
+        )
+        health = json.loads(result.stdout)
+        print(f"    Status: {health['status']}")
+        print(f"    Auth required: {health['auth_required']}")
+        
+        # 4. Publish WITHOUT token (should fail)
+        print("\n[4] Publishing WITHOUT token (expect failure)...")
+        result = subprocess.run(
+            ["python3", "-m", "praisonai", "recipe", "publish", str(bundle_path),
+             "--registry", f"http://127.0.0.1:{port}", "--json"],
+            capture_output=True, text=True,
+            cwd="/Users/praison/praisonai-package/src/praisonai"
+        )
+        if result.returncode != 0 or "error" in result.stdout.lower() or "401" in result.stdout:
+            print("    ✓ Correctly rejected (authentication required)")
+        else:
+            print(f"    ✗ Unexpected success: {result.stdout}")
+        
+        # 5. Publish WITH token (should succeed)
+        print("\n[5] Publishing WITH token...")
+        result = subprocess.run(
+            ["python3", "-m", "praisonai", "recipe", "publish", str(bundle_path),
+             "--registry", f"http://127.0.0.1:{port}", "--token", token, "--json"],
+            capture_output=True, text=True,
+            cwd="/Users/praison/praisonai-package/src/praisonai"
+        )
+        try:
+            data = json.loads(result.stdout)
+            if data.get("ok"):
+                print(f"    ✓ Published: {data['name']}@{data['version']}")
+            else:
+                print(f"    ✗ Failed: {result.stdout}")
+                return 1
+        except json.JSONDecodeError:
+            print(f"    Output: {result.stdout}")
+            print(f"    Stderr: {result.stderr}")
+            return 1
+        
+        # 6. List recipes
+        print("\n[6] Listing recipes from registry...")
+        result = subprocess.run(
+            ["python3", "-m", "praisonai", "recipe", "list",
+             "--registry", f"http://127.0.0.1:{port}", "--json"],
+            capture_output=True, text=True,
+            cwd="/Users/praison/praisonai-package/src/praisonai"
+        )
+        recipes = json.loads(result.stdout)
+        print(f"    Found {len(recipes)} recipe(s):")
+        for r in recipes:
+            print(f"      - {r['name']} v{r['version']}: {r.get('description', '')[:40]}")
+        
+        # 7. Search recipes
+        print("\n[7] Searching for 'agent'...")
+        result = subprocess.run(
+            ["python3", "-m", "praisonai", "recipe", "search", "agent",
+             "--registry", f"http://127.0.0.1:{port}", "--json"],
+            capture_output=True, text=True,
+            cwd="/Users/praison/praisonai-package/src/praisonai"
+        )
+        matches = json.loads(result.stdout)
+        print(f"    Found {len(matches)} match(es)")
+        
+        # 8. Pull recipe
+        print("\n[8] Pulling recipe...")
+        pulled_dir.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["python3", "-m", "praisonai", "recipe", "pull", "sample-agent",
+             "--registry", f"http://127.0.0.1:{port}", "-o", str(pulled_dir), "--json"],
+            capture_output=True, text=True,
+            cwd="/Users/praison/praisonai-package/src/praisonai"
+        )
+        data = json.loads(result.stdout)
+        if data.get("ok"):
+            print(f"    ✓ Pulled to: {data['path']}")
+            
+            # Verify content
+            manifest_path = Path(data['path']) / "manifest.json"
+            if manifest_path.exists():
+                manifest = json.loads(manifest_path.read_text())
+                print(f"    ✓ Verified: {manifest['name']}@{manifest['version']}")
+        else:
+            print(f"    ✗ Failed: {result.stdout}")
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+        
+        # Cleanup
+        server.terminate()
+        server.wait()
+        
+    finally:
+        # Clean up temp directory
+        shutil.rmtree(work_dir, ignore_errors=True)
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/registry/registry_example.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Recipe Registry Example
+
+This example demonstrates how to:
+1. Create and publish recipes to a local registry
+2. Search and list recipes
+3. Pull recipes from the registry
+
+Prerequisites:
+- pip install praisonai
+
+Usage:
+    python registry_example.py
+"""
+
+import json
+import tarfile
+import tempfile
+from pathlib import Path
+
+
+def create_sample_recipe(tmp_dir: Path) -> Path:
+    """Create a sample recipe for demonstration."""
+    recipe_dir = tmp_dir / "hello-world"
+    recipe_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create TEMPLATE.yaml
+    template_content = """
+name: hello-world
+version: "1.0.0"
+description: A simple hello world recipe
+author: example
+tags:
+  - demo
+  - hello
+  - example
+
+requires:
+  env:
+    - OPENAI_API_KEY
+
+config:
+  input:
+    name:
+      type: string
+      required: true
+      description: Name to greet
+"""
+    
+    with open(recipe_dir / "TEMPLATE.yaml", "w") as f:
+        f.write(template_content.strip())
+    
+    # Create main.py
+    main_content = """
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    print(greet("World"))
+"""
+    
+    with open(recipe_dir / "main.py", "w") as f:
+        f.write(main_content.strip())
+    
+    return recipe_dir
+
+
+def pack_recipe(recipe_dir: Path, output_path: Path) -> Path:
+    """Pack a recipe into a .praison bundle."""
+    import hashlib
+    import io
+    from datetime import datetime, timezone
+    
+    with tarfile.open(output_path, "w:gz") as tar:
+        manifest = {
+            "name": "hello-world",
+            "version": "1.0.0",
+            "description": "A simple hello world recipe",
+            "tags": ["demo", "hello", "example"],
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "files": [],
+        }
+        
+        for file_path in recipe_dir.rglob("*"):
+            if file_path.is_file() and not file_path.name.startswith("."):
+                rel_path = file_path.relative_to(recipe_dir)
+                tar.add(file_path, arcname=str(rel_path))
+                
+                with open(file_path, "rb") as f:
+                    checksum = hashlib.sha256(f.read()).hexdigest()
+                manifest["files"].append({
+                    "path": str(rel_path),
+                    "checksum": checksum,
+                })
+        
+        manifest_bytes = json.dumps(manifest, indent=2).encode()
+        manifest_info = tarfile.TarInfo(name="manifest.json")
+        manifest_info.size = len(manifest_bytes)
+        tar.addfile(manifest_info, io.BytesIO(manifest_bytes))
+    
+    return output_path
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Recipe Registry Example")
+    print("=" * 60)
+    
+    # Use a temporary directory for the example
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        
+        # Create registry in temp directory
+        registry_path = tmp_path / "registry"
+        
+        print("\n1. Creating local registry...")
+        from praisonai.recipe.registry import LocalRegistry
+        registry = LocalRegistry(registry_path)
+        print(f"   Registry created at: {registry_path}")
+        
+        # Create and pack a sample recipe
+        print("\n2. Creating sample recipe...")
+        recipe_dir = create_sample_recipe(tmp_path)
+        print(f"   Recipe created at: {recipe_dir}")
+        
+        print("\n3. Packing recipe into bundle...")
+        bundle_path = tmp_path / "hello-world-1.0.0.praison"
+        pack_recipe(recipe_dir, bundle_path)
+        print(f"   Bundle created: {bundle_path}")
+        
+        # Publish to registry
+        print("\n4. Publishing to registry...")
+        result = registry.publish(bundle_path)
+        print(f"   Published: {result['name']}@{result['version']}")
+        print(f"   Checksum: {result['checksum'][:16]}...")
+        
+        # List recipes
+        print("\n5. Listing recipes in registry...")
+        recipes = registry.list_recipes()
+        for r in recipes:
+            print(f"   - {r['name']} ({r['version']}): {r['description']}")
+        
+        # Search recipes
+        print("\n6. Searching for 'hello'...")
+        results = registry.search("hello")
+        print(f"   Found {len(results)} recipe(s)")
+        
+        # Get versions
+        print("\n7. Getting versions of 'hello-world'...")
+        versions = registry.get_versions("hello-world")
+        print(f"   Versions: {versions}")
+        
+        # Pull recipe
+        print("\n8. Pulling recipe from registry...")
+        output_dir = tmp_path / "pulled"
+        pull_result = registry.pull("hello-world", output_dir=output_dir)
+        print(f"   Pulled to: {pull_result['path']}")
+        
+        # Verify pulled files
+        print("\n9. Verifying pulled files...")
+        pulled_recipe = output_dir / "hello-world"
+        for f in pulled_recipe.iterdir():
+            print(f"   - {f.name}")
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/run_history/README.md

@@ -0,0 +1,43 @@
+# Run History Example
+
+This example demonstrates how to use PraisonAI run history for storing, querying, and exporting recipe runs.
+
+## Features Demonstrated
+
+- Storing run results with input/output data
+- Listing and filtering runs
+- Querying run details
+- Exporting runs for replay/debugging
+- Storage statistics and cleanup
+
+## Quick Start
+
+```bash
+python run_history_example.py
+```
+
+## CLI Commands
+
+```bash
+# List recent runs
+praisonai recipe runs list
+
+# List runs for a specific recipe
+praisonai recipe runs list --recipe support-reply
+
+# Get storage stats
+praisonai recipe runs stats
+
+# Export a run
+praisonai recipe export run-abc123 -o export.json
+
+# Replay a run
+praisonai recipe replay export.json --compare
+
+# Cleanup old runs
+praisonai recipe runs cleanup
+```
+
+## Default Storage Location
+
+Run history is stored at `~/.praison/runs`.

examples/run_history/run_history_example.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Run History Example
+
+This example demonstrates how to:
+1. Store recipe run results in history
+2. List and query run history
+3. Export runs for replay/debugging
+
+Prerequisites:
+- pip install praisonai
+
+Usage:
+    python run_history_example.py
+"""
+
+import tempfile
+from pathlib import Path
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Run History Example")
+    print("=" * 60)
+    
+    # Use a temporary directory for the example
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        
+        # Create history storage in temp directory
+        history_path = tmp_path / "runs"
+        
+        print("\n1. Creating run history storage...")
+        from praisonai.recipe.history import RunHistory
+        from praisonai.recipe.models import RecipeResult, RecipeStatus
+        
+        history = RunHistory(history_path)
+        print(f"   Storage created at: {history_path}")
+        
+        # Create sample run results
+        print("\n2. Storing sample run results...")
+        
+        # Run 1: Successful run
+        result1 = RecipeResult(
+            run_id="run-abc123",
+            recipe="support-reply",
+            version="1.0.0",
+            status=RecipeStatus.SUCCESS,
+            output={"reply": "Thank you for contacting us..."},
+            metrics={"duration_sec": 2.5, "tokens": 150},
+            trace={"session_id": "session-001", "trace_id": "trace-xyz"},
+        )
+        
+        history.store(
+            result=result1,
+            input_data={"ticket_id": "T-123", "message": "I need help"},
+        )
+        print(f"   Stored: {result1.run_id} (success)")
+        
+        # Run 2: Failed run
+        result2 = RecipeResult(
+            run_id="run-def456",
+            recipe="code-review",
+            version="2.0.0",
+            status=RecipeStatus.FAILED,
+            error="Timeout exceeded",
+            metrics={"duration_sec": 30.0},
+            trace={"session_id": "session-002"},
+        )
+        
+        history.store(
+            result=result2,
+            input_data={"code": "def hello(): pass"},
+        )
+        print(f"   Stored: {result2.run_id} (failed)")
+        
+        # Run 3: Another successful run
+        result3 = RecipeResult(
+            run_id="run-ghi789",
+            recipe="support-reply",
+            version="1.0.0",
+            status=RecipeStatus.SUCCESS,
+            output={"reply": "Your issue has been resolved..."},
+            metrics={"duration_sec": 1.8},
+            trace={"session_id": "session-001"},
+        )
+        
+        history.store(
+            result=result3,
+            input_data={"ticket_id": "T-456"},
+        )
+        print(f"   Stored: {result3.run_id} (success)")
+        
+        # List all runs
+        print("\n3. Listing all runs...")
+        runs = history.list_runs()
+        for run in runs:
+            status_icon = "✓" if run["status"] == "success" else "✗"
+            print(f"   {status_icon} {run['run_id']} - {run['recipe']} ({run['status']})")
+        
+        # Filter by recipe
+        print("\n4. Filtering runs by recipe 'support-reply'...")
+        filtered = history.list_runs(recipe="support-reply")
+        print(f"   Found {len(filtered)} run(s)")
+        
+        # Filter by session
+        print("\n5. Filtering runs by session 'session-001'...")
+        filtered = history.list_runs(session_id="session-001")
+        print(f"   Found {len(filtered)} run(s)")
+        
+        # Get specific run details
+        print("\n6. Getting details for run-abc123...")
+        run_data = history.get("run-abc123")
+        print(f"   Recipe: {run_data['recipe']}")
+        print(f"   Status: {run_data['status']}")
+        print(f"   Input: {run_data.get('input', {})}")
+        print(f"   Output: {run_data.get('output', {})}")
+        
+        # Export a run
+        print("\n7. Exporting run-abc123...")
+        export_path = history.export("run-abc123", tmp_path / "export.json")
+        print(f"   Exported to: {export_path}")
+        
+        # Show export contents
+        import json
+        with open(export_path) as f:
+            export_data = json.load(f)
+        print(f"   Format: {export_data['format']}")
+        print(f"   Exported at: {export_data['exported_at']}")
+        
+        # Get storage stats
+        print("\n8. Getting storage statistics...")
+        stats = history.get_stats()
+        print(f"   Total runs: {stats['total_runs']}")
+        print(f"   Storage size: {stats['total_size_bytes']} bytes")
+        
+        # Cleanup old runs
+        print("\n9. Running cleanup...")
+        deleted = history.cleanup(retention_days=0)  # Delete all for demo
+        print(f"   Deleted {deleted} run(s)")
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/security/README.md

@@ -0,0 +1,60 @@
+# Security Features Example
+
+This example demonstrates PraisonAI security features including SBOM generation, lockfile validation, dependency auditing, and PII redaction.
+
+## Features Demonstrated
+
+- **SBOM Generation**: Generate Software Bill of Materials in CycloneDX or SPDX format
+- **Lockfile Validation**: Validate presence and format of dependency lockfiles
+- **Dependency Auditing**: Audit dependencies for vulnerabilities
+- **PII Redaction**: Detect and redact personally identifiable information
+
+## Quick Start
+
+```bash
+python security_example.py
+```
+
+## CLI Commands
+
+### SBOM Generation
+
+```bash
+# Generate CycloneDX SBOM
+praisonai recipe sbom ./my-recipe --format cyclonedx -o sbom.json
+
+# Generate SPDX SBOM
+praisonai recipe sbom ./my-recipe --format spdx -o sbom.json
+```
+
+### Dependency Auditing
+
+```bash
+# Audit dependencies
+praisonai recipe audit ./my-recipe
+
+# Strict audit (fail on issues)
+praisonai recipe audit ./my-recipe --strict
+```
+
+### Lockfile Validation
+
+```bash
+# Validate recipe (includes lockfile check)
+praisonai recipe validate ./my-recipe --require-lockfile
+```
+
+## PII Redaction Configuration
+
+In your `TEMPLATE.yaml`:
+
+```yaml
+data_policy:
+  pii:
+    mode: redact  # allow, deny, or redact
+    fields:
+      - email
+      - phone
+      - ssn
+      - credit_card
+```

examples/security/security_example.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Security Features Example
+
+This example demonstrates:
+1. SBOM (Software Bill of Materials) generation
+2. Lockfile validation
+3. Dependency auditing
+4. PII redaction
+
+Prerequisites:
+- pip install praisonai
+
+Usage:
+    python security_example.py
+"""
+
+import json
+import tempfile
+from pathlib import Path
+
+
+def create_sample_recipe(tmp_dir: Path) -> Path:
+    """Create a sample recipe with dependencies."""
+    recipe_dir = tmp_dir / "secure-recipe"
+    recipe_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create TEMPLATE.yaml
+    import yaml
+    template = {
+        "name": "secure-recipe",
+        "version": "1.0.0",
+        "description": "A recipe with security features",
+        "requires": {
+            "tools": ["web_search", "file_reader"],
+            "external": ["ffmpeg"],
+            "env": ["OPENAI_API_KEY"],
+        },
+    }
+    
+    with open(recipe_dir / "TEMPLATE.yaml", "w") as f:
+        yaml.dump(template, f)
+    
+    # Create lock directory with requirements
+    lock_dir = recipe_dir / "lock"
+    lock_dir.mkdir()
+    
+    with open(lock_dir / "requirements.lock", "w") as f:
+        f.write("openai==1.0.0\n")
+        f.write("requests==2.31.0\n")
+        f.write("pydantic==2.0.0\n")
+    
+    return recipe_dir
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Security Features Example")
+    print("=" * 60)
+    
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        
+        # Create sample recipe
+        print("\n1. Creating sample recipe with dependencies...")
+        recipe_dir = create_sample_recipe(tmp_path)
+        print(f"   Recipe created at: {recipe_dir}")
+        
+        # =====================================================
+        # SBOM Generation
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("SBOM Generation")
+        print("=" * 40)
+        
+        from praisonai.recipe.security import generate_sbom
+        
+        print("\n2. Generating CycloneDX SBOM...")
+        sbom = generate_sbom(recipe_dir, format="cyclonedx")
+        print(f"   Format: {sbom['bomFormat']}")
+        print(f"   Spec Version: {sbom['specVersion']}")
+        print(f"   Components: {len(sbom['components'])}")
+        
+        print("\n   Components:")
+        for comp in sbom["components"][:5]:
+            print(f"     - {comp['name']}@{comp['version']} ({comp['type']})")
+        
+        # Save SBOM
+        sbom_path = tmp_path / "sbom.json"
+        with open(sbom_path, "w") as f:
+            json.dump(sbom, f, indent=2)
+        print(f"\n   SBOM saved to: {sbom_path}")
+        
+        # =====================================================
+        # Lockfile Validation
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Lockfile Validation")
+        print("=" * 40)
+        
+        from praisonai.recipe.security import validate_lockfile
+        
+        print("\n3. Validating lockfile...")
+        result = validate_lockfile(recipe_dir)
+        print(f"   Valid: {result['valid']}")
+        print(f"   Lockfile: {result['lockfile']}")
+        print(f"   Type: {result['lockfile_type']}")
+        
+        # Test strict validation without lockfile
+        print("\n4. Testing strict validation on recipe without lockfile...")
+        no_lock_dir = tmp_path / "no-lock-recipe"
+        no_lock_dir.mkdir()
+        
+        result = validate_lockfile(no_lock_dir, strict=True)
+        print(f"   Valid: {result['valid']}")
+        print(f"   Errors: {result['errors']}")
+        
+        # =====================================================
+        # Dependency Auditing
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("Dependency Auditing")
+        print("=" * 40)
+        
+        from praisonai.recipe.security import audit_dependencies
+        
+        print("\n5. Auditing dependencies...")
+        report = audit_dependencies(recipe_dir)
+        print(f"   Recipe: {report['recipe']}")
+        print(f"   Lockfile: {report['lockfile']}")
+        print(f"   Dependencies: {len(report['dependencies'])}")
+        print(f"   Vulnerabilities: {len(report['vulnerabilities'])}")
+        print(f"   Warnings: {len(report['warnings'])}")
+        print(f"   Passed: {report['passed']}")
+        
+        if report["warnings"]:
+            print("\n   Warnings:")
+            for warn in report["warnings"]:
+                print(f"     - {warn}")
+        
+        # =====================================================
+        # PII Redaction
+        # =====================================================
+        print("\n" + "=" * 40)
+        print("PII Redaction")
+        print("=" * 40)
+        
+        from praisonai.recipe.security import redact_pii, detect_pii
+        
+        # Sample data with PII
+        sample_data = {
+            "customer": {
+                "name": "John Doe",
+                "email": "[email protected]",
+                "phone": "555-123-4567",
+                "message": "Please contact me at [email protected]",
+            },
+            "ticket_id": "T-12345",
+        }
+        
+        print("\n6. Detecting PII in sample data...")
+        detections = detect_pii(sample_data)
+        print(f"   Found {len(detections)} PII instance(s):")
+        for d in detections:
+            print(f"     - {d['type']} at {d['path']}")
+        
+        print("\n7. Redacting PII...")
+        policy = {
+            "pii": {
+                "mode": "redact",
+                "fields": ["email", "phone"],
+            }
+        }
+        
+        redacted = redact_pii(sample_data, policy)
+        print("   Original email:", sample_data["customer"]["email"])
+        print("   Redacted email:", redacted["customer"]["email"])
+        print("   Original phone:", sample_data["customer"]["phone"])
+        print("   Redacted phone:", redacted["customer"]["phone"])
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/README.md

@@ -0,0 +1,142 @@
+# PraisonAI Serve Examples
+
+Examples for all PraisonAI server types and the unified endpoints CLI.
+
+## Examples
+
+| Example | Description | CLI Command |
+|---------|-------------|-------------|
+| `unified_server.py` | All providers in one server | `praisonai serve unified` |
+| `agent_as_api_single.py` | Single agent HTTP API | `praisonai serve agents` |
+| `agents_as_api_router.py` | Multi-agent router API | `praisonai serve agents` |
+| `a2a_server_client.py` | A2A protocol server | `praisonai serve a2a` |
+| `a2u_events_stream.py` | A2U event stream | `praisonai serve a2u` |
+| `mcp_http_server.py` | MCP HTTP server | `praisonai serve mcp` |
+| `tools_as_mcp_server.py` | Tools as MCP server | `praisonai serve tools` |
+| `agent_launch_modes.py` | Agent.launch() API | Python only |
+| `endpoints_unified_client.py` | Unified client | `praisonai endpoints` |
+| `serve_example.py` | Recipe server client | `praisonai recipe serve` |
+
+## Server Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai serve unified --port 8765` | Start unified server |
+| `praisonai serve agents --file agents.yaml --port 8000` | Start agents API |
+| `praisonai serve recipe --port 8765` | Start recipe server |
+| `praisonai serve mcp --transport http --port 8080` | Start MCP server |
+| `praisonai serve tools --port 8081` | Start tools MCP server |
+| `praisonai serve a2a --port 8082` | Start A2A server |
+| `praisonai serve a2u --port 8083` | Start A2U server |
+
+## Client Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai endpoints list` | List all endpoints |
+| `praisonai endpoints list --type agents-api` | Filter by type |
+| `praisonai endpoints describe <name>` | Get endpoint details |
+| `praisonai endpoints invoke <name> --input-json '{}'` | Invoke endpoint |
+| `praisonai endpoints health` | Check server health |
+| `praisonai endpoints types` | List provider types |
+| `praisonai endpoints discovery` | Show discovery document |
+
+## Quick Start
+
+```bash
+# Terminal 1: Start unified server
+export OPENAI_API_KEY=your-key
+praisonai serve unified --port 8765
+
+# Terminal 2: Use endpoints CLI
+praisonai endpoints health
+praisonai endpoints list
+praisonai endpoints types
+```
+
+## Provider Types
+
+| Type | Description |
+|------|-------------|
+| `recipe` | Recipe runner endpoints |
+| `agents-api` | Single/multi-agent HTTP API |
+| `mcp` | MCP server (stdio, http, sse) |
+| `tools-mcp` | Tools exposed as MCP server |
+| `a2a` | Agent-to-agent protocol |
+| `a2u` | Agent-to-user event stream |
+
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `host` | Server bind address | 127.0.0.1 |
+| `port` | Server port | 8765 |
+| `auth` | Auth type (none, api-key, jwt) | none |
+| `api_key` | API key for auth | - |
+| `preload` | Preload recipes on startup | false |
+| `recipes` | List of recipes to serve | all |
+| `cors_origins` | CORS allowed origins | - |
+
+## Advanced Features
+
+| Feature | CLI Flag | Description | Docs |
+|---------|----------|-------------|------|
+| Rate Limiting | `--rate_limit 100` | Requests per minute per client | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| Request Size Limit | `--max_request_size 10485760` | Max request body (bytes) | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| Metrics Endpoint | `--enable_metrics` | Prometheus /metrics endpoint | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| Admin Reload | `--enable_admin` | Hot reload /admin/reload | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| Workers | `--workers 4` | Multi-process workers | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| OpenTelemetry | `--trace_exporter otlp` | Distributed tracing | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+| OpenAPI | `GET /openapi.json` | API specification | [Code](/docs/features/recipe-serve-advanced) [CLI](/docs/cli/recipe-serve-advanced) |
+
+## Advanced Examples
+
+| Example | Description |
+|---------|-------------|
+| `recipe_serve_features.py` | All advanced features demo |
+
+## Advanced CLI Commands
+
+```bash
+# Production server with all features
+praisonai recipe serve \
+  --host 0.0.0.0 \
+  --port 8765 \
+  --auth api-key \
+  --workers 4 \
+  --rate_limit 100 \
+  --enable_metrics \
+  --enable_admin
+
+# Get metrics
+curl http://localhost:8765/metrics
+
+# Get OpenAPI spec
+curl http://localhost:8765/openapi.json
+
+# Hot reload recipes
+curl -X POST http://localhost:8765/admin/reload \
+  -H "X-API-Key: your-key"
+```
+
+## CLI Commands
+
+```bash
+# Health check
+praisonai endpoints health
+
+# List recipes (with auth)
+praisonai endpoints list --api-key your-key
+
+# Invoke recipe
+praisonai endpoints invoke my-recipe \
+  --input-json '{"query": "Hello"}' \
+  --api-key your-key \
+  --json
+```
+
+## Security Notes
+
+- Always use `--auth api-key` when binding to `0.0.0.0`
+- Store API keys in environment variables, not config files
+- Use HTTPS in production (via reverse proxy)

examples/serve/a2a_server_client.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+A2A (Agent-to-Agent) Server and Client Example
+
+Demonstrates:
+- Launching an agent as A2A server
+- Agent card discovery
+- Sending A2A messages
+- JSON-RPC protocol
+
+Usage:
+    # Run this example (starts server)
+    python a2a_server_client.py
+    
+    # Or use CLI:
+    praisonai serve a2a --port 8082
+    
+    # Test with curl:
+    curl http://localhost:8082/.well-known/agent.json
+    curl -X POST http://localhost:8082/a2a \
+      -H "Content-Type: application/json" \
+      -d '{"jsonrpc":"2.0","method":"message/send","id":"1","params":{"message":{"role":"user","parts":[{"type":"text","text":"Hello!"}]}}}'
+"""
+
+import os
+import sys
+import json
+import threading
+import time
+
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def run_server():
+    """Run A2A server."""
+    try:
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        from fastapi import FastAPI
+        import uvicorn
+    except ImportError as e:
+        print(f"Error: Missing dependency - {e}")
+        print("Install with: pip install 'praisonaiagents[api]'")
+        sys.exit(1)
+    
+    # Create agent
+    agent = Agent(
+        name="A2A-Assistant",
+        role="Helpful AI Assistant",
+        goal="Help other agents and users with their questions",
+        backstory="You are a knowledgeable assistant accessible via A2A protocol.",
+        llm="gpt-4o-mini"
+    )
+    
+    # Create A2A interface
+    a2a = A2A(
+        agent=agent,
+        url="http://localhost:8082/a2a",
+        name="A2A-Assistant",
+        description="A helpful AI assistant accessible via A2A protocol"
+    )
+    
+    # Create FastAPI app
+    app = FastAPI(title="PraisonAI A2A Server")
+    app.include_router(a2a.get_router())
+    
+    # Add discovery endpoint
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-a2a",
+            "providers": [{"type": "a2a", "name": "A2A Protocol", "capabilities": ["agent-card", "message-send"]}],
+            "endpoints": [{"name": "a2a", "provider_type": "a2a", "streaming": ["sse"]}]
+        }
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI A2A Server",
+            "agent_card": "/.well-known/agent.json",
+            "a2a_endpoint": "/a2a",
+            "discovery": "/__praisonai__/discovery"
+        }
+    
+    print("Starting A2A server on http://localhost:8082")
+    print("Agent Card: http://localhost:8082/.well-known/agent.json")
+    print("A2A Endpoint: http://localhost:8082/a2a")
+    
+    uvicorn.run(app, host="127.0.0.1", port=8082, log_level="warning")
+
+
+def run_client():
+    """Run A2A client test."""
+    import urllib.request
+    import urllib.error
+    
+    base_url = "http://localhost:8082"
+    
+    print("\n--- A2A Client Test ---")
+    
+    # 1. Get agent card
+    print("\n1. Getting Agent Card...")
+    try:
+        req = urllib.request.Request(f"{base_url}/.well-known/agent.json")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            agent_card = json.loads(resp.read().decode())
+            print(f"   Agent: {agent_card.get('name')}")
+            print(f"   URL: {agent_card.get('url')}")
+            print(f"   Capabilities: {agent_card.get('capabilities', {})}")
+    except Exception as e:
+        print(f"   Error: {e}")
+        return
+    
+    # 2. Send A2A message
+    print("\n2. Sending A2A Message...")
+    message = {
+        "jsonrpc": "2.0",
+        "method": "message/send",
+        "id": "test-1",
+        "params": {
+            "message": {
+                "role": "user",
+                "parts": [{"type": "text", "text": "Hello! What can you help me with?"}]
+            }
+        }
+    }
+    
+    try:
+        req = urllib.request.Request(
+            f"{base_url}/a2a",
+            data=json.dumps(message).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST"
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            response = json.loads(resp.read().decode())
+            if "result" in response:
+                result_msg = response["result"].get("message", {})
+                parts = result_msg.get("parts", [])
+                for part in parts:
+                    if part.get("type") == "text":
+                        print(f"   Response: {part.get('text', '')[:200]}...")
+            elif "error" in response:
+                print(f"   Error: {response['error']}")
+    except Exception as e:
+        print(f"   Error: {e}")
+    
+    # 3. Check discovery
+    print("\n3. Checking Discovery...")
+    try:
+        req = urllib.request.Request(f"{base_url}/__praisonai__/discovery")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            discovery = json.loads(resp.read().decode())
+            print(f"   Server: {discovery.get('server_name')}")
+            print(f"   Providers: {[p.get('type') for p in discovery.get('providers', [])]}")
+    except Exception as e:
+        print(f"   Error: {e}")
+    
+    print("\n✓ A2A client test completed!")
+
+
+def main():
+    print("=" * 60)
+    print("A2A (Agent-to-Agent) Server and Client Example")
+    print("=" * 60)
+    
+    mode = sys.argv[1] if len(sys.argv) > 1 else "server"
+    
+    if mode == "client":
+        run_client()
+    elif mode == "test":
+        # Start server in background, run client, then stop
+        print("Starting server in background...")
+        server_thread = threading.Thread(target=run_server, daemon=True)
+        server_thread.start()
+        time.sleep(3)  # Wait for server to start
+        run_client()
+    else:
+        print("\nStarting A2A server...")
+        print("Press Ctrl+C to stop")
+        print("\nTo test, run in another terminal:")
+        print("  python a2a_server_client.py client")
+        run_server()
+
+
+if __name__ == "__main__":
+    main()

examples/serve/a2u_events_stream.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+A2U (Agent-to-User) Event Stream Example
+
+Demonstrates:
+- Launching an A2U event stream server
+- Subscribing to agent events
+- SSE (Server-Sent Events) streaming
+- Event filtering
+
+Usage:
+    # Run this example (starts server)
+    python a2u_events_stream.py
+    
+    # Or use CLI:
+    praisonai serve a2u --port 8083
+    
+    # Test with curl:
+    curl http://localhost:8083/a2u/info
+    curl -N http://localhost:8083/a2u/events/events
+"""
+
+import os
+import sys
+import json
+import threading
+import time
+
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def run_server():
+    """Run A2U server."""
+    try:
+        from fastapi import FastAPI
+        import uvicorn
+        from praisonai.endpoints.a2u_server import (
+            create_a2u_routes,
+            emit_agent_started,
+            emit_agent_thinking,
+            emit_agent_response,
+            emit_agent_completed,
+        )
+    except ImportError as e:
+        print(f"Error: Missing dependency - {e}")
+        print("Install with: pip install praisonai[serve]")
+        sys.exit(1)
+    
+    app = FastAPI(title="PraisonAI A2U Server")
+    
+    # Add A2U routes
+    create_a2u_routes(app)
+    
+    # Add discovery endpoint
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-a2u",
+            "providers": [{"type": "a2u", "name": "A2U Event Stream", "capabilities": ["subscribe", "stream"]}],
+            "endpoints": [{"name": "events", "provider_type": "a2u", "streaming": ["sse"]}]
+        }
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI A2U Server",
+            "info": "/a2u/info",
+            "events": "/a2u/events/<stream>",
+            "discovery": "/__praisonai__/discovery"
+        }
+    
+    # Demo endpoint to emit events
+    @app.post("/demo/emit")
+    async def demo_emit():
+        """Emit demo events for testing."""
+        agent_id = "demo-agent-1"
+        emit_agent_started(agent_id, "DemoAgent")
+        emit_agent_thinking(agent_id, "Processing your request...")
+        emit_agent_response(agent_id, "Here is my response to your query.")
+        emit_agent_completed(agent_id, {"status": "success"})
+        return {"message": "Demo events emitted", "agent_id": agent_id}
+    
+    print("Starting A2U server on http://localhost:8083")
+    print("Info: http://localhost:8083/a2u/info")
+    print("Events: http://localhost:8083/a2u/events/events")
+    print("Demo: POST http://localhost:8083/demo/emit")
+    
+    uvicorn.run(app, host="127.0.0.1", port=8083, log_level="warning")
+
+
+def run_client():
+    """Run A2U client test."""
+    import urllib.request
+    import urllib.error
+    
+    base_url = "http://localhost:8083"
+    
+    print("\n--- A2U Client Test ---")
+    
+    # 1. Get A2U info
+    print("\n1. Getting A2U Info...")
+    try:
+        req = urllib.request.Request(f"{base_url}/a2u/info")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            info = json.loads(resp.read().decode())
+            print(f"   Name: {info.get('name')}")
+            print(f"   Version: {info.get('version')}")
+            print(f"   Streams: {info.get('streams')}")
+            print(f"   Event Types: {info.get('event_types')}")
+    except Exception as e:
+        print(f"   Error: {e}")
+        return
+    
+    # 2. Subscribe to events
+    print("\n2. Subscribing to Events...")
+    try:
+        req = urllib.request.Request(
+            f"{base_url}/a2u/subscribe",
+            data=json.dumps({"stream": "events", "filters": []}).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST"
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            sub = json.loads(resp.read().decode())
+            print(f"   Subscription ID: {sub.get('subscription_id')}")
+            print(f"   Stream URL: {sub.get('stream_url')}")
+    except Exception as e:
+        print(f"   Error: {e}")
+    
+    # 3. Emit demo events
+    print("\n3. Emitting Demo Events...")
+    try:
+        req = urllib.request.Request(
+            f"{base_url}/demo/emit",
+            data=b"{}",
+            headers={"Content-Type": "application/json"},
+            method="POST"
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            result = json.loads(resp.read().decode())
+            print(f"   {result.get('message')}")
+            print(f"   Agent ID: {result.get('agent_id')}")
+    except Exception as e:
+        print(f"   Error: {e}")
+    
+    # 4. Check discovery
+    print("\n4. Checking Discovery...")
+    try:
+        req = urllib.request.Request(f"{base_url}/__praisonai__/discovery")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            discovery = json.loads(resp.read().decode())
+            print(f"   Server: {discovery.get('server_name')}")
+            print(f"   Providers: {[p.get('type') for p in discovery.get('providers', [])]}")
+    except Exception as e:
+        print(f"   Error: {e}")
+    
+    print("\n✓ A2U client test completed!")
+    print("\nTo stream events, run:")
+    print(f"  curl -N {base_url}/a2u/events/events")
+
+
+def main():
+    print("=" * 60)
+    print("A2U (Agent-to-User) Event Stream Example")
+    print("=" * 60)
+    
+    mode = sys.argv[1] if len(sys.argv) > 1 else "server"
+    
+    if mode == "client":
+        run_client()
+    elif mode == "test":
+        print("Starting server in background...")
+        server_thread = threading.Thread(target=run_server, daemon=True)
+        server_thread.start()
+        time.sleep(2)
+        run_client()
+    else:
+        print("\nStarting A2U server...")
+        print("Press Ctrl+C to stop")
+        print("\nTo test, run in another terminal:")
+        print("  python a2u_events_stream.py client")
+        run_server()
+
+
+if __name__ == "__main__":
+    main()

examples/serve/agent_as_api_single.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Single Agent as HTTP API Example
+
+Demonstrates launching a single agent as an HTTP API server with:
+- REST endpoint for queries
+- Streaming support (SSE)
+- Discovery endpoint
+- Health check
+
+Usage:
+    # Run this example
+    python agent_as_api_single.py
+    
+    # Or use CLI:
+    praisonai serve agents --file agents.yaml --port 8000
+    
+    # Test with curl:
+    curl -X POST http://localhost:8000/agent \
+      -H "Content-Type: application/json" \
+      -d '{"query": "What is AI?"}'
+"""
+
+import os
+import sys
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def main():
+    print("=" * 60)
+    print("Single Agent as HTTP API Example")
+    print("=" * 60)
+    
+    try:
+        from praisonaiagents import Agent
+    except ImportError:
+        print("Error: praisonaiagents not installed")
+        print("Install with: pip install praisonaiagents")
+        sys.exit(1)
+    
+    # Create a single agent
+    agent = Agent(
+        name="Assistant",
+        role="Helpful AI Assistant",
+        goal="Help users with their questions accurately and concisely",
+        backstory="You are a knowledgeable assistant who provides clear, helpful answers.",
+        llm="gpt-4o-mini",
+        verbose=True
+    )
+    
+    print(f"Agent: {agent.name}")
+    print(f"Role: {agent.role}")
+    
+    # Launch as HTTP API
+    print("\nLaunching agent as HTTP API...")
+    print("Endpoints:")
+    print("  POST /agent - Query the agent")
+    print("  GET  /health - Health check")
+    print("  GET  /__praisonai__/discovery - Discovery document")
+    print("\nPress Ctrl+C to stop")
+    
+    try:
+        # Use Agent.launch() to start HTTP server
+        agent.launch(
+            port=8000,
+            host="127.0.0.1",
+            path="/agent"
+        )
+    except KeyboardInterrupt:
+        print("\nServer stopped")
+    except Exception as e:
+        print(f"Error launching server: {e}")
+        # Fallback: manual FastAPI setup
+        print("\nFallback: Using manual FastAPI setup...")
+        launch_manual(agent)
+
+
+def launch_manual(agent):
+    """Manual FastAPI server setup as fallback."""
+    try:
+        from fastapi import FastAPI, Request
+        from fastapi.responses import JSONResponse
+        import uvicorn
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        print("Install with: pip install fastapi uvicorn")
+        return
+    
+    app = FastAPI(title="PraisonAI Agent API")
+    
+    @app.post("/agent")
+    async def query_agent(request: Request):
+        try:
+            body = await request.json()
+            query = body.get("query", "")
+            if not query:
+                return JSONResponse({"error": "query required"}, status_code=400)
+            
+            response = agent.chat(query)
+            return {"response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.get("/health")
+    async def health():
+        return {"status": "healthy", "agent": agent.name}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-agent",
+            "providers": [{"type": "agents-api", "name": "Single Agent API"}],
+            "endpoints": [{"name": "agent", "provider_type": "agents-api"}]
+        }
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": f"PraisonAI Agent: {agent.name}",
+            "endpoints": ["/agent", "/health", "/__praisonai__/discovery"]
+        }
+    
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/agent_launch_modes.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Agent.launch() and Agents.launch() Example
+
+Demonstrates the high-level Python API for launching servers:
+- Agent.launch() for single agent
+- Agents.launch() for multi-agent
+- Different server modes (HTTP, MCP, A2A)
+
+Usage:
+    # Run this example
+    python agent_launch_modes.py
+    
+    # Test endpoints:
+    curl http://localhost:8000/agent
+    curl http://localhost:8000/health
+"""
+
+import os
+import sys
+
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def demo_single_agent_launch():
+    """Demo Agent.launch() for single agent."""
+    print("\n--- Single Agent Launch ---")
+    
+    try:
+        from praisonaiagents import Agent
+    except ImportError:
+        print("Error: praisonaiagents not installed")
+        return False
+    
+    agent = Agent(
+        name="Assistant",
+        role="Helpful AI Assistant",
+        goal="Help users with their questions",
+        llm="gpt-4o-mini"
+    )
+    
+    print(f"Agent: {agent.name}")
+    print("Launching as HTTP API on port 8000...")
+    print("\nEndpoints:")
+    print("  POST /agent - Query the agent")
+    print("  GET  /health - Health check")
+    print("\nPress Ctrl+C to stop")
+    
+    try:
+        agent.launch(port=8000, host="127.0.0.1", path="/agent")
+    except AttributeError:
+        print("Agent.launch() not available, using fallback...")
+        launch_single_fallback(agent)
+    except KeyboardInterrupt:
+        print("\nStopped")
+    
+    return True
+
+
+def demo_multi_agent_launch():
+    """Demo Agents.launch() for multi-agent."""
+    print("\n--- Multi-Agent Launch ---")
+    
+    try:
+        from praisonaiagents import Agent, PraisonAIAgents
+    except ImportError:
+        print("Error: praisonaiagents not installed")
+        return False
+    
+    researcher = Agent(
+        name="Researcher",
+        role="Research Specialist",
+        goal="Find accurate information",
+        llm="gpt-4o-mini"
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Content Writer",
+        goal="Create engaging content",
+        llm="gpt-4o-mini"
+    )
+    
+    agents = PraisonAIAgents(agents=[researcher, writer])
+    
+    print(f"Agents: {[researcher.name, writer.name]}")
+    print("Launching as HTTP API on port 8000...")
+    print("\nEndpoints:")
+    print("  POST /agents - Route to best agent")
+    print("  POST /agents/researcher - Query researcher")
+    print("  POST /agents/writer - Query writer")
+    print("  GET  /agents/list - List agents")
+    print("\nPress Ctrl+C to stop")
+    
+    try:
+        agents.launch(port=8000, host="127.0.0.1")
+    except AttributeError:
+        print("Agents.launch() not available, using fallback...")
+        launch_multi_fallback([researcher, writer])
+    except KeyboardInterrupt:
+        print("\nStopped")
+    
+    return True
+
+
+def launch_single_fallback(agent):
+    """Fallback implementation for Agent.launch()."""
+    try:
+        from fastapi import FastAPI, Request
+        from fastapi.responses import JSONResponse
+        import uvicorn
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        return
+    
+    app = FastAPI(title=f"PraisonAI Agent: {agent.name}")
+    
+    @app.post("/agent")
+    async def query(request: Request):
+        try:
+            body = await request.json()
+            query_text = body.get("query", "")
+            response = agent.chat(query_text)
+            return {"response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.get("/health")
+    async def health():
+        return {"status": "healthy", "agent": agent.name}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": f"praisonai-{agent.name.lower()}",
+            "providers": [{"type": "agents-api", "name": "Single Agent API"}],
+            "endpoints": [{"name": "agent", "provider_type": "agents-api"}]
+        }
+    
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+
+
+def launch_multi_fallback(agents):
+    """Fallback implementation for Agents.launch()."""
+    try:
+        from fastapi import FastAPI, Request
+        from fastapi.responses import JSONResponse
+        import uvicorn
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        return
+    
+    app = FastAPI(title="PraisonAI Multi-Agent API")
+    agent_map = {a.name.lower(): a for a in agents}
+    
+    @app.post("/agents")
+    async def route(request: Request):
+        try:
+            body = await request.json()
+            query_text = body.get("query", "")
+            # Simple routing
+            agent = agents[0]
+            response = agent.chat(query_text)
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.post("/agents/{name}")
+    async def query_agent(name: str, request: Request):
+        agent = agent_map.get(name.lower())
+        if not agent:
+            return JSONResponse({"error": f"Agent not found: {name}"}, status_code=404)
+        try:
+            body = await request.json()
+            response = agent.chat(body.get("query", ""))
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.get("/agents/list")
+    async def list_agents():
+        return {"agents": [{"name": a.name, "role": a.role} for a in agents]}
+    
+    @app.get("/health")
+    async def health():
+        return {"status": "healthy", "agents": len(agents)}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-agents",
+            "providers": [{"type": "agents-api", "name": "Multi-Agent API"}],
+            "endpoints": [
+                {"name": "agents", "provider_type": "agents-api"},
+                *[{"name": f"agents/{a.name.lower()}", "provider_type": "agents-api"} for a in agents]
+            ]
+        }
+    
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+
+
+def main():
+    print("=" * 60)
+    print("Agent.launch() and Agents.launch() Example")
+    print("=" * 60)
+    
+    mode = sys.argv[1] if len(sys.argv) > 1 else "single"
+    
+    if mode == "multi":
+        demo_multi_agent_launch()
+    else:
+        demo_single_agent_launch()
+
+
+if __name__ == "__main__":
+    main()

examples/serve/agents_as_api_router.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Router as HTTP API Example
+
+Demonstrates launching multiple agents as an HTTP API with:
+- Router endpoint for automatic agent selection
+- Per-agent endpoints
+- Streaming support (SSE)
+- Discovery endpoint
+
+Usage:
+    # Run this example
+    python agents_as_api_router.py
+    
+    # Or use CLI:
+    praisonai serve agents --file agents.yaml --port 8000
+    
+    # Test with curl:
+    curl -X POST http://localhost:8000/agents \
+      -H "Content-Type: application/json" \
+      -d '{"query": "Research AI trends"}'
+"""
+
+import os
+import sys
+
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def main():
+    print("=" * 60)
+    print("Multi-Agent Router as HTTP API Example")
+    print("=" * 60)
+    
+    try:
+        from praisonaiagents import Agent, PraisonAIAgents
+    except ImportError:
+        print("Error: praisonaiagents not installed")
+        print("Install with: pip install praisonaiagents")
+        sys.exit(1)
+    
+    # Create multiple agents
+    researcher = Agent(
+        name="Researcher",
+        role="Research Specialist",
+        goal="Find accurate and relevant information",
+        backstory="Expert at finding and synthesizing information from various sources.",
+        llm="gpt-4o-mini"
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Content Writer",
+        goal="Create engaging content from research",
+        backstory="Skilled writer who transforms research into readable content.",
+        llm="gpt-4o-mini"
+    )
+    
+    analyst = Agent(
+        name="Analyst",
+        role="Data Analyst",
+        goal="Analyze data and provide insights",
+        backstory="Expert at analyzing data and extracting meaningful insights.",
+        llm="gpt-4o-mini"
+    )
+    
+    agents = [researcher, writer, analyst]
+    
+    print(f"Agents: {[a.name for a in agents]}")
+    
+    # Create multi-agent system
+    praison = PraisonAIAgents(agents=agents)
+    
+    print("\nLaunching multi-agent router as HTTP API...")
+    print("Endpoints:")
+    print("  POST /agents - Route to best agent")
+    print("  POST /agents/researcher - Query researcher")
+    print("  POST /agents/writer - Query writer")
+    print("  POST /agents/analyst - Query analyst")
+    print("  GET  /agents/list - List all agents")
+    print("  GET  /health - Health check")
+    print("  GET  /__praisonai__/discovery - Discovery document")
+    print("\nPress Ctrl+C to stop")
+    
+    try:
+        # Use Agents.launch() to start HTTP server
+        praison.launch(
+            port=8000,
+            host="127.0.0.1"
+        )
+    except KeyboardInterrupt:
+        print("\nServer stopped")
+    except Exception as e:
+        print(f"Error launching server: {e}")
+        print("\nFallback: Using manual FastAPI setup...")
+        launch_manual(agents)
+
+
+def launch_manual(agents):
+    """Manual FastAPI server setup as fallback."""
+    try:
+        from fastapi import FastAPI, Request
+        from fastapi.responses import JSONResponse
+        import uvicorn
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        print("Install with: pip install fastapi uvicorn")
+        return
+    
+    app = FastAPI(title="PraisonAI Multi-Agent API")
+    
+    # Create agent lookup
+    agent_map = {a.name.lower(): a for a in agents}
+    
+    @app.post("/agents")
+    async def route_query(request: Request):
+        """Route query to best agent."""
+        try:
+            body = await request.json()
+            query = body.get("query", "")
+            if not query:
+                return JSONResponse({"error": "query required"}, status_code=400)
+            
+            # Simple routing based on keywords
+            query_lower = query.lower()
+            if any(w in query_lower for w in ["research", "find", "search"]):
+                agent = agent_map.get("researcher", agents[0])
+            elif any(w in query_lower for w in ["write", "create", "draft"]):
+                agent = agent_map.get("writer", agents[0])
+            elif any(w in query_lower for w in ["analyze", "data", "insight"]):
+                agent = agent_map.get("analyst", agents[0])
+            else:
+                agent = agents[0]
+            
+            response = agent.chat(query)
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.post("/agents/{agent_name}")
+    async def query_agent(agent_name: str, request: Request):
+        """Query specific agent."""
+        agent = agent_map.get(agent_name.lower())
+        if not agent:
+            return JSONResponse({"error": f"Agent not found: {agent_name}"}, status_code=404)
+        
+        try:
+            body = await request.json()
+            query = body.get("query", "")
+            response = agent.chat(query)
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+    
+    @app.get("/agents/list")
+    async def list_agents():
+        return {"agents": [{"name": a.name, "role": a.role} for a in agents]}
+    
+    @app.get("/health")
+    async def health():
+        return {"status": "healthy", "agents": len(agents)}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-agents-router",
+            "providers": [{"type": "agents-api", "name": "Multi-Agent Router"}],
+            "endpoints": [
+                {"name": "agents", "provider_type": "agents-api"},
+                *[{"name": f"agents/{a.name.lower()}", "provider_type": "agents-api"} for a in agents]
+            ]
+        }
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI Multi-Agent Router",
+            "agents": [a.name for a in agents],
+            "endpoints": ["/agents", "/agents/list", "/health"]
+        }
+    
+    uvicorn.run(app, host="127.0.0.1", port=8000)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/endpoints_unified_client.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Unified Endpoints Client Example
+
+Demonstrates using the praisonai endpoints CLI to interact with any PraisonAI server.
+Works with recipe, agents-api, mcp, a2a, a2u, and tools-mcp servers.
+
+Usage:
+    # Start any server first (e.g., unified server)
+    praisonai serve unified --port 8765
+    
+    # Then run this example
+    python endpoints_unified_client.py
+    
+    # Or use CLI directly:
+    praisonai endpoints list
+    praisonai endpoints types
+    praisonai endpoints health
+    praisonai endpoints discovery
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def run_cli(args: list) -> tuple:
+    """Run praisonai endpoints CLI command."""
+    cmd = ["python3", "-m", "praisonai.cli.main", "endpoints"] + args
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.returncode, result.stdout, result.stderr
+
+
+def main():
+    print("=" * 60)
+    print("PraisonAI Unified Endpoints Client Example")
+    print("=" * 60)
+    
+    server_url = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+    print(f"Server URL: {server_url}")
+    
+    # 1. List provider types
+    print("\n--- Provider Types ---")
+    code, out, err = run_cli(["types", "--format", "json"])
+    if code == 0:
+        types = json.loads(out)
+        print(f"Supported types: {[t['type'] for t in types]}")
+    else:
+        print(f"Error: {err}")
+    
+    # 2. Health check
+    print("\n--- Health Check ---")
+    code, out, err = run_cli(["health", "--url", server_url])
+    if code == 0:
+        print("✓ Server is healthy")
+        print(out.strip())
+    elif code == 8:
+        print("✗ Connection error - server not running")
+        print("\nStart a server first:")
+        print("  praisonai serve unified --port 8765")
+        print("  praisonai serve agents --file agents.yaml --port 8765")
+        print("  praisonai serve a2a --port 8765")
+        return 1
+    else:
+        print(f"✗ Health check failed: {err}")
+        return 1
+    
+    # 3. Discovery document
+    print("\n--- Discovery Document ---")
+    code, out, err = run_cli(["discovery", "--url", server_url])
+    if code == 0:
+        try:
+            discovery = json.loads(out)
+            print(f"Server: {discovery.get('server_name', 'unknown')}")
+            print(f"Schema version: {discovery.get('schema_version', 'unknown')}")
+            providers = discovery.get('providers', [])
+            print(f"Providers: {[p.get('type') for p in providers]}")
+            endpoints = discovery.get('endpoints', [])
+            print(f"Endpoints: {[e.get('name') for e in endpoints]}")
+        except json.JSONDecodeError:
+            print(out.strip())
+    else:
+        print(f"Discovery not available: {err}")
+    
+    # 4. List endpoints
+    print("\n--- List Endpoints ---")
+    code, out, err = run_cli(["list", "--url", server_url, "--format", "json"])
+    if code == 0:
+        try:
+            endpoints = json.loads(out)
+            if isinstance(endpoints, list):
+                for ep in endpoints[:5]:  # Show first 5
+                    print(f"  - {ep.get('name')}: {ep.get('description', '')[:50]}")
+            else:
+                print(out.strip()[:200])
+        except json.JSONDecodeError:
+            print(out.strip()[:200])
+    else:
+        print(f"List failed: {err}")
+    
+    # 5. Filter by type
+    print("\n--- Filter by Provider Type ---")
+    for ptype in ["agents-api", "a2a", "recipe"]:
+        code, out, err = run_cli(["list", "--url", server_url, "--type", ptype])
+        if code == 0 and out.strip():
+            print(f"  {ptype}: {len(out.strip().split(chr(10)))} endpoints")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/serve/mcp_http_server.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""
+MCP HTTP Server Example
+
+Demonstrates launching an MCP server with HTTP transport:
+- HTTP-based MCP protocol
+- Tool registration
+- Discovery endpoint
+
+Usage:
+    # Run this example
+    python mcp_http_server.py
+    
+    # Or use CLI:
+    praisonai serve mcp --transport http --port 8080
+    
+    # Test with curl:
+    curl http://localhost:8080/mcp/tools
+    curl -X POST http://localhost:8080/mcp/tools/call \
+      -H "Content-Type: application/json" \
+      -d '{"tool": "search", "arguments": {"query": "AI news"}}'
+"""
+
+import sys
+
+
+def main():
+    print("=" * 60)
+    print("MCP HTTP Server Example")
+    print("=" * 60)
+    
+    try:
+        from fastapi import FastAPI
+        import uvicorn
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        print("Install with: pip install fastapi uvicorn")
+        sys.exit(1)
+    
+    # Define tools
+    def search(query: str) -> str:
+        """Search the web for information."""
+        return f"Search results for: {query}"
+    
+    def calculate(expression: str) -> str:
+        """Calculate a math expression safely."""
+        try:
+            # Safe eval for basic math
+            allowed = set("0123456789+-*/.() ")
+            if all(c in allowed for c in expression):
+                return str(eval(expression))
+            return "Error: Invalid expression"
+        except Exception as e:
+            return f"Error: {e}"
+    
+    def get_weather(city: str) -> str:
+        """Get weather for a city (mock)."""
+        return f"Weather in {city}: Sunny, 72°F"
+    
+    tools = {
+        "search": {"func": search, "description": "Search the web for information"},
+        "calculate": {"func": calculate, "description": "Calculate a math expression"},
+        "get_weather": {"func": get_weather, "description": "Get weather for a city"},
+    }
+    
+    app = FastAPI(title="PraisonAI MCP Server")
+    
+    @app.get("/mcp/tools")
+    async def list_tools():
+        """List available MCP tools."""
+        return {
+            "tools": [
+                {
+                    "name": name,
+                    "description": info["description"],
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            list(info["func"].__code__.co_varnames)[0]: {"type": "string"}
+                        },
+                        "required": [list(info["func"].__code__.co_varnames)[0]]
+                    }
+                }
+                for name, info in tools.items()
+            ]
+        }
+    
+    @app.post("/mcp/tools/call")
+    async def call_tool(request: dict):
+        """Call an MCP tool."""
+        tool_name = request.get("tool")
+        arguments = request.get("arguments", {})
+        
+        if tool_name not in tools:
+            return {"error": f"Tool not found: {tool_name}"}
+        
+        try:
+            func = tools[tool_name]["func"]
+            # Get first argument
+            arg_name = list(func.__code__.co_varnames)[0]
+            arg_value = arguments.get(arg_name, "")
+            result = func(arg_value)
+            return {"result": result, "tool": tool_name}
+        except Exception as e:
+            return {"error": str(e)}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-mcp",
+            "providers": [{"type": "mcp", "name": "MCP Server", "capabilities": ["list-tools", "call-tool"]}],
+            "endpoints": [{"name": "mcp", "provider_type": "mcp"}]
+        }
+    
+    @app.get("/health")
+    async def health():
+        return {"status": "healthy", "tools": len(tools)}
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI MCP Server (HTTP)",
+            "tools": list(tools.keys()),
+            "endpoints": ["/mcp/tools", "/mcp/tools/call", "/health"]
+        }
+    
+    print(f"Tools: {list(tools.keys())}")
+    print("\nStarting MCP HTTP server on http://localhost:8080")
+    print("List tools: GET http://localhost:8080/mcp/tools")
+    print("Call tool: POST http://localhost:8080/mcp/tools/call")
+    print("\nPress Ctrl+C to stop")
+    
+    uvicorn.run(app, host="127.0.0.1", port=8080)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/recipe_serve_features.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Recipe Server Advanced Features Example
+
+Demonstrates:
+1. Rate limiting
+2. Request size limits
+3. Metrics endpoint
+4. Admin reload endpoint
+5. OpenAPI specification
+6. Workers configuration
+7. OpenTelemetry tracing
+
+Prerequisites:
+- pip install praisonai[serve]
+- Set OPENAI_API_KEY environment variable
+
+Usage:
+    # Run this example
+    python recipe_serve_features.py
+"""
+
+import json
+import os
+import urllib.request
+import urllib.error
+
+# Configuration
+SERVER_URL = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+API_KEY = os.environ.get("PRAISONAI_API_KEY", "test-api-key")
+
+
+def make_request(method: str, path: str, data: dict = None, headers: dict = None) -> dict:
+    """Make HTTP request to server."""
+    url = f"{SERVER_URL}{path}"
+    default_headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": API_KEY,
+    }
+    if headers:
+        default_headers.update(headers)
+    
+    body = json.dumps(data).encode() if data else None
+    
+    try:
+        req = urllib.request.Request(url, data=body, headers=default_headers, method=method)
+        with urllib.request.urlopen(req, timeout=30) as response:
+            return {
+                "status": response.status,
+                "data": json.loads(response.read().decode()),
+                "headers": dict(response.headers)
+            }
+    except urllib.error.HTTPError as e:
+        body = e.read().decode() if e.fp else ""
+        try:
+            error_data = json.loads(body)
+        except json.JSONDecodeError:
+            error_data = {"raw": body}
+        return {
+            "status": e.code,
+            "error": error_data,
+            "headers": dict(e.headers) if hasattr(e, 'headers') else {}
+        }
+    except urllib.error.URLError as e:
+        return {"status": 0, "error": str(e.reason)}
+
+
+def test_health():
+    """Test health endpoint."""
+    print("\n" + "=" * 60)
+    print("TEST: Health Check")
+    print("=" * 60)
+    
+    result = make_request("GET", "/health")
+    
+    if result.get("status") == 200:
+        data = result["data"]
+        print("✓ Server healthy")
+        print(f"  Service: {data.get('service')}")
+        print(f"  Version: {data.get('version')}")
+        return True
+    else:
+        print(f"✗ Server unhealthy: {result.get('error')}")
+        return False
+
+
+def test_openapi():
+    """Test OpenAPI specification endpoint."""
+    print("\n" + "=" * 60)
+    print("TEST: OpenAPI Specification")
+    print("=" * 60)
+    
+    result = make_request("GET", "/openapi.json")
+    
+    if result.get("status") == 200:
+        spec = result["data"]
+        print("✓ OpenAPI spec available")
+        print(f"  Version: {spec.get('openapi')}")
+        print(f"  Title: {spec.get('info', {}).get('title')}")
+        print(f"  Paths: {list(spec.get('paths', {}).keys())[:5]}...")
+        return True
+    else:
+        print(f"✗ OpenAPI not available: {result.get('error')}")
+        return False
+
+
+def test_metrics():
+    """Test metrics endpoint."""
+    print("\n" + "=" * 60)
+    print("TEST: Metrics Endpoint")
+    print("=" * 60)
+    
+    result = make_request("GET", "/metrics")
+    
+    if result.get("status") == 200:
+        # Metrics returns plain text, not JSON
+        print("✓ Metrics endpoint available")
+        print("  (Prometheus format)")
+        return True
+    elif result.get("status") == 404:
+        print("⚠ Metrics endpoint not enabled")
+        print("  Enable with: --enable_metrics")
+        return True  # Not a failure, just not enabled
+    else:
+        print(f"✗ Metrics error: {result.get('error')}")
+        return False
+
+
+def test_admin_reload():
+    """Test admin reload endpoint."""
+    print("\n" + "=" * 60)
+    print("TEST: Admin Reload Endpoint")
+    print("=" * 60)
+    
+    result = make_request("POST", "/admin/reload")
+    
+    if result.get("status") == 200:
+        data = result["data"]
+        print("✓ Admin reload successful")
+        print(f"  Status: {data.get('status')}")
+        print(f"  Timestamp: {data.get('timestamp')}")
+        return True
+    elif result.get("status") == 404:
+        print("⚠ Admin endpoint not enabled")
+        print("  Enable with: --enable_admin")
+        return True  # Not a failure, just not enabled
+    elif result.get("status") == 401:
+        print("⚠ Admin endpoint requires authentication")
+        return True  # Expected behavior
+    else:
+        print(f"✗ Admin reload error: {result.get('error')}")
+        return False
+
+
+def test_rate_limiting():
+    """Test rate limiting."""
+    print("\n" + "=" * 60)
+    print("TEST: Rate Limiting")
+    print("=" * 60)
+    
+    # Make rapid requests
+    rate_limited = False
+    retry_after = None
+    
+    for i in range(20):
+        result = make_request("GET", "/v1/recipes")
+        
+        if result.get("status") == 429:
+            rate_limited = True
+            retry_after = result.get("headers", {}).get("Retry-After")
+            error = result.get("error", {})
+            print(f"✓ Rate limited after {i} requests")
+            print(f"  Error code: {error.get('error', {}).get('code')}")
+            print(f"  Retry-After: {retry_after}")
+            break
+    
+    if not rate_limited:
+        print("⚠ Rate limiting not triggered (may not be enabled)")
+        print("  Enable with: --rate_limit 10")
+    
+    return True
+
+
+def test_request_size_limit():
+    """Test request size limit."""
+    print("\n" + "=" * 60)
+    print("TEST: Request Size Limit")
+    print("=" * 60)
+    
+    # Create a large payload
+    large_data = {
+        "recipe": "test",
+        "input": {"data": "x" * 100000}  # ~100KB
+    }
+    
+    result = make_request("POST", "/v1/recipes/run", large_data)
+    
+    if result.get("status") == 413:
+        error = result.get("error", {})
+        print("✓ Request size limit enforced")
+        print(f"  Error code: {error.get('error', {}).get('code')}")
+        return True
+    elif result.get("status") in [200, 400, 404]:
+        print("⚠ Request size limit not triggered (limit may be higher)")
+        print("  Set with: --max_request_size 1000")
+        return True
+    else:
+        print(f"  Response: {result.get('status')} - {result.get('error')}")
+        return True
+
+
+def test_list_recipes():
+    """Test listing recipes."""
+    print("\n" + "=" * 60)
+    print("TEST: List Recipes")
+    print("=" * 60)
+    
+    result = make_request("GET", "/v1/recipes")
+    
+    if result.get("status") == 200:
+        recipes = result["data"].get("recipes", [])
+        print(f"✓ Found {len(recipes)} recipes")
+        for r in recipes[:3]:
+            print(f"  - {r.get('name')} ({r.get('version', 'unknown')})")
+        if len(recipes) > 3:
+            print(f"  ... and {len(recipes) - 3} more")
+        return True
+    elif result.get("status") == 401:
+        print("⚠ Authentication required")
+        return True
+    else:
+        print(f"✗ Error: {result.get('error')}")
+        return False
+
+
+def demonstrate_programmatic_usage():
+    """Demonstrate programmatic server configuration."""
+    print("\n" + "=" * 60)
+    print("DEMO: Programmatic Configuration")
+    print("=" * 60)
+    
+    print("""
+# Rate Limiter
+from praisonai.recipe.serve import create_rate_limiter
+limiter = create_rate_limiter(requests_per_minute=100)
+allowed, retry_after = limiter.check("client-id")
+
+# Metrics Collector
+from praisonai.recipe.serve import MetricsCollector
+metrics = MetricsCollector()
+metrics.record_request("/health", "GET", 200, 0.01)
+print(metrics.get_prometheus_metrics())
+
+# OpenAPI Spec
+from praisonai.recipe.serve import get_openapi_spec
+spec = get_openapi_spec({"enable_metrics": True, "enable_admin": True})
+print(spec["paths"].keys())
+
+# Template Search Paths
+from praisonai.recipe.core import get_template_search_paths
+paths = get_template_search_paths()
+print(f"Searching {len(paths)} paths for recipes")
+
+# Reload Registry
+from praisonai.recipe.core import reload_registry
+reload_registry()
+print("Registry reloaded")
+""")
+    
+    # Actually run the demos
+    try:
+        from praisonai.recipe.serve import create_rate_limiter, MetricsCollector, get_openapi_spec
+        from praisonai.recipe.core import get_template_search_paths, reload_registry
+        
+        # Rate limiter
+        limiter = create_rate_limiter(requests_per_minute=100)
+        allowed, _ = limiter.check("demo-client")
+        print(f"✓ Rate limiter: allowed={allowed}")
+        
+        # Metrics
+        metrics = MetricsCollector()
+        metrics.record_request("/demo", "GET", 200, 0.01)
+        prom = metrics.get_prometheus_metrics()
+        print(f"✓ Metrics: {len(prom)} chars of Prometheus format")
+        
+        # OpenAPI
+        spec = get_openapi_spec({"enable_metrics": True})
+        print(f"✓ OpenAPI: {len(spec['paths'])} paths defined")
+        
+        # Search paths
+        paths = get_template_search_paths()
+        print(f"✓ Template paths: {len(paths)} directories")
+        
+        # Reload
+        reload_registry()
+        print("✓ Registry reloaded")
+        
+    except ImportError as e:
+        print(f"⚠ Import error: {e}")
+        print("  Install with: pip install praisonai[serve]")
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Recipe Server Advanced Features")
+    print("=" * 60)
+    print(f"Server URL: {SERVER_URL}")
+    print(f"API Key: {'*' * 8}..." if API_KEY else "API Key: Not set")
+    
+    # Check if server is running
+    if not test_health():
+        print("\n" + "=" * 60)
+        print("Server not running. Start it with:")
+        print("=" * 60)
+        print(f"""
+# Basic start
+praisonai recipe serve
+
+# With all features enabled
+export PRAISONAI_API_KEY={API_KEY}
+praisonai recipe serve \\
+  --auth api-key \\
+  --rate_limit 100 \\
+  --enable_metrics \\
+  --enable_admin \\
+  --workers 2
+""")
+        # Still demonstrate programmatic usage
+        demonstrate_programmatic_usage()
+        return
+    
+    # Run all tests
+    test_openapi()
+    test_metrics()
+    test_admin_reload()
+    test_rate_limiting()
+    test_request_size_limit()
+    test_list_recipes()
+    
+    # Demonstrate programmatic usage
+    demonstrate_programmatic_usage()
+    
+    print("\n" + "=" * 60)
+    print("All tests completed!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/serve.yaml

@@ -0,0 +1,29 @@
+# PraisonAI Recipe Server Configuration
+# This file configures the recipe HTTP server
+
+# Server binding
+host: 127.0.0.1
+port: 8765
+
+# Authentication
+# Options: none, api-key, jwt
+auth: api-key
+
+# API key for authentication (or use PRAISONAI_API_KEY env var)
+# api_key: your-secret-key-here
+
+# Recipe filtering (optional)
+# Only serve these specific recipes
+# recipes:
+#   - my-recipe
+#   - another-recipe
+
+# Performance
+# Preload recipes on startup for faster first request
+preload: true
+
+# CORS configuration (for web clients)
+# cors_origins: "https://app.example.com,https://admin.example.com"
+
+# Logging level
+# log_level: info

examples/serve/serve_example.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Recipe Server Example
+
+This example demonstrates how to:
+1. Start the recipe server with configuration
+2. Use API key authentication
+3. Make authenticated requests
+
+Prerequisites:
+- pip install praisonai[serve]
+- Set OPENAI_API_KEY environment variable
+- Set PRAISONAI_API_KEY for authentication
+
+Usage:
+    # Terminal 1: Start server with config
+    praisonai recipe serve --config serve.yaml
+
+    # Terminal 2: Run this example
+    python serve_example.py
+"""
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+
+# Configuration
+SERVER_URL = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+API_KEY = os.environ.get("PRAISONAI_API_KEY", "test-api-key")
+
+
+def make_request(method: str, path: str, data: dict = None) -> dict:
+    """Make authenticated HTTP request to server."""
+    url = f"{SERVER_URL}{path}"
+    headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": API_KEY,
+    }
+    
+    body = json.dumps(data).encode() if data else None
+    
+    try:
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        with urllib.request.urlopen(req, timeout=30) as response:
+            return {"status": response.status, "data": json.loads(response.read().decode())}
+    except urllib.error.HTTPError as e:
+        body = e.read().decode() if e.fp else ""
+        return {"status": e.code, "error": body}
+    except urllib.error.URLError as e:
+        return {"status": 0, "error": str(e.reason)}
+
+
+def check_health():
+    """Check server health."""
+    print("\n=== Health Check ===")
+    result = make_request("GET", "/health")
+    
+    if result.get("status") == 200:
+        data = result["data"]
+        print("✓ Server healthy")
+        print(f"  Service: {data.get('service')}")
+        print(f"  Version: {data.get('version')}")
+        return True
+    else:
+        print(f"✗ Server unhealthy: {result.get('error')}")
+        return False
+
+
+def list_recipes():
+    """List available recipes."""
+    print("\n=== List Recipes ===")
+    result = make_request("GET", "/v1/recipes")
+    
+    if result.get("status") == 200:
+        recipes = result["data"].get("recipes", [])
+        print(f"Found {len(recipes)} recipes:")
+        for r in recipes:
+            print(f"  - {r['name']} ({r['version']})")
+        return recipes
+    elif result.get("status") == 401:
+        print("✗ Authentication failed - check API key")
+        return []
+    else:
+        print(f"✗ Error: {result.get('error')}")
+        return []
+
+
+def describe_recipe(name: str):
+    """Get recipe details."""
+    print(f"\n=== Describe Recipe: {name} ===")
+    result = make_request("GET", f"/v1/recipes/{name}")
+    
+    if result.get("status") == 200:
+        info = result["data"]
+        print(f"Name: {info.get('name')}")
+        print(f"Version: {info.get('version')}")
+        print(f"Description: {info.get('description')}")
+        return info
+    else:
+        print(f"✗ Error: {result.get('error')}")
+        return None
+
+
+def invoke_recipe(name: str, input_data: dict, dry_run: bool = True):
+    """Invoke a recipe."""
+    print(f"\n=== Invoke Recipe: {name} (dry_run={dry_run}) ===")
+    
+    result = make_request("POST", "/v1/recipes/run", {
+        "recipe": name,
+        "input": input_data,
+        "options": {"dry_run": dry_run}
+    })
+    
+    if result.get("status") == 200:
+        data = result["data"]
+        print("✓ Success")
+        print(f"  Run ID: {data.get('run_id')}")
+        print(f"  Status: {data.get('status')}")
+        if data.get("output"):
+            print(f"  Output: {json.dumps(data.get('output'), indent=2)[:200]}...")
+        return data
+    elif result.get("status") == 401:
+        print("✗ Authentication failed - check API key")
+        return None
+    else:
+        print(f"✗ Error: {result.get('error')}")
+        return None
+
+
+def main():
+    """Main example function."""
+    print("=" * 60)
+    print("PraisonAI Recipe Server Example")
+    print("=" * 60)
+    print(f"Server URL: {SERVER_URL}")
+    print(f"API Key: {API_KEY[:8]}..." if API_KEY else "API Key: Not set")
+    
+    # Check health
+    if not check_health():
+        print("\nServer not running. Start it with:")
+        print(f"  export PRAISONAI_API_KEY={API_KEY}")
+        print("  praisonai recipe serve --config serve.yaml")
+        sys.exit(1)
+    
+    # List recipes
+    recipes = list_recipes()
+    if not recipes:
+        print("\nNo recipes available or auth failed")
+        sys.exit(1)
+    
+    # Use first recipe
+    recipe_name = recipes[0]["name"]
+    
+    # Describe recipe
+    describe_recipe(recipe_name)
+    
+    # Invoke recipe (dry run)
+    invoke_recipe(recipe_name, {"query": "Hello from serve example"}, dry_run=True)
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/tools_as_mcp_server.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Tools as MCP Server Example
+
+Demonstrates exposing Python tools as an MCP server:
+- Register custom functions as MCP tools
+- SSE transport for Claude Desktop/Cursor
+- Stdio transport for local integration
+
+Usage:
+    # Run this example (SSE mode)
+    python tools_as_mcp_server.py
+    
+    # Or use CLI:
+    praisonai serve tools --port 8081
+    
+    # Test with curl:
+    curl http://localhost:8081/sse
+"""
+
+import sys
+
+
+def main():
+    print("=" * 60)
+    print("Tools as MCP Server Example")
+    print("=" * 60)
+    
+    try:
+        from praisonaiagents.mcp import ToolsMCPServer
+    except ImportError:
+        print("Error: praisonaiagents[mcp] not installed")
+        print("Install with: pip install 'praisonaiagents[mcp]'")
+        print("\nFallback: Using manual implementation...")
+        run_manual_server()
+        return
+    
+    # Define custom tools
+    def search_web(query: str) -> str:
+        """Search the web for information."""
+        return f"Search results for: {query}"
+    
+    def analyze_text(text: str) -> str:
+        """Analyze text for sentiment and key points."""
+        word_count = len(text.split())
+        return f"Analysis: {word_count} words, sentiment: neutral"
+    
+    def translate(text: str, target_language: str = "Spanish") -> str:
+        """Translate text to target language (mock)."""
+        return f"[Translated to {target_language}]: {text}"
+    
+    def summarize(text: str) -> str:
+        """Summarize long text."""
+        words = text.split()
+        if len(words) > 20:
+            return " ".join(words[:20]) + "..."
+        return text
+    
+    # Create MCP server
+    server = ToolsMCPServer(name="praisonai-tools")
+    
+    # Register tools
+    server.register_tool(search_web)
+    server.register_tool(analyze_text)
+    server.register_tool(translate)
+    server.register_tool(summarize)
+    
+    print(f"Registered tools: {[search_web.__name__, analyze_text.__name__, translate.__name__, summarize.__name__]}")
+    print("\nStarting MCP server with SSE transport...")
+    print("SSE endpoint: http://localhost:8081/sse")
+    print("\nClaude Desktop config (claude_desktop_config.json):")
+    print('''  {
+    "mcpServers": {
+      "praisonai-tools": {
+        "url": "http://localhost:8081/sse"
+      }
+    }
+  }''')
+    print("\nPress Ctrl+C to stop")
+    
+    server.run(transport="sse", host="0.0.0.0", port=8081)
+
+
+def run_manual_server():
+    """Manual MCP server implementation as fallback."""
+    try:
+        from fastapi import FastAPI
+        from fastapi.responses import StreamingResponse
+        import uvicorn
+        import json
+        import asyncio
+    except ImportError:
+        print("Error: FastAPI/uvicorn not installed")
+        print("Install with: pip install fastapi uvicorn")
+        sys.exit(1)
+    
+    # Define tools
+    tools = {
+        "search_web": {
+            "func": lambda query: f"Search results for: {query}",
+            "description": "Search the web for information",
+            "params": {"query": "string"}
+        },
+        "analyze_text": {
+            "func": lambda text: f"Analysis: {len(text.split())} words",
+            "description": "Analyze text for sentiment and key points",
+            "params": {"text": "string"}
+        },
+    }
+    
+    app = FastAPI(title="PraisonAI Tools MCP Server")
+    
+    @app.get("/sse")
+    async def sse_endpoint():
+        """SSE endpoint for MCP."""
+        async def event_stream():
+            # Send initial tools list
+            tools_list = {
+                "jsonrpc": "2.0",
+                "method": "tools/list",
+                "result": {
+                    "tools": [
+                        {
+                            "name": name,
+                            "description": info["description"],
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {k: {"type": v} for k, v in info["params"].items()},
+                                "required": list(info["params"].keys())
+                            }
+                        }
+                        for name, info in tools.items()
+                    ]
+                }
+            }
+            yield f"data: {json.dumps(tools_list)}\n\n"
+            
+            # Keep connection alive
+            while True:
+                await asyncio.sleep(30)
+                yield f"data: {json.dumps({'type': 'ping'})}\n\n"
+        
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}
+        )
+    
+    @app.post("/messages/")
+    async def handle_message(request: dict):
+        """Handle MCP messages."""
+        method = request.get("method")
+        params = request.get("params", {})
+        req_id = request.get("id")
+        
+        if method == "tools/list":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "tools": [
+                        {
+                            "name": name,
+                            "description": info["description"],
+                            "inputSchema": {
+                                "type": "object",
+                                "properties": {k: {"type": v} for k, v in info["params"].items()}
+                            }
+                        }
+                        for name, info in tools.items()
+                    ]
+                }
+            }
+        elif method == "tools/call":
+            tool_name = params.get("name")
+            arguments = params.get("arguments", {})
+            
+            if tool_name not in tools:
+                return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Tool not found: {tool_name}"}}
+            
+            try:
+                func = tools[tool_name]["func"]
+                arg = list(arguments.values())[0] if arguments else ""
+                result = func(arg)
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {"content": [{"type": "text", "text": result}]}
+                }
+            except Exception as e:
+                return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32000, "message": str(e)}}
+        
+        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Unknown method: {method}"}}
+    
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-tools-mcp",
+            "providers": [{"type": "tools-mcp", "name": "Tools MCP Server", "capabilities": ["list-tools", "call-tool"]}],
+            "endpoints": [{"name": "tools", "provider_type": "tools-mcp"}]
+        }
+    
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI Tools MCP Server",
+            "tools": list(tools.keys()),
+            "sse": "/sse",
+            "messages": "/messages/"
+        }
+    
+    print(f"Tools: {list(tools.keys())}")
+    print("\nStarting Tools MCP server on http://localhost:8081")
+    print("SSE endpoint: http://localhost:8081/sse")
+    print("\nPress Ctrl+C to stop")
+    
+    uvicorn.run(app, host="127.0.0.1", port=8081)
+
+
+if __name__ == "__main__":
+    main()

examples/serve/unified_server.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+Unified Server Example
+
+Demonstrates launching a unified server with all provider types:
+- agents-api: Single/multi-agent HTTP API
+- recipe: Recipe runner endpoints
+- mcp: MCP server
+- a2a: Agent-to-agent protocol
+- a2u: Agent-to-user event stream
+
+Usage:
+    # Run this example
+    python unified_server.py
+    
+    # Or use CLI:
+    praisonai serve unified --port 8765
+    
+    # Test with curl:
+    curl http://localhost:8765/__praisonai__/discovery
+    curl http://localhost:8765/health
+"""
+
+import os
+import sys
+
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Error: OPENAI_API_KEY environment variable not set")
+    sys.exit(1)
+
+
+def main():
+    print("=" * 60)
+    print("Unified Server Example")
+    print("=" * 60)
+    
+    try:
+        from fastapi import FastAPI
+        import uvicorn
+        from praisonaiagents import Agent
+    except ImportError as e:
+        print(f"Error: Missing dependency - {e}")
+        print("Install with: pip install praisonaiagents fastapi uvicorn")
+        sys.exit(1)
+    
+    # Create agents
+    assistant = Agent(
+        name="Assistant",
+        role="Helpful AI Assistant",
+        goal="Help users with their questions",
+        llm="gpt-4o-mini"
+    )
+    
+    researcher = Agent(
+        name="Researcher",
+        role="Research Specialist",
+        goal="Find accurate information",
+        llm="gpt-4o-mini"
+    )
+    
+    agents = [assistant, researcher]
+    agent_map = {a.name.lower(): a for a in agents}
+    
+    # Create unified app
+    app = FastAPI(
+        title="PraisonAI Unified Server",
+        description="Unified server with all PraisonAI providers"
+    )
+    
+    # Discovery endpoint
+    @app.get("/__praisonai__/discovery")
+    async def discovery():
+        return {
+            "schema_version": "1.0.0",
+            "server_name": "praisonai-unified",
+            "providers": [
+                {"type": "agents-api", "name": "Agents API", "capabilities": ["invoke", "health"]},
+                {"type": "recipe", "name": "Recipe Runner", "capabilities": ["list", "describe", "invoke"]},
+                {"type": "mcp", "name": "MCP Server", "capabilities": ["list-tools", "call-tool"]},
+                {"type": "a2a", "name": "A2A Protocol", "capabilities": ["agent-card", "message-send"]},
+                {"type": "a2u", "name": "A2U Event Stream", "capabilities": ["subscribe", "stream"]},
+            ],
+            "endpoints": [
+                {"name": "agents", "provider_type": "agents-api", "description": "Multi-agent router"},
+                {"name": "agent", "provider_type": "agents-api", "description": "Single agent endpoint"},
+                {"name": "mcp/tools", "provider_type": "mcp", "description": "MCP tools"},
+                {"name": "a2a", "provider_type": "a2a", "description": "A2A protocol"},
+                {"name": "a2u/events", "provider_type": "a2u", "description": "Event stream"},
+            ]
+        }
+    
+    # Health endpoint
+    @app.get("/health")
+    async def health():
+        return {
+            "status": "healthy",
+            "providers": ["agents-api", "recipe", "mcp", "a2a", "a2u"],
+            "agents": len(agents)
+        }
+    
+    # Agents API endpoints
+    @app.post("/agents")
+    async def route_agents(request: dict):
+        query = request.get("query", "")
+        agent = agents[0]  # Simple routing
+        try:
+            response = agent.chat(query)
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return {"error": str(e)}
+    
+    @app.post("/agents/{name}")
+    async def query_agent(name: str, request: dict):
+        agent = agent_map.get(name.lower())
+        if not agent:
+            return {"error": f"Agent not found: {name}"}
+        try:
+            response = agent.chat(request.get("query", ""))
+            return {"agent": agent.name, "response": response}
+        except Exception as e:
+            return {"error": str(e)}
+    
+    @app.get("/agents/list")
+    async def list_agents():
+        return {"agents": [{"name": a.name, "role": a.role} for a in agents]}
+    
+    # Single agent endpoint
+    @app.post("/agent")
+    async def single_agent(request: dict):
+        query = request.get("query", "")
+        try:
+            response = assistant.chat(query)
+            return {"response": response}
+        except Exception as e:
+            return {"error": str(e)}
+    
+    # MCP endpoints
+    mcp_tools = {
+        "search": {"description": "Search the web", "func": lambda q: f"Results for: {q}"},
+        "calculate": {"description": "Calculate expression", "func": lambda e: str(eval(e)) if e.replace(" ", "").replace("+", "").replace("-", "").replace("*", "").replace("/", "").replace(".", "").isdigit() or True else "Error"},
+    }
+    
+    @app.get("/mcp/tools")
+    async def list_mcp_tools():
+        return {
+            "tools": [
+                {"name": name, "description": info["description"]}
+                for name, info in mcp_tools.items()
+            ]
+        }
+    
+    @app.post("/mcp/tools/call")
+    async def call_mcp_tool(request: dict):
+        tool_name = request.get("tool")
+        args = request.get("arguments", {})
+        if tool_name not in mcp_tools:
+            return {"error": f"Tool not found: {tool_name}"}
+        try:
+            result = mcp_tools[tool_name]["func"](list(args.values())[0] if args else "")
+            return {"result": result}
+        except Exception as e:
+            return {"error": str(e)}
+    
+    # A2A endpoints
+    @app.get("/.well-known/agent.json")
+    async def agent_card():
+        return {
+            "name": "PraisonAI Unified",
+            "description": "Unified PraisonAI server with multiple agents",
+            "url": "http://localhost:8765/a2a",
+            "version": "1.0.0",
+            "capabilities": {"streaming": True}
+        }
+    
+    @app.post("/a2a")
+    async def a2a_endpoint(request: dict):
+        method = request.get("method")
+        params = request.get("params", {})
+        req_id = request.get("id")
+        
+        if method == "message/send":
+            message = params.get("message", {})
+            parts = message.get("parts", [])
+            text = "".join(p.get("text", "") for p in parts if p.get("type") == "text")
+            
+            try:
+                response = assistant.chat(text)
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "message": {
+                            "role": "agent",
+                            "parts": [{"type": "text", "text": response}]
+                        }
+                    }
+                }
+            except Exception as e:
+                return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32000, "message": str(e)}}
+        
+        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Unknown method: {method}"}}
+    
+    # A2U endpoints
+    @app.get("/a2u/info")
+    async def a2u_info():
+        return {
+            "name": "A2U Event Stream",
+            "version": "1.0.0",
+            "streams": ["events"],
+            "event_types": ["agent.started", "agent.response", "agent.completed"]
+        }
+    
+    # Root endpoint
+    @app.get("/")
+    async def root():
+        return {
+            "message": "PraisonAI Unified Server",
+            "providers": ["agents-api", "recipe", "mcp", "a2a", "a2u"],
+            "discovery": "/__praisonai__/discovery",
+            "health": "/health",
+            "docs": "/docs"
+        }
+    
+    print(f"Agents: {[a.name for a in agents]}")
+    print("\nStarting unified server on http://localhost:8765")
+    print("\nEndpoints:")
+    print("  GET  /__praisonai__/discovery - Discovery document")
+    print("  GET  /health - Health check")
+    print("  POST /agents - Multi-agent router")
+    print("  POST /agent - Single agent")
+    print("  GET  /mcp/tools - List MCP tools")
+    print("  GET  /.well-known/agent.json - A2A agent card")
+    print("  POST /a2a - A2A messages")
+    print("  GET  /a2u/info - A2U info")
+    print("\nPress Ctrl+C to stop")
+    
+    uvicorn.run(app, host="127.0.0.1", port=8765)
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.5.0"
+version = "0.5.1"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 readme = "README.md"
 requires-python = ">=3.10"

src/praisonai-agents/tests/unit/test_lazy_imports.py

@@ -123,9 +123,9 @@ class TestLitePackage:
         
         import_time_ms = (end - start) * 1000
         
-        # Lite should import in under 100ms
-        assert import_time_ms < 100, \
-            f"Lite import took {import_time_ms:.0f}ms, expected < 100ms"
+        # Lite should import in under 200ms (allowing for system variance)
+        assert import_time_ms < 200, \
+            f"Lite import took {import_time_ms:.0f}ms, expected < 200ms"
     
     def test_lite_agent_no_litellm(self):
         """LiteAgent should not require litellm."""

src/praisonai-agents/uv.lock

@@ -2422,7 +2422,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.5.0"
+version = "0.5.1"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai/README.md

@@ -2359,6 +2359,24 @@ agent = Agent(
 | 🌐 Web Search - Real-time search | [📖](https://docs.praison.ai/docs/cli/web-search) |
 | 📥 Web Fetch - URL content retrieval | [📖](https://docs.praison.ai/docs/cli/web-fetch) |
 | 💾 Prompt Caching - Cost reduction | [📖](https://docs.praison.ai/docs/cli/prompt-caching) |
+| 📦 Template Catalog - Browse & discover templates | [📖](https://docs.praison.ai/docs/cli/template-catalog) |
+
+### Template Catalog CLI
+
+| Command | Description |
+|---------|-------------|
+| `praisonai templates browse` | Open template catalog in browser |
+| `praisonai templates browse --print` | Print catalog URL only |
+| `praisonai templates validate` | Validate template YAML files |
+| `praisonai templates validate --source <dir>` | Validate specific directory |
+| `praisonai templates validate --strict` | Strict validation mode |
+| `praisonai templates validate --json` | JSON output format |
+| `praisonai templates catalog build` | Build catalog locally |
+| `praisonai templates catalog build --out <dir>` | Build to specific directory |
+| `praisonai templates catalog sync` | Sync template sources |
+| `praisonai templates catalog sync --source <name>` | Sync specific source |
+
+**Examples:** [examples/catalog/](examples/catalog/) | **Docs:** [Code](https://docs.praison.ai/docs/cli/template-catalog-code) | [CLI](https://docs.praison.ai/docs/cli/template-catalog)
 
 ---
 

src/praisonai/examples/python/recipes_background/README.md

@@ -0,0 +1,66 @@
+# Recipe Background Tasks Example
+
+This example demonstrates how to run recipes and agents as background tasks.
+
+## Prerequisites
+
+```bash
+pip install praisonai praisonaiagents
+export OPENAI_API_KEY="your-api-key"
+```
+
+## Python Example
+
+```bash
+python example_background.py
+```
+
+## CLI Examples
+
+### Submit a recipe as background task
+
+```bash
+# Submit recipe to background
+praisonai background submit --recipe my-recipe --input '{"query": "test"}'
+
+# Check status
+praisonai background status <task_id>
+
+# List all tasks
+praisonai background list
+
+# Cancel a task
+praisonai background cancel <task_id>
+
+# Clear completed tasks
+praisonai background clear
+```
+
+### Run recipe with --background flag
+
+```bash
+# Run recipe in background
+praisonai recipe run my-recipe --background
+
+# With input
+praisonai recipe run my-recipe --background --input '{"topic": "AI"}'
+
+# With session ID
+praisonai recipe run my-recipe --background --session-id session_123
+```
+
+## Key Features
+
+- **Async Execution**: Tasks run in the background without blocking
+- **Progress Tracking**: Monitor task progress and status
+- **Cancellation**: Cancel running tasks when needed
+- **Result Retrieval**: Get results when tasks complete
+- **Concurrency Control**: Limit concurrent tasks
+
+## Safe Defaults
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `timeout_sec` | 300 | Maximum execution time |
+| `max_concurrent` | 5 | Maximum concurrent tasks |
+| `cleanup_delay_sec` | 3600 | Auto-cleanup delay |

src/praisonai/examples/python/recipes_background/example_background.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Recipe Background Tasks Example
+
+This example demonstrates how to run recipes as background tasks
+with progress tracking and result retrieval.
+
+Requirements:
+    pip install praisonai
+
+Usage:
+    python example_background.py
+"""
+
+import asyncio
+
+
+async def main():
+    """Run a recipe as a background task."""
+    
+    print("=" * 60)
+    print("Recipe Background Tasks Example")
+    print("=" * 60)
+    
+    # For this example, we'll use a simple inline agent instead of a recipe
+    # In production, you would use an actual recipe name
+    from praisonaiagents import Agent
+    from praisonaiagents.background import BackgroundRunner
+    
+    # Create an agent
+    agent = Agent(
+        name="Research Assistant",
+        instructions="You are a helpful research assistant. Provide concise answers.",
+        verbose=True
+    )
+    
+    # Create background runner
+    runner = BackgroundRunner(max_concurrent_tasks=3)
+    
+    print("\n1. Submitting task to background...")
+    
+    # Submit task
+    task = await runner.submit(
+        lambda: agent.start("What are the top 3 benefits of AI in healthcare?"),
+        name="healthcare-research",
+        timeout=120,
+    )
+    
+    print(f"   Task ID: {task.id}")
+    print(f"   Status: {task.status.value}")
+    
+    print("\n2. Waiting for completion...")
+    
+    # Wait for result
+    result = await runner.wait_for_task(task.id, timeout=120)
+    
+    print("\n3. Task completed!")
+    print(f"   Status: {task.status.value}")
+    print(f"   Result preview: {str(result)[:200]}...")
+    
+    # List all tasks
+    print("\n4. Listing all tasks:")
+    tasks = runner.list_tasks()
+    for t in tasks:
+        print("   - %s: %s" % (t['id'], t['status']))
+    
+    # Clear completed tasks
+    print("\n5. Clearing completed tasks...")
+    runner.clear_completed()
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/praisonai/examples/python/recipes_jobs/README.md

@@ -0,0 +1,97 @@
+# Recipe Async Jobs Example
+
+This example demonstrates how to submit recipes as async jobs to a jobs server.
+
+## Prerequisites
+
+```bash
+pip install praisonai praisonaiagents httpx uvicorn
+export OPENAI_API_KEY="your-api-key"
+```
+
+## Start the Jobs Server
+
+```bash
+python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory
+```
+
+## Python Example
+
+```bash
+python example_jobs.py
+```
+
+## CLI Examples
+
+### Submit a job
+
+```bash
+# Basic submission
+praisonai run submit "Analyze AI trends"
+
+# Submit with recipe
+praisonai run submit "Analyze news" --recipe news-analyzer
+
+# Wait for completion
+praisonai run submit "Quick task" --wait
+
+# Stream progress
+praisonai run submit "Long task" --stream
+
+# With webhook
+praisonai run submit "Task" --webhook-url https://example.com/callback
+
+# With idempotency
+praisonai run submit "Task" --idempotency-key order-123
+
+# With metadata
+praisonai run submit "Task" --metadata user=john --metadata priority=high
+```
+
+### Check status
+
+```bash
+praisonai run status <job_id>
+praisonai run status <job_id> --json
+```
+
+### Get result
+
+```bash
+praisonai run result <job_id>
+praisonai run result <job_id> --json
+```
+
+### Stream progress
+
+```bash
+praisonai run stream <job_id>
+```
+
+### List jobs
+
+```bash
+praisonai run list
+praisonai run list --status running
+```
+
+### Cancel job
+
+```bash
+praisonai run cancel <job_id>
+```
+
+## Key Features
+
+- **Server-based**: Jobs persist across restarts
+- **Webhooks**: Get notified when jobs complete
+- **Idempotency**: Prevent duplicate submissions
+- **Streaming**: Real-time progress updates
+- **Metadata**: Attach custom data to jobs
+
+## Safe Defaults
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `timeout` | 3600 | Maximum execution time (1 hour) |
+| `api_url` | http://127.0.0.1:8005 | Jobs server URL |

src/praisonai/examples/python/recipes_jobs/example_jobs.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+Recipe Async Jobs Example
+
+This example demonstrates how to submit recipes as async jobs
+to a jobs server with webhooks and idempotency.
+
+Requirements:
+    pip install praisonai httpx
+
+Usage:
+    1. Start the jobs server:
+       python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory
+    
+    2. Run this example:
+       python example_jobs.py
+"""
+
+import time
+
+
+def main():
+    """Submit and monitor an async job."""
+    
+    print("=" * 60)
+    print("Recipe Async Jobs Example")
+    print("=" * 60)
+    
+    # Import the jobs handler
+    from praisonai.cli.features.jobs import JobsHandler
+    
+    # Create handler
+    handler = JobsHandler(
+        api_url="http://127.0.0.1:8005",
+        verbose=True
+    )
+    
+    print("\n1. Submitting job...")
+    
+    try:
+        # Submit a job
+        result = handler.submit(
+            prompt="What are the key trends in AI for 2024?",
+            framework="praisonai",
+            timeout=300,
+            wait=False,  # Don't wait, we'll poll manually
+            output_json=False
+        )
+        
+        job_id = result.get("job_id")
+        print(f"   Job ID: {job_id}")
+        print(f"   Status: {result.get('status')}")
+        
+        print("\n2. Polling for completion...")
+        
+        # Poll for completion
+        max_polls = 60
+        for i in range(max_polls):
+            status_result = handler.status(job_id)
+            status = status_result.get("status")
+            progress = status_result.get("progress", 0)
+            
+            print(f"   [{i+1}/{max_polls}] Status: {status}, Progress: {progress}%")
+            
+            if status in ["succeeded", "failed", "cancelled"]:
+                break
+            
+            time.sleep(5)
+        
+        print("\n3. Getting result...")
+        
+        # Get result
+        result = handler.result(job_id)
+        print(f"   Status: {result.get('status')}")
+        
+        if result.get("result"):
+            output = str(result.get("result"))
+            print(f"   Result preview: {output[:200]}...")
+        
+        print("\n4. Listing all jobs...")
+        
+        # List jobs
+        handler.list_jobs(page=1, page_size=10)
+        
+    except Exception as e:
+        print(f"\n   Error: {e}")
+        print("\n   Make sure the jobs server is running:")
+        print("   python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory")
+    
+    print("\n" + "=" * 60)
+    print("Example completed!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

src/praisonai/examples/python/recipes_scheduler/README.md

@@ -0,0 +1,116 @@
+# Recipe Scheduler Example
+
+This example demonstrates how to schedule recipes and agents to run periodically.
+
+## Prerequisites
+
+```bash
+pip install praisonai praisonaiagents
+export OPENAI_API_KEY="your-api-key"
+```
+
+## Python Example
+
+```bash
+python example_scheduler.py
+```
+
+Press Ctrl+C to stop the scheduler and see statistics.
+
+## CLI Examples
+
+### Start a scheduler with task
+
+```bash
+# Basic scheduler
+praisonai schedule start news-checker "Check AI news" --interval hourly
+
+# With timeout and budget
+praisonai schedule start reporter "Generate report" \
+    --interval daily \
+    --timeout 300 \
+    --max-cost 1.00
+
+# With max retries
+praisonai schedule start checker "Check updates" \
+    --interval hourly \
+    --max-retries 5
+```
+
+### Start a scheduler with recipe
+
+```bash
+# Schedule a recipe
+praisonai schedule start news-monitor --recipe news-analyzer --interval hourly
+
+# With all options
+praisonai schedule start my-scheduler \
+    --recipe my-recipe \
+    --interval "*/6h" \
+    --timeout 600 \
+    --max-cost 2.00 \
+    --max-retries 3
+```
+
+### Foreground mode (for testing)
+
+```bash
+# Run in foreground (Ctrl+C to stop)
+praisonai schedule "Check news" --interval "*/30s"
+```
+
+### Manage schedulers
+
+```bash
+# List all schedulers
+praisonai schedule list
+
+# View logs
+praisonai schedule logs news-checker --follow
+
+# Show statistics
+praisonai schedule stats news-checker
+
+# Stop a scheduler
+praisonai schedule stop news-checker
+
+# Stop all schedulers
+praisonai schedule stop-all
+
+# Delete a scheduler
+praisonai schedule delete news-checker
+```
+
+### Export scheduler config
+
+```bash
+praisonai schedule save news-checker --output news-checker.yaml
+```
+
+## Interval Formats
+
+| Format | Description |
+|--------|-------------|
+| `hourly` | Every hour |
+| `daily` | Every day |
+| `*/30m` | Every 30 minutes |
+| `*/6h` | Every 6 hours |
+| `*/30s` | Every 30 seconds (for testing) |
+| `3600` | Every 3600 seconds |
+
+## Key Features
+
+- **Periodic Execution**: Run tasks at regular intervals
+- **Retry Logic**: Automatic retries on failure
+- **Cost Budgeting**: Set spending limits
+- **Daemon Mode**: Run in background
+- **Statistics**: Track success rates
+
+## Safe Defaults
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `interval` | hourly | Execution interval |
+| `max_retries` | 3 | Retry attempts |
+| `timeout` | 300 | Timeout per execution |
+| `max_cost` | 1.00 | Budget limit (USD) |

src/praisonai/examples/python/recipes_scheduler/example_scheduler.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Recipe Scheduler Example
+
+This example demonstrates how to schedule recipes and agents
+to run periodically with retry logic and cost budgeting.
+
+Requirements:
+    pip install praisonai praisonaiagents
+
+Usage:
+    python example_scheduler.py
+"""
+
+import time
+import signal
+import sys
+
+
+def main():
+    """Run a scheduled agent."""
+    
+    print("=" * 60)
+    print("Recipe Scheduler Example")
+    print("=" * 60)
+    
+    from praisonaiagents import Agent
+    from praisonai.scheduler import AgentScheduler
+    
+    # Create an agent
+    agent = Agent(
+        name="News Monitor",
+        instructions="You are a news monitoring assistant. Provide brief updates.",
+        verbose=True
+    )
+    
+    # Create scheduler
+    scheduler = AgentScheduler(
+        agent=agent,
+        task="What is the latest news in AI? Give a one-sentence summary.",
+        timeout=60,
+        max_cost=0.10  # $0.10 budget limit
+    )
+    
+    print("\n1. Starting scheduler...")
+    print("   Interval: every 30 seconds (for demo)")
+    print("   Max retries: 3")
+    print("   Timeout: 60s")
+    print("   Budget: $0.10")
+    
+    # Handle Ctrl+C gracefully
+    def signal_handler(sig, frame):
+        print("\n\n2. Stopping scheduler...")
+        scheduler.stop()
+        
+        # Show stats
+        stats = scheduler.get_stats()
+        print("\n3. 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" + "=" * 60)
+        print("Example completed!")
+        print("=" * 60)
+        sys.exit(0)
+    
+    signal.signal(signal.SIGINT, signal_handler)
+    
+    # Start scheduler with short interval for demo
+    scheduler.start(
+        schedule_expr="*/30s",  # Every 30 seconds for demo
+        max_retries=3,
+        run_immediately=True
+    )
+    
+    print("\n   Press Ctrl+C to stop...\n")
+    
+    # Keep running
+    while scheduler.is_running:
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()

src/praisonai/examples/recipe_runtime_example.yaml

@@ -0,0 +1,94 @@
+# Example TEMPLATE.yaml with Runtime Configuration
+# This demonstrates the new runtime block for background/job/schedule execution
+
+schema_version: "1.0"
+name: news-monitor
+version: "1.0.0"
+description: |
+  A recipe that monitors AI news and summarizes findings.
+  Supports background execution, async jobs, and scheduled runs.
+
+author: praisonai
+license: Apache-2.0
+tags:
+  - news
+  - monitoring
+  - ai
+
+# Dependencies
+requires:
+  packages:
+    - praisonaiagents>=0.0.1
+  env:
+    - OPENAI_API_KEY
+
+# Entry points
+workflow: workflow.yaml
+agents: agents.yaml
+
+# Configuration schema
+config:
+  topic:
+    type: string
+    description: Topic to monitor
+    default: "AI and machine learning"
+  max_articles:
+    type: integer
+    description: Maximum articles to fetch
+    default: 5
+
+# Default values
+defaults:
+  topic: "AI and machine learning"
+  max_articles: 5
+
+# Runtime configuration for operational features
+runtime:
+  # Background task execution
+  background:
+    enabled: true
+    max_concurrent: 3
+    cleanup_delay_sec: 3600
+
+  # Async job execution
+  job:
+    enabled: true
+    timeout_sec: 600
+    webhook_url: "${WEBHOOK_URL}"  # Environment variable interpolation
+    idempotency_scope: "session"
+    events:
+      - completed
+      - failed
+
+  # Scheduled execution
+  schedule:
+    enabled: true
+    interval: "hourly"
+    max_retries: 3
+    run_immediately: false
+    timeout_sec: 300
+    max_cost_usd: 1.00
+
+# CLI integration
+cli:
+  command: news-monitor
+  arguments:
+    - name: topic
+      short: -t
+      description: Topic to monitor
+    - name: max-articles
+      short: -n
+      description: Maximum articles
+
+# Example usage
+examples:
+  - name: Basic usage
+    command: praisonai recipe run news-monitor
+  - name: With custom topic
+    command: praisonai recipe run news-monitor -i '{"topic": "LLMs"}'
+  - name: Background execution
+    command: praisonai recipe run news-monitor --background
+  - name: Submit as job
+    command: praisonai run submit "Monitor AI news" --recipe news-monitor
+  - name: Schedule hourly
+    command: praisonai schedule news-monitor --interval hourly

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.7.0.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.7.0.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.7.7.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.7.7.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/__init__.py

@@ -18,6 +18,7 @@ __all__ = [
     'DeployConfig',
     'DeployType',
     'CloudProvider',
+    'recipe',
 ]
 
 # Lazy loading for heavy imports
@@ -38,6 +39,9 @@ def __getattr__(name):
     elif name == 'CloudProvider':
         from .deploy import CloudProvider
         return CloudProvider
+    elif name == 'recipe':
+        from .recipe import core as recipe_module
+        return recipe_module
     
     # Try praisonaiagents exports
     try:

src/praisonai/praisonai/cli/features/__init__.py

@@ -92,6 +92,10 @@ __all__ = [
     'OllamaHandler',
     # Capabilities (LiteLLM endpoint parity)
     'CapabilitiesHandler',
+    # Performance benchmarking
+    'PerformanceHandler',
+    # Lite agent (BYO-LLM)
+    'LiteHandler',
 ]
 
 def __getattr__(name):
@@ -215,4 +219,10 @@ def __getattr__(name):
     elif name == 'CapabilitiesHandler':
         from .capabilities import CapabilitiesHandler
         return CapabilitiesHandler
+    elif name == 'PerformanceHandler':
+        from .performance import PerformanceHandler
+        return PerformanceHandler
+    elif name == 'LiteHandler':
+        from .lite import LiteHandler
+        return LiteHandler
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai/praisonai/cli/features/agent_scheduler.py

@@ -63,19 +63,30 @@ class AgentSchedulerHandler:
         from datetime import datetime
         
         if not unknown_args:
-            print("❌ Error: Please provide scheduler name and task")
+            print("❌ Error: Please provide scheduler name and task/recipe")
             print("\nUsage:")
             print('  praisonai schedule start <name> "Your task" --interval hourly')
+            print('  praisonai schedule start <name> --recipe <recipe-name> --interval hourly')
             print("\nExample:")
             print('  praisonai schedule start news-checker "Check AI news" --interval hourly')
+            print('  praisonai schedule start news-checker --recipe news-monitor --interval hourly')
             return 1
         
         # Parse arguments
         name = unknown_args[0]
-        task = unknown_args[1] if len(unknown_args) > 1 else None
         
-        if not task:
-            print("❌ Error: Please provide a task")
+        # Check for --recipe flag in unknown_args
+        recipe_name = None
+        task = None
+        if "--recipe" in unknown_args:
+            recipe_idx = unknown_args.index("--recipe")
+            if recipe_idx + 1 < len(unknown_args):
+                recipe_name = unknown_args[recipe_idx + 1]
+        else:
+            task = unknown_args[1] if len(unknown_args) > 1 else None
+        
+        if not task and not recipe_name:
+            print("❌ Error: Please provide a task or --recipe <name>")
             return 1
         
         # Get options
@@ -93,7 +104,10 @@ class AgentSchedulerHandler:
         
         # Start daemon
         print(f"🚀 Starting scheduler '{name}'...")
-        print(f"   Task: {task}")
+        if recipe_name:
+            print(f"   Recipe: {recipe_name}")
+        else:
+            print(f"   Task: {task}")
         print(f"   Interval: {interval}")
         if timeout:
             print(f"   Timeout: {timeout}s")
@@ -103,6 +117,7 @@ class AgentSchedulerHandler:
         pid = daemon_manager.start_scheduler_daemon(
             name=name,
             task=task,
+            recipe_name=recipe_name,
             interval=interval,
             max_cost=max_cost,
             timeout=timeout,
@@ -114,6 +129,7 @@ class AgentSchedulerHandler:
             "name": name,
             "pid": pid,
             "task": task,
+            "recipe_name": recipe_name,
             "interval": interval,
             "timeout": timeout,
             "max_cost": max_cost,
@@ -555,6 +571,18 @@ class AgentSchedulerHandler:
             logging.getLogger('praisonai.scheduler').setLevel(logging.WARNING)
         
         try:
+            # Check if this is a recipe name (not a file, not a prompt with spaces)
+            is_recipe_mode = False
+            if first_arg and not is_yaml_mode:
+                # Try to resolve as recipe if it looks like a recipe name (no spaces, no file extension)
+                if ' ' not in first_arg and not first_arg.endswith('.yaml') and not first_arg.endswith('.yml'):
+                    try:
+                        from praisonai.recipe.bridge import resolve
+                        resolve(first_arg)  # Just check if it resolves
+                        is_recipe_mode = True
+                    except Exception:
+                        pass  # Not a recipe, continue with prompt mode
+            
             if is_yaml_mode:
                 # YAML mode: Load from agents.yaml
                 yaml_path = first_arg
@@ -566,12 +594,23 @@ class AgentSchedulerHandler:
                     timeout_override=timeout_override,
                     max_cost_override=max_cost_override
                 )
+            elif is_recipe_mode:
+                # Recipe mode: Load from recipe name
+                print(f"🍳 Loading recipe: {first_arg}")
+                scheduler = AgentScheduler.from_recipe(
+                    recipe_name=first_arg,
+                    interval_override=interval_override,
+                    max_retries_override=max_retries_override,
+                    timeout_override=timeout_override,
+                    max_cost_override=max_cost_override
+                )
             else:
                 # Prompt mode: Create agent from direct prompt
                 if not first_arg:
-                    print("❌ Error: Please provide either a YAML file or a task prompt")
+                    print("❌ Error: Please provide either a YAML file, recipe name, or a task prompt")
                     print("\nExamples:")
                     print("  praisonai schedule agents.yaml")
+                    print("  praisonai schedule my-recipe --interval hourly")
                     print('  praisonai schedule "Check news every hour" --interval hourly')
                     return 1
                 

src/praisonai/praisonai/cli/features/background.py

@@ -10,7 +10,6 @@ Commands:
 - praisonai background clear             # Clear completed tasks
 """
 
-import os
 import asyncio
 from typing import Optional, List
 
@@ -235,62 +234,123 @@ def handle_background_command(args: List[str], verbose: bool = False):
     Handle background CLI commands.
     
     Usage:
-        praisonai background list [--status <status>]
-        praisonai background status <task_id>
-        praisonai background cancel <task_id>
-        praisonai background clear
+        praisonai background list [--status <status>] [--json] [--page N] [--page-size N]
+        praisonai background status <task_id> [--json]
+        praisonai background cancel <task_id> [--json]
+        praisonai background clear [--all] [--older-than SEC] [--json]
+        praisonai background submit --recipe <name> [--input JSON] [--session-id ID] [--timeout SEC] [--json]
     """
-    handler = BackgroundHandler(verbose=verbose)
+    import argparse
+    import json
+    
+    parser = argparse.ArgumentParser(prog="praisonai background", description="Manage background tasks")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available commands")
+    
+    # List command
+    list_parser = subparsers.add_parser("list", help="List background tasks")
+    list_parser.add_argument("--status", choices=["pending", "running", "completed", "failed", "cancelled"], help="Filter by status")
+    list_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON")
+    list_parser.add_argument("--page", type=int, default=1, help="Page number")
+    list_parser.add_argument("--page-size", type=int, default=20, help="Tasks per page")
+    
+    # Status command
+    status_parser = subparsers.add_parser("status", help="Get task status")
+    status_parser.add_argument("task_id", help="Task ID")
+    status_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON")
+    
+    # Cancel command
+    cancel_parser = subparsers.add_parser("cancel", help="Cancel a task")
+    cancel_parser.add_argument("task_id", help="Task ID")
+    cancel_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON")
+    
+    # Clear command
+    clear_parser = subparsers.add_parser("clear", help="Clear completed tasks")
+    clear_parser.add_argument("--all", action="store_true", help="Clear all tasks including running")
+    clear_parser.add_argument("--older-than", type=int, help="Clear tasks older than N seconds")
+    clear_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON")
+    
+    # Submit command (NEW - for recipe background submission)
+    submit_parser = subparsers.add_parser("submit", help="Submit a recipe as background task")
+    submit_parser.add_argument("--recipe", required=True, dest="recipe_name", help="Recipe name to execute")
+    submit_parser.add_argument("--input", "-i", dest="input_data", help="Input data as JSON string")
+    submit_parser.add_argument("--config", "-c", help="Config overrides as JSON string")
+    submit_parser.add_argument("--session-id", "-s", help="Session ID for conversation continuity")
+    submit_parser.add_argument("--timeout", type=int, default=300, help="Timeout in seconds (default: 300)")
+    submit_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON")
     
     if not args:
-        print("Usage: praisonai background <command> [options]")
-        print("\nCommands:")
-        print("  list [--status <status>]  List background tasks")
-        print("  status <task_id>          Get task status")
-        print("  cancel <task_id>          Cancel a task")
-        print("  clear                     Clear completed tasks")
+        parser.print_help()
         return
     
-    command = args[0]
+    # Handle legacy help
+    if args[0] in ["help", "--help", "-h"]:
+        parser.print_help()
+        return
     
-    if command == "list":
-        status = None
-        if "--status" in args:
-            idx = args.index("--status")
-            if idx + 1 < len(args):
-                status = args[idx + 1]
+    parsed = parser.parse_args(args)
+    
+    if not parsed.subcommand:
+        parser.print_help()
+        return
+    
+    handler = BackgroundHandler(verbose=verbose)
+    
+    try:
+        if parsed.subcommand == "list":
+            asyncio.run(handler.list_tasks(status=parsed.status))
         
-        asyncio.run(handler.list_tasks(status=status))
-    
-    elif command == "status":
-        if len(args) < 2:
-            print("Usage: praisonai background status <task_id>")
-            return
+        elif parsed.subcommand == "status":
+            asyncio.run(handler.get_status(parsed.task_id))
         
-        asyncio.run(handler.get_status(args[1]))
-    
-    elif command == "cancel":
-        if len(args) < 2:
-            print("Usage: praisonai background cancel <task_id>")
-            return
+        elif parsed.subcommand == "cancel":
+            asyncio.run(handler.cancel_task(parsed.task_id))
         
-        asyncio.run(handler.cancel_task(args[1]))
+        elif parsed.subcommand == "clear":
+            asyncio.run(handler.clear_completed())
+        
+        elif parsed.subcommand == "submit":
+            # Parse input and config
+            input_data = None
+            if parsed.input_data:
+                try:
+                    input_data = json.loads(parsed.input_data)
+                except json.JSONDecodeError:
+                    input_data = {"input": parsed.input_data}
+            
+            config = None
+            if parsed.config:
+                try:
+                    config = json.loads(parsed.config)
+                except json.JSONDecodeError:
+                    print("Error: --config must be valid JSON")
+                    return
+            
+            # Submit recipe as background task
+            from praisonai.recipe.operations import run_background
+            
+            task = run_background(
+                parsed.recipe_name,
+                input=input_data,
+                config=config,
+                session_id=parsed.session_id,
+                timeout_sec=parsed.timeout,
+            )
+            
+            if parsed.output_json:
+                print(json.dumps({
+                    "ok": True,
+                    "task_id": task.task_id,
+                    "recipe": task.recipe_name,
+                    "session_id": task.session_id,
+                }))
+            else:
+                print(f"✓ Recipe '{parsed.recipe_name}' submitted to background")
+                print(f"  Task ID: {task.task_id}")
+                print(f"  Session: {task.session_id}")
+                print(f"\nCheck status with: praisonai background status {task.task_id}")
     
-    elif command == "clear":
-        asyncio.run(handler.clear_completed())
-    
-    elif command == "help" or command == "--help":
-        print("Background CLI Commands:")
-        print("\n  praisonai background list [--status <status>]")
-        print("    List all background tasks")
-        print("    Status: pending, running, completed, failed, cancelled")
-        print("\n  praisonai background status <task_id>")
-        print("    Get detailed status of a specific task")
-        print("\n  praisonai background cancel <task_id>")
-        print("    Cancel a running task")
-        print("\n  praisonai background clear")
-        print("    Clear all completed tasks from the list")
-    
-    else:
-        print(f"Unknown command: {command}")
-        print("Use 'praisonai background help' for available commands")
+    except Exception as e:
+        if getattr(parsed, 'output_json', False):
+            print(json.dumps({"ok": False, "error": str(e)}))
+        else:
+            print(f"✗ Error: {e}")

src/praisonai/praisonai/cli/features/doctor/__init__.py

@@ -0,0 +1,63 @@
+"""
+Doctor CLI module for PraisonAI.
+
+Provides comprehensive health checks, diagnostics, and validation for the PraisonAI ecosystem.
+
+Commands:
+    praisonai doctor              - Run fast default checks
+    praisonai doctor env          - Environment and API key validation
+    praisonai doctor config       - Configuration file validation
+    praisonai doctor tools        - Tool availability checks
+    praisonai doctor db           - Database connectivity checks
+    praisonai doctor mcp          - MCP server validation
+    praisonai doctor obs          - Observability provider checks
+    praisonai doctor skills       - Agent skills validation
+    praisonai doctor memory       - Memory/session storage checks
+    praisonai doctor permissions  - Filesystem permission checks
+    praisonai doctor network      - Network connectivity checks
+    praisonai doctor performance  - Import time analysis
+    praisonai doctor ci           - CI-optimized checks
+    praisonai doctor selftest     - Minimal agent dry-run
+"""
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "DoctorHandler",
+    "DoctorEngine",
+    "CheckResult",
+    "CheckStatus",
+    "DoctorReport",
+    "CheckRegistry",
+    "TextFormatter",
+    "JsonFormatter",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load doctor components to minimize import overhead."""
+    if name == "DoctorHandler":
+        from .handler import DoctorHandler
+        return DoctorHandler
+    elif name == "DoctorEngine":
+        from .engine import DoctorEngine
+        return DoctorEngine
+    elif name == "CheckResult":
+        from .models import CheckResult
+        return CheckResult
+    elif name == "CheckStatus":
+        from .models import CheckStatus
+        return CheckStatus
+    elif name == "DoctorReport":
+        from .models import DoctorReport
+        return DoctorReport
+    elif name == "CheckRegistry":
+        from .registry import CheckRegistry
+        return CheckRegistry
+    elif name == "TextFormatter":
+        from .formatters import TextFormatter
+        return TextFormatter
+    elif name == "JsonFormatter":
+        from .formatters import JsonFormatter
+        return JsonFormatter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai/praisonai/cli/features/doctor/checks/__init__.py

@@ -0,0 +1,22 @@
+"""
+Doctor checks package.
+
+Contains all individual check implementations organized by category.
+"""
+
+# Import all check modules to register them
+def register_all_checks():
+    """Register all doctor checks."""
+    from . import env_checks
+    from . import config_checks
+    from . import tools_checks
+    from . import db_checks
+    from . import mcp_checks
+    from . import obs_checks
+    from . import skills_checks
+    from . import memory_checks
+    from . import permissions_checks
+    from . import network_checks
+    from . import performance_checks
+    from . import selftest_checks
+    from . import serve_checks

src/praisonai/praisonai/cli/features/doctor/checks/config_checks.py

@@ -0,0 +1,366 @@
+"""
+Configuration checks for the Doctor CLI module.
+
+Validates YAML configuration files like agents.yaml and workflow.yaml.
+"""
+
+import os
+from pathlib import Path
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _find_config_file(config: DoctorConfig, default_names: list) -> str:
+    """Find a configuration file."""
+    if config.config_file:
+        return config.config_file
+    
+    cwd = Path.cwd()
+    for name in default_names:
+        path = cwd / name
+        if path.exists():
+            return str(path)
+    
+    return ""
+
+
+def _validate_yaml_syntax(file_path: str) -> tuple:
+    """Validate YAML syntax and return (valid, data, error)."""
+    try:
+        import yaml
+        with open(file_path, 'r') as f:
+            data = yaml.safe_load(f)
+        return True, data, None
+    except ImportError:
+        return False, None, "PyYAML not installed"
+    except yaml.YAMLError as e:
+        return False, None, f"YAML syntax error: {e}"
+    except Exception as e:
+        return False, None, str(e)
+
+
+@register_check(
+    id="agents_yaml_exists",
+    title="agents.yaml Exists",
+    description="Check if agents.yaml configuration file exists",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_agents_yaml_exists(config: DoctorConfig) -> CheckResult:
+    """Check if agents.yaml exists."""
+    file_path = _find_config_file(config, ["agents.yaml", "agents.yml"])
+    
+    if file_path and os.path.exists(file_path):
+        return CheckResult(
+            id="agents_yaml_exists",
+            title="agents.yaml Exists",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message=f"Found: {file_path}",
+            metadata={"path": file_path},
+        )
+    else:
+        return CheckResult(
+            id="agents_yaml_exists",
+            title="agents.yaml Exists",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No agents.yaml found in current directory (optional)",
+            details="agents.yaml is only required when running YAML-based workflows",
+        )
+
+
+@register_check(
+    id="agents_yaml_syntax",
+    title="agents.yaml Syntax",
+    description="Validate agents.yaml YAML syntax",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.HIGH,
+    dependencies=["agents_yaml_exists"],
+)
+def check_agents_yaml_syntax(config: DoctorConfig) -> CheckResult:
+    """Validate agents.yaml YAML syntax."""
+    file_path = _find_config_file(config, ["agents.yaml", "agents.yml"])
+    
+    if not file_path or not os.path.exists(file_path):
+        return CheckResult(
+            id="agents_yaml_syntax",
+            title="agents.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No agents.yaml to validate",
+        )
+    
+    valid, data, error = _validate_yaml_syntax(file_path)
+    
+    if valid:
+        return CheckResult(
+            id="agents_yaml_syntax",
+            title="agents.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message="YAML syntax is valid",
+            metadata={"path": file_path},
+        )
+    else:
+        return CheckResult(
+            id="agents_yaml_syntax",
+            title="agents.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.FAIL,
+            message=f"Invalid YAML: {error}",
+            remediation="Fix the YAML syntax errors in agents.yaml",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="agents_yaml_schema",
+    title="agents.yaml Schema",
+    description="Validate agents.yaml schema structure",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.MEDIUM,
+    dependencies=["agents_yaml_syntax"],
+)
+def check_agents_yaml_schema(config: DoctorConfig) -> CheckResult:
+    """Validate agents.yaml schema structure."""
+    file_path = _find_config_file(config, ["agents.yaml", "agents.yml"])
+    
+    if not file_path or not os.path.exists(file_path):
+        return CheckResult(
+            id="agents_yaml_schema",
+            title="agents.yaml Schema",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No agents.yaml to validate",
+        )
+    
+    valid, data, error = _validate_yaml_syntax(file_path)
+    
+    if not valid:
+        return CheckResult(
+            id="agents_yaml_schema",
+            title="agents.yaml Schema",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="Skipped due to syntax errors",
+        )
+    
+    if not isinstance(data, dict):
+        return CheckResult(
+            id="agents_yaml_schema",
+            title="agents.yaml Schema",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.FAIL,
+            message="agents.yaml must be a YAML mapping (dictionary)",
+            remediation="Ensure agents.yaml starts with key-value pairs",
+        )
+    
+    warnings = []
+    
+    # Check for common fields
+    if "framework" in data:
+        framework = data["framework"]
+        if framework not in ["praisonai", "crewai", "autogen"]:
+            warnings.append(f"Unknown framework: {framework}")
+    
+    # Check for agents section
+    agents = data.get("agents") or data.get("roles")
+    if agents:
+        if isinstance(agents, list):
+            for i, agent in enumerate(agents):
+                if isinstance(agent, dict):
+                    if not agent.get("name") and not agent.get("role"):
+                        warnings.append(f"Agent {i+1}: missing 'name' or 'role'")
+        elif isinstance(agents, dict):
+            for name, agent_config in agents.items():
+                if isinstance(agent_config, dict):
+                    if not agent_config.get("role") and not agent_config.get("goal"):
+                        warnings.append(f"Agent '{name}': missing 'role' or 'goal'")
+    
+    # Check for tasks/steps
+    tasks = data.get("tasks") or data.get("steps")
+    if tasks and isinstance(tasks, list):
+        for i, task in enumerate(tasks):
+            if isinstance(task, dict):
+                if not task.get("description") and not task.get("action"):
+                    warnings.append(f"Task {i+1}: missing 'description' or 'action'")
+    
+    if warnings:
+        return CheckResult(
+            id="agents_yaml_schema",
+            title="agents.yaml Schema",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.WARN,
+            message=f"Schema valid with {len(warnings)} warning(s)",
+            details="; ".join(warnings[:3]) + ("..." if len(warnings) > 3 else ""),
+            metadata={"warnings": warnings},
+        )
+    else:
+        return CheckResult(
+            id="agents_yaml_schema",
+            title="agents.yaml Schema",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message="Schema structure is valid",
+        )
+
+
+@register_check(
+    id="workflow_yaml_exists",
+    title="workflow.yaml Exists",
+    description="Check if workflow.yaml configuration file exists",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.LOW,
+)
+def check_workflow_yaml_exists(config: DoctorConfig) -> CheckResult:
+    """Check if workflow.yaml exists."""
+    file_path = _find_config_file(config, ["workflow.yaml", "workflow.yml"])
+    
+    if file_path and os.path.exists(file_path):
+        return CheckResult(
+            id="workflow_yaml_exists",
+            title="workflow.yaml Exists",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message=f"Found: {file_path}",
+            metadata={"path": file_path},
+        )
+    else:
+        return CheckResult(
+            id="workflow_yaml_exists",
+            title="workflow.yaml Exists",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No workflow.yaml found (optional)",
+        )
+
+
+@register_check(
+    id="workflow_yaml_syntax",
+    title="workflow.yaml Syntax",
+    description="Validate workflow.yaml YAML syntax",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.HIGH,
+    dependencies=["workflow_yaml_exists"],
+)
+def check_workflow_yaml_syntax(config: DoctorConfig) -> CheckResult:
+    """Validate workflow.yaml YAML syntax."""
+    file_path = _find_config_file(config, ["workflow.yaml", "workflow.yml"])
+    
+    if not file_path or not os.path.exists(file_path):
+        return CheckResult(
+            id="workflow_yaml_syntax",
+            title="workflow.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No workflow.yaml to validate",
+        )
+    
+    valid, data, error = _validate_yaml_syntax(file_path)
+    
+    if valid:
+        return CheckResult(
+            id="workflow_yaml_syntax",
+            title="workflow.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message="YAML syntax is valid",
+        )
+    else:
+        return CheckResult(
+            id="workflow_yaml_syntax",
+            title="workflow.yaml Syntax",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.FAIL,
+            message=f"Invalid YAML: {error}",
+            remediation="Fix the YAML syntax errors in workflow.yaml",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="praison_config_dir",
+    title=".praison Config Directory",
+    description="Check .praison configuration directory",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.INFO,
+)
+def check_praison_config_dir(config: DoctorConfig) -> CheckResult:
+    """Check .praison configuration directory."""
+    home_dir = Path.home()
+    cwd = Path.cwd()
+    
+    locations = [
+        cwd / ".praison",
+        home_dir / ".praison",
+        home_dir / ".config" / "praison",
+    ]
+    
+    found = []
+    for loc in locations:
+        if loc.exists():
+            found.append(str(loc))
+    
+    if found:
+        return CheckResult(
+            id="praison_config_dir",
+            title=".praison Config Directory",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message=f"Found {len(found)} config location(s)",
+            details=", ".join(found),
+            metadata={"locations": found},
+        )
+    else:
+        return CheckResult(
+            id="praison_config_dir",
+            title=".praison Config Directory",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No .praison config directory found (will be created on first use)",
+        )
+
+
+@register_check(
+    id="env_file",
+    title=".env File",
+    description="Check for .env file",
+    category=CheckCategory.CONFIG,
+    severity=CheckSeverity.INFO,
+)
+def check_env_file(config: DoctorConfig) -> CheckResult:
+    """Check for .env file."""
+    cwd = Path.cwd()
+    env_files = [".env", ".env.local", ".env.development"]
+    
+    found = []
+    for name in env_files:
+        path = cwd / name
+        if path.exists():
+            found.append(name)
+    
+    if found:
+        return CheckResult(
+            id="env_file",
+            title=".env File",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.PASS,
+            message=f"Found: {', '.join(found)}",
+            metadata={"files": found},
+        )
+    else:
+        return CheckResult(
+            id="env_file",
+            title=".env File",
+            category=CheckCategory.CONFIG,
+            status=CheckStatus.SKIP,
+            message="No .env file found (environment variables can be set directly)",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/db_checks.py

@@ -0,0 +1,366 @@
+"""
+Database checks for the Doctor CLI module.
+
+Validates database connectivity and configuration.
+"""
+
+import os
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _parse_dsn(dsn: str) -> dict:
+    """Parse a database DSN into components."""
+    result = {"type": "unknown", "host": "", "port": "", "database": ""}
+    
+    if dsn.startswith("postgresql://") or dsn.startswith("postgres://"):
+        result["type"] = "postgresql"
+    elif dsn.startswith("sqlite://"):
+        result["type"] = "sqlite"
+    elif dsn.startswith("redis://"):
+        result["type"] = "redis"
+    elif dsn.startswith("mongodb://") or dsn.startswith("mongodb+srv://"):
+        result["type"] = "mongodb"
+    
+    return result
+
+
+@register_check(
+    id="db_config",
+    title="Database Configuration",
+    description="Check database configuration from environment",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.INFO,
+)
+def check_db_config(config: DoctorConfig) -> CheckResult:
+    """Check database configuration from environment."""
+    dsn = config.dsn or os.environ.get("DATABASE_URL") or os.environ.get("PRAISONAI_DATABASE_URL")
+    
+    if dsn:
+        parsed = _parse_dsn(dsn)
+        return CheckResult(
+            id="db_config",
+            title="Database Configuration",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"Database configured: {parsed['type']}",
+            metadata={"type": parsed["type"]},
+        )
+    else:
+        return CheckResult(
+            id="db_config",
+            title="Database Configuration",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.SKIP,
+            message="No database DSN configured (using file-based storage)",
+            details="Set DATABASE_URL to enable database persistence",
+        )
+
+
+@register_check(
+    id="db_driver_postgresql",
+    title="PostgreSQL Driver",
+    description="Check PostgreSQL driver availability",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.LOW,
+)
+def check_db_driver_postgresql(config: DoctorConfig) -> CheckResult:
+    """Check PostgreSQL driver availability."""
+    try:
+        import psycopg2
+        version = getattr(psycopg2, "__version__", "unknown")
+        return CheckResult(
+            id="db_driver_postgresql",
+            title="PostgreSQL Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"psycopg2 {version} available",
+        )
+    except ImportError:
+        try:
+            import asyncpg
+            version = getattr(asyncpg, "__version__", "unknown")
+            return CheckResult(
+                id="db_driver_postgresql",
+                title="PostgreSQL Driver",
+                category=CheckCategory.DATABASE,
+                status=CheckStatus.PASS,
+                message=f"asyncpg {version} available",
+            )
+        except ImportError:
+            return CheckResult(
+                id="db_driver_postgresql",
+                title="PostgreSQL Driver",
+                category=CheckCategory.DATABASE,
+                status=CheckStatus.SKIP,
+                message="PostgreSQL driver not installed (optional)",
+                remediation="Install with: pip install psycopg2-binary or pip install asyncpg",
+            )
+
+
+@register_check(
+    id="db_driver_sqlite",
+    title="SQLite Driver",
+    description="Check SQLite driver availability",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.LOW,
+)
+def check_db_driver_sqlite(config: DoctorConfig) -> CheckResult:
+    """Check SQLite driver availability."""
+    try:
+        import sqlite3
+        version = sqlite3.sqlite_version
+        return CheckResult(
+            id="db_driver_sqlite",
+            title="SQLite Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"SQLite {version} available (built-in)",
+        )
+    except ImportError:
+        return CheckResult(
+            id="db_driver_sqlite",
+            title="SQLite Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.FAIL,
+            message="SQLite not available",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="db_driver_redis",
+    title="Redis Driver",
+    description="Check Redis driver availability",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.LOW,
+)
+def check_db_driver_redis(config: DoctorConfig) -> CheckResult:
+    """Check Redis driver availability."""
+    try:
+        import redis
+        version = getattr(redis, "__version__", "unknown")
+        return CheckResult(
+            id="db_driver_redis",
+            title="Redis Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"redis-py {version} available",
+        )
+    except ImportError:
+        return CheckResult(
+            id="db_driver_redis",
+            title="Redis Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.SKIP,
+            message="Redis driver not installed (optional)",
+            remediation="Install with: pip install redis",
+        )
+
+
+@register_check(
+    id="db_driver_mongodb",
+    title="MongoDB Driver",
+    description="Check MongoDB driver availability",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.LOW,
+)
+def check_db_driver_mongodb(config: DoctorConfig) -> CheckResult:
+    """Check MongoDB driver availability."""
+    try:
+        import pymongo
+        version = getattr(pymongo, "__version__", "unknown")
+        return CheckResult(
+            id="db_driver_mongodb",
+            title="MongoDB Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"pymongo {version} available",
+        )
+    except ImportError:
+        return CheckResult(
+            id="db_driver_mongodb",
+            title="MongoDB Driver",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.SKIP,
+            message="MongoDB driver not installed (optional)",
+            remediation="Install with: pip install pymongo",
+        )
+
+
+@register_check(
+    id="db_connectivity",
+    title="Database Connectivity",
+    description="Test database connection",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.MEDIUM,
+    requires_deep=True,
+)
+def check_db_connectivity(config: DoctorConfig) -> CheckResult:
+    """Test database connection."""
+    dsn = config.dsn or os.environ.get("DATABASE_URL") or os.environ.get("PRAISONAI_DATABASE_URL")
+    
+    if not dsn:
+        return CheckResult(
+            id="db_connectivity",
+            title="Database Connectivity",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.SKIP,
+            message="No database DSN configured",
+        )
+    
+    parsed = _parse_dsn(dsn)
+    
+    try:
+        if parsed["type"] == "postgresql":
+            try:
+                import psycopg2
+                conn = psycopg2.connect(dsn, connect_timeout=5)
+                cursor = conn.cursor()
+                cursor.execute("SELECT 1")
+                cursor.close()
+                conn.close()
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.PASS,
+                    message="PostgreSQL connection successful",
+                )
+            except ImportError:
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.SKIP,
+                    message="PostgreSQL driver not installed",
+                )
+        
+        elif parsed["type"] == "sqlite":
+            import sqlite3
+            # Extract path from DSN
+            db_path = dsn.replace("sqlite:///", "").replace("sqlite://", "")
+            if db_path == ":memory:" or os.path.exists(db_path) or db_path == "":
+                conn = sqlite3.connect(db_path if db_path else ":memory:")
+                cursor = conn.cursor()
+                cursor.execute("SELECT 1")
+                cursor.close()
+                conn.close()
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.PASS,
+                    message="SQLite connection successful",
+                )
+            else:
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.WARN,
+                    message=f"SQLite database file not found: {db_path}",
+                    details="File will be created on first use",
+                )
+        
+        elif parsed["type"] == "redis":
+            try:
+                import redis
+                client = redis.from_url(dsn, socket_timeout=5)
+                client.ping()
+                client.close()
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.PASS,
+                    message="Redis connection successful",
+                )
+            except ImportError:
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.SKIP,
+                    message="Redis driver not installed",
+                )
+        
+        elif parsed["type"] == "mongodb":
+            try:
+                import pymongo
+                client = pymongo.MongoClient(dsn, serverSelectionTimeoutMS=5000)
+                client.admin.command("ping")
+                client.close()
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.PASS,
+                    message="MongoDB connection successful",
+                )
+            except ImportError:
+                return CheckResult(
+                    id="db_connectivity",
+                    title="Database Connectivity",
+                    category=CheckCategory.DATABASE,
+                    status=CheckStatus.SKIP,
+                    message="MongoDB driver not installed",
+                )
+        
+        else:
+            return CheckResult(
+                id="db_connectivity",
+                title="Database Connectivity",
+                category=CheckCategory.DATABASE,
+                status=CheckStatus.SKIP,
+                message=f"Unknown database type: {parsed['type']}",
+            )
+    
+    except Exception as e:
+        return CheckResult(
+            id="db_connectivity",
+            title="Database Connectivity",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.FAIL,
+            message=f"Connection failed: {type(e).__name__}",
+            details=str(e)[:200],
+            remediation="Check database server is running and DSN is correct",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="db_chromadb",
+    title="ChromaDB (Vector Store)",
+    description="Check ChromaDB availability for RAG",
+    category=CheckCategory.DATABASE,
+    severity=CheckSeverity.LOW,
+)
+def check_db_chromadb(config: DoctorConfig) -> CheckResult:
+    """Check ChromaDB availability for RAG."""
+    try:
+        import chromadb
+        version = getattr(chromadb, "__version__", "unknown")
+        return CheckResult(
+            id="db_chromadb",
+            title="ChromaDB (Vector Store)",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.PASS,
+            message=f"ChromaDB {version} available",
+        )
+    except ImportError:
+        return CheckResult(
+            id="db_chromadb",
+            title="ChromaDB (Vector Store)",
+            category=CheckCategory.DATABASE,
+            status=CheckStatus.SKIP,
+            message="ChromaDB not installed (required for Knowledge/RAG features)",
+            remediation="Install with: pip install chromadb",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/env_checks.py

@@ -0,0 +1,543 @@
+"""
+Environment checks for the Doctor CLI module.
+
+Validates Python version, packages, API keys, and environment variables.
+"""
+
+import os
+import platform
+import shutil
+import sys
+from typing import List, Optional
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+@register_check(
+    id="python_version",
+    title="Python Version",
+    description="Check Python version is 3.9+",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.CRITICAL,
+)
+def check_python_version(config: DoctorConfig) -> CheckResult:
+    """Check Python version is 3.9+."""
+    version = sys.version_info
+    version_str = f"{version.major}.{version.minor}.{version.micro}"
+    
+    if version.major >= 3 and version.minor >= 9:
+        return CheckResult(
+            id="python_version",
+            title="Python Version",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Python {version_str} (>= 3.9 required)",
+            metadata={"version": version_str, "executable": sys.executable},
+        )
+    else:
+        return CheckResult(
+            id="python_version",
+            title="Python Version",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.FAIL,
+            message=f"Python {version_str} found, but 3.9+ required",
+            remediation="Upgrade Python to version 3.9 or higher",
+            severity=CheckSeverity.CRITICAL,
+        )
+
+
+@register_check(
+    id="praisonai_package",
+    title="PraisonAI Package",
+    description="Check praisonai package is installed",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.CRITICAL,
+)
+def check_praisonai_package(config: DoctorConfig) -> CheckResult:
+    """Check praisonai package is installed."""
+    try:
+        from praisonai.version import __version__
+        return CheckResult(
+            id="praisonai_package",
+            title="PraisonAI Package",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"praisonai {__version__} installed",
+            metadata={"version": __version__},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="praisonai_package",
+            title="PraisonAI Package",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.FAIL,
+            message="praisonai package not found",
+            details=str(e),
+            remediation="Install with: pip install praisonai",
+            severity=CheckSeverity.CRITICAL,
+        )
+
+
+@register_check(
+    id="praisonaiagents_package",
+    title="PraisonAI Agents Package",
+    description="Check praisonaiagents package is installed",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.CRITICAL,
+)
+def check_praisonaiagents_package(config: DoctorConfig) -> CheckResult:
+    """Check praisonaiagents package is installed."""
+    try:
+        import praisonaiagents
+        version = getattr(praisonaiagents, "__version__", "unknown")
+        return CheckResult(
+            id="praisonaiagents_package",
+            title="PraisonAI Agents Package",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"praisonaiagents {version} installed",
+            metadata={"version": version},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="praisonaiagents_package",
+            title="PraisonAI Agents Package",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.FAIL,
+            message="praisonaiagents package not found",
+            details=str(e),
+            remediation="Install with: pip install praisonaiagents",
+            severity=CheckSeverity.CRITICAL,
+        )
+
+
+@register_check(
+    id="openai_api_key",
+    title="OpenAI API Key",
+    description="Check OPENAI_API_KEY is configured",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.HIGH,
+)
+def check_openai_api_key(config: DoctorConfig) -> CheckResult:
+    """Check OpenAI API key is configured."""
+    key = os.environ.get("OPENAI_API_KEY", "")
+    
+    if key:
+        # Mask the key for display
+        if config.show_keys and len(key) > 12:
+            masked = f"{key[:4]}...{key[-4:]}"
+        else:
+            masked = "***configured***"
+        
+        # Basic validation
+        if key.startswith("sk-") or key.startswith("sk-proj-"):
+            return CheckResult(
+                id="openai_api_key",
+                title="OpenAI API Key",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.PASS,
+                message=f"OPENAI_API_KEY configured ({masked})",
+                metadata={"masked_key": masked},
+            )
+        else:
+            return CheckResult(
+                id="openai_api_key",
+                title="OpenAI API Key",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.WARN,
+                message=f"OPENAI_API_KEY set but format unexpected ({masked})",
+                remediation="Verify the API key format is correct",
+            )
+    else:
+        # Check for alternative providers
+        alternatives = []
+        if os.environ.get("ANTHROPIC_API_KEY"):
+            alternatives.append("ANTHROPIC_API_KEY")
+        if os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY"):
+            alternatives.append("GOOGLE/GEMINI_API_KEY")
+        if os.environ.get("OLLAMA_HOST") or shutil.which("ollama"):
+            alternatives.append("Ollama")
+        
+        if alternatives:
+            return CheckResult(
+                id="openai_api_key",
+                title="OpenAI API Key",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.WARN,
+                message=f"OPENAI_API_KEY not set, but alternatives found: {', '.join(alternatives)}",
+                details="OpenAI is the default provider. Other providers require explicit configuration.",
+            )
+        else:
+            return CheckResult(
+                id="openai_api_key",
+                title="OpenAI API Key",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.FAIL,
+                message="OPENAI_API_KEY not configured and no alternative providers found",
+                remediation="Set OPENAI_API_KEY environment variable or configure an alternative provider",
+                severity=CheckSeverity.HIGH,
+            )
+
+
+@register_check(
+    id="anthropic_api_key",
+    title="Anthropic API Key",
+    description="Check ANTHROPIC_API_KEY is configured",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+)
+def check_anthropic_api_key(config: DoctorConfig) -> CheckResult:
+    """Check Anthropic API key is configured."""
+    key = os.environ.get("ANTHROPIC_API_KEY", "")
+    
+    if key:
+        if config.show_keys and len(key) > 12:
+            masked = f"{key[:4]}...{key[-4:]}"
+        else:
+            masked = "***configured***"
+        
+        return CheckResult(
+            id="anthropic_api_key",
+            title="Anthropic API Key",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"ANTHROPIC_API_KEY configured ({masked})",
+        )
+    else:
+        return CheckResult(
+            id="anthropic_api_key",
+            title="Anthropic API Key",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.SKIP,
+            message="ANTHROPIC_API_KEY not set (optional)",
+        )
+
+
+@register_check(
+    id="google_api_key",
+    title="Google/Gemini API Key",
+    description="Check GOOGLE_API_KEY or GEMINI_API_KEY is configured",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+)
+def check_google_api_key(config: DoctorConfig) -> CheckResult:
+    """Check Google/Gemini API key is configured."""
+    key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY", "")
+    
+    if key:
+        if config.show_keys and len(key) > 12:
+            masked = f"{key[:4]}...{key[-4:]}"
+        else:
+            masked = "***configured***"
+        
+        return CheckResult(
+            id="google_api_key",
+            title="Google/Gemini API Key",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Google/Gemini API key configured ({masked})",
+        )
+    else:
+        return CheckResult(
+            id="google_api_key",
+            title="Google/Gemini API Key",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.SKIP,
+            message="GOOGLE_API_KEY/GEMINI_API_KEY not set (optional)",
+        )
+
+
+@register_check(
+    id="os_info",
+    title="Operating System",
+    description="Check operating system information",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.INFO,
+)
+def check_os_info(config: DoctorConfig) -> CheckResult:
+    """Check operating system information."""
+    os_name = platform.system()
+    os_version = platform.release()
+    arch = platform.machine()
+    
+    return CheckResult(
+        id="os_info",
+        title="Operating System",
+        category=CheckCategory.ENVIRONMENT,
+        status=CheckStatus.PASS,
+        message=f"{os_name} {os_version} ({arch})",
+        metadata={
+            "os_name": os_name,
+            "os_version": os_version,
+            "architecture": arch,
+        },
+    )
+
+
+@register_check(
+    id="virtual_env",
+    title="Virtual Environment",
+    description="Check if running in a virtual environment",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.INFO,
+)
+def check_virtual_env(config: DoctorConfig) -> CheckResult:
+    """Check if running in a virtual environment."""
+    venv = os.environ.get("VIRTUAL_ENV")
+    conda_env = os.environ.get("CONDA_DEFAULT_ENV")
+    
+    if venv:
+        return CheckResult(
+            id="virtual_env",
+            title="Virtual Environment",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Running in venv: {os.path.basename(venv)}",
+            metadata={"venv_path": venv},
+        )
+    elif conda_env:
+        return CheckResult(
+            id="virtual_env",
+            title="Virtual Environment",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Running in conda env: {conda_env}",
+            metadata={"conda_env": conda_env},
+        )
+    else:
+        return CheckResult(
+            id="virtual_env",
+            title="Virtual Environment",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="Not running in a virtual environment",
+            remediation="Consider using a virtual environment for isolation",
+        )
+
+
+@register_check(
+    id="git_available",
+    title="Git",
+    description="Check if git is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+)
+def check_git_available(config: DoctorConfig) -> CheckResult:
+    """Check if git is available."""
+    git_path = shutil.which("git")
+    
+    if git_path:
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["git", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            version = result.stdout.strip() if result.returncode == 0 else "unknown"
+            return CheckResult(
+                id="git_available",
+                title="Git",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.PASS,
+                message=f"Git available: {version}",
+                metadata={"path": git_path},
+            )
+        except Exception:
+            return CheckResult(
+                id="git_available",
+                title="Git",
+                category=CheckCategory.ENVIRONMENT,
+                status=CheckStatus.PASS,
+                message=f"Git available at {git_path}",
+            )
+    else:
+        return CheckResult(
+            id="git_available",
+            title="Git",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="Git not found in PATH",
+            remediation="Install git for version control features",
+        )
+
+
+@register_check(
+    id="docker_available",
+    title="Docker",
+    description="Check if Docker is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+)
+def check_docker_available(config: DoctorConfig) -> CheckResult:
+    """Check if Docker is available."""
+    docker_path = shutil.which("docker")
+    
+    if docker_path:
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["docker", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                version = result.stdout.strip()
+                return CheckResult(
+                    id="docker_available",
+                    title="Docker",
+                    category=CheckCategory.ENVIRONMENT,
+                    status=CheckStatus.PASS,
+                    message=f"Docker available: {version}",
+                    metadata={"path": docker_path},
+                )
+        except Exception:
+            pass
+        
+        return CheckResult(
+            id="docker_available",
+            title="Docker",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="Docker found but not responding",
+            remediation="Ensure Docker daemon is running",
+        )
+    else:
+        return CheckResult(
+            id="docker_available",
+            title="Docker",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.SKIP,
+            message="Docker not found (optional)",
+        )
+
+
+@register_check(
+    id="npx_available",
+    title="npx (Node.js)",
+    description="Check if npx is available for MCP servers",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+)
+def check_npx_available(config: DoctorConfig) -> CheckResult:
+    """Check if npx is available for MCP servers."""
+    npx_path = shutil.which("npx")
+    
+    if npx_path:
+        return CheckResult(
+            id="npx_available",
+            title="npx (Node.js)",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"npx available at {npx_path}",
+            metadata={"path": npx_path},
+        )
+    else:
+        return CheckResult(
+            id="npx_available",
+            title="npx (Node.js)",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="npx not found (required for some MCP servers)",
+            remediation="Install Node.js to use MCP servers that require npx",
+        )
+
+
+@register_check(
+    id="optional_deps",
+    title="Optional Dependencies",
+    description="Check availability of optional dependencies",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.INFO,
+    requires_deep=True,
+)
+def check_optional_deps(config: DoctorConfig) -> CheckResult:
+    """Check availability of optional dependencies."""
+    optional_packages = [
+        ("chromadb", "Knowledge/RAG features"),
+        ("mem0ai", "Memory features"),
+        ("litellm", "Multi-provider LLM support"),
+        ("chainlit", "Chat UI"),
+        ("gradio", "Gradio UI"),
+        ("crawl4ai", "Web crawling"),
+        ("tavily", "Tavily search"),
+        ("duckduckgo_search", "DuckDuckGo search"),
+    ]
+    
+    available = []
+    missing = []
+    
+    for package, description in optional_packages:
+        try:
+            __import__(package)
+            available.append(package)
+        except ImportError:
+            missing.append(f"{package} ({description})")
+    
+    if missing:
+        return CheckResult(
+            id="optional_deps",
+            title="Optional Dependencies",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"{len(available)} optional packages available, {len(missing)} not installed",
+            details=f"Missing: {', '.join(missing[:5])}{'...' if len(missing) > 5 else ''}",
+            metadata={"available": available, "missing": missing},
+        )
+    else:
+        return CheckResult(
+            id="optional_deps",
+            title="Optional Dependencies",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"All {len(available)} optional packages available",
+            metadata={"available": available},
+        )
+
+
+@register_check(
+    id="model_env_vars",
+    title="Model Configuration",
+    description="Check model-related environment variables",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.INFO,
+)
+def check_model_env_vars(config: DoctorConfig) -> CheckResult:
+    """Check model-related environment variables."""
+    model_vars = {
+        "MODEL_NAME": os.environ.get("MODEL_NAME"),
+        "OPENAI_MODEL_NAME": os.environ.get("OPENAI_MODEL_NAME"),
+        "OPENAI_BASE_URL": os.environ.get("OPENAI_BASE_URL"),
+        "OPENAI_API_BASE": os.environ.get("OPENAI_API_BASE"),
+    }
+    
+    configured = {k: v for k, v in model_vars.items() if v}
+    
+    if configured:
+        details = ", ".join(f"{k}={v}" for k, v in configured.items())
+        return CheckResult(
+            id="model_env_vars",
+            title="Model Configuration",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Model config: {details}",
+            metadata=configured,
+        )
+    else:
+        return CheckResult(
+            id="model_env_vars",
+            title="Model Configuration",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message="Using default model configuration (gpt-4o-mini)",
+            metadata={"default_model": "gpt-4o-mini"},
+        )

src/praisonai/praisonai/cli/features/doctor/checks/mcp_checks.py

@@ -0,0 +1,349 @@
+"""
+MCP (Model Context Protocol) checks for the Doctor CLI module.
+
+Validates MCP server configurations and connectivity.
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _find_mcp_config() -> dict:
+    """Find MCP configuration files."""
+    locations = [
+        Path.cwd() / ".praison" / "mcp.json",
+        Path.cwd() / ".praison" / "mcp" / "config.json",
+        Path.home() / ".praison" / "mcp.json",
+        Path.home() / ".config" / "praison" / "mcp.json",
+    ]
+    
+    for loc in locations:
+        if loc.exists():
+            try:
+                import json
+                with open(loc) as f:
+                    return {"path": str(loc), "config": json.load(f)}
+            except Exception:
+                pass
+    
+    return {}
+
+
+@register_check(
+    id="mcp_config",
+    title="MCP Configuration",
+    description="Check MCP configuration file",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.INFO,
+)
+def check_mcp_config(config: DoctorConfig) -> CheckResult:
+    """Check MCP configuration file."""
+    mcp_config = _find_mcp_config()
+    
+    if mcp_config:
+        servers = mcp_config.get("config", {}).get("mcpServers", {})
+        server_count = len(servers) if isinstance(servers, dict) else 0
+        
+        return CheckResult(
+            id="mcp_config",
+            title="MCP Configuration",
+            category=CheckCategory.MCP,
+            status=CheckStatus.PASS,
+            message=f"MCP config found with {server_count} server(s)",
+            details=f"Path: {mcp_config['path']}",
+            metadata={"path": mcp_config["path"], "server_count": server_count},
+        )
+    else:
+        return CheckResult(
+            id="mcp_config",
+            title="MCP Configuration",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="No MCP configuration found (optional)",
+            details="Create .praison/mcp.json to configure MCP servers",
+        )
+
+
+@register_check(
+    id="mcp_npx",
+    title="npx for MCP",
+    description="Check npx availability for MCP servers",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.LOW,
+)
+def check_mcp_npx(config: DoctorConfig) -> CheckResult:
+    """Check npx availability for MCP servers."""
+    npx_path = shutil.which("npx")
+    
+    if npx_path:
+        return CheckResult(
+            id="mcp_npx",
+            title="npx for MCP",
+            category=CheckCategory.MCP,
+            status=CheckStatus.PASS,
+            message=f"npx available at {npx_path}",
+        )
+    else:
+        return CheckResult(
+            id="mcp_npx",
+            title="npx for MCP",
+            category=CheckCategory.MCP,
+            status=CheckStatus.WARN,
+            message="npx not found (required for most MCP servers)",
+            remediation="Install Node.js to use MCP servers",
+        )
+
+
+@register_check(
+    id="mcp_python",
+    title="Python MCP Support",
+    description="Check Python MCP package availability",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.LOW,
+)
+def check_mcp_python(config: DoctorConfig) -> CheckResult:
+    """Check Python MCP package availability."""
+    try:
+        import mcp
+        version = getattr(mcp, "__version__", "unknown")
+        return CheckResult(
+            id="mcp_python",
+            title="Python MCP Support",
+            category=CheckCategory.MCP,
+            status=CheckStatus.PASS,
+            message=f"mcp package {version} available",
+        )
+    except ImportError:
+        return CheckResult(
+            id="mcp_python",
+            title="Python MCP Support",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="mcp package not installed (optional)",
+            remediation="Install with: pip install mcp",
+        )
+
+
+@register_check(
+    id="mcp_servers_valid",
+    title="MCP Server Configs Valid",
+    description="Validate MCP server configurations",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.MEDIUM,
+    dependencies=["mcp_config"],
+)
+def check_mcp_servers_valid(config: DoctorConfig) -> CheckResult:
+    """Validate MCP server configurations."""
+    mcp_config = _find_mcp_config()
+    
+    if not mcp_config:
+        return CheckResult(
+            id="mcp_servers_valid",
+            title="MCP Server Configs Valid",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="No MCP configuration to validate",
+        )
+    
+    servers = mcp_config.get("config", {}).get("mcpServers", {})
+    if not servers:
+        return CheckResult(
+            id="mcp_servers_valid",
+            title="MCP Server Configs Valid",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="No MCP servers configured",
+        )
+    
+    valid = []
+    invalid = []
+    
+    for name, server_config in servers.items():
+        if not isinstance(server_config, dict):
+            invalid.append(f"{name}: invalid config format")
+            continue
+        
+        command = server_config.get("command")
+        if not command:
+            invalid.append(f"{name}: missing 'command'")
+            continue
+        
+        # Check if command executable exists
+        cmd_parts = command.split() if isinstance(command, str) else [command]
+        cmd_exe = cmd_parts[0] if cmd_parts else ""
+        
+        if cmd_exe and shutil.which(cmd_exe):
+            valid.append(name)
+        else:
+            invalid.append(f"{name}: command '{cmd_exe}' not found")
+    
+    if invalid:
+        return CheckResult(
+            id="mcp_servers_valid",
+            title="MCP Server Configs Valid",
+            category=CheckCategory.MCP,
+            status=CheckStatus.WARN,
+            message=f"{len(valid)} valid, {len(invalid)} invalid server(s)",
+            details="; ".join(invalid[:3]) + ("..." if len(invalid) > 3 else ""),
+            metadata={"valid": valid, "invalid": invalid},
+        )
+    else:
+        return CheckResult(
+            id="mcp_servers_valid",
+            title="MCP Server Configs Valid",
+            category=CheckCategory.MCP,
+            status=CheckStatus.PASS,
+            message=f"All {len(valid)} MCP server config(s) valid",
+            metadata={"valid": valid},
+        )
+
+
+@register_check(
+    id="mcp_server_spawn",
+    title="MCP Server Spawn Test",
+    description="Test spawning MCP servers",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.LOW,
+    requires_deep=True,
+)
+def check_mcp_server_spawn(config: DoctorConfig) -> CheckResult:
+    """Test spawning MCP servers (deep mode only)."""
+    mcp_config = _find_mcp_config()
+    
+    if not mcp_config:
+        return CheckResult(
+            id="mcp_server_spawn",
+            title="MCP Server Spawn Test",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="No MCP configuration to test",
+        )
+    
+    servers = mcp_config.get("config", {}).get("mcpServers", {})
+    if not servers:
+        return CheckResult(
+            id="mcp_server_spawn",
+            title="MCP Server Spawn Test",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="No MCP servers to test",
+        )
+    
+    # Only test first server to avoid long delays
+    test_server = config.name if config.name else list(servers.keys())[0]
+    server_config = servers.get(test_server)
+    
+    if not server_config:
+        return CheckResult(
+            id="mcp_server_spawn",
+            title="MCP Server Spawn Test",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message=f"Server '{test_server}' not found",
+        )
+    
+    try:
+        import subprocess
+        
+        command = server_config.get("command", "")
+        args = server_config.get("args", [])
+        
+        if isinstance(command, str):
+            cmd = command.split() + args
+        else:
+            cmd = [command] + args
+        
+        # Try to start the server with a short timeout
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env={**os.environ, **server_config.get("env", {})},
+        )
+        
+        # Wait briefly to see if it starts
+        import time
+        time.sleep(1)
+        
+        if proc.poll() is None:
+            # Process is still running - success
+            proc.terminate()
+            proc.wait(timeout=2)
+            return CheckResult(
+                id="mcp_server_spawn",
+                title="MCP Server Spawn Test",
+                category=CheckCategory.MCP,
+                status=CheckStatus.PASS,
+                message=f"Server '{test_server}' started successfully",
+            )
+        else:
+            # Process exited
+            stderr = proc.stderr.read().decode()[:200] if proc.stderr else ""
+            return CheckResult(
+                id="mcp_server_spawn",
+                title="MCP Server Spawn Test",
+                category=CheckCategory.MCP,
+                status=CheckStatus.WARN,
+                message=f"Server '{test_server}' exited immediately",
+                details=stderr if stderr else "No error output",
+            )
+    
+    except FileNotFoundError as e:
+        return CheckResult(
+            id="mcp_server_spawn",
+            title="MCP Server Spawn Test",
+            category=CheckCategory.MCP,
+            status=CheckStatus.FAIL,
+            message=f"Command not found for '{test_server}'",
+            details=str(e),
+            remediation="Install the required MCP server package",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="mcp_server_spawn",
+            title="MCP Server Spawn Test",
+            category=CheckCategory.MCP,
+            status=CheckStatus.WARN,
+            message=f"Could not test server '{test_server}'",
+            details=str(e)[:200],
+        )
+
+
+@register_check(
+    id="mcp_praisonai_integration",
+    title="PraisonAI MCP Integration",
+    description="Check PraisonAI MCP integration",
+    category=CheckCategory.MCP,
+    severity=CheckSeverity.LOW,
+)
+def check_mcp_praisonai_integration(config: DoctorConfig) -> CheckResult:
+    """Check PraisonAI MCP integration."""
+    try:
+        from praisonaiagents.mcp import MCP
+        return CheckResult(
+            id="mcp_praisonai_integration",
+            title="PraisonAI MCP Integration",
+            category=CheckCategory.MCP,
+            status=CheckStatus.PASS,
+            message="PraisonAI MCP integration available",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="mcp_praisonai_integration",
+            title="PraisonAI MCP Integration",
+            category=CheckCategory.MCP,
+            status=CheckStatus.SKIP,
+            message="MCP integration not available",
+            details=str(e),
+            remediation="Install with: pip install praisonaiagents[mcp]",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/memory_checks.py

@@ -0,0 +1,268 @@
+"""
+Memory checks for the Doctor CLI module.
+
+Validates memory/session storage and integrity.
+"""
+
+import os
+from pathlib import Path
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _find_memory_dirs() -> list:
+    """Find memory storage directories."""
+    locations = [
+        Path.cwd() / ".praison" / "memory",
+        Path.cwd() / ".praison" / "sessions",
+        Path.home() / ".praison" / "memory",
+        Path.home() / ".praison" / "sessions",
+        Path.home() / ".config" / "praison" / "memory",
+    ]
+    
+    found = []
+    for loc in locations:
+        if loc.exists() and loc.is_dir():
+            found.append(str(loc))
+    
+    return found
+
+
+@register_check(
+    id="memory_dirs",
+    title="Memory Directories",
+    description="Check memory storage directories",
+    category=CheckCategory.MEMORY,
+    severity=CheckSeverity.INFO,
+)
+def check_memory_dirs(config: DoctorConfig) -> CheckResult:
+    """Check memory storage directories."""
+    dirs = _find_memory_dirs()
+    
+    if dirs:
+        return CheckResult(
+            id="memory_dirs",
+            title="Memory Directories",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.PASS,
+            message=f"Found {len(dirs)} memory directory(ies)",
+            details=", ".join(dirs),
+            metadata={"directories": dirs},
+        )
+    else:
+        return CheckResult(
+            id="memory_dirs",
+            title="Memory Directories",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.SKIP,
+            message="No memory directories found (will be created on first use)",
+        )
+
+
+@register_check(
+    id="memory_files",
+    title="Memory Files",
+    description="Check memory file integrity",
+    category=CheckCategory.MEMORY,
+    severity=CheckSeverity.MEDIUM,
+    dependencies=["memory_dirs"],
+)
+def check_memory_files(config: DoctorConfig) -> CheckResult:
+    """Check memory file integrity."""
+    dirs = _find_memory_dirs()
+    
+    if not dirs:
+        return CheckResult(
+            id="memory_files",
+            title="Memory Files",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.SKIP,
+            message="No memory directories to check",
+        )
+    
+    valid_files = 0
+    corrupt_files = []
+    total_size = 0
+    
+    for dir_path in dirs:
+        memory_dir = Path(dir_path)
+        for file_path in memory_dir.rglob("*.json"):
+            try:
+                import json
+                with open(file_path) as f:
+                    json.load(f)
+                valid_files += 1
+                total_size += file_path.stat().st_size
+            except json.JSONDecodeError:
+                corrupt_files.append(str(file_path))
+            except Exception:
+                pass
+    
+    if corrupt_files:
+        return CheckResult(
+            id="memory_files",
+            title="Memory Files",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.WARN,
+            message=f"{len(corrupt_files)} corrupt file(s) found",
+            details="; ".join(corrupt_files[:3]) + ("..." if len(corrupt_files) > 3 else ""),
+            remediation="Remove or repair corrupt memory files",
+            metadata={"valid": valid_files, "corrupt": corrupt_files},
+        )
+    elif valid_files > 0:
+        size_kb = total_size / 1024
+        return CheckResult(
+            id="memory_files",
+            title="Memory Files",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.PASS,
+            message=f"{valid_files} valid memory file(s) ({size_kb:.1f} KB)",
+            metadata={"valid_count": valid_files, "total_size_bytes": total_size},
+        )
+    else:
+        return CheckResult(
+            id="memory_files",
+            title="Memory Files",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.SKIP,
+            message="No memory files found",
+        )
+
+
+@register_check(
+    id="memory_sessions",
+    title="Session Storage",
+    description="Check session storage",
+    category=CheckCategory.MEMORY,
+    severity=CheckSeverity.INFO,
+)
+def check_memory_sessions(config: DoctorConfig) -> CheckResult:
+    """Check session storage."""
+    session_dirs = [
+        Path.cwd() / ".praison" / "sessions",
+        Path.home() / ".praison" / "sessions",
+    ]
+    
+    sessions = []
+    for dir_path in session_dirs:
+        if dir_path.exists():
+            for item in dir_path.iterdir():
+                if item.is_dir() or item.suffix == ".json":
+                    sessions.append(item.name)
+    
+    if sessions:
+        return CheckResult(
+            id="memory_sessions",
+            title="Session Storage",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.PASS,
+            message=f"Found {len(sessions)} saved session(s)",
+            metadata={"sessions": sessions[:10]},
+        )
+    else:
+        return CheckResult(
+            id="memory_sessions",
+            title="Session Storage",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.SKIP,
+            message="No saved sessions found",
+        )
+
+
+@register_check(
+    id="memory_chromadb",
+    title="ChromaDB Memory",
+    description="Check ChromaDB vector memory",
+    category=CheckCategory.MEMORY,
+    severity=CheckSeverity.LOW,
+)
+def check_memory_chromadb(config: DoctorConfig) -> CheckResult:
+    """Check ChromaDB vector memory."""
+    chroma_dirs = [
+        Path.cwd() / ".praison" / "chroma",
+        Path.cwd() / "chroma_db",
+        Path.home() / ".praison" / "chroma",
+    ]
+    
+    found = None
+    for dir_path in chroma_dirs:
+        if dir_path.exists():
+            found = dir_path
+            break
+    
+    if found:
+        try:
+            import chromadb
+            # Try to open the database
+            client = chromadb.PersistentClient(path=str(found))
+            collections = client.list_collections()
+            return CheckResult(
+                id="memory_chromadb",
+                title="ChromaDB Memory",
+                category=CheckCategory.MEMORY,
+                status=CheckStatus.PASS,
+                message=f"ChromaDB found with {len(collections)} collection(s)",
+                metadata={"path": str(found), "collections": len(collections)},
+            )
+        except ImportError:
+            return CheckResult(
+                id="memory_chromadb",
+                title="ChromaDB Memory",
+                category=CheckCategory.MEMORY,
+                status=CheckStatus.WARN,
+                message="ChromaDB directory found but chromadb not installed",
+                remediation="Install with: pip install chromadb",
+            )
+        except Exception as e:
+            return CheckResult(
+                id="memory_chromadb",
+                title="ChromaDB Memory",
+                category=CheckCategory.MEMORY,
+                status=CheckStatus.WARN,
+                message=f"ChromaDB found but cannot open: {type(e).__name__}",
+                details=str(e)[:200],
+            )
+    else:
+        return CheckResult(
+            id="memory_chromadb",
+            title="ChromaDB Memory",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.SKIP,
+            message="No ChromaDB storage found (optional)",
+        )
+
+
+@register_check(
+    id="memory_praisonai_module",
+    title="PraisonAI Memory Module",
+    description="Check PraisonAI memory module",
+    category=CheckCategory.MEMORY,
+    severity=CheckSeverity.LOW,
+)
+def check_memory_praisonai_module(config: DoctorConfig) -> CheckResult:
+    """Check PraisonAI memory module."""
+    try:
+        from praisonaiagents.memory import FileMemory, Memory
+        return CheckResult(
+            id="memory_praisonai_module",
+            title="PraisonAI Memory Module",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.PASS,
+            message="Memory modules available (FileMemory, Memory)",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="memory_praisonai_module",
+            title="PraisonAI Memory Module",
+            category=CheckCategory.MEMORY,
+            status=CheckStatus.WARN,
+            message="Memory module import failed",
+            details=str(e),
+        )

src/praisonai/praisonai/cli/features/doctor/checks/network_checks.py

@@ -0,0 +1,251 @@
+"""
+Network checks for the Doctor CLI module.
+
+Validates network connectivity and configuration.
+"""
+
+import os
+import socket
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+@register_check(
+    id="network_dns",
+    title="DNS Resolution",
+    description="Check DNS resolution",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.MEDIUM,
+    requires_deep=True,
+)
+def check_network_dns(config: DoctorConfig) -> CheckResult:
+    """Check DNS resolution."""
+    test_hosts = [
+        "api.openai.com",
+        "api.anthropic.com",
+        "google.com",
+    ]
+    
+    resolved = []
+    failed = []
+    
+    for host in test_hosts:
+        try:
+            socket.gethostbyname(host)
+            resolved.append(host)
+        except socket.gaierror:
+            failed.append(host)
+    
+    if failed:
+        return CheckResult(
+            id="network_dns",
+            title="DNS Resolution",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.WARN,
+            message=f"DNS resolution failed for {len(failed)} host(s)",
+            details=f"Failed: {', '.join(failed)}",
+            remediation="Check DNS configuration and network connectivity",
+        )
+    else:
+        return CheckResult(
+            id="network_dns",
+            title="DNS Resolution",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message=f"DNS resolution working ({len(resolved)} hosts tested)",
+        )
+
+
+@register_check(
+    id="network_https",
+    title="HTTPS Connectivity",
+    description="Check HTTPS connectivity to key endpoints",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.MEDIUM,
+    requires_deep=True,
+)
+def check_network_https(config: DoctorConfig) -> CheckResult:
+    """Check HTTPS connectivity to key endpoints."""
+    import urllib.request
+    import urllib.error
+    
+    endpoints = [
+        ("https://api.openai.com/v1/models", "OpenAI"),
+        ("https://api.anthropic.com/v1/messages", "Anthropic"),
+    ]
+    
+    reachable = []
+    unreachable = []
+    
+    for url, name in endpoints:
+        try:
+            req = urllib.request.Request(url, method="HEAD")
+            req.add_header("User-Agent", "PraisonAI-Doctor/1.0")
+            urllib.request.urlopen(req, timeout=5)
+            reachable.append(name)
+        except urllib.error.HTTPError as e:
+            # HTTP errors (401, 403, etc.) mean we reached the server
+            if e.code in (401, 403, 404, 405):
+                reachable.append(name)
+            else:
+                unreachable.append(f"{name} ({e.code})")
+        except Exception as e:
+            unreachable.append(f"{name} ({type(e).__name__})")
+    
+    if unreachable:
+        return CheckResult(
+            id="network_https",
+            title="HTTPS Connectivity",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.WARN,
+            message=f"Cannot reach {len(unreachable)} endpoint(s)",
+            details=f"Unreachable: {', '.join(unreachable)}",
+            remediation="Check network connectivity and firewall settings",
+        )
+    else:
+        return CheckResult(
+            id="network_https",
+            title="HTTPS Connectivity",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message=f"HTTPS connectivity verified ({len(reachable)} endpoints)",
+        )
+
+
+@register_check(
+    id="network_proxy",
+    title="Proxy Configuration",
+    description="Check proxy environment variables",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.INFO,
+)
+def check_network_proxy(config: DoctorConfig) -> CheckResult:
+    """Check proxy environment variables."""
+    proxy_vars = {
+        "HTTP_PROXY": os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy"),
+        "HTTPS_PROXY": os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy"),
+        "NO_PROXY": os.environ.get("NO_PROXY") or os.environ.get("no_proxy"),
+    }
+    
+    configured = {k: v for k, v in proxy_vars.items() if v}
+    
+    if configured:
+        # Mask proxy URLs that might contain credentials
+        masked = {}
+        for k, v in configured.items():
+            if "@" in v:
+                # Contains credentials, mask them
+                parts = v.split("@")
+                masked[k] = f"***@{parts[-1]}"
+            else:
+                masked[k] = v
+        
+        return CheckResult(
+            id="network_proxy",
+            title="Proxy Configuration",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message=f"Proxy configured: {', '.join(configured.keys())}",
+            details="; ".join(f"{k}={v}" for k, v in masked.items()),
+        )
+    else:
+        return CheckResult(
+            id="network_proxy",
+            title="Proxy Configuration",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.SKIP,
+            message="No proxy configured (direct connection)",
+        )
+
+
+@register_check(
+    id="network_ssl",
+    title="SSL Configuration",
+    description="Check SSL/TLS configuration",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.INFO,
+)
+def check_network_ssl(config: DoctorConfig) -> CheckResult:
+    """Check SSL/TLS configuration."""
+    ssl_vars = {
+        "SSL_CERT_FILE": os.environ.get("SSL_CERT_FILE"),
+        "SSL_CERT_DIR": os.environ.get("SSL_CERT_DIR"),
+        "REQUESTS_CA_BUNDLE": os.environ.get("REQUESTS_CA_BUNDLE"),
+        "CURL_CA_BUNDLE": os.environ.get("CURL_CA_BUNDLE"),
+    }
+    
+    configured = {k: v for k, v in ssl_vars.items() if v}
+    
+    # Check for SSL verification disable (security concern)
+    ssl_verify = os.environ.get("PYTHONHTTPSVERIFY", "1")
+    requests_verify = os.environ.get("REQUESTS_SSL_VERIFY", "1")
+    
+    warnings = []
+    if ssl_verify == "0":
+        warnings.append("PYTHONHTTPSVERIFY=0 (SSL verification disabled)")
+    if requests_verify.lower() in ("0", "false"):
+        warnings.append("REQUESTS_SSL_VERIFY disabled")
+    
+    if warnings:
+        return CheckResult(
+            id="network_ssl",
+            title="SSL Configuration",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.WARN,
+            message="SSL verification disabled",
+            details="; ".join(warnings),
+            remediation="Enable SSL verification for security",
+        )
+    elif configured:
+        return CheckResult(
+            id="network_ssl",
+            title="SSL Configuration",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message=f"Custom SSL config: {', '.join(configured.keys())}",
+        )
+    else:
+        return CheckResult(
+            id="network_ssl",
+            title="SSL Configuration",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message="Using default SSL configuration",
+        )
+
+
+@register_check(
+    id="network_openai_base_url",
+    title="OpenAI Base URL",
+    description="Check OpenAI base URL configuration",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.INFO,
+)
+def check_network_openai_base_url(config: DoctorConfig) -> CheckResult:
+    """Check OpenAI base URL configuration."""
+    base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get("OPENAI_API_BASE")
+    
+    if base_url:
+        return CheckResult(
+            id="network_openai_base_url",
+            title="OpenAI Base URL",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message=f"Custom OpenAI base URL: {base_url}",
+            details="Using custom endpoint (e.g., Azure, local proxy)",
+        )
+    else:
+        return CheckResult(
+            id="network_openai_base_url",
+            title="OpenAI Base URL",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.PASS,
+            message="Using default OpenAI endpoint",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/obs_checks.py

@@ -0,0 +1,328 @@
+"""
+Observability checks for the Doctor CLI module.
+
+Validates observability provider configurations.
+"""
+
+import os
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+# Observability providers and their required env vars
+OBS_PROVIDERS = {
+    "langfuse": {
+        "env_vars": ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"],
+        "optional_vars": ["LANGFUSE_HOST"],
+        "package": "langfuse",
+    },
+    "langsmith": {
+        "env_vars": ["LANGSMITH_API_KEY"],
+        "optional_vars": ["LANGSMITH_PROJECT"],
+        "package": "langsmith",
+    },
+    "agentops": {
+        "env_vars": ["AGENTOPS_API_KEY"],
+        "optional_vars": [],
+        "package": "agentops",
+    },
+    "arize": {
+        "env_vars": ["ARIZE_API_KEY"],
+        "optional_vars": ["ARIZE_SPACE_KEY"],
+        "package": "arize",
+    },
+    "datadog": {
+        "env_vars": ["DATADOG_API_KEY"],
+        "optional_vars": ["DD_SITE"],
+        "package": "ddtrace",
+    },
+    "mlflow": {
+        "env_vars": [],
+        "optional_vars": ["MLFLOW_TRACKING_URI"],
+        "package": "mlflow",
+    },
+    "wandb": {
+        "env_vars": ["WANDB_API_KEY"],
+        "optional_vars": ["WANDB_PROJECT"],
+        "package": "wandb",
+    },
+    "braintrust": {
+        "env_vars": ["BRAINTRUST_API_KEY"],
+        "optional_vars": [],
+        "package": "braintrust",
+    },
+}
+
+
+@register_check(
+    id="obs_config",
+    title="Observability Configuration",
+    description="Check observability provider configuration",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.INFO,
+)
+def check_obs_config(config: DoctorConfig) -> CheckResult:
+    """Check observability provider configuration."""
+    configured = []
+    
+    for provider, info in OBS_PROVIDERS.items():
+        env_vars = info["env_vars"]
+        if env_vars:
+            if all(os.environ.get(var) for var in env_vars):
+                configured.append(provider)
+        else:
+            # Check optional vars for providers without required vars
+            if any(os.environ.get(var) for var in info.get("optional_vars", [])):
+                configured.append(provider)
+    
+    if configured:
+        return CheckResult(
+            id="obs_config",
+            title="Observability Configuration",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.PASS,
+            message=f"Configured provider(s): {', '.join(configured)}",
+            metadata={"providers": configured},
+        )
+    else:
+        return CheckResult(
+            id="obs_config",
+            title="Observability Configuration",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.SKIP,
+            message="No observability providers configured (optional)",
+            details="Set provider API keys to enable observability",
+        )
+
+
+@register_check(
+    id="obs_langfuse",
+    title="Langfuse",
+    description="Check Langfuse observability provider",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.LOW,
+)
+def check_obs_langfuse(config: DoctorConfig) -> CheckResult:
+    """Check Langfuse observability provider."""
+    public_key = os.environ.get("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.environ.get("LANGFUSE_SECRET_KEY")
+    
+    if public_key and secret_key:
+        try:
+            import langfuse
+            version = getattr(langfuse, "__version__", "unknown")
+            return CheckResult(
+                id="obs_langfuse",
+                title="Langfuse",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.PASS,
+                message=f"Langfuse configured (SDK {version})",
+            )
+        except ImportError:
+            return CheckResult(
+                id="obs_langfuse",
+                title="Langfuse",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.WARN,
+                message="Langfuse keys set but SDK not installed",
+                remediation="Install with: pip install langfuse",
+            )
+    else:
+        return CheckResult(
+            id="obs_langfuse",
+            title="Langfuse",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.SKIP,
+            message="Langfuse not configured (optional)",
+        )
+
+
+@register_check(
+    id="obs_langsmith",
+    title="LangSmith",
+    description="Check LangSmith observability provider",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.LOW,
+)
+def check_obs_langsmith(config: DoctorConfig) -> CheckResult:
+    """Check LangSmith observability provider."""
+    api_key = os.environ.get("LANGSMITH_API_KEY")
+    
+    if api_key:
+        try:
+            import langsmith
+            version = getattr(langsmith, "__version__", "unknown")
+            return CheckResult(
+                id="obs_langsmith",
+                title="LangSmith",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.PASS,
+                message=f"LangSmith configured (SDK {version})",
+            )
+        except ImportError:
+            return CheckResult(
+                id="obs_langsmith",
+                title="LangSmith",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.WARN,
+                message="LangSmith key set but SDK not installed",
+                remediation="Install with: pip install langsmith",
+            )
+    else:
+        return CheckResult(
+            id="obs_langsmith",
+            title="LangSmith",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.SKIP,
+            message="LangSmith not configured (optional)",
+        )
+
+
+@register_check(
+    id="obs_agentops",
+    title="AgentOps",
+    description="Check AgentOps observability provider",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.LOW,
+)
+def check_obs_agentops(config: DoctorConfig) -> CheckResult:
+    """Check AgentOps observability provider."""
+    api_key = os.environ.get("AGENTOPS_API_KEY")
+    
+    if api_key:
+        try:
+            import agentops
+            version = getattr(agentops, "__version__", "unknown")
+            return CheckResult(
+                id="obs_agentops",
+                title="AgentOps",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.PASS,
+                message=f"AgentOps configured (SDK {version})",
+            )
+        except ImportError:
+            return CheckResult(
+                id="obs_agentops",
+                title="AgentOps",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.WARN,
+                message="AgentOps key set but SDK not installed",
+                remediation="Install with: pip install agentops",
+            )
+    else:
+        return CheckResult(
+            id="obs_agentops",
+            title="AgentOps",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.SKIP,
+            message="AgentOps not configured (optional)",
+        )
+
+
+@register_check(
+    id="obs_praisonai_telemetry",
+    title="PraisonAI Telemetry",
+    description="Check PraisonAI built-in telemetry",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.INFO,
+)
+def check_obs_praisonai_telemetry(config: DoctorConfig) -> CheckResult:
+    """Check PraisonAI built-in telemetry."""
+    telemetry_enabled = os.environ.get("PRAISONAI_TELEMETRY_ENABLED", "").lower() in ("true", "1", "yes")
+    
+    try:
+        from praisonaiagents.telemetry import get_telemetry
+        
+        if telemetry_enabled:
+            return CheckResult(
+                id="obs_praisonai_telemetry",
+                title="PraisonAI Telemetry",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.PASS,
+                message="PraisonAI telemetry enabled",
+            )
+        else:
+            return CheckResult(
+                id="obs_praisonai_telemetry",
+                title="PraisonAI Telemetry",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.SKIP,
+                message="PraisonAI telemetry available but not enabled",
+                details="Set PRAISONAI_TELEMETRY_ENABLED=true to enable",
+            )
+    except ImportError:
+        return CheckResult(
+            id="obs_praisonai_telemetry",
+            title="PraisonAI Telemetry",
+            category=CheckCategory.OBSERVABILITY,
+            status=CheckStatus.SKIP,
+            message="PraisonAI telemetry module not available",
+        )
+
+
+@register_check(
+    id="obs_connectivity",
+    title="Observability Connectivity",
+    description="Test connectivity to observability providers",
+    category=CheckCategory.OBSERVABILITY,
+    severity=CheckSeverity.LOW,
+    requires_deep=True,
+)
+def check_obs_connectivity(config: DoctorConfig) -> CheckResult:
+    """Test connectivity to observability providers (deep mode)."""
+    # Only test if a specific provider is requested or if we have configured providers
+    provider = config.provider
+    
+    if provider == "langfuse":
+        public_key = os.environ.get("LANGFUSE_PUBLIC_KEY")
+        secret_key = os.environ.get("LANGFUSE_SECRET_KEY")
+        
+        if not (public_key and secret_key):
+            return CheckResult(
+                id="obs_connectivity",
+                title="Observability Connectivity",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.SKIP,
+                message="Langfuse not configured",
+            )
+        
+        try:
+            from langfuse import Langfuse
+            client = Langfuse(
+                public_key=public_key,
+                secret_key=secret_key,
+            )
+            # Try to authenticate
+            client.auth_check()
+            return CheckResult(
+                id="obs_connectivity",
+                title="Observability Connectivity",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.PASS,
+                message="Langfuse connectivity verified",
+            )
+        except Exception as e:
+            return CheckResult(
+                id="obs_connectivity",
+                title="Observability Connectivity",
+                category=CheckCategory.OBSERVABILITY,
+                status=CheckStatus.FAIL,
+                message=f"Langfuse connection failed: {type(e).__name__}",
+                details=str(e)[:200],
+            )
+    
+    # Default: skip if no specific provider requested
+    return CheckResult(
+        id="obs_connectivity",
+        title="Observability Connectivity",
+        category=CheckCategory.OBSERVABILITY,
+        status=CheckStatus.SKIP,
+        message="Use --provider to test specific provider connectivity",
+    )

src/praisonai/praisonai/cli/features/doctor/checks/performance_checks.py

@@ -0,0 +1,235 @@
+"""
+Performance checks for the Doctor CLI module.
+
+Measures import times and identifies slow imports.
+"""
+
+import sys
+import time
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _measure_import_time(module_name: str) -> tuple:
+    """Measure import time for a module."""
+    # Remove from cache if present
+    modules_before = set(sys.modules.keys())
+    
+    start = time.perf_counter()
+    try:
+        __import__(module_name)
+        elapsed = (time.perf_counter() - start) * 1000  # ms
+        return True, elapsed, None
+    except ImportError as e:
+        elapsed = (time.perf_counter() - start) * 1000
+        return False, elapsed, str(e)
+    finally:
+        # Clean up imported modules (optional, for accurate re-measurement)
+        pass
+
+
+@register_check(
+    id="performance_praisonai_import",
+    title="PraisonAI Import Time",
+    description="Measure praisonai package import time",
+    category=CheckCategory.PERFORMANCE,
+    severity=CheckSeverity.INFO,
+)
+def check_performance_praisonai_import(config: DoctorConfig) -> CheckResult:
+    """Measure praisonai package import time."""
+    budget_ms = config.budget_ms or 2000  # 2 second default budget
+    
+    # praisonai is already imported, measure a fresh import of a submodule
+    start = time.perf_counter()
+    try:
+        # Import version module (lightweight)
+        from praisonai import version
+        elapsed = (time.perf_counter() - start) * 1000
+        
+        if elapsed > budget_ms:
+            return CheckResult(
+                id="performance_praisonai_import",
+                title="PraisonAI Import Time",
+                category=CheckCategory.PERFORMANCE,
+                status=CheckStatus.WARN,
+                message=f"Import time {elapsed:.0f}ms exceeds budget {budget_ms}ms",
+                remediation="Check for slow dependencies or disk I/O issues",
+            )
+        else:
+            return CheckResult(
+                id="performance_praisonai_import",
+                title="PraisonAI Import Time",
+                category=CheckCategory.PERFORMANCE,
+                status=CheckStatus.PASS,
+                message=f"Import time: {elapsed:.0f}ms (budget: {budget_ms}ms)",
+                metadata={"import_time_ms": elapsed, "budget_ms": budget_ms},
+            )
+    except ImportError as e:
+        return CheckResult(
+            id="performance_praisonai_import",
+            title="PraisonAI Import Time",
+            category=CheckCategory.PERFORMANCE,
+            status=CheckStatus.FAIL,
+            message=f"Import failed: {e}",
+        )
+
+
+@register_check(
+    id="performance_praisonaiagents_import",
+    title="PraisonAI Agents Import Time",
+    description="Measure praisonaiagents package import time",
+    category=CheckCategory.PERFORMANCE,
+    severity=CheckSeverity.INFO,
+)
+def check_performance_praisonaiagents_import(config: DoctorConfig) -> CheckResult:
+    """Measure praisonaiagents package import time."""
+    budget_ms = config.budget_ms or 3000  # 3 second default budget
+    
+    start = time.perf_counter()
+    try:
+        import praisonaiagents
+        elapsed = (time.perf_counter() - start) * 1000
+        
+        if elapsed > budget_ms:
+            return CheckResult(
+                id="performance_praisonaiagents_import",
+                title="PraisonAI Agents Import Time",
+                category=CheckCategory.PERFORMANCE,
+                status=CheckStatus.WARN,
+                message=f"Import time {elapsed:.0f}ms exceeds budget {budget_ms}ms",
+                remediation="Check for slow dependencies",
+            )
+        else:
+            return CheckResult(
+                id="performance_praisonaiagents_import",
+                title="PraisonAI Agents Import Time",
+                category=CheckCategory.PERFORMANCE,
+                status=CheckStatus.PASS,
+                message=f"Import time: {elapsed:.0f}ms (budget: {budget_ms}ms)",
+                metadata={"import_time_ms": elapsed, "budget_ms": budget_ms},
+            )
+    except ImportError as e:
+        return CheckResult(
+            id="performance_praisonaiagents_import",
+            title="PraisonAI Agents Import Time",
+            category=CheckCategory.PERFORMANCE,
+            status=CheckStatus.FAIL,
+            message=f"Import failed: {e}",
+        )
+
+
+@register_check(
+    id="performance_slow_imports",
+    title="Slow Import Detection",
+    description="Detect slow-loading optional dependencies",
+    category=CheckCategory.PERFORMANCE,
+    severity=CheckSeverity.INFO,
+    requires_deep=True,
+)
+def check_performance_slow_imports(config: DoctorConfig) -> CheckResult:
+    """Detect slow-loading optional dependencies."""
+    modules_to_check = [
+        "litellm",
+        "chromadb",
+        "langchain",
+        "torch",
+        "transformers",
+        "pandas",
+        "numpy",
+    ]
+    
+    top_n = config.top_n or 5
+    budget_ms = config.budget_ms or 1000
+    
+    import_times = []
+    
+    for module in modules_to_check:
+        if module in sys.modules:
+            # Already imported, skip
+            continue
+        
+        success, elapsed, error = _measure_import_time(module)
+        if success:
+            import_times.append((module, elapsed))
+    
+    # Sort by time, descending
+    import_times.sort(key=lambda x: x[1], reverse=True)
+    
+    slow_imports = [(m, t) for m, t in import_times if t > budget_ms]
+    top_imports = import_times[:top_n]
+    
+    if slow_imports:
+        slow_str = ", ".join(f"{m}({t:.0f}ms)" for m, t in slow_imports[:3])
+        return CheckResult(
+            id="performance_slow_imports",
+            title="Slow Import Detection",
+            category=CheckCategory.PERFORMANCE,
+            status=CheckStatus.WARN,
+            message=f"{len(slow_imports)} slow import(s) detected",
+            details=f"Slow: {slow_str}",
+            metadata={"slow_imports": slow_imports, "top_imports": top_imports},
+        )
+    elif top_imports:
+        top_str = ", ".join(f"{m}({t:.0f}ms)" for m, t in top_imports[:3])
+        return CheckResult(
+            id="performance_slow_imports",
+            title="Slow Import Detection",
+            category=CheckCategory.PERFORMANCE,
+            status=CheckStatus.PASS,
+            message=f"No slow imports (top: {top_str})",
+            metadata={"top_imports": top_imports},
+        )
+    else:
+        return CheckResult(
+            id="performance_slow_imports",
+            title="Slow Import Detection",
+            category=CheckCategory.PERFORMANCE,
+            status=CheckStatus.SKIP,
+            message="No optional modules to measure",
+        )
+
+
+@register_check(
+    id="performance_loaded_modules",
+    title="Loaded Modules Count",
+    description="Count currently loaded Python modules",
+    category=CheckCategory.PERFORMANCE,
+    severity=CheckSeverity.INFO,
+)
+def check_performance_loaded_modules(config: DoctorConfig) -> CheckResult:
+    """Count currently loaded Python modules."""
+    module_count = len(sys.modules)
+    
+    # Categorize modules
+    stdlib_count = 0
+    third_party_count = 0
+    praison_count = 0
+    
+    for name in sys.modules:
+        if name.startswith("praisonai"):
+            praison_count += 1
+        elif "site-packages" in str(getattr(sys.modules[name], "__file__", "")):
+            third_party_count += 1
+        else:
+            stdlib_count += 1
+    
+    return CheckResult(
+        id="performance_loaded_modules",
+        title="Loaded Modules Count",
+        category=CheckCategory.PERFORMANCE,
+        status=CheckStatus.PASS,
+        message=f"{module_count} modules loaded (praison: {praison_count})",
+        metadata={
+            "total": module_count,
+            "praison": praison_count,
+            "third_party": third_party_count,
+            "stdlib": stdlib_count,
+        },
+    )

src/praisonai/praisonai/cli/features/doctor/checks/permissions_checks.py

@@ -0,0 +1,259 @@
+"""
+Permissions checks for the Doctor CLI module.
+
+Validates filesystem permissions for PraisonAI directories.
+"""
+
+import os
+import tempfile
+from pathlib import Path
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _check_dir_writable(path: Path) -> tuple:
+    """Check if a directory is writable."""
+    try:
+        if not path.exists():
+            return False, "does not exist"
+        
+        if not path.is_dir():
+            return False, "not a directory"
+        
+        # Try to create a temp file
+        test_file = path / ".praison_write_test"
+        try:
+            test_file.write_text("test")
+            test_file.unlink()
+            return True, "writable"
+        except PermissionError:
+            return False, "permission denied"
+        except Exception as e:
+            return False, str(e)
+    except Exception as e:
+        return False, str(e)
+
+
+@register_check(
+    id="permissions_home_praison",
+    title="~/.praison Directory",
+    description="Check ~/.praison directory permissions",
+    category=CheckCategory.PERMISSIONS,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_permissions_home_praison(config: DoctorConfig) -> CheckResult:
+    """Check ~/.praison directory permissions."""
+    praison_dir = Path.home() / ".praison"
+    
+    if not praison_dir.exists():
+        # Try to create it
+        try:
+            praison_dir.mkdir(parents=True, exist_ok=True)
+            return CheckResult(
+                id="permissions_home_praison",
+                title="~/.praison Directory",
+                category=CheckCategory.PERMISSIONS,
+                status=CheckStatus.PASS,
+                message="~/.praison created successfully",
+                metadata={"path": str(praison_dir)},
+            )
+        except PermissionError:
+            return CheckResult(
+                id="permissions_home_praison",
+                title="~/.praison Directory",
+                category=CheckCategory.PERMISSIONS,
+                status=CheckStatus.FAIL,
+                message="Cannot create ~/.praison directory",
+                remediation="Check home directory permissions",
+                severity=CheckSeverity.HIGH,
+            )
+    
+    writable, reason = _check_dir_writable(praison_dir)
+    
+    if writable:
+        return CheckResult(
+            id="permissions_home_praison",
+            title="~/.praison Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.PASS,
+            message=f"~/.praison is writable",
+            metadata={"path": str(praison_dir)},
+        )
+    else:
+        return CheckResult(
+            id="permissions_home_praison",
+            title="~/.praison Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.FAIL,
+            message=f"~/.praison is not writable: {reason}",
+            remediation="Fix permissions: chmod 755 ~/.praison",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="permissions_project_praison",
+    title=".praison Directory (Project)",
+    description="Check project .praison directory permissions",
+    category=CheckCategory.PERMISSIONS,
+    severity=CheckSeverity.LOW,
+)
+def check_permissions_project_praison(config: DoctorConfig) -> CheckResult:
+    """Check project .praison directory permissions."""
+    praison_dir = Path.cwd() / ".praison"
+    
+    if not praison_dir.exists():
+        return CheckResult(
+            id="permissions_project_praison",
+            title=".praison Directory (Project)",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.SKIP,
+            message="No .praison directory in current project",
+        )
+    
+    writable, reason = _check_dir_writable(praison_dir)
+    
+    if writable:
+        return CheckResult(
+            id="permissions_project_praison",
+            title=".praison Directory (Project)",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.PASS,
+            message=".praison is writable",
+            metadata={"path": str(praison_dir)},
+        )
+    else:
+        return CheckResult(
+            id="permissions_project_praison",
+            title=".praison Directory (Project)",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.WARN,
+            message=f".praison is not writable: {reason}",
+            remediation="Fix permissions or use ~/.praison instead",
+        )
+
+
+@register_check(
+    id="permissions_temp_dir",
+    title="Temp Directory",
+    description="Check temp directory permissions",
+    category=CheckCategory.PERMISSIONS,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_permissions_temp_dir(config: DoctorConfig) -> CheckResult:
+    """Check temp directory permissions."""
+    temp_dir = Path(tempfile.gettempdir())
+    
+    try:
+        # Try to create a temp file
+        with tempfile.NamedTemporaryFile(delete=True) as f:
+            f.write(b"test")
+        
+        return CheckResult(
+            id="permissions_temp_dir",
+            title="Temp Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.PASS,
+            message=f"Temp directory writable: {temp_dir}",
+            metadata={"path": str(temp_dir)},
+        )
+    except Exception as e:
+        return CheckResult(
+            id="permissions_temp_dir",
+            title="Temp Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.FAIL,
+            message=f"Temp directory not writable: {e}",
+            remediation="Check TMPDIR environment variable and permissions",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="permissions_cwd",
+    title="Current Working Directory",
+    description="Check current directory permissions",
+    category=CheckCategory.PERMISSIONS,
+    severity=CheckSeverity.INFO,
+)
+def check_permissions_cwd(config: DoctorConfig) -> CheckResult:
+    """Check current directory permissions."""
+    cwd = Path.cwd()
+    
+    writable, reason = _check_dir_writable(cwd)
+    
+    if writable:
+        return CheckResult(
+            id="permissions_cwd",
+            title="Current Working Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.PASS,
+            message=f"Current directory writable: {cwd}",
+        )
+    else:
+        return CheckResult(
+            id="permissions_cwd",
+            title="Current Working Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.WARN,
+            message=f"Current directory not writable: {reason}",
+            details="Some features may not work without write access",
+        )
+
+
+@register_check(
+    id="permissions_config_dir",
+    title="Config Directory",
+    description="Check ~/.config/praison directory",
+    category=CheckCategory.PERMISSIONS,
+    severity=CheckSeverity.LOW,
+)
+def check_permissions_config_dir(config: DoctorConfig) -> CheckResult:
+    """Check ~/.config/praison directory."""
+    config_dir = Path.home() / ".config" / "praison"
+    
+    if not config_dir.exists():
+        # Check if we can create it
+        try:
+            config_dir.mkdir(parents=True, exist_ok=True)
+            return CheckResult(
+                id="permissions_config_dir",
+                title="Config Directory",
+                category=CheckCategory.PERMISSIONS,
+                status=CheckStatus.PASS,
+                message="~/.config/praison created successfully",
+            )
+        except Exception:
+            return CheckResult(
+                id="permissions_config_dir",
+                title="Config Directory",
+                category=CheckCategory.PERMISSIONS,
+                status=CheckStatus.SKIP,
+                message="~/.config/praison does not exist (will use ~/.praison)",
+            )
+    
+    writable, reason = _check_dir_writable(config_dir)
+    
+    if writable:
+        return CheckResult(
+            id="permissions_config_dir",
+            title="Config Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.PASS,
+            message="~/.config/praison is writable",
+        )
+    else:
+        return CheckResult(
+            id="permissions_config_dir",
+            title="Config Directory",
+            category=CheckCategory.PERMISSIONS,
+            status=CheckStatus.WARN,
+            message=f"~/.config/praison not writable: {reason}",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/selftest_checks.py

@@ -0,0 +1,322 @@
+"""
+Selftest checks for the Doctor CLI module.
+
+Performs minimal agent dry-run to validate the system.
+"""
+
+import os
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+@register_check(
+    id="selftest_agent_import",
+    title="Agent Import",
+    description="Check Agent class can be imported",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.HIGH,
+)
+def check_selftest_agent_import(config: DoctorConfig) -> CheckResult:
+    """Check Agent class can be imported."""
+    try:
+        from praisonaiagents import Agent
+        return CheckResult(
+            id="selftest_agent_import",
+            title="Agent Import",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.PASS,
+            message="Agent class imported successfully",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="selftest_agent_import",
+            title="Agent Import",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message=f"Cannot import Agent: {e}",
+            remediation="Ensure praisonaiagents is properly installed",
+            severity=CheckSeverity.CRITICAL,
+        )
+
+
+@register_check(
+    id="selftest_agent_create",
+    title="Agent Creation",
+    description="Check Agent can be instantiated",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.HIGH,
+    dependencies=["selftest_agent_import"],
+)
+def check_selftest_agent_create(config: DoctorConfig) -> CheckResult:
+    """Check Agent can be instantiated."""
+    try:
+        from praisonaiagents import Agent
+        
+        # Create a minimal agent without making API calls
+        agent = Agent(
+            name="DoctorTestAgent",
+            instructions="You are a test agent.",
+            llm="gpt-4o-mini",  # Default model
+            verbose=False,
+        )
+        
+        return CheckResult(
+            id="selftest_agent_create",
+            title="Agent Creation",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.PASS,
+            message="Agent instantiated successfully",
+            metadata={"agent_name": agent.name},
+        )
+    except Exception as e:
+        return CheckResult(
+            id="selftest_agent_create",
+            title="Agent Creation",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message=f"Agent creation failed: {type(e).__name__}",
+            details=str(e)[:200],
+            remediation="Check configuration and dependencies",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="selftest_llm_config",
+    title="LLM Configuration",
+    description="Check LLM configuration is valid",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_selftest_llm_config(config: DoctorConfig) -> CheckResult:
+    """Check LLM configuration is valid."""
+    # Check for API key
+    openai_key = os.environ.get("OPENAI_API_KEY")
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+    google_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")
+    ollama_host = os.environ.get("OLLAMA_HOST")
+    
+    providers = []
+    if openai_key:
+        providers.append("OpenAI")
+    if anthropic_key:
+        providers.append("Anthropic")
+    if google_key:
+        providers.append("Google")
+    if ollama_host:
+        providers.append("Ollama")
+    
+    if providers:
+        return CheckResult(
+            id="selftest_llm_config",
+            title="LLM Configuration",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.PASS,
+            message=f"LLM provider(s) configured: {', '.join(providers)}",
+            metadata={"providers": providers},
+        )
+    else:
+        return CheckResult(
+            id="selftest_llm_config",
+            title="LLM Configuration",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message="No LLM provider configured",
+            remediation="Set OPENAI_API_KEY or another provider's API key",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="selftest_mock_chat",
+    title="Mock Chat Test",
+    description="Test agent chat with mock response",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.MEDIUM,
+    requires_deep=True,
+)
+def check_selftest_mock_chat(config: DoctorConfig) -> CheckResult:
+    """Test agent chat with mock response (no API call)."""
+    if not config.mock and not config.live:
+        # Default to mock in deep mode
+        config.mock = True
+    
+    if config.live:
+        return CheckResult(
+            id="selftest_mock_chat",
+            title="Mock Chat Test",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.SKIP,
+            message="Skipped (--live mode uses live API)",
+        )
+    
+    try:
+        # Test basic agent functionality without making API calls
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="MockTestAgent",
+            instructions="You are a test agent. Always respond with 'OK'.",
+            llm="gpt-4o-mini",
+            verbose=False,
+        )
+        
+        # Verify agent is properly configured
+        if hasattr(agent, 'name') and hasattr(agent, 'instructions'):
+            return CheckResult(
+                id="selftest_mock_chat",
+                title="Mock Chat Test",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.PASS,
+                message="Agent mock test passed",
+            )
+        else:
+            return CheckResult(
+                id="selftest_mock_chat",
+                title="Mock Chat Test",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.FAIL,
+                message="Agent missing expected attributes",
+            )
+    except Exception as e:
+        return CheckResult(
+            id="selftest_mock_chat",
+            title="Mock Chat Test",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message=f"Mock test failed: {type(e).__name__}",
+            details=str(e)[:200],
+        )
+
+
+@register_check(
+    id="selftest_live_chat",
+    title="Live Chat Test",
+    description="Test agent chat with live API call",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.LOW,
+    requires_deep=True,
+)
+def check_selftest_live_chat(config: DoctorConfig) -> CheckResult:
+    """Test agent chat with live API call."""
+    if not config.live:
+        return CheckResult(
+            id="selftest_live_chat",
+            title="Live Chat Test",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.SKIP,
+            message="Skipped (use --live to enable)",
+        )
+    
+    # Check for API key first
+    if not os.environ.get("OPENAI_API_KEY"):
+        return CheckResult(
+            id="selftest_live_chat",
+            title="Live Chat Test",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.SKIP,
+            message="Skipped (OPENAI_API_KEY not set)",
+        )
+    
+    try:
+        from praisonaiagents import Agent
+        
+        model = config.model or "gpt-4o-mini"
+        
+        agent = Agent(
+            name="LiveTestAgent",
+            instructions="You are a test agent. Respond with exactly: 'Doctor test OK'",
+            llm=model,
+            verbose=False,
+        )
+        
+        # Make a simple API call
+        response = agent.chat("Say hello")
+        
+        if response:
+            return CheckResult(
+                id="selftest_live_chat",
+                title="Live Chat Test",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.PASS,
+                message=f"Live API call successful (model: {model})",
+                metadata={"model": model, "response_length": len(str(response))},
+            )
+        else:
+            return CheckResult(
+                id="selftest_live_chat",
+                title="Live Chat Test",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.FAIL,
+                message="Live API call returned empty response",
+            )
+    except Exception as e:
+        return CheckResult(
+            id="selftest_live_chat",
+            title="Live Chat Test",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message=f"Live API call failed: {type(e).__name__}",
+            details=str(e)[:200],
+            remediation="Check API key and network connectivity",
+        )
+
+
+@register_check(
+    id="selftest_tools_wiring",
+    title="Tools Wiring",
+    description="Check tools can be wired to agent",
+    category=CheckCategory.SELFTEST,
+    severity=CheckSeverity.LOW,
+)
+def check_selftest_tools_wiring(config: DoctorConfig) -> CheckResult:
+    """Check tools can be wired to agent."""
+    try:
+        from praisonaiagents import Agent
+        
+        # Define a simple test tool
+        def test_tool(x: str) -> str:
+            """A test tool that echoes input."""
+            return f"Echo: {x}"
+        
+        agent = Agent(
+            name="ToolTestAgent",
+            instructions="You are a test agent with tools.",
+            tools=[test_tool],
+            llm="gpt-4o-mini",
+            verbose=False,
+        )
+        
+        # Check tools are registered
+        if hasattr(agent, 'tools') or hasattr(agent, '_tools'):
+            return CheckResult(
+                id="selftest_tools_wiring",
+                title="Tools Wiring",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.PASS,
+                message="Tools wired to agent successfully",
+            )
+        else:
+            return CheckResult(
+                id="selftest_tools_wiring",
+                title="Tools Wiring",
+                category=CheckCategory.SELFTEST,
+                status=CheckStatus.WARN,
+                message="Tools wiring could not be verified",
+            )
+    except Exception as e:
+        return CheckResult(
+            id="selftest_tools_wiring",
+            title="Tools Wiring",
+            category=CheckCategory.SELFTEST,
+            status=CheckStatus.FAIL,
+            message=f"Tools wiring failed: {type(e).__name__}",
+            details=str(e)[:200],
+        )

src/praisonai/praisonai/cli/features/doctor/checks/serve_checks.py

@@ -0,0 +1,426 @@
+"""
+Doctor checks for serve and endpoints functionality.
+
+Checks for:
+- Serve module availability
+- Endpoints module availability
+- Server connectivity
+- Discovery endpoint
+- Provider types
+"""
+
+import os
+
+from ..models import CheckResult, CheckStatus, CheckCategory, CheckSeverity, DoctorConfig
+from ..registry import register_check
+
+
+@register_check(
+    id="serve_module",
+    title="Serve Module",
+    description="Check if serve module is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.MEDIUM,
+    tags=["serve", "deploy"],
+)
+def check_serve_module(config: DoctorConfig) -> CheckResult:
+    """Check if serve module is available."""
+    try:
+        from praisonai.cli.features.serve import ServeHandler
+        ServeHandler()  # Test instantiation
+        return CheckResult(
+            id="serve_module",
+            title="Serve Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message="Serve module available",
+            metadata={"handler": "ServeHandler"},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="serve_module",
+            title="Serve Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message=f"Serve module not available: {e}",
+            remediation="pip install praisonai[serve]",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="serve_module",
+            title="Serve Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.ERROR,
+            message=f"Error checking serve module: {e}",
+        )
+
+
+@register_check(
+    id="endpoints_module",
+    title="Endpoints Module",
+    description="Check if endpoints module is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.MEDIUM,
+    tags=["endpoints", "deploy"],
+)
+def check_endpoints_module(config: DoctorConfig) -> CheckResult:
+    """Check if endpoints module is available."""
+    try:
+        from praisonai.endpoints import (
+            DiscoveryDocument,
+            EndpointInfo,
+            ProviderInfo,
+            list_provider_types,
+        )
+        types = list_provider_types()
+        return CheckResult(
+            id="endpoints_module",
+            title="Endpoints Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Endpoints module available ({len(types)} provider types)",
+            metadata={"provider_types": types},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="endpoints_module",
+            title="Endpoints Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message=f"Endpoints module not available: {e}",
+            remediation="pip install praisonai[serve]",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="endpoints_module",
+            title="Endpoints Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.ERROR,
+            message=f"Error checking endpoints module: {e}",
+        )
+
+
+@register_check(
+    id="endpoints_cli",
+    title="Endpoints CLI",
+    description="Check if endpoints CLI handler is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+    tags=["endpoints", "cli"],
+)
+def check_endpoints_cli(config: DoctorConfig) -> CheckResult:
+    """Check if endpoints CLI handler is available."""
+    try:
+        from praisonai.cli.features.endpoints import EndpointsHandler
+        handler = EndpointsHandler()
+        return CheckResult(
+            id="endpoints_cli",
+            title="Endpoints CLI",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message="Endpoints CLI handler available",
+            metadata={"default_url": handler.DEFAULT_URL},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="endpoints_cli",
+            title="Endpoints CLI",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message=f"Endpoints CLI not available: {e}",
+            remediation="pip install praisonai",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="endpoints_cli",
+            title="Endpoints CLI",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.ERROR,
+            message=f"Error checking endpoints CLI: {e}",
+        )
+
+
+@register_check(
+    id="server_connectivity",
+    title="Server Connectivity",
+    description="Check if a PraisonAI server is reachable",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.LOW,
+    requires_deep=True,
+    tags=["serve", "network"],
+)
+def check_server_connectivity(config: DoctorConfig) -> CheckResult:
+    """Check if a PraisonAI server is reachable."""
+    import urllib.request
+    import urllib.error
+    
+    url = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+    health_url = f"{url}/health"
+    
+    try:
+        req = urllib.request.Request(health_url, method="GET")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            if resp.status == 200:
+                return CheckResult(
+                    id="server_connectivity",
+                    title="Server Connectivity",
+                    category=CheckCategory.NETWORK,
+                    status=CheckStatus.PASS,
+                    message=f"Server reachable at {url}",
+                    metadata={"url": url, "status": resp.status},
+                )
+            else:
+                return CheckResult(
+                    id="server_connectivity",
+                    title="Server Connectivity",
+                    category=CheckCategory.NETWORK,
+                    status=CheckStatus.WARN,
+                    message=f"Server returned status {resp.status}",
+                    metadata={"url": url, "status": resp.status},
+                )
+    except urllib.error.URLError as e:
+        return CheckResult(
+            id="server_connectivity",
+            title="Server Connectivity",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.SKIP,
+            message=f"No server running at {url}",
+            details=str(e.reason),
+            remediation="Start a server: praisonai serve unified --port 8765",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="server_connectivity",
+            title="Server Connectivity",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.ERROR,
+            message=f"Error checking server: {e}",
+        )
+
+
+@register_check(
+    id="discovery_endpoint",
+    title="Discovery Endpoint",
+    description="Check if discovery endpoint is available",
+    category=CheckCategory.NETWORK,
+    severity=CheckSeverity.LOW,
+    requires_deep=True,
+    dependencies=["server_connectivity"],
+    tags=["serve", "discovery"],
+)
+def check_discovery_endpoint(config: DoctorConfig) -> CheckResult:
+    """Check if discovery endpoint is available."""
+    import urllib.request
+    import urllib.error
+    import json
+    
+    url = os.environ.get("PRAISONAI_ENDPOINTS_URL", "http://localhost:8765")
+    discovery_url = f"{url}/__praisonai__/discovery"
+    
+    try:
+        req = urllib.request.Request(discovery_url, method="GET")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            if resp.status == 200:
+                data = json.loads(resp.read().decode())
+                providers = data.get("providers", [])
+                endpoints = data.get("endpoints", [])
+                return CheckResult(
+                    id="discovery_endpoint",
+                    title="Discovery Endpoint",
+                    category=CheckCategory.NETWORK,
+                    status=CheckStatus.PASS,
+                    message=f"Discovery available: {len(providers)} providers, {len(endpoints)} endpoints",
+                    metadata={
+                        "url": discovery_url,
+                        "schema_version": data.get("schema_version"),
+                        "server_name": data.get("server_name"),
+                        "providers": [p.get("type") for p in providers],
+                    },
+                )
+            else:
+                return CheckResult(
+                    id="discovery_endpoint",
+                    title="Discovery Endpoint",
+                    category=CheckCategory.NETWORK,
+                    status=CheckStatus.WARN,
+                    message=f"Discovery returned status {resp.status}",
+                )
+    except urllib.error.URLError:
+        return CheckResult(
+            id="discovery_endpoint",
+            title="Discovery Endpoint",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.SKIP,
+            message="No server running (skipped)",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="discovery_endpoint",
+            title="Discovery Endpoint",
+            category=CheckCategory.NETWORK,
+            status=CheckStatus.ERROR,
+            message=f"Error checking discovery: {e}",
+        )
+
+
+@register_check(
+    id="a2u_module",
+    title="A2U Module",
+    description="Check if A2U server module is available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+    tags=["serve", "a2u"],
+)
+def check_a2u_module(config: DoctorConfig) -> CheckResult:
+    """Check if A2U server module is available."""
+    try:
+        from praisonai.endpoints.a2u_server import (
+            A2UEvent,
+            A2USubscription,
+            A2UEventBus,
+            create_a2u_routes,
+        )
+        return CheckResult(
+            id="a2u_module",
+            title="A2U Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message="A2U server module available",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="a2u_module",
+            title="A2U Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message=f"A2U module not available: {e}",
+            remediation="pip install praisonai[serve]",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="a2u_module",
+            title="A2U Module",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.ERROR,
+            message=f"Error checking A2U module: {e}",
+        )
+
+
+@register_check(
+    id="provider_adapters",
+    title="Provider Adapters",
+    description="Check if all provider adapters are available",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.LOW,
+    tags=["serve", "providers"],
+)
+def check_provider_adapters(config: DoctorConfig) -> CheckResult:
+    """Check if all provider adapters are available."""
+    try:
+        from praisonai.endpoints.providers import (
+            BaseProvider,
+            RecipeProvider,
+            AgentsAPIProvider,
+            MCPProvider,
+            ToolsMCPProvider,
+            A2AProvider,
+            A2UProvider,
+        )
+        providers = [
+            "BaseProvider",
+            "RecipeProvider",
+            "AgentsAPIProvider",
+            "MCPProvider",
+            "ToolsMCPProvider",
+            "A2AProvider",
+            "A2UProvider",
+        ]
+        return CheckResult(
+            id="provider_adapters",
+            title="Provider Adapters",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"All {len(providers)} provider adapters available",
+            metadata={"providers": providers},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="provider_adapters",
+            title="Provider Adapters",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message=f"Some provider adapters not available: {e}",
+            remediation="pip install praisonai[serve]",
+        )
+    except Exception as e:
+        return CheckResult(
+            id="provider_adapters",
+            title="Provider Adapters",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.ERROR,
+            message=f"Error checking provider adapters: {e}",
+        )
+
+
+@register_check(
+    id="fastapi_available",
+    title="FastAPI Available",
+    description="Check if FastAPI is available for serving",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.MEDIUM,
+    tags=["serve", "dependencies"],
+)
+def check_fastapi_available(config: DoctorConfig) -> CheckResult:
+    """Check if FastAPI is available."""
+    try:
+        import fastapi
+        version = getattr(fastapi, "__version__", "unknown")
+        return CheckResult(
+            id="fastapi_available",
+            title="FastAPI Available",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"FastAPI {version} available",
+            metadata={"version": version},
+        )
+    except ImportError:
+        return CheckResult(
+            id="fastapi_available",
+            title="FastAPI Available",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="FastAPI not installed",
+            remediation="pip install fastapi uvicorn",
+        )
+
+
+@register_check(
+    id="uvicorn_available",
+    title="Uvicorn Available",
+    description="Check if Uvicorn is available for serving",
+    category=CheckCategory.ENVIRONMENT,
+    severity=CheckSeverity.MEDIUM,
+    tags=["serve", "dependencies"],
+)
+def check_uvicorn_available(config: DoctorConfig) -> CheckResult:
+    """Check if Uvicorn is available."""
+    try:
+        import uvicorn
+        version = getattr(uvicorn, "__version__", "unknown")
+        return CheckResult(
+            id="uvicorn_available",
+            title="Uvicorn Available",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.PASS,
+            message=f"Uvicorn {version} available",
+            metadata={"version": version},
+        )
+    except ImportError:
+        return CheckResult(
+            id="uvicorn_available",
+            title="Uvicorn Available",
+            category=CheckCategory.ENVIRONMENT,
+            status=CheckStatus.WARN,
+            message="Uvicorn not installed",
+            remediation="pip install uvicorn",
+        )

src/praisonai/praisonai/cli/features/doctor/checks/skills_checks.py

@@ -0,0 +1,231 @@
+"""
+Skills checks for the Doctor CLI module.
+
+Validates Agent Skills configurations and manifests.
+"""
+
+from pathlib import Path
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+def _find_skills_dirs() -> list:
+    """Find skills directories."""
+    locations = [
+        Path.cwd() / ".praison" / "skills",
+        Path.cwd() / ".claude" / "skills",
+        Path.home() / ".praison" / "skills",
+        Path.home() / ".config" / "praison" / "skills",
+    ]
+    
+    found = []
+    for loc in locations:
+        if loc.exists() and loc.is_dir():
+            found.append(str(loc))
+    
+    return found
+
+
+def _validate_skill_dir(skill_path: Path) -> dict:
+    """Validate a single skill directory."""
+    result = {"valid": False, "errors": [], "warnings": []}
+    
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        result["errors"].append("Missing SKILL.md")
+        return result
+    
+    try:
+        content = skill_md.read_text()
+        
+        # Check for YAML frontmatter
+        if not content.startswith("---"):
+            result["errors"].append("SKILL.md missing YAML frontmatter")
+            return result
+        
+        # Parse frontmatter
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            result["errors"].append("Invalid YAML frontmatter format")
+            return result
+        
+        try:
+            import yaml
+            frontmatter = yaml.safe_load(parts[1])
+            
+            # Check required fields
+            if not frontmatter.get("name"):
+                result["errors"].append("Missing 'name' in frontmatter")
+            if not frontmatter.get("description"):
+                result["errors"].append("Missing 'description' in frontmatter")
+            
+            # Check name format
+            name = frontmatter.get("name", "")
+            if name and not name.replace("-", "").replace("_", "").isalnum():
+                result["warnings"].append(f"Name '{name}' should be alphanumeric with hyphens")
+            
+            if not result["errors"]:
+                result["valid"] = True
+                result["name"] = name
+                result["description"] = frontmatter.get("description", "")[:100]
+            
+        except Exception as e:
+            result["errors"].append(f"YAML parse error: {e}")
+    
+    except Exception as e:
+        result["errors"].append(f"Cannot read SKILL.md: {e}")
+    
+    return result
+
+
+@register_check(
+    id="skills_dirs",
+    title="Skills Directories",
+    description="Check for skills directories",
+    category=CheckCategory.SKILLS,
+    severity=CheckSeverity.INFO,
+)
+def check_skills_dirs(config: DoctorConfig) -> CheckResult:
+    """Check for skills directories."""
+    dirs = _find_skills_dirs()
+    
+    if config.path:
+        # Check specific path
+        path = Path(config.path)
+        if path.exists():
+            dirs = [str(path)]
+        else:
+            return CheckResult(
+                id="skills_dirs",
+                title="Skills Directories",
+                category=CheckCategory.SKILLS,
+                status=CheckStatus.FAIL,
+                message=f"Specified path not found: {config.path}",
+            )
+    
+    if dirs:
+        return CheckResult(
+            id="skills_dirs",
+            title="Skills Directories",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.PASS,
+            message=f"Found {len(dirs)} skills directory(ies)",
+            details=", ".join(dirs),
+            metadata={"directories": dirs},
+        )
+    else:
+        return CheckResult(
+            id="skills_dirs",
+            title="Skills Directories",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.SKIP,
+            message="No skills directories found (optional)",
+            details="Create .praison/skills/ to add agent skills",
+        )
+
+
+@register_check(
+    id="skills_valid",
+    title="Skills Validation",
+    description="Validate installed skills",
+    category=CheckCategory.SKILLS,
+    severity=CheckSeverity.MEDIUM,
+    dependencies=["skills_dirs"],
+)
+def check_skills_valid(config: DoctorConfig) -> CheckResult:
+    """Validate installed skills."""
+    dirs = _find_skills_dirs()
+    
+    if config.path:
+        path = Path(config.path)
+        if path.exists():
+            dirs = [str(path)]
+    
+    if not dirs:
+        return CheckResult(
+            id="skills_valid",
+            title="Skills Validation",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.SKIP,
+            message="No skills to validate",
+        )
+    
+    valid_skills = []
+    invalid_skills = []
+    
+    for dir_path in dirs:
+        skills_dir = Path(dir_path)
+        for skill_path in skills_dir.iterdir():
+            if skill_path.is_dir() and not skill_path.name.startswith("."):
+                result = _validate_skill_dir(skill_path)
+                if result["valid"]:
+                    valid_skills.append(result.get("name", skill_path.name))
+                else:
+                    invalid_skills.append(f"{skill_path.name}: {'; '.join(result['errors'])}")
+    
+    total = len(valid_skills) + len(invalid_skills)
+    
+    if total == 0:
+        return CheckResult(
+            id="skills_valid",
+            title="Skills Validation",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.SKIP,
+            message="No skills found in directories",
+        )
+    
+    if invalid_skills:
+        return CheckResult(
+            id="skills_valid",
+            title="Skills Validation",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.WARN,
+            message=f"{len(valid_skills)}/{total} skills valid",
+            details="; ".join(invalid_skills[:3]) + ("..." if len(invalid_skills) > 3 else ""),
+            metadata={"valid": valid_skills, "invalid": invalid_skills},
+        )
+    else:
+        return CheckResult(
+            id="skills_valid",
+            title="Skills Validation",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.PASS,
+            message=f"All {total} skill(s) valid",
+            metadata={"valid": valid_skills},
+        )
+
+
+@register_check(
+    id="skills_praisonai_integration",
+    title="PraisonAI Skills Integration",
+    description="Check PraisonAI skills module",
+    category=CheckCategory.SKILLS,
+    severity=CheckSeverity.LOW,
+)
+def check_skills_praisonai_integration(config: DoctorConfig) -> CheckResult:
+    """Check PraisonAI skills module."""
+    try:
+        from praisonaiagents.skills import SkillManager
+        return CheckResult(
+            id="skills_praisonai_integration",
+            title="PraisonAI Skills Integration",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.PASS,
+            message="PraisonAI skills module available",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="skills_praisonai_integration",
+            title="PraisonAI Skills Integration",
+            category=CheckCategory.SKILLS,
+            status=CheckStatus.SKIP,
+            message="Skills module not available",
+            details=str(e),
+        )

src/praisonai/praisonai/cli/features/doctor/checks/tools_checks.py

@@ -0,0 +1,371 @@
+"""
+Tools checks for the Doctor CLI module.
+
+Validates tool availability, dependencies, and API keys.
+"""
+
+import os
+
+from ..models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+)
+from ..registry import register_check
+
+
+# Tool categories and their requirements
+TOOL_CATEGORIES = {
+    "web_search": {
+        "tools": ["internet_search", "duckduckgo", "tavily_search", "exa_search", "searxng_search"],
+        "description": "Web search tools",
+    },
+    "file_ops": {
+        "tools": ["read_file", "write_file", "list_files", "file_tools"],
+        "description": "File operation tools",
+    },
+    "data": {
+        "tools": ["csv_tools", "json_tools", "excel_tools", "xml_tools", "yaml_tools", "pandas_tools"],
+        "description": "Data processing tools",
+    },
+    "database": {
+        "tools": ["duckdb_tools", "mongodb_tools"],
+        "description": "Database tools",
+    },
+    "code": {
+        "tools": ["python_tools", "shell_tools", "execute_code"],
+        "description": "Code execution tools",
+    },
+    "web_crawl": {
+        "tools": ["crawl4ai", "spider_tools", "newspaper_tools"],
+        "description": "Web crawling tools",
+    },
+    "knowledge": {
+        "tools": ["wiki_search", "arxiv_tools", "wikipedia_tools"],
+        "description": "Knowledge/research tools",
+    },
+    "finance": {
+        "tools": ["yfinance", "get_stock_price", "get_stock_info"],
+        "description": "Financial data tools",
+    },
+}
+
+# Tools that require API keys
+TOOLS_REQUIRING_API_KEYS = {
+    "tavily_search": "TAVILY_API_KEY",
+    "tavily": "TAVILY_API_KEY",
+    "exa_search": "EXA_API_KEY",
+    "exa": "EXA_API_KEY",
+    "ydc_search": "YDC_API_KEY",
+    "ydc": "YDC_API_KEY",
+}
+
+# Tools that require optional dependencies
+TOOLS_REQUIRING_DEPS = {
+    "crawl4ai": "crawl4ai",
+    "tavily_search": "tavily",
+    "tavily": "tavily",
+    "pandas_tools": "pandas",
+    "excel_tools": "openpyxl",
+    "yfinance": "yfinance",
+    "duckdb_tools": "duckdb",
+    "mongodb_tools": "pymongo",
+    "newspaper_tools": "newspaper3k",
+    "arxiv_tools": "arxiv",
+}
+
+
+@register_check(
+    id="tools_registry",
+    title="Tools Registry",
+    description="Check tool registry is accessible",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_tools_registry(config: DoctorConfig) -> CheckResult:
+    """Check tool registry is accessible."""
+    try:
+        from praisonaiagents.tools import TOOL_MAPPINGS
+        tool_count = len(TOOL_MAPPINGS)
+        
+        return CheckResult(
+            id="tools_registry",
+            title="Tools Registry",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message=f"Tool registry accessible with {tool_count} tools",
+            metadata={"tool_count": tool_count},
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="tools_registry",
+            title="Tools Registry",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.FAIL,
+            message="Cannot access tool registry",
+            details=str(e),
+            remediation="Ensure praisonaiagents is properly installed",
+            severity=CheckSeverity.HIGH,
+        )
+
+
+@register_check(
+    id="tools_web_search",
+    title="Web Search Tools",
+    description="Check web search tool availability",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.MEDIUM,
+)
+def check_tools_web_search(config: DoctorConfig) -> CheckResult:
+    """Check web search tool availability."""
+    available = []
+    missing = []
+    
+    # Check DuckDuckGo (no API key required)
+    try:
+        from praisonaiagents.tools import internet_search
+        available.append("internet_search (DuckDuckGo)")
+    except ImportError:
+        missing.append("internet_search")
+    
+    # Check Tavily
+    if os.environ.get("TAVILY_API_KEY"):
+        try:
+            from praisonaiagents.tools import tavily_search
+            available.append("tavily_search")
+        except ImportError:
+            missing.append("tavily_search (missing tavily package)")
+    else:
+        missing.append("tavily_search (TAVILY_API_KEY not set)")
+    
+    # Check Exa
+    if os.environ.get("EXA_API_KEY"):
+        try:
+            from praisonaiagents.tools import exa_search
+            available.append("exa_search")
+        except ImportError:
+            missing.append("exa_search (missing exa package)")
+    else:
+        missing.append("exa_search (EXA_API_KEY not set)")
+    
+    if available:
+        return CheckResult(
+            id="tools_web_search",
+            title="Web Search Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message=f"{len(available)} web search tool(s) available",
+            details=", ".join(available),
+            metadata={"available": available, "missing": missing},
+        )
+    else:
+        return CheckResult(
+            id="tools_web_search",
+            title="Web Search Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.WARN,
+            message="No web search tools available",
+            details=", ".join(missing),
+            remediation="Install duckduckgo-search or set TAVILY_API_KEY",
+        )
+
+
+@register_check(
+    id="tools_file_ops",
+    title="File Operation Tools",
+    description="Check file operation tool availability",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.LOW,
+)
+def check_tools_file_ops(config: DoctorConfig) -> CheckResult:
+    """Check file operation tool availability."""
+    try:
+        from praisonaiagents.tools import read_file, write_file, list_files
+        return CheckResult(
+            id="tools_file_ops",
+            title="File Operation Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message="File operation tools available (read_file, write_file, list_files)",
+        )
+    except ImportError as e:
+        return CheckResult(
+            id="tools_file_ops",
+            title="File Operation Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.WARN,
+            message="Some file operation tools not available",
+            details=str(e),
+        )
+
+
+@register_check(
+    id="tools_code_execution",
+    title="Code Execution Tools",
+    description="Check code execution tool availability",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.LOW,
+)
+def check_tools_code_execution(config: DoctorConfig) -> CheckResult:
+    """Check code execution tool availability."""
+    available = []
+    
+    try:
+        from praisonaiagents.tools import execute_code
+        available.append("execute_code")
+    except ImportError:
+        pass
+    
+    try:
+        from praisonaiagents.tools import execute_command
+        available.append("execute_command")
+    except ImportError:
+        pass
+    
+    if available:
+        return CheckResult(
+            id="tools_code_execution",
+            title="Code Execution Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message=f"Code execution tools available: {', '.join(available)}",
+            metadata={"available": available},
+        )
+    else:
+        return CheckResult(
+            id="tools_code_execution",
+            title="Code Execution Tools",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.SKIP,
+            message="Code execution tools not loaded (optional)",
+        )
+
+
+@register_check(
+    id="tools_api_keys",
+    title="Tool API Keys",
+    description="Check API keys for tools that require them",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.INFO,
+)
+def check_tools_api_keys(config: DoctorConfig) -> CheckResult:
+    """Check API keys for tools that require them."""
+    configured = []
+    missing = []
+    
+    api_keys = {
+        "TAVILY_API_KEY": "Tavily search",
+        "EXA_API_KEY": "Exa search",
+        "YDC_API_KEY": "You.com search",
+        "SPIDER_API_KEY": "Spider web crawling",
+    }
+    
+    for key, description in api_keys.items():
+        if os.environ.get(key):
+            configured.append(description)
+        else:
+            missing.append(f"{description} ({key})")
+    
+    if configured:
+        return CheckResult(
+            id="tools_api_keys",
+            title="Tool API Keys",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message=f"{len(configured)} tool API key(s) configured",
+            details=f"Configured: {', '.join(configured)}",
+            metadata={"configured": configured, "missing": missing},
+        )
+    else:
+        return CheckResult(
+            id="tools_api_keys",
+            title="Tool API Keys",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.SKIP,
+            message="No optional tool API keys configured",
+            details="Tools like Tavily, Exa require API keys for enhanced functionality",
+        )
+
+
+@register_check(
+    id="tools_optional_deps",
+    title="Tool Optional Dependencies",
+    description="Check optional dependencies for tools",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.INFO,
+    requires_deep=True,
+)
+def check_tools_optional_deps(config: DoctorConfig) -> CheckResult:
+    """Check optional dependencies for tools."""
+    available = []
+    missing = []
+    
+    deps_to_check = [
+        ("crawl4ai", "Crawl4AI web crawling"),
+        ("tavily", "Tavily search"),
+        ("pandas", "Pandas data tools"),
+        ("openpyxl", "Excel tools"),
+        ("yfinance", "Yahoo Finance tools"),
+        ("duckdb", "DuckDB tools"),
+        ("pymongo", "MongoDB tools"),
+        ("arxiv", "arXiv tools"),
+    ]
+    
+    for package, description in deps_to_check:
+        try:
+            __import__(package)
+            available.append(description)
+        except ImportError:
+            missing.append(f"{description} ({package})")
+    
+    total = len(deps_to_check)
+    
+    return CheckResult(
+        id="tools_optional_deps",
+        title="Tool Optional Dependencies",
+        category=CheckCategory.TOOLS,
+        status=CheckStatus.PASS,
+        message=f"{len(available)}/{total} optional tool dependencies installed",
+        details=f"Missing: {', '.join(missing[:3])}{'...' if len(missing) > 3 else ''}" if missing else "All installed",
+        metadata={"available": available, "missing": missing},
+    )
+
+
+@register_check(
+    id="tools_summary",
+    title="Tools Summary",
+    description="Summary of tool availability by category",
+    category=CheckCategory.TOOLS,
+    severity=CheckSeverity.INFO,
+)
+def check_tools_summary(config: DoctorConfig) -> CheckResult:
+    """Summary of tool availability by category."""
+    try:
+        from praisonaiagents.tools import TOOL_MAPPINGS
+        
+        category_counts = {}
+        for cat_name, cat_info in TOOL_CATEGORIES.items():
+            available = sum(1 for t in cat_info["tools"] if t in TOOL_MAPPINGS)
+            total = len(cat_info["tools"])
+            category_counts[cat_name] = f"{available}/{total}"
+        
+        summary = ", ".join(f"{k}: {v}" for k, v in category_counts.items())
+        
+        return CheckResult(
+            id="tools_summary",
+            title="Tools Summary",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.PASS,
+            message=f"Tool categories: {summary}",
+            metadata={"categories": category_counts},
+        )
+    except ImportError:
+        return CheckResult(
+            id="tools_summary",
+            title="Tools Summary",
+            category=CheckCategory.TOOLS,
+            status=CheckStatus.SKIP,
+            message="Cannot generate tools summary",
+        )

src/praisonai/praisonai/cli/features/doctor/engine.py

@@ -0,0 +1,266 @@
+"""
+Doctor engine for executing health checks.
+
+Provides the core execution logic for running doctor checks.
+"""
+
+import os
+import platform
+import sys
+import traceback
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+from datetime import datetime, timezone
+from typing import Callable, List, Optional
+import time
+
+from .models import (
+    CheckCategory,
+    CheckResult,
+    CheckStatus,
+    CheckSeverity,
+    DoctorConfig,
+    DoctorReport,
+    EnvironmentSummary,
+)
+from .registry import CheckRegistry, get_registry
+
+
+class DoctorEngine:
+    """
+    Engine for executing doctor checks.
+    
+    Handles check execution, timeout management, and report generation.
+    """
+    
+    def __init__(self, config: Optional[DoctorConfig] = None):
+        """
+        Initialize the doctor engine.
+        
+        Args:
+            config: Doctor configuration
+        """
+        self.config = config or DoctorConfig()
+        self.registry = get_registry()
+        self._results: List[CheckResult] = []
+    
+    def get_environment_summary(self) -> EnvironmentSummary:
+        """Gather environment information."""
+        # Get package versions lazily
+        praisonai_version = "unknown"
+        praisonaiagents_version = "unknown"
+        
+        try:
+            from praisonai.version import __version__ as pai_version
+            praisonai_version = pai_version
+        except ImportError:
+            pass
+        
+        try:
+            import praisonaiagents
+            praisonaiagents_version = getattr(praisonaiagents, "__version__", "unknown")
+        except ImportError:
+            pass
+        
+        return EnvironmentSummary(
+            python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            python_executable=sys.executable,
+            os_name=platform.system(),
+            os_version=platform.release(),
+            architecture=platform.machine(),
+            praisonai_version=praisonai_version,
+            praisonaiagents_version=praisonaiagents_version,
+            working_directory=os.getcwd(),
+            virtual_env=os.environ.get("VIRTUAL_ENV"),
+        )
+    
+    def run_check(
+        self,
+        check_id: str,
+        implementation: Callable,
+        timeout: Optional[float] = None,
+    ) -> CheckResult:
+        """
+        Run a single check with timeout handling.
+        
+        Args:
+            check_id: Check identifier
+            implementation: Check function
+            timeout: Timeout in seconds
+            
+        Returns:
+            Check result
+        """
+        timeout = timeout or self.config.timeout
+        definition = self.registry.get_check(check_id)
+        
+        start_time = time.time()
+        
+        try:
+            # Run with timeout using ThreadPoolExecutor
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(implementation, self.config)
+                try:
+                    result = future.result(timeout=timeout)
+                    result.duration_ms = (time.time() - start_time) * 1000
+                    return result
+                except FuturesTimeoutError:
+                    return CheckResult(
+                        id=check_id,
+                        title=definition.title if definition else check_id,
+                        category=definition.category if definition else CheckCategory.ENVIRONMENT,
+                        status=CheckStatus.ERROR,
+                        message=f"Check timed out after {timeout}s",
+                        remediation="Increase timeout with --timeout or check for hanging operations",
+                        duration_ms=(time.time() - start_time) * 1000,
+                        severity=CheckSeverity.HIGH,
+                    )
+        except Exception as e:
+            # Capture exception details but redact potential secrets
+            tb = traceback.format_exc()
+            return CheckResult(
+                id=check_id,
+                title=definition.title if definition else check_id,
+                category=definition.category if definition else CheckCategory.ENVIRONMENT,
+                status=CheckStatus.ERROR,
+                message=f"Check failed with error: {type(e).__name__}: {str(e)[:100]}",
+                details=tb[:500] if not self.config.quiet else None,
+                remediation="Check the error details and fix the underlying issue",
+                duration_ms=(time.time() - start_time) * 1000,
+                severity=CheckSeverity.HIGH,
+            )
+    
+    def run_checks(
+        self,
+        check_ids: Optional[List[str]] = None,
+        categories: Optional[List[CheckCategory]] = None,
+    ) -> List[CheckResult]:
+        """
+        Run multiple checks.
+        
+        Args:
+            check_ids: Specific check IDs to run (None = all)
+            categories: Filter by categories
+            
+        Returns:
+            List of check results
+        """
+        # Get filtered checks
+        checks = self.registry.filter_checks(
+            only=check_ids or self.config.only or None,
+            skip=self.config.skip or None,
+            categories=categories,
+            deep_mode=self.config.deep,
+        )
+        
+        # Resolve dependencies and get ordered list
+        ordered_ids = self.registry.resolve_dependencies([c.id for c in checks])
+        
+        results = []
+        failed_deps = set()
+        
+        for check_id in ordered_ids:
+            definition = self.registry.get_check(check_id)
+            implementation = self.registry.get_implementation(check_id)
+            
+            if not definition or not implementation:
+                continue
+            
+            # Check if dependencies failed
+            if any(dep in failed_deps for dep in definition.dependencies):
+                results.append(CheckResult(
+                    id=check_id,
+                    title=definition.title,
+                    category=definition.category,
+                    status=CheckStatus.SKIP,
+                    message="Skipped due to failed dependency",
+                    severity=definition.severity,
+                ))
+                continue
+            
+            # Run the check
+            result = self.run_check(check_id, implementation)
+            results.append(result)
+            
+            # Track failures for dependency resolution
+            if result.status in (CheckStatus.FAIL, CheckStatus.ERROR):
+                failed_deps.add(check_id)
+                
+                # Fail fast if configured
+                if self.config.fail_fast:
+                    break
+        
+        self._results = results
+        return results
+    
+    def generate_report(self, results: Optional[List[CheckResult]] = None) -> DoctorReport:
+        """
+        Generate a complete doctor report.
+        
+        Args:
+            results: Check results (uses stored results if None)
+            
+        Returns:
+            Complete doctor report
+        """
+        results = results or self._results
+        
+        report = DoctorReport(
+            version="1.0.0",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            environment=self.get_environment_summary(),
+            results=results,
+            mode="deep" if self.config.deep else "fast",
+            filters={
+                "only": self.config.only,
+                "skip": self.config.skip,
+            },
+        )
+        
+        report.calculate_summary()
+        report.exit_code = report.calculate_exit_code(strict=self.config.strict)
+        
+        return report
+    
+    def run(
+        self,
+        check_ids: Optional[List[str]] = None,
+        categories: Optional[List[CheckCategory]] = None,
+    ) -> DoctorReport:
+        """
+        Run checks and generate report.
+        
+        Args:
+            check_ids: Specific check IDs to run
+            categories: Filter by categories
+            
+        Returns:
+            Complete doctor report
+        """
+        start_time = time.time()
+        
+        results = self.run_checks(check_ids, categories)
+        report = self.generate_report(results)
+        
+        report.duration_ms = (time.time() - start_time) * 1000
+        
+        return report
+
+
+def run_doctor(
+    config: Optional[DoctorConfig] = None,
+    check_ids: Optional[List[str]] = None,
+    categories: Optional[List[CheckCategory]] = None,
+) -> DoctorReport:
+    """
+    Convenience function to run doctor checks.
+    
+    Args:
+        config: Doctor configuration
+        check_ids: Specific check IDs to run
+        categories: Filter by categories
+        
+    Returns:
+        Complete doctor report
+    """
+    engine = DoctorEngine(config)
+    return engine.run(check_ids, categories)

src/praisonai/praisonai/cli/features/doctor/formatters.py

@@ -0,0 +1,310 @@
+"""
+Output formatters for the Doctor CLI module.
+
+Provides text and JSON formatting with secret redaction.
+"""
+
+import json
+import re
+import sys
+from typing import Any, Dict, List, Optional, TextIO
+from .models import CheckResult, CheckStatus, DoctorReport, ReportSummary
+
+
+# Patterns for detecting secrets
+SECRET_PATTERNS = [
+    re.compile(r'(sk-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # OpenAI
+    re.compile(r'(sk-ant-[a-zA-Z0-9-]{20,})', re.IGNORECASE),  # Anthropic
+    re.compile(r'(AIza[a-zA-Z0-9_-]{35})', re.IGNORECASE),  # Google
+    re.compile(r'(tvly-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # Tavily
+    re.compile(r'(xai-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # xAI
+    re.compile(r'([a-zA-Z0-9_-]*api[_-]?key[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'([a-zA-Z0-9_-]*token[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'([a-zA-Z0-9_-]*secret[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'(password\s*=\s*["\']?[^\s"\']{8,})', re.IGNORECASE),
+]
+
+# Known API key environment variable names
+API_KEY_ENV_VARS = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_API_KEY",
+    "GEMINI_API_KEY",
+    "TAVILY_API_KEY",
+    "EXA_API_KEY",
+    "COHERE_API_KEY",
+    "HUGGINGFACE_API_KEY",
+    "HF_TOKEN",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGSMITH_API_KEY",
+    "AGENTOPS_API_KEY",
+    "WANDB_API_KEY",
+    "DATADOG_API_KEY",
+    "BRAINTRUST_API_KEY",
+    "YDC_API_KEY",
+]
+
+
+def redact_secrets(text: str, show_prefix_suffix: bool = False) -> str:
+    """
+    Redact secrets from text.
+    
+    Args:
+        text: Text to redact
+        show_prefix_suffix: If True, show first 4 and last 4 chars
+        
+    Returns:
+        Text with secrets redacted
+    """
+    if not text:
+        return text
+    
+    result = text
+    
+    for pattern in SECRET_PATTERNS:
+        def replace_match(match):
+            secret = match.group(1)
+            if show_prefix_suffix and len(secret) > 12:
+                return f"{secret[:4]}...{secret[-4:]}"
+            return "***REDACTED***"
+        result = pattern.sub(replace_match, result)
+    
+    return result
+
+
+def redact_dict(data: Dict[str, Any], show_prefix_suffix: bool = False) -> Dict[str, Any]:
+    """
+    Recursively redact secrets from a dictionary.
+    
+    Args:
+        data: Dictionary to redact
+        show_prefix_suffix: If True, show first 4 and last 4 chars
+        
+    Returns:
+        Dictionary with secrets redacted
+    """
+    result = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            # Check if key suggests it's a secret
+            key_lower = key.lower()
+            if any(s in key_lower for s in ["key", "token", "secret", "password", "credential"]):
+                if show_prefix_suffix and len(value) > 12:
+                    result[key] = f"{value[:4]}...{value[-4:]}"
+                else:
+                    result[key] = "***REDACTED***"
+            else:
+                result[key] = redact_secrets(value, show_prefix_suffix)
+        elif isinstance(value, dict):
+            result[key] = redact_dict(value, show_prefix_suffix)
+        elif isinstance(value, list):
+            result[key] = [
+                redact_dict(v, show_prefix_suffix) if isinstance(v, dict)
+                else redact_secrets(v, show_prefix_suffix) if isinstance(v, str)
+                else v
+                for v in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+class BaseFormatter:
+    """Base class for output formatters."""
+    
+    def __init__(
+        self,
+        no_color: bool = False,
+        quiet: bool = False,
+        redact: bool = True,
+        show_prefix_suffix: bool = False,
+    ):
+        self.no_color = no_color or not sys.stdout.isatty()
+        self.quiet = quiet
+        self.redact = redact
+        self.show_prefix_suffix = show_prefix_suffix
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report."""
+        raise NotImplementedError
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result."""
+        raise NotImplementedError
+    
+    def write(self, report: DoctorReport, output: Optional[TextIO] = None) -> None:
+        """Write formatted report to output."""
+        output = output or sys.stdout
+        output.write(self.format_report(report))
+        if not self.format_report(report).endswith("\n"):
+            output.write("\n")
+
+
+class TextFormatter(BaseFormatter):
+    """Text formatter with optional color support."""
+    
+    # ANSI color codes
+    COLORS = {
+        "reset": "\033[0m",
+        "bold": "\033[1m",
+        "dim": "\033[2m",
+        "red": "\033[31m",
+        "green": "\033[32m",
+        "yellow": "\033[33m",
+        "blue": "\033[34m",
+        "cyan": "\033[36m",
+        "white": "\033[37m",
+    }
+    
+    STATUS_COLORS = {
+        CheckStatus.PASS: "green",
+        CheckStatus.WARN: "yellow",
+        CheckStatus.FAIL: "red",
+        CheckStatus.SKIP: "dim",
+        CheckStatus.ERROR: "red",
+    }
+    
+    STATUS_SYMBOLS = {
+        CheckStatus.PASS: "✓",
+        CheckStatus.WARN: "⚠",
+        CheckStatus.FAIL: "✗",
+        CheckStatus.SKIP: "○",
+        CheckStatus.ERROR: "✗",
+    }
+    
+    def _color(self, text: str, color: str) -> str:
+        """Apply color to text if colors are enabled."""
+        if self.no_color:
+            return text
+        return f"{self.COLORS.get(color, '')}{text}{self.COLORS['reset']}"
+    
+    def _status_symbol(self, status: CheckStatus) -> str:
+        """Get colored status symbol."""
+        symbol = self.STATUS_SYMBOLS.get(status, "?")
+        color = self.STATUS_COLORS.get(status, "white")
+        return self._color(symbol, color)
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result."""
+        symbol = self._status_symbol(result.status)
+        message = result.message
+        if self.redact:
+            message = redact_secrets(message, self.show_prefix_suffix)
+        
+        line = f"{symbol} {result.title}: {message}"
+        
+        if result.details and not self.quiet:
+            details = result.details
+            if self.redact:
+                details = redact_secrets(details, self.show_prefix_suffix)
+            line += f"\n    {self._color(details, 'dim')}"
+        
+        if result.remediation and result.status in (CheckStatus.FAIL, CheckStatus.ERROR):
+            line += f"\n    {self._color('Fix:', 'yellow')} {result.remediation}"
+        
+        return line
+    
+    def format_summary(self, summary: ReportSummary, strict: bool = False) -> str:
+        """Format the summary section."""
+        parts = []
+        
+        if summary.passed > 0:
+            parts.append(self._color(f"{summary.passed} passed", "green"))
+        if summary.warnings > 0:
+            color = "red" if strict else "yellow"
+            parts.append(self._color(f"{summary.warnings} warnings", color))
+        if summary.failed > 0:
+            parts.append(self._color(f"{summary.failed} failed", "red"))
+        if summary.skipped > 0:
+            parts.append(self._color(f"{summary.skipped} skipped", "dim"))
+        if summary.errors > 0:
+            parts.append(self._color(f"{summary.errors} errors", "red"))
+        
+        return f"{summary.total} checks: " + ", ".join(parts)
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report."""
+        lines = []
+        
+        # Header
+        if not self.quiet:
+            header = f"PraisonAI Doctor v{report.version}"
+            lines.append(self._color(header, "bold"))
+            lines.append("━" * 70)
+        
+        # Results
+        for result in report.results:
+            lines.append(self.format_result(result))
+        
+        # Summary
+        if not self.quiet:
+            lines.append("━" * 70)
+        lines.append(self.format_summary(report.summary))
+        
+        # Duration
+        if not self.quiet and report.duration_ms > 0:
+            lines.append(self._color(f"Completed in {report.duration_ms:.0f}ms", "dim"))
+        
+        return "\n".join(lines)
+
+
+class JsonFormatter(BaseFormatter):
+    """JSON formatter with deterministic output."""
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result as JSON."""
+        data = result.to_dict()
+        if self.redact:
+            data = redact_dict(data, self.show_prefix_suffix)
+        return json.dumps(data, indent=2, sort_keys=True)
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report as JSON."""
+        data = report.to_dict()
+        if self.redact:
+            data = redact_dict(data, self.show_prefix_suffix)
+        
+        # Ensure deterministic ordering
+        return json.dumps(data, indent=2, sort_keys=True)
+    
+    def write(self, report: DoctorReport, output: Optional[TextIO] = None) -> None:
+        """Write formatted report to output."""
+        output = output or sys.stdout
+        output.write(self.format_report(report))
+        output.write("\n")
+
+
+def get_formatter(
+    format_type: str = "text",
+    no_color: bool = False,
+    quiet: bool = False,
+    redact: bool = True,
+    show_prefix_suffix: bool = False,
+) -> BaseFormatter:
+    """
+    Get a formatter instance.
+    
+    Args:
+        format_type: "text" or "json"
+        no_color: Disable ANSI colors
+        quiet: Minimal output
+        redact: Redact secrets
+        show_prefix_suffix: Show partial secrets
+        
+    Returns:
+        Formatter instance
+    """
+    if format_type == "json":
+        return JsonFormatter(
+            no_color=True,  # JSON never has colors
+            quiet=quiet,
+            redact=redact,
+            show_prefix_suffix=show_prefix_suffix,
+        )
+    return TextFormatter(
+        no_color=no_color,
+        quiet=quiet,
+        redact=redact,
+        show_prefix_suffix=show_prefix_suffix,
+    )

src/praisonai/praisonai/cli/features/doctor/handler.py

@@ -0,0 +1,397 @@
+"""
+Doctor CLI handler for PraisonAI.
+
+Provides the main DoctorHandler class that integrates with the CLI.
+"""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from ..base import CommandHandler
+from .models import CheckCategory, DoctorConfig, DoctorReport
+from .engine import DoctorEngine
+from .registry import get_registry
+from .formatters import get_formatter
+
+
+class DoctorHandler(CommandHandler):
+    """
+    Handler for the 'praisonai doctor' command.
+    
+    Provides comprehensive health checks and diagnostics.
+    """
+    
+    @property
+    def feature_name(self) -> str:
+        return "doctor"
+    
+    def get_actions(self) -> List[str]:
+        return [
+            "env",
+            "config", 
+            "tools",
+            "db",
+            "mcp",
+            "obs",
+            "skills",
+            "memory",
+            "permissions",
+            "network",
+            "performance",
+            "ci",
+            "selftest",
+        ]
+    
+    def _register_checks(self) -> None:
+        """Register all doctor checks."""
+        from .checks import register_all_checks
+        register_all_checks()
+    
+    def _parse_args(self, args: List[str]) -> argparse.Namespace:
+        """Parse doctor command arguments."""
+        parser = argparse.ArgumentParser(
+            prog="praisonai doctor",
+            description="PraisonAI health checks and diagnostics",
+        )
+        
+        # Subcommand
+        parser.add_argument(
+            "subcommand",
+            nargs="?",
+            choices=self.get_actions() + [None],
+            help="Subcommand to run (default: run all fast checks)",
+        )
+        
+        # Global flags
+        parser.add_argument(
+            "--json",
+            action="store_true",
+            help="Output in JSON format",
+        )
+        parser.add_argument(
+            "--format",
+            choices=["text", "json"],
+            default="text",
+            help="Output format (default: text)",
+        )
+        parser.add_argument(
+            "--output", "-o",
+            type=str,
+            help="Write report to file",
+        )
+        parser.add_argument(
+            "--deep",
+            action="store_true",
+            help="Enable deeper probes (DB connects, network checks)",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=float,
+            default=10.0,
+            help="Per-check timeout in seconds (default: 10)",
+        )
+        parser.add_argument(
+            "--strict",
+            action="store_true",
+            help="Treat warnings as failures",
+        )
+        parser.add_argument(
+            "--quiet", "-q",
+            action="store_true",
+            help="Minimal output",
+        )
+        parser.add_argument(
+            "--no-color",
+            action="store_true",
+            help="Disable ANSI colors",
+        )
+        parser.add_argument(
+            "--only",
+            type=str,
+            help="Only run these check IDs (comma-separated)",
+        )
+        parser.add_argument(
+            "--skip",
+            type=str,
+            help="Skip these check IDs (comma-separated)",
+        )
+        parser.add_argument(
+            "--list-checks",
+            action="store_true",
+            help="List available check IDs",
+        )
+        parser.add_argument(
+            "--version",
+            action="store_true",
+            help="Show doctor module version",
+        )
+        
+        # Subcommand-specific flags
+        parser.add_argument(
+            "--show-keys",
+            action="store_true",
+            help="Show masked API key values (env subcommand)",
+        )
+        parser.add_argument(
+            "--require",
+            type=str,
+            help="Require these env vars (comma-separated)",
+        )
+        parser.add_argument(
+            "--file", "-f",
+            type=str,
+            help="Config file to validate (config subcommand)",
+        )
+        parser.add_argument(
+            "--schema",
+            action="store_true",
+            help="Print expected schema (config subcommand)",
+        )
+        parser.add_argument(
+            "--dsn",
+            type=str,
+            help="Database DSN (db subcommand)",
+        )
+        parser.add_argument(
+            "--provider",
+            type=str,
+            help="Provider name (db/obs subcommand)",
+        )
+        parser.add_argument(
+            "--read-only",
+            action="store_true",
+            default=True,
+            help="Read-only mode for DB checks (default: true)",
+        )
+        parser.add_argument(
+            "--name",
+            type=str,
+            help="Name filter (mcp/tools subcommand)",
+        )
+        parser.add_argument(
+            "--category",
+            type=str,
+            help="Category filter (tools subcommand)",
+        )
+        parser.add_argument(
+            "--all",
+            action="store_true",
+            dest="all_checks",
+            help="Show all items (tools subcommand)",
+        )
+        parser.add_argument(
+            "--missing-only",
+            action="store_true",
+            help="Show only missing items (tools subcommand)",
+        )
+        parser.add_argument(
+            "--list-tools",
+            action="store_true",
+            help="List MCP tools (mcp subcommand)",
+        )
+        parser.add_argument(
+            "--path",
+            type=str,
+            help="Path to check (skills subcommand)",
+        )
+        parser.add_argument(
+            "--all-installed",
+            action="store_true",
+            help="Check all installed skills",
+        )
+        parser.add_argument(
+            "--budget-ms",
+            type=int,
+            help="Import time budget in ms (performance subcommand)",
+        )
+        parser.add_argument(
+            "--top",
+            type=int,
+            default=10,
+            dest="top_n",
+            help="Number of top items to show (default: 10)",
+        )
+        parser.add_argument(
+            "--fail-fast",
+            action="store_true",
+            help="Stop on first failure (ci subcommand)",
+        )
+        parser.add_argument(
+            "--mock",
+            action="store_true",
+            default=True,
+            help="Use mock mode (selftest, default: true)",
+        )
+        parser.add_argument(
+            "--live",
+            action="store_true",
+            help="Use live API calls (selftest)",
+        )
+        parser.add_argument(
+            "--model",
+            type=str,
+            help="Model to use for selftest",
+        )
+        parser.add_argument(
+            "--save-report",
+            action="store_true",
+            help="Save selftest report",
+        )
+        
+        return parser.parse_args(args)
+    
+    def _build_config(self, args: argparse.Namespace) -> DoctorConfig:
+        """Build DoctorConfig from parsed arguments."""
+        return DoctorConfig(
+            deep=args.deep,
+            timeout=args.timeout if args.deep else min(args.timeout, 10.0),
+            strict=args.strict,
+            quiet=args.quiet,
+            no_color=args.no_color,
+            format="json" if args.json else args.format,
+            output_path=args.output,
+            only=args.only.split(",") if args.only else [],
+            skip=args.skip.split(",") if args.skip else [],
+            show_keys=args.show_keys,
+            require_keys=args.require.split(",") if args.require else [],
+            config_file=args.file,
+            dsn=args.dsn,
+            provider=args.provider,
+            read_only=args.read_only,
+            mock=args.mock and not args.live,
+            live=args.live,
+            model=args.model,
+            budget_ms=args.budget_ms,
+            top_n=args.top_n,
+            fail_fast=args.fail_fast,
+            list_tools=args.list_tools,
+            all_checks=args.all_checks,
+            missing_only=args.missing_only,
+            name=args.name,
+            category=args.category,
+            path=args.path,
+            save_report=args.save_report,
+        )
+    
+    def _get_categories_for_subcommand(self, subcommand: Optional[str]) -> Optional[List[CheckCategory]]:
+        """Get check categories for a subcommand."""
+        category_map = {
+            "env": [CheckCategory.ENVIRONMENT],
+            "config": [CheckCategory.CONFIG],
+            "tools": [CheckCategory.TOOLS],
+            "db": [CheckCategory.DATABASE],
+            "mcp": [CheckCategory.MCP],
+            "obs": [CheckCategory.OBSERVABILITY],
+            "skills": [CheckCategory.SKILLS],
+            "memory": [CheckCategory.MEMORY],
+            "permissions": [CheckCategory.PERMISSIONS],
+            "network": [CheckCategory.NETWORK],
+            "performance": [CheckCategory.PERFORMANCE],
+            "selftest": [CheckCategory.SELFTEST],
+            "ci": None,  # CI runs all checks
+        }
+        return category_map.get(subcommand)
+    
+    def execute(self, action: str, action_args: List[str], **kwargs) -> int:
+        """
+        Execute the doctor command.
+        
+        Args:
+            action: The subcommand or empty string
+            action_args: Additional arguments
+            
+        Returns:
+            Exit code (0=pass, 1=fail, 2=error)
+        """
+        # Combine action and action_args for parsing
+        all_args = [action] + action_args if action and action != "help" else action_args
+        
+        try:
+            args = self._parse_args(all_args)
+        except SystemExit:
+            return 0  # Help was shown
+        
+        # Handle special flags
+        if args.version:
+            from . import __version__
+            print(f"PraisonAI Doctor v{__version__}")
+            return 0
+        
+        # Register all checks
+        self._register_checks()
+        
+        if args.list_checks:
+            registry = get_registry()
+            print(registry.list_checks_text())
+            return 0
+        
+        # Build config
+        config = self._build_config(args)
+        
+        # Handle CI mode
+        if args.subcommand == "ci":
+            config.format = "json"
+            config.no_color = True
+            config.quiet = True
+        
+        # Get categories for subcommand
+        categories = self._get_categories_for_subcommand(args.subcommand)
+        
+        # Run doctor
+        engine = DoctorEngine(config)
+        report = engine.run(categories=categories)
+        
+        # Format output
+        formatter = get_formatter(
+            format_type=config.format,
+            no_color=config.no_color,
+            quiet=config.quiet,
+            show_prefix_suffix=config.show_keys,
+        )
+        
+        # Write output
+        if config.output_path:
+            with open(config.output_path, "w") as f:
+                formatter.write(report, f)
+            if not config.quiet:
+                print(f"Report written to: {config.output_path}")
+        else:
+            formatter.write(report, sys.stdout)
+        
+        return report.exit_code
+    
+    def run(self, args: List[str]) -> int:
+        """
+        Run the doctor command from CLI.
+        
+        Args:
+            args: Command line arguments after 'doctor'
+            
+        Returns:
+            Exit code
+        """
+        if not args:
+            return self.execute("", [])
+        
+        action = args[0] if args else ""
+        action_args = args[1:] if len(args) > 1 else []
+        
+        return self.execute(action, action_args)
+
+
+def run_doctor(args: Optional[List[str]] = None) -> int:
+    """
+    Convenience function to run doctor from CLI.
+    
+    Args:
+        args: Command line arguments (default: sys.argv[1:])
+        
+    Returns:
+        Exit code
+    """
+    if args is None:
+        args = sys.argv[1:]
+    
+    handler = DoctorHandler()
+    return handler.run(args)

src/praisonai/praisonai/cli/features/doctor/models.py

@@ -0,0 +1,264 @@
+"""
+Data models for the Doctor CLI module.
+
+Defines the core data structures for check results, reports, and configuration.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+import time
+
+
+class CheckStatus(Enum):
+    """Status of a doctor check."""
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+    SKIP = "skip"
+    ERROR = "error"
+
+
+class CheckCategory(Enum):
+    """Category of a doctor check."""
+    ENVIRONMENT = "environment"
+    CONFIG = "config"
+    TOOLS = "tools"
+    DATABASE = "database"
+    MCP = "mcp"
+    OBSERVABILITY = "observability"
+    SKILLS = "skills"
+    MEMORY = "memory"
+    PERMISSIONS = "permissions"
+    NETWORK = "network"
+    PERFORMANCE = "performance"
+    SELFTEST = "selftest"
+
+
+class CheckSeverity(Enum):
+    """Severity level of a check."""
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+@dataclass
+class CheckResult:
+    """Result of a single doctor check."""
+    id: str
+    title: str
+    category: CheckCategory
+    status: CheckStatus
+    message: str
+    details: Optional[str] = None
+    remediation: Optional[str] = None
+    duration_ms: float = 0.0
+    severity: CheckSeverity = CheckSeverity.MEDIUM
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "id": self.id,
+            "title": self.title,
+            "category": self.category.value,
+            "status": self.status.value,
+            "message": self.message,
+            "details": self.details,
+            "remediation": self.remediation,
+            "duration_ms": round(self.duration_ms, 2),
+            "severity": self.severity.value,
+            "metadata": self.metadata,
+        }
+    
+    @property
+    def passed(self) -> bool:
+        """Check if this result is considered passing."""
+        return self.status in (CheckStatus.PASS, CheckStatus.SKIP)
+    
+    @property
+    def is_warning(self) -> bool:
+        """Check if this result is a warning."""
+        return self.status == CheckStatus.WARN
+    
+    @property
+    def is_failure(self) -> bool:
+        """Check if this result is a failure."""
+        return self.status in (CheckStatus.FAIL, CheckStatus.ERROR)
+
+
+@dataclass
+class CheckDefinition:
+    """Definition of a doctor check."""
+    id: str
+    title: str
+    description: str
+    category: CheckCategory
+    severity: CheckSeverity = CheckSeverity.MEDIUM
+    requires_deep: bool = False
+    dependencies: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "category": self.category.value,
+            "severity": self.severity.value,
+            "requires_deep": self.requires_deep,
+            "dependencies": self.dependencies,
+            "tags": self.tags,
+        }
+
+
+@dataclass
+class EnvironmentSummary:
+    """Summary of the runtime environment."""
+    python_version: str = ""
+    python_executable: str = ""
+    os_name: str = ""
+    os_version: str = ""
+    architecture: str = ""
+    praisonai_version: str = ""
+    praisonaiagents_version: str = ""
+    working_directory: str = ""
+    virtual_env: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "python_version": self.python_version,
+            "python_executable": self.python_executable,
+            "os_name": self.os_name,
+            "os_version": self.os_version,
+            "architecture": self.architecture,
+            "praisonai_version": self.praisonai_version,
+            "praisonaiagents_version": self.praisonaiagents_version,
+            "working_directory": self.working_directory,
+            "virtual_env": self.virtual_env,
+        }
+
+
+@dataclass
+class ReportSummary:
+    """Summary statistics for a doctor report."""
+    total: int = 0
+    passed: int = 0
+    warnings: int = 0
+    failed: int = 0
+    skipped: int = 0
+    errors: int = 0
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "total": self.total,
+            "passed": self.passed,
+            "warnings": self.warnings,
+            "failed": self.failed,
+            "skipped": self.skipped,
+            "errors": self.errors,
+        }
+
+
+@dataclass
+class DoctorReport:
+    """Complete doctor report."""
+    version: str = "1.0.0"
+    timestamp: str = ""
+    duration_ms: float = 0.0
+    environment: EnvironmentSummary = field(default_factory=EnvironmentSummary)
+    results: List[CheckResult] = field(default_factory=list)
+    summary: ReportSummary = field(default_factory=ReportSummary)
+    exit_code: int = 0
+    mode: str = "fast"
+    filters: Dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        if not self.timestamp:
+            from datetime import datetime, timezone
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+    
+    def calculate_summary(self) -> None:
+        """Calculate summary statistics from results."""
+        self.summary = ReportSummary(
+            total=len(self.results),
+            passed=sum(1 for r in self.results if r.status == CheckStatus.PASS),
+            warnings=sum(1 for r in self.results if r.status == CheckStatus.WARN),
+            failed=sum(1 for r in self.results if r.status == CheckStatus.FAIL),
+            skipped=sum(1 for r in self.results if r.status == CheckStatus.SKIP),
+            errors=sum(1 for r in self.results if r.status == CheckStatus.ERROR),
+        )
+    
+    def calculate_exit_code(self, strict: bool = False) -> int:
+        """
+        Calculate exit code based on results.
+        
+        Args:
+            strict: If True, treat warnings as failures
+            
+        Returns:
+            0: All passed (warnings allowed unless strict)
+            1: Failures present
+            2: Internal errors
+        """
+        if self.summary.errors > 0:
+            return 2
+        if self.summary.failed > 0:
+            return 1
+        if strict and self.summary.warnings > 0:
+            return 1
+        return 0
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "version": self.version,
+            "timestamp": self.timestamp,
+            "duration_ms": round(self.duration_ms, 2),
+            "environment": self.environment.to_dict(),
+            "results": [r.to_dict() for r in self.results],
+            "summary": self.summary.to_dict(),
+            "exit_code": self.exit_code,
+            "mode": self.mode,
+            "filters": self.filters,
+        }
+
+
+@dataclass
+class DoctorConfig:
+    """Configuration for doctor execution."""
+    deep: bool = False
+    timeout: float = 10.0
+    strict: bool = False
+    quiet: bool = False
+    no_color: bool = False
+    format: str = "text"
+    output_path: Optional[str] = None
+    only: List[str] = field(default_factory=list)
+    skip: List[str] = field(default_factory=list)
+    
+    # Subcommand-specific options
+    show_keys: bool = False
+    require_keys: List[str] = field(default_factory=list)
+    config_file: Optional[str] = None
+    dsn: Optional[str] = None
+    provider: Optional[str] = None
+    read_only: bool = True
+    mock: bool = True
+    live: bool = False
+    model: Optional[str] = None
+    budget_ms: Optional[int] = None
+    top_n: int = 10
+    fail_fast: bool = False
+    list_tools: bool = False
+    all_checks: bool = False
+    missing_only: bool = False
+    name: Optional[str] = None
+    category: Optional[str] = None
+    path: Optional[str] = None
+    save_report: bool = False

src/praisonai/praisonai/cli/features/doctor/registry.py

@@ -0,0 +1,239 @@
+"""
+Check registry for the Doctor CLI module.
+
+Manages registration and discovery of doctor checks.
+"""
+
+from typing import Callable, Dict, List, Optional, Set
+from .models import CheckDefinition, CheckCategory, CheckSeverity, CheckResult
+
+
+class CheckRegistry:
+    """
+    Registry for doctor checks.
+    
+    Manages check definitions and their implementations.
+    """
+    
+    _instance: Optional["CheckRegistry"] = None
+    
+    def __new__(cls) -> "CheckRegistry":
+        """Singleton pattern for global registry."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._checks: Dict[str, CheckDefinition] = {}
+            cls._instance._implementations: Dict[str, Callable] = {}
+            cls._instance._initialized = False
+        return cls._instance
+    
+    @classmethod
+    def get_instance(cls) -> "CheckRegistry":
+        """Get the singleton instance."""
+        return cls()
+    
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the registry (for testing)."""
+        cls._instance = None
+    
+    def register(
+        self,
+        id: str,
+        title: str,
+        description: str,
+        category: CheckCategory,
+        implementation: Callable,
+        severity: CheckSeverity = CheckSeverity.MEDIUM,
+        requires_deep: bool = False,
+        dependencies: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Register a doctor check.
+        
+        Args:
+            id: Unique identifier (snake_case)
+            title: Human-readable title
+            description: Short description of what the check does
+            category: Check category
+            implementation: Callable that performs the check
+            severity: Severity level
+            requires_deep: Whether this check requires --deep mode
+            dependencies: List of check IDs this check depends on
+            tags: Optional tags for filtering
+        """
+        definition = CheckDefinition(
+            id=id,
+            title=title,
+            description=description,
+            category=category,
+            severity=severity,
+            requires_deep=requires_deep,
+            dependencies=dependencies or [],
+            tags=tags or [],
+        )
+        self._checks[id] = definition
+        self._implementations[id] = implementation
+    
+    def get_check(self, id: str) -> Optional[CheckDefinition]:
+        """Get a check definition by ID."""
+        return self._checks.get(id)
+    
+    def get_implementation(self, id: str) -> Optional[Callable]:
+        """Get a check implementation by ID."""
+        return self._implementations.get(id)
+    
+    def get_all_checks(self) -> List[CheckDefinition]:
+        """Get all registered checks."""
+        return list(self._checks.values())
+    
+    def get_check_ids(self) -> List[str]:
+        """Get all registered check IDs."""
+        return list(self._checks.keys())
+    
+    def get_checks_by_category(self, category: CheckCategory) -> List[CheckDefinition]:
+        """Get all checks in a category."""
+        return [c for c in self._checks.values() if c.category == category]
+    
+    def get_checks_by_tag(self, tag: str) -> List[CheckDefinition]:
+        """Get all checks with a specific tag."""
+        return [c for c in self._checks.values() if tag in c.tags]
+    
+    def filter_checks(
+        self,
+        only: Optional[List[str]] = None,
+        skip: Optional[List[str]] = None,
+        categories: Optional[List[CheckCategory]] = None,
+        deep_mode: bool = False,
+    ) -> List[CheckDefinition]:
+        """
+        Filter checks based on criteria.
+        
+        Args:
+            only: Only include these check IDs
+            skip: Skip these check IDs
+            categories: Only include checks in these categories
+            deep_mode: Include checks that require deep mode
+            
+        Returns:
+            Filtered list of check definitions
+        """
+        checks = list(self._checks.values())
+        
+        # Filter by only
+        if only:
+            only_set = set(only)
+            checks = [c for c in checks if c.id in only_set]
+        
+        # Filter by skip
+        if skip:
+            skip_set = set(skip)
+            checks = [c for c in checks if c.id not in skip_set]
+        
+        # Filter by categories
+        if categories:
+            checks = [c for c in checks if c.category in categories]
+        
+        # Filter by deep mode
+        if not deep_mode:
+            checks = [c for c in checks if not c.requires_deep]
+        
+        return checks
+    
+    def resolve_dependencies(self, check_ids: List[str]) -> List[str]:
+        """
+        Resolve check dependencies and return ordered list.
+        
+        Args:
+            check_ids: List of check IDs to resolve
+            
+        Returns:
+            Ordered list of check IDs with dependencies first
+        """
+        resolved: List[str] = []
+        seen: Set[str] = set()
+        
+        def resolve(id: str) -> None:
+            if id in seen:
+                return
+            seen.add(id)
+            
+            check = self._checks.get(id)
+            if check:
+                for dep in check.dependencies:
+                    resolve(dep)
+                resolved.append(id)
+        
+        for id in check_ids:
+            resolve(id)
+        
+        return resolved
+    
+    def list_checks_text(self) -> str:
+        """Generate text listing of all checks."""
+        lines = ["Available Doctor Checks:", ""]
+        
+        # Group by category
+        by_category: Dict[CheckCategory, List[CheckDefinition]] = {}
+        for check in self._checks.values():
+            if check.category not in by_category:
+                by_category[check.category] = []
+            by_category[check.category].append(check)
+        
+        for category in CheckCategory:
+            if category in by_category:
+                lines.append(f"  {category.value.upper()}:")
+                for check in sorted(by_category[category], key=lambda c: c.id):
+                    deep_marker = " [deep]" if check.requires_deep else ""
+                    lines.append(f"    {check.id:<30} {check.description}{deep_marker}")
+                lines.append("")
+        
+        return "\n".join(lines)
+
+
+# Global registry instance
+_registry = CheckRegistry()
+
+
+def register_check(
+    id: str,
+    title: str,
+    description: str,
+    category: CheckCategory,
+    severity: CheckSeverity = CheckSeverity.MEDIUM,
+    requires_deep: bool = False,
+    dependencies: Optional[List[str]] = None,
+    tags: Optional[List[str]] = None,
+):
+    """
+    Decorator to register a doctor check.
+    
+    Usage:
+        @register_check(
+            id="python_version",
+            title="Python Version",
+            description="Check Python version is 3.9+",
+            category=CheckCategory.ENVIRONMENT,
+        )
+        def check_python_version(config: DoctorConfig) -> CheckResult:
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        _registry.register(
+            id=id,
+            title=title,
+            description=description,
+            category=category,
+            implementation=func,
+            severity=severity,
+            requires_deep=requires_deep,
+            dependencies=dependencies,
+            tags=tags,
+        )
+        return func
+    return decorator
+
+
+def get_registry() -> CheckRegistry:
+    """Get the global check registry."""
+    return _registry

src/praisonai/praisonai/cli/features/jobs.py

@@ -53,11 +53,14 @@ class JobsHandler:
         self,
         prompt: str,
         agent_file: Optional[str] = None,
+        recipe_name: Optional[str] = None,
+        recipe_config: Optional[dict] = None,
         framework: str = "praisonai",
         timeout: int = 3600,
         wait: bool = False,
         poll_interval: int = 5,
         idempotency_key: Optional[str] = None,
+        idempotency_scope: str = "none",
         webhook_url: Optional[str] = None,
         session_id: Optional[str] = None,
         output_json: bool = False
@@ -68,14 +71,25 @@ class JobsHandler:
         Args:
             prompt: The prompt/task for the agent
             agent_file: Optional path to agents.yaml
+            recipe_name: Optional recipe name (mutually exclusive with agent_file)
+            recipe_config: Optional recipe configuration overrides
             framework: Framework to use
             timeout: Job timeout in seconds
             wait: If True, wait for completion
             poll_interval: Seconds between status polls
+            idempotency_key: Key for deduplication
+            idempotency_scope: Scope for deduplication (none, session, global)
+            webhook_url: URL for completion webhook
+            session_id: Session ID for conversation continuity
+            output_json: If True, output JSON format
             
         Returns:
             Job submission response
         """
+        # Validate mutually exclusive options
+        if agent_file and recipe_name:
+            raise ValueError("Cannot specify both --agent-file and --recipe. Choose one.")
+        
         client = self._get_client()
         
         payload = {
@@ -86,12 +100,18 @@ class JobsHandler:
         
         if agent_file:
             payload["agent_file"] = agent_file
+        if recipe_name:
+            payload["recipe_name"] = recipe_name
+        if recipe_config:
+            payload["recipe_config"] = recipe_config
         if webhook_url:
             payload["webhook_url"] = webhook_url
         if session_id:
             payload["session_id"] = session_id
         if idempotency_key:
             payload["idempotency_key"] = idempotency_key
+        if idempotency_scope and idempotency_scope != "none":
+            payload["idempotency_scope"] = idempotency_scope
         
         headers = {}
         if idempotency_key:
@@ -494,12 +514,17 @@ def handle_run_command(args: List[str], verbose: bool = False):
     submit_parser = subparsers.add_parser("submit", help="Submit a new job")
     submit_parser.add_argument("prompt", help="The prompt/task for the agent")
     submit_parser.add_argument("--agent-file", help="Path to agents.yaml")
+    submit_parser.add_argument("--recipe", dest="recipe_name", help="Recipe name to execute (mutually exclusive with --agent-file)")
+    submit_parser.add_argument("--recipe-config", help="Recipe config as JSON string")
     submit_parser.add_argument("--framework", default="praisonai", help="Framework to use")
     submit_parser.add_argument("--timeout", type=int, default=3600, help="Timeout in seconds")
     submit_parser.add_argument("--wait", action="store_true", help="Wait for completion")
+    submit_parser.add_argument("--stream", action="store_true", help="Stream job progress after submission")
     submit_parser.add_argument("--idempotency-key", help="Idempotency key to prevent duplicates")
+    submit_parser.add_argument("--idempotency-scope", default="none", choices=["none", "session", "global"], help="Idempotency scope")
     submit_parser.add_argument("--webhook-url", help="Webhook URL for completion callback")
     submit_parser.add_argument("--session-id", help="Session ID for grouping jobs")
+    submit_parser.add_argument("--metadata", action="append", metavar="KEY=VALUE", help="Custom metadata (can be used multiple times)")
     submit_parser.add_argument("--json", dest="output_json", action="store_true", help="Output JSON for scripting")
     submit_parser.add_argument("--api-url", default="http://127.0.0.1:8005", help="API server URL")
     
@@ -552,13 +577,25 @@ def handle_run_command(args: List[str], verbose: bool = False):
     
     try:
         if parsed.subcommand == "submit":
+            # Parse recipe config if provided
+            recipe_config = None
+            if getattr(parsed, "recipe_config", None):
+                try:
+                    recipe_config = json.loads(parsed.recipe_config)
+                except json.JSONDecodeError:
+                    print("Error: --recipe-config must be valid JSON")
+                    sys.exit(1)
+            
             handler.submit(
                 prompt=parsed.prompt,
                 agent_file=parsed.agent_file,
+                recipe_name=getattr(parsed, "recipe_name", None),
+                recipe_config=recipe_config,
                 framework=parsed.framework,
                 timeout=parsed.timeout,
                 wait=parsed.wait,
                 idempotency_key=getattr(parsed, "idempotency_key", None),
+                idempotency_scope=getattr(parsed, "idempotency_scope", "none"),
                 webhook_url=getattr(parsed, "webhook_url", None),
                 session_id=getattr(parsed, "session_id", None),
                 output_json=getattr(parsed, "output_json", False)

src/praisonai/praisonai/cli/features/lite.py

@@ -0,0 +1,244 @@
+"""
+Lite Agent Handler for CLI.
+
+Provides access to the lightweight praisonaiagents.lite subpackage.
+Usage: praisonai lite [run|info]
+"""
+
+import os
+from typing import Any, Dict, Tuple
+from .base import FlagHandler
+
+
+class LiteHandler(FlagHandler):
+    """
+    Handler for lite agent commands.
+    
+    The lite subpackage provides a minimal agent framework without heavy
+    dependencies like litellm. Users can bring their own LLM client.
+    
+    Commands:
+        praisonai lite run "prompt"     - Run a lite agent with custom LLM
+        praisonai lite info             - Show lite package info
+        praisonai lite example          - Show example usage
+    """
+    
+    @property
+    def feature_name(self) -> str:
+        return "lite"
+    
+    @property
+    def flag_name(self) -> str:
+        return "lite"
+    
+    @property
+    def flag_help(self) -> str:
+        return "Use lightweight agent without heavy dependencies"
+    
+    def check_dependencies(self) -> Tuple[bool, str]:
+        """Check if lite package is available."""
+        import importlib.util
+        if importlib.util.find_spec("praisonaiagents.lite") is not None:
+            return True, ""
+        return False, "Lite package requires praisonaiagents>=0.5.0"
+    
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Get information about the lite package.
+        
+        Returns:
+            Dict with package info
+        """
+        import importlib.util
+        if importlib.util.find_spec("praisonaiagents.lite") is None:
+            return {
+                "available": False,
+                "error": "praisonaiagents.lite not found"
+            }
+        
+        return {
+            "available": True,
+            "classes": ["LiteAgent", "LiteTask", "LiteToolResult"],
+            "decorators": ["@tool"],
+            "helpers": ["create_openai_llm_fn", "create_anthropic_llm_fn"],
+            "features": [
+                "BYO-LLM (Bring Your Own LLM)",
+                "Thread-safe chat history",
+                "Tool execution",
+                "No litellm dependency",
+                "Minimal memory footprint"
+            ]
+        }
+    
+    def show_example(self) -> str:
+        """
+        Show example usage of lite package.
+        
+        Returns:
+            Example code string
+        """
+        example = '''
+# Example: Using praisonaiagents.lite with custom LLM
+
+from praisonaiagents.lite import LiteAgent, tool
+
+# Define a custom LLM function
+def my_llm(messages):
+    """Your custom LLM implementation."""
+    # Example: Call OpenAI directly
+    import openai
+    client = openai.OpenAI()
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages
+    )
+    return response.choices[0].message.content
+
+# Or use the built-in OpenAI adapter
+from praisonaiagents.lite import create_openai_llm_fn
+llm_fn = create_openai_llm_fn(model="gpt-4o-mini")
+
+# Create a lite agent
+agent = LiteAgent(
+    name="MyAgent",
+    llm_fn=llm_fn,
+    instructions="You are a helpful assistant."
+)
+
+# Chat with the agent
+response = agent.chat("Hello!")
+print(response)
+
+# Define and use tools
+@tool
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+agent_with_tools = LiteAgent(
+    name="MathAgent",
+    llm_fn=llm_fn,
+    tools=[add_numbers]
+)
+
+# Execute tool directly
+result = agent_with_tools.execute_tool("add_numbers", a=5, b=3)
+print(f"Result: {result.output}")  # Output: 8
+'''
+        return example
+    
+    def run_lite_agent(
+        self,
+        prompt: str,
+        model: str = "gpt-4o-mini",
+        provider: str = "openai"
+    ) -> str:
+        """
+        Run a lite agent with the given prompt.
+        
+        Args:
+            prompt: The prompt to send to the agent
+            model: Model name to use
+            provider: LLM provider (openai, anthropic)
+            
+        Returns:
+            Agent response
+        """
+        try:
+            from praisonaiagents.lite import LiteAgent, create_openai_llm_fn, create_anthropic_llm_fn
+            
+            # Create LLM function based on provider
+            if provider == "openai":
+                if not os.environ.get("OPENAI_API_KEY"):
+                    return "Error: OPENAI_API_KEY not set"
+                llm_fn = create_openai_llm_fn(model=model)
+            elif provider == "anthropic":
+                if not os.environ.get("ANTHROPIC_API_KEY"):
+                    return "Error: ANTHROPIC_API_KEY not set"
+                llm_fn = create_anthropic_llm_fn(model=model)
+            else:
+                return f"Error: Unknown provider '{provider}'. Use 'openai' or 'anthropic'."
+            
+            # Create and run agent
+            agent = LiteAgent(
+                name="LiteCLIAgent",
+                llm_fn=llm_fn,
+                instructions="You are a helpful assistant. Keep responses concise."
+            )
+            
+            return agent.chat(prompt)
+            
+        except ImportError as e:
+            return f"Error: {e}"
+        except Exception as e:
+            return f"Error: {e}"
+    
+    def handle(self, subcommand: str = "info", **kwargs) -> Any:
+        """
+        Handle lite subcommands.
+        
+        Args:
+            subcommand: One of run, info, example
+            **kwargs: Additional options (prompt, model, provider)
+            
+        Returns:
+            Results
+        """
+        if subcommand == "info":
+            info = self.get_info()
+            if info.get("available"):
+                print("praisonaiagents.lite - Lightweight Agent Package")
+                print("=" * 50)
+                print("\nClasses:", ", ".join(info["classes"]))
+                print("Decorators:", ", ".join(info["decorators"]))
+                print("Helpers:", ", ".join(info["helpers"]))
+                print("\nFeatures:")
+                for feature in info["features"]:
+                    print(f"  • {feature}")
+            else:
+                print(f"Lite package not available: {info.get('error')}")
+            return info
+            
+        elif subcommand == "example":
+            example = self.show_example()
+            print(example)
+            return example
+            
+        elif subcommand == "run":
+            prompt = kwargs.get("prompt", "Hello!")
+            model = kwargs.get("model", "gpt-4o-mini")
+            provider = kwargs.get("provider", "openai")
+            
+            response = self.run_lite_agent(prompt, model, provider)
+            print(response)
+            return response
+            
+        else:
+            print(f"Unknown subcommand: {subcommand}")
+            print("Available: info, example, run")
+            return None
+
+
+def run_lite_command(args) -> int:
+    """
+    Run lite command from CLI args.
+    
+    Args:
+        args: Parsed CLI arguments
+        
+    Returns:
+        Exit code (0 for success)
+    """
+    handler = LiteHandler()
+    subcommand = getattr(args, 'lite_command', 'info')
+    
+    kwargs = {}
+    if hasattr(args, 'prompt'):
+        kwargs['prompt'] = args.prompt
+    if hasattr(args, 'model'):
+        kwargs['model'] = args.model
+    if hasattr(args, 'provider'):
+        kwargs['provider'] = args.provider
+    
+    result = handler.handle(subcommand, **kwargs)
+    return 0 if result else 1

src/praisonai/praisonai/cli/features/package.py

@@ -0,0 +1,631 @@
+"""
+Package CLI Feature Handler
+
+Provides pip-like CLI commands for package management:
+- install: Install Python packages
+- uninstall: Uninstall Python packages
+- list: List installed packages
+- search: Search packages
+- index: Manage package indexes
+
+All commands use the canonical `praisonai` or `praisonai package` prefix.
+
+Security:
+- Default to single authoritative index (PyPI)
+- Warn loudly about dependency confusion when using extra indexes
+- Require explicit opt-in for extra index fallback
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+# Default configuration
+DEFAULT_INDEX_URL = "https://pypi.org/simple"
+CONFIG_DIR = Path.home() / ".praison"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+class PackageConfig:
+    """Package configuration manager."""
+    
+    def __init__(self):
+        """Initialize config."""
+        self._config = None
+    
+    def _load_config(self) -> Dict[str, Any]:
+        """Load configuration from file."""
+        if self._config is not None:
+            return self._config
+        
+        self._config = {
+            "package": {
+                "index_url": DEFAULT_INDEX_URL,
+                "extra_index_urls": [],
+                "allow_extra_index": False,
+                "trusted_hosts": [],
+            }
+        }
+        
+        if CONFIG_FILE.exists():
+            try:
+                import tomllib
+            except ImportError:
+                try:
+                    import tomli as tomllib
+                except ImportError:
+                    return self._config
+            
+            try:
+                with open(CONFIG_FILE, "rb") as f:
+                    file_config = tomllib.load(f)
+                    if "package" in file_config:
+                        self._config["package"].update(file_config["package"])
+            except Exception:
+                pass
+        
+        # Environment variable overrides
+        if os.environ.get("PRAISONAI_PACKAGE_INDEX_URL"):
+            self._config["package"]["index_url"] = os.environ["PRAISONAI_PACKAGE_INDEX_URL"]
+        
+        if os.environ.get("PRAISONAI_PACKAGE_EXTRA_INDEX_URLS"):
+            urls = os.environ["PRAISONAI_PACKAGE_EXTRA_INDEX_URLS"].split(",")
+            self._config["package"]["extra_index_urls"] = [u.strip() for u in urls if u.strip()]
+        
+        return self._config
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get config value."""
+        config = self._load_config()
+        parts = key.split(".")
+        value = config
+        for part in parts:
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            else:
+                return default
+        return value
+    
+    def save_index(self, index_url: str) -> None:
+        """Save index URL to config."""
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        
+        config = {}
+        if CONFIG_FILE.exists():
+            try:
+                import tomllib
+            except ImportError:
+                try:
+                    import tomli as tomllib
+                except ImportError:
+                    # Fall back to simple write
+                    with open(CONFIG_FILE, "w") as f:
+                        f.write(f'[package]\nindex_url = "{index_url}"\n')
+                    return
+            
+            try:
+                with open(CONFIG_FILE, "rb") as f:
+                    config = tomllib.load(f)
+            except Exception:
+                pass
+        
+        if "package" not in config:
+            config["package"] = {}
+        config["package"]["index_url"] = index_url
+        
+        # Write config (simple TOML format)
+        with open(CONFIG_FILE, "w") as f:
+            for section, values in config.items():
+                f.write(f"[{section}]\n")
+                for key, value in values.items():
+                    if isinstance(value, str):
+                        f.write(f'{key} = "{value}"\n')
+                    elif isinstance(value, bool):
+                        f.write(f'{key} = {"true" if value else "false"}\n')
+                    elif isinstance(value, list):
+                        f.write(f'{key} = {json.dumps(value)}\n')
+                    else:
+                        f.write(f'{key} = {value}\n')
+                f.write("\n")
+
+
+class PackageHandler:
+    """
+    CLI handler for package operations.
+    
+    Commands:
+    - install: Install Python packages
+    - uninstall: Uninstall Python packages
+    - list: List installed packages
+    - search: Search packages (best-effort)
+    - index: Manage package indexes
+    """
+    
+    # Stable exit codes
+    EXIT_SUCCESS = 0
+    EXIT_GENERAL_ERROR = 1
+    EXIT_VALIDATION_ERROR = 2
+    EXIT_NETWORK_ERROR = 10
+    EXIT_DEPENDENCY_ERROR = 11
+    
+    def __init__(self):
+        """Initialize the handler."""
+        self.config = PackageConfig()
+    
+    def handle(self, args: List[str]) -> int:
+        """
+        Handle package subcommand.
+        
+        Args:
+            args: Command arguments
+            
+        Returns:
+            Exit code
+        """
+        if not args:
+            self._print_help()
+            return self.EXIT_SUCCESS
+        
+        command = args[0]
+        remaining = args[1:]
+        
+        commands = {
+            "list": self.cmd_list,
+            "search": self.cmd_search,
+            "index": self.cmd_index,
+            "help": lambda _: self._print_help() or self.EXIT_SUCCESS,
+            "--help": lambda _: self._print_help() or self.EXIT_SUCCESS,
+            "-h": lambda _: self._print_help() or self.EXIT_SUCCESS,
+        }
+        
+        handler = commands.get(command)
+        if handler:
+            return handler(remaining)
+        
+        self._print_error(f"Unknown command: {command}")
+        self._print_help()
+        return self.EXIT_VALIDATION_ERROR
+    
+    def _print_help(self):
+        """Print help message."""
+        print("""
+PraisonAI Package Commands
+
+Usage: praisonai package <command> [options]
+       praisonai install <spec...>
+       praisonai uninstall <pkg...>
+
+Commands:
+  install     Install Python packages (shortcut: praisonai install)
+  uninstall   Uninstall Python packages (shortcut: praisonai uninstall)
+  list        List installed packages
+  search      Search for packages
+  index       Manage package indexes
+
+Examples:
+  praisonai install requests
+  praisonai install "requests>=2.28" httpx
+  praisonai uninstall requests
+  praisonai package list
+  praisonai package search langchain
+  praisonai package index show
+  praisonai package index set https://my-index.example.com/simple
+
+Options for 'install':
+  --index-url URL       Use custom index URL
+  --extra-index-url URL Add extra index (requires --allow-extra-index)
+  --allow-extra-index   Allow extra index URLs (security risk!)
+  --python PATH         Python interpreter to use
+  --upgrade, -U         Upgrade packages
+  --no-deps             Don't install dependencies
+  --json                Output in JSON format
+
+Options for 'uninstall':
+  --python PATH         Python interpreter to use
+  --yes, -y             Don't ask for confirmation
+  --json                Output in JSON format
+
+Security Notes:
+  - By default, only the primary index is used (PyPI)
+  - Using --extra-index-url can lead to dependency confusion attacks
+  - Always prefer --index-url over --extra-index-url when possible
+""")
+    
+    def _print_error(self, message: str):
+        """Print error message."""
+        print(f"Error: {message}", file=sys.stderr)
+    
+    def _print_warning(self, message: str):
+        """Print warning message."""
+        print(f"Warning: {message}", file=sys.stderr)
+    
+    def _print_success(self, message: str):
+        """Print success message."""
+        print(f"✓ {message}")
+    
+    def _print_json(self, data: Any):
+        """Print JSON output."""
+        print(json.dumps(data, indent=2))
+    
+    def _parse_args(self, args: List[str], spec: Dict[str, Any]) -> Tuple[Dict[str, Any], List[str]]:
+        """Parse command arguments, returning parsed args and positional args."""
+        result = {k: v.get("default") for k, v in spec.items()}
+        positional = []
+        
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            
+            if arg.startswith("--"):
+                key = arg[2:].replace("-", "_")
+                if key in spec:
+                    if spec[key].get("flag"):
+                        result[key] = True
+                    elif i + 1 < len(args):
+                        result[key] = args[i + 1]
+                        i += 1
+                else:
+                    positional.append(arg)
+            elif arg.startswith("-") and len(arg) == 2:
+                # Short flag
+                found = False
+                for key, val in spec.items():
+                    if val.get("short") == arg:
+                        if val.get("flag"):
+                            result[key] = True
+                        elif i + 1 < len(args):
+                            result[key] = args[i + 1]
+                            i += 1
+                        found = True
+                        break
+                if not found:
+                    positional.append(arg)
+            else:
+                positional.append(arg)
+            i += 1
+        
+        return result, positional
+    
+    def _get_python(self, python_path: str = None) -> str:
+        """Get Python interpreter path."""
+        if python_path:
+            return python_path
+        return sys.executable
+    
+    def _run_pip(
+        self,
+        args: List[str],
+        python: str = None,
+        capture: bool = False,
+    ) -> Tuple[int, str, str]:
+        """
+        Run pip command.
+        
+        Args:
+            args: pip arguments
+            python: Python interpreter path
+            capture: Capture output instead of streaming
+            
+        Returns:
+            Tuple of (return_code, stdout, stderr)
+        """
+        python = self._get_python(python)
+        cmd = [python, "-m", "pip"] + args
+        
+        if capture:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                env={**os.environ, "PAGER": "cat"},
+            )
+            return result.returncode, result.stdout, result.stderr
+        else:
+            result = subprocess.run(
+                cmd,
+                env={**os.environ, "PAGER": "cat"},
+            )
+            return result.returncode, "", ""
+    
+    def cmd_install(self, args: List[str]) -> int:
+        """Install Python packages."""
+        spec = {
+            "index_url": {"default": None},
+            "extra_index_url": {"default": None},
+            "allow_extra_index": {"flag": True, "default": False},
+            "python": {"default": None},
+            "upgrade": {"flag": True, "short": "-U", "default": False},
+            "no_deps": {"flag": True, "default": False},
+            "json": {"flag": True, "default": False},
+        }
+        parsed, packages = self._parse_args(args, spec)
+        
+        if not packages:
+            self._print_error("No packages specified")
+            return self.EXIT_VALIDATION_ERROR
+        
+        # Build pip command
+        pip_args = ["install"]
+        
+        # Index URL
+        index_url = parsed["index_url"] or self.config.get("package.index_url", DEFAULT_INDEX_URL)
+        pip_args.extend(["--index-url", index_url])
+        
+        # Extra index URL (with security warning)
+        extra_index = parsed["extra_index_url"]
+        if extra_index:
+            allow_extra = parsed["allow_extra_index"] or self.config.get("package.allow_extra_index", False)
+            if not allow_extra:
+                self._print_error(
+                    "Extra index URLs are disabled by default for security.\n"
+                    "Using multiple indexes can lead to dependency confusion attacks.\n"
+                    "To enable, use --allow-extra-index flag or set package.allow_extra_index=true in config."
+                )
+                return self.EXIT_VALIDATION_ERROR
+            
+            self._print_warning(
+                "⚠️  SECURITY WARNING: Using extra index URLs can lead to dependency confusion attacks!\n"
+                "   An attacker could publish a malicious package with the same name on PyPI.\n"
+                "   Only use this if you trust both indexes and understand the risks."
+            )
+            pip_args.extend(["--extra-index-url", extra_index])
+        
+        # Other options
+        if parsed["upgrade"]:
+            pip_args.append("--upgrade")
+        if parsed["no_deps"]:
+            pip_args.append("--no-deps")
+        
+        # Add packages
+        pip_args.extend(packages)
+        
+        if parsed["json"]:
+            returncode, stdout, stderr = self._run_pip(pip_args, parsed["python"], capture=True)
+            self._print_json({
+                "ok": returncode == 0,
+                "packages": packages,
+                "returncode": returncode,
+                "stdout": stdout,
+                "stderr": stderr,
+            })
+            return returncode
+        else:
+            print(f"Installing: {', '.join(packages)}")
+            returncode, _, _ = self._run_pip(pip_args, parsed["python"])
+            if returncode == 0:
+                self._print_success("Installation complete")
+            return returncode
+    
+    def cmd_uninstall(self, args: List[str]) -> int:
+        """Uninstall Python packages."""
+        spec = {
+            "python": {"default": None},
+            "yes": {"flag": True, "short": "-y", "default": False},
+            "json": {"flag": True, "default": False},
+        }
+        parsed, packages = self._parse_args(args, spec)
+        
+        if not packages:
+            self._print_error("No packages specified")
+            return self.EXIT_VALIDATION_ERROR
+        
+        pip_args = ["uninstall"]
+        if parsed["yes"]:
+            pip_args.append("-y")
+        pip_args.extend(packages)
+        
+        if parsed["json"]:
+            returncode, stdout, stderr = self._run_pip(pip_args, parsed["python"], capture=True)
+            self._print_json({
+                "ok": returncode == 0,
+                "packages": packages,
+                "returncode": returncode,
+                "stdout": stdout,
+                "stderr": stderr,
+            })
+            return returncode
+        else:
+            print(f"Uninstalling: {', '.join(packages)}")
+            returncode, _, _ = self._run_pip(pip_args, parsed["python"])
+            if returncode == 0:
+                self._print_success("Uninstall complete")
+            return returncode
+    
+    def cmd_list(self, args: List[str]) -> int:
+        """List installed packages."""
+        spec = {
+            "python": {"default": None},
+            "json": {"flag": True, "default": False},
+            "outdated": {"flag": True, "default": False},
+        }
+        parsed, _ = self._parse_args(args, spec)
+        
+        pip_args = ["list", "--format=json"]
+        if parsed["outdated"]:
+            pip_args.append("--outdated")
+        
+        returncode, stdout, stderr = self._run_pip(pip_args, parsed["python"], capture=True)
+        
+        if returncode != 0:
+            self._print_error(stderr or "Failed to list packages")
+            return returncode
+        
+        try:
+            packages = json.loads(stdout)
+        except json.JSONDecodeError:
+            packages = []
+        
+        if parsed["json"]:
+            self._print_json({
+                "ok": True,
+                "packages": packages,
+                "count": len(packages),
+            })
+        else:
+            if not packages:
+                print("No packages installed.")
+            else:
+                print(f"{'Package':<30} {'Version':<15}")
+                print("-" * 45)
+                for pkg in packages:
+                    name = pkg.get("name", "")
+                    version = pkg.get("version", "")
+                    print(f"{name:<30} {version:<15}")
+                print(f"\nTotal: {len(packages)} packages")
+        
+        return self.EXIT_SUCCESS
+    
+    def cmd_search(self, args: List[str]) -> int:
+        """Search for packages (best-effort, uses pip search or PyPI API)."""
+        spec = {
+            "json": {"flag": True, "default": False},
+        }
+        parsed, query_parts = self._parse_args(args, spec)
+        
+        if not query_parts:
+            self._print_error("Search query required")
+            return self.EXIT_VALIDATION_ERROR
+        
+        query = " ".join(query_parts)
+        
+        # pip search is deprecated, use PyPI JSON API
+        try:
+            import urllib.request
+            import urllib.error
+            
+            url = f"https://pypi.org/pypi/{query}/json"
+            try:
+                with urllib.request.urlopen(url, timeout=10) as response:
+                    data = json.loads(response.read().decode())
+                    
+                    info = data.get("info", {})
+                    result = {
+                        "name": info.get("name"),
+                        "version": info.get("version"),
+                        "summary": info.get("summary"),
+                        "author": info.get("author"),
+                        "home_page": info.get("home_page"),
+                    }
+                    
+                    if parsed["json"]:
+                        self._print_json({"ok": True, "results": [result]})
+                    else:
+                        print(f"Found: {result['name']} ({result['version']})")
+                        print(f"  {result['summary']}")
+                        if result['home_page']:
+                            print(f"  Homepage: {result['home_page']}")
+                    
+                    return self.EXIT_SUCCESS
+                    
+            except urllib.error.HTTPError as e:
+                if e.code == 404:
+                    if parsed["json"]:
+                        self._print_json({"ok": True, "results": [], "message": "No exact match found"})
+                    else:
+                        print(f"No exact match for '{query}'")
+                        print("Try: pip search <query> (if available) or browse https://pypi.org")
+                    return self.EXIT_SUCCESS
+                raise
+                
+        except Exception as e:
+            if parsed["json"]:
+                self._print_json({"ok": False, "error": str(e)})
+            else:
+                self._print_error(f"Search failed: {e}")
+            return self.EXIT_NETWORK_ERROR
+    
+    def cmd_index(self, args: List[str]) -> int:
+        """Manage package indexes."""
+        if not args:
+            return self._index_show([])
+        
+        subcommand = args[0]
+        remaining = args[1:]
+        
+        subcommands = {
+            "show": self._index_show,
+            "set": self._index_set,
+            "add": self._index_add,
+            "remove": self._index_remove,
+        }
+        
+        handler = subcommands.get(subcommand)
+        if handler:
+            return handler(remaining)
+        
+        self._print_error(f"Unknown index subcommand: {subcommand}")
+        return self.EXIT_VALIDATION_ERROR
+    
+    def _index_show(self, args: List[str]) -> int:
+        """Show current index configuration."""
+        spec = {
+            "json": {"flag": True, "default": False},
+        }
+        parsed, _ = self._parse_args(args, spec)
+        
+        index_url = self.config.get("package.index_url", DEFAULT_INDEX_URL)
+        extra_urls = self.config.get("package.extra_index_urls", [])
+        allow_extra = self.config.get("package.allow_extra_index", False)
+        
+        if parsed["json"]:
+            self._print_json({
+                "ok": True,
+                "index_url": index_url,
+                "extra_index_urls": extra_urls,
+                "allow_extra_index": allow_extra,
+            })
+        else:
+            print(f"Primary Index: {index_url}")
+            if extra_urls:
+                print(f"Extra Indexes: {', '.join(extra_urls)}")
+            print(f"Allow Extra Index: {'yes' if allow_extra else 'no'}")
+        
+        return self.EXIT_SUCCESS
+    
+    def _index_set(self, args: List[str]) -> int:
+        """Set primary index URL."""
+        if not args:
+            self._print_error("Index URL required")
+            return self.EXIT_VALIDATION_ERROR
+        
+        url = args[0]
+        
+        # Validate URL format
+        if not url.startswith(("http://", "https://")):
+            self._print_error("Index URL must start with http:// or https://")
+            return self.EXIT_VALIDATION_ERROR
+        
+        self.config.save_index(url)
+        self._print_success(f"Primary index set to: {url}")
+        
+        return self.EXIT_SUCCESS
+    
+    def _index_add(self, args: List[str]) -> int:
+        """Add extra index URL."""
+        self._print_warning(
+            "Adding extra index URLs is a security risk!\n"
+            "This can lead to dependency confusion attacks.\n"
+            "Consider using --index-url to switch indexes instead."
+        )
+        
+        if not args:
+            self._print_error("Index URL required")
+            return self.EXIT_VALIDATION_ERROR
+        
+        # For now, just print instructions
+        print("\nTo use extra index, run:")
+        print(f"  praisonai install <pkg> --extra-index-url {args[0]} --allow-extra-index")
+        
+        return self.EXIT_SUCCESS
+    
+    def _index_remove(self, args: List[str]) -> int:
+        """Remove extra index URL."""
+        print("Extra index URLs are not persisted by default.")
+        print("To reset to PyPI, run:")
+        print(f"  praisonai package index set {DEFAULT_INDEX_URL}")
+        
+        return self.EXIT_SUCCESS

src/praisonai/praisonai/cli/features/performance.py

@@ -0,0 +1,308 @@
+"""
+Performance Handler for CLI.
+
+Provides performance benchmarking and regression testing.
+Usage: praisonai perf [benchmark|check|import-time|memory]
+"""
+
+import os
+import sys
+import subprocess
+from typing import Any, Dict, Tuple
+from .base import FlagHandler
+
+
+class PerformanceHandler(FlagHandler):
+    """
+    Handler for performance benchmarking commands.
+    
+    Commands:
+        praisonai perf benchmark     - Run full performance benchmark
+        praisonai perf import-time   - Measure import time only
+        praisonai perf memory        - Measure memory usage only
+        praisonai perf check         - Run regression check against targets
+        praisonai perf lazy-check    - Verify lazy imports are working
+    """
+    
+    # Performance targets
+    IMPORT_TIME_TARGET_MS = 200
+    IMPORT_TIME_HARD_FAIL_MS = 300
+    MEMORY_TARGET_MB = 30
+    MEMORY_HARD_FAIL_MB = 45
+    
+    @property
+    def feature_name(self) -> str:
+        return "performance"
+    
+    @property
+    def flag_name(self) -> str:
+        return "perf"
+    
+    @property
+    def flag_help(self) -> str:
+        return "Run performance benchmarks and regression checks"
+    
+    def check_dependencies(self) -> Tuple[bool, str]:
+        """Check if performance testing is available."""
+        return True, ""
+    
+    def measure_import_time(self, runs: int = 5) -> Dict[str, Any]:
+        """
+        Measure import time for praisonaiagents.
+        
+        Args:
+            runs: Number of runs to average
+            
+        Returns:
+            Dict with timing statistics
+        """
+        times = []
+        
+        for _ in range(runs):
+            code = """
+import time
+start = time.perf_counter()
+import praisonaiagents
+end = time.perf_counter()
+print(f"{(end - start) * 1000:.1f}")
+"""
+            result = subprocess.run(
+                [sys.executable, "-c", code],
+                capture_output=True,
+                text=True,
+                env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"}
+            )
+            if result.returncode == 0:
+                try:
+                    times.append(float(result.stdout.strip()))
+                except ValueError:
+                    pass
+        
+        if not times:
+            return {"error": "Failed to measure import time"}
+        
+        times.sort()
+        median = times[len(times) // 2]
+        
+        return {
+            "times": times,
+            "min": min(times),
+            "max": max(times),
+            "median": median,
+            "mean": sum(times) / len(times),
+            "pass": median < self.IMPORT_TIME_TARGET_MS,
+            "hard_fail": median > self.IMPORT_TIME_HARD_FAIL_MS
+        }
+    
+    def measure_memory(self) -> Dict[str, Any]:
+        """
+        Measure memory usage after importing praisonaiagents.
+        
+        Returns:
+            Dict with memory statistics
+        """
+        code = """
+import tracemalloc
+tracemalloc.start()
+import praisonaiagents
+current, peak = tracemalloc.get_traced_memory()
+tracemalloc.stop()
+print(f"{current / 1024 / 1024:.1f},{peak / 1024 / 1024:.1f}")
+"""
+        result = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"}
+        )
+        
+        if result.returncode != 0:
+            return {"error": f"Failed to measure memory: {result.stderr}"}
+        
+        try:
+            current, peak = result.stdout.strip().split(",")
+            current_mb = float(current)
+            peak_mb = float(peak)
+            
+            return {
+                "current_mb": current_mb,
+                "peak_mb": peak_mb,
+                "pass": current_mb < self.MEMORY_TARGET_MB,
+                "hard_fail": current_mb > self.MEMORY_HARD_FAIL_MB
+            }
+        except (ValueError, IndexError) as e:
+            return {"error": f"Failed to parse memory output: {e}"}
+    
+    def check_lazy_imports(self) -> Dict[str, bool]:
+        """
+        Check that heavy dependencies are not loaded at import time.
+        
+        Returns:
+            Dict mapping module name to whether it's lazy (True = good)
+        """
+        heavy_modules = ["litellm", "chromadb", "mem0", "requests"]
+        results = {}
+        
+        for module in heavy_modules:
+            code = f"""
+import sys
+# Clear any cached imports
+for key in list(sys.modules.keys()):
+    if key.startswith('{module}'):
+        del sys.modules[key]
+
+import praisonaiagents
+print('{module}' not in sys.modules)
+"""
+            result = subprocess.run(
+                [sys.executable, "-c", code],
+                capture_output=True,
+                text=True,
+                env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"}
+            )
+            
+            if result.returncode == 0:
+                results[module] = result.stdout.strip() == "True"
+            else:
+                results[module] = False
+        
+        return results
+    
+    def run_benchmark(self, verbose: bool = True) -> Dict[str, Any]:
+        """
+        Run full performance benchmark.
+        
+        Args:
+            verbose: Print results to console
+            
+        Returns:
+            Dict with all benchmark results
+        """
+        results = {}
+        
+        if verbose:
+            print("=" * 60)
+            print("PraisonAI Agents Performance Benchmark")
+            print("=" * 60)
+        
+        # Import time
+        if verbose:
+            print("\n[1/3] Measuring import time...")
+        results["import_time"] = self.measure_import_time()
+        
+        if verbose and "error" not in results["import_time"]:
+            median = results["import_time"]["median"]
+            status = "PASS" if results["import_time"]["pass"] else "FAIL"
+            print(f"      Median: {median:.1f}ms [{status}]")
+        
+        # Memory
+        if verbose:
+            print("\n[2/3] Measuring memory usage...")
+        results["memory"] = self.measure_memory()
+        
+        if verbose and "error" not in results["memory"]:
+            current = results["memory"]["current_mb"]
+            status = "PASS" if results["memory"]["pass"] else "WARN" if not results["memory"]["hard_fail"] else "FAIL"
+            print(f"      Current: {current:.1f}MB [{status}]")
+        
+        # Lazy imports
+        if verbose:
+            print("\n[3/3] Checking lazy imports...")
+        results["lazy_imports"] = self.check_lazy_imports()
+        
+        if verbose:
+            all_lazy = all(results["lazy_imports"].values())
+            status = "PASS" if all_lazy else "FAIL"
+            print(f"      All lazy: {all_lazy} [{status}]")
+            for module, is_lazy in results["lazy_imports"].items():
+                symbol = "✓" if is_lazy else "✗"
+                print(f"        {symbol} {module}")
+        
+        # Overall
+        overall_pass = (
+            results["import_time"].get("pass", False) and
+            not results["memory"].get("hard_fail", True) and
+            all(results["lazy_imports"].values())
+        )
+        results["overall_pass"] = overall_pass
+        
+        if verbose:
+            print("\n" + "=" * 60)
+            status = "PASS" if overall_pass else "FAIL"
+            print(f"Overall: [{status}]")
+            print("=" * 60)
+        
+        return results
+    
+    def run_check(self) -> bool:
+        """
+        Run regression check against targets.
+        
+        Returns:
+            True if all checks pass
+        """
+        results = self.run_benchmark(verbose=True)
+        return results.get("overall_pass", False)
+    
+    def handle(self, subcommand: str = "benchmark", **kwargs) -> Any:
+        """
+        Handle performance subcommands.
+        
+        Args:
+            subcommand: One of benchmark, import-time, memory, check, lazy-check
+            **kwargs: Additional options
+            
+        Returns:
+            Results dict or bool
+        """
+        if subcommand == "benchmark":
+            return self.run_benchmark(verbose=True)
+        elif subcommand == "import-time":
+            result = self.measure_import_time()
+            if "error" not in result:
+                print(f"Import time: {result['median']:.1f}ms (median)")
+                print(f"Target: <{self.IMPORT_TIME_TARGET_MS}ms")
+                print(f"Status: {'PASS' if result['pass'] else 'FAIL'}")
+            return result
+        elif subcommand == "memory":
+            result = self.measure_memory()
+            if "error" not in result:
+                print(f"Memory: {result['current_mb']:.1f}MB")
+                print(f"Target: <{self.MEMORY_TARGET_MB}MB")
+                print(f"Status: {'PASS' if result['pass'] else 'WARN' if not result['hard_fail'] else 'FAIL'}")
+            return result
+        elif subcommand == "check":
+            return self.run_check()
+        elif subcommand == "lazy-check":
+            results = self.check_lazy_imports()
+            print("Lazy Import Check:")
+            for module, is_lazy in results.items():
+                status = "LAZY (good)" if is_lazy else "EAGER (bad)"
+                print(f"  {module}: {status}")
+            return all(results.values())
+        else:
+            print(f"Unknown subcommand: {subcommand}")
+            print("Available: benchmark, import-time, memory, check, lazy-check")
+            return False
+
+
+# Convenience function for CLI integration
+def run_performance_command(args) -> int:
+    """
+    Run performance command from CLI args.
+    
+    Args:
+        args: Parsed CLI arguments
+        
+    Returns:
+        Exit code (0 for success)
+    """
+    handler = PerformanceHandler()
+    subcommand = getattr(args, 'perf_command', 'benchmark')
+    result = handler.handle(subcommand)
+    
+    if isinstance(result, bool):
+        return 0 if result else 1
+    elif isinstance(result, dict):
+        return 0 if result.get("overall_pass", result.get("pass", False)) else 1
+    return 0