Release v2.7.2

Release v2.7.2 - update doctor examples with improved check listing and CI formatting
- 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
2026-11-08 01:08:39 -10:00 · 2025-12-29 11:40:55 +00:00 · 2025-12-29 02:19:16 +00:00 · 2025-12-29 02:15:51 +00:00 · 2025-12-29 01:33:40 +00:00 · 2025-12-29 00:42:47 +00:00
497 changed files with 88105 additions and 1762 deletions
@@ -80,4 +80,6 @@ CopilotKit*
 issue_details.json

 # MCP Registry tokens
-.mcpregistry_*
+.mcpregistry_*
+
+*.log
@@ -35,46 +35,108 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,

 ---

+> **Quick Paths:**
+> - 🚀 **New here?** → [Quick Start](#-quick-start)
+> - 📦 **Installing?** → [Installation](#-installation)
+> - 💻 **Python SDK?** → [Python Examples](#-using-python-code)
+> - 🎯 **CLI user?** → [CLI Reference](#-cli--no-code-interface)
+> - 🔧 **Need config?** → [Configuration](#-configuration--integration)
+> - 🤝 **Contributing?** → [Development](#-development)
+
+---
+
 ## 📑 Table of Contents

+### Getting Started
 - [⚡ Performance](#-performance)
 - [🚀 Quick Start](#-quick-start)
 - [📦 Installation](#-installation)
  - [Python SDK](#python-sdk)
  - [JavaScript SDK](#javascript-sdk)
- [💻 Usage](#-usage)
-  - [Python Code Examples](#python-code-examples)
-  - [CLI / No-Code Interface](#cli--no-code-interface)
-  - [JavaScript Code Examples](#javascript-code-examples)
+  - [Environment Variables](#environment-variables)
+
+### Core Concepts
 - [✨ Key Features](#-key-features)
 - [🌐 Supported Providers](#-supported-providers)
+
+### Python SDK
+- [📘 Python Examples](#-using-python-code)
+  - [1. Single Agent](#1-single-agent)
+  - [2. Multi Agents](#2-multi-agents)
+  - [3. Planning Mode](#3-agent-with-planning-mode)
+  - [4. Deep Research](#4-deep-research-agent)
+  - [5. Query Rewriter](#5-query-rewriter-agent)
+  - [6. Agent Memory](#6-agent-memory-zero-dependencies)
+  - [7. Rules & Instructions](#7-rules--instructions)
+  - [8. Auto-Generated Memories](#8-auto-generated-memories)
+  - [9. Agentic Workflows](#9-agentic-workflows)
+  - [10. Hooks](#10-hooks)
+  - [11. Shadow Git Checkpoints](#11-shadow-git-checkpoints)
+  - [12. Background Tasks](#12-background-tasks)
+  - [13. Policy Engine](#13-policy-engine)
+  - [14. Thinking Budgets](#14-thinking-budgets)
+  - [15. Output Styles](#15-output-styles)
+  - [16. Context Compaction](#16-context-compaction)
+  - [17. Field Names Reference](#17-field-names-reference-a-i-g-s)
+  - [18. Extended agents.yaml](#18-extended-agentsyaml-with-workflow-patterns)
+  - [19. MCP Protocol](#19-mcp-model-context-protocol)
+  - [20. A2A Protocol](#20-a2a-agent2agent-protocol)
 - [🛠️ Custom Tools](#️-custom-tools)
+
+### JavaScript SDK
+- [💻 JavaScript Examples](#-using-javascript-code)
+
+### CLI Reference
+- [🎯 CLI Overview](#-cli--no-code-interface)
+  - [Auto Mode](#auto-mode)
+  - [Interactive Mode](#interactive-mode-cli)
+  - [Deep Research CLI](#deep-research-cli)
+  - [Planning Mode CLI](#planning-mode-cli)
+  - [Memory CLI](#memory-cli)
+  - [Workflow CLI](#workflow-cli)
+  - [Knowledge CLI](#knowledge-cli)
+  - [Session CLI](#session-cli)
+  - [Tools CLI](#tools-cli)
+  - [MCP Config CLI](#mcp-config-cli)
+  - [External Agents CLI](#external-agents-cli)
+- [CLI Features Summary](#cli-features)
+
+### Configuration
 - [🔧 Configuration & Integration](#-configuration--integration)
  - [Ollama Integration](#ollama-integration)
  - [Groq Integration](#groq-integration)
  - [100+ Models Support](#100-models-support)
- [📋 Workflows](#-workflows)
-  - [Workflow Patterns](#workflow-patterns)
-  - [YAML Configuration](#yaml-configuration)
-  - [Agents Playbook](#agents-playbook)
- [🧠 Memory & Context](#-memory--context)
+- [📋 Agents Playbook](#-agents-playbook)
+
+### Advanced Features
 - [🔬 Advanced Features](#-advanced-features)
  - [Research & Intelligence](#research--intelligence)
+  - [Memory & Caching](#memory--caching)
  - [Planning & Workflows](#planning--workflows)
  - [Specialised Agents](#specialised-agents)
  - [MCP Protocol](#mcp-protocol)
  - [A2A & A2UI Protocols](#a2a--a2ui-protocols)
  - [Safety & Control](#safety--control)
  - [Developer Tools](#developer-tools)
+
+### Architecture
 - [📊 Process Types & Patterns](#-process-types--patterns)
  - [Sequential Process](#sequential-process)
  - [Hierarchical Process](#hierarchical-process)
  - [Workflow Process](#workflow-process)
  - [Agentic Patterns](#agentic-patterns)
+
+### Data & Persistence
+- [💾 Persistence (Databases)](#-persistence-databases)
+- [📚 Knowledge & Retrieval (RAG)](#-knowledge--retrieval-rag)
+- [🔧 Tools Table](#-tools-table)
+
+### Learning & Community
 - [🎓 Video Tutorials](#-video-tutorials)
 - [⭐ Star History](#-star-history)
 - [👥 Contributing](#-contributing)
 - [🔧 Development](#-development)
+- [❓ FAQ & Troubleshooting](#-faq--troubleshooting)

 ---

@@ -143,6 +205,30 @@ pip install praisonai
 npm install praisonai
 ```

+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes* | OpenAI API key |
+| `ANTHROPIC_API_KEY` | No | Anthropic Claude API key |
+| `GOOGLE_API_KEY` | No | Google Gemini API key |
+| `GROQ_API_KEY` | No | Groq API key |
+| `OPENAI_BASE_URL` | No | Custom API endpoint (for Ollama, Groq, etc.) |
+
+> *At least one LLM provider API key is required.
+
+```bash
+# Set your API key
+export OPENAI_API_KEY=your_key_here
+
+# For Ollama (local models)
+export OPENAI_BASE_URL=http://localhost:11434/v1
+
+# For Groq
+export OPENAI_API_KEY=your_groq_key
+export OPENAI_BASE_URL=https://api.groq.com/openai/v1
+```
+
 ---

 ## 💻 Usage
@@ -169,137 +255,263 @@ npm install praisonai

 ## ✨ Key Features

+<details open>
+<summary><strong>🤖 Core Agents</strong></summary>
+
 | Feature | Code | Docs |
 |---------|:----:|:----:|
-| **🤖 Core Agents** | | |
-| ↳ Single Agent | [Example](examples/python/agents/single-agent.py) | [📖](https://docs.praison.ai/agents/single) |
-| ↳ Multi Agents | [Example](examples/python/general/mini_agents_example.py) | [📖](https://docs.praison.ai/concepts/agents) |
-| ↳ Auto Agents | [Example](examples/python/general/auto_agents_example.py) | [📖](https://docs.praison.ai/features/autoagents) |
-| ↳ Self Reflection AI Agents | [Example](examples/python/concepts/self-reflection-details.py) | [📖](https://docs.praison.ai/features/selfreflection) |
-| ↳ Reasoning AI Agents | [Example](examples/python/concepts/reasoning-extraction.py) | [📖](https://docs.praison.ai/features/reasoning) |
-| ↳ Multi Modal AI Agents | [Example](examples/python/general/multimodal.py) | [📖](https://docs.praison.ai/features/multimodal) |
-| **🔄 Workflows** | | |
-| ↳ Simple Workflow | [Example](examples/python/workflows/simple_workflow.py) | [📖](https://docs.praison.ai/features/workflows) |
-| ↳ Workflow with Agents | [Example](examples/python/workflows/workflow_with_agents.py) | [📖](https://docs.praison.ai/features/workflows) |
-| ↳ Agentic Routing (`route()`) | [Example](examples/python/workflows/workflow_routing.py) | [📖](https://docs.praison.ai/features/routing) |
-| ↳ Parallel Execution (`parallel()`) | [Example](examples/python/workflows/workflow_parallel.py) | [📖](https://docs.praison.ai/features/parallelisation) |
-| ↳ Loop over List/CSV (`loop()`) | [Example](examples/python/workflows/workflow_loop_csv.py) | [📖](https://docs.praison.ai/features/repetitive) |
-| ↳ Evaluator-Optimizer (`repeat()`) | [Example](examples/python/workflows/workflow_repeat.py) | [📖](https://docs.praison.ai/features/evaluator-optimiser) |
-| ↳ Conditional Steps | [Example](examples/python/workflows/workflow_conditional.py) | [📖](https://docs.praison.ai/features/workflows) |
-| ↳ Workflow Branching | [Example](examples/python/workflows/workflow_branching.py) | [📖](https://docs.praison.ai/features/workflows) |
-| ↳ Workflow Early Stop | [Example](examples/python/workflows/workflow_early_stop.py) | [📖](https://docs.praison.ai/features/workflows) |
-| ↳ Workflow Checkpoints | [Example](examples/python/workflows/workflow_checkpoints.py) | [📖](https://docs.praison.ai/features/workflows) |
-| **💻 Code & Development** | | |
-| ↳ Code Interpreter Agents | [Example](examples/python/agents/code-agent.py) | [📖](https://docs.praison.ai/features/codeagent) |
-| ↳ AI Code Editing Tools | [Example](examples/python/code/code_editing_example.py) | [📖](https://docs.praison.ai/code/editing) |
-| ↳ External Agents (All) | [Example](examples/python/code/external_agents_example.py) | [📖](https://docs.praison.ai/code/external-agents) |
-| ↳ Claude Code CLI | [Example](examples/python/code/claude_code_example.py) | [📖](https://docs.praison.ai/code/claude-code) |
-| ↳ Gemini CLI | [Example](examples/python/code/gemini_cli_example.py) | [📖](https://docs.praison.ai/code/gemini-cli) |
-| ↳ Codex CLI | [Example](examples/python/code/codex_cli_example.py) | [📖](https://docs.praison.ai/code/codex-cli) |
-| ↳ Cursor CLI | [Example](examples/python/code/cursor_cli_example.py) | [📖](https://docs.praison.ai/code/cursor-cli) |
-| **🧠 Memory & Knowledge** | | |
-| ↳ Memory (Short & Long Term) | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/concepts/memory) |
-| ↳ File-Based Memory | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/concepts/memory) |
-| ↳ Claude Memory Tool | [Example](#claude-memory-tool-cli) | [📖](https://docs.praison.ai/features/claude-memory-tool) |
-| ↳ Add Custom Knowledge | [Example](examples/python/concepts/knowledge-agents.py) | [📖](https://docs.praison.ai/features/knowledge) |
-| ↳ RAG Agents | [Example](examples/python/concepts/rag-agents.py) | [📖](https://docs.praison.ai/features/rag) |
-| ↳ Chat with PDF Agents | [Example](examples/python/concepts/chat-with-pdf.py) | [📖](https://docs.praison.ai/features/chat-with-pdf) |
-| **🔬 Research & Intelligence** | | |
-| ↳ Deep Research Agents | [Example](examples/python/agents/research-agent.py) | [📖](https://docs.praison.ai/agents/deep-research) |
-| ↳ Query Rewriter Agent | [Example](#5-query-rewriter-agent) | [📖](https://docs.praison.ai/agents/query-rewriter) |
-| ↳ Native Web Search | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/agents/websearch) |
-| ↳ Built-in Search Tools | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/tools/tavily) |
-| ↳ Unified Web Search | [Example](src/praisonai-agents/examples/web_search_example.py) | [📖](https://docs.praison.ai/tools/web-search) |
-| ↳ Web Fetch (Anthropic) | [Example](#web-search-web-fetch--prompt-caching) | [📖](https://docs.praison.ai/features/model-capabilities) |
-| **📋 Planning & Execution** | | |
-| ↳ Planning Mode | [Example](examples/python/agents/planning-agent.py) | [📖](https://docs.praison.ai/features/planning-mode) |
-| ↳ Planning Tools | [Example](#3-agent-with-planning-mode) | [📖](https://docs.praison.ai/features/planning-mode) |
-| ↳ Planning Reasoning | [Example](#3-agent-with-planning-mode) | [📖](https://docs.praison.ai/features/planning-mode) |
-| ↳ Prompt Chaining | [Example](examples/python/general/prompt_chaining.py) | [📖](https://docs.praison.ai/features/promptchaining) |
-| ↳ Evaluator Optimiser | [Example](examples/python/general/evaluator-optimiser.py) | [📖](https://docs.praison.ai/features/evaluator-optimiser) |
-| ↳ Orchestrator Workers | [Example](examples/python/general/orchestrator-workers.py) | [📖](https://docs.praison.ai/features/orchestrator-worker) |
-| **👥 Specialized Agents** | | |
-| ↳ Data Analyst Agent | [Example](examples/python/agents/data-analyst-agent.py) | [📖](https://docs.praison.ai/agents/data-analyst) |
-| ↳ Finance Agent | [Example](examples/python/agents/finance-agent.py) | [📖](https://docs.praison.ai/agents/finance) |
-| ↳ Shopping Agent | [Example](examples/python/agents/shopping-agent.py) | [📖](https://docs.praison.ai/agents/shopping) |
-| ↳ Recommendation Agent | [Example](examples/python/agents/recommendation-agent.py) | [📖](https://docs.praison.ai/agents/recommendation) |
-| ↳ Wikipedia Agent | [Example](examples/python/agents/wikipedia-agent.py) | [📖](https://docs.praison.ai/agents/wikipedia) |
-| ↳ Programming Agent | [Example](examples/python/agents/programming-agent.py) | [📖](https://docs.praison.ai/agents/programming) |
-| ↳ Math Agents | [Example](examples/python/agents/math-agent.py) | [📖](https://docs.praison.ai/features/mathagent) |
-| ↳ Markdown Agent | [Example](examples/python/agents/markdown-agent.py) | [📖](https://docs.praison.ai/agents/markdown) |
-| ↳ Prompt Expander Agent | [Example](#prompt-expansion) | [📖](https://docs.praison.ai/agents/prompt-expander) |
-| **🎨 Media & Multimodal** | | |
-| ↳ Image Generation Agent | [Example](examples/python/image/image-agent.py) | [📖](https://docs.praison.ai/features/image-generation) |
-| ↳ Image to Text Agent | [Example](examples/python/agents/image-to-text-agent.py) | [📖](https://docs.praison.ai/agents/image-to-text) |
-| ↳ Video Agent | [Example](examples/python/agents/video-agent.py) | [📖](https://docs.praison.ai/agents/video) |
-| ↳ Camera Integration | [Example](examples/python/camera/) | [📖](https://docs.praison.ai/features/camera-integration) |
-| **🔌 Protocols & Integration** | | |
-| ↳ MCP Transports | [Example](examples/python/mcp/mcp-transports-overview.py) | [📖](https://docs.praison.ai/mcp/transports) |
-| ↳ WebSocket MCP | [Example](examples/python/mcp/websocket-mcp.py) | [📖](https://docs.praison.ai/mcp/sse-transport) |
-| ↳ MCP Security | [Example](examples/python/mcp/mcp-security.py) | [📖](https://docs.praison.ai/mcp/transports) |
-| ↳ MCP Resumability | [Example](examples/python/mcp/mcp-resumability.py) | [📖](https://docs.praison.ai/mcp/sse-transport) |
-| ↳ MCP Config Management | [Example](#mcp-config-cli) | [📖](https://docs.praison.ai/docs/cli/mcp) |
-| ↳ LangChain Integrated Agents | [Example](examples/python/general/langchain_example.py) | [📖](https://docs.praison.ai/features/langchain) |
-| **🛡️ Safety & Control** | | |
-| ↳ Guardrails | [Example](examples/python/guardrails/comprehensive-guardrails-example.py) | [📖](https://docs.praison.ai/features/guardrails) |
-| ↳ Human Approval | [Example](examples/python/general/human_approval_example.py) | [📖](https://docs.praison.ai/features/approval) |
-| ↳ Rules & Instructions | [Example](#6-rules--instructions) | [📖](https://docs.praison.ai/features/rules) |
-| **⚙️ Advanced Features** | | |
-| ↳ Async & Parallel Processing | [Example](examples/python/general/async_example.py) | [📖](https://docs.praison.ai/features/async) |
-| ↳ Parallelisation | [Example](examples/python/general/parallelisation.py) | [📖](https://docs.praison.ai/features/parallelisation) |
-| ↳ Repetitive Agents | [Example](examples/python/concepts/repetitive-agents.py) | [📖](https://docs.praison.ai/features/repetitive) |
-| ↳ Agent Handoffs | [Example](examples/python/handoff/handoff_basic.py) | [📖](https://docs.praison.ai/features/handoffs) |
-| ↳ Stateful Agents | [Example](examples/python/stateful/workflow-state-example.py) | [📖](https://docs.praison.ai/features/stateful-agents) |
-| ↳ Autonomous Workflow | [Example](examples/python/general/autonomous-agent.py) | [📖](https://docs.praison.ai/features/autonomous-workflow) |
-| ↳ Structured Output Agents | [Example](examples/python/general/structured_agents_example.py) | [📖](https://docs.praison.ai/features/structured) |
-| ↳ Model Router | [Example](examples/python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/features/model-router) |
-| ↳ Prompt Caching | [Example](#web-search-web-fetch--prompt-caching) | [📖](https://docs.praison.ai/features/model-capabilities) |
-| ↳ Fast Context | [Example](examples/context/00_agent_fast_context_basic.py) | [📖](https://docs.praison.ai/features/fast-context) |
-| **🛠️ Tools & Configuration** | | |
-| ↳ 100+ Custom Tools | [Example](examples/python/general/tools_example.py) | [📖](https://docs.praison.ai/tools/tools) |
-| ↳ YAML Configuration | [Example](examples/cookbooks/yaml/secondary_market_research_agents.yaml) | [📖](https://docs.praison.ai/developers/agents-playbook) |
-| ↳ 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/models) |
-| ↳ Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/features/callbacks) |
-| ↳ Hooks | [Example](#9-hooks) | [📖](https://docs.praison.ai/features/hooks) |
-| ↳ Shadow Git Checkpoints | [Example](#10-shadow-git-checkpoints) | [📖](https://docs.praison.ai/features/checkpoints) |
-| ↳ Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/features/background-tasks) |
-| ↳ Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/features/policy-engine) |
-| ↳ Thinking Budgets | [Example](examples/thinking/basic_thinking.py) | [📖](https://docs.praison.ai/features/thinking-budgets) |
-| ↳ Output Styles | [Example](examples/output/basic_output.py) | [📖](https://docs.praison.ai/features/output-styles) |
-| ↳ Context Compaction | [Example](examples/compaction/basic_compaction.py) | [📖](https://docs.praison.ai/features/context-compaction) |
-| **📊 Monitoring & Management** | | |
-| ↳ Sessions Management | [Example](examples/python/sessions/comprehensive-session-management.py) | [📖](https://docs.praison.ai/features/sessions) |
-| ↳ Auto-Save Sessions | [Example](#session-management-python) | [📖](https://docs.praison.ai/docs/cli/session) |
-| ↳ History in Context | [Example](#session-management-python) | [📖](https://docs.praison.ai/docs/cli/session) |
-| ↳ Telemetry | [Example](examples/python/telemetry/production-telemetry-example.py) | [📖](https://docs.praison.ai/features/telemetry) |
-| ↳ Project Docs (.praison/docs/) | [Example](#docs-cli) | [📖](https://docs.praison.ai/docs/cli/docs) |
-| ↳ AI Commit Messages | [Example](#ai-commit-cli) | [📖](https://docs.praison.ai/docs/cli/commit) |
-| ↳ @Mentions in Prompts | [Example](#mentions-in-prompts) | [📖](https://docs.praison.ai/docs/cli/mentions) |
-| **🖥️ CLI Features** | | |
-| ↳ Slash Commands | [Example](examples/python/cli/slash_commands_example.py) | [📖](https://docs.praison.ai/docs/cli/slash-commands) |
-| ↳ Autonomy Modes | [Example](examples/python/cli/autonomy_modes_example.py) | [📖](https://docs.praison.ai/docs/cli/autonomy-modes) |
-| ↳ Cost Tracking | [Example](examples/python/cli/cost_tracking_example.py) | [📖](https://docs.praison.ai/docs/cli/cost-tracking) |
-| ↳ Repository Map | [Example](examples/python/cli/repo_map_example.py) | [📖](https://docs.praison.ai/docs/cli/repo-map) |
-| ↳ Interactive TUI | [Example](examples/python/cli/interactive_tui_example.py) | [📖](https://docs.praison.ai/docs/cli/interactive-tui) |
-| ↳ Git Integration | [Example](examples/python/cli/git_integration_example.py) | [📖](https://docs.praison.ai/docs/cli/git-integration) |
-| ↳ Sandbox Execution | [Example](examples/python/cli/sandbox_execution_example.py) | [📖](https://docs.praison.ai/docs/cli/sandbox-execution) |
-| ↳ CLI Compare | [Example](examples/compare/cli_compare_basic.py) | [📖](https://docs.praison.ai/docs/cli/compare) |
-| ↳ Profile/Benchmark | [Example](#profile-benchmark) | [📖](https://docs.praison.ai/docs/cli/profile) |
-| ↳ Auto Mode | [Example](#auto-mode) | [📖](https://docs.praison.ai/docs/cli/auto) |
-| ↳ Init | [Example](#init) | [📖](https://docs.praison.ai/docs/cli/init) |
-| ↳ File Input | [Example](#file-input) | [📖](https://docs.praison.ai/docs/cli/file-input) |
-| ↳ Final Agent | [Example](#final-agent) | [📖](https://docs.praison.ai/docs/cli/final-agent) |
-| ↳ Max Tokens | [Example](#max-tokens) | [📖](https://docs.praison.ai/docs/cli/max-tokens) |
-| **🧪 Evaluation** | | |
-| ↳ Accuracy Evaluation | [Example](examples/eval/accuracy_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
-| ↳ Performance Evaluation | [Example](examples/eval/performance_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
-| ↳ Reliability Evaluation | [Example](examples/eval/reliability_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
-| ↳ Criteria Evaluation | [Example](examples/eval/criteria_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
-| **🎯 Agent Skills** | | |
-| ↳ Skills Management | [Example](examples/skills/basic_skill_usage.py) | [📖](https://docs.praison.ai/features/skills) |
-| ↳ Custom Skills | [Example](examples/skills/custom_skill_example.py) | [📖](https://docs.praison.ai/features/skills) |
-| **⏰ 24/7 Scheduling** | | |
-| ↳ Agent Scheduler | [Example](examples/python/scheduled_agents/news_checker_live.py) | [📖](https://docs.praison.ai/docs/cli/scheduler) |
+| Single Agent | [Example](examples/python/agents/single-agent.py) | [📖](https://docs.praison.ai/agents/single) |
+| Multi Agents | [Example](examples/python/general/mini_agents_example.py) | [📖](https://docs.praison.ai/concepts/agents) |
+| Auto Agents | [Example](examples/python/general/auto_agents_example.py) | [📖](https://docs.praison.ai/features/autoagents) |
+| Self Reflection AI Agents | [Example](examples/python/concepts/self-reflection-details.py) | [📖](https://docs.praison.ai/features/selfreflection) |
+| Reasoning AI Agents | [Example](examples/python/concepts/reasoning-extraction.py) | [📖](https://docs.praison.ai/features/reasoning) |
+| Multi Modal AI Agents | [Example](examples/python/general/multimodal.py) | [📖](https://docs.praison.ai/features/multimodal) |
+
+</details>
+
+<details>
+<summary><strong>🔄 Workflows</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Simple Workflow | [Example](examples/python/workflows/simple_workflow.py) | [📖](https://docs.praison.ai/features/workflows) |
+| Workflow with Agents | [Example](examples/python/workflows/workflow_with_agents.py) | [📖](https://docs.praison.ai/features/workflows) |
+| Agentic Routing (`route()`) | [Example](examples/python/workflows/workflow_routing.py) | [📖](https://docs.praison.ai/features/routing) |
+| Parallel Execution (`parallel()`) | [Example](examples/python/workflows/workflow_parallel.py) | [📖](https://docs.praison.ai/features/parallelisation) |
+| Loop over List/CSV (`loop()`) | [Example](examples/python/workflows/workflow_loop_csv.py) | [📖](https://docs.praison.ai/features/repetitive) |
+| Evaluator-Optimizer (`repeat()`) | [Example](examples/python/workflows/workflow_repeat.py) | [📖](https://docs.praison.ai/features/evaluator-optimiser) |
+| Conditional Steps | [Example](examples/python/workflows/workflow_conditional.py) | [📖](https://docs.praison.ai/features/workflows) |
+| Workflow Branching | [Example](examples/python/workflows/workflow_branching.py) | [📖](https://docs.praison.ai/features/workflows) |
+| Workflow Early Stop | [Example](examples/python/workflows/workflow_early_stop.py) | [📖](https://docs.praison.ai/features/workflows) |
+| Workflow Checkpoints | [Example](examples/python/workflows/workflow_checkpoints.py) | [📖](https://docs.praison.ai/features/workflows) |
+
+</details>
+
+<details>
+<summary><strong>💻 Code & Development</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Code Interpreter Agents | [Example](examples/python/agents/code-agent.py) | [📖](https://docs.praison.ai/features/codeagent) |
+| AI Code Editing Tools | [Example](examples/python/code/code_editing_example.py) | [📖](https://docs.praison.ai/code/editing) |
+| External Agents (All) | [Example](examples/python/code/external_agents_example.py) | [📖](https://docs.praison.ai/code/external-agents) |
+| Claude Code CLI | [Example](examples/python/code/claude_code_example.py) | [📖](https://docs.praison.ai/code/claude-code) |
+| Gemini CLI | [Example](examples/python/code/gemini_cli_example.py) | [📖](https://docs.praison.ai/code/gemini-cli) |
+| Codex CLI | [Example](examples/python/code/codex_cli_example.py) | [📖](https://docs.praison.ai/code/codex-cli) |
+| Cursor CLI | [Example](examples/python/code/cursor_cli_example.py) | [📖](https://docs.praison.ai/code/cursor-cli) |
+
+</details>
+
+<details>
+<summary><strong>🧠 Memory & Knowledge</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Memory (Short & Long Term) | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/concepts/memory) |
+| File-Based Memory | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/concepts/memory) |
+| Claude Memory Tool | [Example](#claude-memory-tool-cli) | [📖](https://docs.praison.ai/features/claude-memory-tool) |
+| Add Custom Knowledge | [Example](examples/python/concepts/knowledge-agents.py) | [📖](https://docs.praison.ai/features/knowledge) |
+| RAG Agents | [Example](examples/python/concepts/rag-agents.py) | [📖](https://docs.praison.ai/features/rag) |
+| Chat with PDF Agents | [Example](examples/python/concepts/chat-with-pdf.py) | [📖](https://docs.praison.ai/features/chat-with-pdf) |
+| Data Readers (PDF, DOCX, etc.) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-readers-api) |
+| Vector Store Selection | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-vector-store-api) |
+| Retrieval Strategies | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-retrieval-api) |
+| Rerankers | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-reranker-api) |
+| Index Types (Vector/Keyword/Hybrid) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-index-api) |
+| Query Engines (Sub-Question, etc.) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-query-engine-api) |
+
+</details>
+
+<details>
+<summary><strong>🔬 Research & Intelligence</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Deep Research Agents | [Example](examples/python/agents/research-agent.py) | [📖](https://docs.praison.ai/agents/deep-research) |
+| Query Rewriter Agent | [Example](#5-query-rewriter-agent) | [📖](https://docs.praison.ai/agents/query-rewriter) |
+| Native Web Search | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/agents/websearch) |
+| Built-in Search Tools | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/tools/tavily) |
+| Unified Web Search | [Example](src/praisonai-agents/examples/web_search_example.py) | [📖](https://docs.praison.ai/tools/web-search) |
+| Web Fetch (Anthropic) | [Example](#web-search-web-fetch--prompt-caching) | [📖](https://docs.praison.ai/features/model-capabilities) |
+
+</details>
+
+<details>
+<summary><strong>📋 Planning & Execution</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Planning Mode | [Example](examples/python/agents/planning-agent.py) | [📖](https://docs.praison.ai/features/planning-mode) |
+| Planning Tools | [Example](#3-agent-with-planning-mode) | [📖](https://docs.praison.ai/features/planning-mode) |
+| Planning Reasoning | [Example](#3-agent-with-planning-mode) | [📖](https://docs.praison.ai/features/planning-mode) |
+| Prompt Chaining | [Example](examples/python/general/prompt_chaining.py) | [📖](https://docs.praison.ai/features/promptchaining) |
+| Evaluator Optimiser | [Example](examples/python/general/evaluator-optimiser.py) | [📖](https://docs.praison.ai/features/evaluator-optimiser) |
+| Orchestrator Workers | [Example](examples/python/general/orchestrator-workers.py) | [📖](https://docs.praison.ai/features/orchestrator-worker) |
+
+</details>
+
+<details>
+<summary><strong>👥 Specialized Agents</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Data Analyst Agent | [Example](examples/python/agents/data-analyst-agent.py) | [📖](https://docs.praison.ai/agents/data-analyst) |
+| Finance Agent | [Example](examples/python/agents/finance-agent.py) | [📖](https://docs.praison.ai/agents/finance) |
+| Shopping Agent | [Example](examples/python/agents/shopping-agent.py) | [📖](https://docs.praison.ai/agents/shopping) |
+| Recommendation Agent | [Example](examples/python/agents/recommendation-agent.py) | [📖](https://docs.praison.ai/agents/recommendation) |
+| Wikipedia Agent | [Example](examples/python/agents/wikipedia-agent.py) | [📖](https://docs.praison.ai/agents/wikipedia) |
+| Programming Agent | [Example](examples/python/agents/programming-agent.py) | [📖](https://docs.praison.ai/agents/programming) |
+| Math Agents | [Example](examples/python/agents/math-agent.py) | [📖](https://docs.praison.ai/features/mathagent) |
+| Markdown Agent | [Example](examples/python/agents/markdown-agent.py) | [📖](https://docs.praison.ai/agents/markdown) |
+| Prompt Expander Agent | [Example](#prompt-expansion) | [📖](https://docs.praison.ai/agents/prompt-expander) |
+
+</details>
+
+<details>
+<summary><strong>🎨 Media & Multimodal</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Image Generation Agent | [Example](examples/python/image/image-agent.py) | [📖](https://docs.praison.ai/features/image-generation) |
+| Image to Text Agent | [Example](examples/python/agents/image-to-text-agent.py) | [📖](https://docs.praison.ai/agents/image-to-text) |
+| Video Agent | [Example](examples/python/agents/video-agent.py) | [📖](https://docs.praison.ai/agents/video) |
+| Camera Integration | [Example](examples/python/camera/) | [📖](https://docs.praison.ai/features/camera-integration) |
+
+</details>
+
+<details>
+<summary><strong>🔌 Protocols & Integration</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| MCP Transports | [Example](examples/python/mcp/mcp-transports-overview.py) | [📖](https://docs.praison.ai/mcp/transports) |
+| WebSocket MCP | [Example](examples/python/mcp/websocket-mcp.py) | [📖](https://docs.praison.ai/mcp/sse-transport) |
+| MCP Security | [Example](examples/python/mcp/mcp-security.py) | [📖](https://docs.praison.ai/mcp/transports) |
+| MCP Resumability | [Example](examples/python/mcp/mcp-resumability.py) | [📖](https://docs.praison.ai/mcp/sse-transport) |
+| MCP Config Management | [Example](#mcp-config-cli) | [📖](https://docs.praison.ai/docs/cli/mcp) |
+| LangChain Integrated Agents | [Example](examples/python/general/langchain_example.py) | [📖](https://docs.praison.ai/features/langchain) |
+
+</details>
+
+<details>
+<summary><strong>🛡️ Safety & Control</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Guardrails | [Example](examples/python/guardrails/comprehensive-guardrails-example.py) | [📖](https://docs.praison.ai/features/guardrails) |
+| Human Approval | [Example](examples/python/general/human_approval_example.py) | [📖](https://docs.praison.ai/features/approval) |
+| Rules & Instructions | [Example](#7-rules--instructions) | [📖](https://docs.praison.ai/features/rules) |
+
+</details>
+
+<details>
+<summary><strong>⚙️ Advanced Features</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Async & Parallel Processing | [Example](examples/python/general/async_example.py) | [📖](https://docs.praison.ai/features/async) |
+| Parallelisation | [Example](examples/python/general/parallelisation.py) | [📖](https://docs.praison.ai/features/parallelisation) |
+| Repetitive Agents | [Example](examples/python/concepts/repetitive-agents.py) | [📖](https://docs.praison.ai/features/repetitive) |
+| Agent Handoffs | [Example](examples/python/handoff/handoff_basic.py) | [📖](https://docs.praison.ai/features/handoffs) |
+| Stateful Agents | [Example](examples/python/stateful/workflow-state-example.py) | [📖](https://docs.praison.ai/features/stateful-agents) |
+| Autonomous Workflow | [Example](examples/python/general/autonomous-agent.py) | [📖](https://docs.praison.ai/features/autonomous-workflow) |
+| Structured Output Agents | [Example](examples/python/general/structured_agents_example.py) | [📖](https://docs.praison.ai/features/structured) |
+| Model Router | [Example](examples/python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/features/model-router) |
+| Prompt Caching | [Example](#web-search-web-fetch--prompt-caching) | [📖](https://docs.praison.ai/features/model-capabilities) |
+| Fast Context | [Example](examples/context/00_agent_fast_context_basic.py) | [📖](https://docs.praison.ai/features/fast-context) |
+
+</details>
+
+<details>
+<summary><strong>🛠️ Tools & Configuration</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| 100+ Custom Tools | [Example](examples/python/general/tools_example.py) | [📖](https://docs.praison.ai/tools/tools) |
+| YAML Configuration | [Example](examples/cookbooks/yaml/secondary_market_research_agents.yaml) | [📖](https://docs.praison.ai/developers/agents-playbook) |
+| 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/models) |
+| Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/features/callbacks) |
+| Hooks | [Example](#10-hooks) | [📖](https://docs.praison.ai/features/hooks) |
+| Middleware System | [Example](examples/middleware/basic_middleware.py) | [📖](https://docs.praison.ai/features/middleware) |
+| Configurable Model | [Example](examples/middleware/configurable_model.py) | [📖](https://docs.praison.ai/features/configurable-model) |
+| Rate Limiter | [Example](examples/middleware/rate_limiter.py) | [📖](https://docs.praison.ai/features/rate-limiter) |
+| Injected Tool State | [Example](examples/middleware/injected_state.py) | [📖](https://docs.praison.ai/features/injected-state) |
+| Shadow Git Checkpoints | [Example](#11-shadow-git-checkpoints) | [📖](https://docs.praison.ai/features/checkpoints) |
+| Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/features/background-tasks) |
+| Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/features/policy-engine) |
+| Thinking Budgets | [Example](examples/thinking/basic_thinking.py) | [📖](https://docs.praison.ai/features/thinking-budgets) |
+| Output Styles | [Example](examples/output/basic_output.py) | [📖](https://docs.praison.ai/features/output-styles) |
+| Context Compaction | [Example](examples/compaction/basic_compaction.py) | [📖](https://docs.praison.ai/features/context-compaction) |
+
+</details>
+
+<details>
+<summary><strong>📊 Monitoring & Management</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Sessions Management | [Example](examples/python/sessions/comprehensive-session-management.py) | [📖](https://docs.praison.ai/features/sessions) |
+| Auto-Save Sessions | [Example](#session-management-python) | [📖](https://docs.praison.ai/docs/cli/session) |
+| History in Context | [Example](#session-management-python) | [📖](https://docs.praison.ai/docs/cli/session) |
+| Telemetry | [Example](examples/python/telemetry/production-telemetry-example.py) | [📖](https://docs.praison.ai/features/telemetry) |
+| Project Docs (.praison/docs/) | [Example](#docs-cli) | [📖](https://docs.praison.ai/docs/cli/docs) |
+| AI Commit Messages | [Example](#ai-commit-cli) | [📖](https://docs.praison.ai/docs/cli/commit) |
+| @Mentions in Prompts | [Example](#mentions-in-prompts) | [📖](https://docs.praison.ai/docs/cli/mentions) |
+
+</details>
+
+<details>
+<summary><strong>🖥️ CLI Features</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Slash Commands | [Example](examples/python/cli/slash_commands_example.py) | [📖](https://docs.praison.ai/docs/cli/slash-commands) |
+| Autonomy Modes | [Example](examples/python/cli/autonomy_modes_example.py) | [📖](https://docs.praison.ai/docs/cli/autonomy-modes) |
+| Cost Tracking | [Example](examples/python/cli/cost_tracking_example.py) | [📖](https://docs.praison.ai/docs/cli/cost-tracking) |
+| Repository Map | [Example](examples/python/cli/repo_map_example.py) | [📖](https://docs.praison.ai/docs/cli/repo-map) |
+| Interactive TUI | [Example](examples/python/cli/interactive_tui_example.py) | [📖](https://docs.praison.ai/docs/cli/interactive-tui) |
+| Git Integration | [Example](examples/python/cli/git_integration_example.py) | [📖](https://docs.praison.ai/docs/cli/git-integration) |
+| Sandbox Execution | [Example](examples/python/cli/sandbox_execution_example.py) | [📖](https://docs.praison.ai/docs/cli/sandbox-execution) |
+| CLI Compare | [Example](examples/compare/cli_compare_basic.py) | [📖](https://docs.praison.ai/docs/cli/compare) |
+| Profile/Benchmark | [Example](#profile-benchmark) | [📖](https://docs.praison.ai/docs/cli/profile) |
+| Auto Mode | [Example](#auto-mode) | [📖](https://docs.praison.ai/docs/cli/auto) |
+| Init | [Example](#init) | [📖](https://docs.praison.ai/docs/cli/init) |
+| File Input | [Example](#file-input) | [📖](https://docs.praison.ai/docs/cli/file-input) |
+| Final Agent | [Example](#final-agent) | [📖](https://docs.praison.ai/docs/cli/final-agent) |
+| Max Tokens | [Example](#max-tokens) | [📖](https://docs.praison.ai/docs/cli/max-tokens) |
+
+</details>
+
+<details>
+<summary><strong>🧪 Evaluation</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Accuracy Evaluation | [Example](examples/eval/accuracy_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
+| Performance Evaluation | [Example](examples/eval/performance_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
+| Reliability Evaluation | [Example](examples/eval/reliability_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
+| Criteria Evaluation | [Example](examples/eval/criteria_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |
+
+</details>
+
+<details>
+<summary><strong>🎯 Agent Skills</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Skills Management | [Example](examples/skills/basic_skill_usage.py) | [📖](https://docs.praison.ai/features/skills) |
+| Custom Skills | [Example](examples/skills/custom_skill_example.py) | [📖](https://docs.praison.ai/features/skills) |
+
+</details>
+
+<details>
+<summary><strong>⏰ 24/7 Scheduling</strong></summary>
+
+| Feature | Code | Docs |
+|---------|:----:|:----:|
+| Agent Scheduler | [Example](examples/python/scheduled_agents/news_checker_live.py) | [📖](https://docs.praison.ai/docs/cli/scheduler) |
+
+</details>

 ---

@@ -533,7 +745,7 @@ memory.handle_command("/memory save my_session")
 | `memory="sqlite"` | Built-in | SQLite with indexing |
 | `memory="chromadb"` | chromadb | Vector/semantic search |

-### 6. Rules & Instructions
+### 7. Rules & Instructions

 PraisonAI auto-discovers instruction files from your project root and git root:

@@ -582,7 +794,7 @@ activation: always  # always, glob, manual, ai_decision
 - Follow PEP 8
 ```

-### 7. Auto-Generated Memories
+### 8. Auto-Generated Memories

 ```python
 from praisonaiagents.memory import FileMemory, AutoMemory
@@ -597,7 +809,7 @@ memories = auto.process_interaction(
 # Extracts: name="John", preference="Python for backend"
 ```

-### 8. Agentic Workflows
+### 9. Agentic Workflows

 Create powerful multi-agent workflows with the `Workflow` class:

@@ -867,7 +1079,7 @@ callbacks:
  on_workflow_complete: log_complete
 ```

-### 9. Hooks
+### 10. Hooks

 Intercept and modify agent behavior at various lifecycle points:

@@ -906,7 +1118,7 @@ praisonai hooks validate hooks.json     # Validate configuration
 ```


-### 10. Shadow Git Checkpoints
+### 11. Shadow Git Checkpoints

 File-level undo/restore using shadow git:

@@ -943,7 +1155,7 @@ praisonai checkpoint restore abc123         # Restore to checkpoint

 ---

-### 11. Background Tasks
+### 12. Background Tasks

 Run agent tasks asynchronously without blocking:

@@ -981,7 +1193,7 @@ praisonai background clear         # Clear completed tasks

 ---

-### 12. Policy Engine
+### 13. Policy Engine

 Control what agents can and cannot do with policy-based execution:

@@ -1022,7 +1234,7 @@ praisonai policy init                  # Create template

 ---

-### 13. Thinking Budgets
+### 14. Thinking Budgets

 Configure token budgets for extended thinking:

@@ -1055,7 +1267,7 @@ praisonai thinking stats       # Show usage statistics

 ---

-### 14. Output Styles
+### 15. Output Styles

 Configure how agents format their responses:

@@ -1085,7 +1297,7 @@ praisonai output set concise   # Set output style

 ---

-### 15. Context Compaction
+### 16. Context Compaction

 Automatically manage context window size:

@@ -1120,7 +1332,7 @@ praisonai compaction stats         # Show statistics

 ---

-### 16. Field Names Reference (A-I-G-S)
+### 17. Field Names Reference (A-I-G-S)

 PraisonAI accepts both old (agents.yaml) and new (workflow.yaml) field names. Use the **canonical names** for new projects:

@@ -1154,7 +1366,7 @@ steps:                         # Define steps (not 'tasks')

 > **Note:** The parser accepts both old and new names. Run `praisonai workflow validate <file.yaml>` to see suggestions for canonical names.

-### 12. Extended agents.yaml with Workflow Patterns
+### 18. Extended agents.yaml with Workflow Patterns

 **Feature Parity:** Both `agents.yaml` and `workflow.yaml` now support the same features:
 - All workflow patterns (route, parallel, loop, repeat)
@@ -1230,7 +1442,7 @@ Run with the same simple command:
 praisonai agents.yaml
 ```

-### 12. MCP (Model Context Protocol)
+### 19. MCP (Model Context Protocol)

 PraisonAI supports MCP Protocol Revision 2025-11-25 with multiple transports.

@@ -1306,7 +1518,7 @@ server.run()  # stdio for Claude Desktop
 | Security | Origin validation, DNS rebinding prevention |
 | WebSocket | Auto-reconnect with exponential backoff |

-### 13. A2A (Agent2Agent Protocol)
+### 20. A2A (Agent2Agent Protocol)

 PraisonAI supports the [A2A Protocol](https://a2a-protocol.org) for agent-to-agent communication, enabling your agents to be discovered and collaborate with other AI agents.

@@ -1354,6 +1566,22 @@ app.include_router(a2a.get_router())

 PraisonAI provides a powerful CLI for no-code automation and quick prototyping.

+### CLI Quick Reference
+
+| Category | Commands |
+|----------|----------|
+| **Execution** | `praisonai`, `--auto`, `--interactive`, `--chat` |
+| **Research** | `research`, `--query-rewrite`, `--deep-research` |
+| **Planning** | `--planning`, `--planning-tools`, `--planning-reasoning` |
+| **Workflows** | `workflow run`, `workflow list`, `workflow auto` |
+| **Memory** | `memory show`, `memory add`, `memory search`, `memory clear` |
+| **Knowledge** | `knowledge add`, `knowledge query`, `knowledge list` |
+| **Sessions** | `session list`, `session resume`, `session delete` |
+| **Tools** | `tools list`, `tools info`, `tools search` |
+| **MCP** | `mcp list`, `mcp create`, `mcp enable` |
+| **Development** | `commit`, `docs`, `checkpoint`, `hooks` |
+| **Scheduling** | `schedule start`, `schedule list`, `schedule stop` |
+
 ### Auto Mode
 ```bash
 pip install praisonai
@@ -1766,19 +1994,23 @@ manager.delete_checkpoint("deploy-v1")

 ### Tools CLI:
 ```bash
-# List all available tools
 praisonai tools list
-
-# Get info about a specific tool
 praisonai tools info internet_search
-
-# Search for tools
 praisonai tools search "web"
-
-# Show all commands
-praisonai tools help
+praisonai tools doctor
+praisonai tools resolve shell_tool
+praisonai tools discover
+praisonai tools show-sources
+praisonai tools show-sources --template ai-video-editor
 ```

+| Command | Example | Docs |
+|---------|---------|------|
+| `tools list` | [example](examples/tools/) | [docs](https://docs.praison.ai/docs/cli/tools) |
+| `tools resolve` | [example](examples/tools/example_tools_resolve.py) | [docs](https://docs.praison.ai/docs/cli/tools-resolve) |
+| `tools discover` | [example](examples/tools/example_tools_discover.py) | [docs](https://docs.praison.ai/docs/cli/tools-discover) |
+| `tools show-sources` | [example](examples/tools/example_tools_sources.py) | [docs](https://docs.praison.ai/docs/cli/tools-show-sources) |
+
 ### Handoff CLI:
 ```bash
 # Enable agent-to-agent task delegation
@@ -2127,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)

 ---

@@ -2637,6 +2887,84 @@ PraisonAI provides zero-dependency persistent memory for agents. For detailed ex

 ---

+## 📚 Knowledge & Retrieval (RAG)
+
+PraisonAI provides a complete knowledge stack for building RAG applications with multiple vector stores, retrieval strategies, rerankers, and query modes.
+
+### Knowledge CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai knowledge add <file\|dir\|url>` | Add documents to knowledge base |
+| `praisonai knowledge query <question>` | Query knowledge base with RAG |
+| `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+### Knowledge CLI Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | Vector store backend |
+| `--retrieval` | `basic`, `fusion`, `recursive`, `auto_merge` | Retrieval strategy |
+| `--reranker` | `simple`, `llm`, `cross_encoder`, `cohere` | Reranking method |
+| `--index-type` | `vector`, `keyword`, `hybrid` | Index type |
+| `--query-mode` | `default`, `sub_question`, `summarize` | Query mode |
+
+### Knowledge CLI Examples
+
+```bash
+# Add documents
+praisonai knowledge add ./docs/
+praisonai knowledge add https://example.com/page.html
+praisonai knowledge add "*.pdf"
+
+# Query with advanced options
+praisonai knowledge query "How to authenticate?" --retrieval fusion --reranker llm
+
+# Full advanced query
+praisonai knowledge query "authentication flow" \
+  --vector-store chroma \
+  --retrieval fusion \
+  --reranker llm \
+  --index-type hybrid \
+  --query-mode sub_question
+```
+
+### Knowledge SDK Usage
+
+```python
+from praisonaiagents import Agent, Knowledge
+
+# Simple usage with Agent
+agent = Agent(
+    name="Research Assistant",
+    knowledge=["docs/manual.pdf", "data/faq.txt"],
+    knowledge_config={
+        "vector_store": {"provider": "chroma"}
+    }
+)
+response = agent.chat("How do I authenticate?")
+
+# Direct Knowledge usage
+knowledge = Knowledge()
+knowledge.add("document.pdf")
+results = knowledge.search("authentication", limit=5)
+```
+
+### Knowledge Stack Features Table
+
+| Feature | Description | SDK Docs | CLI Docs |
+|---------|-------------|----------|----------|
+| **Data Readers** | Load PDF, Markdown, Text, HTML, URLs | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Vector Stores** | ChromaDB, Pinecone, Qdrant, Weaviate, In-Memory | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Retrieval Strategies** | Basic, Fusion (RRF), Recursive, Auto-Merge | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Rerankers** | Simple, LLM, Cross-Encoder, Cohere | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Index Types** | Vector, Keyword (BM25), Hybrid | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Query Engines** | Default, Sub-Question, Summarize | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+
+---
+
 ## 🔬 Advanced Features

 ### Research & Intelligence
@@ -2751,6 +3079,44 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | `praisonai persistence migrate` | Apply schema migrations |
 | `praisonai persistence status` | Show schema status |

+### Knowledge CLI Commands {#knowledge-cli}
+
+| Command | Description |
+|---------|-------------|
+| `praisonai knowledge add <source>` | Add file, directory, URL, or glob pattern |
+| `praisonai knowledge query "<question>"` | Query knowledge base with RAG |
+| `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+**Knowledge Query Flags:**
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | `chroma` |
+| `--retrieval-strategy` | `basic`, `fusion`, `recursive`, `auto_merge` | `basic` |
+| `--reranker` | `none`, `simple`, `llm`, `cross_encoder`, `cohere` | `none` |
+| `--index-type` | `vector`, `keyword`, `hybrid` | `vector` |
+| `--query-mode` | `default`, `sub_question`, `summarize` | `default` |
+| `--workspace` | Path to workspace directory | Current dir |
+| `--session` | Session ID for persistence | - |
+
+**Examples:**
+
+```bash
+# Add documents
+praisonai knowledge add document.pdf
+praisonai knowledge add ./docs/
+praisonai knowledge add "*.md"
+
+# Query with options
+praisonai knowledge query "How to authenticate?" \
+  --vector-store chroma \
+  --retrieval-strategy fusion \
+  --reranker simple \
+  --query-mode sub_question
+```
+
 ### Databases Table

 | Database | Store Type | Install | Example | Docs |
@@ -2763,11 +3129,11 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | SurrealDB | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Qdrant | Knowledge | `pip install "praisonai[tools]"` | [knowledge_qdrant.py](examples/persistence/knowledge_qdrant.py) | [docs](https://docs.praison.ai/docs/databases/qdrant) |
 | ChromaDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Pinecone | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Weaviate | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| LanceDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Pinecone | Knowledge | `pip install pinecone` | [pinecone_wow.py](examples/vector/pinecone_wow.py) | [docs](https://docs.praison.ai/docs/databases/pinecone) |
+| Weaviate | Knowledge | `pip install weaviate-client` | [weaviate_wow.py](examples/vector/weaviate_wow.py) | [docs](https://docs.praison.ai/docs/databases/weaviate) |
+| LanceDB | Knowledge | `pip install lancedb` | [lancedb_real_wow.py](examples/vector/lancedb_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/lancedb) |
 | Milvus | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| PGVector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| PGVector | Knowledge | `pip install psycopg2-binary` | [pgvector_real_wow.py](examples/vector/pgvector_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/pgvector) |
 | Redis Vector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Cassandra | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | ClickHouse | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
@@ -2897,6 +3263,119 @@ cd src/praisonai && uv publish

 ---

+## ❓ FAQ & Troubleshooting
+
+<details>
+<summary><strong>ModuleNotFoundError: No module named 'praisonaiagents'</strong></summary>
+
+Install the package:
+```bash
+pip install praisonaiagents
+```
+
+</details>
+
+<details>
+<summary><strong>API key not found / Authentication error</strong></summary>
+
+Ensure your API key is set:
+```bash
+export OPENAI_API_KEY=your_key_here
+```
+
+For other providers, see [Environment Variables](#environment-variables).
+
+</details>
+
+<details>
+<summary><strong>How do I use a local model (Ollama)?</strong></summary>
+
+```bash
+# Start Ollama server first
+ollama serve
+
+# Set environment variable
+export OPENAI_BASE_URL=http://localhost:11434/v1
+```
+
+See [Ollama Integration](#ollama-integration) for more details.
+
+</details>
+
+<details>
+<summary><strong>How do I persist conversations to a database?</strong></summary>
+
+Use the `db` parameter:
+```python
+from praisonaiagents import Agent, db
+
+agent = Agent(
+    name="Assistant",
+    db=db(database_url="postgresql://localhost/mydb"),
+    session_id="my-session"
+)
+```
+
+See [Persistence (Databases)](#-persistence-databases) for supported databases.
+
+</details>
+
+<details>
+<summary><strong>How do I enable agent memory?</strong></summary>
+
+```python
+from praisonaiagents import Agent
+
+agent = Agent(
+    name="Assistant",
+    memory=True,  # Enables file-based memory (no extra deps!)
+    user_id="user123"
+)
+```
+
+See [Agent Memory](#6-agent-memory-zero-dependencies) for more options.
+
+</details>
+
+<details>
+<summary><strong>How do I run multiple agents together?</strong></summary>
+
+```python
+from praisonaiagents import Agent, PraisonAIAgents
+
+agent1 = Agent(instructions="Research topics")
+agent2 = Agent(instructions="Summarize findings")
+agents = PraisonAIAgents(agents=[agent1, agent2])
+agents.start()
+```
+
+See [Multi Agents](#2-multi-agents) for more examples.
+
+</details>
+
+<details>
+<summary><strong>How do I use MCP tools?</strong></summary>
+
+```python
+from praisonaiagents import Agent, MCP
+
+agent = Agent(
+    tools=MCP("npx @modelcontextprotocol/server-memory")
+)
+```
+
+See [MCP Protocol](#19-mcp-model-context-protocol) for all transport options.
+
+</details>
+
+### Getting Help
+
+- 📚 [Full Documentation](https://docs.praison.ai)
+- 🐛 [Report Issues](https://github.com/MervinPraison/PraisonAI/issues)
+- 💬 [Discussions](https://github.com/MervinPraison/PraisonAI/discussions)
+
+---
+
 <div align="center">
  <p><strong>Made with ❤️ by the PraisonAI Team</strong></p>
  <p>
@@ -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.4.3" \
+    "praisonai>=2.7.2" \
    "praisonai[chat]" \
    "embedchain[github,youtube]"

@@ -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.4.3" \
+    "praisonai>=2.7.2" \
    "praisonai[ui]" \
    "praisonai[chat]" \
    "praisonai[realtime]" \
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
    praisonai_tools \
-    "praisonai>=2.4.3" \
+    "praisonai>=2.7.2" \
    "praisonai[ui]" \
    "praisonai[crewai]"

@@ -0,0 +1,53 @@
+# Templates CLI
+
+```bash
+praisonai templates list
+```
+
+```bash
+praisonai templates search video
+```
+
+```bash
+praisonai templates info ai-video-editor
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --offline
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --strict-tools
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools ./my_tools.py
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools-dir ./tools
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --tools-source praisonai_tools.video
+```
+
+```bash
+praisonai templates run ai-video-editor --input video.mp4 --no-template-tools-py
+```
+
+```bash
+praisonai templates init my-project --template ai-video-editor
+```
+
+```bash
+praisonai templates cache clear
+```
+
+```bash
+praisonai templates cache list
+```
@@ -0,0 +1,104 @@
+# Templates Module
+
+## Loading Templates
+
+```python
+from praisonai.templates.loader import TemplateLoader
+
+loader = TemplateLoader()
+
+# Load from local path
+template = loader.load("./my-template")
+
+# Load from URI
+template = loader.load("ai-video-editor")
+
+# Load offline
+template = loader.load("ai-video-editor", offline=True)
+
+# Check requirements
+missing = loader.check_requirements(template)
+```
+
+## Template Discovery
+
+```python
+from praisonai.templates.discovery import TemplateDiscovery
+
+discovery = TemplateDiscovery(
+    include_package=True,
+    include_defaults=True,
+)
+
+# Find template
+result = discovery.find_template("ai-video-editor")
+
+# List all templates
+templates = discovery.list_templates()
+```
+
+## Template Config
+
+```python
+from praisonai.templates.loader import TemplateConfig
+
+# Access template properties
+template.name
+template.description
+template.version
+template.author
+template.requires
+template.workflow_file
+template.agents_file
+template.path
+```
+
+## Tool Override Integration
+
+```python
+from praisonai.templates.tool_override import (
+    create_tool_registry_with_overrides,
+    resolve_tools,
+)
+
+# Build registry with template sources
+tools_sources = template.requires.get("tools_sources", [])
+
+registry = create_tool_registry_with_overrides(
+    tools_sources=tools_sources,
+    template_dir=str(template.path),
+    include_defaults=True,
+)
+
+# Resolve tool names
+tools = resolve_tools(["shell_tool"], registry=registry)
+```
+
+## TEMPLATE.yaml Schema
+
+```yaml
+name: my-template
+version: "1.0.0"
+description: Template description
+
+requires:
+  tools: [shell_tool]
+  packages: [praisonai-tools]
+  env: [OPENAI_API_KEY]
+  tools_sources:
+    - praisonai_tools.video
+    - ./local_tools.py
+
+workflow: workflow.yaml
+agents: agents.yaml
+
+config:
+  input:
+    type: string
+    required: true
+  output:
+    type: string
+
+defaults:
+  preset: podcast
+```
@@ -0,0 +1,65 @@
+# Tools CLI
+
+```bash
+praisonai tools list
+```
+
+```bash
+praisonai tools info shell_tool
+```
+
+```bash
+praisonai tools info internet_search
+```
+
+```bash
+praisonai tools search "web"
+```
+
+```bash
+praisonai tools search "file"
+```
+
+```bash
+praisonai tools doctor
+```
+
+```bash
+praisonai tools doctor --json
+```
+
+```bash
+praisonai tools resolve shell_tool
+```
+
+```bash
+praisonai tools resolve internet_search --template ai-video-editor
+```
+
+```bash
+praisonai tools resolve my_tool --tools ./my_tools.py
+```
+
+```bash
+praisonai tools resolve my_tool --tools-dir ./tools
+```
+
+```bash
+praisonai tools discover
+```
+
+```bash
+praisonai tools discover --include praisonai_tools.video
+```
+
+```bash
+praisonai tools discover --entrypoints
+```
+
+```bash
+praisonai tools show-sources
+```
+
+```bash
+praisonai tools show-sources --template ai-video-editor
+```
@@ -0,0 +1,90 @@
+# Tools Module
+
+## Tool Registry
+
+```python
+from praisonai.templates.tool_override import (
+    create_tool_registry_with_overrides,
+    resolve_tools,
+)
+
+# Create registry with defaults
+registry = create_tool_registry_with_overrides(include_defaults=True)
+
+# Create registry with overrides
+registry = create_tool_registry_with_overrides(
+    override_files=["my_tools.py"],
+    override_dirs=["./tools"],
+    include_defaults=True,
+)
+
+# Create registry with tools_sources
+registry = create_tool_registry_with_overrides(
+    tools_sources=["praisonai_tools.video"],
+    template_dir="./my-template",
+    include_defaults=True,
+)
+
+# Resolve tool names to callables
+tools = resolve_tools(
+    ["shell_tool", "internet_search"],
+    registry=registry,
+)
+```
+
+## Tool Override Loader
+
+```python
+from praisonai.templates.tool_override import ToolOverrideLoader
+
+loader = ToolOverrideLoader()
+
+# Load from file
+tools = loader.load_from_file("my_tools.py")
+
+# Load from directory
+tools = loader.load_from_directory("./tools")
+
+# Load from module
+tools = loader.load_from_module("praisonai_tools.video")
+
+# Get default tool directories
+dirs = loader.get_default_tool_dirs()
+```
+
+## Resolution Order
+
+1. CLI `--tools` files (highest priority)
+2. CLI `--tools-dir` directories
+3. Template `tools_sources` (from TEMPLATE.yaml)
+4. Template-local `tools.py`
+5. Default dirs (`~/.praison/tools`, `~/.config/praison/tools`)
+6. Package discovery (`praisonai_tools`)
+7. Built-in tools (lowest priority)
+
+## Creating Custom Tools
+
+```python
+from praisonai_tools import tool
+
+@tool
+def my_custom_tool(query: str) -> str:
+    """My custom tool description.
+    
+    Args:
+        query: The search query
+    """
+    return f"Result for: {query}"
+```
+
+## Template tools_sources
+
+```yaml
+# TEMPLATE.yaml
+requires:
+  tools: [shell_tool]
+  tools_sources:
+    - praisonai_tools.video
+    - ./local_tools.py
+    - ./tools_dir/
+```
@@ -30,6 +30,7 @@ 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) |

 ## Running Examples

@@ -0,0 +1,35 @@
+"""
+Async Runs Examples
+===================
+
+This directory contains examples for the PraisonAI Async Jobs API.
+
+Examples:
+---------
+1. sdk_submit_poll_result.py - Python SDK example for submit/poll/result
+2. cli_submit_poll_result.sh - Bash/curl example for submit/poll/result
+3. idempotency.sh - Demonstrates idempotency key usage
+4. cancel.sh - Demonstrates job cancellation
+5. sse_stream.sh - Demonstrates SSE streaming
+
+Prerequisites:
+--------------
+1. Set OPENAI_API_KEY environment variable
+2. Start the jobs server:
+   
+   cd /path/to/praisonai-package/src/praisonai
+   python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory
+
+3. Run examples:
+   
+   python sdk_submit_poll_result.py
+   bash cli_submit_poll_result.sh
+   bash idempotency.sh
+   bash cancel.sh
+   bash sse_stream.sh
+
+Environment Variables:
+----------------------
+- OPENAI_API_KEY: Required for agent execution
+- PRAISONAI_BASE_URL: API server URL (default: http://127.0.0.1:8005)
+"""
@@ -0,0 +1,54 @@
+#!/bin/bash
+# CLI Example: Cancel a Running Job
+#
+# This example demonstrates how to cancel a running job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cancel.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Job Cancellation Example"
+echo "============================================================"
+
+# Submit a long-running job
+echo ""
+echo "1. Submitting a job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "Write a detailed essay about the history of computing."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# Wait briefly
+echo ""
+echo "2. Waiting 1 second..."
+sleep 1
+
+# Cancel the job
+echo ""
+echo "3. Cancelling job..."
+CANCEL_RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs/$JOB_ID/cancel")
+STATUS=$(echo "$CANCEL_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+echo "   Status after cancel: $STATUS"
+
+# Verify cancellation
+echo ""
+echo "4. Verification:"
+if [ "$STATUS" = "cancelled" ]; then
+    echo "   ✓ SUCCESS: Job was cancelled"
+else
+    echo "   ℹ Job status: $STATUS (may have completed before cancel)"
+fi
+
+echo ""
+echo "============================================================"
+echo "Cancellation example completed!"
+echo "============================================================"
@@ -0,0 +1,75 @@
+#!/bin/bash
+# CLI Example: Submit, Poll, and Get Result for Async Jobs
+#
+# This example demonstrates how to use the PraisonAI CLI to:
+# 1. Submit an async job
+# 2. Check job status
+# 3. Get the result
+#
+# Requirements:
+# - OPENAI_API_KEY environment variable set
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cli_submit_poll_result.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Async Jobs CLI Example"
+echo "============================================================"
+
+# Check if server is running
+echo ""
+echo "Checking server health..."
+if ! curl -s "$API_URL/health" > /dev/null 2>&1; then
+    echo "✗ Server not available at $API_URL"
+    echo "  Start the server with: python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory"
+    exit 1
+fi
+echo "✓ Server is healthy"
+
+# 1. Submit a job
+echo ""
+echo "1. Submitting job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "What is 2+2? Answer with just the number."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# 2. Poll for status
+echo ""
+echo "2. Polling for status..."
+while true; do
+    STATUS_RESPONSE=$(curl -s "$API_URL/api/v1/runs/$JOB_ID")
+    STATUS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+    PROGRESS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['progress']['percentage'])")
+    
+    echo "   Status: $STATUS | Progress: ${PROGRESS}%"
+    
+    if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
+        break
+    fi
+    
+    sleep 2
+done
+
+# 3. Get result
+echo ""
+echo "3. Getting result..."
+if [ "$STATUS" = "succeeded" ]; then
+    RESULT=$(curl -s "$API_URL/api/v1/runs/$JOB_ID/result")
+    echo "   Result: $(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['result'])")"
+    echo "   Duration: $(echo "$RESULT" | python3 -c "import sys,json; print(f\"{json.load(sys.stdin)['duration_seconds']:.2f}s\")")"
+else
+    echo "   Job did not succeed: $STATUS"
+fi
+
+echo ""
+echo "============================================================"
+echo "Example completed!"
+echo "============================================================"
@@ -0,0 +1,57 @@
+#!/bin/bash
+# CLI Example: Idempotency Key Usage
+#
+# This example demonstrates how idempotency keys prevent duplicate job submissions.
+# Submitting the same request with the same idempotency key returns the existing job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash idempotency.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+IDEM_KEY="example-idem-key-$(date +%s)"
+
+echo "============================================================"
+echo "PraisonAI Idempotency Key Example"
+echo "============================================================"
+
+# First submission
+echo ""
+echo "1. First submission with Idempotency-Key: $IDEM_KEY"
+RESPONSE1=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "What is 1+1?"}')
+
+JOB_ID1=$(echo "$RESPONSE1" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID1"
+
+# Second submission with same key
+echo ""
+echo "2. Second submission with SAME Idempotency-Key: $IDEM_KEY"
+RESPONSE2=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "Different prompt but same key"}')
+
+JOB_ID2=$(echo "$RESPONSE2" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID2"
+
+# Verify same job ID
+echo ""
+echo "3. Verification:"
+if [ "$JOB_ID1" = "$JOB_ID2" ]; then
+    echo "   ✓ SUCCESS: Same job ID returned (no duplicate created)"
+else
+    echo "   ✗ FAILURE: Different job IDs returned"
+    exit 1
+fi
+
+echo ""
+echo "============================================================"
+echo "Idempotency example completed!"
+echo "============================================================"
@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+SDK Example: Submit, Poll, and Get Result for Async Jobs
+
+This example demonstrates how to use the PraisonAI Jobs SDK to:
+1. Submit an async job
+2. Poll for status
+3. Get the result
+
+Requirements:
+- OPENAI_API_KEY environment variable set
+- Jobs server running on http://127.0.0.1:8005
+
+Usage:
+    python sdk_submit_poll_result.py
+"""
+
+import os
+import time
+import httpx
+
+# Configuration
+API_URL = os.getenv("PRAISONAI_BASE_URL", "http://127.0.0.1:8005")
+POLL_INTERVAL = 2  # seconds
+
+
+def submit_job(prompt: str, idempotency_key: str = None) -> dict:
+    """Submit a job and return the response."""
+    headers = {}
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    
+    with httpx.Client(timeout=30.0) as client:
+        response = client.post(
+            f"{API_URL}/api/v1/runs",
+            json={"prompt": prompt},
+            headers=headers if headers else None
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def get_status(job_id: str) -> dict:
+    """Get job status."""
+    with httpx.Client(timeout=30.0) as client:
+        response = client.get(f"{API_URL}/api/v1/runs/{job_id}")
+        response.raise_for_status()
+        return response.json()
+
+
+def get_result(job_id: str) -> dict:
+    """Get job result."""
+    with httpx.Client(timeout=30.0) as client:
+        response = client.get(f"{API_URL}/api/v1/runs/{job_id}/result")
+        response.raise_for_status()
+        return response.json()
+
+
+def wait_for_completion(job_id: str, max_wait: int = 120) -> dict:
+    """Poll until job completes."""
+    start = time.time()
+    while time.time() - start < max_wait:
+        status = get_status(job_id)
+        print(f"  Status: {status['status']} | Progress: {status['progress']['percentage']:.0f}%")
+        
+        if status["status"] in ("succeeded", "failed", "cancelled"):
+            return status
+        
+        # Honor retry_after if present
+        wait_time = status.get("retry_after") or POLL_INTERVAL
+        time.sleep(wait_time)
+    
+    raise TimeoutError(f"Job {job_id} did not complete within {max_wait}s")
+
+
+def main():
+    print("=" * 60)
+    print("PraisonAI Async Jobs SDK Example")
+    print("=" * 60)
+    
+    # Check if server is running
+    try:
+        with httpx.Client(timeout=5.0) as client:
+            health = client.get(f"{API_URL}/health")
+            health.raise_for_status()
+            print(f"✓ Server healthy: {health.json()['status']}")
+    except Exception as e:
+        print(f"✗ Server not available at {API_URL}: {e}")
+        print("  Start the server with: python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory")
+        return
+    
+    # 1. Submit a job
+    print("\n1. Submitting job...")
+    prompt = "What is the capital of France? Answer in one word."
+    result = submit_job(prompt)
+    job_id = result["job_id"]
+    print(f"   Job ID: {job_id}")
+    print(f"   Status: {result['status']}")
+    print(f"   Poll URL: {result['poll_url']}")
+    
+    # 2. Wait for completion
+    print("\n2. Waiting for completion...")
+    final_status = wait_for_completion(job_id)
+    print(f"   Final status: {final_status['status']}")
+    
+    # 3. Get result
+    if final_status["status"] == "succeeded":
+        print("\n3. Getting result...")
+        result = get_result(job_id)
+        print(f"   Result: {result['result']}")
+        print(f"   Duration: {result['duration_seconds']:.2f}s")
+    else:
+        print(f"\n3. Job did not succeed: {final_status.get('error', 'Unknown error')}")
+    
+    print("\n" + "=" * 60)
+    print("Example completed successfully!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,51 @@
+#!/bin/bash
+# CLI Example: SSE Streaming
+#
+# This example demonstrates how to stream job progress via Server-Sent Events.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash sse_stream.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI SSE Streaming Example"
+echo "============================================================"
+
+# Submit a job
+echo ""
+echo "1. Submitting job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "Count from 1 to 5."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# Stream progress
+echo ""
+echo "2. Streaming progress (Ctrl+C to stop)..."
+echo "   Connecting to: $API_URL/api/v1/runs/$JOB_ID/stream"
+echo ""
+
+# Use curl to stream SSE events (timeout after 60s)
+curl -s -N --max-time 60 "$API_URL/api/v1/runs/$JOB_ID/stream" | while read -r line; do
+    if [[ "$line" == data:* ]]; then
+        data="${line#data: }"
+        if [ "$data" = "[DONE]" ]; then
+            echo "   Stream completed"
+            break
+        fi
+        echo "   Event: $data"
+    fi
+done
+
+echo ""
+echo "============================================================"
+echo "Streaming example completed!"
+echo "============================================================"
@@ -0,0 +1,24 @@
+"""
+Assistants Capabilities Example
+
+Demonstrates OpenAI Assistants API using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import assistant_list
+
+print("=== List Assistants ===")
+try:
+    assistants = assistant_list()
+    print(f"Assistants found: {len(assistants)}")
+    for a in assistants[:5]:  # Show first 5
+        print(f"  - {a.get('name', 'unnamed')}: {a.get('id', 'unknown')}")
+except Exception as e:
+    print(f"Note: {e}")
+
+print("\n=== Assistant Operations ===")
+print("Available functions:")
+print("  assistant_create(name, instructions, model='gpt-4o-mini')")
+print("  assistant_list()")
+
+print("\nSee CLI: praisonai assistants list")
+print("See CLI: praisonai assistants create --name 'My Assistant'")
@@ -0,0 +1,24 @@
+"""
+Audio Capabilities Example
+
+Demonstrates transcription and text-to-speech using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import transcribe, speech
+
+# Note: Audio transcription requires an audio file
+# This example shows the API structure
+
+print("=== Audio Transcription ===")
+print("To transcribe audio, use:")
+print("  result = transcribe('audio.mp3', model='whisper-1')")
+print("  print(result.text)")
+
+print("\n=== Text-to-Speech ===")
+print("To generate speech, use:")
+print("  audio_data = speech('Hello world', model='tts-1', voice='alloy')")
+print("  # Save to file or play")
+
+print("\nNote: These operations require audio files or generate audio output.")
+print("See CLI: praisonai audio transcribe <file>")
+print("See CLI: praisonai audio speech <text>")
@@ -0,0 +1,27 @@
+"""
+Batches Capabilities Example
+
+Demonstrates batch processing using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import batch_list
+
+print("=== Batch List ===")
+try:
+    batches = batch_list()
+    print(f"Batches found: {len(batches)}")
+    for b in batches[:5]:  # Show first 5
+        print(f"  - {b.get('id', 'unknown')}: {b.get('status', 'unknown')}")
+except Exception as e:
+    print(f"Note: {e}")
+    print("Batch operations require batch jobs to be created first.")
+
+print("\n=== Batch Operations ===")
+print("Available functions:")
+print("  batch_create(input_file_id, endpoint, completion_window='24h')")
+print("  batch_list()")
+print("  batch_retrieve(batch_id)")
+print("  batch_cancel(batch_id)")
+
+print("\nSee CLI: praisonai batches list")
+print("See CLI: praisonai batches create <input_file_id>")
@@ -0,0 +1,30 @@
+"""
+Completions Capability Example
+
+Demonstrates chat and text completions using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import chat_completion, text_completion
+
+# Chat completion example
+print("=== Chat Completion ===")
+result = chat_completion(
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is 2 + 2? Answer in one word."}
+    ],
+    model="gpt-4o-mini",
+    max_tokens=10
+)
+print(f"Response: {result.content}")
+print(f"Model: {result.model}")
+print(f"Usage: {result.usage}")
+
+# Text completion example (legacy)
+print("\n=== Text Completion ===")
+result = text_completion(
+    prompt="The capital of France is",
+    model="gpt-3.5-turbo-instruct",
+    max_tokens=10
+)
+print(f"Response: {result.content}")
@@ -0,0 +1,27 @@
+"""
+Embeddings Capability Example
+
+Demonstrates text embedding generation using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import embed
+
+# Single text embedding
+print("=== Single Text Embedding ===")
+result = embed(
+    input="Hello, world!",
+    model="text-embedding-3-small"
+)
+print(f"Embedding dimensions: {len(result.embeddings[0])}")
+print(f"First 5 values: {result.embeddings[0][:5]}")
+print(f"Usage: {result.usage}")
+
+# Multiple text embeddings
+print("\n=== Multiple Text Embeddings ===")
+result = embed(
+    input=["Hello", "World", "AI"],
+    model="text-embedding-3-small"
+)
+print(f"Number of embeddings: {len(result.embeddings)}")
+for i, emb in enumerate(result.embeddings):
+    print(f"  Text {i+1}: {len(emb)} dimensions")
@@ -0,0 +1,28 @@
+"""
+Files Capabilities Example
+
+Demonstrates file management using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import file_list
+
+print("=== File List ===")
+try:
+    files = file_list()
+    print(f"Files found: {len(files)}")
+    for f in files[:5]:  # Show first 5
+        print(f"  - {f.get('filename', 'unknown')}: {f.get('id', 'unknown')}")
+except Exception as e:
+    print(f"Note: {e}")
+    print("File operations require files to be uploaded first.")
+
+print("\n=== File Operations ===")
+print("Available functions:")
+print("  file_create(file_path, purpose='assistants')")
+print("  file_list(purpose=None)")
+print("  file_retrieve(file_id)")
+print("  file_delete(file_id)")
+print("  file_content(file_id)")
+
+print("\nSee CLI: praisonai files list")
+print("See CLI: praisonai files upload <file>")
@@ -0,0 +1,31 @@
+"""
+Images Capability Example
+
+Demonstrates image generation using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import image_generate
+
+# Generate an image with DALL-E 2
+print("=== Image Generation (DALL-E 2) ===")
+result = image_generate(
+    prompt="A simple blue circle on a white background",
+    model="dall-e-2",
+    size="256x256",
+    n=1
+)
+print(f"Images generated: {len(result)}")
+if result:
+    print(f"URL: {result[0].url[:80]}...")
+
+# Generate with DALL-E 3 (higher quality)
+print("\n=== Image Generation (DALL-E 3) ===")
+result = image_generate(
+    prompt="A serene mountain landscape at sunset",
+    model="dall-e-3",
+    size="1024x1024",
+    quality="standard"
+)
+print(f"Images generated: {len(result)}")
+if result:
+    print(f"Revised prompt: {result[0].revised_prompt[:80]}..." if result[0].revised_prompt else "No revised prompt")
@@ -0,0 +1,33 @@
+"""
+Messages Capability Example
+
+Demonstrates Anthropic-style messages API and token counting.
+"""
+
+from praisonai.capabilities import messages_create, count_tokens
+
+# Create a message (Anthropic-style)
+print("=== Messages Create ===")
+result = messages_create(
+    messages=[{"role": "user", "content": "What is the meaning of life? Answer briefly."}],
+    model="gpt-4o-mini",  # Works with any model via LiteLLM
+    max_tokens=100,
+    system="You are a philosophical assistant."
+)
+print(f"Message ID: {result.id}")
+if result.content:
+    for block in result.content:
+        if block.get("type") == "text":
+            print(f"Response: {block.get('text')}")
+print(f"Usage: {result.usage}")
+
+# Count tokens
+print("\n=== Token Counting ===")
+result = count_tokens(
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hello, how are you today?"}
+    ],
+    model="gpt-4o-mini"
+)
+print(f"Token count: {result.input_tokens}")
@@ -0,0 +1,24 @@
+"""
+Moderations Capability Example
+
+Demonstrates content moderation using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import moderate
+
+# Check safe content
+print("=== Safe Content Check ===")
+result = moderate(
+    input="Hello, how are you today?"
+)
+print(f"Flagged: {result[0].flagged}")
+print(f"Categories: {list(result[0].categories.keys())[:5]}...")
+
+# Check multiple texts
+print("\n=== Multiple Text Moderation ===")
+result = moderate(
+    input=["Hello world", "Have a nice day", "This is a test"]
+)
+print(f"Number of results: {len(result)}")
+for i, r in enumerate(result):
+    print(f"  Text {i+1}: Flagged = {r.flagged}")
@@ -0,0 +1,23 @@
+"""
+Realtime Capability Example
+
+Demonstrates realtime session creation for audio/video streaming.
+"""
+
+from praisonai.capabilities import realtime_connect
+
+# Create a realtime session
+print("=== Realtime Session ===")
+session = realtime_connect(
+    model="gpt-4o-realtime-preview",
+    modalities=["text", "audio"],
+    voice="alloy"
+)
+print(f"Session ID: {session.id}")
+print(f"Status: {session.status}")
+print(f"URL: {session.url}")
+print(f"Modalities: {session.metadata.get('modalities')}")
+print(f"Voice: {session.metadata.get('voice')}")
+
+print("\nNote: To use this session, connect via WebSocket to the URL above.")
+print("See OpenAI Realtime API documentation for WebSocket protocol details.")
@@ -0,0 +1,32 @@
+"""
+Rerank Capabilities Example
+
+Demonstrates document reranking using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import rerank
+
+print("=== Document Reranking ===")
+try:
+    documents = [
+        "Python is a programming language",
+        "Machine learning uses algorithms",
+        "Python is great for data science",
+        "JavaScript runs in browsers"
+    ]
+    
+    results = rerank(
+        query="Python programming",
+        documents=documents,
+        model="cohere/rerank-english-v3.0"
+    )
+    
+    print(f"Query: 'Python programming'")
+    print(f"Reranked results:")
+    for r in results:
+        print(f"  Score {r.get('relevance_score', 0):.4f}: {r.get('document', {}).get('text', '')[:50]}")
+except Exception as e:
+    print(f"Note: Reranking requires Cohere API key")
+    print(f"Error: {e}")
+
+print("\nSee CLI: praisonai rerank <query> --documents 'doc1' 'doc2'")
@@ -0,0 +1,22 @@
+"""
+Vector Stores Capabilities Example
+
+Demonstrates vector store management using PraisonAI capabilities.
+"""
+
+from praisonai.capabilities import vector_store_create, vector_store_search
+
+print("=== Vector Store Operations ===")
+print("Available functions:")
+print("  vector_store_create(name)")
+print("  vector_store_search(vector_store_id, query)")
+
+print("\n=== Create Vector Store ===")
+try:
+    store = vector_store_create(name="test-store")
+    print(f"Created: {store}")
+except Exception as e:
+    print(f"Note: {e}")
+
+print("\nSee CLI: praisonai vector-stores create --name 'my-store'")
+print("See CLI: praisonai vector-stores search <store_id> <query>")
@@ -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()
@@ -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);
@@ -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()
@@ -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()
@@ -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
+```
@@ -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}")
@@ -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)
@@ -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()
@@ -0,0 +1,19 @@
+/**
+ * Basic Agent Example
+ * Demonstrates simple agent usage with OpenAI
+ */
+
+import { Agent } from 'praisonai';
+
+async function main() {
+  const agent = new Agent({
+    name: 'Assistant',
+    instructions: 'You are a helpful assistant. Be concise and informative.',
+    llm: 'openai/gpt-4o-mini'
+  });
+
+  const response = await agent.chat('What is TypeScript?');
+  console.log('Response:', response.text);
+}
+
+main().catch(console.error);
@@ -0,0 +1,47 @@
+/**
+ * Context Agent Example
+ * Demonstrates RAG-enabled agent with knowledge base
+ */
+
+import { ContextAgent, createContextAgent, KnowledgeBase } from 'praisonai';
+
+async function main() {
+  // Create knowledge base
+  const kb = new KnowledgeBase();
+  
+  // Add documents
+  await kb.add({
+    id: 'doc1',
+    content: 'TypeScript is a strongly typed programming language that builds on JavaScript.',
+    metadata: { topic: 'typescript' }
+  });
+  
+  await kb.add({
+    id: 'doc2',
+    content: 'TypeScript adds optional static typing and class-based object-oriented programming.',
+    metadata: { topic: 'typescript' }
+  });
+
+  await kb.add({
+    id: 'doc3',
+    content: 'PraisonAI is a framework for building AI agents in TypeScript and Python.',
+    metadata: { topic: 'praisonai' }
+  });
+
+  // Create context agent with knowledge base
+  const agent = createContextAgent({
+    name: 'KnowledgeAgent',
+    llm: 'openai/gpt-4o-mini',
+    knowledgeBase: kb,
+    maxContextDocs: 3
+  });
+
+  // Query with context
+  const response = await agent.chat('What is TypeScript?');
+  console.log('Response:', response.text);
+
+  // Check conversation history
+  console.log('\nConversation history:', agent.getHistory().length, 'messages');
+}
+
+main().catch(console.error);
@@ -0,0 +1,29 @@
+/**
+ * Image Agent Example
+ * Demonstrates image analysis capabilities
+ */
+
+import { ImageAgent, createImageAgent } from 'praisonai';
+
+async function main() {
+  const agent = createImageAgent({
+    name: 'VisionAgent',
+    llm: 'openai/gpt-4o-mini',
+    verbose: true
+  });
+
+  console.log('Image Agent created:', agent.name);
+
+  // Note: For actual image analysis, provide a real image URL
+  // const analysis = await agent.analyze({
+  //   imageUrl: 'https://example.com/image.jpg',
+  //   prompt: 'Describe this image in detail'
+  // });
+  // console.log('Analysis:', analysis);
+
+  // Chat without image
+  const response = await agent.chat('What types of images can you analyze?');
+  console.log('Response:', response);
+}
+
+main().catch(console.error);
@@ -0,0 +1,48 @@
+/**
+ * Multi-Agent Example
+ * Demonstrates multiple agents working together
+ */
+
+import { Agent, PraisonAIAgents, Task } from 'praisonai';
+
+async function main() {
+  // Create specialized agents
+  const researcher = new Agent({
+    name: 'Researcher',
+    role: 'Research Specialist',
+    goal: 'Find accurate information on topics',
+    instructions: 'You research topics thoroughly and provide factual information.'
+  });
+
+  const writer = new Agent({
+    name: 'Writer',
+    role: 'Content Writer',
+    goal: 'Create engaging content from research',
+    instructions: 'You write clear, engaging content based on provided research.'
+  });
+
+  // Create tasks
+  const researchTask = new Task({
+    description: 'Research the benefits of TypeScript over JavaScript',
+    expectedOutput: 'A list of key benefits with explanations',
+    agent: researcher
+  });
+
+  const writeTask = new Task({
+    description: 'Write a short article about TypeScript benefits',
+    expectedOutput: 'A 200-word article',
+    agent: writer
+  });
+
+  // Run agents
+  const agents = new PraisonAIAgents({
+    agents: [researcher, writer],
+    tasks: [researchTask, writeTask],
+    process: 'sequential'
+  });
+
+  const result = await agents.start();
+  console.log('Result:', result);
+}
+
+main().catch(console.error);
@@ -0,0 +1,33 @@
+/**
+ * Deep Research Agent Example
+ * Demonstrates comprehensive research with citations
+ */
+
+import { DeepResearchAgent, createDeepResearchAgent } from 'praisonai';
+
+async function main() {
+  const agent = createDeepResearchAgent({
+    name: 'Scholar',
+    llm: 'openai/gpt-4o-mini',
+    maxIterations: 5,
+    verbose: true
+  });
+
+  console.log('Research Agent:', agent.name);
+
+  // Conduct research
+  const result = await agent.research('What are the key benefits of TypeScript?');
+
+  console.log('\n=== Research Results ===');
+  console.log('Answer:', result.answer.substring(0, 500) + '...');
+  console.log('\nConfidence:', result.confidence);
+  console.log('Reasoning steps:', result.reasoning.length);
+
+  // Show reasoning
+  console.log('\n=== Reasoning Process ===');
+  result.reasoning.forEach(step => {
+    console.log(`Step ${step.step}: ${step.thought}`);
+  });
+}
+
+main().catch(console.error);
@@ -0,0 +1,57 @@
+/**
+ * Router Agent Example
+ * Demonstrates routing requests to specialized agents
+ */
+
+import { RouterAgent, createRouter, routeConditions, Agent } from 'praisonai';
+
+async function main() {
+  // Create specialized agents
+  const mathAgent = {
+    name: 'MathAgent',
+    chat: async (input: string) => ({ text: `Math answer for: ${input}` })
+  } as any;
+
+  const codeAgent = {
+    name: 'CodeAgent', 
+    chat: async (input: string) => ({ text: `Code solution for: ${input}` })
+  } as any;
+
+  const generalAgent = {
+    name: 'GeneralAgent',
+    chat: async (input: string) => ({ text: `General response: ${input}` })
+  } as any;
+
+  // Create router with conditions
+  const router = createRouter({
+    name: 'SmartRouter',
+    routes: [
+      {
+        agent: mathAgent,
+        condition: routeConditions.keywords(['math', 'calculate', 'number', 'equation']),
+        priority: 10
+      },
+      {
+        agent: codeAgent,
+        condition: routeConditions.keywords(['code', 'program', 'function', 'javascript']),
+        priority: 10
+      }
+    ],
+    defaultAgent: generalAgent
+  });
+
+  // Test routing
+  const queries = [
+    'Calculate 2 + 2',
+    'Write a function to sort an array',
+    'What is the weather today?'
+  ];
+
+  for (const query of queries) {
+    const result = await router.route(query);
+    console.log(`Query: "${query}"`);
+    console.log(`Routed to: ${result?.agent.name || 'default'}\n`);
+  }
+}
+
+main().catch(console.error);
@@ -0,0 +1,59 @@
+/**
+ * AutoAgents Example
+ * Demonstrates automatic agent generation from task descriptions
+ */
+
+import { AutoAgents, createAutoAgents } from 'praisonai';
+
+async function main() {
+  const auto = createAutoAgents({
+    pattern: 'sequential',
+    verbose: true
+  });
+
+  // Analyze task complexity
+  console.log('=== Complexity Analysis ===');
+  const tasks = [
+    'Write a hello world function',
+    'Build a web scraper that extracts product data',
+    'Create a multi-step data pipeline with validation, transformation, and multiple output formats'
+  ];
+
+  tasks.forEach(task => {
+    const complexity = auto.analyzeComplexity(task);
+    console.log(`"${task.substring(0, 40)}..." -> ${complexity}`);
+  });
+
+  // Recommend patterns
+  console.log('\n=== Pattern Recommendations ===');
+  const patternTasks = [
+    'Process items in parallel',
+    'Route requests to different handlers',
+    'Orchestrate multiple workers',
+    'Evaluate and optimize results'
+  ];
+
+  patternTasks.forEach(task => {
+    const pattern = auto.recommendPattern(task);
+    console.log(`"${task}" -> ${pattern}`);
+  });
+
+  // Generate agent configuration
+  console.log('\n=== Generate Agent Config ===');
+  console.log('Generating agents for: "Build a web scraper"');
+  
+  const team = await auto.generate('Build a web scraper that extracts product prices from e-commerce sites');
+  
+  console.log('\nGenerated Team:');
+  console.log('Pattern:', team.pattern);
+  console.log('Agents:', team.agents.length);
+  team.agents.forEach(agent => {
+    console.log(`  - ${agent.name}: ${agent.role}`);
+  });
+  console.log('Tasks:', team.tasks.length);
+  team.tasks.forEach(task => {
+    console.log(`  - ${task.description.substring(0, 50)}...`);
+  });
+}
+
+main().catch(console.error);
@@ -0,0 +1,47 @@
+/**
+ * Redis Database Example
+ */
+
+import { createMemoryRedis } from '../../../src/praisonai-ts/src';
+
+async function main() {
+  // Use in-memory Redis for this example
+  const redis = createMemoryRedis();
+  await redis.connect();
+
+  console.log('Connected to Redis');
+
+  // Basic get/set
+  await redis.set('user:123', { name: 'John', role: 'admin' });
+  const user = await redis.get('user:123');
+  console.log('User:', user);
+
+  // Set with TTL
+  await redis.set('session:abc', { token: 'xyz' }, 60);
+  const ttl = await redis.ttl('session:abc');
+  console.log('Session TTL:', ttl, 'seconds');
+
+  // Hash operations
+  await redis.hset('profile:123', 'email', '[email protected]');
+  await redis.hset('profile:123', 'phone', '555-1234');
+  const profile = await redis.hgetall('profile:123');
+  console.log('Profile:', profile);
+
+  // List operations
+  await redis.rpush('queue:tasks', { id: 1, type: 'process' });
+  await redis.rpush('queue:tasks', { id: 2, type: 'notify' });
+  const tasks = await redis.lrange('queue:tasks', 0, -1);
+  console.log('Tasks:', tasks);
+
+  // Pub/Sub (memory only)
+  await redis.subscribe('events', (message) => {
+    console.log('Received event:', message);
+  });
+  await redis.publish('events', JSON.stringify({ type: 'user_joined' }));
+
+  // Cleanup
+  await redis.disconnect();
+  console.log('Done!');
+}
+
+main().catch(console.error);
@@ -0,0 +1,64 @@
+/**
+ * Evaluation Framework Example
+ * Demonstrates accuracy, performance, and reliability evaluation
+ */
+
+import { accuracyEval, performanceEval, reliabilityEval, EvalSuite } from 'praisonai';
+
+async function main() {
+  console.log('=== Accuracy Evaluation ===');
+  const accuracyResult = await accuracyEval({
+    input: 'What is 2 + 2?',
+    expectedOutput: '4',
+    actualOutput: 'The answer is 4'
+  });
+  console.log('Passed:', accuracyResult.passed);
+  console.log('Score:', accuracyResult.score);
+  console.log('Duration:', accuracyResult.duration, 'ms');
+
+  console.log('\n=== Performance Evaluation ===');
+  const perfResult = await performanceEval({
+    func: async () => {
+      // Simulate some work
+      await new Promise(r => setTimeout(r, 100));
+      return 'done';
+    },
+    iterations: 5,
+    warmupRuns: 1
+  });
+  console.log('Iterations:', perfResult.times.length);
+  console.log('Avg time:', perfResult.avgTime.toFixed(2), 'ms');
+  console.log('Min time:', perfResult.minTime.toFixed(2), 'ms');
+  console.log('Max time:', perfResult.maxTime.toFixed(2), 'ms');
+
+  console.log('\n=== Reliability Evaluation ===');
+  const reliabilityResult = await reliabilityEval({
+    expectedToolCalls: ['search', 'calculate'],
+    actualToolCalls: ['search', 'calculate']
+  });
+  console.log('Passed:', reliabilityResult.passed);
+  console.log('Score:', reliabilityResult.score);
+
+  console.log('\n=== Eval Suite ===');
+  const suite = new EvalSuite();
+
+  await suite.runAccuracy('test1', {
+    input: 'Hello',
+    expectedOutput: 'Hi',
+    actualOutput: 'Hi there!'
+  });
+
+  await suite.runAccuracy('test2', {
+    input: 'Goodbye',
+    expectedOutput: 'Bye',
+    actualOutput: 'Bye!'
+  });
+
+  const summary = suite.getSummary();
+  console.log('Total tests:', summary.total);
+  console.log('Passed:', summary.passed);
+  console.log('Failed:', summary.failed);
+  console.log('Pass rate:', (summary.passRate * 100).toFixed(1) + '%');
+}
+
+main().catch(console.error);
@@ -0,0 +1,67 @@
+/**
+ * Content Guardrails Example
+ * Demonstrates input/output validation
+ */
+
+import { guardrail, GuardrailManager, builtinGuardrails, LLMGuardrail } from 'praisonai';
+
+async function main() {
+  // Create custom guardrail
+  const noSpamGuardrail = guardrail({
+    name: 'no_spam',
+    check: (content) => {
+      const spamWords = ['buy now', 'free money', 'click here'];
+      const hasSpam = spamWords.some(word => 
+        content.toLowerCase().includes(word)
+      );
+      return {
+        status: hasSpam ? 'failed' : 'passed',
+        message: hasSpam ? 'Content contains spam' : undefined
+      };
+    }
+  });
+
+  // Use built-in guardrails
+  const maxLength = builtinGuardrails.maxLength(500);
+  const minLength = builtinGuardrails.minLength(10);
+  const blockedWords = builtinGuardrails.blockedWords(['badword1', 'badword2']);
+
+  // Create manager
+  const manager = new GuardrailManager();
+  manager.add(noSpamGuardrail);
+  manager.add(maxLength);
+  manager.add(minLength);
+  manager.add(blockedWords);
+
+  // Test content
+  const testCases = [
+    'This is a normal, helpful response about programming.',
+    'BUY NOW! Free money if you click here!',
+    'Short',
+    'This is a valid response that provides useful information about TypeScript and its benefits for developers.'
+  ];
+
+  console.log('=== Guardrail Tests ===\n');
+
+  for (const content of testCases) {
+    console.log(`Content: "${content.substring(0, 40)}..."`);
+    const result = await manager.runAll(content);
+    console.log(`  Passed: ${result.passed}`);
+    if (!result.passed) {
+      result.results
+        .filter(r => r.status === 'failed')
+        .forEach(r => console.log(`  Failed: ${r.message}`));
+    }
+    console.log();
+  }
+
+  // LLM Guardrail example
+  console.log('=== LLM Guardrail ===');
+  const llmGuard = new LLMGuardrail({
+    name: 'quality_check',
+    criteria: 'Content must be helpful and professional'
+  });
+  console.log('LLM Guardrail created:', llmGuard.name);
+}
+
+main().catch(console.error);
@@ -0,0 +1,62 @@
+/**
+ * Knowledge Base (RAG) Example
+ * Demonstrates retrieval-augmented generation
+ */
+
+import { KnowledgeBase, createKnowledgeBase, Chunking } from 'praisonai';
+
+async function main() {
+  // Create knowledge base
+  const kb = createKnowledgeBase();
+
+  // Add documents
+  const documents = [
+    {
+      id: 'ts-intro',
+      content: 'TypeScript is a strongly typed programming language that builds on JavaScript, giving you better tooling at any scale.',
+      metadata: { category: 'introduction', language: 'typescript' }
+    },
+    {
+      id: 'ts-types',
+      content: 'TypeScript adds optional static typing and class-based object-oriented programming to the language.',
+      metadata: { category: 'features', language: 'typescript' }
+    },
+    {
+      id: 'ts-benefits',
+      content: 'Benefits of TypeScript include catching errors early, better IDE support, and improved code maintainability.',
+      metadata: { category: 'benefits', language: 'typescript' }
+    },
+    {
+      id: 'js-intro',
+      content: 'JavaScript is a lightweight, interpreted programming language with first-class functions.',
+      metadata: { category: 'introduction', language: 'javascript' }
+    }
+  ];
+
+  for (const doc of documents) {
+    await kb.add(doc);
+  }
+
+  console.log('Documents added:', kb.size);
+
+  // Search
+  console.log('\n=== Search: "TypeScript benefits" ===');
+  const results = await kb.search('TypeScript benefits', 3);
+  results.forEach(r => {
+    console.log(`Score: ${r.score.toFixed(2)} - ${r.document.content.substring(0, 50)}...`);
+  });
+
+  // Build context
+  console.log('\n=== Context for LLM ===');
+  const context = kb.buildContext(results);
+  console.log(context);
+
+  // Chunking example
+  console.log('\n=== Chunking Example ===');
+  const chunker = new Chunking({ chunkSize: 100, overlap: 20 });
+  const longText = 'This is a long document. '.repeat(20);
+  const chunks = chunker.chunk(longText);
+  console.log(`Chunked into ${chunks.length} pieces`);
+}
+
+main().catch(console.error);
@@ -0,0 +1,42 @@
+/**
+ * Conversation Memory Example
+ * Demonstrates memory management for conversations
+ */
+
+import { Memory, createMemory } from 'praisonai';
+
+async function main() {
+  const memory = createMemory({
+    maxEntries: 100,
+    maxTokens: 10000
+  });
+
+  // Simulate a conversation
+  await memory.add('What is TypeScript?', 'user');
+  await memory.add('TypeScript is a strongly typed programming language that builds on JavaScript.', 'assistant');
+  await memory.add('What are its main benefits?', 'user');
+  await memory.add('Key benefits include type safety, better IDE support, and easier refactoring.', 'assistant');
+  await memory.add('Can you give an example?', 'user');
+
+  console.log('Memory size:', memory.size, 'entries\n');
+
+  // Get recent messages
+  console.log('=== Recent Messages ===');
+  const recent = memory.getRecent(3);
+  recent.forEach(entry => {
+    console.log(`[${entry.role}]: ${entry.content.substring(0, 50)}...`);
+  });
+
+  // Search memory
+  console.log('\n=== Search Results for "TypeScript" ===');
+  const results = await memory.search('TypeScript');
+  results.forEach(r => {
+    console.log(`Score: ${r.score.toFixed(2)} - ${r.entry.content.substring(0, 40)}...`);
+  });
+
+  // Build context
+  console.log('\n=== Full Context ===');
+  console.log(memory.buildContext());
+}
+
+main().catch(console.error);
@@ -0,0 +1,60 @@
+/**
+ * Observability Example
+ * Demonstrates tracing and monitoring
+ */
+
+import { MemoryObservabilityAdapter, ConsoleObservabilityAdapter } from 'praisonai';
+
+async function main() {
+  // Memory adapter - stores traces in memory
+  const memoryAdapter = new MemoryObservabilityAdapter();
+
+  // Start a trace
+  const trace = memoryAdapter.startTrace('agent-execution');
+  console.log('Trace started:', trace.traceId);
+
+  // Create spans for different operations
+  const llmSpan = trace.startSpan('llm-call', 'llm');
+  llmSpan.setAttribute('model', 'gpt-4o-mini');
+  llmSpan.setAttribute('tokens', 150);
+  await new Promise(r => setTimeout(r, 100)); // Simulate work
+  llmSpan.end();
+
+  const toolSpan = trace.startSpan('tool-execution', 'tool');
+  toolSpan.setAttribute('tool', 'calculator');
+  toolSpan.addEvent('tool-started', { input: '2+2' });
+  await new Promise(r => setTimeout(r, 50)); // Simulate work
+  toolSpan.addEvent('tool-completed', { output: '4' });
+  toolSpan.end();
+
+  // End trace
+  trace.end();
+
+  // Retrieve trace data
+  const traceData = memoryAdapter.getTrace(trace.traceId);
+  console.log('\n=== Trace Data ===');
+  console.log('Trace ID:', traceData?.traceId);
+  console.log('Spans:', traceData?.spans.length);
+  console.log('Duration:', traceData?.endTime! - traceData?.startTime!, 'ms');
+
+  // Show spans
+  console.log('\n=== Spans ===');
+  traceData?.spans.forEach(span => {
+    console.log(`- ${span.name} (${span.kind}): ${span.endTime! - span.startTime}ms`);
+    if (span.attributes) {
+      Object.entries(span.attributes).forEach(([k, v]) => {
+        console.log(`    ${k}: ${v}`);
+      });
+    }
+  });
+
+  // Console adapter example
+  console.log('\n=== Console Adapter ===');
+  const consoleAdapter = new ConsoleObservabilityAdapter();
+  const trace2 = consoleAdapter.startTrace('demo-trace');
+  const span = trace2.startSpan('demo-span', 'custom');
+  span.end();
+  trace2.end();
+}
+
+main().catch(console.error);
@@ -0,0 +1,71 @@
+/**
+ * Planning System Example
+ * Demonstrates plans, steps, and todo lists
+ */
+
+import { Plan, PlanStep, TodoList, TodoItem, PlanStorage, createPlan, createTodoList } from 'praisonai';
+
+async function main() {
+  // Create a project plan
+  console.log('=== Project Plan ===');
+  const plan = createPlan({ 
+    name: 'Build AI Agent',
+    description: 'Create a fully functional AI agent'
+  });
+
+  plan.addStep(new PlanStep({ description: 'Design agent architecture' }));
+  plan.addStep(new PlanStep({ description: 'Implement core functionality' }));
+  plan.addStep(new PlanStep({ description: 'Add tool support' }));
+  plan.addStep(new PlanStep({ description: 'Write tests' }));
+  plan.addStep(new PlanStep({ description: 'Deploy to production' }));
+
+  console.log('Plan:', plan.name);
+  console.log('Steps:', plan.steps.length);
+
+  // Execute steps
+  plan.start();
+  plan.steps[0].start();
+  plan.steps[0].complete();
+  plan.steps[1].start();
+  plan.steps[1].complete();
+
+  const progress = plan.getProgress();
+  console.log(`Progress: ${progress.completed}/${progress.total} (${progress.percentage}%)`);
+
+  // Create todo list
+  console.log('\n=== Todo List ===');
+  const todos = createTodoList('Sprint Tasks');
+
+  todos.add(new TodoItem({ content: 'Review PR #123', priority: 'high' }));
+  todos.add(new TodoItem({ content: 'Fix bug in router', priority: 'high' }));
+  todos.add(new TodoItem({ content: 'Update documentation', priority: 'medium' }));
+  todos.add(new TodoItem({ content: 'Refactor tests', priority: 'low' }));
+
+  console.log('Total items:', todos.items.length);
+  console.log('High priority:', todos.getByPriority('high').length);
+
+  // Complete some items
+  todos.items[0].complete();
+  todos.items[1].start();
+
+  console.log('Pending:', todos.getPending().length);
+  console.log('Completed:', todos.getCompleted().length);
+
+  const todoProgress = todos.getProgress();
+  console.log(`Progress: ${todoProgress.completed}/${todoProgress.total} (${todoProgress.percentage}%)`);
+
+  // Use storage
+  console.log('\n=== Plan Storage ===');
+  const storage = new PlanStorage();
+  storage.savePlan(plan);
+  storage.saveTodoList(todos);
+
+  console.log('Saved plans:', storage.listPlans().length);
+  console.log('Saved todo lists:', storage.listTodoLists().length);
+
+  // Retrieve
+  const retrieved = storage.getPlan(plan.id);
+  console.log('Retrieved plan:', retrieved?.name);
+}
+
+main().catch(console.error);
@@ -0,0 +1,74 @@
+/**
+ * Skills System Example
+ * Demonstrates skill management and parsing
+ */
+
+import { SkillManager, parseSkillFile, createSkillManager } from 'praisonai';
+
+async function main() {
+  // Parse a skill file
+  const skillContent = `---
+name: code-review
+description: Reviews code for best practices and potential issues
+license: MIT
+metadata:
+  author: praisonai
+  version: "1.0"
+allowed-tools: Read Grep
+---
+
+# Code Review Skill
+
+When reviewing code:
+1. Check for syntax errors
+2. Look for security vulnerabilities
+3. Suggest performance improvements
+4. Ensure proper error handling
+`;
+
+  console.log('=== Parse Skill File ===');
+  const skill = parseSkillFile(skillContent);
+  console.log('Name:', skill.metadata.name);
+  console.log('Description:', skill.metadata.description);
+  console.log('License:', skill.metadata.license);
+  console.log('Instructions preview:', skill.instructions.substring(0, 100) + '...');
+
+  // Create skill manager
+  console.log('\n=== Skill Manager ===');
+  const manager = createSkillManager({ paths: [] });
+
+  // Register skills manually
+  manager.register({
+    metadata: {
+      name: 'typescript-expert',
+      description: 'Expert knowledge in TypeScript development'
+    },
+    instructions: 'You are a TypeScript expert. Help with type definitions, generics, and best practices.'
+  });
+
+  manager.register({
+    metadata: {
+      name: 'api-designer',
+      description: 'Designs RESTful APIs following best practices'
+    },
+    instructions: 'You design clean, RESTful APIs with proper versioning and documentation.'
+  });
+
+  // List skills
+  console.log('Registered skills:');
+  manager.list().forEach(s => {
+    console.log(`- ${s.metadata.name}: ${s.metadata.description}`);
+  });
+
+  // Get specific skill
+  const tsSkill = manager.get('typescript-expert');
+  console.log('\n=== TypeScript Expert Skill ===');
+  console.log('Instructions:', tsSkill?.instructions);
+
+  // Generate prompt
+  console.log('\n=== Generated Prompt ===');
+  const prompt = manager.generatePrompt(['typescript-expert']);
+  console.log(prompt.substring(0, 200) + '...');
+}
+
+main().catch(console.error);
@@ -0,0 +1,61 @@
+/**
+ * Basic Tools Example
+ * Demonstrates tool creation and usage
+ */
+
+import { tool, ToolRegistry, getRegistry } from 'praisonai';
+
+async function main() {
+  // Create tools
+  const calculator = tool({
+    name: 'calculator',
+    description: 'Perform basic math calculations',
+    parameters: {
+      type: 'object',
+      properties: {
+        expression: { type: 'string', description: 'Math expression to evaluate' }
+      },
+      required: ['expression']
+    },
+    execute: async ({ expression }) => {
+      try {
+        const result = eval(expression);
+        return `Result: ${result}`;
+      } catch (e) {
+        return 'Error: Invalid expression';
+      }
+    }
+  });
+
+  const greeter = tool({
+    name: 'greeter',
+    description: 'Generate a greeting',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name to greet' }
+      },
+      required: ['name']
+    },
+    execute: async ({ name }) => `Hello, ${name}! Welcome to PraisonAI.`
+  });
+
+  // Create registry and register tools
+  const registry = new ToolRegistry();
+  registry.register(calculator);
+  registry.register(greeter);
+
+  console.log('Registered tools:', registry.list().map(t => t.name));
+
+  // Execute tools
+  const calcResult = await calculator.execute({ expression: '10 * 5 + 2' });
+  console.log('\nCalculator:', calcResult);
+
+  const greetResult = await greeter.execute({ name: 'Developer' });
+  console.log('Greeter:', greetResult);
+
+  // Get OpenAI format
+  console.log('\nOpenAI tool format:', JSON.stringify(calculator.toOpenAITool(), null, 2));
+}
+
+main().catch(console.error);
@@ -0,0 +1,113 @@
+/**
+ * Custom Tool Example
+ * Demonstrates creating custom tools using BaseTool class (plugin pattern)
+ */
+
+import { BaseTool, createTool, tool, ToolRegistry } from 'praisonai';
+
+// Method 1: Extend BaseTool class (recommended for complex tools)
+class WeatherTool extends BaseTool<{ location: string; units?: string }, { temp: number; condition: string }> {
+  name = 'get_weather';
+  description = 'Get current weather for a location';
+  parameters = {
+    type: 'object' as const,
+    properties: {
+      location: { type: 'string', description: 'City name' },
+      units: { type: 'string', description: 'celsius or fahrenheit', default: 'celsius' }
+    },
+    required: ['location']
+  };
+
+  async run(params: { location: string; units?: string }): Promise<{ temp: number; condition: string }> {
+    // Simulate API call
+    console.log(`Getting weather for ${params.location} in ${params.units || 'celsius'}`);
+    return { temp: 22, condition: 'sunny' };
+  }
+}
+
+// Method 2: Use createTool function (quick inline tools)
+const calculatorTool = createTool({
+  name: 'calculator',
+  description: 'Evaluate a math expression',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: { type: 'string', description: 'Math expression to evaluate' }
+    },
+    required: ['expression']
+  },
+  run: (params: { expression: string }) => {
+    try {
+      return eval(params.expression);
+    } catch {
+      return 'Error: Invalid expression';
+    }
+  }
+});
+
+// Method 3: Use tool() function with config object
+const greeterTool = tool({
+  name: 'greeter',
+  description: 'Generate a personalized greeting',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'Name to greet' },
+      style: { type: 'string', description: 'Greeting style: formal or casual' }
+    },
+    required: ['name']
+  },
+  execute: async (params: { name: string; style?: string }) => {
+    if (params.style === 'formal') {
+      return `Good day, ${params.name}. How may I assist you?`;
+    }
+    return `Hey ${params.name}! What's up?`;
+  }
+});
+
+async function main() {
+  console.log('=== Custom Tool Examples ===\n');
+
+  // Test WeatherTool (class-based)
+  console.log('--- WeatherTool (class-based) ---');
+  const weather = new WeatherTool();
+  console.log('Name:', weather.name);
+  console.log('Description:', weather.description);
+  
+  const weatherResult = await weather.run({ location: 'New York' });
+  console.log('Result:', weatherResult);
+  
+  // Safe execution with error handling
+  const safeResult = await weather.safeRun({ location: 'London' });
+  console.log('Safe result:', safeResult);
+
+  // Get OpenAI schema
+  console.log('OpenAI Schema:', JSON.stringify(weather.getSchema(), null, 2));
+
+  // Test calculatorTool (createTool)
+  console.log('\n--- Calculator Tool (createTool) ---');
+  const calcResult = await calculatorTool.run({ expression: '10 * 5 + 2' });
+  console.log('10 * 5 + 2 =', calcResult);
+
+  // Test greeterTool (tool function)
+  console.log('\n--- Greeter Tool (tool function) ---');
+  const greeting1 = await greeterTool.execute({ name: 'Alice' });
+  console.log('Casual:', greeting1);
+  
+  const greeting2 = await greeterTool.execute({ name: 'Mr. Smith', style: 'formal' });
+  console.log('Formal:', greeting2);
+
+  // Register tools in registry
+  console.log('\n--- Tool Registry ---');
+  const registry = new ToolRegistry();
+  registry.register(greeterTool);
+  
+  console.log('Registered tools:', registry.list().map(t => t.name));
+  console.log('OpenAI tools format:', registry.toOpenAITools().length, 'tools');
+
+  // Validate tool
+  console.log('\n--- Validation ---');
+  console.log('WeatherTool valid:', weather.validate());
+}
+
+main().catch(console.error);
@@ -0,0 +1,57 @@
+/**
+ * Pinecone Vector Store Example
+ */
+
+import { createPineconeStore } from 'praisonai';
+
+async function main() {
+  const pinecone = createPineconeStore({
+    apiKey: process.env.PINECONE_API_KEY!
+  });
+
+  const indexName = 'test-index';
+
+  // Create index
+  console.log('Creating index...');
+  await pinecone.createIndex({
+    indexName,
+    dimension: 3,
+    metric: 'cosine'
+  });
+
+  // List indexes
+  const indexes = await pinecone.listIndexes();
+  console.log('Indexes:', indexes);
+
+  // Upsert vectors
+  console.log('Upserting vectors...');
+  await pinecone.upsert({
+    indexName,
+    vectors: [
+      { id: 'vec-1', vector: [0.1, 0.2, 0.3], metadata: { category: 'A' } },
+      { id: 'vec-2', vector: [0.4, 0.5, 0.6], metadata: { category: 'B' } },
+      { id: 'vec-3', vector: [0.7, 0.8, 0.9], metadata: { category: 'A' } }
+    ]
+  });
+
+  // Query
+  console.log('Querying...');
+  const results = await pinecone.query({
+    indexName,
+    vector: [0.1, 0.2, 0.3],
+    topK: 2,
+    includeMetadata: true
+  });
+
+  console.log('Results:');
+  for (const r of results) {
+    console.log(`  ${r.id}: score=${r.score.toFixed(4)}, metadata=${JSON.stringify(r.metadata)}`);
+  }
+
+  // Cleanup
+  console.log('Deleting index...');
+  await pinecone.deleteIndex(indexName);
+  console.log('Done!');
+}
+
+main().catch(console.error);
@@ -0,0 +1,30 @@
+/**
+ * Voice/TTS Example
+ */
+
+import { createOpenAIVoice } from '../../../src/praisonai-ts/src';
+import { writeFileSync } from 'fs';
+
+async function main() {
+  const voice = createOpenAIVoice({
+    apiKey: process.env.OPENAI_API_KEY
+  });
+
+  // Check available voices
+  const speakers = await voice.getSpeakers();
+  console.log('Available voices:', speakers.map(s => s.name).join(', '));
+
+  // Generate speech
+  console.log('Generating speech...');
+  const audio = await voice.speak('Hello! Welcome to PraisonAI TypeScript SDK.', {
+    voice: 'nova',
+    speed: 1.0,
+    format: 'mp3'
+  });
+
+  // Save to file
+  writeFileSync('output.mp3', audio);
+  console.log('Audio saved to output.mp3');
+}
+
+main().catch(console.error);
@@ -0,0 +1,29 @@
+/**
+ * Basic Workflow Example
+ * Demonstrates sequential workflow execution
+ */
+
+import { Workflow, parallel, route, loop } from 'praisonai';
+
+async function main() {
+  // Create a simple workflow
+  const workflow = new Workflow<string, string>('DataProcessor')
+    .step('validate', async (input) => {
+      console.log('Step 1: Validating input...');
+      return input.trim();
+    })
+    .step('transform', async (input) => {
+      console.log('Step 2: Transforming...');
+      return input.toUpperCase();
+    })
+    .step('format', async (input) => {
+      console.log('Step 3: Formatting...');
+      return `[PROCESSED] ${input}`;
+    });
+
+  const result = await workflow.run('  hello world  ');
+  console.log('\nFinal output:', result.output);
+  console.log('Steps executed:', result.steps.length);
+}
+
+main().catch(console.error);
@@ -0,0 +1,48 @@
+/**
+ * Conditional Workflow Example
+ * Demonstrates routing based on conditions
+ */
+
+import { route } from 'praisonai';
+
+async function main() {
+  const processRequest = async (type: string) => {
+    console.log(`Processing request type: ${type}`);
+
+    const result = await route([
+      {
+        condition: () => type === 'urgent',
+        execute: async () => {
+          console.log('  -> Urgent handler activated');
+          return 'Processed urgently';
+        }
+      },
+      {
+        condition: () => type === 'normal',
+        execute: async () => {
+          console.log('  -> Normal handler activated');
+          return 'Processed normally';
+        }
+      },
+      {
+        condition: () => true, // Default
+        execute: async () => {
+          console.log('  -> Default handler activated');
+          return 'Processed with default handler';
+        }
+      }
+    ]);
+
+    return result;
+  };
+
+  // Test different request types
+  const types = ['urgent', 'normal', 'unknown'];
+  
+  for (const type of types) {
+    const result = await processRequest(type);
+    console.log(`Result: ${result}\n`);
+  }
+}
+
+main().catch(console.error);
@@ -0,0 +1,36 @@
+/**
+ * Parallel Workflow Example
+ * Demonstrates parallel execution of tasks
+ */
+
+import { parallel } from 'praisonai';
+
+async function main() {
+  console.log('Starting parallel tasks...\n');
+
+  const results = await parallel([
+    async () => {
+      console.log('Task 1: Starting...');
+      await new Promise(r => setTimeout(r, 1000));
+      console.log('Task 1: Complete');
+      return 'Result 1';
+    },
+    async () => {
+      console.log('Task 2: Starting...');
+      await new Promise(r => setTimeout(r, 500));
+      console.log('Task 2: Complete');
+      return 'Result 2';
+    },
+    async () => {
+      console.log('Task 3: Starting...');
+      await new Promise(r => setTimeout(r, 750));
+      console.log('Task 3: Complete');
+      return 'Result 3';
+    }
+  ]);
+
+  console.log('\nAll tasks complete!');
+  console.log('Results:', results);
+}
+
+main().catch(console.error);
@@ -0,0 +1,55 @@
+"""
+Basic Middleware Example - PraisonAI Agents
+
+Demonstrates before/after hooks and wrap decorators for model and tool calls.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.hooks import (
+    before_model, after_model, wrap_model_call,
+    before_tool, after_tool, wrap_tool_call,
+    InvocationContext, ModelRequest, ModelResponse
+)
+
+# Simple tool for demonstration
+@tool
+def get_weather(city: str) -> str:
+    """Get weather for a city."""
+    return f"Sunny, 22°C in {city}"
+
+# Before model hook - adds context
+@before_model
+def add_context(request: ModelRequest) -> ModelRequest:
+    print(f"[before_model] Adding context to request")
+    return request
+
+# After model hook - logs response
+@after_model  
+def log_response(response: ModelResponse) -> ModelResponse:
+    print(f"[after_model] Response received")
+    return response
+
+# Wrap tool call - retry on error
+@wrap_tool_call
+def retry_on_error(tool_call, call_next):
+    print(f"[wrap_tool_call] Executing tool")
+    try:
+        return call_next(tool_call)
+    except Exception as e:
+        print(f"[wrap_tool_call] Retrying after error: {e}")
+        return call_next(tool_call)
+
+# Create agent with hooks
+agent = Agent(
+    name="WeatherBot",
+    instructions="You help with weather queries.",
+    tools=[get_weather],
+    hooks=[add_context, log_response, retry_on_error]
+)
+
+if __name__ == "__main__":
+    # Test the tool directly
+    result = get_weather("London")
+    print(f"Weather: {result}")
+    
+    print("\n✓ Middleware example complete")
@@ -0,0 +1,31 @@
+"""
+Configurable Model Example - PraisonAI Agents
+
+Demonstrates runtime model switching without recreating the agent.
+"""
+
+from praisonaiagents import Agent
+
+# Create agent with configurable model enabled
+agent = Agent(
+    name="FlexBot",
+    instructions="You are a helpful assistant.",
+    llm="gpt-4o-mini",
+    llm_config={"configurable": True}
+)
+
+if __name__ == "__main__":
+    # Default model call
+    print("Using default model (gpt-4o-mini)...")
+    # response = agent.chat("Say hello in 5 words")
+    
+    # Override model per-call
+    print("\nOverriding to different model...")
+    # response = agent.chat("Say hello in 5 words", config={"model": "gpt-4o"})
+    
+    # Override temperature
+    print("\nOverriding temperature...")
+    # response = agent.chat("Say hello creatively", config={"temperature": 0.9})
+    
+    print("\n✓ Configurable model example complete")
+    print("Note: Uncomment agent.chat() calls to run with API key")
@@ -0,0 +1,50 @@
+"""
+Injected State Example - PraisonAI Agents
+
+Demonstrates injecting agent state into tools without exposing it in the schema.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.tools import Injected
+from praisonaiagents.tools.injected import AgentState, with_injection_context
+
+# Tool with injected state - state param is NOT in the public schema
+@tool
+def show_context(query: str, state: Injected[dict]) -> str:
+    """Show the current agent context."""
+    session_id = state.get('session_id', 'unknown')
+    agent_id = state.get('agent_id', 'unknown')
+    return f"Query: {query}, Session: {session_id}, Agent: {agent_id}"
+
+# Create agent with the tool
+agent = Agent(
+    name="ContextBot",
+    instructions="You help show context information.",
+    tools=[show_context],
+    session_id="my-session-123"
+)
+
+if __name__ == "__main__":
+    # Verify injected param is not in schema
+    schema = show_context.get_schema()
+    params = schema['function']['parameters']['properties']
+    print(f"Schema params: {list(params.keys())}")
+    assert 'state' not in params, "state should NOT be in schema"
+    print("✓ 'state' correctly excluded from schema")
+    
+    # Test with manual injection context
+    mock_state = AgentState(
+        agent_id="test-agent",
+        run_id="run-1",
+        session_id="session-abc"
+    )
+    
+    with with_injection_context(mock_state):
+        result = show_context(query="hello")
+        print(f"Result: {result}")
+    
+    # Test via agent.execute_tool
+    result = agent.execute_tool("show_context", {"query": "test"})
+    print(f"Agent result: {result}")
+    
+    print("\n✓ Injected state example complete")
@@ -0,0 +1,29 @@
+"""
+Rate Limiter Example - PraisonAI Agents
+
+Demonstrates token bucket rate limiting for LLM API calls.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.llm import RateLimiter
+
+# Create rate limiter: 60 requests per minute
+limiter = RateLimiter(requests_per_minute=60, burst=5)
+
+# Create agent with rate limiter
+agent = Agent(
+    name="RateLimitedBot",
+    instructions="You are a helpful assistant.",
+    rate_limiter=limiter
+)
+
+if __name__ == "__main__":
+    print(f"Rate limiter: {limiter}")
+    print(f"Available tokens: {limiter.available_tokens}")
+    
+    # Demonstrate rate limiting
+    for i in range(3):
+        limiter.acquire()
+        print(f"Request {i+1} acquired, tokens left: {limiter.available_tokens:.1f}")
+    
+    print("\n✓ Rate limiter example complete")
@@ -0,0 +1,40 @@
+"""Multi-Agent Shared Session - DB Persistence Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_conversation_store
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+# Create shared session for multiple agents
+store = create_conversation_store("sqlite", path="/tmp/multi_agent.db")
+session_id = "shared-session-123"
+
+# Create session
+session = ConversationSession(session_id=session_id, agent_id="multi")
+try:
+    store.create_session(session)
+except Exception:
+    pass
+
+# Agent 1 writes
+msg1 = ConversationMessage(session_id=session_id, role="user", content="Agent1: Hello")
+store.add_message(session_id, msg1)
+msg2 = ConversationMessage(session_id=session_id, role="assistant", content="Agent1: Hi there!")
+store.add_message(session_id, msg2)
+
+# Agent 2 writes to same session
+msg3 = ConversationMessage(session_id=session_id, role="user", content="Agent2: What did Agent1 say?")
+store.add_message(session_id, msg3)
+msg4 = ConversationMessage(session_id=session_id, role="assistant", content="Agent2: Agent1 said Hello")
+store.add_message(session_id, msg4)
+
+# Verify both agents' messages are in session
+messages = store.get_messages(session_id)
+print(f"Total messages in shared session: {len(messages)}")
+assert len(messages) >= 4, "Should have messages from both agents"
+
+# Verify content
+contents = [m.content for m in messages]
+assert any("Agent1" in c for c in contents), "Should have Agent1 messages"
+assert any("Agent2" in c for c in contents), "Should have Agent2 messages"
+
+print("PASSED: Multi-agent shared session persistence")
@@ -0,0 +1,108 @@
+"""
+Performance Benchmark Example for PraisonAI.
+
+This example demonstrates how to measure and verify performance metrics
+for PraisonAI CLI and SDK imports.
+
+Usage:
+    python benchmark_example.py
+"""
+
+import time
+import tracemalloc
+import sys
+
+
+def measure_import_time(module_name: str) -> float:
+    """Measure import time for a module."""
+    # Clear from cache if already imported
+    if module_name in sys.modules:
+        del sys.modules[module_name]
+    
+    start = time.time()
+    __import__(module_name)
+    elapsed = time.time() - start
+    return elapsed * 1000  # Return milliseconds
+
+
+def measure_memory_usage(import_func) -> tuple:
+    """Measure memory usage during import."""
+    tracemalloc.start()
+    import_func()
+    current, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    return current / 1024 / 1024, peak / 1024 / 1024  # Return MB
+
+
+def main():
+    print("=" * 60)
+    print("PraisonAI Performance Benchmark")
+    print("=" * 60)
+    
+    # Test 1: CLI Import Time
+    print("\n1. CLI Import Time")
+    print("-" * 40)
+    
+    import os
+    os.environ['LOGLEVEL'] = 'WARNING'
+    
+    start = time.time()
+    from praisonai.cli.main import PraisonAI
+    cli_import_time = (time.time() - start) * 1000
+    
+    print(f"   CLI import time: {cli_import_time:.0f}ms")
+    print(f"   Status: {'✓ FAST' if cli_import_time < 500 else '✗ SLOW'}")
+    
+    # Test 2: Memory Usage
+    print("\n2. Memory Usage")
+    print("-" * 40)
+    
+    tracemalloc.start()
+    # Force re-import by clearing cache
+    for mod in list(sys.modules.keys()):
+        if 'praisonai' in mod:
+            del sys.modules[mod]
+    
+    from praisonai.cli.main import PraisonAI as PraisonAI2
+    current, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    
+    print(f"   Current memory: {current/1024/1024:.1f}MB")
+    print(f"   Peak memory: {peak/1024/1024:.1f}MB")
+    print(f"   Status: {'✓ LOW' if peak/1024/1024 < 50 else '✗ HIGH'}")
+    
+    # Test 3: Lazy Loading Verification
+    print("\n3. Lazy Loading Verification")
+    print("-" * 40)
+    
+    heavy_modules = ['litellm', 'instructor', 'praisonai.auto']
+    loaded = [m for m in heavy_modules if m in sys.modules]
+    
+    if loaded:
+        print(f"   Heavy modules loaded: {loaded}")
+        print("   Status: ✗ NOT LAZY")
+    else:
+        print("   Heavy modules NOT loaded at startup")
+        print("   Status: ✓ LAZY")
+    
+    # Summary
+    print("\n" + "=" * 60)
+    print("Summary")
+    print("=" * 60)
+    
+    all_pass = (
+        cli_import_time < 500 and
+        peak/1024/1024 < 50 and
+        len(loaded) == 0
+    )
+    
+    if all_pass:
+        print("✓ All performance benchmarks PASSED")
+    else:
+        print("✗ Some benchmarks FAILED")
+    
+    return 0 if all_pass else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -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'}")
@@ -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!")
@@ -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())
@@ -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!")
@@ -1,7 +1,7 @@
 """
-Qdrant Knowledge Store Example for PraisonAI.
+Qdrant Knowledge Store - Agent-First Example

-Demonstrates vector insert + search through the knowledge store.
+Demonstrates using Qdrant for knowledge-based RAG with an Agent.

 Requirements:
    pip install "praisonai[tools]"
@@ -13,67 +13,59 @@ Run:
    python knowledge_qdrant.py

 Expected Output:
-    === Qdrant Knowledge Store Demo ===
-    Created collection: demo_knowledge
-    Inserted 3 documents
-    Search results: 2 documents found
+    Agent responds using knowledge from documents
 """

-from praisonai.persistence.factory import create_knowledge_store
-from praisonai.persistence.knowledge.base import KnowledgeDocument
-import random
+from praisonaiagents import Agent
+import tempfile
+import os
+import shutil

-# Create Qdrant knowledge store
-store = create_knowledge_store("qdrant", url="http://localhost:6333")
+# Create sample knowledge document
+sample_doc = """
+# AI and Programming Guide

-collection_name = "demo_knowledge"
-dimension = 384  # Embedding dimension
+## Python Programming
+Python is a versatile programming language used for web development, data science, and AI.
+It has a simple syntax and extensive libraries.

-# Create collection
-print("=== Qdrant Knowledge Store Demo ===")
-if store.collection_exists(collection_name):
-    store.delete_collection(collection_name)
+## Machine Learning
+Machine learning enables computers to learn patterns from data without explicit programming.
+Common frameworks include TensorFlow, PyTorch, and scikit-learn.

-store.create_collection(collection_name, dimension=dimension)
-print(f"Created collection: {collection_name}")
+## Databases
+PostgreSQL is a powerful open-source relational database system.
+It supports both SQL and JSON data types.
+"""

-# Create sample documents with embeddings
-random.seed(42)
-documents = [
-    KnowledgeDocument(
-        id="doc-1",
-        content="Python is a versatile programming language used for web development, data science, and AI.",
-        embedding=[random.random() for _ in range(dimension)],
-        metadata={"category": "programming", "language": "python"}
-    ),
-    KnowledgeDocument(
-        id="doc-2", 
-        content="Machine learning enables computers to learn patterns from data without explicit programming.",
-        embedding=[random.random() for _ in range(dimension)],
-        metadata={"category": "ai", "topic": "ml"}
-    ),
-    KnowledgeDocument(
-        id="doc-3",
-        content="PostgreSQL is a powerful open-source relational database system.",
-        embedding=[random.random() for _ in range(dimension)],
-        metadata={"category": "database", "type": "sql"}
-    ),
-]
+# Save to temp file
+temp_dir = tempfile.mkdtemp()
+doc_path = os.path.join(temp_dir, "guide.txt")
+with open(doc_path, "w") as f:
+    f.write(sample_doc)

-# Insert documents
-ids = store.insert(collection_name, documents)
-print(f"Inserted {len(ids)} documents")
+print("=== Qdrant Knowledge Store Demo (Agent-First) ===")

-# Search for similar documents
-query_embedding = [random.random() for _ in range(dimension)]
-results = store.search(collection_name, query_embedding, limit=2)
-print(f"Search results: {len(results)} documents found")
+# Agent-first approach: use knowledge parameter with Qdrant
+agent = Agent(
+    name="KnowledgeAssistant",
+    instructions="You are a helpful assistant with access to technical documentation.",
+    knowledge=[doc_path],
+    knowledge_config={
+        "vector_store": "qdrant",
+        "url": "http://localhost:6333"
+    }
+)

-for doc in results:
-    print(f"  - {doc.id}: {doc.content[:50]}...")
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What programming language is good for AI?")
+print(f"Response: {response}")

 # Cleanup
-store.delete_collection(collection_name)
-store.close()
+shutil.rmtree(temp_dir)

 print("\n=== Demo Complete ===")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence.factory import create_knowledge_store
+# store = create_knowledge_store("qdrant", url="http://localhost:6333")
@@ -1,83 +1,46 @@
 """
-Redis State Store
+Redis State Store - Agent-First Example

-Use Redis for state management, tracing, and caching.
+Use Redis for state management with an Agent.
+
+Docker Setup:
+    docker run -d --name redis -p 6379:6379 redis:7

 Run:
    python redis_state.py

 Expected output:
-    - State operations (set/get/delete)
-    - Tracing operations
+    Agent responds with state persisted to Redis
 """

-from praisonaiagents import db
+from praisonaiagents import Agent, db

-# Create Redis-only database (for state/tracing)
-redis_db = db.RedisDB(host="localhost", port=6379)
+print("=== Redis State Store (Agent-First) ===")

-print("=== Redis State Store ===")
-
-# Test state operations
-print("\n1. State Operations:")
-redis_db._init_stores()  # Initialize stores
-
-# Set a value
-redis_db._state_store.set("user:123:preferences", {
-    "theme": "dark",
-    "language": "en"
-})
-print("   Set user preferences")
-
-# Get the value
-prefs = redis_db._state_store.get("user:123:preferences")
-print(f"   Got preferences: {prefs}")
-
-# Set with TTL (expires in 60 seconds)
-redis_db._state_store.set("temp:token", "abc123", ttl=60)
-print("   Set temporary token (60s TTL)")
-
-# Delete
-redis_db._state_store.delete("user:123:preferences")
-print("   Deleted preferences")
-
-# Test tracing
-print("\n2. Tracing Operations:")
-
-# Start a trace
-trace_id = "trace-example-001"
-redis_db.on_trace_start(
-    trace_id=trace_id,
-    session_id="example-session",
-    agent_name="ExampleAgent",
-    metadata={"purpose": "demo"}
+# Agent-first approach: use db parameter with Redis state store
+my_db = db(
+    database_url="sqlite:///conversations.db",  # Conversations
+    state_url="redis://localhost:6379"          # State/tracing
 )
-print(f"   Started trace: {trace_id}")

-# Add spans
-span_id = "span-llm-001"
-redis_db.on_span_start(
-    span_id=span_id,
-    trace_id=trace_id,
-    name="llm_call",
-    attributes={"model": "gpt-4", "temperature": 0.7}
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    db=my_db,
+    session_id="redis-state-session"
 )
-print(f"   Started span: {span_id}")

-redis_db.on_span_end(
-    span_id=span_id,
-    status="ok",
-    attributes={"tokens": 150, "latency_ms": 450}
-)
-print(f"   Ended span: {span_id}")
+# Chat - state is automatically managed via Redis
+response = agent.chat("Hello! Remember my name is Alice.")
+print(f"Response: {response}")

-# End trace
-redis_db.on_trace_end(
-    trace_id=trace_id,
-    status="ok",
-    metadata={"total_spans": 1}
-)
-print(f"   Ended trace: {trace_id}")
+# Second message to test state
+response2 = agent.chat("What is my name?")
+print(f"Response: {response2}")

-redis_db.close()
+my_db.close()
 print("\n✅ Done")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonaiagents import db
+# redis_db = db.RedisDB(host="localhost", port=6379)
@@ -26,23 +26,18 @@ Expected Output:
    Messages persisted: 2
 """

-from praisonaiagents import Agent
-from praisonai.db import PostgresDB
+from praisonaiagents import Agent, db

-# Create database adapter
-db = PostgresDB(
-    host="localhost",
-    port=5432,
-    database="praisonai",
-    user="postgres",
-    password="praison123"
+# Create database adapter (simplified import)
+db_instance = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai"
 )

 # Create agent with persistence enabled
 agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant. Keep responses brief.",
-    db=db,
+    db=db_instance,
    session_id="demo-session-001",  # Same session_id = resume conversation
    verbose=False
 )
@@ -57,7 +52,7 @@ print(f"Session ID: {agent.session_id}")
 print(f"Messages in history: {len(agent.chat_history)}")

 # Close DB connection
-db.close()
+db_instance.close()

 print("\n=== Session persisted! ===")
 print("Run again with same session_id to resume.")
@@ -1,10 +1,7 @@
 """
-Redis State Store Example for PraisonAI.
+Redis State Store - Agent-First Example

-Demonstrates set/get/delete + TTL operations.
-
-Requirements:
-    pip install "praisonai[tools]"
+Use Redis for state management with an Agent.

 Docker Setup:
    docker run -d --name praison-redis -p 6379:6379 redis:7
@@ -13,55 +10,37 @@ Run:
    python state_redis.py

 Expected Output:
-    === Redis State Store Demo ===
-    Set key: session:user123:preferences
-    Get value: {'theme': 'dark', 'language': 'en'}
-    TTL remaining: 3600 seconds
-    Hash operations: {'name': 'Alice', 'role': 'admin'}
+    Agent responds with state persisted to Redis
 """

-from praisonai.persistence.factory import create_state_store
+from praisonaiagents import Agent, db

-# Create Redis state store
-store = create_state_store("redis", url="redis://localhost:6379")
+print("=== Redis State Store (Agent-First) ===")

-print("=== Redis State Store Demo ===")
+# Agent-first approach: use db parameter with Redis state store
+my_db = db(
+    database_url="sqlite:///conversations.db",  # Conversations
+    state_url="redis://localhost:6379"          # State/tracing
+)

-# Basic set/get
-key = "session:user123:preferences"
-value = {"theme": "dark", "language": "en", "notifications": True}
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    db=my_db,
+    session_id="redis-state-example"
+)

-store.set(key, value)
-print(f"Set key: {key}")
+# Chat - state is automatically managed via Redis
+response = agent.chat("Hello! Remember my favorite color is blue.")
+print(f"Response: {response}")

-retrieved = store.get(key)
-print(f"Get value: {retrieved}")
-
-# Set with TTL (expires in 1 hour)
-ttl_key = "session:user123:token"
-store.set(ttl_key, "abc123xyz", ttl=3600)
-remaining = store.ttl(ttl_key)
-print(f"TTL remaining: {remaining} seconds")
-
-# Hash operations (for structured data)
-hash_key = "user:123:profile"
-store.hset(hash_key, "name", "Alice")
-store.hset(hash_key, "role", "admin")
-store.hset(hash_key, "last_login", "2024-12-24")
-
-profile = store.hgetall(hash_key)
-print(f"Hash operations: {profile}")
-
-# Check existence
-exists = store.exists(key)
-print(f"Key exists: {exists}")
-
-# Delete keys
-store.delete(key)
-store.delete(ttl_key)
-store.delete(hash_key)
-print("Cleaned up test keys")
-
-store.close()
+# Second message to test state
+response2 = agent.chat("What is my favorite color?")
+print(f"Response: {response2}")

+my_db.close()
 print("\n=== Demo Complete ===")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence.factory import create_state_store
+# store = create_state_store("redis", url="redis://localhost:6379")
@@ -15,6 +15,7 @@ Features demonstrated:
 from praisonaiagents import Agent
 import tempfile
 import os
+import shutil

 # Create a sample knowledge document for demonstration
 sample_document = """
@@ -91,38 +92,15 @@ doc_path = os.path.join(temp_dir, "ai_healthcare_guide.txt")
 with open(doc_path, "w") as f:
    f.write(sample_document)

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

 # Clean up temporary files
-import shutil
 shutil.rmtree(temp_dir)

 print("="*80)
@@ -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()
@@ -0,0 +1,128 @@
+"""
+Example: Using pandas as a custom tool with PraisonAI Agent
+
+This example shows how to wrap pandas functions as tools
+that can be used with Agent().
+"""
+
+import pandas as pd
+from io import StringIO
+
+# Define pandas wrapper tools
+def analyze_csv_data(csv_data: str) -> str:
+    """Analyze CSV data using pandas DataFrame.
+    
+    Args:
+        csv_data: CSV-formatted string data
+        
+    Returns:
+        Analysis summary including shape, columns, and statistics
+    """
+    df = pd.read_csv(StringIO(csv_data))
+    summary = f"""DataFrame Analysis:
+- Shape: {df.shape[0]} rows, {df.shape[1]} columns
+- Columns: {list(df.columns)}
+- Data Types: {dict(df.dtypes)}
+- Summary Statistics:
+{df.describe().to_string()}"""
+    return summary
+
+
+def filter_dataframe(csv_data: str, column: str, condition: str, value: str) -> str:
+    """Filter a DataFrame based on a condition.
+    
+    Args:
+        csv_data: CSV-formatted string data
+        column: Column name to filter on
+        condition: Condition type ('equals', 'greater', 'less', 'contains')
+        value: Value to compare against
+        
+    Returns:
+        Filtered data as CSV string
+    """
+    df = pd.read_csv(StringIO(csv_data))
+    
+    if condition == 'equals':
+        filtered = df[df[column] == value]
+    elif condition == 'greater':
+        filtered = df[df[column] > float(value)]
+    elif condition == 'less':
+        filtered = df[df[column] < float(value)]
+    elif condition == 'contains':
+        filtered = df[df[column].str.contains(value, na=False)]
+    else:
+        return f"Unknown condition: {condition}"
+    
+    return filtered.to_csv(index=False)
+
+
+def calculate_statistics(csv_data: str, column: str) -> str:
+    """Calculate statistics for a specific column.
+    
+    Args:
+        csv_data: CSV-formatted string data
+        column: Column name to analyze
+        
+    Returns:
+        Statistics summary for the column
+    """
+    df = pd.read_csv(StringIO(csv_data))
+    
+    if column not in df.columns:
+        return f"Column '{column}' not found. Available: {list(df.columns)}"
+    
+    col = df[column]
+    
+    if pd.api.types.is_numeric_dtype(col):
+        stats = f"""Statistics for '{column}':
+- Count: {col.count()}
+- Mean: {col.mean():.2f}
+- Std: {col.std():.2f}
+- Min: {col.min()}
+- Max: {col.max()}
+- Median: {col.median()}"""
+    else:
+        stats = f"""Statistics for '{column}':
+- Count: {col.count()}
+- Unique: {col.nunique()}
+- Top: {col.mode().iloc[0] if len(col.mode()) > 0 else 'N/A'}
+- Sample values: {list(col.head(3))}"""
+    
+    return stats
+
+
+if __name__ == "__main__":
+    # Test data
+    test_csv = """name,age,salary,department
+Alice,30,50000,Engineering
+Bob,25,45000,Marketing
+Charlie,35,60000,Engineering
+Diana,28,52000,Sales
+Eve,32,55000,Marketing"""
+
+    print("=== Test: analyze_csv_data ===")
+    print(analyze_csv_data(test_csv))
+    print()
+    
+    print("=== Test: filter_dataframe ===")
+    print(filter_dataframe(test_csv, "age", "greater", "28"))
+    print()
+    
+    print("=== Test: calculate_statistics ===")
+    print(calculate_statistics(test_csv, "salary"))
+    print()
+    
+    # Example with Agent (requires praisonaiagents)
+    print("=== Agent Usage Example ===")
+    print("""
+from praisonaiagents import Agent
+
+agent = Agent(
+    name="data_analyst",
+    role="Data Analyst",
+    goal="Analyze data using pandas tools",
+    tools=[analyze_csv_data, filter_dataframe, calculate_statistics]
+)
+
+result = agent.start("Analyze this data and find the average salary")
+""")
@@ -0,0 +1,25 @@
+"""Example: Discover tools from installed packages."""
+
+# Discover from praisonaiagents built-in tools
+try:
+    from praisonaiagents.tools import TOOL_MAPPINGS
+    print("Built-in tools from praisonaiagents:")
+    for name in list(TOOL_MAPPINGS.keys())[:10]:
+        print(f"  - {name}")
+    print(f"  ... and {len(TOOL_MAPPINGS) - 10} more")
+except ImportError:
+    print("praisonaiagents not installed")
+
+# Discover from praisonai_tools
+try:
+    import praisonai_tools
+    print("\nTools from praisonai_tools:")
+    
+    # Check for video module
+    try:
+        from praisonai_tools import video
+        print("  - praisonai_tools.video (video editing)")
+    except ImportError:
+        pass
+except ImportError:
+    print("praisonai_tools not installed")
@@ -0,0 +1,18 @@
+"""Example: Resolve tool names to callable tools."""
+from praisonai.templates.tool_override import (
+    create_tool_registry_with_overrides,
+    resolve_tools,
+)
+
+# Create registry with defaults
+registry = create_tool_registry_with_overrides(include_defaults=True)
+
+print(f"Registry contains {len(registry)} tools")
+
+# Resolve tool names
+tool_names = ["shell_tool", "internet_search"]
+resolved = resolve_tools(tool_names, registry=registry)
+
+print(f"\nResolved {len(resolved)} tools:")
+for tool in resolved:
+    print(f"  - {getattr(tool, '__name__', type(tool).__name__)}")
@@ -0,0 +1,14 @@
+"""Example: Configure tool sources for templates."""
+from praisonai.templates.tool_override import create_tool_registry_with_overrides
+
+# Create registry with tools_sources
+registry = create_tool_registry_with_overrides(
+    tools_sources=["praisonai_tools.video"],
+    include_defaults=True,
+)
+
+print(f"Registry with tools_sources: {len(registry)} tools")
+
+# List some tools
+for name in list(registry.keys())[:10]:
+    print(f"  - {name}")
@@ -1,21 +1,23 @@
-"""ChromaDB Vector Store - Basic Test"""
-import sys
-sys.path.insert(0, 'src/praisonai')
-from praisonai.persistence import create_knowledge_store
-from praisonai.persistence.knowledge.base import KnowledgeDocument
+"""ChromaDB Vector Store - Agent-First Example"""
+from praisonaiagents import Agent

-store = create_knowledge_store("chroma", path="/tmp/chroma_demo")
-try:
-    store.delete_collection("demo")
-except Exception:
-    pass
-store.create_collection("demo", dimension=1536)
-docs = [
-    KnowledgeDocument(id="1", content="Python is a programming language", embedding=[0.1]*1536),
-    KnowledgeDocument(id="2", content="JavaScript runs in browsers", embedding=[0.2]*1536)
-]
-store.insert("demo", docs)
-results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
-print(f"Found: {len(results)} results")
-assert len(results) >= 1
-print("PASSED: ChromaDB vector store")
+# Agent-first approach: use knowledge parameter with ChromaDB
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "chroma",
+        "path": "/tmp/chroma_demo"
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: ChromaDB with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence import create_knowledge_store
+# store = create_knowledge_store("chroma", path="/tmp/chroma_demo")
@@ -0,0 +1,25 @@
+"""LanceDB Vector Store - Agent-First Example"""
+from praisonaiagents import Agent
+
+# Agent-first approach: use knowledge parameter with LanceDB
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "lancedb",
+        "path": "/tmp/lancedb_test"
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: LanceDB with Agent")
+
+# --- Advanced: Direct LanceDB Usage ---
+# import lancedb
+# db = lancedb.connect("/tmp/lancedb_test")
+# data = [{"id": "1", "text": "ML is AI", "vector": [0.1] * 128}]
+# table = db.create_table("demo", data)
@@ -1,20 +1,23 @@
-"""LanceDB Vector Store - Basic Test"""
-import sys
-sys.path.insert(0, 'src/praisonai')
-try:
-    from praisonai.persistence import create_knowledge_store
-    from praisonai.persistence.knowledge.base import KnowledgeDocument
-    
-    store = create_knowledge_store("lancedb", path="/tmp/lancedb_demo")
-    store.create_collection("demo", dimension=1536)
-    docs = [
-        KnowledgeDocument(id="doc1", content="The Eiffel Tower is in Paris", embedding=[0.1]*1536),
-        KnowledgeDocument(id="doc2", content="The Statue of Liberty is in New York", embedding=[0.2]*1536)
-    ]
-    store.insert("demo", docs)
-    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
-    print(f"Found: {len(results)} results")
-    assert len(results) >= 1
-    print("PASSED: LanceDB vector store")
-except ImportError as e:
-    print(f"SKIPPED: LanceDB - {e}")
+"""LanceDB Vector Store - Agent-First Example"""
+from praisonaiagents import Agent
+
+# Agent-first approach: use knowledge parameter with LanceDB
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "lancedb",
+        "path": "/tmp/lancedb_demo"
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: LanceDB with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence import create_knowledge_store
+# store = create_knowledge_store("lancedb", path="/tmp/lancedb_demo")
@@ -0,0 +1,31 @@
+"""PGVector Vector Store - Agent-First Example
+
+Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+"""
+import os
+from praisonaiagents import Agent
+
+url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
+
+# Agent-first approach: use knowledge parameter with PGVector
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "pgvector",
+        "url": url
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: PGVector with Agent")
+
+# --- Advanced: Direct PGVector Usage ---
+# import psycopg2
+# conn = psycopg2.connect(url)
+# cur = conn.cursor()
+# cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
@@ -1,23 +1,29 @@
-"""PGVector Knowledge Store - Basic Test (requires Docker)"""
-import sys
+"""PGVector Knowledge Store - Agent-First Example (requires Docker)
+
+Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+"""
 import os
-sys.path.insert(0, 'src/praisonai')
-from praisonai.persistence import create_knowledge_store
-from praisonai.persistence.knowledge.base import KnowledgeDocument
+from praisonaiagents import Agent

-# Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
 url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
-try:
-    store = create_knowledge_store("pgvector", url=url)
-    store.create_collection("demo", dimension=1536)
-    docs = [
-        KnowledgeDocument(id="1", content="Kubernetes orchestrates containers", embedding=[0.1]*1536),
-        KnowledgeDocument(id="2", content="Docker packages applications", embedding=[0.2]*1536)
-    ]
-    store.insert("demo", docs)
-    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
-    print(f"Found: {len(results)} results")
-    assert len(results) >= 1
-    print("PASSED: PGVector vector store")
-except Exception as e:
-    print(f"SKIPPED: PGVector - {e}")
+
+# Agent-first approach: use knowledge parameter with PGVector
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "pgvector",
+        "url": url
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: PGVector with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence import create_knowledge_store
+# store = create_knowledge_store("pgvector", url=url)
@@ -0,0 +1,34 @@
+"""Pinecone Vector Store - Agent-First Example
+
+Requires: export PINECONE_API_KEY=...
+"""
+import os
+import sys
+from praisonaiagents import Agent
+
+api_key = os.getenv("PINECONE_API_KEY")
+if not api_key:
+    print("SKIPPED: Pinecone - PINECONE_API_KEY not set")
+    sys.exit(0)
+
+# Agent-first approach: use knowledge parameter with Pinecone
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "pinecone",
+        "api_key": api_key,
+        "environment": "us-east-1"
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: Pinecone with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# from pinecone import Pinecone
+# pc = Pinecone(api_key=api_key)
@@ -1,23 +1,29 @@
-"""Qdrant Vector Store - Basic Test (requires Docker)"""
-import sys, os
-sys.path.insert(0, 'src/praisonai')
-from praisonai.persistence import create_knowledge_store
-from praisonai.persistence.knowledge.base import KnowledgeDocument
+"""Qdrant Vector Store - Agent-First Example (requires Docker)

-# Docker: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
+Docker: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
+"""
+import os
+from praisonaiagents import Agent
+
+# Agent-first approach: use knowledge parameter with Qdrant
 url = os.getenv("QDRANT_URL", "http://localhost:6333")
-store = create_knowledge_store("qdrant", url=url)
-try:
-    store.delete_collection("demo")
-except Exception:
-    pass
-store.create_collection("demo", dimension=1536)
-docs = [
-    KnowledgeDocument(id="1", content="Machine learning is AI", embedding=[0.1]*1536),
-    KnowledgeDocument(id="2", content="Deep learning uses neural nets", embedding=[0.2]*1536)
-]
-store.insert("demo", docs)
-results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
-print(f"Found: {len(results)} results")
-assert len(results) >= 1
-print("PASSED: Qdrant vector store")
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "qdrant",
+        "url": url
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: Qdrant with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# from praisonai.persistence import create_knowledge_store
+# store = create_knowledge_store("qdrant", url=url)
@@ -0,0 +1,36 @@
+"""Weaviate Cloud Vector Store - Agent-First Example
+
+Requires: export WEAVIATE_URL=... and WEAVIATE_API_KEY=...
+"""
+import os
+import sys
+from praisonaiagents import Agent
+
+weaviate_url = os.getenv("WEAVIATE_URL", "https://your-cluster.weaviate.cloud")
+weaviate_key = os.getenv("WEAVIATE_API_KEY")
+if not weaviate_key:
+    print("SKIPPED: Weaviate - WEAVIATE_API_KEY not set")
+    sys.exit(0)
+
+# Agent-first approach: use knowledge parameter with Weaviate
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant with access to documents.",
+    knowledge=["./docs/guide.pdf"],  # Add your documents here
+    knowledge_config={
+        "vector_store": "weaviate",
+        "url": weaviate_url,
+        "api_key": weaviate_key
+    }
+)
+
+# Chat - agent uses knowledge for RAG
+response = agent.chat("What information do you have?")
+print(f"Response: {response}")
+
+print("PASSED: Weaviate with Agent")
+
+# --- Advanced: Direct Store Usage ---
+# import weaviate
+# from weaviate.classes.init import Auth
+# client = weaviate.connect_to_weaviate_cloud(cluster_url=weaviate_url, auth_credentials=Auth.api_key(weaviate_key))
@@ -62,6 +62,8 @@ docs/generated/
 *.log
 *.sqlite
 *.db
+# But keep the db module directory
+!praisonaiagents/db/

 # OS generated files
 .DS_Store
@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Import time benchmark for praisonaiagents.
+
+This benchmark measures the import time of the praisonaiagents package
+and verifies that heavy dependencies are not loaded at import time.
+
+Usage:
+    python benchmarks/import_time.py
+    
+CI Gate:
+    - PASS: import time < 200ms
+    - WARN: import time 200-300ms
+    - FAIL: import time > 300ms
+"""
+import sys
+import time
+import statistics
+
+
+def clear_modules():
+    """Clear all praisonai and litellm related modules from cache."""
+    to_remove = [m for m in sys.modules.keys() 
+                 if 'praison' in m or 'litellm' in m]
+    for mod in to_remove:
+        del sys.modules[mod]
+
+
+def measure_import_time(runs: int = 5) -> dict:
+    """
+    Measure import time over multiple runs.
+    
+    Returns:
+        dict with min, max, median, mean times in milliseconds
+    """
+    times = []
+    
+    for _ in range(runs):
+        clear_modules()
+        
+        start = time.perf_counter()
+        import praisonaiagents  # noqa: F401
+        end = time.perf_counter()
+        
+        times.append((end - start) * 1000)
+        
+        # Clean up for next run
+        if 'praisonaiagents' in sys.modules:
+            del sys.modules['praisonaiagents']
+    
+    times.sort()
+    
+    return {
+        'times': times,
+        'min': min(times),
+        'max': max(times),
+        'median': statistics.median(times),
+        'mean': statistics.mean(times),
+        'stdev': statistics.stdev(times) if len(times) > 1 else 0,
+    }
+
+
+def check_lazy_imports() -> dict:
+    """
+    Check that heavy dependencies are NOT loaded after importing praisonaiagents.
+    
+    Returns:
+        dict with module names and whether they are loaded
+    """
+    clear_modules()
+    
+    import praisonaiagents  # noqa: F401
+    
+    heavy_modules = [
+        'litellm',
+        'chromadb', 
+        'mem0',
+        'requests',
+    ]
+    
+    results = {}
+    for mod in heavy_modules:
+        results[mod] = mod in sys.modules
+    
+    return results
+
+
+def main():
+    """Run the benchmark and print results."""
+    print("=" * 60)
+    print("PraisonAI Agents Import Time Benchmark")
+    print("=" * 60)
+    
+    # Measure import time
+    print("\n[1/2] Measuring import time (5 runs)...")
+    results = measure_import_time(runs=5)
+    
+    print(f"\nImport times (ms): {[round(t, 1) for t in results['times']]}")
+    print(f"  Min:    {results['min']:.1f} ms")
+    print(f"  Max:    {results['max']:.1f} ms")
+    print(f"  Median: {results['median']:.1f} ms")
+    print(f"  Mean:   {results['mean']:.1f} ms")
+    print(f"  StdDev: {results['stdev']:.1f} ms")
+    
+    # Check lazy imports
+    print("\n[2/2] Checking lazy imports...")
+    lazy_results = check_lazy_imports()
+    
+    print("\nHeavy modules loaded at import time:")
+    all_lazy = True
+    for mod, loaded in lazy_results.items():
+        status = "LOADED (BAD)" if loaded else "NOT LOADED (GOOD)"
+        print(f"  {mod}: {status}")
+        if loaded:
+            all_lazy = False
+    
+    # Determine pass/fail
+    print("\n" + "=" * 60)
+    print("RESULTS")
+    print("=" * 60)
+    
+    median_time = results['median']
+    
+    if median_time < 200:
+        time_status = "PASS"
+        time_msg = f"Import time {median_time:.0f}ms < 200ms target"
+    elif median_time < 300:
+        time_status = "WARN"
+        time_msg = f"Import time {median_time:.0f}ms between 200-300ms"
+    else:
+        time_status = "FAIL"
+        time_msg = f"Import time {median_time:.0f}ms > 300ms limit"
+    
+    lazy_status = "PASS" if all_lazy else "FAIL"
+    lazy_msg = "All heavy deps lazy loaded" if all_lazy else "Some heavy deps loaded eagerly"
+    
+    print(f"\nImport Time: [{time_status}] {time_msg}")
+    print(f"Lazy Imports: [{lazy_status}] {lazy_msg}")
+    
+    overall = "PASS" if time_status != "FAIL" and lazy_status == "PASS" else "FAIL"
+    print(f"\nOverall: [{overall}]")
+    
+    # Exit code for CI
+    return 0 if overall == "PASS" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+Memory usage benchmark for praisonaiagents.
+
+This benchmark measures the memory footprint of importing praisonaiagents
+and verifies it stays within acceptable limits.
+
+Usage:
+    python benchmarks/memory_usage.py
+    
+CI Gate:
+    - PASS: memory < 30MB
+    - WARN: memory 30-45MB
+    - FAIL: memory > 45MB
+"""
+import sys
+import tracemalloc
+
+
+def clear_modules():
+    """Clear all praisonai and litellm related modules from cache."""
+    to_remove = [m for m in sys.modules.keys() 
+                 if 'praison' in m or 'litellm' in m]
+    for mod in to_remove:
+        del sys.modules[mod]
+
+
+def measure_memory() -> dict:
+    """
+    Measure memory usage after importing praisonaiagents.
+    
+    Returns:
+        dict with current and peak memory in MB
+    """
+    clear_modules()
+    
+    tracemalloc.start()
+    
+    import praisonaiagents  # noqa: F401
+    
+    current, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    
+    return {
+        'current_bytes': current,
+        'peak_bytes': peak,
+        'current_mb': current / 1024 / 1024,
+        'peak_mb': peak / 1024 / 1024,
+    }
+
+
+def main():
+    """Run the benchmark and print results."""
+    print("=" * 60)
+    print("PraisonAI Agents Memory Usage Benchmark")
+    print("=" * 60)
+    
+    print("\nMeasuring memory usage...")
+    results = measure_memory()
+    
+    print(f"\nMemory Usage:")
+    print(f"  Current: {results['current_mb']:.1f} MB")
+    print(f"  Peak:    {results['peak_mb']:.1f} MB")
+    
+    # Determine pass/fail based on peak memory
+    peak_mb = results['peak_mb']
+    
+    print("\n" + "=" * 60)
+    print("RESULTS")
+    print("=" * 60)
+    
+    if peak_mb < 30:
+        status = "PASS"
+        msg = f"Memory {peak_mb:.1f}MB < 30MB target"
+    elif peak_mb < 45:
+        status = "WARN"
+        msg = f"Memory {peak_mb:.1f}MB between 30-45MB"
+    else:
+        status = "FAIL"
+        msg = f"Memory {peak_mb:.1f}MB > 45MB limit"
+    
+    print(f"\nMemory: [{status}] {msg}")
+    
+    # Exit code for CI
+    return 0 if status != "FAIL" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Example: Using PraisonAI Agents Lite Package
+
+The lite package provides a minimal agent framework without heavy dependencies
+like litellm. It's ideal for users who want to bring their own LLM client.
+
+This example shows:
+1. Creating a LiteAgent with a custom LLM function
+2. Using the built-in OpenAI adapter
+3. Thread-safe chat history management
+"""
+import os
+
+
+def example_custom_llm():
+    """Example 1: Using a custom LLM function."""
+    from praisonaiagents.lite import LiteAgent
+    
+    # Define your own LLM function
+    def my_simple_llm(messages):
+        """A mock LLM that echoes back the last message."""
+        last_msg = messages[-1]["content"] if messages else "No message"
+        return f"Echo: {last_msg}"
+    
+    agent = LiteAgent(
+        name="EchoAgent",
+        llm_fn=my_simple_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 2: Using the built-in OpenAI adapter."""
+    from praisonaiagents.lite import LiteAgent, create_openai_llm_fn
+    
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Skipping OpenAI example - OPENAI_API_KEY not set")
+        return
+    
+    # Create LLM function using OpenAI SDK directly (no litellm)
+    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"OpenAI Response: {response}")
+
+
+def example_with_tools():
+    """Example 3: Using tools with LiteAgent."""
+    from praisonaiagents.lite import LiteAgent, tool
+    
+    @tool
+    def add_numbers(a: int, b: int) -> int:
+        """Add two numbers together."""
+        return a + b
+    
+    def mock_llm(messages):
+        return "The sum is 8"
+    
+    agent = LiteAgent(
+        name="MathAgent",
+        llm_fn=mock_llm,
+        tools=[add_numbers]
+    )
+    
+    # Execute tool directly
+    result = agent.execute_tool("add_numbers", a=5, b=3)
+    print(f"Tool result: {result.output}")
+    print(f"Tool success: {result.success}")
+
+
+def example_anthropic_adapter():
+    """Example 4: Using the built-in Anthropic adapter."""
+    from praisonaiagents.lite import LiteAgent, create_anthropic_llm_fn
+    
+    # Check for API key
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        print("Skipping Anthropic example - ANTHROPIC_API_KEY not set")
+        return
+    
+    # Create LLM function using Anthropic SDK directly
+    llm_fn = create_anthropic_llm_fn(model="claude-3-5-sonnet-20241022")
+    
+    agent = LiteAgent(
+        name="ClaudeAgent",
+        llm_fn=llm_fn,
+        instructions="You are a helpful assistant. Keep responses brief."
+    )
+    
+    response = agent.chat("What is the capital of France?")
+    print(f"Claude Response: {response}")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("PraisonAI Agents Lite Examples")
+    print("=" * 60)
+    
+    print("\n[1] Custom LLM Function:")
+    example_custom_llm()
+    
+    print("\n[2] OpenAI Adapter:")
+    example_openai_adapter()
+    
+    print("\n[3] Tools with LiteAgent:")
+    example_with_tools()
+    
+    print("\n[4] Anthropic Adapter:")
+    example_anthropic_adapter()
+    
+    print("\n" + "=" * 60)
+    print("Examples completed!")
@@ -1,5 +1,8 @@
 """
 Praison AI Agents - A package for hierarchical AI agent task execution
+
+This module uses lazy loading to minimize import time and memory usage.
+Heavy dependencies like litellm are only loaded when actually needed.
 """

 # Apply warning patch BEFORE any imports to intercept warnings at the source
@@ -11,52 +14,18 @@ from . import _logging
 # Configure root logger after logging is initialized
 _logging.configure_root_logger()

-# Now import everything else
-from .agent.agent import Agent
-from .agent.image_agent import ImageAgent
-from .agent.context_agent import ContextAgent, create_context_agent
-from .agent.deep_research_agent import (
-    DeepResearchAgent,
-    DeepResearchResponse,
-    Citation,
-    ReasoningStep,
-    WebSearchCall,
-    CodeExecutionStep,
-    MCPCall,
-    FileSearchCall,
-    Provider
-)
-from .agent.query_rewriter_agent import (
-    QueryRewriterAgent,
-    RewriteStrategy,
-    RewriteResult
-)
-from .agent.prompt_expander_agent import (
-    PromptExpanderAgent,
-    ExpandStrategy,
-    ExpandResult
-)
-from .agents.agents import PraisonAIAgents
-from .task.task import Task
+# Import configuration (lightweight, no heavy deps)
+from . import _config
+
+# Lightweight imports that don't trigger heavy dependency chains
 from .tools.tools import Tools
 from .tools.base import BaseTool, ToolResult, ToolValidationError, validate_tool
 from .tools.decorator import tool, FunctionTool
 from .tools.registry import get_registry, register_tool, get_tool, ToolRegistry
-from .agents.autoagents import AutoAgents
-from .knowledge.knowledge import Knowledge
-from .knowledge.chunking import Chunking
-# MCP support (optional)
-try:
-    from .mcp.mcp import MCP
-    _mcp_available = True
-except ImportError:
-    _mcp_available = False
-    MCP = None
-from .session import Session
-from .memory.memory import Memory
 from .db import db
 from .obs import obs
-# Workflows - import from dedicated workflows module
+
+# Workflows - lightweight module
 from .workflows import (
    Workflow, WorkflowStep, WorkflowContext, StepResult,
    Route, Parallel, Loop, Repeat,
@@ -65,68 +34,18 @@ from .workflows import (
 )
 from .guardrails import GuardrailResult, LLMGuardrail

-# Fast Context support (lazy loaded to avoid performance impact)
-def __getattr__(name):
-    """Lazy load FastContext to avoid impacting package load time."""
-    if name == "FastContext":
-        from praisonaiagents.context.fast import FastContext
-        return FastContext
-    elif name == "FastContextResult":
-        from praisonaiagents.context.fast import FastContextResult
-        return FastContextResult
-    elif name == "FileMatch":
-        from praisonaiagents.context.fast import FileMatch
-        return FileMatch
-    elif name == "LineRange":
-        from praisonaiagents.context.fast import LineRange
-        return LineRange
-    # Agent Skills support (lazy loaded for zero performance impact)
-    elif name == "SkillManager":
-        from praisonaiagents.skills import SkillManager
-        return SkillManager
-    elif name == "SkillProperties":
-        from praisonaiagents.skills import SkillProperties
-        return SkillProperties
-    elif name == "SkillMetadata":
-        from praisonaiagents.skills import SkillMetadata
-        return SkillMetadata
-    elif name == "SkillLoader":
-        from praisonaiagents.skills import SkillLoader
-        return SkillLoader
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-# Planning mode support
-try:
-    from .planning import (
-        Plan,
-        PlanStep,
-        TodoList,
-        TodoItem,
-        PlanStorage,
-        PlanningAgent,
-        ApprovalCallback,
-        READ_ONLY_TOOLS,
-        RESTRICTED_TOOLS,
-    )
-    _planning_available = True
-except ImportError:
-    _planning_available = False
-    Plan = None
-    PlanStep = None
-    TodoList = None
-    TodoItem = None
-    PlanStorage = None
-    PlanningAgent = None
-    ApprovalCallback = None
-    READ_ONLY_TOOLS = []
-    RESTRICTED_TOOLS = []
+# Handoff - lightweight
 from .agent.handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
-# Flow display
+
+# Flow display (optional)
 try:
    from .flow_display import FlowDisplay, track_workflow
 except ImportError:
    FlowDisplay = None
    track_workflow = None
+
+# Main display utilities - these are used frequently so import directly
+# but they don't pull in litellm
 from .main import (
    TaskOutput,
    ReflectionOutput,
@@ -143,98 +62,296 @@ from .main import (
    async_display_callbacks,
 )

-# Telemetry support (lazy loaded)
-try:
-    from .telemetry import (
-        get_telemetry,
-        enable_telemetry,
-        disable_telemetry,
-        enable_performance_mode,
-        disable_performance_mode,
-        cleanup_telemetry_resources,
-        MinimalTelemetry,
-        TelemetryCollector
-    )
-    _telemetry_available = True
-except ImportError:
-    # Telemetry not available - provide stub functions
-    _telemetry_available = False
-    def get_telemetry():
-        return None
-    
-    def enable_telemetry(*args, **kwargs):
-        import logging
-        logging.warning(
-            "Telemetry not available. Install with: pip install praisonaiagents[telemetry]"
-        )
-        return None
-    
-    def disable_telemetry():
-        pass
-    
-    def enable_performance_mode():
-        pass
-    
-    def disable_performance_mode():
-        pass
-    
-    def cleanup_telemetry_resources():
-        pass
-    
-    MinimalTelemetry = None
-    TelemetryCollector = None
+# Module-level caches for lazy-loaded classes
+_lazy_cache = {}

-# Add Agents as an alias for PraisonAIAgents
-Agents = PraisonAIAgents
+# Flags for optional modules
+_mcp_available = None
+_planning_available = None
+_telemetry_available = None
+_agui_available = None
+_a2a_available = None

-# Enable PostHog telemetry by default with actual event posting  
-# PostHog events are posted by default unless explicitly disabled
-# Users can:
-#   - Disable completely: PRAISONAI_DISABLE_TELEMETRY=true (or DO_NOT_TRACK=true)
-#   - Enable performance mode: PRAISONAI_PERFORMANCE_MODE=true (minimal overhead, limited events)
-#   - Enable full telemetry: PRAISONAI_FULL_TELEMETRY=true (detailed tracking)
-#   - Legacy opt-in mode: PRAISONAI_AUTO_INSTRUMENT=true
-if _telemetry_available:
+
+def __getattr__(name):
+    """
+    Lazy load heavy modules to avoid impacting package load time.
+    
+    This function is called when an attribute is not found in the module.
+    It enables deferred loading of heavy dependencies like litellm.
+    """
+    global _mcp_available, _planning_available, _telemetry_available
+    global _agui_available, _a2a_available
+    
+    # Return cached values if available
+    if name in _lazy_cache:
+        return _lazy_cache[name]
+    
+    # Agent and related classes (triggers litellm import chain)
+    if name == "Agent":
+        from .agent.agent import Agent
+        _lazy_cache[name] = Agent
+        return Agent
+    elif name == "ImageAgent":
+        from .agent.image_agent import ImageAgent
+        _lazy_cache[name] = ImageAgent
+        return ImageAgent
+    elif name == "ContextAgent":
+        from .agent.context_agent import ContextAgent
+        _lazy_cache[name] = ContextAgent
+        return ContextAgent
+    elif name == "create_context_agent":
+        from .agent.context_agent import create_context_agent
+        _lazy_cache[name] = create_context_agent
+        return create_context_agent
+    elif name == "DeepResearchAgent":
+        from .agent.deep_research_agent import DeepResearchAgent
+        _lazy_cache[name] = DeepResearchAgent
+        return DeepResearchAgent
+    elif name == "DeepResearchResponse":
+        from .agent.deep_research_agent import DeepResearchResponse
+        _lazy_cache[name] = DeepResearchResponse
+        return DeepResearchResponse
+    elif name == "Citation":
+        from .agent.deep_research_agent import Citation
+        _lazy_cache[name] = Citation
+        return Citation
+    elif name == "ReasoningStep":
+        from .agent.deep_research_agent import ReasoningStep
+        _lazy_cache[name] = ReasoningStep
+        return ReasoningStep
+    elif name == "WebSearchCall":
+        from .agent.deep_research_agent import WebSearchCall
+        _lazy_cache[name] = WebSearchCall
+        return WebSearchCall
+    elif name == "CodeExecutionStep":
+        from .agent.deep_research_agent import CodeExecutionStep
+        _lazy_cache[name] = CodeExecutionStep
+        return CodeExecutionStep
+    elif name == "MCPCall":
+        from .agent.deep_research_agent import MCPCall
+        _lazy_cache[name] = MCPCall
+        return MCPCall
+    elif name == "FileSearchCall":
+        from .agent.deep_research_agent import FileSearchCall
+        _lazy_cache[name] = FileSearchCall
+        return FileSearchCall
+    elif name == "Provider":
+        from .agent.deep_research_agent import Provider
+        _lazy_cache[name] = Provider
+        return Provider
+    elif name == "QueryRewriterAgent":
+        from .agent.query_rewriter_agent import QueryRewriterAgent
+        _lazy_cache[name] = QueryRewriterAgent
+        return QueryRewriterAgent
+    elif name == "RewriteStrategy":
+        from .agent.query_rewriter_agent import RewriteStrategy
+        _lazy_cache[name] = RewriteStrategy
+        return RewriteStrategy
+    elif name == "RewriteResult":
+        from .agent.query_rewriter_agent import RewriteResult
+        _lazy_cache[name] = RewriteResult
+        return RewriteResult
+    elif name == "PromptExpanderAgent":
+        from .agent.prompt_expander_agent import PromptExpanderAgent
+        _lazy_cache[name] = PromptExpanderAgent
+        return PromptExpanderAgent
+    elif name == "ExpandStrategy":
+        from .agent.prompt_expander_agent import ExpandStrategy
+        _lazy_cache[name] = ExpandStrategy
+        return ExpandStrategy
+    elif name == "ExpandResult":
+        from .agent.prompt_expander_agent import ExpandResult
+        _lazy_cache[name] = ExpandResult
+        return ExpandResult
+    
+    # PraisonAIAgents and Agents alias
+    elif name == "PraisonAIAgents":
+        from .agents.agents import PraisonAIAgents
+        _lazy_cache[name] = PraisonAIAgents
+        _lazy_cache["Agents"] = PraisonAIAgents  # Also cache alias
+        return PraisonAIAgents
+    elif name == "Agents":
+        from .agents.agents import PraisonAIAgents
+        _lazy_cache["PraisonAIAgents"] = PraisonAIAgents
+        _lazy_cache[name] = PraisonAIAgents
+        return PraisonAIAgents
+    
+    # Task
+    elif name == "Task":
+        from .task.task import Task
+        _lazy_cache[name] = Task
+        return Task
+    
+    # AutoAgents
+    elif name == "AutoAgents":
+        from .agents.autoagents import AutoAgents
+        _lazy_cache[name] = AutoAgents
+        return AutoAgents
+    
+    # Session (imports requests)
+    elif name == "Session":
+        from .session import Session
+        _lazy_cache[name] = Session
+        return Session
+    
+    # MCP support (optional)
+    elif name == "MCP":
+        if _mcp_available is None:
+            try:
+                from .mcp.mcp import MCP as _MCP
+                _lazy_cache[name] = _MCP
+                return _MCP
+            except ImportError:
+                return None
+        return _lazy_cache.get(name)
+    
+    # Knowledge module (imports chromadb, mem0)
+    elif name == "Knowledge":
+        from praisonaiagents.knowledge.knowledge import Knowledge
+        _lazy_cache[name] = Knowledge
+        return Knowledge
+    elif name == "Chunking":
+        from praisonaiagents.knowledge.chunking import Chunking
+        _lazy_cache[name] = Chunking
+        return Chunking
+    
+    # FastContext support
+    elif name == "FastContext":
+        from praisonaiagents.context.fast import FastContext
+        _lazy_cache[name] = FastContext
+        return FastContext
+    elif name == "FastContextResult":
+        from praisonaiagents.context.fast import FastContextResult
+        _lazy_cache[name] = FastContextResult
+        return FastContextResult
+    elif name == "FileMatch":
+        from praisonaiagents.context.fast import FileMatch
+        _lazy_cache[name] = FileMatch
+        return FileMatch
+    elif name == "LineRange":
+        from praisonaiagents.context.fast import LineRange
+        _lazy_cache[name] = LineRange
+        return LineRange
+    
+    # Agent Skills support (lazy loaded for zero performance impact)
+    elif name == "SkillManager":
+        from praisonaiagents.skills import SkillManager
+        _lazy_cache[name] = SkillManager
+        return SkillManager
+    elif name == "SkillProperties":
+        from praisonaiagents.skills import SkillProperties
+        _lazy_cache[name] = SkillProperties
+        return SkillProperties
+    elif name == "SkillMetadata":
+        from praisonaiagents.skills import SkillMetadata
+        _lazy_cache[name] = SkillMetadata
+        return SkillMetadata
+    elif name == "SkillLoader":
+        from praisonaiagents.skills import SkillLoader
+        _lazy_cache[name] = SkillLoader
+        return SkillLoader
+    
+    # Memory module (imports chromadb)
+    elif name == "Memory":
+        from praisonaiagents.memory.memory import Memory
+        _lazy_cache[name] = Memory
+        return Memory
+    
+    # Planning mode support (lazy)
+    elif name in ("Plan", "PlanStep", "TodoList", "TodoItem", "PlanStorage", 
+                  "PlanningAgent", "ApprovalCallback", "READ_ONLY_TOOLS", 
+                  "RESTRICTED_TOOLS"):
+        try:
+            from . import planning as _planning
+            result = getattr(_planning, name)
+            _lazy_cache[name] = result
+            return result
+        except ImportError:
+            if name in ("READ_ONLY_TOOLS", "RESTRICTED_TOOLS"):
+                return []
+            return None
+    
+    # Telemetry support (lazy loaded)
+    elif name in ("get_telemetry", "enable_telemetry", "disable_telemetry",
+                  "enable_performance_mode", "disable_performance_mode",
+                  "cleanup_telemetry_resources", "MinimalTelemetry", "TelemetryCollector"):
+        try:
+            from . import telemetry as _telemetry
+            result = getattr(_telemetry, name)
+            _lazy_cache[name] = result
+            return result
+        except ImportError:
+            # Provide stub functions
+            if name == "get_telemetry":
+                return lambda: None
+            elif name == "enable_telemetry":
+                import logging
+                def _stub(*args, **kwargs):
+                    logging.warning(
+                        "Telemetry not available. Install with: pip install praisonaiagents[telemetry]"
+                    )
+                    return None
+                return _stub
+            elif name in ("disable_telemetry", "enable_performance_mode", 
+                         "disable_performance_mode", "cleanup_telemetry_resources"):
+                return lambda: None
+            return None
+    
+    # AG-UI support (optional, lazy loaded)
+    elif name == "AGUI":
+        try:
+            from praisonaiagents.ui.agui import AGUI
+            _lazy_cache[name] = AGUI
+            return AGUI
+        except ImportError:
+            return None
+    
+    # A2A support (optional, lazy loaded)
+    elif name == "A2A":
+        try:
+            from praisonaiagents.ui.a2a import A2A
+            _lazy_cache[name] = A2A
+            return A2A
+        except ImportError:
+            return None
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# Initialize telemetry only if explicitly enabled via config
+def _init_telemetry():
+    """Initialize telemetry if enabled via environment variable."""
+    if not _config.TELEMETRY_ENABLED:
+        return
+    
    try:
-        import os
+        from .telemetry import get_telemetry
+        from .telemetry.integration import auto_instrument_all
        
-        # Check for explicit disable (respects DO_NOT_TRACK and other disable flags)
-        telemetry_disabled = any([
-            os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
-            os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
-            os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
-        ])
-        
-        # Check for performance mode (minimal overhead with limited events)
-        performance_mode = os.environ.get('PRAISONAI_PERFORMANCE_MODE', '').lower() in ('true', '1', 'yes')
-        
-        # Check for full telemetry mode (more detailed tracking)
-        full_telemetry = os.environ.get('PRAISONAI_FULL_TELEMETRY', '').lower() in ('true', '1', 'yes')
-        
-        # Legacy explicit auto-instrument option
-        explicit_auto_instrument = os.environ.get('PRAISONAI_AUTO_INSTRUMENT', '').lower() in ('true', '1', 'yes')
-        
-        # Enable PostHog by default unless explicitly disabled
-        if not telemetry_disabled:
-            _telemetry = get_telemetry()
-            if _telemetry and _telemetry.enabled:
-                from .telemetry.integration import auto_instrument_all
-                
-                # Default: PostHog telemetry is enabled and events are posted
-                # Performance mode can be explicitly enabled for minimal overhead
-                use_performance_mode = performance_mode and not (full_telemetry or explicit_auto_instrument)
-                auto_instrument_all(_telemetry, performance_mode=use_performance_mode)
-                
-                # Track package import for basic usage analytics
-                try:
-                    _telemetry.track_feature_usage("package_import")
-                except Exception:
-                    pass
+        _telemetry = get_telemetry()
+        if _telemetry and _telemetry.enabled:
+            use_performance_mode = _config.PERFORMANCE_MODE and not (
+                _config.FULL_TELEMETRY or _config.AUTO_INSTRUMENT
+            )
+            auto_instrument_all(_telemetry, performance_mode=use_performance_mode)
+            
+            # Track package import for basic usage analytics
+            try:
+                _telemetry.track_feature_usage("package_import")
+            except Exception:
+                pass
    except Exception:
        # Silently fail if there are any issues - never break user applications
        pass

+
+# Only initialize telemetry if explicitly enabled
+_init_telemetry()
+
+
 __all__ = [
+    # Core classes (lazy loaded)
    'Agent',
    'ImageAgent',
    'ContextAgent',
@@ -303,11 +420,8 @@ __all__ = [
    'RewriteResult',
    'PromptExpanderAgent',
    'ExpandStrategy',
-    'ExpandResult'
-]
-
-# Add workflow exports
-__all__.extend([
+    'ExpandResult',
+    # Workflows
    'Workflow',
    'WorkflowStep', 
    'WorkflowContext',
@@ -320,48 +434,33 @@ __all__.extend([
    'parallel',
    'loop',
    'repeat',
-    'Pipeline'
-])
-
-# Add MCP to __all__ if available
-if _mcp_available:
-    __all__.append('MCP')
-    
-# Add flow display if available
-if FlowDisplay is not None:
-    __all__.extend(['FlowDisplay', 'track_workflow'])
-
-# Add FastContext exports (lazy loaded)
-__all__.extend([
+    'Pipeline',
+    # MCP
+    'MCP',
+    # Flow display
+    'FlowDisplay',
+    'track_workflow',
+    # FastContext
    'FastContext',
    'FastContextResult',
    'FileMatch',
-    'LineRange'
-])
-
-# Add Agent Skills exports (lazy loaded)
-__all__.extend([
+    'LineRange',
+    # Agent Skills
    'SkillManager',
    'SkillProperties',
    'SkillMetadata',
-    'SkillLoader'
-])
-
-# AG-UI support (optional, lazy loaded)
-try:
-    from praisonaiagents.ui.agui import AGUI
-    __all__.append('AGUI')
-    _agui_available = True
-except ImportError:
-    _agui_available = False
-    AGUI = None
-
-# A2A support (optional, lazy loaded)
-try:
-    from praisonaiagents.ui.a2a import A2A
-    __all__.append('A2A')
-    _a2a_available = True
-except ImportError:
-    _a2a_available = False
-    A2A = None
-
+    'SkillLoader',
+    # Planning
+    'Plan',
+    'PlanStep',
+    'TodoList',
+    'TodoItem',
+    'PlanStorage',
+    'PlanningAgent',
+    'ApprovalCallback',
+    'READ_ONLY_TOOLS',
+    'RESTRICTED_TOOLS',
+    # UI
+    'AGUI',
+    'A2A',
+]
@@ -0,0 +1,106 @@
+"""
+Configuration module for PraisonAI Agents.
+
+Provides feature flags and configuration options that can be controlled
+via environment variables for performance tuning and behavior control.
+
+Environment Variables:
+    PRAISONAI_LAZY_IMPORTS: Enable lazy imports (default: true)
+    PRAISONAI_TELEMETRY_ENABLED: Enable telemetry (default: false, opt-in)
+    PRAISONAI_TELEMETRY_DISABLED: Disable telemetry (takes precedence)
+    DO_NOT_TRACK: Standard opt-out flag (takes precedence)
+"""
+import os
+from typing import Optional
+
+
+def _str_to_bool(value: Optional[str], default: bool = False) -> bool:
+    """Convert string environment variable to boolean."""
+    if value is None:
+        return default
+    return value.lower() in ('true', '1', 'yes', 'on')
+
+
+# Feature Flags
+# -------------
+
+# Lazy imports: When True (default), heavy dependencies like litellm are
+# only imported when actually needed, reducing import time significantly.
+LAZY_IMPORTS = _str_to_bool(
+    os.environ.get('PRAISONAI_LAZY_IMPORTS'), 
+    default=True
+)
+
+# Telemetry: Opt-in by default (False). Users must explicitly enable.
+# Precedence (highest to lowest):
+#   1. DO_NOT_TRACK=true -> disabled
+#   2. PRAISONAI_TELEMETRY_DISABLED=true -> disabled  
+#   3. PRAISONAI_DISABLE_TELEMETRY=true -> disabled
+#   4. PRAISONAI_TELEMETRY_ENABLED=true -> enabled
+#   5. Default: disabled (opt-in model)
+def _get_telemetry_enabled() -> bool:
+    """Determine if telemetry should be enabled based on env vars."""
+    # Check disable flags first (highest precedence)
+    if _str_to_bool(os.environ.get('DO_NOT_TRACK')):
+        return False
+    if _str_to_bool(os.environ.get('PRAISONAI_TELEMETRY_DISABLED')):
+        return False
+    if _str_to_bool(os.environ.get('PRAISONAI_DISABLE_TELEMETRY')):
+        return False
+    
+    # Check explicit enable flag
+    if _str_to_bool(os.environ.get('PRAISONAI_TELEMETRY_ENABLED')):
+        return True
+    
+    # Default: disabled (opt-in model)
+    return False
+
+
+TELEMETRY_ENABLED = _get_telemetry_enabled()
+
+# Performance mode: Minimal telemetry overhead when enabled
+PERFORMANCE_MODE = _str_to_bool(
+    os.environ.get('PRAISONAI_PERFORMANCE_MODE'),
+    default=False
+)
+
+# Full telemetry mode: Detailed tracking when enabled
+FULL_TELEMETRY = _str_to_bool(
+    os.environ.get('PRAISONAI_FULL_TELEMETRY'),
+    default=False
+)
+
+# Legacy auto-instrument flag
+AUTO_INSTRUMENT = _str_to_bool(
+    os.environ.get('PRAISONAI_AUTO_INSTRUMENT'),
+    default=False
+)
+
+
+def missing_dependency_error(
+    package_name: str,
+    extra_name: Optional[str] = None,
+    feature_name: Optional[str] = None
+) -> ImportError:
+    """
+    Create a standardized ImportError for missing optional dependencies.
+    
+    Args:
+        package_name: The name of the missing package (e.g., 'litellm')
+        extra_name: The pip extra to install (e.g., 'llm' for [llm])
+        feature_name: Human-readable feature name (e.g., 'LLM support')
+    
+    Returns:
+        ImportError with helpful install instructions
+    """
+    if extra_name:
+        install_cmd = f"pip install 'praisonaiagents[{extra_name}]'"
+    else:
+        install_cmd = f"pip install {package_name}"
+    
+    feature_desc = f" for {feature_name}" if feature_name else ""
+    
+    return ImportError(
+        f"{package_name} is required{feature_desc} but not installed. "
+        f"Please install with: {install_cmd}"
+    )
@@ -84,8 +84,18 @@ def _configure_loggers():
 # ========================================================================
 # LITELLM CONFIGURATION
 # ========================================================================
-def _configure_litellm():
-    """Configure litellm after it's imported."""
+_litellm_configured = False
+
+def configure_litellm():
+    """Configure litellm after it's imported.
+    
+    This function should be called lazily when litellm is actually used,
+    not at module import time, to avoid importing litellm unnecessarily.
+    """
+    global _litellm_configured
+    if _litellm_configured:
+        return
+    
    try:
        import litellm
        litellm.telemetry = False
@@ -97,11 +107,17 @@ def _configure_litellm():
        
        if hasattr(litellm, 'set_verbose'):
            litellm.set_verbose = False
+        
+        _litellm_configured = True
            
    except (ImportError, AttributeError):
        pass


+# Alias for backward compatibility
+_configure_litellm = configure_litellm
+
+
 # ========================================================================
 # ROOT LOGGER CONFIGURATION
 # ========================================================================
@@ -124,11 +140,16 @@ def configure_root_logger():
 # INITIALIZATION
 # ========================================================================
 def initialize_logging():
-    """Initialize all logging configuration."""
+    """Initialize all logging configuration.
+    
+    Note: litellm configuration is NOT done here to avoid importing litellm
+    at package import time. Call configure_litellm() when litellm is needed.
+    """
    _configure_environment()
    _configure_loggers()
-    _configure_litellm()
+    # NOTE: _configure_litellm() is NOT called here to avoid importing litellm
+    # It will be called lazily when LLM class is instantiated


-# Auto-initialize on import
+# Auto-initialize on import (but NOT litellm)
 initialize_logging()
@@ -4,6 +4,7 @@ import json
 import copy
 import logging
 import asyncio
+import threading
 from typing import List, Optional, Any, Dict, Union, Literal, TYPE_CHECKING, Callable, Tuple, Generator
 from rich.console import Console
 from rich.live import Live
@@ -61,6 +62,57 @@ class Agent:
            logging.getLogger("httpx").setLevel(logging.WARNING)
            logging.getLogger("httpcore").setLevel(logging.WARNING)
    
+    @classmethod
+    def from_template(
+        cls,
+        uri: str,
+        config: Optional[Dict[str, Any]] = None,
+        offline: bool = False,
+        **kwargs
+    ) -> 'Agent':
+        """
+        Create an Agent from a template.
+        
+        Args:
+            uri: Template URI (local path, package ref, or github ref)
+                Examples:
+                - "./my-template" (local path)
+                - "transcript-generator" (default recipes repo)
+                - "github:owner/repo/[email protected]" (GitHub with version)
+                - "package:agent_recipes/transcript-generator" (installed package)
+            config: Optional configuration overrides
+            offline: If True, only use cached templates (no network)
+            **kwargs: Additional Agent constructor arguments
+            
+        Returns:
+            Configured Agent instance
+            
+        Example:
+            ```python
+            from praisonaiagents import Agent
+            
+            # From default recipes repo
+            agent = Agent.from_template("transcript-generator")
+            result = agent.chat("Transcribe ./audio.mp3")
+            
+            # With config overrides
+            agent = Agent.from_template(
+                "data-transformer",
+                config={"output_format": "json"},
+                verbose=True
+            )
+            ```
+        """
+        try:
+            # Lazy import to avoid circular dependencies and keep core SDK lean
+            from praisonai.templates.loader import create_agent_from_template
+            return create_agent_from_template(uri, config=config, offline=offline, **kwargs)
+        except ImportError:
+            raise ImportError(
+                "Template support requires the 'praisonai' package. "
+                "Install with: pip install praisonai"
+            )
+    
    def _generate_tool_definition(self, function_name):
        """
        Generate a tool definition from a function name by inspecting the function.
@@ -254,7 +306,10 @@ class Agent:
        skills: Optional[List[str]] = None,
        skills_dirs: Optional[List[str]] = None,
        db: Optional[Any] = None,
-        session_id: Optional[str] = None
+        session_id: Optional[str] = None,
+        hooks: Optional[List[Any]] = None,
+        llm_config: Optional[Dict[str, Any]] = None,
+        rate_limiter: Optional[Any] = None
    ):
        """Initialize an Agent instance.

@@ -395,6 +450,17 @@ class Agent:
        # Flag to track if final result has been displayed to prevent duplicates
        self._final_display_shown = False
        
+        # Store hooks for middleware system (zero overhead when empty)
+        self._hooks = hooks or []
+        self._middleware_manager = None  # Lazy init
+        
+        # Store llm_config for configurable model switching
+        self._llm_config = llm_config or {}
+        self._llm_configurable = self._llm_config.get('configurable', False)
+        
+        # Store rate limiter (optional, zero overhead when None)
+        self._rate_limiter = rate_limiter
+        
        # Store OpenAI client parameters for lazy initialization
        self._openai_api_key = api_key
        self._openai_base_url = base_url
@@ -515,9 +581,9 @@ class Agent:
        self.embedder_config = embedder_config
        self.knowledge = knowledge
        self.use_system_prompt = use_system_prompt
-        # NOTE: chat_history is not thread-safe. If concurrent access is needed,
-        # consider using threading.Lock or other synchronization mechanisms
+        # Thread-safe chat_history with lock for concurrent access
        self.chat_history = []
+        self._history_lock = threading.Lock()
        self.markdown = markdown
        self.stream = stream
        self.metrics = metrics
@@ -578,11 +644,11 @@ Your Goal: {self.goal}
        self._guardrail_fn = None
        self._setup_guardrail()
        
-        # Cache for system prompts and formatted tools
-        # Note: In single-threaded usage (common case), these are safe
-        # For multi-threaded usage, consider using threading.Lock
+        # Cache for system prompts and formatted tools with thread-safe lock
+        # RLock allows re-entrant access from the same thread
        self._system_prompt_cache = {}
        self._formatted_tools_cache = {}
+        self._cache_lock = threading.RLock()
        # Limit cache size to prevent unbounded growth
        self._max_cache_size = 100

@@ -1622,8 +1688,32 @@ Your Goal: {self.goal}"""
    def execute_tool(self, function_name, arguments):
        """
        Execute a tool dynamically based on the function name and arguments.
+        Injects agent state for tools with Injected[T] parameters.
        """
        logging.debug(f"{self.name} executing tool {function_name} with arguments: {arguments}")
+        
+        # Set up injection context for tools with Injected parameters
+        from ..tools.injected import AgentState, with_injection_context
+        state = AgentState(
+            agent_id=self.name,
+            run_id=getattr(self, '_current_run_id', 'unknown'),
+            session_id=getattr(self, '_session_id', None) or 'default',
+            last_user_message=self.chat_history[-1].get('content') if self.chat_history else None,
+            metadata={'agent_name': self.name}
+        )
+        
+        # Execute within injection context
+        return self._execute_tool_with_context(function_name, arguments, state)
+    
+    def _execute_tool_with_context(self, function_name, arguments, state):
+        """Execute tool within injection context."""
+        from ..tools.injected import with_injection_context
+        
+        with with_injection_context(state):
+            return self._execute_tool_impl(function_name, arguments)
+    
+    def _execute_tool_impl(self, function_name, arguments):
+        """Internal tool execution implementation."""

        # Check if approval is required for this tool
        from ..approval import is_approval_required, console_approval_callback, get_risk_level, mark_approved, ApprovalDecision, get_approval_callback
@@ -1656,7 +1746,11 @@ Your Goal: {self.goal}"""

        # Special handling for MCP tools
        # Check if tools is an MCP instance with the requested function name
-        from ..mcp.mcp import MCP
+        MCP = None
+        try:
+            from ..mcp.mcp import MCP
+        except ImportError:
+            pass  # MCP not available
        
        # Helper function to execute MCP tool
        def _execute_mcp_tool(mcp_instance, func_name, args):
@@ -1691,7 +1785,7 @@ Your Goal: {self.goal}"""
            return False, None
        
        # Check if tools is a single MCP instance
-        if isinstance(self.tools, MCP):
+        if MCP is not None and isinstance(self.tools, MCP):
            logging.debug(f"Looking for MCP tool {function_name}")
            found, result = _execute_mcp_tool(self.tools, function_name, arguments)
            if found:
@@ -1700,7 +1794,7 @@ Your Goal: {self.goal}"""
        # Check if tools is a list that may contain MCP instances
        if isinstance(self.tools, (list, tuple)):
            for tool in self.tools:
-                if isinstance(tool, MCP):
+                if MCP is not None and isinstance(tool, MCP):
                    logging.debug(f"Looking for MCP tool {function_name} in MCP instance")
                    found, result = _execute_mcp_tool(tool, function_name, arguments)
                    if found:
@@ -2058,7 +2152,11 @@ Your Goal: {self.goal}"""
        """Get the current session ID."""
        return self._session_id

-    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None):
+    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None, config=None):
+        # Apply rate limiter if configured (before any LLM call)
+        if self._rate_limiter is not None:
+            self._rate_limiter.acquire()
+        
        # Initialize DB session on first chat (lazy)
        self._init_db_session()
        
@@ -2118,8 +2216,12 @@ Your Goal: {self.goal}"""
                
                # Convert MCP tool objects to OpenAI format if needed
                if tool_param is not None:
-                    from ..mcp.mcp import MCP
-                    if isinstance(tool_param, MCP) and hasattr(tool_param, 'to_openai_tool'):
+                    MCP = None
+                    try:
+                        from ..mcp.mcp import MCP
+                    except ImportError:
+                        pass
+                    if MCP is not None and isinstance(tool_param, MCP) and hasattr(tool_param, 'to_openai_tool'):
                        # Single MCP instance
                        logging.debug("Converting single MCP tool to OpenAI format")
                        openai_tool = tool_param.to_openai_tool()
@@ -2134,7 +2236,7 @@ Your Goal: {self.goal}"""
                        # List that may contain MCP instances - convert each MCP to OpenAI format
                        converted_tools = []
                        for t in tool_param:
-                            if isinstance(t, MCP) and hasattr(t, 'to_openai_tool'):
+                            if MCP is not None and isinstance(t, MCP) and hasattr(t, 'to_openai_tool'):
                                logging.debug("Converting MCP instance in list to OpenAI format")
                                openai_tools = t.to_openai_tool()
                                if isinstance(openai_tools, list):
@@ -3069,8 +3171,12 @@ Write the complete compiled report:"""
                
                # Convert MCP tools if needed
                if tool_param is not None:
-                    from ..mcp.mcp import MCP
-                    if isinstance(tool_param, MCP) and hasattr(tool_param, 'to_openai_tool'):
+                    MCP = None
+                    try:
+                        from ..mcp.mcp import MCP
+                    except ImportError:
+                        pass
+                    if MCP is not None and isinstance(tool_param, MCP) and hasattr(tool_param, 'to_openai_tool'):
                        openai_tool = tool_param.to_openai_tool()
                        if openai_tool:
                            if isinstance(openai_tool, list):
@@ -0,0 +1,85 @@
+"""
+Database adapter interface for PraisonAI Agents.
+
+This module provides the protocol and types for database persistence.
+Implementations are provided by the wrapper layer (praisonai.db).
+
+Usage (simplest - recommended):
+    from praisonaiagents import Agent, db
+    
+    agent = Agent(
+        name="Assistant",
+        db=db(database_url="postgresql://localhost/mydb"),  # db(...) shortcut
+        session_id="my-session"  # optional: defaults to per-hour ID
+    )
+    agent.chat("Hello!")  # auto-persists messages, runs, traces, tool calls
+
+Alternative (explicit backend):
+    db=db.PraisonDB(database_url="...")  # Auto-detect backend
+    db=db.PostgresDB(host="localhost")   # PostgreSQL
+    db=db.SQLiteDB(path="data.db")       # SQLite
+    db=db.RedisDB(host="localhost")      # Redis (state only)
+"""
+
+from .protocol import (
+    DbAdapter,
+    AsyncDbAdapter,
+    DbMessage,
+    DbToolCall,
+    DbRun,
+    DbSpan,
+    DbTrace,
+)
+
+
+class _LazyDbModule:
+    """
+    Lazy proxy for database backends.
+    
+    Allows `from praisonaiagents import db` without importing heavy deps.
+    Actual backend classes are loaded only when accessed.
+    """
+    
+    _BACKENDS = {
+        "PraisonDB": "praisonai.db.adapter",
+        "PostgresDB": "praisonai.db.adapter",
+        "SQLiteDB": "praisonai.db.adapter",
+        "RedisDB": "praisonai.db.adapter",
+    }
+    
+    def __getattr__(self, name: str):
+        if name in self._BACKENDS:
+            try:
+                import importlib
+                module = importlib.import_module(self._BACKENDS[name])
+                return getattr(module, name)
+            except ImportError as e:
+                raise ImportError(
+                    f"Database backend '{name}' requires the praisonai package. "
+                    f"Install with: pip install praisonai\n"
+                    f"Original error: {e}"
+                ) from e
+        raise AttributeError(f"module 'db' has no attribute {name!r}")
+    
+    def __repr__(self):
+        return "<module 'praisonaiagents.db' (lazy database backends)>"
+    
+    def __call__(self, **kwargs):
+        """Shortcut: db(...) is equivalent to db.PraisonDB(...)"""
+        return self.PraisonDB(**kwargs)
+
+
+# Singleton lazy module instance
+db = _LazyDbModule()
+
+
+__all__ = [
+    "DbAdapter",
+    "AsyncDbAdapter",
+    "DbMessage",
+    "DbToolCall",
+    "DbRun",
+    "DbSpan",
+    "DbTrace",
+    "db",
+]
@@ -0,0 +1,519 @@
+"""
+Database adapter protocol for PraisonAI Agents.
+
+This module uses only stdlib (typing, dataclasses) to define the interface.
+No external dependencies are imported here.
+
+Implementations are provided by the wrapper layer (praisonai.db).
+
+Schema Versioning:
+- SCHEMA_VERSION tracks the protocol version
+- Adapters should implement get_schema_version() to report their version
+- Adapters should implement migrate_schema() for upgrades
+- Version format: MAJOR.MINOR (e.g., "1.0", "1.1", "2.0")
+- MAJOR changes are breaking, MINOR changes are backward compatible
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable, Tuple
+import time
+
+
+# Current schema version for the DbAdapter protocol
+# Increment MINOR for backward-compatible additions
+# Increment MAJOR for breaking changes
+SCHEMA_VERSION = "1.0"
+
+
+@dataclass
+class DbToolCall:
+    """A tool call to be persisted."""
+    tool_name: str
+    args: Dict[str, Any]
+    result: Any = None
+    call_id: Optional[str] = None
+    timestamp: float = field(default_factory=time.time)
+    duration_ms: Optional[float] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class DbMessage:
+    """A message to be persisted."""
+    role: str  # "user", "assistant", "system", "tool"
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+    id: Optional[str] = None
+    tool_calls: Optional[List["DbToolCall"]] = None  # For assistant messages with tool calls
+    run_id: Optional[str] = None  # Group messages by run
+
+
+@dataclass
+class DbRun:
+    """A single agent run (turn) to be persisted."""
+    run_id: str
+    session_id: str
+    agent_name: str
+    started_at: float = field(default_factory=time.time)
+    ended_at: Optional[float] = None
+    status: str = "running"  # running, completed, error, cancelled
+    input_content: Optional[str] = None
+    output_content: Optional[str] = None
+    messages: List[DbMessage] = field(default_factory=list)
+    tool_calls: List[DbToolCall] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    metrics: Dict[str, Any] = field(default_factory=dict)  # tokens, latency, etc.
+
+
+@dataclass
+class DbSpan:
+    """A span for tracing/observability."""
+    span_id: str
+    trace_id: str
+    name: str
+    started_at: float = field(default_factory=time.time)
+    ended_at: Optional[float] = None
+    parent_span_id: Optional[str] = None
+    status: str = "running"  # running, ok, error
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    events: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class DbTrace:
+    """A trace for observability (groups spans)."""
+    trace_id: str
+    session_id: Optional[str] = None
+    run_id: Optional[str] = None
+    agent_name: Optional[str] = None
+    user_id: Optional[str] = None
+    started_at: float = field(default_factory=time.time)
+    ended_at: Optional[float] = None
+    status: str = "running"  # running, ok, error
+    spans: List[DbSpan] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class DbAdapter(Protocol):
+    """
+    Protocol for database adapters that provide persistence for agents.
+    
+    Implementations must provide these methods. The agent will call them
+    at appropriate lifecycle points if a db adapter is provided.
+    
+    All methods are synchronous. Async support can be added via wrapper.
+    """
+    
+    def on_agent_start(
+        self,
+        agent_name: str,
+        session_id: str,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> List[DbMessage]:
+        """
+        Called when agent starts a session.
+        
+        Args:
+            agent_name: Name of the agent
+            session_id: Session identifier
+            user_id: Optional user identifier
+            metadata: Optional session metadata
+            
+        Returns:
+            List of previous messages for this session (for resume)
+        """
+        ...
+    
+    def on_user_message(
+        self,
+        session_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when user sends a message.
+        
+        Args:
+            session_id: Session identifier
+            content: Message content
+            metadata: Optional message metadata
+        """
+        ...
+    
+    def on_agent_message(
+        self,
+        session_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when agent produces a response.
+        
+        Args:
+            session_id: Session identifier
+            content: Response content
+            metadata: Optional message metadata
+        """
+        ...
+    
+    def on_tool_call(
+        self,
+        session_id: str,
+        tool_name: str,
+        args: Dict[str, Any],
+        result: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a tool is executed.
+        
+        Args:
+            session_id: Session identifier
+            tool_name: Name of the tool
+            args: Tool arguments
+            result: Tool result
+            metadata: Optional call metadata
+        """
+        ...
+    
+    def on_agent_end(
+        self,
+        session_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when agent session ends.
+        
+        Args:
+            session_id: Session identifier
+            metadata: Optional end metadata
+        """
+        ...
+    
+    def on_run_start(
+        self,
+        session_id: str,
+        run_id: str,
+        input_content: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a new run (turn) starts.
+        
+        Args:
+            session_id: Session identifier
+            run_id: Run identifier
+            input_content: User input for this run
+            metadata: Optional run metadata
+        """
+        ...
+    
+    def on_run_end(
+        self,
+        session_id: str,
+        run_id: str,
+        output_content: Optional[str] = None,
+        status: str = "completed",
+        metrics: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a run (turn) ends.
+        
+        Args:
+            session_id: Session identifier
+            run_id: Run identifier
+            output_content: Agent output for this run
+            status: Run status (completed, error, cancelled)
+            metrics: Optional metrics (tokens, latency)
+            metadata: Optional run metadata
+        """
+        ...
+    
+    def get_runs(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+    ) -> List["DbRun"]:
+        """
+        Get runs for a session.
+        
+        Args:
+            session_id: Session identifier
+            limit: Maximum number of runs to return
+            
+        Returns:
+            List of runs for this session
+        """
+        ...
+    
+    def export_session(
+        self,
+        session_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Export a session as a dictionary (for JSONL export).
+        
+        Args:
+            session_id: Session identifier
+            
+        Returns:
+            Dictionary with session data, messages, runs
+        """
+        ...
+    
+    def import_session(
+        self,
+        data: Dict[str, Any],
+    ) -> str:
+        """
+        Import a session from a dictionary.
+        
+        Args:
+            data: Session data dictionary
+            
+        Returns:
+            Session ID of imported session
+        """
+        ...
+    
+    # --- Tracing/Observability ---
+    
+    def on_trace_start(
+        self,
+        trace_id: str,
+        session_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a new trace starts.
+        
+        Args:
+            trace_id: Unique trace identifier
+            session_id: Optional session identifier
+            run_id: Optional run identifier
+            agent_name: Optional agent name
+            user_id: Optional user identifier
+            metadata: Optional trace metadata
+        """
+        ...
+    
+    def on_trace_end(
+        self,
+        trace_id: str,
+        status: str = "ok",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a trace ends.
+        
+        Args:
+            trace_id: Trace identifier
+            status: Trace status (ok, error)
+            metadata: Optional end metadata
+        """
+        ...
+    
+    def on_span_start(
+        self,
+        span_id: str,
+        trace_id: str,
+        name: str,
+        parent_span_id: Optional[str] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a new span starts.
+        
+        Args:
+            span_id: Unique span identifier
+            trace_id: Parent trace identifier
+            name: Span name (e.g., "llm_call", "tool_execution")
+            parent_span_id: Optional parent span for nesting
+            attributes: Optional span attributes
+        """
+        ...
+    
+    def on_span_end(
+        self,
+        span_id: str,
+        status: str = "ok",
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Called when a span ends.
+        
+        Args:
+            span_id: Span identifier
+            status: Span status (ok, error)
+            attributes: Optional end attributes
+        """
+        ...
+    
+    def get_traces(
+        self,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List["DbTrace"]:
+        """
+        Get traces with optional filters.
+        
+        Args:
+            session_id: Filter by session
+            user_id: Filter by user
+            limit: Maximum number of traces
+            
+        Returns:
+            List of traces
+        """
+        ...
+    
+    def close(self) -> None:
+        """Close the database connection."""
+        ...
+    
+    # --- Schema Versioning (Optional) ---
+    # These methods are optional for backward compatibility.
+    # Adapters that don't implement them will work but won't support migrations.
+    
+    def get_schema_version(self) -> str:
+        """
+        Get the current schema version of this adapter.
+        
+        Returns:
+            Schema version string (e.g., "1.0")
+            Default implementation returns "1.0"
+        """
+        ...
+    
+    def migrate_schema(
+        self,
+        from_version: str,
+        to_version: str,
+    ) -> bool:
+        """
+        Migrate the schema from one version to another.
+        
+        Args:
+            from_version: Current schema version
+            to_version: Target schema version
+            
+        Returns:
+            True if migration succeeded, False otherwise
+        """
+        ...
+    
+    def check_schema_compatibility(self) -> Tuple[bool, str]:
+        """
+        Check if the adapter's schema is compatible with the protocol.
+        
+        Returns:
+            Tuple of (is_compatible, message)
+            - is_compatible: True if schema is compatible
+            - message: Description of compatibility status or required action
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncDbAdapter(Protocol):
+    """
+    Async protocol for database adapters.
+    
+    Provides async variants of all DbAdapter methods for use with
+    async/await patterns and async backends like asyncpg.
+    """
+    
+    async def on_agent_start(
+        self,
+        agent_name: str,
+        session_id: str,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> List["DbMessage"]:
+        """Async version of on_agent_start."""
+        ...
+    
+    async def on_user_message(
+        self,
+        session_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_user_message."""
+        ...
+    
+    async def on_agent_message(
+        self,
+        session_id: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_agent_message."""
+        ...
+    
+    async def on_tool_call(
+        self,
+        session_id: str,
+        tool_name: str,
+        args: Dict[str, Any],
+        result: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_tool_call."""
+        ...
+    
+    async def on_agent_end(
+        self,
+        session_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_agent_end."""
+        ...
+    
+    async def on_run_start(
+        self,
+        session_id: str,
+        run_id: str,
+        input_content: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_run_start."""
+        ...
+    
+    async def on_run_end(
+        self,
+        session_id: str,
+        run_id: str,
+        output_content: Optional[str] = None,
+        status: str = "completed",
+        metrics: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Async version of on_run_end."""
+        ...
+    
+    async def export_session(
+        self,
+        session_id: str,
+    ) -> Dict[str, Any]:
+        """Async version of export_session."""
+        ...
+    
+    async def import_session(
+        self,
+        data: Dict[str, Any],
+    ) -> str:
+        """Async version of import_session."""
+        ...
+    
+    async def close(self) -> None:
+        """Async close the database connection."""
+        ...
@@ -0,0 +1 @@
+"""TDD tests for db integration."""
@@ -0,0 +1,246 @@
+"""
+TDD tests for PraisonAI Agents DB integration.
+
+Tests:
+1. Lazy import verification - no heavy deps on import
+2. Agent(db=MockDb) calls hook lifecycle in correct order
+3. Session resume injects history
+4. db=None behavior unchanged
+"""
+
+import sys
+import time
+
+
+def test_lazy_import_no_heavy_deps():
+    """Test that importing praisonaiagents.db does not import DB libs."""
+    print("=== Test: Lazy Import Verification ===")
+    
+    # Record modules before import
+    before_modules = set(sys.modules.keys())
+    
+    # Import only the db module (not full praisonaiagents which loads Knowledge)
+    from praisonaiagents.db import DbAdapter, DbMessage
+    
+    # Check that heavy DB libs are NOT loaded by db module itself
+    # Note: praisonaiagents main package loads qdrant/chroma via Knowledge
+    # but the db module should not add any additional heavy deps
+    heavy_libs = ['psycopg2', 'pymysql', 'redis']  # DB-specific libs
+    loaded_heavy = [lib for lib in heavy_libs if lib in sys.modules]
+    
+    if loaded_heavy:
+        print(f"  ❌ Heavy DB libs loaded by db module: {loaded_heavy}")
+        return False
+    
+    print("  ✅ No heavy DB libs loaded by praisonaiagents.db module")
+    return True
+
+
+def test_agent_accepts_db_parameter():
+    """Test that Agent accepts db and session_id parameters."""
+    print("\n=== Test: Agent Accepts db Parameter ===")
+    
+    import inspect
+    from praisonaiagents import Agent
+    
+    sig = inspect.signature(Agent.__init__)
+    params = list(sig.parameters.keys())
+    
+    if 'db' not in params:
+        print("  ❌ Agent does not accept 'db' parameter")
+        return False
+    
+    if 'session_id' not in params:
+        print("  ❌ Agent does not accept 'session_id' parameter")
+        return False
+    
+    print("  ✅ Agent accepts db and session_id parameters")
+    return True
+
+
+class MockDbAdapter:
+    """Mock DB adapter for testing hook lifecycle."""
+    
+    def __init__(self):
+        self.calls = []
+        self.history_to_return = []
+    
+    def on_agent_start(self, agent_name, session_id, user_id=None, metadata=None):
+        self.calls.append(('on_agent_start', agent_name, session_id))
+        return self.history_to_return
+    
+    def on_user_message(self, session_id, content, metadata=None):
+        self.calls.append(('on_user_message', session_id, content))
+    
+    def on_agent_message(self, session_id, content, metadata=None):
+        self.calls.append(('on_agent_message', session_id, content))
+    
+    def on_tool_call(self, session_id, tool_name, args, result, metadata=None):
+        self.calls.append(('on_tool_call', session_id, tool_name))
+    
+    def on_agent_end(self, session_id, metadata=None):
+        self.calls.append(('on_agent_end', session_id))
+    
+    def close(self):
+        self.calls.append(('close',))
+
+
+def test_db_hook_lifecycle():
+    """Test that Agent calls db hooks in correct order."""
+    print("\n=== Test: DB Hook Lifecycle ===")
+    
+    from praisonaiagents import Agent
+    
+    mock_db = MockDbAdapter()
+    
+    # Create agent with mock db
+    agent = Agent(
+        name="TestAgent",
+        instructions="Test agent",
+        db=mock_db,
+        session_id="test-session-001",
+        verbose=False
+    )
+    
+    # Verify db is stored
+    if agent._db is not mock_db:
+        print("  ❌ Agent did not store db adapter")
+        return False
+    
+    if agent._session_id != "test-session-001":
+        print("  ❌ Agent did not store session_id")
+        return False
+    
+    print("  ✅ Agent stores db and session_id correctly")
+    return True
+
+
+def test_db_none_unchanged_behavior():
+    """Test that db=None behavior is unchanged."""
+    print("\n=== Test: db=None Unchanged Behavior ===")
+    
+    from praisonaiagents import Agent
+    
+    # Create agent without db
+    agent = Agent(
+        name="TestAgent",
+        instructions="Test agent",
+        verbose=False
+    )
+    
+    # Verify db is None
+    if agent._db is not None:
+        print("  ❌ Agent._db should be None when not provided")
+        return False
+    
+    # Verify _init_db_session does nothing when db is None
+    agent._init_db_session()
+    
+    if agent._db_initialized:
+        print("  ❌ _db_initialized should remain False when db is None")
+        return False
+    
+    print("  ✅ db=None behavior unchanged")
+    return True
+
+
+def test_session_id_auto_generation():
+    """Test that session_id is auto-generated if not provided."""
+    print("\n=== Test: Session ID Auto-Generation ===")
+    
+    from praisonaiagents import Agent
+    
+    mock_db = MockDbAdapter()
+    
+    agent = Agent(
+        name="TestAgent",
+        instructions="Test agent",
+        db=mock_db,
+        # No session_id provided
+        verbose=False
+    )
+    
+    # Trigger db initialization
+    agent._init_db_session()
+    
+    if agent._session_id is None:
+        print("  ❌ session_id should be auto-generated")
+        return False
+    
+    if not agent._session_id.startswith("session-"):
+        print(f"  ❌ session_id format unexpected: {agent._session_id}")
+        return False
+    
+    print(f"  ✅ session_id auto-generated: {agent._session_id}")
+    return True
+
+
+def test_protocol_compliance():
+    """Test that DbAdapter protocol is properly defined."""
+    print("\n=== Test: DbAdapter Protocol Compliance ===")
+    
+    from praisonaiagents.db.protocol import DbAdapter, DbMessage
+    
+    # Check DbMessage fields
+    msg = DbMessage(role="user", content="test")
+    if msg.role != "user" or msg.content != "test":
+        print("  ❌ DbMessage fields not working")
+        return False
+    
+    # Check protocol methods
+    required_methods = [
+        'on_agent_start',
+        'on_user_message', 
+        'on_agent_message',
+        'on_tool_call',
+        'on_agent_end',
+        'close'
+    ]
+    
+    mock = MockDbAdapter()
+    for method in required_methods:
+        if not hasattr(mock, method):
+            print(f"  ❌ MockDbAdapter missing {method}")
+            return False
+    
+    # Check protocol isinstance
+    if not isinstance(mock, DbAdapter):
+        print("  ❌ MockDbAdapter should implement DbAdapter protocol")
+        return False
+    
+    print("  ✅ DbAdapter protocol properly defined")
+    return True
+
+
+def run_all_tests():
+    """Run all TDD tests."""
+    print("=" * 60)
+    print("PraisonAI Agents DB Integration - TDD Tests")
+    print("=" * 60)
+    
+    results = []
+    
+    results.append(("Lazy Import", test_lazy_import_no_heavy_deps()))
+    results.append(("Agent db Parameter", test_agent_accepts_db_parameter()))
+    results.append(("DB Hook Lifecycle", test_db_hook_lifecycle()))
+    results.append(("db=None Unchanged", test_db_none_unchanged_behavior()))
+    results.append(("Session ID Auto-Gen", test_session_id_auto_generation()))
+    results.append(("Protocol Compliance", test_protocol_compliance()))
+    
+    print("\n" + "=" * 60)
+    passed = sum(1 for _, r in results if r)
+    total = len(results)
+    print(f"Results: {passed}/{total} tests passed")
+    
+    for name, result in results:
+        status = "✅" if result else "❌"
+        print(f"  {status} {name}")
+    
+    print("=" * 60)
+    
+    return passed == total
+
+
+if __name__ == "__main__":
+    success = run_all_tests()
+    sys.exit(0 if success else 1)
@@ -89,11 +89,9 @@ class AccuracyEvaluator(BaseEvaluator):
            EvaluationScore with score and reasoning
        """
        try:
-            from openai import OpenAI
+            import litellm
        except ImportError:
-            raise ImportError("OpenAI package required for accuracy evaluation. Install with: pip install openai")
-        
-        client = OpenAI()
+            raise ImportError("litellm package required for accuracy evaluation. Install with: pip install litellm")
        
        prompt = f"""You are an expert evaluator. Compare the actual output against the expected output and provide a score from 1-10.

@@ -115,7 +113,8 @@ Respond in this exact format:
 SCORE: [number 1-10]
 REASONING: [brief explanation]"""

-        response = client.chat.completions.create(
+        # Use litellm for unified multi-provider support
+        response = litellm.completion(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            temperature=0.1,
Author	SHA1	Message	Date
Mervin Praison	9a5a432d96	Release v2.7.2	2025-12-29 11:40:55 +00:00
Mervin Praison	8cb5bbb605	Release v2.7.2 - update doctor examples with improved check listing and CI formatting - 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	2025-12-29 02:19:16 +00:00
Mervin Praison	952514d73c	Release v2.7.1	2025-12-29 02:15:51 +00:00
Mervin Praison	6e1dc34864	Release v2.7.0	2025-12-29 01:33:40 +00:00
Mervin Praison	820d5c2995	Release v2.6.8	2025-12-29 00:42:47 +00:00
Mervin Praison	0b1b3d3b3e	Release v2.6.7	2025-12-29 00:22:52 +00:00
Mervin Praison	59107addc3	Release v2.6.6	2025-12-28 23:51:03 +00:00
Mervin Praison	b460ded5e0	Release v2.6.5	2025-12-28 23:02:27 +00:00
Mervin Praison	a8967ed200	Release v1.3.1 - add Router class with simplified keyword/pattern-based routing and agent session management - Bump praisonai-ts version from 1.3.0 to 1.3.1 - Add Router class with simplified keyword/pattern-based routing API (5-line usage) - Export Router, RouterAgent, createRouter, routeConditions from agent module - Add SimpleRouterConfig and SimpleRouteConfig types for simplified configuration - Support both Agent and EnhancedAgent types in router (AnyAgent union type) - Add Router.chat() method for direct routing	2025-12-28 22:53:04 +00:00
Mervin Praison	9189f42470	Release v2.6.4	2025-12-28 21:47:32 +00:00
Mervin Praison	c86f660f66	Release v2.6.3	2025-12-28 07:31:42 +00:00
Mervin Praison	a2d181dd74	Release v2.6.2	2025-12-27 07:58:18 +00:00
Mervin Praison	7411fdbb52	Release v2.6.1	2025-12-26 19:41:45 +00:00
Mervin Praison	e7a8ce8eb7	Release v2.6.0	2025-12-26 19:31:15 +00:00
Mervin Praison	61fb094306	Release v1.2.3 - add comprehensive CLI feature exports and command definitions - Bump praisonai-ts version from 1.2.2 to 1.2.3 - Add 18 new command definitions to CLI spec: query-rewrite, prompt-expand, router, context, handoff, vector, observability, voice, reranker, graph-rag, cache, db, scheduler, jobs, checkpoints, fast-context, autonomy, sandbox, repo-map, git, n8n, external-agents, flow, cost, interactive - Export FileMemory and AutoMemory classes with factory functions and types from memory module - Export	2025-12-26 18:41:37 +00:00
Mervin Praison	018e8c78ab	refactor(ts): update CLI to v1.0.0 spec and change default model to gpt-4o-mini - Change default agent model from gpt-5-nano to gpt-4o-mini in simple.ts - Refactor CLI to implement CLI Spec v1.0.0 with lazy command loading - Add parseArgs() function for spec-compliant argument parsing - Add executeCommand() for dynamic command module loading - Add comprehensive command definitions: memory, session, knowledge, skills, mcp, auto, image, research, guardrail, telemetry, planning - Export CLI_SPEC_VERSION,	2025-12-26 14:07:05 +00:00
Mervin Praison	f0f0f653fe	Release v2.5.7	2025-12-26 13:31:45 +00:00
Mervin Praison	98a4ff8450	Release v2.5.6	2025-12-26 13:11:09 +00:00
Mervin Praison	d6333aaf33	Release v1.2.1 - refactor TypeScript tools to use generic BaseTool - Bump praisonai-ts version from 1.2.0 to 1.2.1 - Refactor BaseTool to use generics for type-safe input/output parameters - Update ArxivSearchTool and ArxivDownloadTool to extend generic BaseTool with typed params - Update MCPTool to extend generic BaseTool - Change tool method from execute() to run() for consistency - Export ToolResult, ToolValidationError, validateTool, createTool from base module - Remove Tool interface export	2025-12-26 11:47:17 +00:00
Mervin Praison	8005094267	update	2025-12-26 08:39:22 +00:00
Mervin Praison	08b21dabe3	Release v2.5.5	2025-12-26 08:16:54 +00:00
Mervin Praison	8c70d840df	docs: add knowledge export/import CLI commands to README - Add knowledge export/import row to features table with CLI link - Document `praisonai knowledge export <file.json>` command - Document `praisonai knowledge import <file.json>` command	2025-12-26 06:53:20 +00:00
Mervin Praison	d8e944c1d3	Release v2.5.4	2025-12-26 06:49:33 +00:00
Mervin Praison	79b2b88f72	Release v2.5.3	2025-12-26 05:54:09 +00:00
Mervin Praison	f5dfbd5670	fix: resolve Core Tests failures in knowledge/reranker integration - Fix #1: MemoryConfig Pydantic validation - add _prepare_mem0_config() to strip PraisonAI-specific reranker fields (enabled, default_rerank) before passing to mem0, which only accepts provider and config fields - Fix #2: LLM Reranker 'Chat' object not callable - check if client.chat is callable, not just if it exists. OpenAI client has chat as namespace object. Also handle max_completion_tokens vs max_tokens for different model versions. - Fix #3: Chroma vector store metadata validation - ensure non-empty metadata dicts by adding placeholder key when metadata is empty or None - Fix test file issues: add user_id parameter (required by mem0 API), handle dict return type from knowledge.search, use gpt-4o-mini for reranker test (gpt-5-nano returns empty responses with max_completion_tokens=10)	2025-12-26 05:52:46 +00:00
Mervin Praison	aa6aa5933d	fix: update test files to use gpt-5-nano for cheaper CI runs - Update test_workflow_patterns.py to use gpt-5-nano instead of gpt-4o/gpt-4o-mini - Also set OPENAI_MODEL_NAME=gpt-5-nano as CI secret	2025-12-26 05:26:40 +00:00
Mervin Praison	ff3a4f2016	Release v2.5.2	2025-12-26 05:25:08 +00:00
Mervin Praison	0d5444fc23	fix: add missing praisonai.db module to git - Add praisonai/db/ module that was being ignored by *.db pattern - This fixes ModuleNotFoundError: No module named 'praisonai.db' in CI tests	2025-12-26 04:54:05 +00:00
Mervin Praison	d7d5dab17b	fix: add missing db module to git and update .gitignore - Add praisonaiagents/db/ module that was being ignored by *.db pattern - Add exception in .gitignore for the db module directory - This fixes ModuleNotFoundError: No module named 'praisonaiagents.db' in CI	2025-12-26 04:49:31 +00:00
Mervin Praison	05678394e6	fix: remove sys.exit() at module level in test files causing pytest INTERNALERROR - test_mini_agents_fix.py: Convert module-level sys.exit(1) to pytest.mark.skipif pattern - test_xai_fix.py: Convert to proper pytest test function with cleanup These sys.exit() calls at module level caused pytest to crash during test collection with INTERNALERROR, breaking all CI pipelines.	2025-12-26 04:46:58 +00:00
Mervin Praison	54cddc09b4	Release v2.5.1	2025-12-26 04:23:51 +00:00
Mervin Praison	9cbab01785	Release v2.5.0	2025-12-26 02:20:59 +00:00
Mervin Praison	de9d4bd3c6	Release v2.4.4	2025-12-26 01:21:26 +00:00