Release v3.3.0

## Queue Editing
- Added update_input method to QueueScheduler for editing queued runs
- Added update_input method to QueueManager
- Added handler for QueuePanelWidget.EditRequested in TUIApp
- Only queued (not running) items can be edited

## Queue-First Architecture Support
- Queue items can be edited before processing
- EditRequested message already existed in QueuePanelWidget

31 tests passing

README.md

@@ -36,10 +36,10 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 ---
 
 > **Quick Paths:**
-> - 🚀 **New here?** → [Quick Start](#-quick-start)
+> - 🆕 **New here?** → [Quick Start](#-quick-start) *(1 minute to first agent)*
 > - 📦 **Installing?** → [Installation](#-installation)
-> - 💻 **Python SDK?** → [Python Examples](#-using-python-code)
-> - 🎯 **CLI user?** → [CLI Reference](#-cli--no-code-interface)
+> - 🐍 **Python SDK?** → [Python Examples](#-using-python-code)
+> - 🎯 **CLI user?** → [CLI Quick Reference](#cli-quick-reference)
 > - 🔧 **Need config?** → [Configuration](#-configuration--integration)
 > - 🤝 **Contributing?** → [Development](#-development)
 
@@ -47,96 +47,81 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 
 ## 📑 Table of Contents
 
-### Getting Started
-- [⚡ Performance](#-performance)
+<details open>
+<summary><strong>Getting Started</strong></summary>
+
 - [🚀 Quick Start](#-quick-start)
 - [📦 Installation](#-installation)
-  - [Python SDK](#python-sdk)
-  - [JavaScript SDK](#javascript-sdk)
-  - [Environment Variables](#environment-variables)
+- [⚡ Performance](#-performance)
 
-### Core Concepts
-- [✨ Key Features](#-key-features)
-- [🌐 Supported Providers](#-supported-providers)
+</details>
+
+<details>
+<summary><strong>Python SDK</strong></summary>
 
-### 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)
+  - [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
+</details>
+
+<details>
+<summary><strong>JavaScript SDK</strong></summary>
+
 - [💻 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)
+</details>
 
-### Configuration
-- [🔧 Configuration & Integration](#-configuration--integration)
-  - [Ollama Integration](#ollama-integration)
-  - [Groq Integration](#groq-integration)
-  - [100+ Models Support](#100-models-support)
+<details>
+<summary><strong>CLI Reference</strong></summary>
+
+- [🎯 CLI Overview](#-cli--no-code-interface) | [CLI Quick Reference](#cli-quick-reference)
+- [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)
+
+</details>
+
+<details>
+<summary><strong>Configuration & Features</strong></summary>
+
+- [✨ Key Features](#-key-features) | [🌐 Supported Providers](#-supported-providers)
+- [🔧 Configuration & Integration](#-configuration--integration) | [Ollama](#ollama-integration) | [Groq](#groq-integration) | [100+ Models](#100-models-support)
 - [📋 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
+</details>
+
+<details>
+<summary><strong>Architecture & Patterns</strong></summary>
+
 - [📊 Process Types & Patterns](#-process-types--patterns)
-  - [Sequential Process](#sequential-process)
-  - [Hierarchical Process](#hierarchical-process)
-  - [Workflow Process](#workflow-process)
-  - [Agentic Patterns](#agentic-patterns)
+- [Sequential](#sequential-process) | [Hierarchical](#hierarchical-process) | [Workflow](#workflow-process) | [Agentic Patterns](#agentic-patterns)
+
+</details>
+
+<details>
+<summary><strong>Data & Persistence</strong></summary>
 
-### 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)
+</details>
+
+<details>
+<summary><strong>Learning & Community</strong></summary>
+
+- [🎓 Video Tutorials](#-video-tutorials) | [⭐ Star History](#-star-history)
+- [👥 Contributing](#-contributing) | [🔧 Development](#-development) | [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
+
+</details>
 
 ---
 
@@ -181,6 +166,8 @@ export OPENAI_API_KEY=your_key_here
 python -c "from praisonaiagents import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"
 ```
 
+> **Next Steps:** [Single Agent Example](#1-single-agent) | [Multi Agents](#2-multi-agents) | [CLI Auto Mode](#auto-mode)
+
 ---
 
 ## 📦 Installation
@@ -231,28 +218,6 @@ export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 
 ---
 
-## 💻 Usage
-
-### Python Code Examples
-
-- [📘 Complete Python Examples](#using-python-code)
-- [🔧 Custom Tools](#️-custom-tools)
-- [🧠 Memory Configuration](#-memory--context)
-
-### CLI / No-Code Interface
-
-- [🎯 Auto Mode](#auto-mode)
-- [🔬 Deep Research](#deep-research-cli)
-- [📋 Planning Mode](#planning-mode-cli)
-- [💾 Memory Management](#memory-cli)
-- [🔄 Workflow Execution](#workflow-cli)
-
-### JavaScript Code Examples
-
-- [💻 JavaScript Usage](#using-javascript-code)
-
----
-
 ## ✨ Key Features
 
 <details open>
@@ -519,6 +484,9 @@ export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 
 PraisonAI supports 100+ LLM providers through seamless integration:
 
+<details>
+<summary><strong>View all 24 providers</strong></summary>
+
 | Provider | Example |
 |----------|:-------:|
 | OpenAI | [Example](examples/python/providers/openai/openai_gpt4_example.py) |
@@ -546,17 +514,12 @@ PraisonAI supports 100+ LLM providers through seamless integration:
 | Moonshot | [Example](examples/python/providers/moonshot/moonshot_example.py) |
 | vLLM | [Example](examples/python/providers/vllm/vllm_example.py) |
 
+</details>
+
 ---
 
 ## 📘 Using Python Code
 
-Light weight package dedicated for coding:
-
-```bash
-pip install praisonaiagents
-export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
-```
-
 ### 1. Single Agent
 
 Create app.py file and add the code below:
@@ -1967,11 +1930,11 @@ agent = Agent(
     auto_save="my-project"
 )
 
-# Load history from last 5 sessions
+# Load history from past sessions via context management
 agent = Agent(
     name="Assistant",
     memory=True,
-    history_in_context=5
+    context=True,  # Enable context management for history
 )
 ```
 
@@ -2405,6 +2368,9 @@ agent.start('Write a movie script about a robot in Mars');
 
 ## 📊 Process Types & Patterns
 
+<details>
+<summary><strong>View architecture diagrams and workflow patterns</strong></summary>
+
 ### AI Agents Flow
 
 ```mermaid
@@ -2744,6 +2710,8 @@ flowchart LR
     style Out fill:#8B0000,color:#fff
 ```
 
+</details>
+
 ---
 
 ## 🔧 Configuration & Integration
@@ -2891,77 +2859,179 @@ PraisonAI provides zero-dependency persistent memory for agents. For detailed ex
 
 PraisonAI provides a complete knowledge stack for building RAG applications with multiple vector stores, retrieval strategies, rerankers, and query modes.
 
+### RAG Quickstart (Agent-first)
+
+```python
+from praisonaiagents import Agent
+from praisonaiagents.rag.models import RetrievalStrategy
+
+# Agent with RAG - simplest approach
+agent = Agent(
+    name="Research Assistant",
+    knowledge=["docs/manual.pdf", "data/faq.txt"],
+    knowledge_config={"vector_store": {"provider": "chroma"}},
+    rag_config={
+        "include_citations": True,
+        "retrieval_strategy": RetrievalStrategy.HYBRID,  # Dense + BM25
+        "rerank": True,
+    }
+)
+
+# Query with citations
+result = agent.rag_query("How do I authenticate?")
+print(result.answer)
+for citation in result.citations:
+    print(f"  [{citation.id}] {citation.source}")
+```
+
+### RAG CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai rag query "<question>"` | One-shot question answering with citations |
+| `praisonai rag chat` | Interactive RAG chat session |
+| `praisonai rag serve` | Start RAG as a microservice API |
+| `praisonai rag eval <test_file>` | Evaluate RAG retrieval quality |
+
+### RAG CLI Examples
+
+```bash
+# Query with hybrid retrieval (dense + BM25 keyword search)
+praisonai rag query "What are the key findings?" --hybrid
+
+# Query with hybrid + reranking for best quality
+praisonai rag query "Summarize conclusions" --hybrid --rerank
+
+# Interactive chat with hybrid retrieval
+praisonai rag chat --collection research --hybrid --rerank
+
+# Start API server with OpenAI-compatible endpoint
+praisonai rag serve --hybrid --rerank --openai-compat --port 8080
+
+# Query with profiling
+praisonai rag query "Summary?" --profile --profile-out ./profile.json
+```
+
 ### 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 index <sources>` | Index documents into knowledge base |
+| `praisonai knowledge search <query>` | Search knowledge base (no LLM generation) |
 | `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"
+# Index documents
+praisonai knowledge index ./docs/ --collection myproject
 
-# Query with advanced options
-praisonai knowledge query "How to authenticate?" --retrieval fusion --reranker llm
+# Search with hybrid retrieval
+praisonai knowledge search "authentication" --hybrid --collection myproject
 
-# Full advanced query
-praisonai knowledge query "authentication flow" \
-  --vector-store chroma \
-  --retrieval fusion \
-  --reranker llm \
-  --index-type hybrid \
-  --query-mode sub_question
+# Index with profiling
+praisonai knowledge index ./data --profile --profile-out ./profile.json
 ```
 
-### Knowledge SDK Usage
+### Knowledge vs RAG vs AutoRagAgent
+
+- **Knowledge** is the indexing and retrieval substrate - use for indexing and raw search
+- **RAG** orchestrates on top - use for question answering with LLM-generated responses and citations
+- **AutoRagAgent** wraps an Agent with automatic retrieval decision - use when you want the agent to decide when to retrieve
+- All share the same underlying index
+
+### AutoRagAgent (Automatic RAG)
+
+AutoRagAgent automatically decides when to retrieve context from knowledge bases vs direct chat, based on query heuristics.
 
 ```python
-from praisonaiagents import Agent, Knowledge
+from praisonaiagents import Agent, AutoRagAgent
 
-# Simple usage with Agent
+# Create agent with knowledge
 agent = Agent(
     name="Research Assistant",
-    knowledge=["docs/manual.pdf", "data/faq.txt"],
-    knowledge_config={
-        "vector_store": {"provider": "chroma"}
-    }
+    knowledge=["docs/manual.pdf"],
+    user_id="user123",  # Required for RAG retrieval
 )
-response = agent.chat("How do I authenticate?")
 
-# Direct Knowledge usage
-knowledge = Knowledge()
-knowledge.add("document.pdf")
-results = knowledge.search("authentication", limit=5)
+# Wrap with AutoRagAgent
+auto_rag = AutoRagAgent(
+    agent=agent,
+    retrieval_policy="auto",  # auto, always, never
+    top_k=5,
+    hybrid=True,
+    rerank=True,
+)
+
+# Auto-decides: retrieves for questions, skips for greetings
+result = auto_rag.chat("What are the key findings?")  # Retrieves
+result = auto_rag.chat("Hello!")  # Skips retrieval
+
+# Force retrieval or skip per-call
+result = auto_rag.chat("Hi", force_retrieval=True)
+result = auto_rag.chat("Summary?", skip_retrieval=True)
+```
+
+**CLI Usage:**
+```bash
+# Enable auto-rag with default policy (auto)
+praisonai --auto-rag "What are the key findings?"
+
+# Always retrieve
+praisonai --auto-rag --rag-policy always "Tell me about X"
+
+# With hybrid retrieval and reranking
+praisonai --auto-rag --rag-hybrid --rag-rerank "Summarize the document"
+```
+
+### Configuration Precedence
+
+Settings are applied in this order (highest priority first):
+1. **CLI flags** - `--hybrid`, `--rerank`, `--top-k`
+2. **Environment variables** - `PRAISONAI_HYBRID=true`
+3. **Config file** - YAML configuration (`--config`)
+4. **Defaults**
+
+```bash
+# Environment variables
+export PRAISONAI_HYBRID=true
+export PRAISONAI_RERANK=true
+export PRAISONAI_TOP_K=10
+```
+
+### Lightweight Installs
+
+```bash
+# Base install (minimal, fast imports)
+pip install praisonaiagents
+
+# With RAG API server support
+pip install "praisonai[rag-api]"
+```
+
+### Live Tests (Real API Keys)
+
+Run integration tests with real API keys:
+
+```bash
+# Enable live tests
+export PRAISONAI_LIVE_TESTS=1
+export OPENAI_API_KEY="your-key"
+
+# Run live tests
+pytest -m live tests/integration/
 ```
 
 ### 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) |
+| **Hybrid Retrieval** | Dense vectors + BM25 keyword search with RRF fusion | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
+| **Reranking** | LLM, Cross-Encoder, Cohere rerankers | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
+| **RAG Serve** | Microservice API with OpenAI-compatible mode | [SDK](/docs/rag/module) | [CLI](/docs/cli/rag) |
 | **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) |
+| **Data Readers** | Load PDF, Markdown, Text, HTML, URLs | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Profiling** | Performance profiling with `--profile` flag | [SDK](/docs/features/profiling) | [CLI](/docs/cli/rag) |
 
 ---
 
@@ -3079,43 +3149,7 @@ 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
-```
+> **Note:** See [Knowledge & Retrieval (RAG)](#-knowledge--retrieval-rag) for complete Knowledge CLI documentation.
 
 ### Databases Table
 
@@ -3191,6 +3225,9 @@ Install all tools with: `pip install "praisonai[tools]"`
 
 Learn PraisonAI through our comprehensive video series:
 
+<details>
+<summary><strong>View all 22 video tutorials</strong></summary>
+
 | Topic | Video |
 |-------|--------|
 | AI Agents with Self Reflection | [![Self Reflection](https://img.youtube.com/vi/vLXobEN2Vc8/0.jpg)](https://www.youtube.com/watch?v=vLXobEN2Vc8) |
@@ -3216,6 +3253,8 @@ Learn PraisonAI through our comprehensive video series:
 | Call Interface | [![Call](https://img.youtube.com/vi/m1cwrUG2iAk/0.jpg)](https://www.youtube.com/watch?v=m1cwrUG2iAk) |
 | Reasoning Extract Agents | [![Reasoning Extract](https://img.youtube.com/vi/2PPamsADjJA/0.jpg)](https://www.youtube.com/watch?v=2PPamsADjJA) |
 
+</details>
+
 ---
 
 ## 👥 Contributing

docker/Dockerfile.chat

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

docs/profiling-cli.md

@@ -0,0 +1,203 @@
+# Profiling CLI
+
+PraisonAI provides unified profiling capabilities for performance analysis and debugging, with **full visibility from ENTER to first response**.
+
+## Quick Start
+
+```bash
+# Basic profiling
+praisonai "What is 2+2?" --profile
+
+# Deep profiling with call graph, decision trace, and module breakdown
+praisonai "What is 2+2?" --profile --profile-deep
+
+# JSON output format
+praisonai "What is 2+2?" --profile --profile-format json
+```
+
+## Time to First Response (TTFR)
+
+**TTFR** is the key user-perceived latency metric. It measures the time from when you press ENTER until the first visible output appears.
+
+### What contributes to TTFR?
+
+1. **CLI Entry** - Time to reach the CLI entry point
+2. **CLI Parse** - Argparse/Typer routing time
+3. **Routing** - Command routing to handler
+4. **Imports** - Loading required modules
+5. **Agent Init** - Initializing the agent
+6. **Network Request** - Sending request to LLM API
+7. **First Token** - Receiving first token (streaming)
+8. **First Output** - Rendering first visible output
+
+### How to reduce TTFR
+
+1. **Warm runs** - Imports are cached after first run
+2. **Streaming mode** - See output as tokens arrive
+3. **Lighter models** - Faster response times
+4. **Local models** - Eliminate network latency
+
+## CLI Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--profile` | Enable profiling with timing breakdown | Disabled |
+| `--profile-deep` | Enable deep profiling with call graph (higher overhead) | Disabled |
+| `--profile-format` | Output format: `text` or `json` | `text` |
+
+## Profile Command
+
+For more detailed profiling options, use the `profile` subcommand:
+
+```bash
+# Profile a query
+praisonai profile query "What is 2+2?"
+
+# With deep call tracing
+praisonai profile query "Hello" --deep
+
+# Limit functions shown
+praisonai profile query "Test" --limit 20
+
+# Save artifacts to directory
+praisonai profile query "Test" --save ./profile_results
+
+# JSON output
+praisonai profile query "Test" --format json
+```
+
+### Profile Query Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--model, -m` | Model to use | Default model |
+| `--stream/--no-stream` | Use streaming mode | No stream |
+| `--deep` | Enable deep call tracing | Disabled |
+| `--limit, -n` | Top N functions to show | 30 |
+| `--sort, -s` | Sort by: `cumulative` or `tottime` | `cumulative` |
+| `--show-callers` | Show caller functions | Disabled |
+| `--show-callees` | Show callee functions | Disabled |
+| `--save` | Save artifacts to path | None |
+| `--format, -f` | Output format: `text` or `json` | `text` |
+
+## Other Profile Commands
+
+```bash
+# Profile module import times
+praisonai profile imports
+
+# Profile CLI startup time
+praisonai profile startup
+
+# Run comprehensive profiling suite
+praisonai profile suite
+
+# Create performance snapshots for comparison
+praisonai profile snapshot --baseline
+praisonai profile snapshot current --compare
+
+# Configure performance optimizations
+praisonai profile optimize --show
+```
+
+## Output Format
+
+### Text Report
+
+```
+======================================================================
+PraisonAI Profile Report
+======================================================================
+
+Run ID:     abc12345
+Timestamp:  2024-01-02T12:00:00.000000Z
+Method:     cli_direct
+Version:    3.0.1
+
+## Execution Timeline
+---------------------------------------------
+  Imports                   :   500.00 ms
+  Agent Init                :     0.50 ms
+  Execution                 :  2000.00 ms
+  ───────────────────────────────────────────
+  ⏱ Time to First Response  :  2500.50 ms
+  TOTAL                     :  2500.50 ms
+
+## Timing Breakdown
+----------------------------------------
+  Imports:            500.00 ms
+  Agent Init:           0.50 ms
+  Execution:         2000.00 ms
+  ─────────────────────────────────────
+  TOTAL:             2500.50 ms
+
+## Decision Trace (deep profile only)
+----------------------------------------
+  Agent Config:    default
+  Model:           gpt-4
+  Streaming:       disabled
+  Profile Layer:   2
+
+## Top Functions by Cumulative Time
+----------------------------------------------------------------------
+Function                                    Calls   Cumul (ms)
+----------------------------------------------------------------------
+request                                         1      1800.00
+send                                            1      1750.00
+...
+```
+
+### JSON Report
+
+```json
+{
+  "schema_version": "1.0",
+  "run_id": "abc12345",
+  "timestamp": "2024-01-02T12:00:00.000000Z",
+  "invocation": {
+    "method": "cli_direct",
+    "flags": {"layer": 1, "stream": false, "model": null},
+    "praisonai_version": "3.0.1",
+    "python_version": "3.12.0"
+  },
+  "timing": {
+    "total_ms": 2500.5,
+    "imports_ms": 500.0,
+    "agent_init_ms": 0.5,
+    "execution_ms": 2000.0
+  },
+  "functions": [...],
+  "response_preview": "four"
+}
+```
+
+## Profiling Layers
+
+| Layer | Overhead | Features |
+|-------|----------|----------|
+| 0 | < 1ms | Wall-clock phases only |
+| 1 | ~5% | + cProfile function stats |
+| 2 | ~15% | + Call graph (callers/callees) |
+
+- `--profile` uses Layer 1
+- `--profile --profile-deep` uses Layer 2
+
+## Performance Tips
+
+1. **Use Layer 0 for production monitoring** - minimal overhead
+2. **Use Layer 1 for development profiling** - good balance
+3. **Use Layer 2 only for deep debugging** - higher overhead
+
+## Observational Equivalence
+
+The following commands produce equivalent profile reports:
+
+```bash
+# CLI direct
+praisonai "prompt" --profile
+
+# Profile command
+praisonai profile query "prompt"
+```
+
+Both use the same unified profiling architecture and produce identical schema output.

docs/profiling-module.md

@@ -0,0 +1,257 @@
+# Profiling Module
+
+PraisonAI provides a unified profiling module for programmatic performance analysis.
+
+## Quick Start
+
+```python
+from praisonai.cli.execution import (
+    ExecutionRequest,
+    Profiler,
+    ProfilerConfig,
+)
+
+# Create execution request
+request = ExecutionRequest(prompt="What is 2+2?")
+
+# Configure profiler
+config = ProfilerConfig(layer=1)
+
+# Run with profiling
+profiler = Profiler(config)
+result, report = profiler.profile_sync(request)
+
+# Access results
+print(f"Output: {result.output}")
+print(f"Total time: {report.timing.total_ms}ms")
+```
+
+## ExecutionRequest
+
+Immutable request descriptor for execution.
+
+```python
+from praisonai.cli.execution import ExecutionRequest
+
+# Basic request
+request = ExecutionRequest(prompt="Hello")
+
+# With model
+request = ExecutionRequest(
+    prompt="Hello",
+    model="gpt-4",
+    agent_name="MyAgent",
+)
+
+# With streaming
+request = ExecutionRequest(
+    prompt="Hello",
+    stream=True,
+)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt` | str | Required | The prompt to execute |
+| `agent_name` | str | "Assistant" | Name of the agent |
+| `agent_instructions` | str | None | Custom instructions |
+| `model` | str | None | Model to use |
+| `stream` | bool | False | Enable streaming |
+| `tools` | tuple | () | Tools to provide |
+
+## ProfilerConfig
+
+Configuration for profiling behavior.
+
+```python
+from praisonai.cli.execution import ProfilerConfig
+
+# Layer 0: Wall-clock only (< 1ms overhead)
+config = ProfilerConfig(layer=0)
+
+# Layer 1: + cProfile stats (~5% overhead)
+config = ProfilerConfig(layer=1)
+
+# Layer 2: + Call graph (~15% overhead)
+config = ProfilerConfig(
+    layer=2,
+    show_callers=True,
+    show_callees=True,
+)
+
+# From CLI flags
+config = ProfilerConfig.from_flags(
+    profile=True,
+    deep=True,
+    network=False,
+)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `layer` | int | 1 | Profiling layer (0, 1, or 2) |
+| `limit` | int | 30 | Max functions to show |
+| `sort_by` | str | "cumulative" | Sort by: cumulative, time, calls |
+| `show_callers` | bool | False | Show caller functions |
+| `show_callees` | bool | False | Show callee functions |
+| `track_network` | bool | False | Track network requests |
+| `output_format` | str | "text" | Output format: text, json |
+| `save_path` | str | None | Path to save artifacts |
+
+## Profiler
+
+The main profiler class that wraps execution.
+
+```python
+from praisonai.cli.execution import Profiler, ProfilerConfig, ExecutionRequest
+
+config = ProfilerConfig(layer=1)
+profiler = Profiler(config)
+
+request = ExecutionRequest(prompt="Hello")
+result, report = profiler.profile_sync(request, invocation_method="api")
+```
+
+### Methods
+
+#### `profile_sync(request, invocation_method="profile_command")`
+
+Profile synchronous execution.
+
+**Parameters:**
+- `request`: ExecutionRequest - The execution request
+- `invocation_method`: str - How this was invoked (for report)
+
+**Returns:** Tuple of (ExecutionResult, ProfileReport)
+
+## ProfileReport
+
+The canonical profile report with timing and statistics.
+
+```python
+# Access timing breakdown
+print(f"Total: {report.timing.total_ms}ms")
+print(f"Imports: {report.timing.imports_ms}ms")
+print(f"Agent Init: {report.timing.agent_init_ms}ms")
+print(f"Execution: {report.timing.execution_ms}ms")
+
+# Access function stats (layer 1+)
+if report.functions:
+    for func in report.functions[:5]:
+        print(f"{func.name}: {func.cumulative_time_ms}ms")
+
+# Access call graph (layer 2)
+if report.call_graph:
+    print(f"Edges: {len(report.call_graph.edges)}")
+
+# Export formats
+json_str = report.to_json()
+text_str = report.to_text()
+dict_data = report.to_dict()
+```
+
+### Schema Version
+
+The report uses schema version `1.0`. Schema is frozen after release - new fields are always optional with defaults.
+
+### Mandatory Fields
+
+- `schema_version`: str
+- `run_id`: str
+- `timestamp`: str (ISO 8601)
+- `invocation`: InvocationInfo
+- `timing`: TimingBreakdown
+- `response_preview`: str
+
+### Optional Fields
+
+- `functions`: List[FunctionStat] (layer 1+)
+- `call_graph`: CallGraph (layer 2)
+- `network`: List[RequestTiming] (if track_network)
+
+## ExecutionResult
+
+Result of execution with output and metadata.
+
+```python
+# Access output
+print(result.output)
+print(result.success)
+print(result.run_id)
+
+# Check for errors
+if result.error:
+    print(f"Error: {result.error}")
+
+# Duration
+print(f"Duration: {result.duration_ms}ms")
+```
+
+## Data Bounds
+
+Profile data is strictly bounded to prevent memory issues:
+
+| Data Type | Maximum |
+|-----------|---------|
+| Function stats | 1000 |
+| Call graph edges | 5000 |
+| Network requests | 100 |
+
+## Example: Full Profiling Workflow
+
+```python
+from praisonai.cli.execution import (
+    ExecutionRequest,
+    Profiler,
+    ProfilerConfig,
+)
+
+# Configure deep profiling
+config = ProfilerConfig(
+    layer=2,
+    limit=50,
+    show_callers=True,
+    show_callees=True,
+)
+
+# Create request
+request = ExecutionRequest(
+    prompt="Explain quantum computing in simple terms",
+    model="gpt-4",
+)
+
+# Profile execution
+profiler = Profiler(config)
+result, report = profiler.profile_sync(request)
+
+# Print text report
+print(report.to_text())
+
+# Save JSON report
+with open("profile.json", "w") as f:
+    f.write(report.to_json())
+
+# Analyze timing
+print(f"\nTiming Analysis:")
+print(f"  Import overhead: {report.timing.imports_ms / report.timing.total_ms * 100:.1f}%")
+print(f"  Execution time: {report.timing.execution_ms / report.timing.total_ms * 100:.1f}%")
+
+# Top 5 hotspots
+if report.functions:
+    print(f"\nTop 5 Hotspots:")
+    for func in report.functions[:5]:
+        print(f"  {func.name}: {func.cumulative_time_ms:.2f}ms ({func.calls} calls)")
+```
+
+## Invariants
+
+The profiling module guarantees:
+
+1. **Output Equivalence**: Profiled execution produces identical output to non-profiled execution
+2. **Schema Stability**: Schema version 1.0 is frozen; new fields are always optional
+3. **Bounded Data**: All profile data respects maximum bounds
+4. **Zero Overhead When Disabled**: No profiling code runs unless explicitly enabled

examples/background/basic_background.py

@@ -2,10 +2,10 @@
 """
 Basic Background Tasks Example for PraisonAI Agents.
 
-This example demonstrates how to use the background task system to:
-1. Run tasks asynchronously
-2. Track task progress
-3. Cancel running tasks
+This example demonstrates how to use the background task system with Agent:
+1. Create an Agent with background task support
+2. Run agent tasks asynchronously
+3. Track task progress
 4. Handle task completion
 
 Usage:
@@ -13,74 +13,77 @@ Usage:
 """
 
 import asyncio
-import time
-
+from praisonaiagents import Agent
 from praisonaiagents.background import BackgroundRunner, BackgroundConfig, TaskStatus
 
 
 async def main():
     print("=" * 60)
-    print("Background Tasks Demo")
+    print("Agent-Centric Background Tasks Demo")
     print("=" * 60)
     
     # Create a background runner with config
-    config = BackgroundConfig(max_concurrent_tasks=3)
-    runner = BackgroundRunner(config=config)
+    runner = BackgroundRunner(config=BackgroundConfig(max_concurrent_tasks=3))
+    
+    # Create an Agent with background task support
+    agent = Agent(
+        name="AsyncAssistant",
+        instructions="You are a helpful research assistant.",
+        background=runner
+    )
+    
+    print("\n--- Agent with Background Support Created ---")
+    print(f"Agent: {agent.name}")
+    print(f"Background runner: {agent.background is not None}")
     
     # Define some example tasks
-    def slow_task(duration: float, name: str) -> str:
-        """A slow task that simulates work."""
-        print(f"  🔄 Task '{name}' starting (will take {duration}s)")
-        time.sleep(duration)
-        return f"Task '{name}' completed after {duration}s"
+    async def research_task(topic: str) -> str:
+        """Simulate a research task."""
+        print(f"  🔄 Researching '{topic}'...")
+        await asyncio.sleep(1.5)
+        return f"Research on '{topic}' completed with 5 key findings"
     
-    async def async_task(duration: float, name: str) -> str:
-        """An async task that simulates work."""
-        print(f"  🔄 Async task '{name}' starting (will take {duration}s)")
-        await asyncio.sleep(duration)
-        return f"Async task '{name}' completed after {duration}s"
+    async def analysis_task(data: str) -> str:
+        """Simulate an analysis task."""
+        print(f"  🔄 Analyzing data...")
+        await asyncio.sleep(1.0)
+        return f"Analysis complete: {data}"
     
-    # Submit tasks
-    print("\n--- Submitting Tasks ---")
+    # Submit tasks via agent's background runner
+    print("\n--- Submitting Background Tasks ---")
     
-    task1 = await runner.submit(slow_task, args=(1.0, "quick-job"), name="task1")
-    print(f"✅ Submitted task 1: {task1.id[:8]}")
+    task1 = await agent.background.submit(
+        research_task, 
+        args=("AI trends 2025",), 
+        name="research_ai"
+    )
+    print(f"✅ Submitted research task: {task1.id[:8]}")
     
-    task2 = await runner.submit(slow_task, args=(2.0, "medium-job"), name="task2")
-    print(f"✅ Submitted task 2: {task2.id[:8]}")
-    
-    task3 = await runner.submit(async_task, args=(1.5, "async-job"), name="task3")
-    print(f"✅ Submitted async task 3: {task3.id[:8]}")
+    task2 = await agent.background.submit(
+        analysis_task, 
+        args=("market data",), 
+        name="analyze_market"
+    )
+    print(f"✅ Submitted analysis task: {task2.id[:8]}")
     
     # List all tasks
     print("\n--- Task Status ---")
-    for task in runner.tasks:
+    for task in agent.background.tasks:
         print(f"  [{task.id[:8]}] {task.status.value}")
     
-    # Wait for task 1 to complete
-    print("\n--- Waiting for Task 1 ---")
-    await task1.wait(timeout=5.0)
-    print(f"✅ Task 1 result: {task1.result}")
-    
-    # Check status of all tasks
-    print("\n--- Updated Task Status ---")
-    for task in [task1, task2, task3]:
-        status = "✅" if task.status == TaskStatus.COMPLETED else "🔄"
-        print(f"  {status} [{task.id[:8]}] {task.status.value}")
-    
-    # Wait for all remaining tasks
-    print("\n--- Waiting for All Tasks ---")
+    # Wait for tasks to complete
+    print("\n--- Waiting for Tasks ---")
+    await task1.wait(timeout=10.0)
     await task2.wait(timeout=10.0)
-    await task3.wait(timeout=10.0)
     
-    # Final status
-    print("\n--- Final Results ---")
-    for task in [task1, task2, task3]:
-        if task.result:
-            print(f"  ✅ {task.result}")
+    # Final results
+    print("\n--- Results ---")
+    for task in [task1, task2]:
+        status = "✅" if task.status == TaskStatus.COMPLETED else "❌"
+        print(f"  {status} {task.result}")
     
     # Cleanup
-    runner.clear_completed()
+    agent.background.clear_completed()
     print("\n✅ Cleared completed tasks")
     
     print("\n" + "=" * 60)

examples/benchmark/benchmark_example.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Benchmark Example
+
+This example demonstrates how to use the benchmark system programmatically
+to compare performance across different execution paths.
+
+Usage:
+    python benchmark_example.py
+    
+Requirements:
+    - OPENAI_API_KEY environment variable set
+    - praisonai package installed
+"""
+
+import os
+import sys
+
+# Ensure the package is importable
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai'))
+
+from praisonai.cli.features.benchmark import BenchmarkHandler, BenchmarkReport
+
+
+def run_quick_comparison():
+    """Run a quick comparison of key execution paths."""
+    print("=" * 60)
+    print("Quick Benchmark Comparison")
+    print("=" * 60)
+    
+    handler = BenchmarkHandler()
+    
+    # Run benchmark with 2 iterations on key paths
+    report = handler.run_full_benchmark(
+        prompt="What is 2+2?",
+        iterations=2,
+        paths=["openai_sdk", "praisonai_agent"],
+        verbose=True
+    )
+    
+    # Print comparison table
+    print("\n" + handler.create_comparison_table(report))
+    
+    return report
+
+
+def run_full_benchmark():
+    """Run full benchmark suite across all paths."""
+    print("=" * 60)
+    print("Full Benchmark Suite")
+    print("=" * 60)
+    
+    handler = BenchmarkHandler()
+    
+    # Run full benchmark
+    report = handler.run_full_benchmark(
+        prompt="Hi",
+        iterations=3,
+        verbose=True
+    )
+    
+    # Print full report
+    handler.print_report(report)
+    
+    return report
+
+
+def run_agent_benchmark():
+    """Benchmark PraisonAI Agent specifically."""
+    print("=" * 60)
+    print("Agent Benchmark")
+    print("=" * 60)
+    
+    handler = BenchmarkHandler()
+    
+    # Benchmark agent vs SDK
+    report = handler.run_full_benchmark(
+        prompt="Explain Python in one sentence",
+        iterations=3,
+        paths=["openai_sdk", "praisonai_agent"],
+        verbose=True
+    )
+    
+    # Show timeline diagrams
+    for name, result in report.results.items():
+        print(f"\n### {name}")
+        print(handler.create_timeline_diagram(result))
+    
+    # Show variance analysis
+    print(handler.create_variance_table(report))
+    
+    return report
+
+
+def save_benchmark_results(report: BenchmarkReport, output_path: str):
+    """Save benchmark results to JSON file."""
+    import json
+    
+    with open(output_path, 'w') as f:
+        json.dump(report.to_dict(), f, indent=2)
+    
+    print(f"\nResults saved to: {output_path}")
+
+
+def main():
+    """Main entry point."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="PraisonAI Benchmark Example")
+    parser.add_argument(
+        "--mode",
+        choices=["quick", "full", "agent"],
+        default="quick",
+        help="Benchmark mode: quick (2 paths), full (all paths), agent (agent focus)"
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        help="Output JSON file path"
+    )
+    
+    args = parser.parse_args()
+    
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Error: OPENAI_API_KEY environment variable not set")
+        sys.exit(1)
+    
+    # Run selected benchmark
+    if args.mode == "quick":
+        report = run_quick_comparison()
+    elif args.mode == "full":
+        report = run_full_benchmark()
+    elif args.mode == "agent":
+        report = run_agent_benchmark()
+    
+    # Save results if requested
+    if args.output:
+        save_benchmark_results(report, args.output)
+    
+    print("\n✅ Benchmark complete!")
+
+
+if __name__ == "__main__":
+    main()

examples/checkpoints/basic_checkpoints.py

@@ -2,10 +2,10 @@
 """
 Basic Checkpoints Example for PraisonAI Agents.
 
-This example demonstrates how to use the shadow git checkpointing system to:
-1. Save checkpoints before making changes
-2. List available checkpoints
-3. View diffs between checkpoints
+This example demonstrates how to use the shadow git checkpointing system with Agent:
+1. Create an Agent with checkpoint support
+2. Save checkpoints before making changes
+3. List available checkpoints
 4. Restore to a previous checkpoint
 
 Usage:
@@ -16,6 +16,7 @@ import asyncio
 import tempfile
 from pathlib import Path
 
+from praisonaiagents import Agent
 from praisonaiagents.checkpoints import CheckpointService
 
 
@@ -23,7 +24,7 @@ async def main():
     # Create a temporary workspace for demonstration
     with tempfile.TemporaryDirectory() as workspace:
         print("=" * 60)
-        print("Shadow Git Checkpointing Demo")
+        print("Agent-Centric Checkpointing Demo")
         print("=" * 60)
         print(f"\nWorkspace: {workspace}")
         
@@ -32,24 +33,35 @@ async def main():
         test_file.write_text("# Initial content\nprint('Hello, World!')\n")
         print(f"\n✅ Created initial file: {test_file.name}")
         
-        # Initialize the checkpoint service
-        service = CheckpointService(workspace_dir=workspace)
+        # Create checkpoint service
+        checkpoints = CheckpointService(workspace_dir=workspace)
+        
+        # Create an Agent with checkpoint support
+        agent = Agent(
+            name="RefactorBot",
+            instructions="You are a code refactoring assistant.",
+            checkpoints=checkpoints
+        )
+        
+        print("\n--- Agent with Checkpoint Support Created ---")
+        print(f"Agent: {agent.name}")
+        print(f"Checkpoints enabled: {agent.checkpoints is not None}")
         
         try:
             # Initialize the shadow git repository
             print("\n--- Initializing Checkpoint Service ---")
-            await service.initialize()
+            await agent.checkpoints.initialize()
             print("✅ Shadow git repository initialized")
             
             # Save first checkpoint
             print("\n--- Saving Checkpoint 1: Initial State ---")
-            result1 = await service.save("Initial state")
+            result1 = await agent.checkpoints.save("Initial state")
             print(f"✅ Checkpoint saved: {result1.checkpoint.id[:8]}")
             print(f"   Message: {result1.checkpoint.message}")
             
-            # Make some changes
-            print("\n--- Making Changes ---")
-            test_file.write_text("# Modified content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
+            # Make some changes (simulating agent modifications)
+            print("\n--- Simulating Agent Changes ---")
+            test_file.write_text("# Refactored content\nprint('Hello, PraisonAI!')\nprint('Checkpoints are awesome!')\n")
             print("✅ Modified example.py")
             
             # Create a new file
@@ -58,38 +70,32 @@ async def main():
             print("✅ Created utils.py")
             
             # Save second checkpoint
-            print("\n--- Saving Checkpoint 2: After Changes ---")
-            result2 = await service.save("Added features")
+            print("\n--- Saving Checkpoint 2: After Refactoring ---")
+            result2 = await agent.checkpoints.save("Added features")
             print(f"✅ Checkpoint saved: {result2.checkpoint.id[:8]}")
             
             # List all checkpoints
             print("\n--- Listing All Checkpoints ---")
-            checkpoints = await service.list_checkpoints()
-            for i, cp in enumerate(checkpoints, 1):
-                print(f"  {i}. [{cp.id[:8]}] {cp.message} ({cp.timestamp})")
+            checkpoints_list = await agent.checkpoints.list_checkpoints()
+            for i, cp in enumerate(checkpoints_list, 1):
+                print(f"  {i}. [{cp.id[:8]}] {cp.message}")
             
             # Show diff
-            print("\n--- Current Diff (uncommitted changes) ---")
-            diff = await service.diff()
+            print("\n--- Current Diff ---")
+            diff = await agent.checkpoints.diff()
             if diff.files:
                 for f in diff.files:
                     print(f"  {f.status}: {f.path}")
             else:
                 print("  No uncommitted changes")
             
-            # Make more changes to show diff
-            test_file.write_text("# Even more changes\nprint('This will be reverted')\n")
-            print("\n✅ Made more changes to example.py")
-            
-            diff = await service.diff()
-            print("\n--- New Diff ---")
-            if diff.files:
-                for f in diff.files:
-                    print(f"  {f.status}: {f.path}")
+            # Make more changes
+            test_file.write_text("# Bad changes\nprint('This will be reverted')\n")
+            print("\n✅ Made problematic changes to example.py")
             
             # Restore to checkpoint 2
             print(f"\n--- Restoring to Checkpoint: {result2.checkpoint.id[:8]} ---")
-            await service.restore(result2.checkpoint.id)
+            await agent.checkpoints.restore(result2.checkpoint.id)
             print("✅ Restored successfully!")
             
             # Verify restoration

examples/compaction/basic_compaction.py

@@ -2,140 +2,114 @@
 """
 Basic Context Compaction Example for PraisonAI Agents.
 
-This example demonstrates how to use context compaction to:
-1. Manage conversation context length
-2. Use different compaction strategies
-3. Track compaction results
-4. Preserve important messages
+This example demonstrates how to use context compaction with Agent:
+1. Create an Agent with context= parameter for compaction
+2. Use different compaction strategies via ManagerConfig
+3. Monitor compaction results
 
 Usage:
     python basic_compaction.py
 """
 
-from praisonaiagents.compaction import (
-    ContextCompactor, CompactionConfig, CompactionStrategy, CompactionResult
-)
+from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig
 
 
 def main():
     print("=" * 60)
-    print("Context Compaction Demo")
+    print("Agent-Centric Context Compaction Demo")
     print("=" * 60)
     
     # ==========================================================================
-    # Sample Messages
+    # Available Strategies
     # ==========================================================================
-    messages = [
-        {"role": "system", "content": "You are a helpful AI assistant."},
-        {"role": "user", "content": "Hello! Can you help me with Python?"},
-        {"role": "assistant", "content": "Of course! I'd be happy to help you with Python. What would you like to know?"},
-        {"role": "user", "content": "How do I read a file in Python?"},
-        {"role": "assistant", "content": "To read a file in Python, you can use the built-in open() function. Here's an example:\n\nwith open('filename.txt', 'r') as f:\n    content = f.read()\n\nThis opens the file, reads its content, and automatically closes it."},
-        {"role": "user", "content": "What about writing to a file?"},
-        {"role": "assistant", "content": "To write to a file, use the 'w' mode:\n\nwith open('filename.txt', 'w') as f:\n    f.write('Hello, World!')\n\nUse 'a' mode to append instead of overwriting."},
-        {"role": "user", "content": "Can you explain list comprehensions?"},
-        {"role": "assistant", "content": "List comprehensions are a concise way to create lists. Instead of:\n\nresult = []\nfor x in range(10):\n    result.append(x * 2)\n\nYou can write:\n\nresult = [x * 2 for x in range(10)]"},
+    print("\n--- Available Compaction Strategies ---")
+    
+    strategies = [
+        ("truncate", "Remove oldest messages first"),
+        ("sliding_window", "Keep most recent messages within limit"),
+        ("summarize", "Replace old messages with summary"),
+        ("smart", "Intelligently select messages to keep"),
     ]
     
-    print(f"\n--- Original Messages ---")
-    print(f"  Message count: {len(messages)}")
+    for name, desc in strategies:
+        print(f"  {name}: {desc}")
     
     # ==========================================================================
-    # Basic Compaction
+    # Agent with Context Compaction via context= param
     # ==========================================================================
-    print("\n--- Basic Compaction (Truncate Strategy) ---")
+    print("\n--- Creating Agent with Context Compaction ---")
     
-    compactor = ContextCompactor(
-        max_tokens=50,  # Low limit to trigger compaction
-        strategy=CompactionStrategy.TRUNCATE,
-        preserve_system=True,
-        preserve_recent=2
+    # Use context= parameter with ManagerConfig for compaction
+    agent = Agent(
+        name="LongChat",
+        instructions="You are a helpful assistant for extended conversations.",
+        context=ManagerConfig(
+            auto_compact=True,
+            compact_threshold=0.8,
+            strategy="sliding_window",
+        )
     )
     
-    # Check stats before
-    stats = compactor.get_stats(messages)
-    print(f"  Total tokens: {stats['total_tokens']}")
-    print(f"  Max tokens: {stats['max_tokens']}")
-    print(f"  Needs compaction: {stats['needs_compaction']}")
-    
-    # Compact
-    compacted, result = compactor.compact(messages)
-    
-    print(f"\n  After compaction:")
-    print(f"    Messages: {len(messages)} -> {len(compacted)}")
-    print(f"    Tokens: {result.original_tokens} -> {result.compacted_tokens}")
-    print(f"    Saved: {result.tokens_saved} tokens")
-    print(f"    Compression: {result.compression_ratio:.1%}")
+    print(f"Agent: {agent.name}")
+    print(f"Context manager: {agent.context_manager is not None}")
+    if agent.context_manager:
+        print(f"Auto-compact: {agent.context_manager.config.auto_compact}")
+        print(f"Threshold: {agent.context_manager.config.compact_threshold}")
+        print(f"Strategy: {agent.context_manager.config.strategy}")
     
     # ==========================================================================
-    # Sliding Window Strategy
+    # Different Strategy Examples via context= param
     # ==========================================================================
-    print("\n--- Sliding Window Strategy ---")
+    print("\n--- Strategy Examples ---")
     
-    compactor = ContextCompactor(
-        max_tokens=50,
-        strategy=CompactionStrategy.SLIDING,
-        preserve_system=True,
-        preserve_recent=3
+    # Sliding window strategy
+    sliding_agent = Agent(
+        name="SlidingAgent",
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="sliding_window",
+        )
     )
+    print(f"  Sliding: strategy={sliding_agent.context_manager.config.strategy}")
     
-    compacted, result = compactor.compact(messages)
-    
-    print(f"  Messages kept: {result.messages_kept}")
-    print(f"  Messages removed: {result.messages_removed}")
-    print(f"  Strategy: {result.strategy_used.value}")
-    
-    # ==========================================================================
-    # Summarize Strategy
-    # ==========================================================================
-    print("\n--- Summarize Strategy ---")
-    
-    compactor = ContextCompactor(
-        max_tokens=50,
-        strategy=CompactionStrategy.SUMMARIZE,
-        preserve_system=True,
-        preserve_recent=2
+    # Summarize strategy
+    summarize_agent = Agent(
+        name="SummarizeAgent",
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="summarize",
+        )
     )
+    print(f"  Summarize: strategy={summarize_agent.context_manager.config.strategy}")
     
-    compacted, result = compactor.compact(messages)
-    
-    print(f"  Messages kept: {result.messages_kept}")
-    print(f"  Strategy: {result.strategy_used.value}")
-    
-    # Show what messages remain
-    print(f"\n  Remaining message roles:")
-    for msg in compacted:
-        role = msg.get("role", "unknown")
-        content_preview = msg.get("content", "")[:50]
-        print(f"    [{role}] {content_preview}...")
-    
-    # ==========================================================================
-    # No Compaction Needed
-    # ==========================================================================
-    print("\n--- No Compaction Needed ---")
-    
-    compactor = ContextCompactor(
-        max_tokens=10000,  # High limit
-        strategy=CompactionStrategy.TRUNCATE
+    # Smart strategy
+    smart_agent = Agent(
+        name="SmartAgent",
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="smart",
+        )
     )
-    
-    compacted, result = compactor.compact(messages)
-    
-    print(f"  Was compacted: {result.was_compacted}")
-    print(f"  Messages unchanged: {len(compacted) == len(messages)}")
+    print(f"  Smart: strategy={smart_agent.context_manager.config.strategy}")
     
     # ==========================================================================
-    # Result Serialization
+    # Context Manager Stats Demo
     # ==========================================================================
-    print("\n--- Result Serialization ---")
+    print("\n--- Context Manager Stats Demo ---")
     
-    compactor = ContextCompactor(max_tokens=50)
-    _, result = compactor.compact(messages)
-    
-    data = result.to_dict()
-    print(f"  Original tokens: {data['original_tokens']}")
-    print(f"  Compacted tokens: {data['compacted_tokens']}")
-    print(f"  Compression ratio: {data['compression_ratio']:.2f}")
+    # Access context manager stats
+    if agent.context_manager:
+        stats = agent.context_manager.get_stats()
+        print(f"  Model: {stats.get('model', 'N/A')}")
+        print(f"  Model limit: {stats.get('model_limit', 'N/A')}")
+        print(f"  Output reserve: {stats.get('output_reserve', 'N/A')}")
+        print(f"  Usable budget: {stats.get('usable_budget', 'N/A')}")
+    else:
+        print("  Context manager not initialized")
     
     print("\n" + "=" * 60)
     print("Demo Complete!")

examples/context/00_agent_fast_context_basic.py

@@ -1,87 +1,72 @@
 """
-Fast Context with Agent - Basic Example
+Fast Context - Basic Example
 
-This is the simplest way to use Fast Context with an Agent.
-Just set fast_context=True and the agent will automatically
-have access to rapid code search capabilities.
+FastContext provides rapid code search capabilities.
+Use it directly from the context module for code search.
 
-Fast Context provides:
+FastContext provides:
 - 10-20x faster code search than traditional methods
 - Parallel execution (8 concurrent searches)
 - Automatic caching for repeated queries
-- Seamless integration with Agent workflows
+
+Note: FastContext is now accessed via the context module directly,
+not as Agent parameters. For context management with agents,
+use Agent(context=True) or Agent(context=ManagerConfig(...)).
 """
 
 from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig
 
 def main():
     print("=" * 60)
-    print("Agent with Fast Context - Basic Example")
+    print("Agent with Context Management - Basic Example")
     print("=" * 60)
     
-    # Create an agent with Fast Context enabled
-    # This is the simplest configuration
+    # Create an agent with context management enabled
+    # This is the recommended way to use context features
     agent = Agent(
         name="CodeAssistant",
         instructions="You are a helpful code assistant.",
-        fast_context=True,  # Enable Fast Context
-        fast_context_path=".",  # Search in current directory
+        context=True,  # Enable context management with defaults
         verbose=False
     )
     
-    print("\n✓ Agent created with Fast Context enabled")
-    print(f"  - fast_context_enabled: {agent.fast_context_enabled}")
-    print(f"  - fast_context_path: {agent.fast_context_path}")
-    print(f"  - fast_context_model: {agent.fast_context_model}")
+    print("\n✓ Agent created with context management enabled")
+    print(f"  - context_manager: {agent.context_manager is not None}")
+    if agent.context_manager:
+        print(f"  - auto_compact: {agent.context_manager.config.auto_compact}")
+        print(f"  - strategy: {agent.context_manager.config.strategy}")
     
-    # Use delegate_to_fast_context to search code
+    # For FastContext code search, use the module directly
     print("\n" + "-" * 60)
-    print("Searching for 'class Agent' in the codebase...")
+    print("Using FastContext for code search...")
     print("-" * 60)
     
-    context = agent.delegate_to_fast_context("class Agent")
-    
-    if context:
-        print(f"\n✓ Found relevant code!")
-        print(f"  Context length: {len(context)} characters")
-        print("\nPreview of found context:")
-        print("-" * 40)
-        # Show first 500 characters
-        preview = context[:500]
-        print(preview)
-        if len(context) > 500:
-            print("...")
-    else:
-        print("\n✗ No relevant code found")
-    
-    # Another search example
-    print("\n" + "-" * 60)
-    print("Searching for 'def chat' in the codebase...")
-    print("-" * 60)
-    
-    context = agent.delegate_to_fast_context("def chat")
-    
-    if context:
-        print(f"\n✓ Found relevant code!")
-        print(f"  Context length: {len(context)} characters")
-    else:
-        print("\n✗ No relevant code found")
-    
-    # Access FastContext directly for more control
-    print("\n" + "-" * 60)
-    print("Direct FastContext access for advanced usage...")
-    print("-" * 60)
-    
-    fc = agent.fast_context
-    if fc:
-        result = fc.search("import")
-        print(f"\n✓ Direct search for 'import':")
+    try:
+        from praisonaiagents.context.fast import FastContext
+        
+        fc = FastContext(
+            workspace_path=".",
+            model="gpt-4o-mini",
+            max_turns=4,
+            max_parallel=8,
+        )
+        
+        result = fc.search("class Agent")
+        print(f"\n✓ Search for 'class Agent':")
         print(f"  Files found: {result.total_files}")
         print(f"  Search time: {result.search_time_ms}ms")
-        print(f"  From cache: {result.from_cache}")
+        
+        if result.total_files > 0:
+            context = fc.get_context_for_agent("class Agent")
+            print(f"  Context length: {len(context)} characters")
+    except ImportError:
+        print("\n⚠ FastContext not available (optional feature)")
+    except Exception as e:
+        print(f"\n⚠ FastContext search failed: {e}")
     
     print("\n" + "=" * 60)
-    print("Fast Context makes code search instant for your agents!")
+    print("Context management is now unified via context= param!")
     print("=" * 60)
 
 

examples/context/04_agent_integration.py

@@ -1,103 +1,98 @@
 """
-Example 4: Agent Integration with Fast Context
+Example 4: Agent Integration with Context Management
 
-This example shows how to use Fast Context integrated with the Agent class
-for automatic code search delegation.
+This example shows how to use context management with the Agent class.
+Context management is now unified via the context= parameter.
 
 Benefits:
 - Seamless integration with existing Agent workflows
-- Automatic context injection for code-related queries
-- Configurable via Agent parameters or environment variables
+- Automatic token tracking and optimization
+- Configurable via context= parameter with ManagerConfig
 """
 
 from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig
 
 WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
 
 
 def main():
     print("=" * 70)
-    print("Agent Integration with Fast Context")
+    print("Agent Integration with Context Management")
     print("=" * 70)
     
-    # Create an agent with Fast Context enabled
-    print("\n1. Creating Agent with Fast Context")
+    # Create an agent with context management enabled
+    print("\n1. Creating Agent with Context Management")
     print("-" * 40)
     
+    config = ManagerConfig(
+        auto_compact=True,
+        compact_threshold=0.8,
+        strategy="smart",
+        monitor_enabled=True,
+        monitor_path="./context_debug.txt",
+    )
+    
     agent = Agent(
         name="CodeAssistant",
-        instructions="You are a helpful code assistant that can search and analyze code.",
-        fast_context=True,
-        fast_context_path=WORKSPACE,
-        fast_context_model="gpt-4o-mini",
-        fast_context_max_turns=4,
-        fast_context_parallelism=8,
-        fast_context_timeout=30.0,
+        instructions="You are a helpful code assistant.",
+        context=config,
         verbose=False
     )
     
     print(f"   Agent name: {agent.name}")
-    print(f"   Fast Context enabled: {agent.fast_context_enabled}")
-    print(f"   Fast Context path: {agent.fast_context_path}")
-    print(f"   Fast Context model: {agent.fast_context_model}")
-    print(f"   Max turns: {agent.fast_context_max_turns}")
-    print(f"   Parallelism: {agent.fast_context_parallelism}")
+    print(f"   Context manager: {agent.context_manager is not None}")
+    if agent.context_manager:
+        print(f"   Auto-compact: {agent.context_manager.config.auto_compact}")
+        print(f"   Threshold: {agent.context_manager.config.compact_threshold}")
+        print(f"   Strategy: {agent.context_manager.config.strategy}")
     
-    # Use delegate_to_fast_context for code search
-    print("\n2. Delegating Code Search to Fast Context")
+    # For FastContext code search, use the module directly
+    print("\n2. Using FastContext for Code Search")
     print("-" * 40)
     
-    queries = [
-        "find the Agent class definition",
-        "search for authentication handlers",
-        "locate memory management code",
-    ]
-    
-    for query in queries:
-        print(f"\n   Query: '{query}'")
-        context = agent.delegate_to_fast_context(query)
+    try:
+        from praisonaiagents.context.fast import FastContext
         
-        if context:
-            # Show preview of context
-            lines = context.split('\n')
-            preview_lines = lines[:5]
-            print(f"   Found context ({len(context)} chars):")
-            for line in preview_lines:
-                print(f"      {line[:60]}{'...' if len(line) > 60 else ''}")
-            if len(lines) > 5:
-                print(f"      ... and {len(lines) - 5} more lines")
-        else:
-            print("   No relevant code found")
-    
-    # Access the FastContext instance directly
-    print("\n3. Direct FastContext Access")
-    print("-" * 40)
-    
-    fc = agent.fast_context
-    if fc:
-        result = fc.search("def chat")
-        print(f"   Direct search for 'def chat':")
-        print(f"   Files found: {result.total_files}")
-        print(f"   Search time: {result.search_time_ms}ms")
+        fc = FastContext(
+            workspace_path=WORKSPACE,
+            model="gpt-4o-mini",
+            max_turns=4,
+            max_parallel=8,
+            timeout=30.0,
+        )
         
-        for f in result.files[:3]:
-            print(f"   - {f.path}")
+        queries = [
+            "find the Agent class definition",
+            "search for chat method",
+        ]
+        
+        for query in queries:
+            print(f"\n   Query: '{query}'")
+            result = fc.search(query)
+            print(f"   Files found: {result.total_files}")
+            print(f"   Search time: {result.search_time_ms}ms")
+            
+    except ImportError:
+        print("   FastContext not available (optional feature)")
+    except Exception as e:
+        print(f"   FastContext error: {e}")
     
     # Show configuration options
-    print("\n4. Configuration Options")
+    print("\n3. Configuration Options")
     print("-" * 40)
     
-    print("   Agent parameters:")
-    print("   - fast_context=True              # Enable Fast Context")
-    print("   - fast_context_path='.'          # Workspace path")
-    print("   - fast_context_model='gpt-4o-mini'  # Search model")
-    print("   - fast_context_max_turns=4       # Max search turns")
-    print("   - fast_context_parallelism=8     # Parallel calls")
-    print("   - fast_context_timeout=30.0      # Timeout (seconds)")
+    print("   Agent context= parameter:")
+    print("   - context=True                   # Enable with defaults")
+    print("   - context=ManagerConfig(...)     # Custom configuration")
+    print("   - context=False                  # Disabled (default)")
     
-    print("\n   Environment variables:")
-    print("   - FAST_CONTEXT_MODEL")
-    print("   - FAST_CONTEXT_MAX_TURNS")
+    print("\n   ManagerConfig options:")
+    print("   - auto_compact=True              # Auto-optimize context")
+    print("   - compact_threshold=0.8          # Trigger at 80%")
+    print("   - strategy='smart'               # Optimization strategy")
+    print("   - monitor_enabled=True           # Write snapshots")
+    print("   - monitor_path='./context.txt'   # Snapshot path")
     print("   - FAST_CONTEXT_PARALLELISM")
     print("   - FAST_CONTEXT_TIMEOUT")
     print("   - FAST_CONTEXT_CACHE")

examples/context/09_context_budgeting.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Context Budgeting Example
+
+Demonstrates how to use context budgeting with Agent via context= param,
+and also shows low-level ContextBudgeter usage for advanced scenarios.
+
+Agent-Centric Quick Start:
+    from praisonaiagents import Agent
+    from praisonaiagents.context import ManagerConfig
+    
+    agent = Agent(
+        instructions="You are helpful.",
+        context=ManagerConfig(output_reserve=16000),  # Custom output reserve
+    )
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import (
+    ManagerConfig,
+    ContextBudgeter,
+    BudgetAllocation,
+    get_model_limit,
+    get_output_reserve,
+)
+
+
+def agent_centric_example():
+    """Agent-centric usage - recommended approach."""
+    print("=" * 60)
+    print("Agent-Centric Context Budgeting")
+    print("=" * 60)
+    
+    # Simple: Enable context management with defaults
+    agent = Agent(
+        instructions="You are a helpful assistant.",
+        context=True,
+    )
+    print(f"Agent with context=True created")
+    print(f"Context manager: {agent.context_manager is not None}")
+    
+    # Custom: Specify output reserve
+    agent2 = Agent(
+        instructions="You are a code assistant.",
+        context=ManagerConfig(output_reserve=16000),
+    )
+    print(f"Agent with custom output_reserve created")
+    if agent2.context_manager:
+        stats = agent2.context_manager.get_stats()
+        print(f"Output reserve: {stats.get('output_reserve', 'N/A')}")
+
+
+def main():
+    print("=" * 60)
+    print("Context Budgeting Example")
+    print("=" * 60)
+    
+    # Example 1: Basic budget allocation for GPT-4o-mini
+    print("\n1. Basic Budget Allocation (gpt-4o-mini)")
+    print("-" * 40)
+    
+    budgeter = ContextBudgeter(model="gpt-4o-mini")
+    budget = budgeter.allocate()
+    
+    print(f"Model: gpt-4o-mini")
+    print(f"Model Limit: {budget.model_limit:,} tokens")
+    print(f"Output Reserve: {budget.output_reserve:,} tokens")
+    print(f"Usable Context: {budget.usable:,} tokens")
+    
+    # Example 2: Different models have different limits
+    print("\n2. Model Comparison")
+    print("-" * 40)
+    
+    models = ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo", "claude-3-opus", "gemini-1.5-pro"]
+    
+    for model in models:
+        limit = get_model_limit(model)
+        reserve = get_output_reserve(model)
+        print(f"{model:20s}: {limit:>10,} tokens (reserve: {reserve:,})")
+    
+    # Example 3: Custom segment budgets
+    print("\n3. Custom Segment Budgets")
+    print("-" * 40)
+    
+    budgeter = ContextBudgeter(
+        model="gpt-4o",
+        system_prompt_budget=2000,
+        rules_budget=1000,
+        skills_budget=500,
+        memory_budget=5000,
+        tools_schema_budget=3000,
+    )
+    budget = budgeter.allocate()
+    
+    print(f"System prompt budget: 2,000 tokens")
+    print(f"Rules budget: 1,000 tokens")
+    print(f"Skills budget: 500 tokens")
+    print(f"Memory budget: 5,000 tokens")
+    print(f"Tools schema budget: 3,000 tokens")
+    print(f"Total usable: {budget.usable:,} tokens")
+    
+    # Example 4: Check for overflow
+    print("\n4. Overflow Detection")
+    print("-" * 40)
+    
+    budgeter = ContextBudgeter(model="gpt-4o-mini")
+    
+    # Simulate different usage levels
+    test_cases = [
+        ("Low usage", 10000),
+        ("Medium usage", 80000),
+        ("High usage", 100000),
+        ("Near limit", 110000),
+        ("Over limit", 130000),
+    ]
+    
+    for name, tokens in test_cases:
+        overflow = budgeter.check_overflow(tokens)
+        utilization = budgeter.get_utilization(tokens)
+        remaining = budgeter.get_remaining(tokens)
+        status = "⚠️ OVERFLOW" if overflow else "✓ OK"
+        print(f"{name:15s}: {tokens:>7,} tokens | {utilization:>5.1%} | {status}")
+    
+    # Example 5: Budget to dict for serialization
+    print("\n5. Budget Serialization")
+    print("-" * 40)
+    
+    budget_dict = budgeter.to_dict()
+    print(f"Budget as dict: {budget_dict}")
+    
+    print("\n" + "=" * 60)
+    print("✓ Context budgeting examples complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/10_context_monitoring.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Context Monitoring Example
+
+Demonstrates how to use context monitoring with Agent via context= param,
+and also shows low-level ContextMonitor usage for advanced scenarios.
+
+Agent-Centric Quick Start:
+    from praisonaiagents import Agent
+    from praisonaiagents.context import ManagerConfig
+    
+    agent = Agent(
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            monitor_enabled=True,
+            monitor_path="./debug/context.json",
+        ),
+    )
+"""
+
+import os
+import tempfile
+from praisonaiagents import Agent
+from praisonaiagents.context import (
+    ManagerConfig,
+    ContextMonitor,
+    ContextLedger,
+    BudgetAllocation,
+    format_human_snapshot,
+    format_json_snapshot,
+    redact_sensitive,
+    ContextSnapshot,
+)
+
+
+def agent_centric_example():
+    """Agent-centric usage - recommended approach."""
+    print("=" * 60)
+    print("Agent-Centric Context Monitoring")
+    print("=" * 60)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        monitor_path = os.path.join(tmpdir, "context.json")
+        
+        agent = Agent(
+            instructions="You are a helpful assistant.",
+            context=ManagerConfig(
+                monitor_enabled=True,
+                monitor_path=monitor_path,
+                monitor_format="json",
+            ),
+        )
+        print(f"Agent with monitoring enabled")
+        print(f"Monitor path: {monitor_path}")
+        print(f"Context manager: {agent.context_manager is not None}")
+
+
+def main():
+    print("=" * 60)
+    print("Context Monitoring Example")
+    print("=" * 60)
+    
+    # Sample conversation for demonstration
+    messages = [
+        {"role": "system", "content": "You are a helpful AI assistant."},
+        {"role": "user", "content": "What is the weather like today?"},
+        {"role": "assistant", "content": "I don't have access to real-time weather data."},
+        {"role": "user", "content": "Can you help me write Python code?"},
+        {"role": "assistant", "content": "Of course! I'd be happy to help with Python."},
+    ]
+    
+    # Example 1: Basic monitoring setup
+    print("\n1. Basic Monitor Setup")
+    print("-" * 40)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        context_path = os.path.join(tmpdir, "context.txt")
+        
+        monitor = ContextMonitor(
+            enabled=True,
+            path=context_path,
+            format="human",
+            frequency="turn",
+        )
+        
+        print(f"Monitor enabled: {monitor.enabled}")
+        print(f"Output path: {context_path}")
+        print(f"Format: {monitor.format}")
+        
+        # Create sample ledger and budget
+        ledger = ContextLedger(
+            system_prompt=500,
+            history=2500,
+            tools_schema=300,
+            tool_outputs=1200,
+        )
+        
+        budget = BudgetAllocation(
+            model_limit=128000,
+            output_reserve=8000,
+        )
+        
+        # Write snapshot
+        result_path = monitor.snapshot(
+            ledger=ledger,
+            budget=budget,
+            messages=messages,
+            trigger="turn",
+        )
+        
+        print(f"\n✓ Snapshot written to: {result_path}")
+        
+        # Read and display
+        with open(context_path) as f:
+            content = f.read()
+        print(f"\nSnapshot preview ({len(content)} chars):")
+        print("-" * 40)
+        print(content[:500] + "..." if len(content) > 500 else content)
+    
+    # Example 2: JSON format
+    print("\n\n2. JSON Format Output")
+    print("-" * 40)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        json_path = os.path.join(tmpdir, "context.json")
+        
+        monitor = ContextMonitor(
+            enabled=True,
+            path=json_path,
+            format="json",
+        )
+        
+        monitor.snapshot(
+            ledger=ledger,
+            budget=budget,
+            messages=messages,
+            trigger="manual",
+        )
+        
+        with open(json_path) as f:
+            content = f.read()
+        
+        print(f"JSON snapshot ({len(content)} chars):")
+        print(content[:300] + "..." if len(content) > 300 else content)
+    
+    # Example 3: Sensitive data redaction
+    print("\n\n3. Sensitive Data Redaction")
+    print("-" * 40)
+    
+    sensitive_text = """
+    Here's my API key: sk-proj-abc123def456ghi789
+    And my password is: supersecret123
+    Database connection: postgresql://user:pass@localhost/db
+    """
+    
+    redacted = redact_sensitive(sensitive_text)
+    print("Original text contains sensitive data:")
+    print(f"  - API key pattern found: {'sk-proj-' in sensitive_text}")
+    print(f"  - Password pattern found: {'password' in sensitive_text.lower()}")
+    print("\nAfter redaction:")
+    print(redacted)
+    
+    # Example 4: Monitor frequency options
+    print("\n4. Monitor Frequency Options")
+    print("-" * 40)
+    
+    frequencies = ["turn", "tool_call", "manual", "overflow"]
+    
+    for freq in frequencies:
+        monitor = ContextMonitor(enabled=True, frequency=freq)
+        
+        # Check what triggers writing
+        triggers = {
+            "turn": monitor.should_write("turn"),
+            "tool_call": monitor.should_write("tool_call"),
+            "manual": monitor.should_write("manual"),
+            "overflow": monitor.should_write("overflow"),
+        }
+        
+        active = [k for k, v in triggers.items() if v]
+        print(f"Frequency '{freq}': writes on {active}")
+    
+    # Example 5: Snapshot data structure
+    print("\n5. Snapshot Data Structure")
+    print("-" * 40)
+    
+    snapshot = ContextSnapshot(
+        timestamp="2025-01-07T19:30:00Z",
+        session_id="example-session-123",
+        agent_name="ExampleAgent",
+        model_name="gpt-4o-mini",
+        budget=budget,
+        ledger=ledger,
+        utilization=0.45,
+        warnings=["Context usage at 45%"],
+    )
+    
+    print(f"Snapshot fields:")
+    print(f"  - timestamp: {snapshot.timestamp}")
+    print(f"  - session_id: {snapshot.session_id}")
+    print(f"  - agent_name: {snapshot.agent_name}")
+    print(f"  - model_name: {snapshot.model_name}")
+    print(f"  - utilization: {snapshot.utilization:.1%}")
+    print(f"  - warnings: {snapshot.warnings}")
+    
+    # Format as human-readable
+    human_output = format_human_snapshot(snapshot)
+    print(f"\nHuman-readable format ({len(human_output)} chars)")
+    
+    # Format as JSON
+    json_output = format_json_snapshot(snapshot)
+    print(f"JSON format ({len(json_output)} chars)")
+    
+    print("\n" + "=" * 60)
+    print("✓ Context monitoring examples complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/11_context_optimization.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Context Optimization Example
+
+Demonstrates how to use context optimization with Agent via context= param,
+and also shows low-level optimizer usage for advanced scenarios.
+
+Agent-Centric Quick Start:
+    from praisonaiagents import Agent
+    from praisonaiagents.context import ManagerConfig
+    
+    agent = Agent(
+        instructions="You are helpful.",
+        context=ManagerConfig(
+            auto_compact=True,
+            strategy="smart",  # truncate, sliding_window, summarize, smart
+        ),
+    )
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.context import (
+    ManagerConfig,
+    get_optimizer,
+    OptimizerStrategy,
+    TruncateOptimizer,
+    SlidingWindowOptimizer,
+    PruneToolsOptimizer,
+    SmartOptimizer,
+    estimate_messages_tokens,
+)
+
+
+def agent_centric_example():
+    """Agent-centric usage - recommended approach."""
+    print("=" * 60)
+    print("Agent-Centric Context Optimization")
+    print("=" * 60)
+    
+    # Enable auto-compaction with smart strategy
+    agent = Agent(
+        instructions="You are a helpful assistant.",
+        context=ManagerConfig(
+            auto_compact=True,
+            compact_threshold=0.8,
+            strategy="smart",
+        ),
+    )
+    print("Agent with auto-compaction enabled")
+    print(f"Strategy: smart")
+    print(f"Threshold: 0.8 (80% of context budget)")
+    print(f"Context manager: {agent.context_manager is not None}")
+
+
+def main():
+    print("=" * 60)
+    print("Context Optimization Example")
+    print("=" * 60)
+    
+    # Create sample conversation with tool calls
+    messages = [
+        {"role": "system", "content": "You are a helpful AI assistant with access to tools."},
+        {"role": "user", "content": "What's the weather in Paris?"},
+        {"role": "assistant", "content": "", "tool_calls": [{"id": "call_1", "function": {"name": "get_weather", "arguments": '{"city": "Paris"}'}}]},
+        {"role": "tool", "tool_call_id": "call_1", "content": "Weather in Paris: 15°C, partly cloudy, humidity 65%, wind 10 km/h from the west. Extended forecast shows temperatures ranging from 12-18°C over the next week with occasional rain expected on Thursday and Friday."},
+        {"role": "assistant", "content": "The weather in Paris is currently 15°C and partly cloudy."},
+        {"role": "user", "content": "What about London?"},
+        {"role": "assistant", "content": "", "tool_calls": [{"id": "call_2", "function": {"name": "get_weather", "arguments": '{"city": "London"}'}}]},
+        {"role": "tool", "tool_call_id": "call_2", "content": "Weather in London: 12°C, overcast with light drizzle, humidity 80%, wind 15 km/h from the southwest. Rain expected to continue throughout the day with temperatures dropping to 8°C overnight."},
+        {"role": "assistant", "content": "London is 12°C with light drizzle."},
+    ]
+    
+    # Add more history to simulate a long conversation
+    for i in range(10):
+        messages.append({"role": "user", "content": f"Question {i}: Can you explain concept number {i} in detail? " * 20})
+        messages.append({"role": "assistant", "content": f"Answer {i}: Here's a detailed explanation of concept {i}. " * 30})
+    
+    original_tokens = estimate_messages_tokens(messages)
+    print(f"\nOriginal conversation: {len(messages)} messages, ~{original_tokens} tokens")
+    
+    # Example 1: Truncate Optimizer
+    print("\n1. Truncate Optimizer")
+    print("-" * 40)
+    
+    optimizer = TruncateOptimizer()
+    result, stats = optimizer.optimize(messages, target_tokens=2000)
+    result_tokens = estimate_messages_tokens(result)
+    
+    print(f"Strategy: Remove oldest messages first")
+    print(f"Result: {len(messages)} -> {len(result)} messages")
+    print(f"Tokens: {original_tokens} -> {result_tokens}")
+    
+    # Example 2: Sliding Window Optimizer
+    print("\n2. Sliding Window Optimizer")
+    print("-" * 40)
+    
+    optimizer = SlidingWindowOptimizer()
+    result, stats = optimizer.optimize(messages, target_tokens=2000)
+    result_tokens = estimate_messages_tokens(result)
+    
+    print(f"Strategy: Keep most recent messages within window")
+    print(f"Result: {len(messages)} -> {len(result)} messages")
+    print(f"Tokens: {original_tokens} -> {result_tokens}")
+    
+    # Example 3: Prune Tools Optimizer
+    print("\n3. Prune Tools Optimizer")
+    print("-" * 40)
+    
+    optimizer = PruneToolsOptimizer()
+    result, stats = optimizer.optimize(messages, target_tokens=2000)
+    result_tokens = estimate_messages_tokens(result)
+    
+    print(f"Strategy: Truncate old tool outputs, preserve recent")
+    print(f"Result: {len(messages)} -> {len(result)} messages")
+    print(f"Tokens: {original_tokens} -> {result_tokens}")
+    
+    # Example 4: Smart Optimizer (combines strategies)
+    print("\n4. Smart Optimizer (Recommended)")
+    print("-" * 40)
+    
+    optimizer = SmartOptimizer()
+    result, stats = optimizer.optimize(messages, target_tokens=2000)
+    result_tokens = estimate_messages_tokens(result)
+    
+    print(f"Strategy: Intelligent combination of all strategies")
+    print(f"Result: {len(messages)} -> {len(result)} messages")
+    print(f"Tokens: {original_tokens} -> {result_tokens}")
+    print(f"Stats: {stats}")
+    
+    # Example 5: Using the factory function
+    print("\n5. Optimizer Factory")
+    print("-" * 40)
+    
+    strategies = [
+        OptimizerStrategy.TRUNCATE,
+        OptimizerStrategy.SLIDING_WINDOW,
+        OptimizerStrategy.PRUNE_TOOLS,
+        OptimizerStrategy.SMART,
+    ]
+    
+    for strategy in strategies:
+        optimizer = get_optimizer(strategy)
+        result, _ = optimizer.optimize(messages, target_tokens=3000)
+        result_tokens = estimate_messages_tokens(result)
+        print(f"{strategy.value:15s}: {len(messages)} -> {len(result)} msgs, ~{result_tokens} tokens")
+    
+    # Example 6: Tool call/result pair preservation
+    print("\n6. Tool Call/Result Pair Preservation")
+    print("-" * 40)
+    
+    tool_messages = [
+        {"role": "system", "content": "You are helpful."},
+        {"role": "user", "content": "Get data"},
+        {"role": "assistant", "content": "", "tool_calls": [{"id": "tc1"}]},
+        {"role": "tool", "tool_call_id": "tc1", "content": "Data result"},
+        {"role": "assistant", "content": "Here's the data."},
+    ]
+    
+    optimizer = SmartOptimizer()
+    result, _ = optimizer.optimize(tool_messages, target_tokens=100)
+    
+    # Check if tool pairs are preserved
+    tool_calls = [m for m in result if m.get("tool_calls")]
+    tool_results = [m for m in result if m.get("role") == "tool"]
+    
+    print(f"Original: {len(tool_messages)} messages")
+    print(f"Optimized: {len(result)} messages")
+    print(f"Tool calls preserved: {len(tool_calls)}")
+    print(f"Tool results preserved: {len(tool_results)}")
+    
+    print("\n" + "=" * 60)
+    print("✓ Context optimization examples complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/12_multi_agent_context.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Multi-Agent Context Isolation Example
+
+Demonstrates how to use multi-agent context with PraisonAIAgents via context= param,
+and also shows low-level MultiAgentLedger usage for advanced scenarios.
+
+Agent-Centric Quick Start:
+    from praisonaiagents import Agent, PraisonAIAgents
+    from praisonaiagents.context import ManagerConfig
+    
+    agents = PraisonAIAgents(
+        agents=[agent1, agent2],
+        context=ManagerConfig(policy="isolated"),  # or "shared"
+    )
+"""
+
+import os
+import tempfile
+from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents.context import (
+    ManagerConfig,
+    MultiAgentLedger,
+    MultiAgentMonitor,
+    ContextLedgerManager,
+    ContextMonitor,
+    ContextBudgeter,
+)
+
+
+def agent_centric_example():
+    """Agent-centric usage - recommended approach."""
+    print("=" * 60)
+    print("Agent-Centric Multi-Agent Context")
+    print("=" * 60)
+    
+    # Create agents with context enabled
+    researcher = Agent(
+        name="Researcher",
+        instructions="You are a research specialist.",
+        context=True,
+    )
+    writer = Agent(
+        name="Writer", 
+        instructions="You are a technical writer.",
+        context=True,
+    )
+    
+    # Multi-agent setup with isolated context policy
+    # (each agent maintains its own context)
+    print("Created agents with context=True")
+    print("Use PraisonAIAgents(agents=[...], context=ManagerConfig(policy='isolated'))")
+    print("for multi-agent context isolation")
+
+
+def main():
+    print("=" * 60)
+    print("Multi-Agent Context Isolation Example")
+    print("=" * 60)
+    
+    # Example 1: Multi-Agent Ledger
+    print("\n1. Multi-Agent Ledger")
+    print("-" * 40)
+    
+    multi_ledger = MultiAgentLedger()
+    
+    # Get ledgers for different agents
+    researcher_ledger = multi_ledger.get_agent_ledger("researcher")
+    writer_ledger = multi_ledger.get_agent_ledger("writer")
+    reviewer_ledger = multi_ledger.get_agent_ledger("reviewer")
+    
+    # Track different context for each agent
+    researcher_ledger.track_system_prompt("You are a research specialist.")
+    researcher_ledger.track_history([
+        {"role": "user", "content": "Research AI trends"},
+        {"role": "assistant", "content": "Here are the latest AI trends..."},
+    ])
+    
+    writer_ledger.track_system_prompt("You are a technical writer.")
+    writer_ledger.track_history([
+        {"role": "user", "content": "Write an article about AI"},
+        {"role": "assistant", "content": "# AI in 2025\n\nArtificial Intelligence..."},
+    ])
+    
+    reviewer_ledger.track_system_prompt("You are a content reviewer.")
+    reviewer_ledger.track_history([
+        {"role": "user", "content": "Review this article"},
+        {"role": "assistant", "content": "The article is well-written..."},
+    ])
+    
+    # Check token usage per agent
+    print("Token usage per agent:")
+    for agent_id in multi_ledger.get_agent_ids():
+        ledger = multi_ledger.get_agent_ledger(agent_id)
+        print(f"  {agent_id}: {ledger.get_total()} tokens")
+    
+    # Get combined total
+    total = multi_ledger.get_combined_total()
+    print(f"\nTotal across all agents: {total} tokens")
+    
+    # Example 2: Multi-Agent Monitor
+    print("\n2. Multi-Agent Monitor")
+    print("-" * 40)
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        multi_monitor = MultiAgentMonitor(base_path=tmpdir)
+        
+        # Get monitors for each agent
+        for agent_id in ["researcher", "writer", "reviewer"]:
+            monitor = multi_monitor.get_agent_monitor(agent_id)
+            print(f"Monitor for {agent_id}: {monitor.path}")
+        
+        # Enable all monitors
+        multi_monitor.enable_all()
+        print(f"\nAll monitors enabled: {multi_monitor.enabled}")
+        
+        # List all agent IDs
+        agent_ids = multi_monitor.get_agent_ids()
+        print(f"Monitored agents: {agent_ids}")
+    
+    # Example 3: Per-Agent Budgeting
+    print("\n3. Per-Agent Budgeting")
+    print("-" * 40)
+    
+    agents_config = {
+        "researcher": {"model": "gpt-4o", "role": "Research"},
+        "writer": {"model": "gpt-4o-mini", "role": "Writing"},
+        "reviewer": {"model": "gpt-4o-mini", "role": "Review"},
+    }
+    
+    for agent_id, config in agents_config.items():
+        budgeter = ContextBudgeter(model=config["model"])
+        budget = budgeter.allocate()
+        print(f"{agent_id} ({config['model']}): {budget.usable:,} usable tokens")
+    
+    # Example 4: Context Isolation Verification
+    print("\n4. Context Isolation Verification")
+    print("-" * 40)
+    
+    # Create fresh multi-ledger
+    isolated_ledger = MultiAgentLedger()
+    
+    # Agent A tracks some context
+    agent_a = isolated_ledger.get_agent_ledger("agent_a")
+    agent_a.track_system_prompt("Agent A system prompt")
+    agent_a.track_history([{"role": "user", "content": "Message for A"}])
+    
+    # Agent B tracks different context
+    agent_b = isolated_ledger.get_agent_ledger("agent_b")
+    agent_b.track_system_prompt("Agent B system prompt")
+    agent_b.track_history([{"role": "user", "content": "Message for B"}])
+    
+    # Verify isolation
+    print(f"Agent A tokens: {agent_a.get_total()}")
+    print(f"Agent B tokens: {agent_b.get_total()}")
+    print(f"Agents are isolated: {agent_a.get_total() != agent_b.get_total() or True}")
+    
+    # Verify they don't share state
+    agent_a_ledger = agent_a.get_ledger()
+    agent_b_ledger = agent_b.get_ledger()
+    print(f"Agent A system_prompt tokens: {agent_a_ledger.system_prompt}")
+    print(f"Agent B system_prompt tokens: {agent_b_ledger.system_prompt}")
+    
+    # Example 5: Shared Team Memory (Optional)
+    print("\n5. Shared Team Memory Pattern")
+    print("-" * 40)
+    
+    # For shared context, you can use a dedicated "team" ledger
+    team_ledger = MultiAgentLedger()
+    
+    # Shared team memory
+    shared = team_ledger.get_agent_ledger("shared_memory")
+    shared.track_system_prompt("Team goal: Complete the research project by Friday")
+    
+    # Individual agents can reference shared memory
+    agent1 = team_ledger.get_agent_ledger("agent1")
+    agent2 = team_ledger.get_agent_ledger("agent2")
+    
+    # Each agent has their own context plus can access shared
+    agent1.track_system_prompt("You are agent 1")
+    agent2.track_system_prompt("You are agent 2")
+    
+    print(f"Shared memory tokens: {shared.get_total()}")
+    print(f"Agent 1 tokens: {agent1.get_total()}")
+    print(f"Agent 2 tokens: {agent2.get_total()}")
+    print(f"Total team tokens: {team_ledger.get_combined_total()}")
+    
+    print("\n" + "=" * 60)
+    print("✓ Multi-agent context isolation examples complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/13_agent_with_context_management.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Agent with Context Management Example
+
+Demonstrates how to use context management features with a real Agent
+making actual API calls.
+
+Requires: OPENAI_API_KEY environment variable
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.context import (
+    ContextBudgeter,
+    ContextLedgerManager,
+    ContextMonitor,
+    get_optimizer,
+    OptimizerStrategy,
+    estimate_messages_tokens,
+)
+
+
+def main():
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Error: OPENAI_API_KEY environment variable not set")
+        return
+    
+    print("=" * 60)
+    print("Agent with Context Management Example")
+    print("=" * 60)
+    
+    # Initialize context management components
+    budgeter = ContextBudgeter(model="gpt-4o-mini")
+    ledger = ContextLedgerManager()
+    optimizer = get_optimizer(OptimizerStrategy.SMART)
+    
+    # Get budget info
+    budget = budgeter.allocate()
+    print(f"\nModel: gpt-4o-mini")
+    print(f"Context budget: {budget.usable:,} tokens")
+    print(f"Output reserve: {budget.output_reserve:,} tokens")
+    
+    # Create an agent
+    agent = Agent(
+        instructions="You are a helpful AI assistant. Keep responses concise.",
+        llm="gpt-4o-mini",
+    )
+    
+    # Track the system prompt
+    ledger.track_system_prompt(agent.instructions)
+    print(f"\nSystem prompt tracked: {ledger.get_total()} tokens")
+    
+    # Simulate a conversation
+    print("\n" + "-" * 40)
+    print("Starting conversation...")
+    print("-" * 40)
+    
+    conversation = []
+    questions = [
+        "What is Python?",
+        "What are its main features?",
+        "Give me a simple example.",
+    ]
+    
+    for question in questions:
+        print(f"\nUser: {question}")
+        
+        # Add user message to conversation
+        conversation.append({"role": "user", "content": question})
+        
+        # Track in ledger
+        ledger.track_history(conversation[-1:])
+        
+        # Check context usage before API call
+        current_tokens = ledger.get_total()
+        utilization = budgeter.get_utilization(current_tokens)
+        
+        print(f"[Context: {current_tokens} tokens, {utilization:.1%} used]")
+        
+        # Check if optimization needed
+        if utilization > 0.8:
+            print("[Warning: High context usage, optimizing...]")
+            conversation, _ = optimizer.optimize(conversation, target_tokens=int(budget.usable * 0.7))
+        
+        # Make API call
+        response = agent.chat(question)
+        
+        # Add assistant response to conversation
+        conversation.append({"role": "assistant", "content": response})
+        ledger.track_history(conversation[-1:])
+        
+        print(f"Assistant: {response[:200]}..." if len(response) > 200 else f"Assistant: {response}")
+    
+    # Final stats
+    print("\n" + "-" * 40)
+    print("Final Context Statistics")
+    print("-" * 40)
+    
+    final_tokens = ledger.get_total()
+    final_utilization = budgeter.get_utilization(final_tokens)
+    
+    print(f"Total tokens used: {final_tokens:,}")
+    print(f"Context utilization: {final_utilization:.1%}")
+    print(f"Messages in conversation: {len(conversation)}")
+    print(f"Remaining capacity: {budgeter.get_remaining(final_tokens):,} tokens")
+    
+    # Demonstrate optimization on the final conversation
+    print("\n" + "-" * 40)
+    print("Optimization Demo")
+    print("-" * 40)
+    
+    original_tokens = estimate_messages_tokens(conversation)
+    optimized, stats = optimizer.optimize(conversation, target_tokens=500)
+    optimized_tokens = estimate_messages_tokens(optimized)
+    
+    print(f"Original: {len(conversation)} messages, {original_tokens} tokens")
+    print(f"Optimized: {len(optimized)} messages, {optimized_tokens} tokens")
+    print(f"Reduction: {((original_tokens - optimized_tokens) / original_tokens * 100):.1f}%")
+    
+    print("\n" + "=" * 60)
+    print("✓ Agent with context management example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/14_agent_context_param.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Agent-Centric Context Management Example
+
+Demonstrates the recommended way to use context management with the new
+`context=` parameter. This is the simplest and most powerful approach.
+
+The `context=` parameter accepts:
+- False (default): Zero overhead, no context management
+- True: Enable with safe defaults (auto-compact, smart strategy)
+- ManagerConfig: Custom configuration object
+- ContextManager: Pre-configured manager instance
+
+Requires: OPENAI_API_KEY environment variable
+"""
+
+import os
+from praisonaiagents import Agent
+from praisonaiagents.context import ManagerConfig
+
+
+def example_1_simple_enable():
+    """Simplest usage - just enable context management."""
+    print("=" * 60)
+    print("Example 1: Simple Enable (context=True)")
+    print("=" * 60)
+    
+    # Create agent with context management enabled
+    agent = Agent(
+        instructions="You are a helpful assistant. Keep responses concise.",
+        llm="gpt-4o-mini",
+        context=True,  # Enable with safe defaults
+    )
+    
+    # The agent now automatically:
+    # - Tracks token usage
+    # - Optimizes when approaching limits (80% threshold)
+    # - Uses smart optimization strategy
+    
+    print("Agent created with context management enabled")
+    print(f"Context manager initialized: {agent.context_manager is not None}")
+    
+    if agent.context_manager:
+        print(f"Model: {agent.context_manager.model}")
+        print(f"Auto-compact: {agent.context_manager.config.auto_compact}")
+        print(f"Threshold: {agent.context_manager.config.compact_threshold}")
+        print(f"Strategy: {agent.context_manager.config.strategy}")
+    
+    # Make a chat call
+    if os.environ.get("OPENAI_API_KEY"):
+        response = agent.chat("What is 2+2?")
+        print(f"\nResponse: {response}")
+    else:
+        print("\nSkipping API call (no OPENAI_API_KEY)")
+    
+    print()
+
+
+def example_2_custom_config():
+    """Custom configuration with ManagerConfig."""
+    print("=" * 60)
+    print("Example 2: Custom Configuration (context=ManagerConfig)")
+    print("=" * 60)
+    
+    # Create custom configuration
+    config = ManagerConfig(
+        auto_compact=True,
+        compact_threshold=0.7,  # Trigger at 70% instead of 80%
+        strategy="smart",
+        monitor_enabled=True,
+        monitor_path="./context_debug.txt",
+        monitor_format="human",
+        redact_sensitive=True,
+        output_reserve=8000,
+    )
+    
+    # Create agent with custom config
+    agent = Agent(
+        instructions="You are a code assistant.",
+        llm="gpt-4o-mini",
+        context=config,
+    )
+    
+    print("Agent created with custom context config")
+    print(f"Threshold: {agent.context_manager.config.compact_threshold}")
+    print(f"Monitor enabled: {agent.context_manager.config.monitor_enabled}")
+    print(f"Monitor path: {agent.context_manager.config.monitor_path}")
+    
+    if os.environ.get("OPENAI_API_KEY"):
+        response = agent.chat("Write a hello world in Python")
+        print(f"\nResponse: {response[:200]}...")
+    else:
+        print("\nSkipping API call (no OPENAI_API_KEY)")
+    
+    print()
+
+
+def example_3_disabled():
+    """Disabled context management - zero overhead."""
+    print("=" * 60)
+    print("Example 3: Disabled (context=False)")
+    print("=" * 60)
+    
+    # Create agent without context management (default)
+    agent = Agent(
+        instructions="You are a simple assistant.",
+        llm="gpt-4o-mini",
+        context=False,  # Explicit disable (same as default)
+    )
+    
+    print("Agent created without context management")
+    print(f"Context manager: {agent.context_manager}")
+    print("Zero overhead: No token tracking, no optimization")
+    
+    if os.environ.get("OPENAI_API_KEY"):
+        response = agent.chat("Hello!")
+        print(f"\nResponse: {response}")
+    else:
+        print("\nSkipping API call (no OPENAI_API_KEY)")
+    
+    print()
+
+
+def example_4_access_stats():
+    """Access context statistics and history."""
+    print("=" * 60)
+    print("Example 4: Access Context Stats")
+    print("=" * 60)
+    
+    agent = Agent(
+        instructions="You are helpful.",
+        llm="gpt-4o-mini",
+        context=True,
+    )
+    
+    manager = agent.context_manager
+    
+    # Access budget info via internal attribute
+    budget = manager._budget
+    print(f"Model limit: {budget.model_limit:,} tokens")
+    print(f"Output reserve: {budget.output_reserve:,} tokens")
+    print(f"Usable budget: {budget.usable:,} tokens")
+    
+    # Access config
+    print("\nConfiguration:")
+    print(f"  Auto-compact: {manager.config.auto_compact}")
+    print(f"  Threshold: {manager.config.compact_threshold}")
+    print(f"  Strategy: {manager.config.strategy}")
+    
+    print()
+
+
+def example_5_multi_agent():
+    """Multi-agent with shared context management."""
+    print("=" * 60)
+    print("Example 5: Multi-Agent Context Management")
+    print("=" * 60)
+    
+    from praisonaiagents import PraisonAIAgents, Task
+    
+    config = ManagerConfig(
+        auto_compact=True,
+        compact_threshold=0.8,
+    )
+    
+    # Create agents
+    researcher = Agent(
+        name="Researcher",
+        instructions="You research topics thoroughly.",
+        llm="gpt-4o-mini",
+    )
+    
+    writer = Agent(
+        name="Writer", 
+        instructions="You write clear summaries.",
+        llm="gpt-4o-mini",
+    )
+    
+    # Create tasks
+    task1 = Task(description="Research AI trends", agent=researcher)
+    task2 = Task(description="Write a summary", agent=writer)
+    
+    # Create multi-agent system with context management
+    agents = PraisonAIAgents(
+        agents=[researcher, writer],
+        tasks=[task1, task2],
+        context=config,  # Shared context config
+    )
+    
+    print("Multi-agent system created")
+    print(f"Context manager: {agents.context_manager is not None}")
+    
+    if agents.context_manager:
+        print("Type: MultiAgentContextManager")
+        print("Provides per-agent isolation with shared config")
+    
+    print()
+
+
+def main():
+    print("\n" + "=" * 60)
+    print("Agent-Centric Context Management Examples")
+    print("=" * 60 + "\n")
+    
+    example_1_simple_enable()
+    example_2_custom_config()
+    example_3_disabled()
+    example_4_access_stats()
+    example_5_multi_agent()
+    
+    print("=" * 60)
+    print("✓ All examples complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/interactive_defaults/interactive_tools_example.py

@@ -0,0 +1,147 @@
+"""
+Interactive Default Tools Example
+
+This example demonstrates how PraisonAI's interactive modes (TUI and prompt)
+include ACP and LSP tools by default.
+
+Tool Groups:
+- ACP: acp_create_file, acp_edit_file, acp_delete_file, acp_execute_command
+- LSP: lsp_list_symbols, lsp_find_definition, lsp_find_references, lsp_get_diagnostics
+- Basic: read_file, write_file, list_files, execute_command, internet_search
+
+Usage:
+    python interactive_tools_example.py
+"""
+
+import os
+import sys
+
+# Add paths for development
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../src/praisonai-agents'))
+
+
+def example_get_default_tools():
+    """Example: Get all default interactive tools."""
+    from praisonai.cli.features.interactive_tools import (
+        get_interactive_tools,
+        ToolConfig,
+        TOOL_GROUPS,
+    )
+    
+    print("=== Default Interactive Tools ===\n")
+    
+    # Show tool groups
+    print("Tool Groups:")
+    for group, tools in TOOL_GROUPS.items():
+        if group != "interactive":
+            print(f"  {group}: {tools}")
+    print()
+    
+    # Get all tools
+    config = ToolConfig(workspace=os.getcwd())
+    tools = get_interactive_tools(config=config)
+    
+    print(f"Total tools loaded: {len(tools)}")
+    print(f"Tool names: {[t.__name__ for t in tools]}")
+    print()
+    
+    return tools
+
+
+def example_disable_acp():
+    """Example: Disable ACP tools."""
+    from praisonai.cli.features.interactive_tools import (
+        get_interactive_tools,
+        ToolConfig,
+    )
+    
+    print("=== Disable ACP Tools (--no-acp) ===\n")
+    
+    config = ToolConfig(workspace=os.getcwd(), enable_acp=False)
+    tools = get_interactive_tools(config=config, disable=["acp"])
+    
+    acp_tools = [t for t in tools if t.__name__.startswith("acp_")]
+    print(f"ACP tools after --no-acp: {len(acp_tools)}")
+    print(f"Remaining tools: {[t.__name__ for t in tools]}")
+    print()
+    
+    return tools
+
+
+def example_disable_lsp():
+    """Example: Disable LSP tools."""
+    from praisonai.cli.features.interactive_tools import (
+        get_interactive_tools,
+        ToolConfig,
+    )
+    
+    print("=== Disable LSP Tools (--no-lsp) ===\n")
+    
+    config = ToolConfig(workspace=os.getcwd(), enable_lsp=False)
+    tools = get_interactive_tools(config=config, disable=["lsp"])
+    
+    lsp_tools = [t for t in tools if t.__name__.startswith("lsp_")]
+    print(f"LSP tools after --no-lsp: {len(lsp_tools)}")
+    print(f"Remaining tools: {[t.__name__ for t in tools]}")
+    print()
+    
+    return tools
+
+
+def example_agent_with_default_tools():
+    """Example: Create an Agent with default interactive tools."""
+    from praisonai.cli.features.interactive_tools import get_interactive_tools, ToolConfig
+    from praisonaiagents import Agent
+    
+    print("=== Agent with Default Interactive Tools ===\n")
+    
+    # Get default tools
+    config = ToolConfig(workspace=os.getcwd())
+    tools = get_interactive_tools(config=config)
+    
+    # Create agent with tools
+    agent = Agent(
+        name="InteractiveAgent",
+        instructions="You are a helpful coding assistant with file and code analysis capabilities.",
+        tools=tools,
+        verbose=False
+    )
+    
+    print(f"Agent created with {len(tools)} tools")
+    print(f"Tools: {[t.__name__ for t in tools]}")
+    print()
+    
+    # Simple test - list files
+    print("Testing agent with list_files tool...")
+    result = agent.start("List the Python files in the current directory using list_files tool.")
+    print(f"Result: {result[:200]}..." if len(str(result)) > 200 else f"Result: {result}")
+    print()
+    
+    return agent
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("PraisonAI Interactive Default Tools Example")
+    print("=" * 60)
+    print()
+    
+    # Example 1: Get default tools
+    example_get_default_tools()
+    
+    # Example 2: Disable ACP
+    example_disable_acp()
+    
+    # Example 3: Disable LSP
+    example_disable_lsp()
+    
+    # Example 4: Agent with default tools (requires API key)
+    if os.environ.get("OPENAI_API_KEY"):
+        example_agent_with_default_tools()
+    else:
+        print("=== Agent Example Skipped (no OPENAI_API_KEY) ===")
+    
+    print("=" * 60)
+    print("Examples Complete")
+    print("=" * 60)

examples/knowledge/compression_demo.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+Example: Context Compression Demo
+
+This example demonstrates:
+1. Context compression for large retrieved content
+2. Token budget management
+3. Agent-centric knowledge retrieval with unique codes
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python compression_demo.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+# Unique verification code that CANNOT be guessed
+SECRET_CODE = "COMPRESS-8K4M2"
+
+
+def create_verbose_document(temp_dir: str) -> str:
+    """Create a verbose document with a hidden unique code."""
+    filepath = os.path.join(temp_dir, 'verbose_policy.txt')
+    
+    # Create a document with lots of filler text but one unique code
+    with open(filepath, 'w') as f:
+        f.write("""
+ACME CORPORATION COMPREHENSIVE POLICY MANUAL
+=============================================
+
+CHAPTER 1: INTRODUCTION
+-----------------------
+
+This comprehensive policy manual outlines all procedures, guidelines, and 
+requirements for employees of Acme Corporation. All employees are expected 
+to read and understand this document in its entirety. This manual supersedes 
+all previous versions and is effective immediately upon publication.
+
+The purpose of this manual is to provide clear guidance on company policies,
+procedures, and expectations. It covers a wide range of topics including but
+not limited to workplace conduct, benefits, leave policies, and security
+protocols.
+
+CHAPTER 2: WORKPLACE CONDUCT
+----------------------------
+
+All employees are expected to maintain professional conduct at all times.
+This includes treating colleagues with respect, maintaining a clean workspace,
+and adhering to the company dress code. Violations of workplace conduct
+policies may result in disciplinary action up to and including termination.
+
+Professional behavior includes punctuality, meeting deadlines, and effective
+communication with team members. Employees should report any concerns about
+workplace conduct to their immediate supervisor or Human Resources.
+
+CHAPTER 3: BENEFITS AND COMPENSATION
+------------------------------------
+
+Acme Corporation offers a comprehensive benefits package to all full-time
+employees. This includes health insurance, dental coverage, vision care,
+and a 401(k) retirement plan with company matching up to 6% of salary.
+
+Employees are eligible for benefits after completing 90 days of employment.
+Open enrollment occurs annually in November. Changes to benefits outside
+of open enrollment require a qualifying life event.
+
+CHAPTER 4: LEAVE POLICIES
+-------------------------
+
+Employees accrue paid time off (PTO) based on years of service:
+- 0-2 years: 15 days per year
+- 3-5 years: 20 days per year
+- 6+ years: 25 days per year
+
+Sick leave is provided separately at 10 days per year. Unused sick leave
+may be carried over to the following year up to a maximum of 30 days.
+
+CHAPTER 5: SECURITY PROTOCOLS
+-----------------------------
+
+All employees must follow strict security protocols to protect company
+assets and confidential information. This includes using strong passwords,
+locking workstations when away, and reporting any suspicious activity.
+
+IMPORTANT: The master security verification code is: COMPRESS-8K4M2
+
+This code is required for accessing secure areas and systems. Do not share
+this code with unauthorized personnel. Misuse of security credentials is
+grounds for immediate termination.
+
+CHAPTER 6: EMERGENCY PROCEDURES
+-------------------------------
+
+In case of emergency, employees should follow the evacuation procedures
+posted throughout the building. Assembly points are located in the parking
+lot on the north side of the building.
+
+Fire drills are conducted quarterly. All employees must participate in
+fire drills and know the location of the nearest emergency exit.
+
+CHAPTER 7: CONCLUSION
+---------------------
+
+This policy manual is a living document and may be updated periodically.
+Employees will be notified of any changes via email and updated copies
+will be made available on the company intranet.
+
+Questions about any policy should be directed to Human Resources.
+
+Document Version: 3.2.1
+Last Updated: 2024-12-01
+""")
+    
+    return filepath
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_compress_')
+    
+    try:
+        print("=" * 60)
+        print("Example: Context Compression Demo")
+        print("=" * 60)
+        
+        # Create verbose document
+        doc_path = create_verbose_document(temp_dir)
+        print(f"\nCreated verbose document: {doc_path}")
+        print(f"Secret code embedded: {SECRET_CODE}")
+        
+        # Demonstrate compression
+        print("\n" + "-" * 40)
+        print("Compression Demo")
+        print("-" * 40)
+        
+        try:
+            from praisonaiagents.rag import ContextCompressor
+            
+            # Read the document
+            with open(doc_path, 'r') as f:
+                content = f.read()
+            
+            print(f"\nOriginal document length: {len(content)} characters")
+            
+            # Compress with different ratios
+            for ratio in [0.3, 0.5, 0.7]:
+                compressor = ContextCompressor(
+                    max_tokens=2000,
+                    target_ratio=ratio,
+                )
+                result = compressor.compress([content], query="security verification code")
+                
+                print(f"\nCompression ratio {ratio}:")
+                print(f"  Original tokens: {result.original_tokens}")
+                print(f"  Compressed tokens: {result.compressed_tokens}")
+                print(f"  Actual ratio: {result.compressed_tokens / max(result.original_tokens, 1):.2f}")
+                
+                # Check if secret code is preserved
+                compressed_text = " ".join(result.chunks) if result.chunks else ""
+                if SECRET_CODE in compressed_text:
+                    print(f"  ✅ Secret code preserved in compressed output")
+                else:
+                    print(f"  ⚠️ Secret code may have been removed (query-focused compression)")
+                    
+        except ImportError as e:
+            print(f"Note: Compression module not available: {e}")
+        
+        # Create agent with knowledge
+        print("\n" + "-" * 40)
+        print("Agent Knowledge Retrieval Test")
+        print("-" * 40)
+        
+        agent = Agent(
+            name="PolicyExpert",
+            instructions="""You are a company policy expert.
+Answer questions based ONLY on the provided knowledge context.
+When asked about codes, provide the EXACT code from the documents.
+Be concise but accurate.""",
+            knowledge=[temp_dir],
+            user_id="compression_demo_user",
+            verbose=True,
+        )
+        
+        # Test retrieval of the unique code
+        print("\nQ: What is the master security verification code?")
+        response = agent.chat("What is the master security verification code?")
+        print(f"A: {response}")
+        
+        if SECRET_CODE in response.upper():
+            print(f"\n✅ VERIFIED: Agent correctly retrieved the secret code!")
+        else:
+            print(f"\n❌ WARNING: Expected code {SECRET_CODE} not found in response")
+        
+        print("\n" + "=" * 60)
+        print("Demo Complete")
+        print("=" * 60)
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/context_required_example.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Example: Knowledge Retrieval with Context-Required Questions
+
+This example demonstrates:
+1. Agent answers questions that REQUIRE retrieved context (not general knowledge)
+2. Unique codes/secrets that cannot be guessed
+3. Verification that context is text, not file path
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python context_required_example.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_ctx_')
+    
+    try:
+        # Create test document with UNIQUE content that cannot be guessed
+        doc = os.path.join(temp_dir, 'company_policy.txt')
+        with open(doc, 'w') as f:
+            f.write("""
+Acme Corporation Internal Policy Document
+==========================================
+
+Remote Work Policy:
+- Employees may work from home up to 3 days per week
+- Manager approval is required for remote work
+- Manager approval code: ZEBRA-71
+- All requests must be submitted via the HR portal
+
+Expense Reimbursement:
+- Maximum daily meal allowance: $47.50
+- Mileage rate: $0.655 per mile
+- Expense submission code: TIGER-42
+- Receipts required for amounts over $25
+
+IT Security:
+- VPN access code prefix: FALCON-
+- Password reset hotline: 555-0199
+- Security incident code: HAWK-88
+
+This document is confidential. Last updated: 2024-01-15.
+            """)
+        
+        print("=" * 60)
+        print("Example: Context-Required Knowledge Retrieval")
+        print("=" * 60)
+        print(f"\nDocument location: {doc}")
+        print("\nThis example asks questions that CANNOT be answered")
+        print("without the retrieved context (unique codes/values).\n")
+        
+        # Create agent with knowledge
+        agent = Agent(
+            name="PolicyExpert",
+            instructions="""You are a company policy expert. 
+Answer questions based ONLY on the provided knowledge context.
+If the answer is not in the context, say 'I don't have that information.'
+Be precise and quote exact values when asked about codes or numbers.""",
+            knowledge=[temp_dir],
+            user_id="demo_user",
+            verbose=True,
+        )
+        
+        # Question 1: Unique code that requires context
+        print("-" * 40)
+        print("Question 1: What is the manager approval code for remote work?")
+        print("-" * 40)
+        response = agent.chat("What is the manager approval code for remote work?")
+        print(f"\nAnswer: {response}\n")
+        
+        # Verify the answer contains the unique code
+        if "ZEBRA-71" in response.upper():
+            print("✅ VERIFIED: Agent correctly retrieved the unique code from context!\n")
+        else:
+            print("❌ WARNING: Agent did not find the code - check retrieval\n")
+        
+        # Question 2: Another unique value
+        print("-" * 40)
+        print("Question 2: What is the maximum daily meal allowance?")
+        print("-" * 40)
+        response = agent.chat("What is the maximum daily meal allowance?")
+        print(f"\nAnswer: {response}\n")
+        
+        if "47.50" in response or "$47.50" in response:
+            print("✅ VERIFIED: Agent correctly retrieved the specific amount!\n")
+        else:
+            print("❌ WARNING: Agent did not find the amount - check retrieval\n")
+        
+        # Question 3: Security code
+        print("-" * 40)
+        print("Question 3: What is the security incident code?")
+        print("-" * 40)
+        response = agent.chat("What is the security incident code?")
+        print(f"\nAnswer: {response}\n")
+        
+        if "HAWK-88" in response.upper():
+            print("✅ VERIFIED: Agent correctly retrieved the security code!\n")
+        else:
+            print("❌ WARNING: Agent did not find the code - check retrieval\n")
+        
+        # Show context preview to prove it's text, not path
+        print("=" * 60)
+        print("Context Verification")
+        print("=" * 60)
+        context, _ = agent._get_knowledge_context("policy codes", use_rag=True)
+        print(f"\nRetrieved context preview (first 300 chars):")
+        print("-" * 40)
+        print(context[:300] if context else "NO CONTEXT")
+        print("-" * 40)
+        
+        # Verify context is text, not path
+        if temp_dir in context:
+            print("\n❌ ERROR: Context contains file path instead of text!")
+        else:
+            print("\n✅ VERIFIED: Context contains actual text, not file path!")
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/hierarchical_summaries_demo.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+Example: Hierarchical Summaries Demo
+
+This example demonstrates:
+1. Building multi-level summaries (file → folder → project)
+2. Query routing to appropriate summary level
+3. Agent-centric knowledge retrieval with unique codes
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python hierarchical_summaries_demo.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+# Unique verification codes per department
+DEPT_CODES = {
+    "engineering": "ENG-7X2K9",
+    "marketing": "MKT-3M5N8",
+    "finance": "FIN-9P4Q1",
+}
+
+
+def create_hierarchical_corpus(temp_dir: str) -> dict:
+    """Create a hierarchical corpus with departments and files."""
+    structure = {}
+    
+    for dept, code in DEPT_CODES.items():
+        dept_dir = os.path.join(temp_dir, dept)
+        os.makedirs(dept_dir, exist_ok=True)
+        structure[dept] = []
+        
+        # Create department overview
+        overview_path = os.path.join(dept_dir, "overview.txt")
+        with open(overview_path, 'w') as f:
+            f.write(f"""
+{dept.upper()} DEPARTMENT OVERVIEW
+{'=' * 40}
+
+Department: {dept.title()}
+Department Code: {code}
+
+Mission Statement:
+The {dept.title()} department is responsible for driving excellence
+in our organization through innovative solutions and dedicated teamwork.
+
+Key Responsibilities:
+- Strategic planning and execution
+- Cross-functional collaboration
+- Continuous improvement initiatives
+
+Access Code: {code}
+Use this code for all department-related system access.
+
+Last Updated: 2024-12-01
+""")
+        structure[dept].append(overview_path)
+        
+        # Create team files
+        for i, team in enumerate(["alpha", "beta", "gamma"]):
+            team_path = os.path.join(dept_dir, f"team_{team}.txt")
+            with open(team_path, 'w') as f:
+                f.write(f"""
+{dept.upper()} - TEAM {team.upper()}
+{'=' * 40}
+
+Team: {team.title()}
+Department: {dept.title()}
+Team Size: {5 + i * 2} members
+
+Current Projects:
+- Project {team.upper()}-001: In Progress
+- Project {team.upper()}-002: Planning
+- Project {team.upper()}-003: Completed
+
+Team Lead: {team.title()} Lead
+Contact: {team}@acme.com
+
+Note: For department access, use code: {code}
+""")
+            structure[dept].append(team_path)
+    
+    return structure
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_hierarchy_')
+    
+    try:
+        print("=" * 60)
+        print("Example: Hierarchical Summaries Demo")
+        print("=" * 60)
+        
+        # Create hierarchical corpus
+        structure = create_hierarchical_corpus(temp_dir)
+        total_files = sum(len(files) for files in structure.values())
+        print(f"\nCreated hierarchical corpus:")
+        print(f"  Departments: {len(structure)}")
+        print(f"  Total files: {total_files}")
+        print(f"  Location: {temp_dir}")
+        
+        for dept, files in structure.items():
+            print(f"  - {dept}/: {len(files)} files (code: {DEPT_CODES[dept]})")
+        
+        # Demonstrate hierarchical summarizer
+        print("\n" + "-" * 40)
+        print("Hierarchical Summarizer Demo")
+        print("-" * 40)
+        
+        try:
+            from praisonaiagents.rag import HierarchicalSummarizer
+            
+            # Collect all files
+            all_files = []
+            for files in structure.values():
+                all_files.extend(files)
+            
+            # Build hierarchy
+            summarizer = HierarchicalSummarizer(max_levels=3)
+            result = summarizer.build_hierarchy(all_files, base_path=temp_dir)
+            
+            print(f"\nHierarchy built:")
+            print(f"  Levels: {summarizer.max_levels}")
+            if hasattr(result, 'nodes'):
+                print(f"  Summary nodes: {len(result.nodes)}")
+            
+            # Query at different levels
+            print("\nQuery routing demonstration:")
+            queries = [
+                ("What is the engineering department code?", "engineering"),
+                ("Tell me about marketing team alpha", "marketing"),
+                ("What are the finance department responsibilities?", "finance"),
+            ]
+            
+            for query, expected_dept in queries:
+                print(f"\n  Query: {query}")
+                # In a full implementation, this would route to the appropriate level
+                print(f"  Expected department: {expected_dept}")
+                print(f"  Expected code: {DEPT_CODES[expected_dept]}")
+                
+        except ImportError as e:
+            print(f"Note: Hierarchical summarizer not available: {e}")
+        except Exception as e:
+            print(f"Note: Hierarchy building skipped: {e}")
+        
+        # Create agent with knowledge
+        print("\n" + "-" * 40)
+        print("Agent Knowledge Retrieval Test")
+        print("-" * 40)
+        
+        agent = Agent(
+            name="DepartmentExpert",
+            instructions="""You are a department information expert.
+Answer questions based ONLY on the provided knowledge context.
+When asked about department codes, provide the EXACT code from the documents.
+Be specific about which department you're referring to.""",
+            knowledge=[temp_dir],
+            user_id="hierarchy_demo_user",
+            verbose=True,
+        )
+        
+        # Test retrieval of department codes
+        test_cases = [
+            ("What is the engineering department access code?", "ENG-7X2K9"),
+            ("What is the marketing department code?", "MKT-3M5N8"),
+            ("What is the finance department code?", "FIN-9P4Q1"),
+        ]
+        
+        print("\nTesting retrieval of department codes:\n")
+        
+        for question, expected_code in test_cases:
+            print(f"Q: {question}")
+            response = agent.chat(question)
+            print(f"A: {response[:200]}...")
+            
+            if expected_code in response.upper():
+                print(f"✅ VERIFIED: Found code {expected_code}\n")
+            else:
+                print(f"❌ WARNING: Expected code {expected_code} not found\n")
+        
+        print("=" * 60)
+        print("Demo Complete")
+        print("=" * 60)
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/large_corpus_strategy_demo.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Example: Large Corpus Strategy Selection Demo
+
+This example demonstrates:
+1. Automatic strategy selection based on corpus size
+2. Different retrieval strategies (DIRECT, BASIC, HYBRID, RERANKED, COMPRESSED)
+3. Agent-centric knowledge retrieval with unique codes
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python large_corpus_strategy_demo.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+# Unique verification codes that CANNOT be guessed
+VERIFICATION_CODES = {
+    "project_alpha": "ALPHA-7X9K2",
+    "project_beta": "BETA-3M8N1",
+    "project_gamma": "GAMMA-5P2Q7",
+    "budget_code": "BUDGET-9R4T6",
+    "security_clearance": "CLEARANCE-2W8Y3",
+}
+
+
+def create_test_corpus(temp_dir: str, num_files: int = 10) -> list:
+    """Create a test corpus with unique codes in each file."""
+    files = []
+    
+    # Create main project files with unique codes
+    for i, (project, code) in enumerate(VERIFICATION_CODES.items()):
+        filepath = os.path.join(temp_dir, f"{project}_doc.txt")
+        with open(filepath, 'w') as f:
+            f.write(f"""
+{project.upper().replace('_', ' ')} Documentation
+{'=' * 50}
+
+Project Overview:
+This document contains confidential information about {project}.
+The verification code for this project is: {code}
+
+Key Details:
+- Project started: 2024-0{i+1}-15
+- Team size: {10 + i * 5} members
+- Status: Active
+- Priority: {'High' if i < 2 else 'Medium'}
+
+Access Requirements:
+To access this project, use verification code: {code}
+All access attempts are logged for security purposes.
+
+Last updated: 2024-12-01
+            """)
+        files.append(filepath)
+    
+    # Create additional filler files to simulate larger corpus
+    for i in range(num_files - len(VERIFICATION_CODES)):
+        filepath = os.path.join(temp_dir, f"general_doc_{i}.txt")
+        with open(filepath, 'w') as f:
+            f.write(f"""
+General Documentation File {i}
+{'=' * 40}
+
+This is a general documentation file containing various information
+about company processes and procedures.
+
+Section {i}.1: Overview
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+Section {i}.2: Procedures
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
+Duis aute irure dolor in reprehenderit in voluptate velit esse.
+
+Section {i}.3: Guidelines
+Excepteur sint occaecat cupidatat non proident, sunt in culpa.
+Qui officia deserunt mollit anim id est laborum.
+
+Document ID: DOC-{1000 + i}
+            """)
+        files.append(filepath)
+    
+    return files
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_strategy_')
+    
+    try:
+        print("=" * 60)
+        print("Example: Large Corpus Strategy Selection Demo")
+        print("=" * 60)
+        
+        # Create test corpus
+        files = create_test_corpus(temp_dir, num_files=15)
+        print(f"\nCreated {len(files)} test documents in: {temp_dir}")
+        print(f"Unique verification codes embedded: {len(VERIFICATION_CODES)}")
+        
+        # Show strategy selection based on corpus size
+        print("\n" + "-" * 40)
+        print("Strategy Selection Demo")
+        print("-" * 40)
+        
+        try:
+            from praisonaiagents.rag import select_strategy, RetrievalStrategy
+            from praisonaiagents.knowledge.indexing import CorpusStats
+            
+            # Get corpus stats
+            stats = CorpusStats.from_directory(temp_dir)
+            print(f"\nCorpus Statistics:")
+            print(f"  Files: {stats.file_count}")
+            print(f"  Estimated tokens: {stats.total_tokens}")
+            print(f"  Recommended strategy: {stats.strategy_recommendation}")
+            
+            # Show strategy selection for different corpus sizes
+            print(f"\nStrategy selection by corpus size:")
+            for size in [100, 1000, 10000, 50000, 100000]:
+                strategy = select_strategy(corpus_tokens=size)
+                print(f"  {size:>6} tokens -> {strategy.value}")
+                
+        except ImportError as e:
+            print(f"Note: Strategy module not available: {e}")
+        
+        # Create agent with knowledge
+        print("\n" + "-" * 40)
+        print("Agent Knowledge Retrieval Test")
+        print("-" * 40)
+        
+        agent = Agent(
+            name="ProjectExpert",
+            instructions="""You are a project documentation expert.
+Answer questions based ONLY on the provided knowledge context.
+When asked about verification codes, provide the EXACT code from the documents.
+If information is not in the context, say 'Information not found in documents.'""",
+            knowledge=[temp_dir],
+            user_id="strategy_demo_user",
+            verbose=True,
+        )
+        
+        # Test retrieval with unique codes
+        test_questions = [
+            ("What is the verification code for Project Alpha?", "ALPHA-7X9K2"),
+            ("What is the budget code?", "BUDGET-9R4T6"),
+            ("What is the security clearance code?", "CLEARANCE-2W8Y3"),
+        ]
+        
+        print("\nTesting retrieval of unique codes:\n")
+        
+        for question, expected_code in test_questions:
+            print(f"Q: {question}")
+            response = agent.chat(question)
+            print(f"A: {response[:200]}...")
+            
+            if expected_code in response.upper():
+                print(f"✅ VERIFIED: Found code {expected_code}\n")
+            else:
+                print(f"❌ WARNING: Expected code {expected_code} not found\n")
+        
+        print("=" * 60)
+        print("Demo Complete")
+        print("=" * 60)
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/mem0_backend_example.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+Example: Using mem0 Backend with Agent Retrieval
+
+This example demonstrates:
+1. Agent with knowledge using mem0 backend (default)
+2. Proper scope identifiers (user_id/agent_id)
+3. Handling of metadata normalization (mem0 returns metadata=None)
+4. Agent-first retrieval API
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python mem0_backend_example.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+def main():
+    # Create temporary directory with test documents
+    temp_dir = tempfile.mkdtemp(prefix='praison_example_')
+    
+    try:
+        # Create test documents with UNIQUE content that requires retrieval
+        doc1 = os.path.join(temp_dir, 'acme_policy.txt')
+        with open(doc1, 'w') as f:
+            f.write("""
+            Acme Corp Travel Policy Document
+            
+            Flight booking code: FALCON-77
+            Hotel reservation prefix: HTL-
+            Maximum daily meal allowance: $52.75
+            Mileage reimbursement rate: $0.67 per mile
+            Travel approval required for trips over: $500
+            Emergency travel hotline: 555-ACME-911
+            """)
+        
+        doc2 = os.path.join(temp_dir, 'project_info.txt')
+        with open(doc2, 'w') as f:
+            f.write("""
+            Project Phoenix Status Report
+            
+            Project code: PHOENIX-2024
+            Lead engineer: Dr. Sarah Chen
+            Budget allocation: $2.4 million
+            Target completion: Q3 2025
+            Security clearance required: Level 3
+            Weekly standup: Tuesdays at 10am PST
+            """)
+        
+        print("=" * 60)
+        print("Example: Agent with Knowledge (mem0 backend)")
+        print("=" * 60)
+        
+        # Create agent with knowledge
+        # mem0 is the default backend - it requires scope identifiers
+        agent = Agent(
+            name="PolicyExpert",
+            instructions="You are a company policy expert. Answer questions based ONLY on the provided knowledge. Quote exact values when asked about codes or numbers.",
+            knowledge=[temp_dir],  # Add directory with documents
+            user_id="example_user",  # Required for mem0 backend
+        )
+        
+        print("\n1. Testing Agent.chat() with context-required question:")
+        print("-" * 40)
+        
+        # Question that REQUIRES the retrieved context (unique code)
+        response = agent.chat("What is the flight booking code?")
+        print("Q: What is the flight booking code?")
+        print(f"A: {response}")
+        
+        # Verify the answer contains the unique code
+        if "FALCON-77" in response.upper():
+            print("✅ VERIFIED: Agent correctly retrieved the unique code!")
+        
+        print("\n2. Testing Agent.chat() with another context-required question:")
+        print("-" * 40)
+        
+        response = agent.chat("What is the maximum daily meal allowance?")
+        print("Q: What is the maximum daily meal allowance?")
+        print(f"A: {response}")
+        
+        if "52.75" in response:
+            print("✅ VERIFIED: Agent correctly retrieved the specific amount!")
+        
+        print("\n3. Testing Agent.retrieve() for context-only retrieval:")
+        print("-" * 40)
+        
+        # retrieve() returns context without LLM generation
+        try:
+            context_pack = agent.retrieve("Project Phoenix")
+            print("Query: Project Phoenix")
+            print(f"Context preview: {context_pack.context[:200]}...")
+            print(f"Citations: {len(context_pack.citations)} found")
+        except Exception as e:
+            print(f"Note: retrieve() requires RAG module: {e}")
+        
+        print("\n" + "=" * 60)
+        print("Example completed successfully!")
+        print("=" * 60)
+        
+    finally:
+        # Cleanup
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/scope_identifiers_example.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Example: Using Scope Identifiers (user_id, agent_id, run_id)
+
+This example demonstrates:
+1. Multi-user knowledge isolation with user_id
+2. Multi-agent knowledge sharing with agent_id
+3. Run-specific context with run_id
+4. Error handling for missing scope identifiers
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python scope_identifiers_example.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_scope_')
+    
+    try:
+        # Create test document
+        doc = os.path.join(temp_dir, 'shared_knowledge.txt')
+        with open(doc, 'w') as f:
+            f.write("""
+            Company Policy Document
+            
+            1. All employees must complete security training annually.
+            2. Remote work is allowed with manager approval.
+            3. Expense reports must be submitted within 30 days.
+            """)
+        
+        print("=" * 60)
+        print("Example: Scope Identifiers for Knowledge Isolation")
+        print("=" * 60)
+        
+        # Example 1: User-scoped knowledge
+        print("\n1. User-scoped knowledge (user_id):")
+        print("-" * 40)
+        
+        user1_agent = Agent(
+            name="HR_Assistant_User1",
+            instructions="You are an HR assistant.",
+            knowledge=[temp_dir],
+            user_id="user_alice",  # Knowledge scoped to Alice
+        )
+        
+        response = user1_agent.chat("What is the policy on remote work?")
+        print("User Alice asks: What is the policy on remote work?")
+        print(f"Response: {response[:200]}...")
+        
+        # Example 2: Agent-scoped knowledge
+        print("\n2. Agent-scoped knowledge (agent_id):")
+        print("-" * 40)
+        
+        shared_agent = Agent(
+            name="Policy_Expert",
+            instructions="You are a policy expert.",
+            knowledge=[temp_dir],
+            agent_id="policy_agent_v1",  # Knowledge scoped to this agent
+        )
+        
+        response = shared_agent.chat("What are the expense report rules?")
+        print("Agent policy_agent_v1 query: What are the expense report rules?")
+        print(f"Response: {response[:200]}...")
+        
+        # Example 3: Combined scoping
+        print("\n3. Combined scoping (user_id + agent_id):")
+        print("-" * 40)
+        
+        combined_agent = Agent(
+            name="Personal_HR_Bot",
+            instructions="You are a personal HR assistant.",
+            knowledge=[temp_dir],
+            user_id="user_bob",
+            agent_id="hr_bot_v2",
+        )
+        
+        response = combined_agent.chat("What training is required?")
+        print("User Bob with hr_bot_v2: What training is required?")
+        print(f"Response: {response[:200]}...")
+        
+        print("\n" + "=" * 60)
+        print("Scope Identifier Summary:")
+        print("=" * 60)
+        print("""
+- user_id: Isolates knowledge per user (multi-tenant)
+- agent_id: Isolates knowledge per agent type/version
+- run_id: Isolates knowledge per execution run (ephemeral)
+
+Best Practices:
+1. Always provide at least one scope identifier
+2. Use user_id for user-specific data
+3. Use agent_id for shared agent knowledge
+4. Use run_id for temporary/session-specific context
+        """)
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/knowledge/scope_isolation_example.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Example: Multi-Agent Scope Isolation
+
+This example demonstrates:
+1. Agent A ingests knowledge under user_id=U1
+2. Agent B queries under user_id=U2 - should NOT find the knowledge
+3. Agent B queries under user_id=U1 - should find the knowledge
+4. Proves scope isolation works correctly
+
+Requirements:
+- pip install praisonaiagents[knowledge]
+- OPENAI_API_KEY environment variable
+
+Usage:
+    python scope_isolation_example.py
+"""
+
+import os
+import tempfile
+import shutil
+
+from praisonaiagents import Agent, Knowledge
+
+
+def main():
+    temp_dir = tempfile.mkdtemp(prefix='praison_scope_')
+    
+    try:
+        # Create test document with UNIQUE secret
+        doc = os.path.join(temp_dir, 'secret.txt')
+        with open(doc, 'w') as f:
+            f.write("""
+Project Codename: PHOENIX
+Secret access code: WRENCH-992
+Classification: Top Secret
+Only authorized personnel with code WRENCH-992 may access this project.
+            """)
+        
+        print("=" * 60)
+        print("Example: Multi-Agent Scope Isolation")
+        print("=" * 60)
+        
+        # Step 1: Agent A ingests knowledge under user_id=U1
+        print("\n1. Agent A ingests knowledge under user_id='user_alice'")
+        print("-" * 40)
+        
+        agent_a = Agent(
+            name="AgentA_Ingester",
+            instructions="You ingest and store knowledge.",
+            knowledge=[temp_dir],
+            user_id="user_alice",  # Scoped to Alice
+            verbose=False,
+        )
+        
+        # Ensure knowledge is processed
+        agent_a._ensure_knowledge_processed()
+        print("   Knowledge ingested by Agent A under user_alice scope")
+        
+        # Step 2: Agent B queries under user_id=U2 - should NOT find
+        print("\n2. Agent B queries under user_id='user_bob' (different scope)")
+        print("-" * 40)
+        
+        # Create a separate Knowledge instance for Agent B with different scope
+        knowledge_b = Knowledge()
+        search_result = knowledge_b.search("WRENCH-992", user_id="user_bob")
+        
+        results = search_result.get('results', []) if isinstance(search_result, dict) else []
+        
+        if len(results) == 0:
+            print("   ✅ CORRECT: Agent B (user_bob) found NO results")
+            print("   Scope isolation is working!")
+        else:
+            # Check if any result actually contains the secret
+            found_secret = any('wrench-992' in str(r.get('memory', '')).lower() for r in results)
+            if found_secret:
+                print("   ❌ ERROR: Agent B found the secret - scope isolation failed!")
+            else:
+                print("   ✅ CORRECT: Agent B found no matching content")
+        
+        # Step 3: Agent B queries under user_id=U1 - should find
+        print("\n3. Agent B queries under user_id='user_alice' (same scope)")
+        print("-" * 40)
+        
+        search_result = knowledge_b.search("WRENCH-992", user_id="user_alice")
+        results = search_result.get('results', []) if isinstance(search_result, dict) else []
+        
+        if len(results) > 0:
+            memory = results[0].get('memory', '')
+            if 'wrench-992' in memory.lower():
+                print("   ✅ CORRECT: Agent B (as user_alice) found the secret!")
+                print(f"   Retrieved: {memory[:80]}...")
+            else:
+                print(f"   ⚠️ Found results but no secret: {memory[:80]}...")
+        else:
+            print("   ❌ ERROR: Agent B should have found results with user_alice scope")
+        
+        # Step 4: Full Agent chat test with scope
+        print("\n4. Full Agent chat test with correct scope")
+        print("-" * 40)
+        
+        agent_b = Agent(
+            name="AgentB_Querier",
+            instructions="Answer questions based on the provided knowledge. If you don't have the information, say so.",
+            knowledge=[temp_dir],
+            user_id="user_alice",  # Same scope as Agent A
+            verbose=False,
+        )
+        
+        response = agent_b.chat("What is the secret access code for Project PHOENIX?")
+        print(f"   Question: What is the secret access code?")
+        print(f"   Answer: {response}")
+        
+        if "WRENCH-992" in response.upper():
+            print("\n   ✅ VERIFIED: Agent correctly retrieved the secret code!")
+        else:
+            print("\n   ⚠️ Agent may not have found the code")
+        
+        print("\n" + "=" * 60)
+        print("Summary: Scope Isolation")
+        print("=" * 60)
+        print("""
+- user_id='user_alice': Can access knowledge ingested by user_alice
+- user_id='user_bob': Cannot access knowledge ingested by user_alice
+- This enables multi-tenant knowledge isolation
+        """)
+        
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()

examples/policy/basic_policy.py

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

examples/python/profiling/README.md

@@ -0,0 +1,83 @@
+# PraisonAI Profiling Examples
+
+This directory contains examples for profiling PraisonAI agent performance.
+
+## Prerequisites
+
+```bash
+pip install praisonai
+export OPENAI_API_KEY=your_key_here
+```
+
+## Examples
+
+### 1. Basic Profiling (`basic_profiling.py`)
+
+Demonstrates programmatic profiling of a single query:
+
+```bash
+python basic_profiling.py
+```
+
+### 2. Suite Profiling (`suite_profiling.py`)
+
+Runs a comprehensive profiling suite with multiple scenarios:
+
+```bash
+python suite_profiling.py
+```
+
+### 3. Optimization Demo (`optimization_example.py`)
+
+Demonstrates Tier 0/1/2 performance optimizations:
+
+```bash
+python optimization_example.py
+```
+
+## CLI Commands
+
+You can also profile directly from the command line:
+
+```bash
+# Profile a query
+praisonai profile query "What is 2+2?"
+
+# Profile with file grouping
+praisonai profile query "Hello" --show-files --limit 20
+
+# Profile imports
+praisonai profile imports
+
+# Profile startup time
+praisonai profile startup
+
+# Run comprehensive suite
+praisonai profile suite --quick
+
+# Create performance baseline
+praisonai profile snapshot --baseline
+
+# Compare against baseline
+praisonai profile snapshot current --compare
+
+# Show optimization status
+praisonai profile optimize --show
+```
+
+## Output
+
+- **Text output**: Human-readable timing breakdown
+- **JSON output**: Machine-readable for CI/CD (`--format json`)
+- **Artifacts**: Binary cProfile data and reports (`--save ./results`)
+- **Snapshots**: Performance baselines for regression detection
+
+## Performance Optimizations
+
+Enable opt-in optimizations via environment variables:
+
+```bash
+export PRAISONAI_LITE_MODE=1
+export PRAISONAI_SKIP_TYPE_VALIDATION=1
+export PRAISONAI_MINIMAL_IMPORTS=1
+```

examples/python/profiling/basic_profiling.py

@@ -0,0 +1,71 @@
+"""
+Basic Profiling Example for PraisonAI
+
+This example demonstrates how to use the unified profiler programmatically
+to measure agent performance.
+
+Run with:
+    python basic_profiling.py
+"""
+
+import os
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+from praisonai.cli.execution import (
+    ExecutionRequest,
+    Profiler,
+    ProfilerConfig,
+)
+
+
+def main():
+    """Run a profiled query and display results."""
+    
+    # Configure profiler (Layer 1 = basic profiling with function stats)
+    config = ProfilerConfig(
+        layer=1,             # 0=minimal, 1=basic, 2=deep
+        limit=15,            # Show top 15 functions
+        show_callers=False,  # Set True for caller info (layer 2)
+        show_callees=False,  # Set True for callee info (layer 2)
+    )
+    
+    # Create execution request
+    request = ExecutionRequest(
+        prompt="What is 2+2?",
+        agent_name="ProfiledAgent",
+    )
+    
+    # Run profiled query
+    print("🔬 Running profiled query...")
+    profiler = Profiler(config)
+    result, report = profiler.profile_sync(request)
+    
+    # Print formatted report
+    print("\n" + report.to_text())
+    
+    # Access timing data programmatically
+    print("\n📊 Timing Summary:")
+    print(f"  Imports:        {report.timing.imports_ms:>10.2f} ms")
+    print(f"  Agent Init:     {report.timing.agent_init_ms:>10.2f} ms")
+    print(f"  Execution:      {report.timing.execution_ms:>10.2f} ms")
+    print(f"  Total:          {report.timing.total_ms:>10.2f} ms")
+    
+    # Show top 5 functions
+    if report.functions:
+        print("\n🔥 Top 5 Functions by Cumulative Time:")
+        for i, func in enumerate(report.functions[:5], 1):
+            print(f"  {i}. {func.name}: {func.cumulative_time_ms:.2f}ms")
+    
+    # Show response
+    print(f"\n💬 Response: {result.output}")
+    
+    # Export to JSON
+    print("\n📄 JSON Export available via: report.to_json()")
+
+
+if __name__ == "__main__":
+    main()

examples/python/profiling/optimization_example.py

@@ -0,0 +1,223 @@
+"""
+Performance Optimization Example for PraisonAI
+
+This example demonstrates how to use the Tier 0/1/2 optimization features
+programmatically.
+
+Run with:
+    python optimization_example.py
+"""
+
+import os
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+
+def demo_provider_cache():
+    """Demonstrate provider caching (Tier 0)."""
+    print("\n" + "=" * 60)
+    print("Tier 0: Provider Cache Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import (
+        get_provider_cache,
+        resolve_model_provider,
+    )
+    
+    cache = get_provider_cache()
+    cache.invalidate()  # Start fresh
+    
+    # Resolve some models
+    models = ['gpt-4o', 'claude-3-opus', 'gemini-pro', 'gpt-4o-mini']
+    
+    print("\nResolving models:")
+    for model in models:
+        provider, name = resolve_model_provider(model)
+        print(f"  {model} -> {provider}/{name}")
+    
+    # Check cache stats
+    stats = cache.get_stats()
+    print("\nCache Stats:")
+    print(f"  Hits: {stats['hits']}")
+    print(f"  Misses: {stats['misses']}")
+    print(f"  Size: {stats['size']}")
+
+
+def demo_lazy_importer():
+    """Demonstrate lazy imports (Tier 0)."""
+    print("\n" + "=" * 60)
+    print("Tier 0: Lazy Importer Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import LazyImporter
+    import time
+    
+    LazyImporter.clear()
+    
+    # Time lazy import
+    start = time.perf_counter()
+    json_module = LazyImporter.get('json')
+    first_import = (time.perf_counter() - start) * 1000
+    
+    # Second import (cached)
+    start = time.perf_counter()
+    json_module2 = LazyImporter.get('json')
+    cached_import = (time.perf_counter() - start) * 1000
+    
+    print(f"\nFirst import: {first_import:.3f}ms")
+    print(f"Cached import: {cached_import:.3f}ms")
+    print(f"Same object: {json_module is json_module2}")
+
+
+def demo_client_pool():
+    """Demonstrate client pooling (Tier 1)."""
+    print("\n" + "=" * 60)
+    print("Tier 1: Client Pool Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import ClientPool
+    
+    pool = ClientPool(max_size=3)
+    
+    # Create some mock clients
+    def create_client(name):
+        return {'name': name, 'created': True}
+    
+    # Get or create clients
+    client1 = pool.get_or_create('openai', lambda: create_client('openai'))
+    _ = pool.get_or_create('anthropic', lambda: create_client('anthropic'))
+    
+    # Reuse existing client
+    client1_again = pool.get_or_create('openai', lambda: create_client('openai_new'))
+    
+    print(f"\nPool size: {pool.size()}")
+    print(f"Client reused: {client1 is client1_again}")
+    print(f"Client1 name: {client1['name']}")
+
+
+def demo_prewarm():
+    """Demonstrate pre-warming (Tier 1)."""
+    print("\n" + "=" * 60)
+    print("Tier 1: Pre-warming Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import PrewarmManager
+    import time
+    
+    PrewarmManager.reset()
+    
+    print(f"\nPre-warming enabled: {PrewarmManager.is_enabled()}")
+    
+    # Enable and prewarm
+    PrewarmManager.enable()
+    print(f"After enable: {PrewarmManager.is_enabled()}")
+    
+    # Prewarm OpenAI (runs in background)
+    PrewarmManager.prewarm_provider('openai')
+    print("Pre-warming OpenAI in background...")
+    
+    # Wait a bit for background thread
+    time.sleep(0.5)
+    
+    print(f"OpenAI prewarmed: {PrewarmManager.is_prewarmed('openai')}")
+    
+    PrewarmManager.reset()
+
+
+def demo_lite_mode():
+    """Demonstrate lite mode (Tier 2)."""
+    print("\n" + "=" * 60)
+    print("Tier 2: Lite Mode Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import (
+        LiteModeConfig,
+        is_lite_mode,
+    )
+    
+    # Default config
+    config = LiteModeConfig()
+    print(f"\nDefault lite mode: {config.enabled}")
+    
+    # Config from env
+    print("\nTo enable lite mode, set environment variables:")
+    print("  export PRAISONAI_LITE_MODE=1")
+    print("  export PRAISONAI_SKIP_TYPE_VALIDATION=1")
+    
+    print(f"\nCurrent is_lite_mode(): {is_lite_mode()}")
+
+
+def demo_perf_snapshot():
+    """Demonstrate performance snapshots (Tier 2)."""
+    print("\n" + "=" * 60)
+    print("Tier 2: Performance Snapshot Demo")
+    print("=" * 60)
+    
+    from praisonai.cli.features.profiler import (
+        PerfSnapshot,
+        PerfComparison,
+        PerfSnapshotManager,
+    )
+    import tempfile
+    from pathlib import Path
+    
+    # Create manager with temp directory
+    with tempfile.TemporaryDirectory() as tmpdir:
+        manager = PerfSnapshotManager(snapshot_dir=Path(tmpdir))
+        
+        # Create baseline
+        baseline = PerfSnapshot(
+            timestamp='2025-01-01T00:00:00Z',
+            name='baseline',
+            startup_cold_ms=100.0,
+            startup_warm_ms=80.0,
+            import_time_ms=500.0,
+            query_time_ms=2000.0,
+            first_token_ms=300.0,
+        )
+        manager.save_baseline(baseline)
+        print("\nBaseline saved")
+        
+        # Create current snapshot (simulated improvement)
+        current = PerfSnapshot(
+            timestamp='2025-01-02T00:00:00Z',
+            name='current',
+            startup_cold_ms=95.0,  # 5% faster
+            startup_warm_ms=78.0,
+            import_time_ms=480.0,  # 4% faster
+            query_time_ms=1900.0,  # 5% faster
+            first_token_ms=280.0,
+        )
+        
+        # Compare
+        comparison = PerfComparison(baseline=baseline, current=current)
+        
+        print(f"\nStartup improvement: {-comparison.startup_cold_diff_pct:.1f}%")
+        print(f"Import improvement: {-comparison.import_time_diff_pct:.1f}%")
+        print(f"Query improvement: {-comparison.query_time_diff_pct:.1f}%")
+        print(f"Is regression: {comparison.is_regression()}")
+
+
+def main():
+    """Run all demos."""
+    print("=" * 60)
+    print("PraisonAI Performance Optimization Demo")
+    print("=" * 60)
+    
+    demo_provider_cache()
+    demo_lazy_importer()
+    demo_client_pool()
+    demo_prewarm()
+    demo_lite_mode()
+    demo_perf_snapshot()
+    
+    print("\n" + "=" * 60)
+    print("All demos complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/python/profiling/profile_results/suite_results.json

@@ -0,0 +1,227 @@
+{
+  "timestamp": "2025-12-31T18:45:38.187539Z",
+  "metadata": {
+    "python_version": "3.12.11",
+    "platform": "macOS-15.7.4-arm64-arm-64bit",
+    "praisonai_version": "2.9.2",
+    "timestamp": "2025-12-31T18:45:38.226558Z"
+  },
+  "startup": {
+    "cold_ms": 80.9305000002496,
+    "warm_ms": 55.266541996388696
+  },
+  "import_analysis": [
+    {
+      "module": "praisonaiagents",
+      "self_us": 2419,
+      "cumulative_us": 1645390,
+      "self_ms": 2.419,
+      "cumulative_ms": 1645.39
+    },
+    {
+      "module": "praisonaiagents.workflows",
+      "self_us": 670,
+      "cumulative_us": 1375919,
+      "self_ms": 0.67,
+      "cumulative_ms": 1375.919
+    },
+    {
+      "module": "praisonaiagents.workflows.yaml_parser",
+      "self_us": 775,
+      "cumulative_us": 1369435,
+      "self_ms": 0.775,
+      "cumulative_ms": 1369.435
+    },
+    {
+      "module": "praisonaiagents.agent.agent",
+      "self_us": 19,
+      "cumulative_us": 1349174,
+      "self_ms": 0.019,
+      "cumulative_ms": 1349.174
+    },
+    {
+      "module": "praisonaiagents.agent",
+      "self_us": 537,
+      "cumulative_us": 1349155,
+      "self_ms": 0.537,
+      "cumulative_ms": 1349.155
+    },
+    {
+      "module": "praisonaiagents.agent.agent",
+      "self_us": 1453,
+      "cumulative_us": 1285299,
+      "self_ms": 1.453,
+      "cumulative_ms": 1285.299
+    },
+    {
+      "module": "praisonaiagents.llm.openai_client",
+      "self_us": 7887,
+      "cumulative_us": 1123578,
+      "self_ms": 7.887,
+      "cumulative_ms": 1123.578
+    },
+    {
+      "module": "openai",
+      "self_us": 1083,
+      "cumulative_us": 1115692,
+      "self_ms": 1.083,
+      "cumulative_ms": 1115.692
+    },
+    {
+      "module": "openai.types",
+      "self_us": 2606,
+      "cumulative_us": 957990,
+      "self_ms": 2.606,
+      "cumulative_ms": 957.99
+    },
+    {
+      "module": "openai.types.batch",
+      "self_us": 1787,
+      "cumulative_us": 485667,
+      "self_ms": 1.787,
+      "cumulative_ms": 485.667
+    },
+    {
+      "module": "openai._models",
+      "self_us": 13423,
+      "cumulative_us": 450798,
+      "self_ms": 13.423,
+      "cumulative_ms": 450.798
+    },
+    {
+      "module": "openai.types.eval_create_params",
+      "self_us": 644,
+      "cumulative_us": 393275,
+      "self_ms": 0.644,
+      "cumulative_ms": 393.275
+    },
+    {
+      "module": "openai.types.graders.grader_inputs_param",
+      "self_us": 17,
+      "cumulative_us": 359515,
+      "self_ms": 0.017,
+      "cumulative_ms": 359.515
+    },
+    {
+      "module": "openai.types.graders",
+      "self_us": 392,
+      "cumulative_us": 359498,
+      "self_ms": 0.392,
+      "cumulative_ms": 359.498
+    },
+    {
+      "module": "openai.types.graders.multi_grader",
+      "self_us": 3847,
+      "cumulative_us": 351251,
+      "self_ms": 3.847,
+      "cumulative_ms": 351.251
+    },
+    {
+      "module": "openai.types.graders.label_model_grader",
+      "self_us": 5450,
+      "cumulative_us": 337291,
+      "self_ms": 5.45,
+      "cumulative_ms": 337.291
+    },
+    {
+      "module": "openai.types.graders.grader_inputs",
+      "self_us": 545,
+      "cumulative_us": 331841,
+      "self_ms": 0.545,
+      "cumulative_ms": 331.841
+    },
+    {
+      "module": "openai.types.responses.response_input_text",
+      "self_us": 21,
+      "cumulative_us": 331297,
+      "self_ms": 0.021,
+      "cumulative_ms": 331.297
+    },
+    {
+      "module": "openai.types.responses",
+      "self_us": 1301,
+      "cumulative_us": 331277,
+      "self_ms": 1.301,
+      "cumulative_ms": 331.277
+    },
+    {
+      "module": "rich.logging",
+      "self_us": 1066,
+      "cumulative_us": 238256,
+      "self_ms": 1.066,
+      "cumulative_ms": 238.256
+    }
+  ],
+  "scenarios": [
+    {
+      "name": "simple_query",
+      "config": {
+        "prompt": "What is 2+2?",
+        "model": "default",
+        "stream": false,
+        "iterations": 2
+      },
+      "import_time_stats": {
+        "mean": 0.008833496394800022,
+        "min": 0.005916997906751931,
+        "max": 0.011749994882848114,
+        "stdev": 0.0041245517164382375,
+        "median": 0.008833496394800022
+      },
+      "total_time_stats": {
+        "mean": 1727.4090415012324,
+        "min": 1367.2264170018025,
+        "max": 2087.5916660006624,
+        "stdev": 509.3751524982296,
+        "median": 1727.4090415012324
+      },
+      "first_token_stats": null,
+      "raw_import_times_ms": [
+        0.011749994882848114,
+        0.005916997906751931
+      ],
+      "raw_total_times_ms": [
+        1367.2264170018025,
+        2087.5916660006624
+      ]
+    },
+    {
+      "name": "simple_stream",
+      "config": {
+        "prompt": "What is 2+2?",
+        "model": "default",
+        "stream": true,
+        "iterations": 2
+      },
+      "import_time_stats": {
+        "mean": 0.008792001608526334,
+        "min": 0.006375004886649549,
+        "max": 0.01120899833040312,
+        "stdev": 0.0034181495442894613,
+        "median": 0.008792001608526334
+      },
+      "total_time_stats": {
+        "mean": 2321.0982290001994,
+        "min": 1697.1089580038097,
+        "max": 2945.087499996589,
+        "stdev": 882.4540898183949,
+        "median": 2321.0982290001994
+      },
+      "first_token_stats": {
+        "mean": 2312.8511880022415,
+        "min": 1681.2440420035273,
+        "max": 2944.458334000956,
+        "stdev": 893.2273919631452,
+        "median": 2312.8511880022415
+      },
+      "raw_import_times_ms": [
+        0.01120899833040312,
+        0.006375004886649549
+      ],
+      "raw_total_times_ms": [
+        2945.087499996589,
+        1697.1089580038097
+      ]
+    }
+  ]
+}

examples/python/profiling/suite_profiling.py

@@ -0,0 +1,80 @@
+"""
+Profile Suite Example for PraisonAI
+
+This example demonstrates how to run a comprehensive profiling suite
+programmatically with multiple scenarios.
+
+Run with:
+    python suite_profiling.py
+"""
+
+import os
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+from praisonai.cli.features.profiler import (
+    ScenarioConfig,
+    run_profile_suite,
+)
+
+
+def main():
+    """Run a profiling suite with custom scenarios."""
+    
+    # Define custom scenarios
+    scenarios = [
+        ScenarioConfig(
+            name="simple_query",
+            prompt="What is 2+2?",
+            stream=False,
+            iterations=2,
+            warmup=1,
+        ),
+        ScenarioConfig(
+            name="simple_stream",
+            prompt="What is 2+2?",
+            stream=True,
+            iterations=2,
+            warmup=1,
+        ),
+    ]
+    
+    # Run suite with custom output directory
+    print("🔬 Running Profile Suite...")
+    result = run_profile_suite(
+        output_dir="./profile_results",
+        scenarios=scenarios,
+        verbose=True,
+    )
+    
+    # Print summary
+    print("\n" + "=" * 60)
+    print("Profile Suite Results")
+    print("=" * 60)
+    
+    print("\n📊 Startup Times:")
+    print(f"  Cold Start: {result.startup_cold_ms:.2f}ms")
+    print(f"  Warm Start: {result.startup_warm_ms:.2f}ms")
+    
+    if result.import_analysis:
+        print("\n📦 Top Import:")
+        print(f"  {result.import_analysis[0]['module']}: {result.import_analysis[0]['cumulative_ms']:.2f}ms")
+    
+    print("\n🎯 Scenario Results:")
+    for scenario in result.scenarios:
+        stats = scenario.get_stats(scenario.total_times)
+        print(f"  {scenario.name}:")
+        print(f"    Mean: {stats['mean']:.2f}ms")
+        print(f"    Min:  {stats['min']:.2f}ms")
+        print(f"    Max:  {stats['max']:.2f}ms")
+    
+    print("\n✅ Results saved to: ./profile_results/")
+    print("   - suite_results.json (machine-readable)")
+    print("   - suite_report.txt (human-readable)")
+
+
+if __name__ == "__main__":
+    main()

examples/python/rag/agent_vs_auto_rag.py

@@ -0,0 +1,109 @@
+"""
+Agent vs AutoRagAgent Comparison
+
+Demonstrates the difference between using Agent directly vs AutoRagAgent wrapper.
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent, AutoRagAgent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a sample document
+sample_doc = "/tmp/comparison_doc.txt"
+with open(sample_doc, "w") as f:
+    f.write("""
+Product Manual: Smart Thermostat
+
+Installation:
+1. Turn off power at the circuit breaker
+2. Remove old thermostat
+3. Connect wires to matching terminals
+4. Mount the base plate
+5. Attach the display unit
+6. Restore power
+
+Features:
+- Wi-Fi connectivity
+- Voice control support
+- Energy usage reports
+- Geofencing auto-away
+- Learning schedule
+
+Troubleshooting:
+- If display is blank, check power connection
+- If Wi-Fi won't connect, restart router
+- If temperature is inaccurate, recalibrate sensor
+""")
+
+# Create base agent with knowledge
+agent = Agent(
+    name="TechSupport",
+    instructions="You are a technical support assistant.",
+    knowledge=[sample_doc],
+    user_id="comparison_user",
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+print("=" * 60)
+print("Agent vs AutoRagAgent Comparison")
+print("=" * 60)
+
+# Using Agent directly - always uses RAG when knowledge is configured
+print("\n[Using Agent Directly]")
+print("Agent with knowledge always retrieves context for every query.")
+print("\nQuery: 'Hello!'")
+response = agent.chat("Hello!")
+print(f"Response: {response}")
+
+print("\nQuery: 'How do I install the thermostat?'")
+response = agent.chat("How do I install the thermostat?")
+print(f"Response: {response[:300]}...")
+
+# Using AutoRagAgent - decides when to retrieve
+print("\n" + "=" * 60)
+print("[Using AutoRagAgent]")
+print("AutoRagAgent decides when to retrieve based on query heuristics.")
+
+auto_rag = AutoRagAgent(agent=agent, retrieval_policy="auto")
+
+print("\nQuery: 'Hello!' (short greeting - skips retrieval)")
+response = auto_rag.chat("Hello!")
+print(f"Response: {response}")
+
+print("\nQuery: 'How do I install the thermostat?' (question - retrieves)")
+response = auto_rag.chat("How do I install the thermostat?")
+print(f"Response: {response[:300]}...")
+
+# Summary
+print("\n" + "=" * 60)
+print("Summary:")
+print("-" * 60)
+print("""
+| Approach      | Retrieval Behavior              | Best For                    |
+|---------------|--------------------------------|------------------------------|
+| Agent         | Always retrieves (if knowledge)| Consistent RAG responses     |
+| AutoRagAgent  | Decides per query              | Mixed chat + RAG workloads   |
+
+AutoRagAgent is ideal when:
+- You have a chatbot that sometimes needs knowledge, sometimes doesn't
+- You want to reduce unnecessary retrieval overhead
+- You need fine-grained control over retrieval behavior
+""")
+
+# Cleanup
+os.remove(sample_doc)
+
+print("=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/rag/auto_rag_agent_basic.py

@@ -0,0 +1,79 @@
+"""
+AutoRagAgent Basic Example
+
+Demonstrates basic usage of AutoRagAgent for automatic RAG retrieval decision.
+AutoRagAgent wraps an Agent and decides when to retrieve context based on query heuristics.
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent, AutoRagAgent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a sample document for testing
+sample_doc = "/tmp/sample_doc.txt"
+with open(sample_doc, "w") as f:
+    f.write("""
+PraisonAI Framework Documentation
+
+PraisonAI is an AI agents framework that supports:
+- Single agent workflows
+- Multi-agent collaboration
+- RAG (Retrieval Augmented Generation)
+- Tool integration
+- Memory and context management
+
+Key Features:
+1. AutoRagAgent - Automatic retrieval decision
+2. Knowledge bases - Document indexing and search
+3. Hybrid retrieval - Dense + BM25 search
+4. Reranking - Improve result relevance
+""")
+
+# Create agent with knowledge
+agent = Agent(
+    name="DocBot",
+    instructions="You are a helpful documentation assistant. Answer questions based on the provided context.",
+    knowledge=[sample_doc],
+    user_id="example_user",  # Required for RAG retrieval
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+# Wrap with AutoRagAgent (default: auto policy)
+auto_rag = AutoRagAgent(agent=agent)
+
+print("=" * 60)
+print("AutoRagAgent Basic Example")
+print("=" * 60)
+
+# Test 1: Question that should trigger retrieval
+print("\n[Test 1] Question about documentation (should retrieve):")
+response = auto_rag.chat("What features does PraisonAI support?")
+print(f"Response: {response}")
+
+# Test 2: Short greeting that should skip retrieval
+print("\n[Test 2] Short greeting (should skip retrieval):")
+response = auto_rag.chat("Hi!")
+print(f"Response: {response}")
+
+# Test 3: Another question
+print("\n[Test 3] Another question (should retrieve):")
+response = auto_rag.chat("What is AutoRagAgent?")
+print(f"Response: {response}")
+
+# Cleanup
+os.remove(sample_doc)
+
+print("\n" + "=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/rag/auto_rag_agent_policy.py

@@ -0,0 +1,97 @@
+"""
+AutoRagAgent Policy Example
+
+Demonstrates different retrieval policies:
+- auto: Decides based on query heuristics (default)
+- always: Always retrieves context
+- never: Never retrieves, direct chat only
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent, AutoRagAgent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a sample document
+sample_doc = "/tmp/policy_doc.txt"
+with open(sample_doc, "w") as f:
+    f.write("""
+Company Return Policy
+
+Our return policy allows returns within 30 days of purchase.
+Items must be in original condition with tags attached.
+Refunds are processed within 5-7 business days.
+Exchanges are available for different sizes or colors.
+""")
+
+# Create base agent with knowledge
+agent = Agent(
+    name="PolicyBot",
+    instructions="You are a customer service assistant.",
+    knowledge=[sample_doc],
+    user_id="policy_user",
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+print("=" * 60)
+print("AutoRagAgent Policy Example")
+print("=" * 60)
+
+# Policy 1: AUTO (default)
+print("\n[Policy: AUTO] - Decides based on query heuristics")
+auto_rag = AutoRagAgent(agent=agent, retrieval_policy="auto")
+
+print("  Query: 'What is the return policy?' (should retrieve)")
+response = auto_rag.chat("What is the return policy?")
+print(f"  Response: {response[:200]}...")
+
+print("\n  Query: 'Hello' (should skip)")
+response = auto_rag.chat("Hello")
+print(f"  Response: {response}")
+
+# Policy 2: ALWAYS
+print("\n" + "-" * 60)
+print("[Policy: ALWAYS] - Always retrieves context")
+always_rag = AutoRagAgent(agent=agent, retrieval_policy="always")
+
+print("  Query: 'Hello' (will retrieve even for greeting)")
+response = always_rag.chat("Hello")
+print(f"  Response: {response[:200]}...")
+
+# Policy 3: NEVER
+print("\n" + "-" * 60)
+print("[Policy: NEVER] - Never retrieves, direct chat only")
+never_rag = AutoRagAgent(agent=agent, retrieval_policy="never")
+
+print("  Query: 'What is the return policy?' (will NOT retrieve)")
+response = never_rag.chat("What is the return policy?")
+print(f"  Response: {response[:200]}...")
+
+# Per-call overrides
+print("\n" + "-" * 60)
+print("[Per-call Overrides]")
+
+print("  Force retrieval on 'auto' policy:")
+response = auto_rag.chat("Hi there", force_retrieval=True)
+print(f"  Response: {response[:200]}...")
+
+print("\n  Skip retrieval on 'auto' policy:")
+response = auto_rag.chat("What is the return window?", skip_retrieval=True)
+print(f"  Response: {response[:200]}...")
+
+# Cleanup
+os.remove(sample_doc)
+
+print("\n" + "=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/rag/rag_basic.py

@@ -0,0 +1,70 @@
+"""
+RAG Basic Example
+
+Demonstrates basic RAG (Retrieval Augmented Generation) with an Agent.
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a sample document
+sample_doc = "/tmp/rag_basic_doc.txt"
+with open(sample_doc, "w") as f:
+    f.write("""
+Machine Learning Fundamentals
+
+Machine learning is a subset of artificial intelligence that enables systems
+to learn and improve from experience without being explicitly programmed.
+
+Types of Machine Learning:
+1. Supervised Learning - Learning from labeled data
+2. Unsupervised Learning - Finding patterns in unlabeled data
+3. Reinforcement Learning - Learning through trial and error
+
+Common Algorithms:
+- Linear Regression
+- Decision Trees
+- Neural Networks
+- Support Vector Machines
+""")
+
+# Create agent with RAG
+agent = Agent(
+    name="MLExpert",
+    instructions="You are a machine learning expert. Answer questions based on the provided context.",
+    knowledge=[sample_doc],
+    user_id="rag_user",
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+print("=" * 60)
+print("RAG Basic Example")
+print("=" * 60)
+
+# Query with RAG
+print("\nQuery: What are the types of machine learning?")
+response = agent.chat("What are the types of machine learning?")
+print(f"Response: {response}")
+
+print("\nQuery: What algorithms are commonly used?")
+response = agent.chat("What algorithms are commonly used?")
+print(f"Response: {response}")
+
+# Cleanup
+os.remove(sample_doc)
+
+print("\n" + "=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/rag/rag_hybrid.py

@@ -0,0 +1,94 @@
+"""
+RAG Hybrid Retrieval Example
+
+Demonstrates hybrid retrieval (dense + BM25 keyword search) for better results.
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent, AutoRagAgent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a sample document with technical content
+sample_doc = "/tmp/rag_hybrid_doc.txt"
+with open(sample_doc, "w") as f:
+    f.write("""
+API Documentation
+
+Authentication:
+All API requests require an API key in the X-API-Key header.
+Rate limits: 100 requests per minute for free tier, 1000 for pro tier.
+
+Endpoints:
+
+POST /api/v1/users
+Creates a new user account.
+Required fields: email, password, name
+Returns: user_id, created_at
+
+GET /api/v1/users/{id}
+Retrieves user information by ID.
+Returns: email, name, created_at, last_login
+
+PUT /api/v1/users/{id}
+Updates user information.
+Optional fields: name, email, password
+
+DELETE /api/v1/users/{id}
+Deletes a user account. Requires admin privileges.
+
+Error Codes:
+- 400: Bad Request - Invalid input
+- 401: Unauthorized - Missing or invalid API key
+- 403: Forbidden - Insufficient permissions
+- 404: Not Found - Resource doesn't exist
+- 429: Too Many Requests - Rate limit exceeded
+""")
+
+# Create agent with knowledge
+agent = Agent(
+    name="APIDocBot",
+    instructions="You are an API documentation assistant.",
+    knowledge=[sample_doc],
+    user_id="hybrid_user",
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+print("=" * 60)
+print("RAG Hybrid Retrieval Example")
+print("=" * 60)
+
+# Standard retrieval
+print("\n[Standard Retrieval]")
+auto_rag_standard = AutoRagAgent(agent=agent, hybrid=False)
+response = auto_rag_standard.chat("What error code means rate limit exceeded?")
+print(f"Response: {response}")
+
+# Hybrid retrieval (dense + BM25)
+print("\n[Hybrid Retrieval - Dense + BM25]")
+auto_rag_hybrid = AutoRagAgent(agent=agent, hybrid=True)
+response = auto_rag_hybrid.chat("What error code means rate limit exceeded?")
+print(f"Response: {response}")
+
+# Hybrid with reranking for best quality
+print("\n[Hybrid + Reranking]")
+auto_rag_best = AutoRagAgent(agent=agent, hybrid=True, rerank=True, top_k=10)
+response = auto_rag_best.chat("How do I create a new user via the API?")
+print(f"Response: {response}")
+
+# Cleanup
+os.remove(sample_doc)
+
+print("\n" + "=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/rag/rag_with_citations.py

@@ -0,0 +1,84 @@
+"""
+RAG with Citations Example
+
+Demonstrates RAG with citation tracking for source attribution.
+
+Requirements:
+    pip install praisonaiagents
+    
+Environment:
+    OPENAI_API_KEY - Required for LLM calls
+"""
+
+import os
+from praisonaiagents import Agent, AutoRagAgent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create multiple sample documents
+doc1 = "/tmp/citation_doc1.txt"
+with open(doc1, "w") as f:
+    f.write("""
+Research Paper: Climate Change Effects
+
+Global temperatures have risen by 1.1°C since pre-industrial times.
+Sea levels are rising at 3.3mm per year.
+Arctic ice is declining at 13% per decade.
+""")
+
+doc2 = "/tmp/citation_doc2.txt"
+with open(doc2, "w") as f:
+    f.write("""
+Research Paper: Renewable Energy
+
+Solar energy capacity has grown 20x in the last decade.
+Wind power now provides 7% of global electricity.
+Battery storage costs have dropped 89% since 2010.
+""")
+
+# Create agent with multiple knowledge sources
+agent = Agent(
+    name="ResearchBot",
+    instructions="You are a research assistant. Always cite your sources.",
+    knowledge=[doc1, doc2],
+    user_id="citation_user",
+    llm="openai/gpt-4o-mini",
+    verbose=False,
+)
+
+print("=" * 60)
+print("RAG with Citations Example")
+print("=" * 60)
+
+# AutoRagAgent with citations enabled (default)
+auto_rag = AutoRagAgent(
+    agent=agent,
+    citations=True,  # Include citations in response
+)
+
+print("\nQuery: What are the key climate change statistics?")
+response = auto_rag.chat("What are the key climate change statistics?")
+print(f"Response:\n{response}")
+
+print("\n" + "-" * 60)
+print("\nQuery: How has renewable energy grown?")
+response = auto_rag.chat("How has renewable energy grown?")
+print(f"Response:\n{response}")
+
+# Without citations
+print("\n" + "-" * 60)
+print("\n[Without Citations]")
+auto_rag_no_cite = AutoRagAgent(agent=agent, citations=False)
+response = auto_rag_no_cite.chat("What is the rate of sea level rise?")
+print(f"Response: {response}")
+
+# Cleanup
+os.remove(doc1)
+os.remove(doc2)
+
+print("\n" + "=" * 60)
+print("Example completed successfully!")
+print("=" * 60)

examples/python/session/session_persistence_example.py

@@ -0,0 +1,165 @@
+"""
+Session Persistence Example
+
+Demonstrates automatic session persistence with zero configuration.
+When you provide a session_id to an Agent, conversation history is
+automatically saved to disk and restored on subsequent runs.
+
+Usage:
+    python session_persistence_example.py
+
+Requirements:
+    - praisonaiagents package installed
+    - OPENAI_API_KEY environment variable set
+"""
+
+from praisonaiagents import Agent
+
+
+def example_basic_persistence():
+    """Basic session persistence example."""
+    print("=" * 60)
+    print("EXAMPLE 1: Basic Session Persistence")
+    print("=" * 60)
+    
+    session_id = "demo-session-basic"
+    
+    # Create agent with session_id
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful assistant. Be very brief.",
+        session_id=session_id,
+        verbose=False,
+    )
+    
+    # First message
+    print("\n[User]: My favorite color is blue and my lucky number is 7.")
+    response1 = agent.chat("My favorite color is blue and my lucky number is 7.")
+    print(f"[Assistant]: {response1}")
+    
+    # Second message - agent remembers
+    print("\n[User]: What is my favorite color?")
+    response2 = agent.chat("What is my favorite color?")
+    print(f"[Assistant]: {response2}")
+    
+    print(f"\n✅ Session saved to: ~/.praison/sessions/{session_id}.json")
+    print(f"   Chat history length: {len(agent.chat_history)} messages")
+
+
+def example_session_restoration():
+    """Demonstrates session restoration across Agent instances."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 2: Session Restoration")
+    print("=" * 60)
+    
+    session_id = "demo-session-restore"
+    
+    # First agent instance
+    print("\n--- First Agent Instance ---")
+    agent1 = Agent(
+        name="MemoryBot",
+        instructions="You are a helpful assistant. Be very brief.",
+        session_id=session_id,
+        verbose=False,
+    )
+    
+    print("[User]: Remember that my pet's name is Max.")
+    response1 = agent1.chat("Remember that my pet's name is Max.")
+    print(f"[Assistant]: {response1}")
+    
+    # Simulate new process by creating new agent instance
+    print("\n--- New Agent Instance (simulating restart) ---")
+    agent2 = Agent(
+        name="MemoryBot",
+        instructions="You are a helpful assistant. Be very brief.",
+        session_id=session_id,
+        verbose=False,
+    )
+    
+    print("[User]: What is my pet's name?")
+    response2 = agent2.chat("What is my pet's name?")
+    print(f"[Assistant]: {response2}")
+    
+    if "max" in response2.lower():
+        print("\n✅ Session restored successfully! Agent remembered 'Max'.")
+    else:
+        print("\n⚠️ Agent may not have remembered correctly.")
+
+
+def example_in_memory_only():
+    """Demonstrates in-memory memory without persistence."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 3: In-Memory Only (No session_id)")
+    print("=" * 60)
+    
+    # Agent without session_id - in-memory only
+    agent = Agent(
+        name="TempBot",
+        instructions="You are a helpful assistant. Be very brief.",
+        verbose=False,
+    )
+    
+    print("\n[User]: My name is Alice.")
+    response1 = agent.chat("My name is Alice.")
+    print(f"[Assistant]: {response1}")
+    
+    print("\n[User]: What is my name?")
+    response2 = agent.chat("What is my name?")
+    print(f"[Assistant]: {response2}")
+    
+    print(f"\n✅ In-memory chat history: {len(agent.chat_history)} messages")
+    print("   (This will be lost when the Agent instance is garbage collected)")
+
+
+def example_direct_store_access():
+    """Demonstrates direct access to the session store."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 4: Direct Session Store Access")
+    print("=" * 60)
+    
+    from praisonaiagents.session import get_default_session_store
+    
+    store = get_default_session_store()
+    session_id = "demo-direct-access"
+    
+    # Add messages directly
+    store.add_user_message(session_id, "Hello from direct access!")
+    store.add_assistant_message(session_id, "Hi! I received your message.")
+    
+    # Get history
+    history = store.get_chat_history(session_id)
+    print(f"\n✅ Added {len(history)} messages directly to session store")
+    
+    for msg in history:
+        print(f"   [{msg['role']}]: {msg['content']}")
+    
+    # List all sessions
+    sessions = store.list_sessions()
+    print(f"\n📋 Total sessions in store: {len(sessions)}")
+    
+    # Clean up demo session
+    store.delete_session(session_id)
+    print(f"   Deleted demo session: {session_id}")
+
+
+def main():
+    """Run all examples."""
+    print("\n" + "=" * 60)
+    print("SESSION PERSISTENCE EXAMPLES")
+    print("=" * 60)
+    
+    # Run examples
+    example_basic_persistence()
+    example_session_restoration()
+    example_in_memory_only()
+    example_direct_store_access()
+    
+    print("\n" + "=" * 60)
+    print("ALL EXAMPLES COMPLETE")
+    print("=" * 60)
+    print("\nSession files are stored in: ~/.praison/sessions/")
+    print("You can inspect them with: cat ~/.praison/sessions/<session_id>.json")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/README.md

@@ -0,0 +1,121 @@
+# RAG Examples
+
+This directory contains comprehensive examples demonstrating RAG (Retrieval Augmented Generation) with PraisonAI Agents.
+
+## Core RAG Concepts
+
+| Example | Description | Key Concepts |
+|---------|-------------|--------------|
+| `basic_retrieval.py` | Fundamental retrieve-then-generate pattern | Knowledge base, context injection |
+| `auto_retrieval.py` | Intelligent retrieval decisions with AutoRagAgent | Conditional RAG, retrieval policies |
+| `chunking_strategies.py` | Document splitting approaches | Paragraph, section, fixed-size chunking |
+| `hybrid_search.py` | Dense + sparse retrieval combination | Semantic search, keyword matching |
+| `reranking.py` | Two-stage retrieval with reranking | Precision optimization, cross-encoders |
+
+## Advanced RAG Patterns
+
+| Example | Description | Key Concepts |
+|---------|-------------|--------------|
+| `multi_document.py` | Synthesizing across multiple sources | Cross-referencing, source diversity |
+| `knowledge_graph.py` | Relationship-aware retrieval | Entity connections, multi-hop reasoning |
+| `external_sources.py` | Web, API, and database augmentation | Real-time data, hybrid sources |
+| `structured_output.py` | Guided and constrained generation | JSON output, Pydantic schemas |
+| `retrieval_policies.py` | Agent-decided retrieval strategies | Adaptive top-k, priority filtering |
+| `citations.py` | Source attribution and verification | Inline citations, verification |
+
+## Application Examples
+
+### PDF Q&A (`rag_pdf_qa.py`)
+
+Basic RAG example showing how to:
+- Use Agent with knowledge parameter
+- Create explicit RAG pipeline with citations
+- Stream responses
+
+```bash
+python rag_pdf_qa.py
+```
+
+### Multi-Agent RAG (`rag_multi_agent.py`)
+
+Advanced example showing:
+- Shared knowledge base across multiple agents
+- Collaborative RAG workflow
+- Sequential task processing
+
+```bash
+python rag_multi_agent.py
+```
+
+### RAG Evaluation (`rag_evaluation.py`)
+
+Evaluation example showing:
+- Golden query testing
+- Retrieval accuracy metrics
+- Answer relevance checking
+
+```bash
+python rag_evaluation.py
+```
+
+## Quick Start
+
+Run any example:
+
+```bash
+# Basic RAG
+python basic_retrieval.py
+
+# Auto RAG with intelligent decisions
+python auto_retrieval.py
+
+# Hybrid search (dense + sparse)
+python hybrid_search.py
+
+# RAG with citations
+python citations.py
+```
+
+## Installation
+
+```bash
+pip install "praisonaiagents[knowledge]"
+```
+
+## CLI Usage
+
+```bash
+# Index documents
+praisonai rag index ./documents --collection my_docs
+
+# Query
+praisonai rag query "What is the main finding?" --collection my_docs
+
+# Interactive chat
+praisonai rag chat --collection my_docs
+
+# Evaluate
+praisonai rag eval golden_queries.json --collection my_docs
+```
+
+## Configuration
+
+Create `rag_config.yaml`:
+
+```yaml
+knowledge:
+  collection: my_docs
+  chunking:
+    strategy: recursive
+    chunk_size: 512
+
+rag:
+  top_k: 5
+  min_score: 0.3
+  include_citations: true
+```
+
+Use with:
+```bash
+praisonai rag query "Question" --config rag_config.yaml
+```

examples/rag/auto_retrieval.py

@@ -0,0 +1,207 @@
+"""
+Auto RAG: Intelligent Retrieval Decisions
+
+This example demonstrates AutoRagAgent - an agent that automatically decides
+when to retrieve context based on the query type.
+
+RAG Concept: Conditional retrieval - not every query needs RAG. Simple greetings
+or general knowledge questions can be answered directly, while domain-specific
+questions benefit from retrieval.
+"""
+
+from praisonaiagents import Agent, AutoRagAgent
+
+# Sample knowledge base: Software development best practices as text strings
+DEV_PRACTICES = [
+    """Code Review Guidelines:
+    - Review code within 24 hours of submission
+    - Focus on logic, security, and maintainability
+    - Limit reviews to 400 lines of code at a time
+    - Use constructive language and suggest alternatives
+    - Automate style checks with linters""",
+    
+    """Testing Strategy:
+    - Aim for 80% code coverage minimum
+    - Write unit tests before integration tests
+    - Use mocking for external dependencies
+    - Run tests in CI/CD pipeline before merge
+    - Include edge cases and error scenarios""",
+    
+    """Documentation Standards:
+    - Document public APIs with examples
+    - Keep README files up to date
+    - Use inline comments for complex logic only
+    - Maintain a changelog for version history
+    - Include setup instructions for new developers""",
+    
+    """Security Practices:
+    - Never commit secrets or API keys
+    - Use environment variables for configuration
+    - Validate all user inputs
+    - Keep dependencies updated
+    - Conduct regular security audits"""
+]
+
+
+def auto_rag_basic():
+    """Demonstrate AutoRagAgent with automatic retrieval decisions."""
+    
+    # Build context from knowledge
+    context = "\n\n".join(DEV_PRACTICES)
+    
+    # Create base agent with context in instructions
+    base_agent = Agent(
+        name="Dev Coach",
+        instructions=f"""You are a software development coach.
+        Answer questions about development best practices.
+        Be concise and practical in your responses.
+        
+        KNOWLEDGE BASE:
+        {context}""",
+        verbose=False
+    )
+    
+    # Wrap with AutoRagAgent for intelligent retrieval
+    auto_agent = AutoRagAgent(agent=base_agent)
+    
+    # Mix of queries - some need retrieval, some don't
+    queries = [
+        # Should trigger retrieval (domain-specific)
+        "What are the code review guidelines?",
+        "How much code coverage should we aim for?",
+        
+        # Should skip retrieval (general/greeting)
+        "Hello, how are you?",
+        "What is 2 + 2?",
+        
+        # Should trigger retrieval (domain-specific)
+        "What security practices should we follow?",
+    ]
+    
+    print("=" * 60)
+    print("AUTO RAG: Intelligent Retrieval Decisions")
+    print("=" * 60)
+    print("\nAutoRagAgent decides when to retrieve based on query type.\n")
+    
+    for query in queries:
+        print(f"📝 Query: {query}")
+        response = auto_agent.chat(query)
+        print(f"💡 Answer: {response[:200]}..." if len(str(response)) > 200 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def auto_rag_with_policies():
+    """Demonstrate different retrieval policies."""
+    from praisonaiagents import AutoRagConfig
+    from praisonaiagents.agents.auto_rag_agent import RetrievalPolicy
+    
+    # Build context
+    context = "\n\n".join(DEV_PRACTICES)
+    
+    # Create base agent
+    base_agent = Agent(
+        name="Policy Demo Agent",
+        instructions=f"""You answer questions about software development.
+        
+        KNOWLEDGE BASE:
+        {context}""",
+        verbose=False
+    )
+    
+    print("\n" + "=" * 60)
+    print("RETRIEVAL POLICIES COMPARISON")
+    print("=" * 60)
+    
+    query = "What are the documentation standards?"
+    
+    # Policy: AUTO (default) - agent decides
+    auto_config = AutoRagConfig(retrieval_policy=RetrievalPolicy.AUTO)
+    auto_agent = AutoRagAgent(agent=base_agent, config=auto_config)
+    
+    print(f"\n📝 Query: {query}")
+    print("\n🔄 Policy: AUTO (agent decides)")
+    response = auto_agent.chat(query)
+    print(f"   Answer: {response[:150]}...")
+    
+    # Policy: ALWAYS - always retrieve
+    always_config = AutoRagConfig(retrieval_policy=RetrievalPolicy.ALWAYS)
+    always_agent = AutoRagAgent(agent=base_agent, config=always_config)
+    
+    print("\n🔄 Policy: ALWAYS (force retrieval)")
+    response = always_agent.chat(query)
+    print(f"   Answer: {response[:150]}...")
+    
+    # Policy: NEVER - never retrieve (use parametric knowledge only)
+    never_config = AutoRagConfig(retrieval_policy=RetrievalPolicy.NEVER)
+    never_agent = AutoRagAgent(agent=base_agent, config=never_config)
+    
+    print("\n🔄 Policy: NEVER (no retrieval)")
+    response = never_agent.chat(query)
+    print(f"   Answer: {response[:150]}...")
+
+
+def auto_rag_config_options():
+    """Demonstrate AutoRagConfig options."""
+    from praisonaiagents import AutoRagConfig
+    
+    # Build context
+    context = "\n\n".join(DEV_PRACTICES)
+    
+    base_agent = Agent(
+        name="Config Demo",
+        instructions=f"""You are a helpful assistant with development knowledge.
+        
+        KNOWLEDGE BASE:
+        {context}""",
+        verbose=False
+    )
+    
+    print("\n" + "=" * 60)
+    print("AUTO RAG CONFIG OPTIONS")
+    print("=" * 60)
+    
+    # Config with citations enabled
+    config_with_citations = AutoRagConfig(
+        include_citations=True,
+        top_k=3,
+        max_context_tokens=2000
+    )
+    agent_with_citations = AutoRagAgent(agent=base_agent, config=config_with_citations)
+    
+    query = "What testing practices should we follow?"
+    print(f"\n📝 Query: {query}")
+    
+    print("\n🔄 With citations enabled (top_k=3):")
+    response = agent_with_citations.chat(query)
+    print(f"   {response[:200]}...")
+    
+    # Config without citations
+    config_no_citations = AutoRagConfig(
+        include_citations=False,
+        top_k=5
+    )
+    agent_no_citations = AutoRagAgent(agent=base_agent, config=config_no_citations)
+    
+    print("\n🔄 Without citations (top_k=5):")
+    response = agent_no_citations.chat(query)
+    print(f"   {response[:200]}...")
+
+
+def main():
+    """Run all auto RAG examples."""
+    print("\n🚀 PraisonAI Auto RAG Examples\n")
+    
+    # Example 1: Basic AutoRagAgent
+    auto_rag_basic()
+    
+    # Example 2: Different retrieval policies
+    auto_rag_with_policies()
+    
+    # Example 3: Config options
+    auto_rag_config_options()
+    
+    print("\n✅ Auto RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/basic_retrieval.py

@@ -0,0 +1,131 @@
+"""
+Basic RAG: Retrieve and Generate
+
+This example demonstrates the fundamental RAG pattern in PraisonAI:
+1. Provide context to an agent
+2. Agent uses context to answer questions accurately
+3. Generate grounded answers using the provided context
+
+RAG Concept: The core retrieve-then-generate pattern that grounds LLM responses
+in factual content, reducing hallucinations.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Technology company profiles as text strings
+COMPANY_PROFILES = [
+    """NovaTech Solutions specializes in cloud infrastructure and DevOps automation.
+    Founded in 2018, they serve over 500 enterprise clients globally.
+    Key products: CloudSync (infrastructure orchestration), DevPipeline (CI/CD platform).
+    Headquarters: Austin, Texas. Employees: 1,200.""",
+    
+    """GreenLeaf Analytics provides environmental monitoring and sustainability reporting.
+    Established in 2015, they work with governments and corporations on climate data.
+    Key products: EcoTrack (emissions monitoring), SustainReport (ESG reporting).
+    Headquarters: Seattle, Washington. Employees: 450.""",
+    
+    """QuantumBridge Financial offers algorithmic trading and risk management solutions.
+    Started in 2012, they manage over $50 billion in assets for institutional clients.
+    Key products: AlgoTrader Pro (trading platform), RiskShield (portfolio analytics).
+    Headquarters: New York City. Employees: 800.""",
+    
+    """MediCore Health develops AI-powered diagnostic tools for healthcare providers.
+    Founded in 2019, they partner with 200+ hospitals across North America.
+    Key products: DiagnosAI (medical imaging analysis), PatientFlow (care coordination).
+    Headquarters: Boston, Massachusetts. Employees: 350."""
+]
+
+
+def basic_rag_example():
+    """Demonstrate basic RAG with context injection."""
+    
+    # Build context from knowledge base
+    context = "\n\n".join(COMPANY_PROFILES)
+    
+    # Create an agent with instructions
+    agent = Agent(
+        name="Company Analyst",
+        instructions=f"""You are a business analyst who answers questions about companies.
+        Use only the following company information to answer questions accurately.
+        If the information isn't available, say so clearly.
+        
+        COMPANY DATABASE:
+        {context}""",
+        verbose=False
+    )
+    
+    # Test queries
+    queries = [
+        "What products does NovaTech Solutions offer?",
+        "Which company focuses on environmental monitoring?",
+        "How many employees does QuantumBridge Financial have?",
+        "What is MediCore Health's main focus area?"
+    ]
+    
+    print("=" * 60)
+    print("BASIC RAG EXAMPLE: Company Knowledge Base")
+    print("=" * 60)
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def rag_with_query_context():
+    """Demonstrate per-query context injection for RAG."""
+    
+    # Create a general agent
+    agent = Agent(
+        name="Research Assistant",
+        instructions="You answer questions based on the context provided in each query.",
+        verbose=False
+    )
+    
+    # Simulate retrieved context (in real RAG, this comes from vector search)
+    retrieved_context = """
+    The Pacific Ocean is the largest and deepest ocean on Earth.
+    It covers approximately 165.25 million square kilometers.
+    The Mariana Trench, located in the Pacific, is the deepest known point at 10,994 meters.
+    The Pacific Ocean was named by explorer Ferdinand Magellan in 1520.
+    """
+    
+    query = "What is the deepest point in the Pacific Ocean?"
+    
+    # Build prompt with context (RAG pattern)
+    prompt_with_context = f"""Use the following context to answer the question.
+
+Context:
+{retrieved_context}
+
+Question: {query}
+
+Answer based only on the context provided:"""
+    
+    print("\n" + "=" * 60)
+    print("RAG WITH PER-QUERY CONTEXT INJECTION")
+    print("=" * 60)
+    
+    print(f"\n📚 Context: {retrieved_context[:100]}...")
+    print(f"\n📝 Query: {query}")
+    
+    response = agent.chat(prompt_with_context)
+    print(f"\n💡 Answer: {response}")
+
+
+def main():
+    """Run all basic RAG examples."""
+    print("\n🚀 PraisonAI Basic RAG Examples\n")
+    
+    # Example 1: Basic RAG with knowledge base
+    basic_rag_example()
+    
+    # Example 2: Per-query context injection
+    rag_with_query_context()
+    
+    print("\n✅ Basic RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/chunking_strategies.py

@@ -0,0 +1,272 @@
+"""
+Chunking Strategies for RAG
+
+This example demonstrates different approaches to splitting documents into
+chunks for effective retrieval.
+
+RAG Concept: Chunking is critical for RAG quality. Too large chunks dilute
+relevance; too small chunks lose context. The right strategy depends on
+your content type and query patterns.
+"""
+
+from praisonaiagents import Agent
+
+# Sample long document: Product documentation
+PRODUCT_DOCUMENTATION = """
+# CloudManager Pro - Complete User Guide
+
+## Chapter 1: Getting Started
+
+CloudManager Pro is an enterprise cloud management platform that helps organizations
+monitor, optimize, and secure their multi-cloud infrastructure. This guide covers
+installation, configuration, and daily operations.
+
+### 1.1 System Requirements
+
+Before installing CloudManager Pro, ensure your system meets these requirements:
+- Operating System: Ubuntu 20.04+, RHEL 8+, or Windows Server 2019+
+- Memory: Minimum 16GB RAM, recommended 32GB for production
+- Storage: 100GB SSD for application, additional storage for logs
+- Network: Outbound HTTPS access to cloud provider APIs
+
+### 1.2 Installation Steps
+
+1. Download the installer from the customer portal
+2. Run the installation script with root privileges
+3. Configure the database connection
+4. Set up the initial admin account
+5. Verify the installation with the health check command
+
+## Chapter 2: Dashboard Overview
+
+The main dashboard provides a unified view of your cloud resources across all
+connected providers. Key metrics displayed include:
+
+### 2.1 Resource Metrics
+
+- Total compute instances across all clouds
+- Storage utilization and growth trends
+- Network bandwidth consumption
+- Cost breakdown by provider and project
+
+### 2.2 Alert Summary
+
+The alert panel shows active incidents categorized by severity:
+- Critical: Immediate action required (service outages)
+- Warning: Attention needed within 24 hours
+- Info: Informational notifications
+
+## Chapter 3: Cost Optimization
+
+CloudManager Pro includes powerful cost optimization features that can reduce
+your cloud spending by 20-40%.
+
+### 3.1 Right-sizing Recommendations
+
+The platform analyzes resource utilization patterns and suggests optimal
+instance sizes. Recommendations are based on:
+- CPU utilization over 14-day periods
+- Memory usage patterns
+- Network I/O requirements
+
+### 3.2 Reserved Instance Planning
+
+Use the RI Planner to identify opportunities for reserved instance purchases.
+The tool calculates potential savings based on your usage patterns and
+commitment preferences (1-year vs 3-year terms).
+
+## Chapter 4: Security Features
+
+### 4.1 Compliance Monitoring
+
+CloudManager Pro continuously monitors your infrastructure against common
+compliance frameworks including SOC 2, HIPAA, and PCI-DSS. Non-compliant
+resources are flagged with remediation guidance.
+
+### 4.2 Access Control
+
+Role-based access control (RBAC) allows fine-grained permissions:
+- Admin: Full access to all features
+- Operator: Can view and modify resources
+- Viewer: Read-only access to dashboards
+- Billing: Access to cost and billing features only
+"""
+
+
+def chunk_by_paragraphs(text: str, min_length: int = 100) -> list:
+    """Split text into paragraph-based chunks."""
+    paragraphs = text.split("\n\n")
+    chunks = []
+    current_chunk = ""
+    
+    for para in paragraphs:
+        para = para.strip()
+        if not para:
+            continue
+            
+        if len(current_chunk) + len(para) < 500:
+            current_chunk += "\n\n" + para if current_chunk else para
+        else:
+            if len(current_chunk) >= min_length:
+                chunks.append({"content": current_chunk.strip()})
+            current_chunk = para
+    
+    if current_chunk and len(current_chunk) >= min_length:
+        chunks.append({"content": current_chunk.strip()})
+    
+    return chunks
+
+
+def chunk_by_sections(text: str) -> list:
+    """Split text by markdown headers (sections)."""
+    import re
+    
+    # Split by headers (## or ###)
+    sections = re.split(r'\n(?=##+ )', text)
+    chunks = []
+    
+    for section in sections:
+        section = section.strip()
+        if len(section) > 50:  # Skip very short sections
+            # Extract title if present
+            lines = section.split('\n')
+            title = lines[0].replace('#', '').strip() if lines[0].startswith('#') else "Untitled"
+            chunks.append({
+                "id": title.lower().replace(' ', '_')[:30],
+                "content": section
+            })
+    
+    return chunks
+
+
+def chunk_by_fixed_size(text: str, chunk_size: int = 500, overlap: int = 50) -> list:
+    """Split text into fixed-size chunks with overlap."""
+    chunks = []
+    start = 0
+    
+    while start < len(text):
+        end = start + chunk_size
+        chunk_text = text[start:end]
+        
+        # Try to break at sentence boundary
+        if end < len(text):
+            last_period = chunk_text.rfind('.')
+            if last_period > chunk_size * 0.5:
+                end = start + last_period + 1
+                chunk_text = text[start:end]
+        
+        chunks.append({"content": chunk_text.strip()})
+        start = end - overlap
+    
+    return chunks
+
+
+def demonstrate_chunking_strategies():
+    """Show different chunking approaches and their effects."""
+    
+    print("=" * 60)
+    print("CHUNKING STRATEGIES COMPARISON")
+    print("=" * 60)
+    
+    # Strategy 1: Paragraph-based chunking
+    para_chunks = chunk_by_paragraphs(PRODUCT_DOCUMENTATION)
+    print(f"\n📄 Paragraph Chunking: {len(para_chunks)} chunks")
+    print(f"   Average chunk size: {sum(len(c['content']) for c in para_chunks) // len(para_chunks)} chars")
+    print(f"   Sample chunk: {para_chunks[0]['content'][:100]}...")
+    
+    # Strategy 2: Section-based chunking
+    section_chunks = chunk_by_sections(PRODUCT_DOCUMENTATION)
+    print(f"\n📑 Section Chunking: {len(section_chunks)} chunks")
+    print(f"   Average chunk size: {sum(len(c['content']) for c in section_chunks) // len(section_chunks)} chars")
+    print(f"   Sections: {[c['id'] for c in section_chunks[:5]]}...")
+    
+    # Strategy 3: Fixed-size chunking
+    fixed_chunks = chunk_by_fixed_size(PRODUCT_DOCUMENTATION, chunk_size=400, overlap=50)
+    print(f"\n📏 Fixed-Size Chunking (400 chars, 50 overlap): {len(fixed_chunks)} chunks")
+    print(f"   Average chunk size: {sum(len(c['content']) for c in fixed_chunks) // len(fixed_chunks)} chars")
+
+
+def rag_with_section_chunks():
+    """Demonstrate RAG using section-based chunks."""
+    
+    # Create section-based chunks
+    chunks = chunk_by_sections(PRODUCT_DOCUMENTATION)
+    
+    # Build context from chunks
+    context = "\n\n".join([f"[{c['id']}]\n{c['content']}" for c in chunks])
+    
+    # Create agent with chunked knowledge in instructions
+    agent = Agent(
+        name="Product Expert",
+        instructions=f"""You are a CloudManager Pro product expert.
+        Answer questions using the product documentation.
+        Be specific and reference relevant sections when helpful.
+        
+        PRODUCT DOCUMENTATION:
+        {context}""",
+        verbose=False
+    )
+    
+    queries = [
+        "What are the system requirements for CloudManager Pro?",
+        "How can I reduce cloud costs?",
+        "What compliance frameworks are supported?"
+    ]
+    
+    print("\n" + "=" * 60)
+    print("RAG WITH SECTION-BASED CHUNKS")
+    print("=" * 60)
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response[:250]}..." if len(str(response)) > 250 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def semantic_chunking_concept():
+    """Explain semantic chunking concept (agent-driven)."""
+    
+    print("\n" + "=" * 60)
+    print("SEMANTIC CHUNKING CONCEPT")
+    print("=" * 60)
+    
+    print("""
+    Semantic chunking goes beyond fixed rules by considering meaning:
+    
+    1. **Sentence Embedding Similarity**
+       - Compute embeddings for each sentence
+       - Group sentences with similar embeddings
+       - Split when similarity drops below threshold
+    
+    2. **Topic-Based Chunking**
+       - Identify topic shifts in the document
+       - Create chunks that maintain topical coherence
+    
+    3. **Agent-Driven Chunking**
+       - Use an LLM to identify logical boundaries
+       - Preserve context and relationships
+    
+    PraisonAI's Knowledge system handles chunking automatically,
+    but understanding these strategies helps optimize retrieval quality.
+    """)
+
+
+def main():
+    """Run all chunking strategy examples."""
+    print("\n🚀 PraisonAI Chunking Strategies Examples\n")
+    
+    # Example 1: Compare chunking strategies
+    demonstrate_chunking_strategies()
+    
+    # Example 2: RAG with section chunks
+    rag_with_section_chunks()
+    
+    # Example 3: Semantic chunking concept
+    semantic_chunking_concept()
+    
+    print("\n✅ Chunking strategy examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/citations.py

@@ -0,0 +1,370 @@
+"""
+RAG with Citations: Source Attribution and Verification
+
+This example demonstrates how to include citations and source references
+in RAG responses for transparency and verification.
+
+RAG Concept: Trust in AI-generated answers requires verification. Citations
+link answers back to source documents, enabling fact-checking and building
+user confidence.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Legal documents with clear sources
+LEGAL_DOCUMENTS = [
+    {
+        "id": "policy_001",
+        "source": "Employee Handbook v2024",
+        "section": "Section 3.2 - Leave Policies",
+        "content": """
+        Annual Leave Entitlement:
+        - Full-time employees: 20 days per year
+        - Part-time employees: Pro-rated based on hours
+        - Unused leave: Up to 5 days may carry over to next year
+        - Leave requests: Submit at least 2 weeks in advance
+        - Approval: Manager approval required for leave > 3 consecutive days
+        """
+    },
+    {
+        "id": "policy_002",
+        "source": "Employee Handbook v2024",
+        "section": "Section 4.1 - Remote Work",
+        "content": """
+        Remote Work Policy:
+        - Eligibility: Employees in approved roles after 6 months tenure
+        - Maximum: 3 days per week remote work allowed
+        - Requirements: Reliable internet, dedicated workspace
+        - Core hours: Must be available 10am-3pm local time
+        - Equipment: Company provides laptop; employee provides internet
+        """
+    },
+    {
+        "id": "policy_003",
+        "source": "Benefits Guide 2024",
+        "section": "Chapter 2 - Health Insurance",
+        "content": """
+        Health Insurance Coverage:
+        - Provider: BlueCross BlueShield
+        - Coverage: Employee + dependents eligible
+        - Premium: Company pays 80%, employee pays 20%
+        - Deductible: $500 individual, $1000 family
+        - Enrollment: During annual open enrollment or qualifying life event
+        """
+    },
+    {
+        "id": "policy_004",
+        "source": "Benefits Guide 2024",
+        "section": "Chapter 5 - Retirement",
+        "content": """
+        401(k) Retirement Plan:
+        - Eligibility: After 90 days of employment
+        - Company match: 100% up to 4% of salary
+        - Vesting: Immediate vesting for employee contributions
+        - Company match vesting: 3-year graded schedule
+        - Investment options: 15 fund choices available
+        """
+    },
+    {
+        "id": "policy_005",
+        "source": "Code of Conduct 2024",
+        "section": "Article 7 - Conflicts of Interest",
+        "content": """
+        Conflict of Interest Policy:
+        - Disclosure: All potential conflicts must be disclosed to HR
+        - Outside employment: Requires written approval
+        - Financial interests: Cannot hold >5% in competitors
+        - Gifts: Cannot accept gifts valued over $50
+        - Relationships: Must disclose family relationships with vendors
+        """
+    }
+]
+
+
+def basic_citations():
+    """Demonstrate basic citation inclusion in RAG responses."""
+    
+    print("=" * 60)
+    print("BASIC CITATIONS IN RAG")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['source']}, {d['section']}]\n{d['content']}" for d in LEGAL_DOCUMENTS])
+    
+    agent = Agent(
+        name="HR Policy Expert",
+        instructions=f"""You are an HR policy expert who answers employee questions.
+        
+        IMPORTANT: Always cite your sources using this format:
+        [Source: Document Name, Section]
+        
+        Include the citation immediately after the relevant information.
+        If information comes from multiple sources, cite each one.
+        
+        POLICY DOCUMENTS:
+        {context}""",
+        verbose=False
+    )
+    
+    queries = [
+        "How many vacation days do I get?",
+        "Can I work from home?",
+        "What's the company match for 401k?"
+    ]
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer with Citations:\n{response}")
+        print("-" * 40)
+
+
+def structured_citations():
+    """Demonstrate structured citation format."""
+    
+    print("\n" + "=" * 60)
+    print("STRUCTURED CITATIONS")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['source']}, {d['section']}]\n{d['content']}" for d in LEGAL_DOCUMENTS])
+    
+    agent = Agent(
+        name="Policy Researcher",
+        instructions=f"""You provide policy information with structured citations.
+        
+        Format your response as:
+        
+        ANSWER:
+        [Your answer here]
+        
+        SOURCES:
+        1. [Document] - [Section] - [Relevant quote]
+        2. [Document] - [Section] - [Relevant quote]
+        
+        Always include at least one source citation.
+        
+        POLICY DOCUMENTS:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "What are the requirements for remote work eligibility?"
+    
+    print(f"\n📝 Query: {query}")
+    response = agent.chat(query)
+    print(f"\n💡 Structured Response:\n{response}")
+
+
+def inline_citations():
+    """Demonstrate inline citation style."""
+    
+    print("\n" + "=" * 60)
+    print("INLINE CITATIONS (Academic Style)")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['source']}, {d['section']}]\n{d['content']}" for d in LEGAL_DOCUMENTS])
+    
+    agent = Agent(
+        name="Academic Researcher",
+        instructions=f"""You write responses with inline citations like academic papers.
+        
+        Use numbered citations [1], [2], etc. in the text.
+        List full references at the end.
+        
+        Example:
+        "Employees receive 20 days of leave [1]. Remote work is allowed
+        for up to 3 days per week [2]."
+        
+        References:
+        [1] Employee Handbook v2024, Section 3.2
+        [2] Employee Handbook v2024, Section 4.1
+        
+        POLICY DOCUMENTS:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "Summarize the key employee benefits."
+    
+    print(f"\n📝 Query: {query}")
+    response = agent.chat(query)
+    print(f"\n💡 Academic-Style Response:\n{response}")
+
+
+def citation_verification():
+    """Demonstrate citation verification concept."""
+    
+    print("\n" + "=" * 60)
+    print("CITATION VERIFICATION")
+    print("=" * 60)
+    
+    print("""
+    🔍 Citation Verification Process:
+    
+    1. **Extract Citations**
+       Parse the agent's response to find citation markers
+       
+    2. **Locate Source Documents**
+       Match citations to documents in knowledge base
+       
+    3. **Verify Claims**
+       Check if the cited text supports the claim
+       
+    4. **Flag Discrepancies**
+       Highlight any mismatches or unsupported claims
+    
+    Example Verification:
+    """)
+    
+    # Simulated verification
+    claim = "Employees get 20 days of annual leave"
+    cited_source = "Employee Handbook v2024, Section 3.2"
+    source_text = "Full-time employees: 20 days per year"
+    
+    print(f"   Claim: \"{claim}\"")
+    print(f"   Citation: {cited_source}")
+    print(f"   Source Text: \"{source_text}\"")
+    print("   Verification: ✅ SUPPORTED")
+    
+    print("""
+    
+    Implementation:
+    ```python
+    def verify_citation(claim: str, source_id: str, knowledge) -> bool:
+        # Get source document
+        source = knowledge.get(source_id)
+        
+        # Check if claim is supported by source
+        # (In practice, use semantic similarity)
+        return claim_supported_by_source(claim, source)
+    ```
+    """)
+
+
+def multi_source_synthesis():
+    """Demonstrate synthesizing from multiple sources with citations."""
+    
+    print("\n" + "=" * 60)
+    print("MULTI-SOURCE SYNTHESIS WITH CITATIONS")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['source']}, {d['section']}]\n{d['content']}" for d in LEGAL_DOCUMENTS])
+    
+    agent = Agent(
+        name="Benefits Advisor",
+        instructions=f"""You synthesize information from multiple policy documents.
+        
+        When answering:
+        1. Gather relevant information from all sources
+        2. Synthesize into a coherent answer
+        3. Cite each source for the specific information it provides
+        4. Note if sources have different or complementary information
+        
+        Format: Include [Source: X] after each piece of information.
+        
+        POLICY DOCUMENTS:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "Give me a complete overview of employee benefits and policies."
+    
+    print(f"\n📝 Query: {query}")
+    response = agent.chat(query)
+    print(f"\n💡 Multi-Source Synthesis:\n{response}")
+
+
+def citation_best_practices():
+    """Share best practices for citations in RAG."""
+    
+    print("\n" + "=" * 60)
+    print("CITATION BEST PRACTICES")
+    print("=" * 60)
+    
+    print("""
+    📚 Best Practices for RAG Citations:
+    
+    1. **Include Metadata in Knowledge Base**
+       ```python
+       documents = [
+           {
+               "id": "doc_001",
+               "source": "Policy Manual",
+               "section": "Chapter 3",
+               "date": "2024-01-15",
+               "author": "HR Department",
+               "content": "..."
+           }
+       ]
+       ```
+    
+    2. **Instruct Agent to Cite**
+       - Be explicit in instructions about citation format
+       - Provide examples of expected citation style
+       - Require citations for factual claims
+    
+    3. **Use Consistent Citation Format**
+       - Inline: [1], [2] with reference list
+       - Parenthetical: (Source, Section)
+       - Footnote style: ¹, ² with notes
+    
+    4. **Enable Verification**
+       - Include document IDs for programmatic lookup
+       - Store enough metadata to locate original
+       - Consider including page numbers or paragraphs
+    
+    5. **Handle Missing Sources**
+       - Instruct agent to acknowledge when info isn't in sources
+       - Distinguish between sourced and general knowledge
+       - Use phrases like "Based on the provided documents..."
+    
+    6. **Citation Granularity**
+       - Document level: Good for general attribution
+       - Section level: Better for verification
+       - Quote level: Best for accuracy-critical applications
+    
+    Example Agent Instructions:
+    ```python
+    instructions = '''
+    Answer questions using the provided documents.
+    
+    Rules:
+    - Cite sources for all factual claims
+    - Use format: [Source: Document Name, Section]
+    - If information isn't in the documents, say so
+    - Never make claims without citation
+    '''
+    ```
+    """)
+
+
+def main():
+    """Run all citation examples."""
+    print("\n🚀 PraisonAI RAG Citations Examples\n")
+    
+    # Example 1: Basic citations
+    basic_citations()
+    
+    # Example 2: Structured citations
+    structured_citations()
+    
+    # Example 3: Inline citations
+    inline_citations()
+    
+    # Example 4: Citation verification
+    citation_verification()
+    
+    # Example 5: Multi-source synthesis
+    multi_source_synthesis()
+    
+    # Example 6: Best practices
+    citation_best_practices()
+    
+    print("\n✅ Citation examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/external_sources.py

@@ -0,0 +1,353 @@
+"""
+External Sources RAG: Beyond Vector Search
+
+This example demonstrates RAG with external knowledge sources like
+web search, APIs, and databases.
+
+RAG Concept: RAG isn't limited to pre-indexed documents. External sources
+provide real-time, up-to-date information that complements static knowledge.
+"""
+
+from praisonaiagents import Agent
+
+# Simulated external data sources
+def mock_web_search(query: str) -> list:
+    """Simulate web search results."""
+    # In production, this would call a real search API
+    mock_results = {
+        "weather": [
+            {"title": "Current Weather", "snippet": "Today's forecast: Partly cloudy, high of 72°F (22°C), low of 58°F (14°C). Humidity at 45%."},
+            {"title": "Weekly Outlook", "snippet": "Rain expected Wednesday and Thursday. Weekend looks sunny with temperatures in the mid-70s."}
+        ],
+        "news": [
+            {"title": "Tech Industry Update", "snippet": "Major tech companies report strong Q3 earnings. AI investments continue to grow across sectors."},
+            {"title": "Market Summary", "snippet": "Stock markets closed higher today. S&P 500 up 0.8%, Nasdaq up 1.2%."}
+        ],
+        "default": [
+            {"title": "General Information", "snippet": "Search results would appear here with relevant web content."}
+        ]
+    }
+    
+    for key in mock_results:
+        if key in query.lower():
+            return mock_results[key]
+    return mock_results["default"]
+
+
+def mock_database_query(query: str) -> dict:
+    """Simulate database query results."""
+    # In production, this would query a real database
+    mock_data = {
+        "user_stats": {
+            "total_users": 15420,
+            "active_today": 3250,
+            "new_signups": 127,
+            "retention_rate": "78%"
+        },
+        "sales_data": {
+            "monthly_revenue": "$1.2M",
+            "top_product": "Enterprise Plan",
+            "growth_rate": "15% MoM",
+            "avg_deal_size": "$4,500"
+        },
+        "system_health": {
+            "uptime": "99.97%",
+            "avg_response_time": "145ms",
+            "error_rate": "0.02%",
+            "active_servers": 24
+        }
+    }
+    
+    for key in mock_data:
+        if key.replace("_", " ") in query.lower() or key in query.lower():
+            return mock_data[key]
+    return {"message": "No matching data found"}
+
+
+def mock_api_call(endpoint: str) -> dict:
+    """Simulate API call results."""
+    # In production, this would call a real API
+    mock_responses = {
+        "stock_price": {"symbol": "ACME", "price": 142.50, "change": "+2.3%"},
+        "exchange_rate": {"from": "USD", "to": "EUR", "rate": 0.92},
+        "crypto": {"bitcoin": "$67,500", "ethereum": "$3,450"}
+    }
+    
+    for key in mock_responses:
+        if key in endpoint.lower():
+            return mock_responses[key]
+    return {"status": "endpoint not found"}
+
+
+# Static knowledge base for hybrid approach
+COMPANY_KNOWLEDGE = [
+    {
+        "id": "company_overview",
+        "content": """
+        Acme Corporation is a technology company founded in 2015.
+        Headquarters: San Francisco, CA
+        Products: Enterprise software, cloud services, AI solutions
+        Mission: Empowering businesses through intelligent automation
+        """
+    },
+    {
+        "id": "product_info",
+        "content": """
+        Acme Products:
+        - Acme Cloud: Infrastructure-as-a-service platform
+        - Acme AI: Machine learning toolkit for enterprises
+        - Acme Connect: Integration and API management
+        Pricing: Starter ($99/mo), Professional ($499/mo), Enterprise (custom)
+        """
+    }
+]
+
+
+def web_augmented_rag():
+    """Demonstrate RAG augmented with web search."""
+    
+    print("=" * 60)
+    print("WEB-AUGMENTED RAG")
+    print("=" * 60)
+    
+    # Build context from company knowledge
+    context = "\n\n".join([f"[{k['id']}]\n{k['content']}" for k in COMPANY_KNOWLEDGE])
+    
+    # Create agent that can use web search
+    agent = Agent(
+        name="Research Assistant",
+        instructions=f"""You are a research assistant that combines internal knowledge
+        with web search results. When answering:
+        1. Check if the question requires current/real-time information
+        2. Use web search for news, weather, current events
+        3. Combine web results with your knowledge for comprehensive answers
+        4. Clearly indicate when information comes from web search.
+        
+        COMPANY KNOWLEDGE:
+        {context}""",
+        verbose=False
+    )
+    
+    # Simulate web-augmented queries
+    queries = [
+        ("What's the weather like today?", True),  # Needs web
+        ("Tell me about Acme Corporation's products", False),  # Static knowledge
+        ("What's happening in the tech industry?", True),  # Needs web
+    ]
+    
+    for query, needs_web in queries:
+        print(f"\n📝 Query: {query}")
+        
+        if needs_web:
+            # Augment with web search
+            web_results = mock_web_search(query)
+            web_context = "\n".join([f"- {r['title']}: {r['snippet']}" for r in web_results])
+            augmented_query = f"{query}\n\nWeb search results:\n{web_context}"
+            response = agent.chat(augmented_query)
+            print("🌐 (Web-augmented)")
+        else:
+            response = agent.chat(query)
+            print("📚 (Static knowledge)")
+        
+        print(f"💡 Answer: {response[:250]}..." if len(str(response)) > 250 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def database_augmented_rag():
+    """Demonstrate RAG augmented with database queries."""
+    
+    print("\n" + "=" * 60)
+    print("DATABASE-AUGMENTED RAG")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{k['id']}]\n{k['content']}" for k in COMPANY_KNOWLEDGE])
+    
+    agent = Agent(
+        name="Business Analyst",
+        instructions=f"""You are a business analyst with access to company databases.
+        Interpret data accurately and provide actionable insights.
+        When presenting numbers, add context and trends.
+        
+        COMPANY KNOWLEDGE:
+        {context}""",
+        verbose=False
+    )
+    
+    queries = [
+        "How are our user stats looking?",
+        "Give me a sales summary",
+        "What's our system health status?"
+    ]
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        
+        # Fetch database data
+        db_data = mock_database_query(query)
+        db_context = f"Database results: {db_data}"
+        
+        augmented_query = f"{query}\n\n{db_context}"
+        response = agent.chat(augmented_query)
+        
+        print(f"🗄️ DB Data: {db_data}")
+        print(f"💡 Analysis: {response[:200]}..." if len(str(response)) > 200 else f"💡 Analysis: {response}")
+        print("-" * 40)
+
+
+def api_augmented_rag():
+    """Demonstrate RAG augmented with API calls."""
+    
+    print("\n" + "=" * 60)
+    print("API-AUGMENTED RAG")
+    print("=" * 60)
+    
+    agent = Agent(
+        name="Financial Assistant",
+        instructions="""You are a financial assistant with access to market APIs.
+        Provide accurate financial information and context.
+        Always note that prices are subject to change.""",
+        user_id="api_demo"
+    )
+    
+    queries = [
+        ("What's the ACME stock price?", "stock_price"),
+        ("USD to EUR exchange rate?", "exchange_rate"),
+        ("Crypto market update?", "crypto")
+    ]
+    
+    for query, endpoint in queries:
+        print(f"\n📝 Query: {query}")
+        
+        # Fetch API data
+        api_data = mock_api_call(endpoint)
+        api_context = f"API response: {api_data}"
+        
+        augmented_query = f"{query}\n\n{api_context}"
+        response = agent.chat(augmented_query)
+        
+        print(f"🔌 API Data: {api_data}")
+        print(f"💡 Response: {response[:200]}..." if len(str(response)) > 200 else f"💡 Response: {response}")
+        print("-" * 40)
+
+
+def hybrid_source_rag():
+    """Combine multiple external sources."""
+    
+    print("\n" + "=" * 60)
+    print("HYBRID SOURCE RAG")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{k['id']}]\n{k['content']}" for k in COMPANY_KNOWLEDGE])
+    
+    agent = Agent(
+        name="Executive Assistant",
+        instructions=f"""You are an executive assistant with access to multiple data sources.
+        Synthesize information from static knowledge, databases, and APIs.
+        Provide comprehensive briefings that combine all relevant data.
+        
+        COMPANY KNOWLEDGE:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "Give me a complete business briefing for today"
+    
+    # Gather from multiple sources
+    db_stats = mock_database_query("user_stats")
+    db_sales = mock_database_query("sales_data")
+    db_health = mock_database_query("system_health")
+    api_stock = mock_api_call("stock_price")
+    web_news = mock_web_search("news")
+    
+    combined_context = f"""
+    User Statistics: {db_stats}
+    Sales Data: {db_sales}
+    System Health: {db_health}
+    Stock Price: {api_stock}
+    Industry News: {[r['snippet'] for r in web_news]}
+    """
+    
+    augmented_query = f"{query}\n\nData from multiple sources:\n{combined_context}"
+    
+    print(f"\n📝 Query: {query}")
+    print("\n📊 Data Sources:")
+    print("   - Database: user_stats, sales_data, system_health")
+    print("   - API: stock_price")
+    print("   - Web: news search")
+    
+    response = agent.chat(augmented_query)
+    print(f"\n💡 Executive Briefing:\n{response}")
+
+
+def external_source_patterns():
+    """Explain external source patterns."""
+    
+    print("\n" + "=" * 60)
+    print("EXTERNAL SOURCE PATTERNS")
+    print("=" * 60)
+    
+    print("""
+    🌐 External Source Integration Patterns:
+    
+    1. **Query-Time Augmentation**
+       - Fetch external data when query arrives
+       - Inject into prompt as additional context
+       - Best for: Real-time data needs
+    
+    2. **Scheduled Refresh**
+       - Periodically update knowledge base from external sources
+       - Index external data for faster retrieval
+       - Best for: Semi-static external data
+    
+    3. **Tool-Based Retrieval**
+       - Give agent tools to fetch external data
+       - Agent decides when to use external sources
+       - Best for: Complex, multi-step queries
+    
+    4. **Hybrid Static + Dynamic**
+       - Combine indexed knowledge with real-time fetches
+       - Use static for stable info, dynamic for current
+       - Best for: Comprehensive answers
+    
+    Implementation Example:
+    ```python
+    def web_search_tool(query: str) -> str:
+        # Call search API
+        results = search_api.search(query)
+        return format_results(results)
+    
+    agent = Agent(
+        knowledge=static_docs,
+        tools=[web_search_tool],
+        instructions="Use web search for current events..."
+    )
+    ```
+    """)
+
+
+def main():
+    """Run all external source RAG examples."""
+    print("\n🚀 PraisonAI External Sources RAG Examples\n")
+    
+    # Example 1: Web-augmented RAG
+    web_augmented_rag()
+    
+    # Example 2: Database-augmented RAG
+    database_augmented_rag()
+    
+    # Example 3: API-augmented RAG
+    api_augmented_rag()
+    
+    # Example 4: Hybrid sources
+    hybrid_source_rag()
+    
+    # Example 5: Patterns
+    external_source_patterns()
+    
+    print("\n✅ External sources RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/hybrid_search.py

@@ -0,0 +1,275 @@
+"""
+Hybrid Search: Combining Dense and Sparse Retrieval
+
+This example demonstrates hybrid retrieval that combines semantic (dense)
+search with keyword (sparse) search for improved accuracy.
+
+RAG Concept: Dense embeddings capture meaning but may miss exact matches.
+Sparse/keyword search finds exact terms but lacks semantic understanding.
+Hybrid search combines both for best results.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Technical troubleshooting guides
+TROUBLESHOOTING_GUIDES = [
+    {
+        "id": "error_001",
+        "content": """
+        Error Code: ERR_CONNECTION_REFUSED
+        
+        This error occurs when the client cannot establish a connection to the server.
+        
+        Common Causes:
+        - Server is not running or has crashed
+        - Firewall blocking the connection port
+        - Incorrect host or port configuration
+        - Network connectivity issues
+        
+        Resolution Steps:
+        1. Verify the server process is running: `systemctl status myservice`
+        2. Check firewall rules: `sudo ufw status`
+        3. Test port connectivity: `telnet hostname 8080`
+        4. Review server logs for startup errors
+        """
+    },
+    {
+        "id": "error_002",
+        "content": """
+        Error Code: ERR_OUT_OF_MEMORY
+        
+        This error indicates the application has exhausted available memory.
+        
+        Common Causes:
+        - Memory leak in application code
+        - Insufficient heap size configuration
+        - Too many concurrent connections
+        - Large data processing without streaming
+        
+        Resolution Steps:
+        1. Increase heap size: `-Xmx4g` for Java applications
+        2. Enable memory profiling to identify leaks
+        3. Implement pagination for large datasets
+        4. Add memory limits to container configurations
+        """
+    },
+    {
+        "id": "error_003",
+        "content": """
+        Error Code: ERR_SSL_CERTIFICATE_EXPIRED
+        
+        This error means the SSL/TLS certificate has passed its validity date.
+        
+        Common Causes:
+        - Certificate not renewed before expiration
+        - Automatic renewal process failed
+        - Wrong certificate installed
+        
+        Resolution Steps:
+        1. Check certificate expiry: `openssl x509 -enddate -noout -in cert.pem`
+        2. Renew certificate with your CA or Let's Encrypt
+        3. Update certificate files on the server
+        4. Restart the web server to load new certificate
+        """
+    },
+    {
+        "id": "error_004",
+        "content": """
+        Error Code: ERR_DATABASE_DEADLOCK
+        
+        A deadlock occurs when two transactions block each other indefinitely.
+        
+        Common Causes:
+        - Transactions acquiring locks in different orders
+        - Long-running transactions holding locks
+        - Missing indexes causing table scans with locks
+        
+        Resolution Steps:
+        1. Review transaction isolation levels
+        2. Ensure consistent lock ordering across queries
+        3. Add appropriate indexes to reduce lock duration
+        4. Implement retry logic for deadlock exceptions
+        """
+    },
+    {
+        "id": "error_005",
+        "content": """
+        Error Code: ERR_RATE_LIMIT_EXCEEDED
+        
+        The API has rejected requests due to exceeding the rate limit.
+        
+        Common Causes:
+        - Too many requests in a short time window
+        - Missing request throttling in client code
+        - Retry loops without backoff
+        
+        Resolution Steps:
+        1. Implement exponential backoff for retries
+        2. Cache responses to reduce API calls
+        3. Use bulk endpoints where available
+        4. Request rate limit increase if needed
+        """
+    }
+]
+
+
+def demonstrate_search_types():
+    """Show the difference between semantic and keyword search concepts."""
+    
+    print("=" * 60)
+    print("SEARCH TYPES COMPARISON")
+    print("=" * 60)
+    
+    print("""
+    📊 DENSE (Semantic) Search:
+       - Uses vector embeddings to capture meaning
+       - "memory issues" matches "out of memory" and "RAM exhausted"
+       - Good for natural language queries
+       - May miss exact technical terms
+    
+    📊 SPARSE (Keyword) Search:
+       - Uses term frequency and exact matching
+       - "ERR_SSL_CERTIFICATE_EXPIRED" matches exactly
+       - Good for error codes, IDs, technical terms
+       - Misses synonyms and paraphrases
+    
+    📊 HYBRID Search:
+       - Combines both approaches
+       - Weighted scoring: (α × dense_score) + ((1-α) × sparse_score)
+       - Best of both worlds for technical documentation
+    """)
+
+
+def hybrid_rag_example():
+    """Demonstrate hybrid retrieval with an agent."""
+    
+    # Build context from troubleshooting guides
+    context = "\n\n".join([f"[{g['id']}]\n{g['content']}" for g in TROUBLESHOOTING_GUIDES])
+    
+    # Create agent with context in instructions
+    agent = Agent(
+        name="Tech Support",
+        instructions=f"""You are a technical support specialist.
+        Help users troubleshoot errors using the knowledge base.
+        Always mention the specific error code when relevant.
+        Provide step-by-step resolution guidance.
+        
+        TROUBLESHOOTING KNOWLEDGE BASE:
+        {context}""",
+        verbose=False
+    )
+    
+    # Test with different query types
+    queries = [
+        # Semantic query (natural language)
+        "My application is running out of memory, what should I do?",
+        
+        # Exact match query (error code)
+        "ERR_SSL_CERTIFICATE_EXPIRED",
+        
+        # Mixed query
+        "Getting connection refused error when connecting to port 8080",
+        
+        # Conceptual query
+        "How do I handle API throttling?"
+    ]
+    
+    print("\n" + "=" * 60)
+    print("HYBRID RAG IN ACTION")
+    print("=" * 60)
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response[:300]}..." if len(str(response)) > 300 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def compare_retrieval_modes():
+    """Compare results with different retrieval configurations."""
+    
+    print("\n" + "=" * 60)
+    print("RETRIEVAL MODE COMPARISON")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{g['id']}]\n{g['content']}" for g in TROUBLESHOOTING_GUIDES])
+    
+    query = "database transaction blocking issue"
+    
+    # Agent with context
+    agent = Agent(
+        name="Search Agent",
+        instructions=f"""Answer based on the knowledge provided.
+        
+        KNOWLEDGE BASE:
+        {context}""",
+        verbose=False
+    )
+    
+    print(f"\n📝 Query: {query}")
+    
+    print("\n🔍 RAG Response:")
+    response = agent.chat(query)
+    print(f"   {response[:200]}...")
+    
+    print("\n💡 Note: Hybrid search combines semantic + keyword matching for best results.")
+
+
+def hybrid_search_tuning():
+    """Explain hybrid search tuning parameters."""
+    
+    print("\n" + "=" * 60)
+    print("HYBRID SEARCH TUNING")
+    print("=" * 60)
+    
+    print("""
+    Key parameters for hybrid search optimization:
+    
+    1. **Alpha (α) Weight** - Balance between dense and sparse
+       - α = 1.0: Pure semantic search
+       - α = 0.5: Equal weight (good default)
+       - α = 0.0: Pure keyword search
+    
+    2. **Top-K Retrieval** - Number of candidates
+       - Higher K: More context, slower, may dilute relevance
+       - Lower K: Faster, focused, may miss relevant docs
+       - Typical range: 3-10 for RAG
+    
+    3. **Reranking** - Second-pass scoring
+       - Cross-encoder reranking improves precision
+       - Adds latency but improves quality
+    
+    Example configuration:
+    ```python
+    knowledge_config = {
+        "hybrid": True,
+        "hybrid_alpha": 0.6,  # Favor semantic
+        "top_k": 5,
+        "rerank": True
+    }
+    ```
+    """)
+
+
+def main():
+    """Run all hybrid search examples."""
+    print("\n🚀 PraisonAI Hybrid Search Examples\n")
+    
+    # Example 1: Explain search types
+    demonstrate_search_types()
+    
+    # Example 2: Hybrid RAG in action
+    hybrid_rag_example()
+    
+    # Example 3: Compare retrieval modes
+    compare_retrieval_modes()
+    
+    # Example 4: Tuning guidance
+    hybrid_search_tuning()
+    
+    print("\n✅ Hybrid search examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/knowledge_graph.py

@@ -0,0 +1,304 @@
+"""
+Graph-Assisted RAG: Relationship-Aware Retrieval
+
+This example demonstrates how graph structures can enhance RAG by
+capturing relationships between entities and enabling path-based retrieval.
+
+RAG Concept: Traditional vector search finds similar documents but misses
+relationships. Graph-assisted RAG understands connections between entities,
+enabling multi-hop reasoning and relationship-aware answers.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Interconnected entities (simulating a knowledge graph)
+ENTITY_KNOWLEDGE = [
+    {
+        "id": "person_einstein",
+        "type": "person",
+        "content": """
+        Albert Einstein (1879-1955) was a theoretical physicist who developed
+        the theory of relativity. He received the Nobel Prize in Physics in 1921
+        for his explanation of the photoelectric effect. Einstein worked at the
+        Institute for Advanced Study in Princeton from 1933 until his death.
+        Key relationships: Collaborated with Niels Bohr, influenced by Max Planck,
+        mentored by Heinrich Weber.
+        """
+    },
+    {
+        "id": "person_bohr",
+        "type": "person",
+        "content": """
+        Niels Bohr (1885-1962) was a Danish physicist who made foundational
+        contributions to understanding atomic structure and quantum theory.
+        He received the Nobel Prize in Physics in 1922. Bohr founded the
+        Institute of Theoretical Physics in Copenhagen.
+        Key relationships: Debated with Einstein on quantum mechanics,
+        mentored Werner Heisenberg, influenced by Ernest Rutherford.
+        """
+    },
+    {
+        "id": "person_heisenberg",
+        "type": "person",
+        "content": """
+        Werner Heisenberg (1901-1976) was a German physicist and pioneer of
+        quantum mechanics. He formulated the uncertainty principle in 1927.
+        He received the Nobel Prize in Physics in 1932.
+        Key relationships: Student of Niels Bohr, collaborated with Max Born,
+        worked with Wolfgang Pauli.
+        """
+    },
+    {
+        "id": "concept_relativity",
+        "type": "concept",
+        "content": """
+        Theory of Relativity: A framework developed by Albert Einstein consisting
+        of special relativity (1905) and general relativity (1915). Special
+        relativity deals with objects moving at constant speeds, introducing
+        E=mc². General relativity describes gravity as the curvature of spacetime.
+        Related concepts: Spacetime, time dilation, gravitational waves.
+        Applications: GPS satellites, particle accelerators, cosmology.
+        """
+    },
+    {
+        "id": "concept_quantum",
+        "type": "concept",
+        "content": """
+        Quantum Mechanics: A fundamental theory describing nature at atomic scales.
+        Key principles include wave-particle duality, superposition, and entanglement.
+        Developed through contributions from Planck, Bohr, Heisenberg, Schrödinger.
+        Related concepts: Uncertainty principle, quantum tunneling, wave function.
+        Applications: Semiconductors, lasers, MRI machines, quantum computing.
+        """
+    },
+    {
+        "id": "institution_princeton",
+        "type": "institution",
+        "content": """
+        Institute for Advanced Study (Princeton): A private research center
+        founded in 1930. Notable members include Albert Einstein, John von Neumann,
+        Kurt Gödel, and Robert Oppenheimer. The institute focuses on theoretical
+        research in mathematics, natural sciences, and humanities.
+        Location: Princeton, New Jersey, USA.
+        """
+    },
+    {
+        "id": "institution_copenhagen",
+        "type": "institution",
+        "content": """
+        Niels Bohr Institute (Copenhagen): Founded in 1921 by Niels Bohr as the
+        Institute of Theoretical Physics. It became a world center for quantum
+        mechanics research. Notable visitors included Heisenberg, Pauli, and Dirac.
+        The "Copenhagen interpretation" of quantum mechanics originated here.
+        Location: Copenhagen, Denmark.
+        """
+    },
+    {
+        "id": "event_solvay",
+        "type": "event",
+        "content": """
+        Solvay Conferences: Series of physics conferences held in Brussels since 1911.
+        The 1927 Fifth Solvay Conference is famous for the Bohr-Einstein debates
+        on quantum mechanics. Attendees included Einstein, Bohr, Heisenberg,
+        Schrödinger, Dirac, and Marie Curie. These conferences shaped modern physics.
+        """
+    }
+]
+
+
+def graph_aware_rag():
+    """Demonstrate relationship-aware retrieval."""
+    
+    # Build context from entity knowledge
+    context = "\n\n".join([f"[{e['type'].upper()}: {e['id']}]\n{e['content']}" for e in ENTITY_KNOWLEDGE])
+    
+    # Create agent with entity knowledge
+    agent = Agent(
+        name="Physics Historian",
+        instructions=f"""You are a physics historian who understands the relationships
+        between scientists, concepts, and institutions. When answering:
+        1. Trace connections between entities
+        2. Explain how ideas and people influenced each other
+        3. Reference specific relationships mentioned in the knowledge base
+        4. Build a narrative that shows the interconnected nature of physics history.
+        
+        KNOWLEDGE GRAPH:
+        {context}""",
+        verbose=False
+    )
+    
+    # Relationship-focused queries
+    queries = [
+        "How were Einstein and Bohr connected?",
+        "Trace the lineage of quantum mechanics through its key figures.",
+        "What institutions were central to 20th century physics?",
+        "How did the Solvay Conferences shape physics?"
+    ]
+    
+    print("=" * 60)
+    print("GRAPH-ASSISTED RAG: Physics History Network")
+    print("=" * 60)
+    print("\nKnowledge graph entities:")
+    for entity in ENTITY_KNOWLEDGE:
+        print(f"  - [{entity['type']}] {entity['id']}")
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response[:350]}..." if len(str(response)) > 350 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def multi_hop_reasoning():
+    """Demonstrate multi-hop reasoning across entities."""
+    
+    print("\n" + "=" * 60)
+    print("MULTI-HOP REASONING")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{e['type'].upper()}: {e['id']}]\n{e['content']}" for e in ENTITY_KNOWLEDGE])
+    
+    agent = Agent(
+        name="Connection Finder",
+        instructions=f"""You excel at finding indirect connections between entities.
+        When asked about relationships, trace the path through intermediate entities.
+        Format your answer to show the chain of connections.
+        
+        KNOWLEDGE GRAPH:
+        {context}""",
+        verbose=False
+    )
+    
+    # Multi-hop query requiring traversal
+    query = """
+    What is the connection between the uncertainty principle and Princeton?
+    (Hint: trace through people and their relationships)
+    """
+    
+    print(f"\n📝 Multi-hop Query: {query.strip()}")
+    print("\n🔗 Expected path: Uncertainty Principle → Heisenberg → Bohr → Einstein → Princeton")
+    
+    response = agent.chat(query)
+    print(f"\n💡 Answer:\n{response}")
+
+
+def entity_type_filtering():
+    """Show filtering by entity type."""
+    
+    print("\n" + "=" * 60)
+    print("ENTITY TYPE FILTERING")
+    print("=" * 60)
+    
+    # Filter to only people
+    people_only = [e for e in ENTITY_KNOWLEDGE if e['type'] == 'person']
+    people_context = "\n\n".join([f"[{e['id']}]\n{e['content']}" for e in people_only])
+    
+    people_agent = Agent(
+        name="Biographer",
+        instructions=f"""You are a biographer focused on scientists' lives and relationships.
+        
+        SCIENTISTS:
+        {people_context}""",
+        verbose=False
+    )
+    
+    # Filter to only concepts
+    concepts_only = [e for e in ENTITY_KNOWLEDGE if e['type'] == 'concept']
+    concepts_context = "\n\n".join([f"[{e['id']}]\n{e['content']}" for e in concepts_only])
+    
+    concept_agent = Agent(
+        name="Concept Explainer",
+        instructions=f"""You explain scientific concepts and their relationships.
+        
+        CONCEPTS:
+        {concepts_context}""",
+        verbose=False
+    )
+    
+    query = "Tell me about the major developments in early 20th century physics."
+    
+    print(f"\n📝 Query: {query}")
+    
+    print("\n👤 People-focused view:")
+    response1 = people_agent.chat(query)
+    print(f"   {response1[:250]}...")
+    
+    print("\n💡 Concept-focused view:")
+    response2 = concept_agent.chat(query)
+    print(f"   {response2[:250]}...")
+
+
+def graph_rag_patterns():
+    """Explain graph RAG patterns."""
+    
+    print("\n" + "=" * 60)
+    print("GRAPH RAG PATTERNS")
+    print("=" * 60)
+    
+    print("""
+    📊 Graph-Assisted RAG Patterns:
+    
+    1. **Entity-Centric Retrieval**
+       - Store entities with their relationships
+       - Query retrieves entity + connected entities
+       - Good for: "Tell me about X and its connections"
+    
+    2. **Path-Based Retrieval**
+       - Find paths between two entities
+       - Retrieve all nodes along the path
+       - Good for: "How is X related to Y?"
+    
+    3. **Neighborhood Expansion**
+       - Start with query-matched entities
+       - Expand to include 1-hop or 2-hop neighbors
+       - Good for: Comprehensive context
+    
+    4. **Subgraph Extraction**
+       - Extract relevant subgraph for query
+       - Include nodes and edges as context
+       - Good for: Complex multi-entity questions
+    
+    Implementation in PraisonAI:
+    ```python
+    # Structure knowledge as entities with relationships
+    entities = [
+        {
+            "id": "entity_1",
+            "type": "person",
+            "content": "...",
+            "relationships": ["entity_2", "entity_3"]
+        },
+        ...
+    ]
+    
+    # Agent retrieves related entities automatically
+    agent = Agent(
+        knowledge=entities,
+        instructions="Trace relationships between entities..."
+    )
+    ```
+    """)
+
+
+def main():
+    """Run all graph-assisted RAG examples."""
+    print("\n🚀 PraisonAI Graph-Assisted RAG Examples\n")
+    
+    # Example 1: Graph-aware retrieval
+    graph_aware_rag()
+    
+    # Example 2: Multi-hop reasoning
+    multi_hop_reasoning()
+    
+    # Example 3: Entity type filtering
+    entity_type_filtering()
+    
+    # Example 4: Graph RAG patterns
+    graph_rag_patterns()
+    
+    print("\n✅ Graph-assisted RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/multi_document.py

@@ -0,0 +1,280 @@
+"""
+Multi-Document RAG: Synthesizing Information Across Sources
+
+This example demonstrates retrieving and synthesizing information from
+multiple documents to answer complex questions.
+
+RAG Concept: Real-world questions often require combining information
+from multiple sources. Multi-document RAG retrieves relevant chunks
+from different documents and synthesizes a coherent answer.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Multiple documents on different topics
+CLIMATE_REPORT = {
+    "id": "climate_2024",
+    "source": "Global Climate Report 2024",
+    "content": """
+    Global Climate Report 2024 - Executive Summary
+    
+    Global temperatures in 2024 reached 1.45°C above pre-industrial levels,
+    making it the warmest year on record. Key findings:
+    
+    - Arctic sea ice extent hit a new minimum in September
+    - Ocean heat content reached unprecedented levels
+    - Extreme weather events increased by 23% compared to the decade average
+    - CO2 concentrations reached 422 ppm, up from 417 ppm in 2023
+    
+    Regional impacts varied significantly. Europe experienced its hottest
+    summer, while parts of South America faced severe drought conditions.
+    The economic cost of climate-related disasters exceeded $380 billion.
+    """
+}
+
+ENERGY_REPORT = {
+    "id": "energy_2024",
+    "source": "World Energy Outlook 2024",
+    "content": """
+    World Energy Outlook 2024 - Key Highlights
+    
+    Renewable energy capacity grew by 35% in 2024, led by solar and wind.
+    Major developments:
+    
+    - Solar installations reached 1.5 TW cumulative capacity globally
+    - Wind power generated 12% of global electricity
+    - Battery storage capacity doubled to 500 GWh
+    - Electric vehicle sales reached 20 million units
+    
+    Despite progress, fossil fuels still account for 75% of primary energy.
+    Investment in clean energy reached $1.8 trillion, but $4 trillion annually
+    is needed to meet net-zero targets by 2050.
+    """
+}
+
+POLICY_REPORT = {
+    "id": "policy_2024",
+    "source": "Climate Policy Tracker 2024",
+    "content": """
+    Climate Policy Tracker 2024 - Global Progress
+    
+    145 countries have now committed to net-zero emissions targets.
+    Policy developments:
+    
+    - EU Carbon Border Adjustment Mechanism fully implemented
+    - US Inflation Reduction Act drove $300B in clean energy investment
+    - China pledged to peak emissions before 2030
+    - India launched National Green Hydrogen Mission
+    
+    Carbon pricing now covers 23% of global emissions, up from 20% in 2023.
+    Average carbon price increased to $45/ton. However, only 4% of emissions
+    are priced at levels consistent with Paris Agreement goals ($100+/ton).
+    """
+}
+
+TECH_REPORT = {
+    "id": "tech_2024",
+    "source": "Climate Technology Review 2024",
+    "content": """
+    Climate Technology Review 2024 - Breakthrough Innovations
+    
+    Several climate technologies reached commercial viability in 2024:
+    
+    - Direct Air Capture: Costs fell to $400/ton CO2, down from $600 in 2022
+    - Green Hydrogen: Production costs reached $3/kg in optimal locations
+    - Solid-state Batteries: Energy density improved 40%, enabling longer EV range
+    - Perovskite Solar Cells: Efficiency reached 33%, approaching silicon limits
+    
+    Emerging technologies to watch:
+    - Enhanced geothermal systems showing promise in non-volcanic regions
+    - Ocean-based carbon removal gaining investment interest
+    - AI-optimized grid management reducing curtailment by 15%
+    """
+}
+
+# Combine all documents
+ALL_DOCUMENTS = [CLIMATE_REPORT, ENERGY_REPORT, POLICY_REPORT, TECH_REPORT]
+
+
+def multi_document_rag():
+    """Demonstrate RAG across multiple documents."""
+    
+    # Build context from all documents
+    context = "\n\n".join([f"[{d['source']}]\n{d['content']}" for d in ALL_DOCUMENTS])
+    
+    # Create agent with multi-document knowledge
+    agent = Agent(
+        name="Climate Analyst",
+        instructions=f"""You are a climate and energy analyst.
+        Synthesize information from multiple reports to answer questions.
+        When information comes from different sources, mention which reports
+        you're drawing from. Provide comprehensive, well-rounded answers.
+        
+        REPORTS:
+        {context}""",
+        verbose=False
+    )
+    
+    # Questions that require multi-document synthesis
+    queries = [
+        "What is the current state of global climate and what are we doing about it?",
+        "How is renewable energy progressing and what policies support it?",
+        "What technologies are emerging to address climate change?",
+        "Compare the economic investment in clean energy with climate damage costs."
+    ]
+    
+    print("=" * 60)
+    print("MULTI-DOCUMENT RAG: Climate Analysis")
+    print("=" * 60)
+    print(f"\nKnowledge base: {len(ALL_DOCUMENTS)} documents")
+    print(f"Sources: {[d['source'] for d in ALL_DOCUMENTS]}")
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response[:400]}..." if len(str(response)) > 400 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def cross_reference_example():
+    """Show how agents can cross-reference information."""
+    
+    print("\n" + "=" * 60)
+    print("CROSS-REFERENCING ACROSS DOCUMENTS")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['source']}]\n{d['content']}" for d in ALL_DOCUMENTS])
+    
+    agent = Agent(
+        name="Cross-Reference Analyst",
+        instructions=f"""You are an analyst who excels at finding connections
+        between different reports. When answering:
+        1. Identify relevant information from each source
+        2. Note any contradictions or complementary data
+        3. Synthesize a coherent narrative
+        4. Cite your sources explicitly.
+        
+        REPORTS:
+        {context}""",
+        verbose=False
+    )
+    
+    query = """
+    Analyze the relationship between renewable energy growth (from Energy Report),
+    policy support (from Policy Report), and technology costs (from Tech Report).
+    How do these factors reinforce each other?
+    """
+    
+    print(f"\n📝 Complex Query: {query.strip()}")
+    response = agent.chat(query)
+    print(f"\n💡 Synthesized Answer:\n{response}")
+
+
+def document_filtering():
+    """Demonstrate filtering documents by metadata."""
+    
+    print("\n" + "=" * 60)
+    print("DOCUMENT FILTERING BY SOURCE")
+    print("=" * 60)
+    
+    # Create agents focused on specific document types
+    policy_agent = Agent(
+        name="Policy Expert",
+        instructions=f"""You are a policy expert. Focus only on policy-related information.
+        
+        POLICY REPORT:
+        {POLICY_REPORT['content']}""",
+        verbose=False
+    )
+    
+    tech_agent = Agent(
+        name="Technology Expert",
+        instructions=f"""You are a technology expert. Focus on technical innovations.
+        
+        TECHNOLOGY REPORT:
+        {TECH_REPORT['content']}""",
+        verbose=False
+    )
+    
+    query = "What progress has been made in addressing climate change?"
+    
+    print(f"\n📝 Query: {query}")
+    
+    print("\n🏛️ Policy Expert's View:")
+    policy_response = policy_agent.chat(query)
+    print(f"   {policy_response[:250]}...")
+    
+    print("\n🔬 Technology Expert's View:")
+    tech_response = tech_agent.chat(query)
+    print(f"   {tech_response[:250]}...")
+    
+    print("\n💡 Note: Different document subsets yield different perspectives!")
+
+
+def multi_document_best_practices():
+    """Share best practices for multi-document RAG."""
+    
+    print("\n" + "=" * 60)
+    print("MULTI-DOCUMENT RAG BEST PRACTICES")
+    print("=" * 60)
+    
+    print("""
+    📚 Best Practices for Multi-Document RAG:
+    
+    1. **Document Metadata**
+       - Include source, date, author in each document
+       - Enables filtering and citation
+    
+    2. **Consistent Chunking**
+       - Use similar chunk sizes across documents
+       - Maintains balanced retrieval
+    
+    3. **Source Diversity**
+       - Retrieve from multiple sources when possible
+       - Reduces single-source bias
+    
+    4. **Conflict Resolution**
+       - Instruct agent how to handle contradictions
+       - Prefer newer sources or authoritative ones
+    
+    5. **Citation Requirements**
+       - Ask agent to cite sources in responses
+       - Enables verification and trust
+    
+    Example configuration:
+    ```python
+    documents = [
+        {"id": "doc1", "source": "Report A", "date": "2024-01", "content": "..."},
+        {"id": "doc2", "source": "Report B", "date": "2024-06", "content": "..."},
+    ]
+    
+    agent = Agent(
+        knowledge=documents,
+        instructions="Always cite which report your information comes from."
+    )
+    ```
+    """)
+
+
+def main():
+    """Run all multi-document RAG examples."""
+    print("\n🚀 PraisonAI Multi-Document RAG Examples\n")
+    
+    # Example 1: Basic multi-document RAG
+    multi_document_rag()
+    
+    # Example 2: Cross-referencing
+    cross_reference_example()
+    
+    # Example 3: Document filtering
+    document_filtering()
+    
+    # Example 4: Best practices
+    multi_document_best_practices()
+    
+    print("\n✅ Multi-document RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/rag_evaluation.py

@@ -0,0 +1,150 @@
+"""
+RAG Evaluation Example
+
+This example demonstrates how to evaluate RAG quality by testing
+agent responses against expected answers.
+
+Usage:
+    python rag_evaluation.py
+"""
+
+from praisonaiagents import Agent
+
+
+# Sample knowledge for evaluation
+SAMPLE_KNOWLEDGE = """
+Product Overview:
+CloudManager Pro is an enterprise cloud management platform.
+Its main purpose is to help organizations monitor, optimize, and secure their multi-cloud infrastructure.
+
+Key Features:
+- Real-time monitoring across AWS, Azure, and GCP
+- Cost optimization with automated recommendations
+- Security compliance checking
+- Automated scaling and resource management
+
+Getting Started:
+1. Sign up at cloudmanager.example.com
+2. Connect your cloud accounts
+3. Configure monitoring dashboards
+4. Set up alerts and policies
+"""
+
+
+def create_test_queries():
+    """Create sample test queries for evaluation."""
+    return [
+        {
+            "query": "What is the main purpose of CloudManager Pro?",
+            "expected_contains": ["monitor", "cloud", "infrastructure"],
+        },
+        {
+            "query": "What are the key features?",
+            "expected_contains": ["monitoring", "cost", "security"],
+        },
+        {
+            "query": "How do I get started?",
+            "expected_contains": ["sign up", "connect", "configure"],
+        },
+    ]
+
+
+def evaluate_rag_agent(agent: Agent, test_queries: list) -> dict:
+    """
+    Evaluate RAG agent performance on test queries.
+    
+    Returns metrics including answer relevance accuracy.
+    """
+    results = {
+        "total": len(test_queries),
+        "passed": 0,
+        "details": [],
+    }
+    
+    for test in test_queries:
+        query = test["query"]
+        expected_terms = test.get("expected_contains", [])
+        
+        # Get agent response
+        response = agent.chat(query)
+        response_lower = response.lower()
+        
+        # Check if response contains expected terms
+        terms_found = sum(1 for term in expected_terms if term.lower() in response_lower)
+        pass_rate = terms_found / len(expected_terms) if expected_terms else 1.0
+        passed = pass_rate >= 0.5  # At least 50% of terms found
+        
+        if passed:
+            results["passed"] += 1
+        
+        results["details"].append({
+            "query": query,
+            "passed": passed,
+            "terms_found": terms_found,
+            "total_terms": len(expected_terms),
+            "pass_rate": pass_rate,
+            "answer_preview": response[:150],
+        })
+    
+    results["accuracy"] = results["passed"] / results["total"]
+    return results
+
+
+def print_results(results: dict):
+    """Print evaluation results in a formatted way."""
+    print("\n" + "=" * 60)
+    print("RAG Evaluation Results")
+    print("=" * 60)
+    
+    print(f"\nTotal Queries: {results['total']}")
+    print(f"Passed: {results['passed']}/{results['total']}")
+    print(f"Accuracy: {results['accuracy']:.1%}")
+    
+    print("\n" + "-" * 60)
+    print("Detailed Results:")
+    print("-" * 60)
+    
+    for i, detail in enumerate(results["details"], 1):
+        status = "✅ PASS" if detail["passed"] else "❌ FAIL"
+        print(f"\n[{i}] {status}: {detail['query']}")
+        print(f"    Terms Found: {detail['terms_found']}/{detail['total_terms']}")
+        print(f"    Answer: {detail['answer_preview']}...")
+
+
+def main():
+    print("=" * 60)
+    print("RAG Evaluation Example")
+    print("=" * 60)
+    
+    # Create agent with knowledge
+    agent = Agent(
+        name="Product Expert",
+        instructions=f"""You are a product expert who answers questions accurately.
+        Use only the following knowledge to answer questions.
+        
+        KNOWLEDGE:
+        {SAMPLE_KNOWLEDGE}""",
+        verbose=False
+    )
+    
+    # Get test queries
+    test_queries = create_test_queries()
+    
+    # Run evaluation
+    print(f"\nEvaluating {len(test_queries)} queries...")
+    results = evaluate_rag_agent(agent, test_queries)
+    
+    # Print results
+    print_results(results)
+    
+    # Return status
+    if results["accuracy"] < 0.8:
+        print("\n⚠️ WARNING: Accuracy below 80% threshold!")
+        return 1
+    
+    print("\n✅ Evaluation PASSED!")
+    return 0
+
+
+if __name__ == "__main__":
+    exit(main())

examples/rag/rag_multi_agent.py

@@ -0,0 +1,135 @@
+"""
+RAG Multi-Agent Example
+
+This example demonstrates how multiple agents can work together
+on a shared knowledge base for collaborative RAG.
+
+Usage:
+    python rag_multi_agent.py
+"""
+
+from praisonaiagents import Agent, PraisonAIAgents, Task
+
+
+# Shared knowledge base content
+SHARED_KNOWLEDGE = """
+# Climate Technology Report 2024
+
+## Executive Summary
+Global investment in climate technology reached $150 billion in 2024, 
+a 25% increase from the previous year. Key areas of growth include 
+renewable energy, carbon capture, and sustainable transportation.
+
+## Key Findings
+
+### Renewable Energy
+- Solar capacity grew by 40% globally
+- Wind energy now provides 15% of global electricity
+- Battery storage costs decreased by 20%
+
+### Carbon Capture
+- Direct air capture costs fell to $400/ton
+- 50 new carbon capture facilities announced
+- Total captured CO2 reached 50 million tons
+
+### Sustainable Transportation
+- Electric vehicle sales reached 25 million units
+- Hydrogen fuel cell technology advancing rapidly
+- Sustainable aviation fuel production doubled
+
+## Recommendations
+1. Increase investment in grid infrastructure
+2. Accelerate carbon capture deployment
+3. Support EV charging network expansion
+"""
+
+
+def main():
+    print("=" * 60)
+    print("Multi-Agent RAG: Collaborative Analysis")
+    print("=" * 60)
+    
+    # Create specialized agents with shared knowledge
+    researcher = Agent(
+        name="Researcher",
+        role="Research Analyst",
+        goal="Find and analyze relevant information",
+        instructions=f"""You are a research analyst. Your job is to:
+        1. Extract key facts and data points
+        2. Provide detailed analysis
+        3. Cite specific sections
+        
+        KNOWLEDGE BASE:
+        {SHARED_KNOWLEDGE}""",
+        verbose=False
+    )
+    
+    summarizer = Agent(
+        name="Summarizer",
+        role="Content Summarizer",
+        goal="Create concise summaries",
+        instructions=f"""You are a content summarizer. Your job is to:
+        1. Take research findings and create clear summaries
+        2. Highlight the most important points
+        3. Make complex information accessible
+        
+        KNOWLEDGE BASE:
+        {SHARED_KNOWLEDGE}""",
+        verbose=False
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Report Writer",
+        goal="Create well-structured reports",
+        instructions=f"""You are a report writer. Your job is to:
+        1. Combine research and summaries into a cohesive report
+        2. Ensure proper structure and flow
+        3. Include key statistics
+        
+        KNOWLEDGE BASE:
+        {SHARED_KNOWLEDGE}""",
+        verbose=False
+    )
+    
+    # Define tasks
+    research_task = Task(
+        description="Research the main investment trends and growth areas in climate technology",
+        expected_output="Detailed research notes with key statistics",
+        agent=researcher,
+    )
+    
+    summary_task = Task(
+        description="Summarize the research findings into 5 key bullet points",
+        expected_output="Bullet-point summary of main findings",
+        agent=summarizer,
+    )
+    
+    report_task = Task(
+        description="Write a brief executive briefing based on the research and summary",
+        expected_output="A 2-paragraph executive briefing",
+        agent=writer,
+    )
+    
+    # Run the multi-agent workflow
+    print("\n🔄 Running multi-agent workflow...")
+    
+    agents = PraisonAIAgents(
+        agents=[researcher, summarizer, writer],
+        tasks=[research_task, summary_task, report_task],
+        process="sequential",
+        verbose=False
+    )
+    
+    result = agents.start()
+    
+    print("\n" + "=" * 60)
+    print("Final Report")
+    print("=" * 60)
+    print(result)
+    
+    print("\n✅ Multi-agent RAG example completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/rag_pdf_qa.py

@@ -0,0 +1,129 @@
+"""
+RAG Document Q&A Example
+
+This example demonstrates how to use RAG to answer questions
+about documents with proper context injection.
+
+Usage:
+    python rag_pdf_qa.py
+"""
+
+from praisonaiagents import Agent
+
+
+# Sample document content (simulating PDF content)
+DOCUMENT_CONTENT = """
+# Research Study: Impact of Remote Work on Productivity
+
+## Abstract
+This study examines the effects of remote work arrangements on employee 
+productivity across 50 technology companies during 2023-2024.
+
+## Methodology
+- Survey of 5,000 employees across 50 companies
+- Productivity metrics tracked over 12 months
+- Control group: in-office workers
+- Test group: remote and hybrid workers
+
+## Key Findings
+
+### Productivity Impact
+- Remote workers showed 13% higher productivity on average
+- Hybrid workers (3 days remote) showed 18% higher productivity
+- Fully remote workers reported 25% better work-life balance
+
+### Challenges Identified
+- Communication delays increased by 15%
+- Collaboration on complex projects took 10% longer
+- New employee onboarding was 20% slower remotely
+
+### Cost Analysis
+- Companies saved average of $11,000 per remote employee annually
+- Employees saved average of $4,500 in commuting costs
+- Office space reduction saved 30% on real estate costs
+
+## Recommendations
+1. Implement hybrid work model (2-3 days remote)
+2. Invest in collaboration tools
+3. Create structured onboarding for remote hires
+4. Establish clear communication protocols
+
+## Conclusion
+Remote work, when properly implemented, leads to improved productivity
+and significant cost savings for both employers and employees.
+"""
+
+
+def main():
+    # Method 1: Simple Agent with Context
+    print("=" * 60)
+    print("Method 1: Agent with Document Context")
+    print("=" * 60)
+    
+    agent = Agent(
+        name="Document Assistant",
+        instructions=f"""You are a helpful assistant that answers questions about documents.
+        Always cite specific sections when answering.
+        
+        DOCUMENT:
+        {DOCUMENT_CONTENT}""",
+        verbose=False
+    )
+    
+    query = "What are the main topics covered in this document?"
+    response = agent.chat(query)
+    print(f"\n📝 Query: {query}")
+    print(f"💡 Answer: {response}\n")
+    
+    # Method 2: Q&A with Citations
+    print("=" * 60)
+    print("Method 2: Q&A with Citations")
+    print("=" * 60)
+    
+    citation_agent = Agent(
+        name="Citation Assistant",
+        instructions=f"""You answer questions about research documents.
+        Always include citations in format [Section: Name].
+        Be precise and reference specific data points.
+        
+        DOCUMENT:
+        {DOCUMENT_CONTENT}""",
+        verbose=False
+    )
+    
+    queries = [
+        "What methodology was used in this research?",
+        "What were the key findings about productivity?",
+        "What are the recommendations?"
+    ]
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = citation_agent.chat(query)
+        print(f"💡 Answer: {response[:300]}...")
+    
+    # Method 3: Comparative Analysis
+    print("\n" + "=" * 60)
+    print("Method 3: Analytical Questions")
+    print("=" * 60)
+    
+    analyst = Agent(
+        name="Research Analyst",
+        instructions=f"""You are a research analyst who provides insights from documents.
+        Analyze data, identify trends, and provide actionable insights.
+        
+        DOCUMENT:
+        {DOCUMENT_CONTENT}""",
+        verbose=False
+    )
+    
+    analysis_query = "Compare the benefits vs challenges of remote work based on this study"
+    print(f"\n📝 Query: {analysis_query}")
+    response = analyst.chat(analysis_query)
+    print(f"💡 Analysis:\n{response}")
+    
+    print("\n✅ Document Q&A example completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/reranking.py

@@ -0,0 +1,249 @@
+"""
+Reranking: Improving Retrieval Precision
+
+This example demonstrates reranking - a second-pass scoring mechanism
+that improves the quality of retrieved documents.
+
+RAG Concept: Initial retrieval (first stage) prioritizes recall - finding
+all potentially relevant documents. Reranking (second stage) prioritizes
+precision - ordering results by true relevance to the query.
+"""
+
+from praisonaiagents import Agent
+
+# Sample knowledge base: Research paper abstracts
+RESEARCH_PAPERS = [
+    {
+        "id": "paper_001",
+        "content": """
+        Title: Attention Mechanisms in Neural Machine Translation
+        
+        Abstract: This paper introduces a novel attention mechanism for sequence-to-sequence
+        models in machine translation. Unlike previous approaches that use a fixed-length
+        context vector, our method allows the model to automatically search for parts of
+        the source sentence relevant to predicting the target word. Experiments on
+        English-to-French translation show significant improvements over baseline systems.
+        """
+    },
+    {
+        "id": "paper_002",
+        "content": """
+        Title: Deep Residual Learning for Image Recognition
+        
+        Abstract: We present a residual learning framework to ease the training of very deep
+        neural networks. By reformulating layers as learning residual functions with
+        reference to layer inputs, we show that these networks are easier to optimize
+        and can gain accuracy from considerably increased depth. Our 152-layer residual
+        network achieves state-of-the-art results on ImageNet classification.
+        """
+    },
+    {
+        "id": "paper_003",
+        "content": """
+        Title: BERT: Pre-training of Deep Bidirectional Transformers
+        
+        Abstract: We introduce BERT, a new language representation model designed to
+        pre-train deep bidirectional representations from unlabeled text. Unlike previous
+        models, BERT is designed to jointly condition on both left and right context.
+        The pre-trained BERT model can be fine-tuned with just one additional output
+        layer for a wide range of NLP tasks.
+        """
+    },
+    {
+        "id": "paper_004",
+        "content": """
+        Title: Generative Adversarial Networks
+        
+        Abstract: We propose a new framework for estimating generative models via an
+        adversarial process. We simultaneously train two models: a generative model G
+        that captures the data distribution, and a discriminative model D that estimates
+        the probability that a sample came from the training data rather than G.
+        This framework can generate realistic images from random noise.
+        """
+    },
+    {
+        "id": "paper_005",
+        "content": """
+        Title: Transformer Architecture for Language Understanding
+        
+        Abstract: We propose the Transformer, a model architecture eschewing recurrence
+        and instead relying entirely on an attention mechanism to draw global dependencies
+        between input and output. The Transformer allows for significantly more
+        parallelization and achieves new state of the art in translation quality.
+        """
+    },
+    {
+        "id": "paper_006",
+        "content": """
+        Title: Word Embeddings and Semantic Similarity
+        
+        Abstract: This paper explores methods for learning distributed representations
+        of words that capture semantic relationships. We show that word vectors trained
+        on large corpora encode meaningful syntactic and semantic regularities. These
+        representations enable analogical reasoning: king - man + woman = queen.
+        """
+    }
+]
+
+
+def explain_reranking():
+    """Explain the reranking concept."""
+    
+    print("=" * 60)
+    print("RERANKING EXPLAINED")
+    print("=" * 60)
+    
+    print("""
+    🔄 Two-Stage Retrieval Pipeline:
+    
+    Stage 1: Initial Retrieval (Bi-encoder)
+    ├── Fast approximate matching
+    ├── Retrieves top-K candidates (e.g., 20-100)
+    ├── Uses pre-computed embeddings
+    └── Optimizes for RECALL (find all relevant docs)
+    
+    Stage 2: Reranking (Cross-encoder)
+    ├── Slower but more accurate scoring
+    ├── Reorders the top-K candidates
+    ├── Computes query-document interaction
+    └── Optimizes for PRECISION (best docs first)
+    
+    Why Reranking Matters:
+    - Bi-encoders encode query and docs separately (fast but approximate)
+    - Cross-encoders process query+doc together (slow but accurate)
+    - Reranking gives you the best of both worlds
+    """)
+
+
+def rag_with_reranking():
+    """Demonstrate RAG with reranking enabled."""
+    
+    # Build context from research papers
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in RESEARCH_PAPERS])
+    
+    # Create agent with context
+    agent = Agent(
+        name="Research Assistant",
+        instructions=f"""You are a research paper expert.
+        Answer questions about machine learning research.
+        Reference specific papers when relevant.
+        Be precise about technical details.
+        
+        RESEARCH PAPERS:
+        {context}""",
+        verbose=False
+    )
+    
+    queries = [
+        "Which paper introduced the attention mechanism for translation?",
+        "Tell me about pre-training language models",
+        "What architecture avoids recurrence entirely?"
+    ]
+    
+    print("\n" + "=" * 60)
+    print("RAG WITH RERANKING")
+    print("=" * 60)
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 Answer: {response[:300]}..." if len(str(response)) > 300 else f"💡 Answer: {response}")
+        print("-" * 40)
+
+
+def compare_with_without_reranking():
+    """Compare retrieval quality with and without reranking."""
+    
+    print("\n" + "=" * 60)
+    print("RERANKING IMPACT COMPARISON")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in RESEARCH_PAPERS])
+    
+    query = "How do transformers handle long-range dependencies?"
+    
+    # Agent with context
+    agent = Agent(
+        name="Research Agent",
+        instructions=f"""Answer based on the research papers provided.
+        
+        RESEARCH PAPERS:
+        {context}""",
+        verbose=False
+    )
+    
+    print(f"\n📝 Query: {query}")
+    
+    print("\n🔍 RAG Response:")
+    response = agent.chat(query)
+    print(f"   {response[:250]}...")
+    
+    print("\n💡 Note: Reranking uses cross-encoders to improve precision after initial retrieval.")
+
+
+def reranking_configuration():
+    """Show reranking configuration options."""
+    
+    print("\n" + "=" * 60)
+    print("RERANKING CONFIGURATION")
+    print("=" * 60)
+    
+    print("""
+    Configuration options for reranking in PraisonAI:
+    
+    ```python
+    agent = Agent(
+        name="My Agent",
+        knowledge=documents,
+        knowledge_config={
+            # Enable reranking
+            "rerank": True,
+            
+            # Number of candidates for initial retrieval
+            "top_k": 10,
+            
+            # Number of results after reranking
+            "rerank_top_k": 3,
+            
+            # Reranker model (optional)
+            "rerank_model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
+        }
+    )
+    ```
+    
+    Performance Considerations:
+    ┌─────────────────┬──────────────┬─────────────┐
+    │ Configuration   │ Latency      │ Quality     │
+    ├─────────────────┼──────────────┼─────────────┤
+    │ No reranking    │ ~50ms        │ Good        │
+    │ Light reranker  │ ~100ms       │ Better      │
+    │ Heavy reranker  │ ~200ms       │ Best        │
+    └─────────────────┴──────────────┴─────────────┘
+    
+    Tip: Use reranking for precision-critical applications
+    where quality matters more than latency.
+    """)
+
+
+def main():
+    """Run all reranking examples."""
+    print("\n🚀 PraisonAI Reranking Examples\n")
+    
+    # Example 1: Explain reranking
+    explain_reranking()
+    
+    # Example 2: RAG with reranking
+    rag_with_reranking()
+    
+    # Example 3: Compare with/without reranking
+    compare_with_without_reranking()
+    
+    # Example 4: Configuration options
+    reranking_configuration()
+    
+    print("\n✅ Reranking examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/retrieval_policies.py

@@ -0,0 +1,396 @@
+"""
+Retrieval Policies: Agent-Decided Retrieval Strategies
+
+This example demonstrates how agents can dynamically decide retrieval
+strategies based on query characteristics.
+
+RAG Concept: Not all queries are equal. Some need deep retrieval, others
+need broad coverage, and some don't need retrieval at all. Smart policies
+optimize both quality and efficiency.
+"""
+
+from praisonaiagents import Agent, AutoRagAgent, AutoRagConfig
+from praisonaiagents.agents.auto_rag_agent import RetrievalPolicy
+
+# Sample knowledge base: IT support documentation
+IT_SUPPORT_DOCS = [
+    {
+        "id": "password_reset",
+        "category": "account",
+        "priority": "high",
+        "content": """
+        Password Reset Procedure:
+        1. Go to the self-service portal at https://portal.company.com
+        2. Click "Forgot Password"
+        3. Enter your employee ID and email
+        4. Check your email for the reset link (valid for 1 hour)
+        5. Create a new password meeting complexity requirements
+        
+        If you don't receive the email, check spam or contact IT helpdesk.
+        """
+    },
+    {
+        "id": "vpn_setup",
+        "category": "network",
+        "priority": "medium",
+        "content": """
+        VPN Setup Guide:
+        1. Download the VPN client from the software center
+        2. Install with default settings
+        3. Launch and enter your credentials
+        4. Select the nearest server location
+        5. Click Connect
+        
+        Troubleshooting: If connection fails, check firewall settings
+        and ensure port 443 is open.
+        """
+    },
+    {
+        "id": "email_config",
+        "category": "communication",
+        "priority": "medium",
+        "content": """
+        Email Configuration:
+        - Server: mail.company.com
+        - Port: 993 (IMAP) / 587 (SMTP)
+        - Security: SSL/TLS required
+        - Username: your full email address
+        
+        Mobile setup: Use the Company Portal app for automatic configuration.
+        """
+    },
+    {
+        "id": "printer_setup",
+        "category": "hardware",
+        "priority": "low",
+        "content": """
+        Printer Setup:
+        1. Open Settings > Printers & Scanners
+        2. Click Add Printer
+        3. Select your floor's printer from the list
+        4. Install drivers if prompted
+        
+        Printer naming convention: FLOOR-WING-NUMBER (e.g., 3-EAST-01)
+        """
+    },
+    {
+        "id": "software_request",
+        "category": "software",
+        "priority": "medium",
+        "content": """
+        Software Request Process:
+        1. Submit request through ServiceNow
+        2. Manager approval required for licensed software
+        3. IT reviews for security compliance
+        4. Approved software deployed within 48 hours
+        
+        Pre-approved software can be installed directly from Software Center.
+        """
+    }
+]
+
+
+def query_classification():
+    """Demonstrate query classification for retrieval decisions."""
+    
+    print("=" * 60)
+    print("QUERY CLASSIFICATION FOR RETRIEVAL")
+    print("=" * 60)
+    
+    # Different query types
+    queries = [
+        ("How do I reset my password?", "procedural", True),
+        ("Hello!", "greeting", False),
+        ("What is 2 + 2?", "general_knowledge", False),
+        ("VPN connection keeps failing", "troubleshooting", True),
+        ("Thanks for your help", "closing", False),
+        ("How do I request new software?", "procedural", True),
+    ]
+    
+    print("\n📊 Query Classification Examples:\n")
+    print(f"{'Query':<40} {'Type':<20} {'Needs RAG':<10}")
+    print("-" * 70)
+    
+    for query, query_type, needs_rag in queries:
+        rag_indicator = "✅ Yes" if needs_rag else "❌ No"
+        print(f"{query:<40} {query_type:<20} {rag_indicator:<10}")
+    
+    print("\n💡 Smart agents classify queries to decide retrieval strategy.")
+
+
+def policy_based_retrieval():
+    """Demonstrate different retrieval policies."""
+    
+    print("\n" + "=" * 60)
+    print("RETRIEVAL POLICY COMPARISON")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{d['id']}]\n{d['content']}" for d in IT_SUPPORT_DOCS])
+    
+    base_agent = Agent(
+        name="IT Support",
+        instructions=f"""You are an IT support agent. Help users with technical issues.
+        
+        IT SUPPORT DOCS:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "How do I set up VPN?"
+    
+    policies = [
+        (RetrievalPolicy.AUTO, "Agent decides based on query analysis"),
+        (RetrievalPolicy.ALWAYS, "Always retrieve, even for simple queries"),
+        (RetrievalPolicy.NEVER, "Never retrieve, use only parametric knowledge"),
+    ]
+    
+    print(f"\n📝 Query: {query}\n")
+    
+    for policy, description in policies:
+        config = AutoRagConfig(retrieval_policy=policy)
+        auto_agent = AutoRagAgent(agent=base_agent, config=config)
+        
+        print(f"🔄 Policy: {policy.value.upper()}")
+        print(f"   Description: {description}")
+        
+        response = auto_agent.chat(query)
+        print(f"   Response: {response[:150]}...")
+        print()
+
+
+def adaptive_top_k():
+    """Demonstrate adaptive top-k based on query complexity."""
+    
+    print("\n" + "=" * 60)
+    print("ADAPTIVE TOP-K RETRIEVAL")
+    print("=" * 60)
+    
+    print("""
+    📊 Adaptive Top-K Strategy:
+    
+    Query Complexity → Top-K Value
+    ─────────────────────────────────
+    Simple (single topic)     → k=1-2
+    Moderate (related topics) → k=3-5
+    Complex (multi-topic)     → k=5-10
+    
+    Examples:
+    """)
+    
+    queries = [
+        ("Reset password", 2, "Simple - single procedure"),
+        ("VPN not working, also need email setup", 5, "Moderate - two topics"),
+        ("New employee setup: email, VPN, printer, software", 8, "Complex - multiple topics"),
+    ]
+    
+    for query, suggested_k, complexity in queries:
+        print(f"   Query: \"{query}\"")
+        print(f"   Complexity: {complexity}")
+        print(f"   Suggested top_k: {suggested_k}")
+        print()
+
+
+def priority_based_retrieval():
+    """Demonstrate priority-based document retrieval."""
+    
+    print("\n" + "=" * 60)
+    print("PRIORITY-BASED RETRIEVAL")
+    print("=" * 60)
+    
+    # Group documents by priority
+    high_priority = [d for d in IT_SUPPORT_DOCS if d.get('priority') == 'high']
+    all_docs = IT_SUPPORT_DOCS
+    
+    print("\n📊 Document Priorities in Knowledge Base:")
+    for doc in IT_SUPPORT_DOCS:
+        print(f"   [{doc['priority'].upper():^6}] {doc['id']}")
+    
+    # Build contexts
+    high_context = "\n\n".join([f"[{d['id']}]\n{d['content']}" for d in high_priority])
+    full_context = "\n\n".join([f"[{d['id']}]\n{d['content']}" for d in all_docs])
+    
+    # High-priority agent (for urgent issues)
+    urgent_agent = Agent(
+        name="Urgent Support",
+        instructions=f"""Handle urgent IT issues. Focus on critical procedures.
+        
+        HIGH PRIORITY DOCS:
+        {high_context}""",
+        verbose=False
+    )
+    
+    # Full knowledge agent
+    full_agent = Agent(
+        name="Full Support",
+        instructions=f"""Handle all IT support requests.
+        
+        IT SUPPORT DOCS:
+        {full_context}""",
+        verbose=False
+    )
+    
+    query = "I'm locked out of my account!"
+    
+    print(f"\n📝 Urgent Query: {query}")
+    
+    print("\n🚨 Urgent Support Agent (high-priority docs only):")
+    response1 = urgent_agent.chat(query)
+    print(f"   {response1[:200]}...")
+    
+    print("\n📚 Full Support Agent (all docs):")
+    response2 = full_agent.chat(query)
+    print(f"   {response2[:200]}...")
+
+
+def context_aware_retrieval():
+    """Demonstrate context-aware retrieval strategies."""
+    
+    print("\n" + "=" * 60)
+    print("CONTEXT-AWARE RETRIEVAL")
+    print("=" * 60)
+    
+    print("""
+    🎯 Context-Aware Retrieval Strategies:
+    
+    1. **User Role Context**
+       - New employee → Onboarding docs first
+       - IT admin → Technical docs
+       - Executive → Summary docs
+    
+    2. **Time Context**
+       - Business hours → Standard support
+       - After hours → Emergency procedures only
+    
+    3. **Conversation Context**
+       - First message → Broad retrieval
+       - Follow-up → Narrow to topic
+    
+    4. **Device Context**
+       - Mobile → Mobile-specific guides
+       - Desktop → Full documentation
+    
+    Implementation:
+    ```python
+    def get_retrieval_config(context: dict) -> dict:
+        if context.get("user_role") == "new_employee":
+            return {"filter": {"category": "onboarding"}, "top_k": 5}
+        elif context.get("is_followup"):
+            return {"top_k": 2}  # Narrow focus
+        else:
+            return {"top_k": 3}  # Default
+    ```
+    """)
+
+
+def fallback_strategies():
+    """Demonstrate fallback strategies when retrieval fails."""
+    
+    print("\n" + "=" * 60)
+    print("RETRIEVAL FALLBACK STRATEGIES")
+    print("=" * 60)
+    
+    print("""
+    🔄 Fallback Strategy Chain:
+    
+    1. Primary: Vector search in knowledge base
+       ↓ (if no relevant results)
+    2. Secondary: Expand search with synonyms
+       ↓ (if still no results)
+    3. Tertiary: Search external sources
+       ↓ (if still no results)
+    4. Final: Acknowledge limitation, offer alternatives
+    
+    Example Implementation:
+    ```python
+    def retrieve_with_fallback(query: str, knowledge) -> str:
+        # Primary retrieval
+        results = knowledge.search(query, top_k=3)
+        
+        if results and results[0].score > 0.7:
+            return format_context(results)
+        
+        # Fallback: Expand query
+        expanded = expand_query(query)  # Add synonyms
+        results = knowledge.search(expanded, top_k=5)
+        
+        if results and results[0].score > 0.5:
+            return format_context(results)
+        
+        # Final fallback
+        return "I don't have specific information about that. " \\
+               "Please contact IT helpdesk at ext. 1234."
+    ```
+    """)
+
+
+def retrieval_metrics():
+    """Explain retrieval quality metrics."""
+    
+    print("\n" + "=" * 60)
+    print("RETRIEVAL QUALITY METRICS")
+    print("=" * 60)
+    
+    print("""
+    📈 Key Metrics for Retrieval Policy Tuning:
+    
+    ┌─────────────────┬────────────────────────────────────────┐
+    │ Metric          │ Description                            │
+    ├─────────────────┼────────────────────────────────────────┤
+    │ Precision@K     │ % of retrieved docs that are relevant │
+    │ Recall@K        │ % of relevant docs that are retrieved │
+    │ MRR             │ Mean Reciprocal Rank of first hit     │
+    │ NDCG            │ Normalized Discounted Cumulative Gain │
+    │ Latency         │ Time to retrieve (ms)                 │
+    │ Token Usage     │ Context tokens consumed               │
+    └─────────────────┴────────────────────────────────────────┘
+    
+    Policy Optimization Goals:
+    
+    - High Precision: Use smaller top_k, stricter thresholds
+    - High Recall: Use larger top_k, relaxed thresholds
+    - Low Latency: Use smaller top_k, skip reranking
+    - Low Cost: Use smaller top_k, aggressive filtering
+    
+    Balanced Default:
+    ```python
+    config = {
+        "top_k": 3,
+        "score_threshold": 0.5,
+        "rerank": True,
+        "max_tokens": 2000
+    }
+    ```
+    """)
+
+
+def main():
+    """Run all retrieval policy examples."""
+    print("\n🚀 PraisonAI Retrieval Policies Examples\n")
+    
+    # Example 1: Query classification
+    query_classification()
+    
+    # Example 2: Policy comparison
+    policy_based_retrieval()
+    
+    # Example 3: Adaptive top-k
+    adaptive_top_k()
+    
+    # Example 4: Priority-based
+    priority_based_retrieval()
+    
+    # Example 5: Context-aware
+    context_aware_retrieval()
+    
+    # Example 6: Fallback strategies
+    fallback_strategies()
+    
+    # Example 7: Metrics
+    retrieval_metrics()
+    
+    print("\n✅ Retrieval policies examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/rag/structured_output.py

@@ -0,0 +1,359 @@
+"""
+Structured Output RAG: Guided and Constrained Generation
+
+This example demonstrates how to guide RAG output into specific formats
+and structures using Pydantic models and output constraints.
+
+RAG Concept: Sometimes you need RAG answers in a specific format - JSON,
+tables, or structured data. Guided generation ensures the LLM output
+conforms to your schema.
+"""
+
+from typing import List
+from pydantic import BaseModel, Field
+from praisonaiagents import Agent
+
+# Sample knowledge base: Product catalog
+PRODUCT_CATALOG = [
+    {
+        "id": "prod_001",
+        "content": """
+        Product: UltraWidget Pro
+        Category: Electronics
+        Price: $299.99
+        Rating: 4.5/5 (1,250 reviews)
+        Features: Wireless connectivity, 12-hour battery, water-resistant
+        Availability: In stock
+        SKU: UW-PRO-2024
+        """
+    },
+    {
+        "id": "prod_002",
+        "content": """
+        Product: SmartHome Hub
+        Category: Home Automation
+        Price: $149.99
+        Rating: 4.2/5 (890 reviews)
+        Features: Voice control, 100+ device compatibility, energy monitoring
+        Availability: In stock
+        SKU: SH-HUB-2024
+        """
+    },
+    {
+        "id": "prod_003",
+        "content": """
+        Product: ErgoDesk Standing Desk
+        Category: Furniture
+        Price: $599.99
+        Rating: 4.8/5 (2,100 reviews)
+        Features: Electric height adjustment, memory presets, cable management
+        Availability: Ships in 3-5 days
+        SKU: ED-STAND-2024
+        """
+    },
+    {
+        "id": "prod_004",
+        "content": """
+        Product: CloudSync Backup Drive
+        Category: Storage
+        Price: $199.99
+        Rating: 4.6/5 (1,800 reviews)
+        Features: 4TB capacity, automatic backup, encrypted storage
+        Availability: In stock
+        SKU: CS-4TB-2024
+        """
+    }
+]
+
+
+# Pydantic models for structured output
+class ProductInfo(BaseModel):
+    """Structured product information."""
+    name: str = Field(description="Product name")
+    price: float = Field(description="Price in USD")
+    rating: float = Field(description="Rating out of 5")
+    in_stock: bool = Field(description="Whether product is in stock")
+    key_features: List[str] = Field(description="Top 3 features")
+
+
+class ProductComparison(BaseModel):
+    """Structured comparison of products."""
+    products: List[str] = Field(description="Names of compared products")
+    winner: str = Field(description="Recommended product")
+    reason: str = Field(description="Why this product is recommended")
+    price_range: str = Field(description="Price range of compared products")
+
+
+class SearchResult(BaseModel):
+    """Structured search result."""
+    query: str = Field(description="Original search query")
+    matches: List[str] = Field(description="Matching product names")
+    total_found: int = Field(description="Number of matches")
+    summary: str = Field(description="Brief summary of results")
+
+
+def json_output_rag():
+    """Demonstrate RAG with JSON-structured output."""
+    
+    print("=" * 60)
+    print("JSON-STRUCTURED RAG OUTPUT")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in PRODUCT_CATALOG])
+    
+    agent = Agent(
+        name="Product Assistant",
+        instructions=f"""You are a product assistant that provides structured information.
+        Always respond with valid JSON matching the requested format.
+        Extract accurate information from the product catalog.
+        
+        PRODUCT CATALOG:
+        {context}""",
+        verbose=False
+    )
+    
+    # Request structured product info
+    query = """
+    Tell me about the UltraWidget Pro. Respond in this JSON format:
+    {
+        "name": "product name",
+        "price": 0.00,
+        "rating": 0.0,
+        "in_stock": true/false,
+        "key_features": ["feature1", "feature2", "feature3"]
+    }
+    """
+    
+    print("\n📝 Query: Get structured product info")
+    response = agent.chat(query)
+    print("💡 Structured Response:\n" + str(response))
+    print("-" * 40)
+
+
+def pydantic_guided_rag():
+    """Demonstrate RAG with Pydantic model guidance."""
+    
+    print("\n" + "=" * 60)
+    print("PYDANTIC-GUIDED RAG")
+    print("=" * 60)
+    
+    # Generate schema from Pydantic model
+    schema = ProductComparison.model_json_schema()
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in PRODUCT_CATALOG])
+    
+    agent = Agent(
+        name="Product Comparator",
+        instructions=f"""You compare products and provide structured recommendations.
+        Your response MUST be valid JSON matching this schema:
+        {schema}
+        
+        Be objective and base recommendations on the product data.
+        
+        PRODUCT CATALOG:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "Compare the UltraWidget Pro and SmartHome Hub. Which should I buy?"
+    
+    print(f"\n📝 Query: {query}")
+    print("📋 Expected Schema: ProductComparison")
+    
+    response = agent.chat(query)
+    print(f"\n💡 Structured Comparison:\n{response}")
+
+
+def table_format_rag():
+    """Demonstrate RAG with table-formatted output."""
+    
+    print("\n" + "=" * 60)
+    print("TABLE-FORMATTED RAG")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in PRODUCT_CATALOG])
+    
+    agent = Agent(
+        name="Catalog Browser",
+        instructions=f"""You present product information in clean table format.
+        Use markdown tables for structured data.
+        Include relevant columns based on the query.
+        
+        PRODUCT CATALOG:
+        {context}""",
+        verbose=False
+    )
+    
+    query = "Show me all products in a table with name, price, and rating."
+    
+    print(f"\n📝 Query: {query}")
+    response = agent.chat(query)
+    print(f"\n💡 Table Output:\n{response}")
+
+
+def list_format_rag():
+    """Demonstrate RAG with list-formatted output."""
+    
+    print("\n" + "=" * 60)
+    print("LIST-FORMATTED RAG")
+    print("=" * 60)
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in PRODUCT_CATALOG])
+    
+    agent = Agent(
+        name="Feature Lister",
+        instructions=f"""You extract and present information as organized lists.
+        Use bullet points and numbered lists appropriately.
+        Group related items together.
+        
+        PRODUCT CATALOG:
+        {context}""",
+        verbose=False
+    )
+    
+    queries = [
+        "List all product features across the catalog",
+        "What are the top-rated products? List them in order."
+    ]
+    
+    for query in queries:
+        print(f"\n📝 Query: {query}")
+        response = agent.chat(query)
+        print(f"💡 List Output:\n{response[:400]}..." if len(str(response)) > 400 else f"💡 List Output:\n{response}")
+        print("-" * 40)
+
+
+def constrained_generation():
+    """Demonstrate constrained/guided generation patterns."""
+    
+    print("\n" + "=" * 60)
+    print("CONSTRAINED GENERATION PATTERNS")
+    print("=" * 60)
+    
+    print("""
+    🎯 Constrained Generation Techniques:
+    
+    1. **Schema Enforcement**
+       - Provide JSON schema in instructions
+       - Agent outputs valid JSON matching schema
+       ```python
+       instructions = f"Respond with JSON matching: {schema}"
+       ```
+    
+    2. **Format Templates**
+       - Give explicit output templates
+       - Agent fills in the blanks
+       ```python
+       instructions = '''
+       Respond in this format:
+       PRODUCT: [name]
+       PRICE: $[amount]
+       VERDICT: [recommendation]
+       '''
+       ```
+    
+    3. **Pydantic Validation**
+       - Parse agent output with Pydantic
+       - Retry if validation fails
+       ```python
+       response = agent.chat(query)
+       try:
+           result = ProductInfo.model_validate_json(response)
+       except ValidationError:
+           # Retry with clarification
+       ```
+    
+    4. **Output Parsers**
+       - Post-process agent output
+       - Extract structured data from text
+       ```python
+       def parse_product(text: str) -> dict:
+           # Extract price, rating, etc.
+           return structured_data
+       ```
+    
+    5. **Few-Shot Examples**
+       - Show examples of desired output format
+       - Agent learns pattern from examples
+       ```python
+       instructions = '''
+       Example:
+       Q: Tell me about Product X
+       A: {"name": "Product X", "price": 99.99}
+       
+       Now answer the user's question in the same format.
+       '''
+       ```
+    """)
+
+
+def multi_format_rag():
+    """Demonstrate switching between output formats."""
+    
+    print("\n" + "=" * 60)
+    print("MULTI-FORMAT RAG")
+    print("=" * 60)
+    
+    base_knowledge = PRODUCT_CATALOG
+    query = "Tell me about the ErgoDesk Standing Desk"
+    
+    formats = [
+        ("JSON", "Respond with a JSON object containing name, price, and features."),
+        ("Markdown", "Respond with a markdown-formatted product card with headers."),
+        ("Plain Text", "Respond with a brief, conversational product description."),
+        ("Bullet Points", "Respond with bullet points covering key product details.")
+    ]
+    
+    print(f"\n📝 Base Query: {query}")
+    print("\n🔄 Same query, different output formats:\n")
+    
+    # Build context
+    context = "\n\n".join([f"[{p['id']}]\n{p['content']}" for p in base_knowledge])
+    
+    for format_name, format_instruction in formats:
+        agent = Agent(
+            name=f"{format_name} Agent",
+            instructions=f"""You are a product expert. {format_instruction}
+            
+            PRODUCT CATALOG:
+            {context}""",
+            verbose=False
+        )
+        
+        response = agent.chat(query)
+        print(f"📋 {format_name} Format:")
+        print(f"{response[:250]}..." if len(str(response)) > 250 else response)
+        print("-" * 40)
+
+
+def main():
+    """Run all structured output RAG examples."""
+    print("\n🚀 PraisonAI Structured Output RAG Examples\n")
+    
+    # Example 1: JSON output
+    json_output_rag()
+    
+    # Example 2: Pydantic-guided
+    pydantic_guided_rag()
+    
+    # Example 3: Table format
+    table_format_rag()
+    
+    # Example 4: List format
+    list_format_rag()
+    
+    # Example 5: Constrained generation patterns
+    constrained_generation()
+    
+    # Example 6: Multi-format
+    multi_format_rag()
+    
+    print("\n✅ Structured output RAG examples completed!")
+
+
+if __name__ == "__main__":
+    main()

examples/retrieval/basic_retrieval.py

@@ -0,0 +1,105 @@
+"""
+Basic Agent Retrieval Example
+
+Demonstrates the Agent-first retrieval API with knowledge and retrieval_config.
+"""
+
+import os
+from praisonaiagents import Agent
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+# Create a simple text file for testing
+test_content = """
+# PraisonAI Framework Overview
+
+PraisonAI is an AI agents framework that enables building sophisticated AI applications.
+
+## Key Features
+
+1. **Agent-First Design**: Everything centers around the Agent class
+2. **Knowledge Integration**: Agents can use knowledge bases for retrieval
+3. **Unified Configuration**: Single retrieval_config for all retrieval settings
+4. **Multi-Agent Support**: Multiple agents can share knowledge
+
+## Retrieval Policies
+
+- **auto**: Automatically decide when to retrieve based on query
+- **always**: Always retrieve for every query
+- **never**: Never retrieve (use for pure generation)
+
+## Citation Modes
+
+- **append**: Add citations at the end of the response
+- **inline**: Include citations inline in the text
+- **hidden**: Citations available in result but not in text
+"""
+
+# Write test content to a file
+os.makedirs(".praison/test_docs", exist_ok=True)
+with open(".praison/test_docs/overview.txt", "w") as f:
+    f.write(test_content)
+
+print("=" * 60)
+print("Basic Agent Retrieval Example")
+print("=" * 60)
+
+# Create agent with knowledge and retrieval config
+agent = Agent(
+    name="Knowledge Agent",
+    instructions="You are a helpful assistant that answers questions based on the provided knowledge. Be concise.",
+    knowledge=[".praison/test_docs/overview.txt"],
+    retrieval_config={
+        "policy": "always",      # Always retrieve for this demo
+        "top_k": 3,              # Get top 3 chunks
+        "citations": True,       # Include citations
+        "max_context_tokens": 2000,
+    }
+)
+
+# Test 1: Basic chat with retrieval
+print("\n1. Basic Chat with Retrieval:")
+print("-" * 40)
+response = agent.chat("What are the key features of PraisonAI?")
+print(response)
+
+# Test 2: Query with structured result
+print("\n2. Structured Query with Citations:")
+print("-" * 40)
+try:
+    result = agent.query("What are the retrieval policies?")
+    print(f"Answer: {result.answer}")
+    if result.citations:
+        print(f"\nCitations ({len(result.citations)}):")
+        for citation in result.citations:
+            print(f"  - {citation.source}")
+except Exception as e:
+    print(f"Query not available (RAG module may not be installed): {e}")
+
+# Test 3: Retrieve only (no LLM generation)
+print("\n3. Retrieve Only (No LLM):")
+print("-" * 40)
+try:
+    context = agent.retrieve("citation modes")
+    print(f"Found context: {len(context.context)} chars")
+    if context.citations:
+        print(f"Sources: {len(context.citations)}")
+except Exception as e:
+    print(f"Retrieve not available (RAG module may not be installed): {e}")
+
+# Test 4: Skip retrieval
+print("\n4. Chat with skip_retrieval=True:")
+print("-" * 40)
+response = agent.chat("What is 2 + 2?", skip_retrieval=True)
+print(response)
+
+print("\n" + "=" * 60)
+print("Example Complete!")
+print("=" * 60)
+
+# Cleanup
+import shutil
+shutil.rmtree(".praison/test_docs", ignore_errors=True)

examples/thinking/basic_thinking.py

@@ -2,31 +2,29 @@
 """
 Basic Thinking Budgets Example for PraisonAI Agents.
 
-This example demonstrates how to use thinking budgets to:
-1. Configure token budgets for extended thinking
+This example demonstrates how to use thinking budgets with Agent:
+1. Create an Agent with thinking budget
 2. Use predefined budget levels
 3. Track thinking usage
-4. Adapt budgets based on complexity
 
 Usage:
     python basic_thinking.py
 """
 
-from praisonaiagents.thinking import (
-    ThinkingBudget, ThinkingConfig, ThinkingUsage, ThinkingTracker
-)
+from praisonaiagents import Agent
+from praisonaiagents.thinking import ThinkingBudget, ThinkingTracker
 from praisonaiagents.thinking.budget import BudgetLevel
 
 
 def main():
     print("=" * 60)
-    print("Thinking Budgets Demo")
+    print("Agent-Centric Thinking Budgets Demo")
     print("=" * 60)
     
     # ==========================================================================
     # Budget Levels
     # ==========================================================================
-    print("\n--- Budget Levels ---")
+    print("\n--- Available Budget Levels ---")
     
     levels = [
         ("Minimal", ThinkingBudget.minimal()),
@@ -39,10 +37,25 @@ def main():
     for name, budget in levels:
         print(f"  {name}: {budget.max_tokens:,} tokens")
     
+    # ==========================================================================
+    # Agent with Thinking Budget
+    # ==========================================================================
+    print("\n--- Creating Agent with Thinking Budget ---")
+    
+    agent = Agent(
+        name="DeepThinker",
+        instructions="You are a problem-solving assistant that thinks step by step.",
+        thinking_budget=ThinkingBudget.high()  # 16,000 tokens for reasoning
+    )
+    
+    print(f"Agent: {agent.name}")
+    print(f"Thinking budget: {agent.thinking_budget.max_tokens:,} tokens")
+    print(f"Adaptive: {agent.thinking_budget.adaptive}")
+    
     # ==========================================================================
     # Custom Budget
     # ==========================================================================
-    print("\n--- Custom Budget ---")
+    print("\n--- Custom Thinking Budget ---")
     
     custom_budget = ThinkingBudget(
         max_tokens=12000,
@@ -50,22 +63,24 @@ def main():
         adaptive=True,
         max_time_seconds=120.0
     )
-    print(f"  Max tokens: {custom_budget.max_tokens:,}")
-    print(f"  Min tokens: {custom_budget.min_tokens:,}")
-    print(f"  Adaptive: {custom_budget.adaptive}")
-    print(f"  Time limit: {custom_budget.max_time_seconds}s")
+    
+    agent_custom = Agent(
+        name="CustomThinker",
+        instructions="You solve complex problems.",
+        thinking_budget=custom_budget
+    )
+    
+    print(f"Agent: {agent_custom.name}")
+    print(f"Max tokens: {agent_custom.thinking_budget.max_tokens:,}")
+    print(f"Min tokens: {agent_custom.thinking_budget.min_tokens:,}")
+    print(f"Time limit: {agent_custom.thinking_budget.max_time_seconds}s")
     
     # ==========================================================================
     # Complexity-Based Scaling
     # ==========================================================================
     print("\n--- Complexity-Based Token Allocation ---")
     
-    budget = ThinkingBudget(
-        max_tokens=16000,
-        min_tokens=2000,
-        adaptive=True
-    )
-    
+    budget = agent.thinking_budget
     complexities = [0.0, 0.25, 0.5, 0.75, 1.0]
     for complexity in complexities:
         tokens = budget.get_tokens_for_complexity(complexity)
@@ -75,34 +90,15 @@ def main():
     # ==========================================================================
     # Usage Tracking
     # ==========================================================================
-    print("\n--- Usage Tracking ---")
-    
-    usage = ThinkingUsage(
-        budget_tokens=8000,
-        tokens_used=5000,
-        time_seconds=30.0,
-        budget_time=60.0
-    )
-    
-    print(f"  Tokens used: {usage.tokens_used:,} / {usage.budget_tokens:,}")
-    print(f"  Tokens remaining: {usage.tokens_remaining:,}")
-    print(f"  Utilization: {usage.token_utilization:.1%}")
-    print(f"  Over budget: {usage.is_over_budget}")
-    print(f"  Time remaining: {usage.time_remaining}s")
-    
-    # ==========================================================================
-    # Session Tracking
-    # ==========================================================================
     print("\n--- Session Tracking ---")
     
     tracker = ThinkingTracker()
     
-    # Simulate multiple thinking sessions
+    # Simulate thinking sessions
     sessions = [
         (8000, 4000, 20.0),
         (8000, 6000, 35.0),
         (16000, 12000, 60.0),
-        (8000, 9000, 45.0),  # Over budget
     ]
     
     for budget_tokens, tokens_used, time_seconds in sessions:
@@ -112,21 +108,7 @@ def main():
     summary = tracker.get_summary()
     print(f"  Total sessions: {summary['session_count']}")
     print(f"  Total tokens used: {summary['total_tokens_used']:,}")
-    print(f"  Average tokens/session: {summary['average_tokens_per_session']:,.0f}")
     print(f"  Average utilization: {summary['average_utilization']:.1%}")
-    print(f"  Over-budget sessions: {summary['over_budget_count']}")
-    
-    # ==========================================================================
-    # Serialization
-    # ==========================================================================
-    print("\n--- Serialization ---")
-    
-    budget = ThinkingBudget.from_level(BudgetLevel.HIGH)
-    data = budget.to_dict()
-    print(f"  Serialized: level={data['level']}, max_tokens={data['max_tokens']}")
-    
-    restored = ThinkingBudget.from_dict(data)
-    print(f"  Restored: {restored.max_tokens:,} tokens")
     
     print("\n" + "=" * 60)
     print("Demo Complete!")

scripts/generate_cli_docs.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+Auto-generate CLI reference documentation from --help output.
+
+Usage:
+    python scripts/generate_cli_docs.py > docs/cli/reference.mdx
+    python scripts/generate_cli_docs.py --output docs/cli/reference.mdx
+
+This script runs `praisonai <cmd> --help` for key commands and generates
+deterministic markdown documentation.
+"""
+
+import subprocess
+import sys
+import argparse
+from datetime import datetime
+from pathlib import Path
+
+
+# Commands to document
+COMMANDS = [
+    # Top-level
+    ("praisonai", "--help"),
+    # Knowledge
+    ("praisonai knowledge", "--help"),
+    ("praisonai knowledge index", "--help"),
+    ("praisonai knowledge search", "--help"),
+    ("praisonai knowledge add", "--help"),
+    ("praisonai knowledge list", "--help"),
+    # RAG
+    ("praisonai rag", "--help"),
+    ("praisonai rag index", "--help"),
+    ("praisonai rag query", "--help"),
+    ("praisonai rag chat", "--help"),
+    ("praisonai rag eval", "--help"),
+    ("praisonai rag serve", "--help"),
+    # Run
+    ("praisonai run", "--help"),
+    # Chat
+    ("praisonai chat", "--help"),
+]
+
+
+def run_help(cmd: str, flag: str = "--help") -> str:
+    """Run a command with --help and capture output."""
+    full_cmd = f"{cmd} {flag}"
+    try:
+        result = subprocess.run(
+            full_cmd.split(),
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        return result.stdout or result.stderr or "(no output)"
+    except subprocess.TimeoutExpired:
+        return "(timeout)"
+    except FileNotFoundError:
+        return "(command not found)"
+    except Exception as e:
+        return f"(error: {e})"
+
+
+def generate_markdown() -> str:
+    """Generate markdown documentation."""
+    lines = [
+        "---",
+        "title: CLI Reference",
+        "description: Auto-generated CLI command reference",
+        "---",
+        "",
+        "# PraisonAI CLI Reference",
+        "",
+        "This page is auto-generated from `--help` output.",
+        "",
+        f"Generated: {datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S')} UTC",
+        "",
+    ]
+    
+    for cmd, flag in COMMANDS:
+        # Section header
+        cmd_name = cmd.replace("praisonai ", "").replace(" ", "-") or "main"
+        lines.append(f"## `{cmd}`")
+        lines.append("")
+        lines.append("```")
+        
+        # Get help output
+        output = run_help(cmd, flag)
+        lines.append(output.strip())
+        
+        lines.append("```")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate CLI docs from --help")
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        help="Output file path (default: stdout)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if output matches existing file (for CI)",
+    )
+    args = parser.parse_args()
+    
+    content = generate_markdown()
+    
+    if args.check and args.output:
+        if args.output.exists():
+            existing = args.output.read_text()
+            # Compare ignoring timestamp line
+            existing_lines = [l for l in existing.split("\n") if not l.startswith("Generated:")]
+            new_lines = [l for l in content.split("\n") if not l.startswith("Generated:")]
+            if existing_lines != new_lines:
+                print(f"ERROR: {args.output} is out of date. Run: python scripts/generate_cli_docs.py -o {args.output}", file=sys.stderr)
+                sys.exit(1)
+            print(f"OK: {args.output} is up to date")
+            sys.exit(0)
+        else:
+            print(f"ERROR: {args.output} does not exist", file=sys.stderr)
+            sys.exit(1)
+    
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(content)
+        print(f"Written to {args.output}")
+    else:
+        print(content)
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/examples/fast_context_example.py

@@ -78,26 +78,29 @@ def example_get_context_for_agent():
 # =============================================
 
 def example_agent_with_fast_context():
-    """Use FastContext with an Agent."""
+    """Use FastContext with an Agent via context= param."""
     from praisonaiagents import Agent
+    from praisonaiagents.context.fast import FastContext
     
-    # Create agent with FastContext enabled
+    # Create FastContext instance
+    fc = FastContext(workspace_path=".")
+    
+    # Search for code context
+    result = fc.search("find authentication code")
+    context = result.to_context_string() if result.files else None
+    
+    # Create agent with context management enabled
     agent = Agent(
         name="CodeAssistant",
         instructions="You are a helpful code assistant.",
-        fast_context=True,
-        fast_context_path=".",  # Current directory
-        fast_context_model="gpt-4o-mini",
-        fast_context_max_turns=4,
-        fast_context_parallelism=8
+        context=True,  # Enable context management
     )
     
-    # Use delegate_to_fast_context for code search
-    context = agent.delegate_to_fast_context("find authentication code")
-    
     if context:
         print("Found relevant code context:")
         print(context[:300] + "...")
+        # Use the context in a chat
+        print(agent.chat(f"Based on this code:\n{context}\n\nExplain the authentication flow."))
     else:
         print("No relevant code found")
 

src/praisonai-agents/examples/large_context_knowledge.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""
+Large Context Knowledge Handling Example
+
+Demonstrates the full pipeline:
+1. Token Budget calculation
+2. Incremental indexing with ignore patterns
+3. Strategy selection based on corpus size
+4. Smart retrieval with filtering
+5. Contextual compression
+6. Hierarchical summarization
+
+Usage:
+    python examples/large_context_knowledge.py
+"""
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def create_sample_corpus(base_path: str) -> None:
+    """Create a sample corpus for demonstration."""
+    # Create directory structure
+    src_dir = Path(base_path) / "src"
+    docs_dir = Path(base_path) / "docs"
+    src_dir.mkdir(parents=True, exist_ok=True)
+    docs_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Create Python files
+    (src_dir / "main.py").write_text("""
+# Main application entry point
+def main():
+    '''Start the application.'''
+    print("Hello from PraisonAI!")
+    
+if __name__ == "__main__":
+    main()
+""")
+    
+    (src_dir / "utils.py").write_text("""
+# Utility functions
+def helper_function(x: int) -> int:
+    '''Double the input value.'''
+    return x * 2
+
+def format_output(text: str) -> str:
+    '''Format text for display.'''
+    return f"[OUTPUT] {text}"
+""")
+    
+    # Create documentation
+    (docs_dir / "readme.md").write_text("""
+# Project Documentation
+
+This is a sample project demonstrating large context knowledge handling.
+
+## Features
+- Token budget management
+- Incremental indexing
+- Smart retrieval
+- Contextual compression
+""")
+    
+    (docs_dir / "api.md").write_text("""
+# API Reference
+
+## Functions
+
+### main()
+Entry point for the application.
+
+### helper_function(x)
+Doubles the input value.
+
+### format_output(text)
+Formats text for display.
+""")
+    
+    # Create .praisonignore
+    (Path(base_path) / ".praisonignore").write_text("""
+# Ignore patterns
+*.pyc
+__pycache__/
+.git/
+""")
+    
+    print(f"Created sample corpus at: {base_path}")
+
+
+def demo_token_budget():
+    """Demonstrate token budget calculation."""
+    print("\n" + "="*60)
+    print("1. TOKEN BUDGET CALCULATION")
+    print("="*60)
+    
+    from praisonaiagents.rag.budget import TokenBudget, get_model_context_window
+    
+    # Get context window for different models
+    models = ["gpt-4o", "claude-3.5-sonnet", "gemini-1.5-pro", "llama-3.1-70b"]
+    print("\nModel context windows:")
+    for model in models:
+        window = get_model_context_window(model)
+        print(f"  {model}: {window:,} tokens")
+    
+    # Create budget for GPT-4o
+    budget = TokenBudget.from_model("gpt-4o")
+    print(f"\nBudget for GPT-4o:")
+    print(f"  Max tokens: {budget.model_max_tokens:,}")
+    print(f"  Reserved for response: {budget.reserved_response_tokens:,}")
+    print(f"  Max context tokens: {budget.max_context_tokens:,}")
+    
+    # Dynamic budget calculation
+    available = budget.dynamic_budget(
+        prompt_tokens=500,
+        history_tokens=2000,
+        system_tokens=1000,
+    )
+    print(f"\nDynamic budget (with 500 prompt + 2000 history + 1000 system):")
+    print(f"  Available for context: {available:,} tokens")
+
+
+def demo_indexing(corpus_path: str):
+    """Demonstrate incremental indexing."""
+    print("\n" + "="*60)
+    print("2. INCREMENTAL INDEXING")
+    print("="*60)
+    
+    from praisonaiagents.knowledge import Knowledge
+    from praisonaiagents.knowledge.indexing import CorpusStats
+    
+    # Get corpus stats before indexing
+    stats = CorpusStats.from_directory(corpus_path)
+    print(f"\nCorpus statistics:")
+    print(f"  Files: {stats.file_count}")
+    print(f"  Estimated tokens: {stats.total_tokens:,}")
+    print(f"  Recommended strategy: {stats.strategy_recommendation}")
+    
+    # Index the corpus
+    knowledge = Knowledge()
+    result = knowledge.index(
+        corpus_path,
+        user_id="demo_user",
+        incremental=False,
+        exclude_glob=["*.pyc"],
+    )
+    
+    print(f"\nIndexing result:")
+    print(f"  Files indexed: {result.files_indexed}")
+    print(f"  Files skipped: {result.files_skipped}")
+    print(f"  Chunks created: {result.chunks_created}")
+    print(f"  Duration: {result.duration_seconds:.2f}s")
+    
+    # Incremental re-index (should skip unchanged files)
+    print("\nRe-indexing (incremental)...")
+    result2 = knowledge.index(corpus_path, user_id="demo_user", incremental=True)
+    print(f"  Files indexed: {result2.files_indexed}")
+    print(f"  Files skipped: {result2.files_skipped}")
+
+
+def demo_strategy_selection():
+    """Demonstrate strategy selection."""
+    print("\n" + "="*60)
+    print("3. STRATEGY SELECTION")
+    print("="*60)
+    
+    from praisonaiagents.rag.strategy import select_strategy, get_strategy_description, RetrievalStrategy
+    from praisonaiagents.knowledge.indexing import CorpusStats
+    
+    # Show strategy for different corpus sizes
+    sizes = [5, 50, 500, 5000, 50000, 500000]
+    print("\nStrategy selection by corpus size:")
+    for size in sizes:
+        stats = CorpusStats(file_count=size)
+        strategy = select_strategy(stats)
+        print(f"  {size:>7} files -> {strategy.value}")
+    
+    # Show strategy descriptions
+    print("\nStrategy descriptions:")
+    for strategy in RetrievalStrategy:
+        desc = get_strategy_description(strategy)
+        print(f"  {strategy.value}: {desc[:60]}...")
+
+
+def demo_smart_retriever():
+    """Demonstrate smart retriever with filtering."""
+    print("\n" + "="*60)
+    print("4. SMART RETRIEVER")
+    print("="*60)
+    
+    from praisonaiagents.rag.retriever import SmartRetriever, SimpleReranker
+    
+    # Create retriever with reranker
+    reranker = SimpleReranker()
+    retriever = SmartRetriever(reranker=reranker)
+    
+    # Demonstrate filtering
+    chunks = [
+        {"text": "Python code for data processing", "metadata": {"filename": "process.py"}},
+        {"text": "JavaScript frontend code", "metadata": {"filename": "app.js"}},
+        {"text": "Python utilities and helpers", "metadata": {"filename": "utils.py"}},
+        {"text": "CSS styling rules", "metadata": {"filename": "styles.css"}},
+    ]
+    
+    print("\nFiltering by include pattern (*.py):")
+    filtered = retriever._apply_filters(chunks, include_glob=["*.py"])
+    for chunk in filtered:
+        print(f"  - {chunk['metadata']['filename']}: {chunk['text'][:40]}...")
+    
+    print("\nFiltering by exclude pattern (utils*):")
+    filtered = retriever._apply_filters(chunks, exclude_glob=["utils*"])
+    for chunk in filtered:
+        print(f"  - {chunk['metadata']['filename']}: {chunk['text'][:40]}...")
+    
+    # Demonstrate reranking
+    print("\nReranking for query 'Python data':")
+    reranked = reranker.rerank("Python data", chunks)
+    for i, chunk in enumerate(reranked[:3], 1):
+        print(f"  {i}. [{chunk['score']:.2f}] {chunk['text'][:40]}...")
+
+
+def demo_compression():
+    """Demonstrate contextual compression."""
+    print("\n" + "="*60)
+    print("5. CONTEXTUAL COMPRESSION")
+    print("="*60)
+    
+    from praisonaiagents.rag.compressor import ContextCompressor
+    
+    compressor = ContextCompressor()
+    
+    # Create chunks with some redundancy
+    chunks = [
+        {"text": "Python is a high-level programming language. It is known for its simplicity and readability. Python supports multiple programming paradigms."},
+        {"text": "Python is a high-level programming language. It is known for its simplicity and readability. Python supports multiple programming paradigms."},  # Duplicate
+        {"text": "JavaScript is the language of the web. It runs in browsers and on servers with Node.js."},
+        {"text": "Python has extensive libraries for data science, machine learning, and web development."},
+    ]
+    
+    print(f"\nOriginal chunks: {len(chunks)}")
+    
+    result = compressor.compress(chunks, "Python programming", target_tokens=200)
+    
+    print(f"After compression:")
+    print(f"  Chunks: {len(result.chunks)}")
+    print(f"  Original tokens: {result.original_tokens}")
+    print(f"  Compressed tokens: {result.compressed_tokens}")
+    print(f"  Compression ratio: {result.compression_ratio:.2%}")
+    print(f"  Method: {result.method_used}")
+
+
+def demo_hierarchical_summarizer(corpus_path: str):
+    """Demonstrate hierarchical summarization."""
+    print("\n" + "="*60)
+    print("6. HIERARCHICAL SUMMARIZATION")
+    print("="*60)
+    
+    from praisonaiagents.rag.summarizer import HierarchicalSummarizer
+    
+    summarizer = HierarchicalSummarizer()
+    
+    # Build hierarchy
+    print(f"\nBuilding hierarchy for: {corpus_path}")
+    result = summarizer.build_hierarchy(corpus_path, levels=2)
+    
+    print(f"\nHierarchy result:")
+    print(f"  Total files: {result.total_files}")
+    print(f"  Total nodes: {len(result.nodes)}")
+    print(f"  Total tokens: {result.total_tokens}")
+    
+    # Show summaries
+    print("\nFile summaries:")
+    for path, node in result.nodes.items():
+        if node.level == 1:  # File level
+            filename = node.metadata.get("filename", os.path.basename(path))
+            summary = node.summary[:60] + "..." if len(node.summary) > 60 else node.summary
+            print(f"  {filename}: {summary}")
+    
+    # Query hierarchy
+    print("\nQuerying hierarchy for 'function':")
+    results = summarizer.query_hierarchy("function", corpus_path, max_results=3)
+    for r in results:
+        print(f"  - {os.path.basename(r['path'])}: score={r['score']}")
+
+
+def main():
+    """Run all demonstrations."""
+    print("="*60)
+    print("LARGE CONTEXT KNOWLEDGE HANDLING DEMO")
+    print("="*60)
+    
+    # Create temporary corpus
+    with tempfile.TemporaryDirectory() as tmpdir:
+        create_sample_corpus(tmpdir)
+        
+        # Run demos
+        demo_token_budget()
+        demo_indexing(tmpdir)
+        demo_strategy_selection()
+        demo_smart_retriever()
+        demo_compression()
+        demo_hierarchical_summarizer(tmpdir)
+    
+    print("\n" + "="*60)
+    print("DEMO COMPLETE")
+    print("="*60)
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/praisonaiagents/__init__.py

@@ -189,7 +189,21 @@ def __getattr__(name):
         _lazy_cache[name] = AutoAgents
         return AutoAgents
     
-    # Session (imports requests)
+    # AutoRagAgent (auto RAG retrieval decision)
+    elif name == "AutoRagAgent":
+        from .agents.auto_rag_agent import AutoRagAgent
+        _lazy_cache[name] = AutoRagAgent
+        return AutoRagAgent
+    elif name == "AutoRagConfig":
+        from .agents.auto_rag_agent import AutoRagConfig
+        _lazy_cache[name] = AutoRagConfig
+        return AutoRagConfig
+    elif name == "RagRetrievalPolicy":
+        from .agents.auto_rag_agent import RetrievalPolicy
+        _lazy_cache[name] = RetrievalPolicy
+        return RetrievalPolicy
+    
+    # Session (imports requests lazily via session/api.py)
     elif name == "Session":
         from .session import Session
         _lazy_cache[name] = Session
@@ -234,6 +248,48 @@ def __getattr__(name):
         _lazy_cache[name] = LineRange
         return LineRange
     
+    # Retrieval configuration (Agent-first unified config)
+    elif name == "RetrievalConfig":
+        from praisonaiagents.rag.retrieval_config import RetrievalConfig
+        _lazy_cache[name] = RetrievalConfig
+        return RetrievalConfig
+    elif name == "RetrievalPolicy":
+        from praisonaiagents.rag.retrieval_config import RetrievalPolicy
+        _lazy_cache[name] = RetrievalPolicy
+        return RetrievalPolicy
+    elif name == "CitationsMode":
+        from praisonaiagents.rag.retrieval_config import CitationsMode
+        _lazy_cache[name] = CitationsMode
+        return CitationsMode
+    
+    # RAG models (used by Agent.query() and Agent.retrieve())
+    elif name == "ContextPack":
+        from praisonaiagents.rag.models import ContextPack
+        _lazy_cache[name] = ContextPack
+        return ContextPack
+    elif name == "RAGResult":
+        from praisonaiagents.rag import RAGResult
+        _lazy_cache[name] = RAGResult
+        return RAGResult
+    elif name == "Citation":
+        from praisonaiagents.rag import Citation
+        _lazy_cache[name] = Citation
+        return Citation
+    
+    # RAG internals (advanced use - prefer Agent.query() for normal usage)
+    elif name == "RAG":
+        from praisonaiagents.rag import RAG
+        _lazy_cache[name] = RAG
+        return RAG
+    elif name == "RAGConfig":
+        from praisonaiagents.rag import RAGConfig
+        _lazy_cache[name] = RAGConfig
+        return RAGConfig
+    elif name == "RAGCitation":
+        from praisonaiagents.rag import Citation
+        _lazy_cache[name] = Citation
+        return Citation
+    
     # Agent Skills support (lazy loaded for zero performance impact)
     elif name == "SkillManager":
         from praisonaiagents.skills import SkillManager
@@ -374,6 +430,9 @@ __all__ = [
     'TaskOutput',
     'ReflectionOutput',
     'AutoAgents',
+    'AutoRagAgent',
+    'AutoRagConfig',
+    'RagRetrievalPolicy',
     'Session',
     'Memory',
     'db',
@@ -463,4 +522,9 @@ __all__ = [
     # UI
     'AGUI',
     'A2A',
+    # RAG
+    'RAG',
+    'RAGConfig',
+    'RAGResult',
+    'RAGCitation',
 ]

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

@@ -45,6 +45,7 @@ if TYPE_CHECKING:
     from ..task.task import Task
     from ..main import TaskOutput
     from ..handoff import Handoff
+    from ..rag.models import RAGResult, ContextPack
 
 class Agent:
     @classmethod
@@ -266,11 +267,12 @@ class Agent:
         response_template: Optional[str] = None,
         allow_code_execution: Optional[bool] = False,
         max_retry_limit: int = 2,
-        respect_context_window: bool = True,
         code_execution_mode: Literal["safe", "unsafe"] = "safe",
         embedder_config: Optional[Dict[str, Any]] = None,
-        knowledge: Optional[List[str]] = None,
+        knowledge: Optional[Union[List[str], Any]] = None,
+        retrieval_config: Optional[Union[Dict[str, Any], Any]] = None,
         knowledge_config: Optional[Dict[str, Any]] = None,
+        rag_config: Optional[Dict[str, Any]] = None,
         use_system_prompt: Optional[bool] = True,
         markdown: bool = True,
         stream: bool = False,
@@ -295,13 +297,6 @@ class Agent:
         planning: bool = False,
         planning_tools: Optional[List[Any]] = None,
         planning_reasoning: bool = False,
-        fast_context: bool = False,
-        fast_context_path: Optional[str] = None,
-        fast_context_model: str = "gpt-4o-mini",
-        fast_context_max_turns: int = 4,
-        fast_context_parallelism: int = 8,
-        fast_context_timeout: float = 30.0,
-        history_in_context: Optional[int] = None,
         auto_save: Optional[str] = None,
         skills: Optional[List[str]] = None,
         skills_dirs: Optional[List[str]] = None,
@@ -309,7 +304,16 @@ class Agent:
         session_id: Optional[str] = None,
         hooks: Optional[List[Any]] = None,
         llm_config: Optional[Dict[str, Any]] = None,
-        rate_limiter: Optional[Any] = None
+        rate_limiter: Optional[Any] = None,
+        # Agent-centric feature parameters (lazy loaded)
+        auto_memory: Optional[Any] = None,
+        policy: Optional[Any] = None,
+        background: Optional[Any] = None,
+        checkpoints: Optional[Any] = None,
+        output_style: Optional[Any] = None,
+        thinking_budget: Optional[Any] = None,
+        # Context management (single param for all context features)
+        context: Optional[Union[bool, Any]] = False
     ):
         """Initialize an Agent instance.
 
@@ -358,8 +362,6 @@ class Agent:
                 snippets during task completion. Use with caution for security. Defaults to False.
             max_retry_limit (int, optional): Maximum number of retry attempts for failed operations
                 before giving up. Helps handle transient errors. Defaults to 2.
-            respect_context_window (bool, optional): Automatically manage context window size
-                to prevent token limit errors with large conversations. Defaults to True.
             code_execution_mode (Literal["safe", "unsafe"], optional): Safety mode for code execution.
                 "safe" restricts dangerous operations, "unsafe" allows full code execution. Defaults to "safe".
             embedder_config (Optional[Dict[str, Any]], optional): Configuration dictionary for
@@ -576,7 +578,6 @@ class Agent:
         self.response_template = response_template
         self.allow_code_execution = allow_code_execution
         self.max_retry_limit = max_retry_limit
-        self.respect_context_window = respect_context_window
         self.code_execution_mode = code_execution_mode
         self.embedder_config = embedder_config
         self.knowledge = knowledge
@@ -617,7 +618,6 @@ Your Goal: {self.goal}
         self.claude_memory = claude_memory
         
         # Session management
-        self.history_in_context = history_in_context  # Number of past sessions to include
         self.auto_save = auto_save  # Session name for auto-saving
         
         # Initialize rules manager for persistent context (like Cursor/Windsurf)
@@ -656,26 +656,47 @@ Your Goal: {self.goal}
         self.handoffs = handoffs if handoffs else []
         self._process_handoffs()
 
+        # Initialize unified retrieval configuration
+        # retrieval_config is the SINGLE configuration surface (replaces knowledge_config + rag_config)
+        self._retrieval_config = None
+        if retrieval_config is not None:
+            from ..rag.retrieval_config import RetrievalConfig, create_retrieval_config
+            if isinstance(retrieval_config, RetrievalConfig):
+                self._retrieval_config = retrieval_config
+            elif isinstance(retrieval_config, dict):
+                self._retrieval_config = RetrievalConfig.from_dict(retrieval_config)
+        elif knowledge_config is not None or rag_config is not None:
+            # Legacy support: merge old configs into unified config
+            from ..rag.retrieval_config import create_retrieval_config
+            self._retrieval_config = create_retrieval_config(
+                knowledge_config=knowledge_config,
+                rag_config=rag_config,
+            )
+        
         # Check if knowledge parameter has any values
         if not knowledge:
             self.knowledge = None
             self._knowledge_sources = None
             self._knowledge_processed = True  # No knowledge to process
+            self._rag_instance = None
         else:
-            # Store knowledge sources for lazy processing
-            self._knowledge_sources = knowledge
-            self._knowledge_processed = False
-            self._knowledge_config = knowledge_config
-            self.knowledge = None  # Will be initialized on first use
-
-        # Fast Context configuration (lazy loaded)
-        self.fast_context_enabled = fast_context
-        self._fast_context_path = fast_context_path  # Store raw, resolve lazily
-        self.fast_context_model = fast_context_model
-        self.fast_context_max_turns = fast_context_max_turns
-        self.fast_context_parallelism = fast_context_parallelism
-        self.fast_context_timeout = fast_context_timeout
-        self._fast_context_instance = None  # Lazy loaded
+            # Check if knowledge is a Knowledge instance (shared knowledge)
+            if hasattr(knowledge, 'search') and hasattr(knowledge, 'add'):
+                # It's a Knowledge instance - use directly
+                self.knowledge = knowledge
+                self._knowledge_sources = None
+                self._knowledge_processed = True
+            else:
+                # It's a list of sources - store for lazy processing
+                self._knowledge_sources = knowledge
+                self._knowledge_processed = False
+                self.knowledge = None  # Will be initialized on first use
+            self._rag_instance = None  # Lazy loaded RAG instance
+            
+            # Create default retrieval config if knowledge provided but no config
+            if self._retrieval_config is None:
+                from ..rag.retrieval_config import RetrievalConfig
+                self._retrieval_config = RetrievalConfig()
 
         # Agent Skills configuration (lazy loaded for zero performance impact)
         self._skills = skills
@@ -687,6 +708,140 @@ Your Goal: {self.goal}
         self._db = db
         self._session_id = session_id
         self._db_initialized = False
+        
+        # Session store for JSON-based persistence (lazy - no imports until used)
+        # Used when session_id is provided but no DB adapter
+        self._session_store = None
+        self._session_store_initialized = False
+
+        # Agent-centric feature instances (lazy loaded for zero performance impact)
+        self._auto_memory = auto_memory
+        self._policy = policy
+        self._background = background
+        self._checkpoints = checkpoints
+        self._output_style = output_style
+        self._thinking_budget = thinking_budget
+        
+        # Context management (lazy loaded for zero overhead when disabled)
+        self._context_param = context  # Store raw param for lazy init
+        self._context_manager = None  # Lazy initialized on first use
+        self._context_manager_initialized = False
+
+    @property
+    def auto_memory(self):
+        """AutoMemory instance for automatic memory extraction."""
+        return self._auto_memory
+    
+    @auto_memory.setter
+    def auto_memory(self, value):
+        self._auto_memory = value
+
+    @property
+    def policy(self):
+        """PolicyEngine instance for execution control."""
+        return self._policy
+    
+    @policy.setter
+    def policy(self, value):
+        self._policy = value
+
+    @property
+    def background(self):
+        """BackgroundRunner instance for async task execution."""
+        return self._background
+    
+    @background.setter
+    def background(self, value):
+        self._background = value
+
+    @property
+    def checkpoints(self):
+        """CheckpointService instance for file-level undo/restore."""
+        return self._checkpoints
+    
+    @checkpoints.setter
+    def checkpoints(self, value):
+        self._checkpoints = value
+
+    @property
+    def output_style(self):
+        """OutputStyle instance for response formatting."""
+        return self._output_style
+    
+    @output_style.setter
+    def output_style(self, value):
+        self._output_style = value
+
+    @property
+    def thinking_budget(self):
+        """ThinkingBudget instance for extended thinking control."""
+        return self._thinking_budget
+    
+    @thinking_budget.setter
+    def thinking_budget(self, value):
+        self._thinking_budget = value
+
+    @property
+    def context_manager(self):
+        """
+        ContextManager instance for unified context management.
+        
+        Lazy initialized on first access when context=True or context=ManagerConfig.
+        Returns None when context=False (zero overhead).
+        
+        Example:
+            agent = Agent(instructions="...", context=True)
+            # Access manager for advanced operations
+            if agent.context_manager:
+                stats = agent.context_manager.get_stats()
+        """
+        if self._context_manager_initialized:
+            return self._context_manager
+        
+        # Initialize based on context param type
+        if self._context_param is False or self._context_param is None:
+            # Zero overhead - no context management
+            self._context_manager = None
+            self._context_manager_initialized = True
+            return None
+        
+        # Lazy import to avoid overhead when not used
+        try:
+            from ..context import ContextManager, ManagerConfig
+        except ImportError:
+            # Context module not available
+            self._context_manager = None
+            self._context_manager_initialized = True
+            return None
+        
+        if self._context_param is True:
+            # Enable with safe defaults
+            self._context_manager = ContextManager(
+                model=self.llm if isinstance(self.llm, str) else "gpt-4o-mini",
+                agent_name=self.name or "Agent",
+            )
+        elif isinstance(self._context_param, ManagerConfig):
+            # Use provided config
+            self._context_manager = ContextManager(
+                model=self.llm if isinstance(self.llm, str) else "gpt-4o-mini",
+                config=self._context_param,
+                agent_name=self.name or "Agent",
+            )
+        elif hasattr(self._context_param, 'process'):
+            # Already a ContextManager instance
+            self._context_manager = self._context_param
+        else:
+            # Unknown type, disable
+            self._context_manager = None
+        
+        self._context_manager_initialized = True
+        return self._context_manager
+    
+    @context_manager.setter
+    def context_manager(self, value):
+        """Set context manager directly."""
+        self._context_manager = value
+        self._context_manager_initialized = True
 
     @property
     def console(self):
@@ -696,17 +851,6 @@ Your Goal: {self.goal}
             self._console = Console()
         return self._console
     
-    @property
-    def fast_context_path(self):
-        """Lazily resolve fast_context_path - avoids os.getcwd() on every init."""
-        if self._fast_context_path is None:
-            self._fast_context_path = os.getcwd()
-        return self._fast_context_path
-    
-    @fast_context_path.setter
-    def fast_context_path(self, value):
-        self._fast_context_path = value
-    
     @property
     def skill_manager(self):
         """Lazily initialize SkillManager only when skills are accessed."""
@@ -893,57 +1037,6 @@ Your Goal: {self.goal}
         
         return supports_prompt_caching(model_name)
     
-    @property
-    def fast_context(self):
-        """Lazily initialize FastContext instance when needed.
-        
-        Returns:
-            FastContext instance or None if not enabled
-        """
-        if not self.fast_context_enabled:
-            return None
-        
-        if self._fast_context_instance is None:
-            try:
-                from ..context.fast import FastContext
-                self._fast_context_instance = FastContext(
-                    workspace_path=self.fast_context_path,
-                    model=self.fast_context_model,
-                    max_turns=self.fast_context_max_turns,
-                    max_parallel=self.fast_context_parallelism,
-                    timeout=self.fast_context_timeout,
-                    verbose=self.verbose
-                )
-            except ImportError:
-                logging.warning("FastContext not available")
-                return None
-        
-        return self._fast_context_instance
-    
-    def delegate_to_fast_context(self, query: str) -> Optional[str]:
-        """Delegate a code search query to FastContext subagent.
-        
-        This method uses the FastContext subagent to rapidly search
-        the codebase and return relevant context.
-        
-        Args:
-            query: Natural language search query
-            
-        Returns:
-            Formatted context string or None if FastContext not available
-        """
-        if not self.fast_context_enabled or self.fast_context is None:
-            return None
-        
-        try:
-            result = self.fast_context.search(query)
-            if result.total_files > 0:
-                return self.fast_context.get_context_for_agent(query)
-            return None
-        except Exception as e:
-            logging.warning(f"FastContext search failed: {e}")
-            return None
-    
     @property
     def rules_manager(self):
         """
@@ -1177,9 +1270,14 @@ Your Goal: {self.goal}
     def _ensure_knowledge_processed(self):
         """Ensure knowledge is initialized and processed when first accessed."""
         if not self._knowledge_processed and self._knowledge_sources:
-            # Initialize Knowledge with provided or default config
+            # Initialize Knowledge with config from retrieval_config
             from praisonaiagents.knowledge import Knowledge
-            self.knowledge = Knowledge(self._knowledge_config or None)
+            
+            knowledge_config = None
+            if self._retrieval_config is not None:
+                knowledge_config = self._retrieval_config.to_knowledge_config()
+            
+            self.knowledge = Knowledge(knowledge_config)
             
             # Process all knowledge sources
             for source in self._knowledge_sources:
@@ -1187,6 +1285,302 @@ Your Goal: {self.goal}
             
             self._knowledge_processed = True
     
+    @property
+    def retrieval_config(self):
+        """Get the unified retrieval configuration."""
+        return self._retrieval_config
+    
+    @property
+    def rag(self):
+        """
+        Lazy-loaded RAG instance for advanced retrieval with citations.
+        
+        Returns RAG instance configured with agent's knowledge and retrieval_config.
+        Returns None if no knowledge is configured.
+        
+        Usage:
+            agent = Agent(knowledge=["doc.pdf"], retrieval_config={"citations": True})
+            result = agent.rag.query("What is the main finding?")
+            print(result.answer)
+            for citation in result.citations:
+                print(f"[{citation.id}] {citation.source}")
+        """
+        # Check if we have knowledge (either sources or direct instance)
+        if not self._knowledge_sources and self.knowledge is None:
+            return None
+        
+        if self._rag_instance is None:
+            self._ensure_knowledge_processed()
+            if self.knowledge:
+                try:
+                    from praisonaiagents.rag import RAG, RAGConfig
+                    
+                    # Build RAGConfig from unified retrieval_config
+                    rag_config_obj = RAGConfig()
+                    if self._retrieval_config is not None:
+                        rag_dict = self._retrieval_config.to_rag_config()
+                        for key, value in rag_dict.items():
+                            if hasattr(rag_config_obj, key):
+                                setattr(rag_config_obj, key, value)
+                    
+                    # Get LLM instance for RAG
+                    llm = None
+                    if hasattr(self, 'llm_instance') and self.llm_instance:
+                        llm = self.llm_instance
+                    
+                    self._rag_instance = RAG(
+                        knowledge=self.knowledge,
+                        config=rag_config_obj,
+                        llm=llm,
+                    )
+                except ImportError:
+                    logging.warning("RAG module not available. Install with: pip install 'praisonaiagents[rag]'")
+                    return None
+        
+        return self._rag_instance
+    
+    def _get_knowledge_context(self, query: str, use_rag: bool = False) -> tuple:
+        """
+        Get knowledge context for a query using unified retrieval pipeline.
+        
+        Args:
+            query: The user's question/prompt
+            use_rag: If True, use RAG pipeline for token-aware context building
+            
+        Returns:
+            Tuple of (context_string, citations_list or None)
+        """
+        # Check if we have knowledge (sources or direct instance)
+        if not self._knowledge_sources and self.knowledge is None:
+            return "", None
+        
+        self._ensure_knowledge_processed()
+        
+        if not self.knowledge:
+            return "", None
+        
+        # Use RAG pipeline for token-aware context building (DRY - single path)
+        if use_rag and self.rag:
+            try:
+                context_pack = self.rag.retrieve(query, user_id=self.user_id, agent_id=self.agent_id)
+                return context_pack.context, context_pack.citations
+            except Exception as e:
+                logging.warning(f"RAG retrieve failed, falling back to basic retrieval: {e}")
+        
+        # Fallback: basic retrieval with token-aware formatting
+        try:
+            from praisonaiagents.rag.context import build_context
+            
+            search_results = self.knowledge.search(query, agent_id=self.agent_id)
+            if not search_results:
+                return "", None
+            
+            # Normalize results format (filter out None values, handle None metadata)
+            if isinstance(search_results, dict) and 'results' in search_results:
+                results = []
+                for r in search_results['results']:
+                    if r is None:
+                        continue
+                    text = r.get('memory', '') or ''
+                    metadata = r.get('metadata') or {}  # Handle None metadata
+                    if text:
+                        results.append({"text": text, "metadata": metadata})
+            elif isinstance(search_results, list):
+                results = [{"text": str(r), "metadata": {}} for r in search_results if r is not None and str(r)]
+            else:
+                results = [{"text": str(search_results), "metadata": {}}] if search_results else []
+            
+            # Use token-aware context building (same as RAG pipeline)
+            max_tokens = 4000
+            if self._retrieval_config:
+                max_tokens = self._retrieval_config.max_context_tokens
+            
+            context, _ = build_context(results, max_tokens=max_tokens)
+            return context, None
+            
+        except ImportError:
+            # Fallback to simple concatenation if RAG context module not available
+            search_results = self.knowledge.search(query, agent_id=self.agent_id)
+            if not search_results:
+                return "", None
+            
+            if isinstance(search_results, dict) and 'results' in search_results:
+                # CRITICAL: Handle None results and get 'memory' field safely
+                parts = []
+                for result in search_results['results']:
+                    if result is not None:
+                        memory = result.get('memory', '') or ''
+                        if memory:
+                            parts.append(memory)
+                knowledge_content = "\n".join(parts)
+            else:
+                knowledge_content = "\n".join(search_results) if isinstance(search_results, list) else str(search_results)
+            
+            return knowledge_content, None
+    
+    def retrieve(self, query: str, **kwargs) -> "ContextPack":
+        """
+        Retrieve context from knowledge without LLM generation.
+        
+        Returns a ContextPack that can be passed to chat_with_context().
+        This enables conditional retrieval - only retrieve when needed.
+        
+        Args:
+            query: Search query
+            **kwargs: Additional arguments (top_k, rerank, etc.)
+            
+        Returns:
+            ContextPack with context string and citations (no LLM call)
+            
+        Raises:
+            ValueError: If no knowledge is configured
+            ImportError: If RAG module is not available
+            
+        Usage:
+            agent = Agent(knowledge=["docs/"], retrieval_config={"citations": True})
+            context = agent.retrieve("What are the key findings?")
+            print(f"Found {len(context.citations)} sources")
+            response = agent.chat_with_context("Summarize", context)
+        """
+        if not self._knowledge_sources and self.knowledge is None:
+            raise ValueError("No knowledge configured. Add knowledge=[] to Agent init.")
+        
+        if not self.rag:
+            raise ImportError("RAG module not available. Install with: pip install 'praisonaiagents[rag]'")
+        
+        kwargs.setdefault('user_id', self.user_id)
+        kwargs.setdefault('agent_id', self.agent_id)
+        
+        return self.rag.retrieve(query, **kwargs)
+    
+    def query(self, question: str, **kwargs) -> "RAGResult":
+        """
+        Query knowledge and get a structured answer with citations.
+        
+        This is the recommended method for getting answers with source citations.
+        Returns a structured result with answer, citations, context used, and metadata.
+        
+        Args:
+            question: The question to answer
+            **kwargs: Additional arguments (top_k, rerank, etc.)
+            
+        Returns:
+            RAGResult with answer, citations, context_used, and metadata
+            
+        Raises:
+            ValueError: If no knowledge is configured
+            ImportError: If RAG module is not available
+            
+        Usage:
+            agent = Agent(knowledge=["doc.pdf"], retrieval_config={"citations": True})
+            result = agent.query("What is the main finding?")
+            print(result.answer)
+            for citation in result.citations:
+                print(f"  [{citation.id}] {citation.source}")
+        """
+        if not self._knowledge_sources and self.knowledge is None:
+            raise ValueError("No knowledge configured. Add knowledge=[] to Agent init.")
+        
+        if not self.rag:
+            raise ImportError("RAG module not available. Install with: pip install 'praisonaiagents[rag]'")
+        
+        kwargs.setdefault('user_id', self.user_id)
+        kwargs.setdefault('agent_id', self.agent_id)
+        
+        return self.rag.query(question, **kwargs)
+    
+    def rag_query(self, question: str, **kwargs) -> "RAGResult":
+        """
+        Query knowledge using RAG pipeline with citations.
+        
+        This is the recommended way to get answers with citations from an agent's knowledge.
+        
+        Args:
+            question: The question to answer
+            **kwargs: Additional arguments passed to RAG.query()
+            
+        Returns:
+            RAGResult with answer, citations, context_used, and metadata
+            
+        Raises:
+            ValueError: If no knowledge sources are configured
+            ImportError: If RAG module is not available
+            
+        Usage:
+            agent = Agent(knowledge=["doc.pdf"], rag_config={"include_citations": True})
+            result = agent.rag_query("What is the main finding?")
+            print(result.answer)
+            for citation in result.citations:
+                print(f"[{citation.id}] {citation.source}: {citation.text[:100]}")
+        """
+        if not self._knowledge_sources:
+            raise ValueError("No knowledge sources configured. Add knowledge=[] to Agent init.")
+        
+        if not self.rag:
+            raise ImportError("RAG module not available. Install with: pip install 'praisonaiagents[rag]'")
+        
+        # Pass agent context
+        kwargs.setdefault('user_id', self.user_id)
+        kwargs.setdefault('agent_id', self.agent_id)
+        
+        return self.rag.query(question, **kwargs)
+    
+    def chat_with_context(
+        self,
+        message: str,
+        context: "ContextPack",
+        *,
+        citations_mode: str = "append",
+        **kwargs,
+    ) -> str:
+        """
+        Chat with pre-retrieved context.
+        
+        This method allows AutoRagAgent or manual workflows to inject 
+        pre-retrieved context into the agent's chat, enabling conditional 
+        retrieval without duplicating RAG logic.
+        
+        Args:
+            message: User message/question
+            context: ContextPack from RAG.retrieve()
+            citations_mode: How to include citations (append/hidden/none)
+            **kwargs: Additional arguments passed to chat()
+            
+        Returns:
+            Agent response with optional citations
+            
+        Usage:
+            from praisonaiagents import AutoRagAgent
+            
+            auto_rag = AutoRagAgent(agent=my_agent)
+            result = auto_rag.chat("What are the key findings?")
+            
+            # Or manually:
+            context_pack = rag.retrieve("What are the key findings?")
+            response = agent.chat_with_context("What are the key findings?", context_pack)
+        """
+        # Build augmented prompt with context
+        augmented_prompt = f"""Based on the following context, answer the question.
+
+Context:
+{context.context}
+
+Question: {message}
+
+Answer:"""
+        
+        # Call chat with augmented prompt
+        response = self.chat(augmented_prompt, **kwargs)
+        
+        # Add citations if configured
+        if citations_mode == "append" and context.has_citations:
+            sources = "\n\nSources:\n"
+            for citation in context.citations:
+                sources += f"  [{citation.id}] {citation.source}\n"
+            response = response + sources
+        
+        return response
+    
     def _process_knowledge(self, knowledge_item):
         """Process and store knowledge from a file path, URL, or string."""
         try:
@@ -2094,6 +2488,49 @@ Your Goal: {self.goal}"""
         
         self._db_initialized = True
         self._current_run_id = None  # Track current run
+    
+    def _init_session_store(self):
+        """
+        Initialize session store for JSON-based persistence (lazy, first chat only).
+        
+        This is used when session_id is provided but no DB adapter.
+        Enables automatic session persistence with zero configuration.
+        """
+        if self._session_store_initialized:
+            return
+        
+        # Only initialize if session_id is provided and no DB adapter
+        if self._session_id is None or self._db is not None:
+            self._session_store_initialized = True
+            return
+        
+        try:
+            from ..session import get_default_session_store
+            self._session_store = get_default_session_store()
+            
+            # Restore chat history from previous session
+            history = self._session_store.get_chat_history(self._session_id)
+            if history:
+                # Only restore if chat_history is empty (avoid duplicates)
+                if not self.chat_history:
+                    for msg in history:
+                        self.chat_history.append({
+                            "role": msg["role"],
+                            "content": msg["content"]
+                        })
+                    logging.info(f"Restored session {self._session_id} with {len(history)} messages from JSON store")
+            
+            # Set agent info
+            self._session_store.set_agent_info(
+                self._session_id,
+                agent_name=self.name,
+                user_id=self.user_id,
+            )
+        except Exception as e:
+            logging.warning(f"Failed to initialize session store: {e}")
+            self._session_store = None
+        
+        self._session_store_initialized = True
 
     def _start_run(self, input_content: str):
         """Start a new run (turn) for persistence tracking."""
@@ -2135,24 +2572,34 @@ Your Goal: {self.goal}"""
         self._current_run_id = None
 
     def _persist_message(self, role: str, content: str):
-        """Persist a message to the DB if adapter is provided."""
-        if self._db is None:
+        """Persist a message to the DB or session store."""
+        # Try DB adapter first
+        if self._db is not None:
+            try:
+                if role == "user":
+                    self._db.on_user_message(self._session_id, content)
+                elif role == "assistant":
+                    self._db.on_agent_message(self._session_id, content)
+            except Exception as e:
+                logging.warning(f"Failed to persist message to DB: {e}")
             return
         
-        try:
-            if role == "user":
-                self._db.on_user_message(self._session_id, content)
-            elif role == "assistant":
-                self._db.on_agent_message(self._session_id, content)
-        except Exception as e:
-            logging.warning(f"Failed to persist message: {e}")
+        # Fall back to session store (JSON-based)
+        if self._session_store is not None and self._session_id is not None:
+            try:
+                if role == "user":
+                    self._session_store.add_user_message(self._session_id, content)
+                elif role == "assistant":
+                    self._session_store.add_assistant_message(self._session_id, content)
+            except Exception as e:
+                logging.warning(f"Failed to persist message to session store: {e}")
 
     @property
     def session_id(self) -> Optional[str]:
         """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, config=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, force_retrieval=False, skip_retrieval=False):
         # Apply rate limiter if configured (before any LLM call)
         if self._rate_limiter is not None:
             self._rate_limiter.acquire()
@@ -2160,6 +2607,10 @@ Your Goal: {self.goal}"""
         # Initialize DB session on first chat (lazy)
         self._init_db_session()
         
+        # Initialize session store for JSON-based persistence (lazy)
+        # This enables automatic session persistence when session_id is provided
+        self._init_session_store()
+        
         # Start a new run for this chat turn
         prompt_str = prompt if isinstance(prompt, str) else str(prompt)
         self._start_run(prompt_str)
@@ -2187,23 +2638,42 @@ Your Goal: {self.goal}"""
         # Use agent's stream setting if not explicitly provided
         if stream is None:
             stream = self.stream
-        # Search for existing knowledge if any knowledge is provided
-        if self._knowledge_sources and not self._knowledge_processed:
-            self._ensure_knowledge_processed()
         
-        if self.knowledge:
-            search_results = self.knowledge.search(prompt, agent_id=self.agent_id)
-            if search_results:
-                # Check if search_results is a list of dictionaries or strings
-                if isinstance(search_results, dict) and 'results' in search_results:
-                    # Extract memory content from the results
-                    knowledge_content = "\n".join([result['memory'] for result in search_results['results']])
-                else:
-                    # If search_results is a list of strings, join them directly
-                    knowledge_content = "\n".join(search_results)
-                
-                # Append found knowledge to the prompt
-                prompt = f"{prompt}\n\nKnowledge: {knowledge_content}"
+        # Unified retrieval handling with policy-based decision
+        # Uses token-aware context building (DRY - same path as RAG pipeline)
+        if self._knowledge_sources or self.knowledge is not None:
+            if not self._knowledge_processed:
+                self._ensure_knowledge_processed()
+            
+            # Determine if we should retrieve based on policy
+            should_retrieve = False
+            if self._retrieval_config is not None:
+                should_retrieve = self._retrieval_config.should_retrieve(
+                    prompt if isinstance(prompt, str) else str(prompt),
+                    force=force_retrieval,
+                    skip=skip_retrieval
+                )
+            elif not skip_retrieval:
+                # No config but knowledge exists - retrieve by default unless skipped
+                should_retrieve = True if force_retrieval else (self.knowledge is not None)
+            
+            if should_retrieve and self.knowledge:
+                # Use unified retrieval path with token-aware context building
+                knowledge_context, _ = self._get_knowledge_context(
+                    prompt if isinstance(prompt, str) else str(prompt),
+                    use_rag=True  # Use RAG pipeline for token-aware context
+                )
+                if knowledge_context:
+                    # Format with safety boundaries
+                    if self._retrieval_config and self._retrieval_config.context_template:
+                        formatted_context = self._retrieval_config.context_template.format(
+                            context=knowledge_context
+                        )
+                    else:
+                        formatted_context = f"<retrieved_context>\n{knowledge_context}\n</retrieved_context>"
+                    
+                    # Append formatted knowledge to the prompt
+                    prompt = f"{prompt}\n\n{formatted_context}"
 
         if self._using_custom_llm:
             try:
@@ -3061,9 +3531,34 @@ Write the complete compiled report:"""
         # Return the single result if only one step
         return results[0]["result"] if results else None
 
+    def switch_model(self, new_model: str) -> None:
+        """
+        Switch the agent's LLM model while preserving conversation history.
+        
+        Args:
+            new_model: The new model name to switch to (e.g., "gpt-4o", "claude-3-sonnet")
+        """
+        # Store the new model name
+        self.llm = new_model
+        
+        # Recreate the LLM instance with the new model
+        try:
+            from ..llm.llm import LLM
+            self._llm_instance = LLM(
+                model=new_model,
+                base_url=self._openai_base_url,
+                api_key=self._openai_api_key,
+            )
+            self._using_custom_llm = True
+        except ImportError:
+            # If LLM class not available, just update the model string
+            pass
+        
+        # Chat history is preserved in self.chat_history (no action needed)
+
     def start(self, prompt: str, **kwargs):
         """Start the agent with a prompt. This is a convenience method that wraps chat()."""
-        # Load history from past sessions if history_in_context is set
+        # Load history from past sessions (now handled via context= param)
         self._load_history_context()
         
         # Check if planning mode is enabled
@@ -3083,37 +3578,13 @@ Write the complete compiled report:"""
         return result
     
     def _load_history_context(self):
-        """Load history from past sessions into context if history_in_context is set."""
-        if not self.history_in_context or not self._memory_instance:
-            return
+        """Load history from past sessions into context.
         
-        try:
-            sessions = self._memory_instance.list_sessions()
-            if not sessions:
-                return
-            
-            # Get the last N sessions
-            sessions_to_load = sessions[:self.history_in_context]
-            
-            for session_info in reversed(sessions_to_load):
-                try:
-                    session_data = self._memory_instance.resume_session(session_info["name"])
-                    history = session_data.get("conversation_history", [])
-                    
-                    # Add history to chat_history with a marker
-                    for msg in history:
-                        if msg not in self.chat_history:
-                            # Mark as from history to avoid duplication
-                            msg_copy = msg.copy()
-                            msg_copy["_from_history"] = True
-                            self.chat_history.append(msg_copy)
-                except Exception:
-                    continue
-                    
-            if sessions_to_load:
-                logging.debug(f"Loaded history from {len(sessions_to_load)} past session(s)")
-        except Exception as e:
-            logging.debug(f"Error loading history context: {e}")
+        Note: This functionality is now handled via context= param with ManagerConfig.
+        This method is kept for backward compatibility but is a no-op.
+        Use context=ManagerConfig(history_sessions=N) to load past sessions.
+        """
+        pass
     
     def _auto_save_session(self):
         """Auto-save session if auto_save is enabled."""

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

@@ -0,0 +1,202 @@
+"""
+Message Queue for PraisonAI Agents.
+
+Provides queuing for agent prompts when agent is busy.
+Thread-safe implementation for concurrent access.
+"""
+
+import threading
+import heapq
+import time
+import logging
+from typing import Optional, Any, List, Tuple
+from dataclasses import dataclass, field
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class MessagePriority(Enum):
+    """Message priority levels."""
+    LOW = 1
+    NORMAL = 5
+    HIGH = 10
+    URGENT = 20
+
+
+@dataclass(order=True)
+class QueuedMessage:
+    """A message in the queue with priority and timestamp."""
+    priority: int
+    timestamp: float = field(compare=False)
+    content: Any = field(compare=False)
+    metadata: dict = field(default_factory=dict, compare=False)
+    
+    def __post_init__(self):
+        # Negate priority for max-heap behavior (higher priority = lower number in heap)
+        self.priority = -self.priority
+
+
+class AgentMessageQueue:
+    """
+    Thread-safe message queue for agent prompts.
+    
+    Supports priority-based ordering and FIFO within same priority.
+    
+    Usage:
+        queue = AgentMessageQueue()
+        queue.enqueue("Hello", priority=5)
+        queue.enqueue("Urgent!", priority=10)
+        
+        msg = queue.dequeue()  # Returns "Urgent!" first
+    """
+    
+    def __init__(self, max_size: int = 100):
+        """
+        Initialize message queue.
+        
+        Args:
+            max_size: Maximum number of messages in queue (0 = unlimited)
+        """
+        self._queue: List[QueuedMessage] = []
+        self._lock = threading.RLock()
+        self._not_empty = threading.Condition(self._lock)
+        self._max_size = max_size
+        self._message_count = 0
+        
+    def enqueue(
+        self,
+        content: Any,
+        priority: int = MessagePriority.NORMAL.value,
+        metadata: Optional[dict] = None
+    ) -> bool:
+        """
+        Add a message to the queue.
+        
+        Args:
+            content: Message content
+            priority: Message priority (higher = more urgent)
+            metadata: Optional metadata dict
+            
+        Returns:
+            True if message was added, False if queue is full
+        """
+        with self._lock:
+            if self._max_size > 0 and len(self._queue) >= self._max_size:
+                logger.warning(f"Message queue full (max_size={self._max_size})")
+                return False
+                
+            message = QueuedMessage(
+                priority=priority,
+                timestamp=time.time(),
+                content=content,
+                metadata=metadata or {}
+            )
+            
+            heapq.heappush(self._queue, message)
+            self._message_count += 1
+            self._not_empty.notify()
+            
+            logger.debug(f"Message enqueued (priority={priority}, queue_size={len(self._queue)})")
+            return True
+    
+    def dequeue(self, timeout: Optional[float] = None) -> Optional[Any]:
+        """
+        Remove and return the highest priority message.
+        
+        Args:
+            timeout: Maximum time to wait for a message (None = don't wait)
+            
+        Returns:
+            Message content or None if queue is empty
+        """
+        with self._not_empty:
+            if not self._queue:
+                if timeout is not None:
+                    self._not_empty.wait(timeout)
+                    
+            if not self._queue:
+                return None
+                
+            message = heapq.heappop(self._queue)
+            logger.debug(f"Message dequeued (queue_size={len(self._queue)})")
+            return message.content
+    
+    def peek(self) -> Optional[Any]:
+        """Return the highest priority message without removing it."""
+        with self._lock:
+            if not self._queue:
+                return None
+            return self._queue[0].content
+    
+    def is_empty(self) -> bool:
+        """Check if queue is empty."""
+        with self._lock:
+            return len(self._queue) == 0
+    
+    def size(self) -> int:
+        """Get current queue size."""
+        with self._lock:
+            return len(self._queue)
+    
+    def clear(self) -> int:
+        """Clear all messages from queue. Returns number of cleared messages."""
+        with self._lock:
+            count = len(self._queue)
+            self._queue.clear()
+            return count
+    
+    def get_all(self) -> List[Any]:
+        """Get all messages in priority order without removing them."""
+        with self._lock:
+            # Sort by priority (remember priority is negated)
+            sorted_queue = sorted(self._queue)
+            return [msg.content for msg in sorted_queue]
+    
+    @property
+    def total_messages_processed(self) -> int:
+        """Total number of messages ever enqueued."""
+        return self._message_count
+
+
+class AsyncAgentMessageQueue:
+    """
+    Async-compatible message queue for agent prompts.
+    
+    Wraps AgentMessageQueue with async interface.
+    """
+    
+    def __init__(self, max_size: int = 100):
+        self._sync_queue = AgentMessageQueue(max_size=max_size)
+        
+    async def enqueue(
+        self,
+        content: Any,
+        priority: int = MessagePriority.NORMAL.value,
+        metadata: Optional[dict] = None
+    ) -> bool:
+        """Async enqueue."""
+        return self._sync_queue.enqueue(content, priority, metadata)
+    
+    async def dequeue(self, timeout: Optional[float] = None) -> Optional[Any]:
+        """Async dequeue."""
+        import asyncio
+        
+        if timeout is None:
+            return self._sync_queue.dequeue(timeout=0)
+            
+        # Poll with async sleep for timeout
+        start = time.time()
+        while time.time() - start < timeout:
+            result = self._sync_queue.dequeue(timeout=0)
+            if result is not None:
+                return result
+            await asyncio.sleep(0.01)
+            
+        return None
+    
+    def is_empty(self) -> bool:
+        return self._sync_queue.is_empty()
+    
+    def size(self) -> int:
+        return self._sync_queue.size()

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

@@ -0,0 +1,226 @@
+"""
+Automatic Conversation Summarization for PraisonAI Agents.
+
+Provides automatic summarization when context window fills up.
+Reuses existing telemetry/token_collector for token tracking.
+"""
+
+import logging
+from typing import Optional, List, Dict, Any, Callable
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SummarizationConfig:
+    """Configuration for auto-summarization."""
+    enabled: bool = False
+    threshold: float = 0.8  # 80% of context window
+    context_window: int = 128000  # Default for GPT-4
+    summary_model: Optional[str] = None  # Use smaller model for summaries
+    preserve_system: bool = True  # Keep system message
+    preserve_recent: int = 2  # Keep last N message pairs
+
+
+class SummarizationManager:
+    """
+    Manages automatic conversation summarization.
+    
+    Tracks token usage and triggers summarization when threshold is reached.
+    Thread-safe for multi-agent use.
+    """
+    
+    # Context window sizes for common models
+    MODEL_CONTEXT_WINDOWS = {
+        "gpt-4o": 128000,
+        "gpt-4o-mini": 128000,
+        "gpt-4-turbo": 128000,
+        "gpt-4": 8192,
+        "gpt-3.5-turbo": 16385,
+        "claude-3-opus": 200000,
+        "claude-3-sonnet": 200000,
+        "claude-3-haiku": 200000,
+        "claude-3-5-sonnet": 200000,
+        "gemini-pro": 32000,
+        "gemini-1.5-pro": 1000000,
+        "gemini-1.5-flash": 1000000,
+    }
+    
+    def __init__(
+        self,
+        context_window: int = 128000,
+        threshold: float = 0.8,
+        summary_model: Optional[str] = None,
+        preserve_system: bool = True,
+        preserve_recent: int = 2,
+    ):
+        """
+        Initialize summarization manager.
+        
+        Args:
+            context_window: Maximum context window size in tokens
+            threshold: Percentage of context window to trigger summarization (0.0-1.0)
+            summary_model: Model to use for generating summaries (None = use same model)
+            preserve_system: Whether to preserve system message after summarization
+            preserve_recent: Number of recent message pairs to preserve
+        """
+        if not 0.0 < threshold <= 1.0:
+            raise ValueError("threshold must be between 0.0 and 1.0")
+            
+        self.context_window = context_window
+        self.threshold = threshold
+        self.summary_model = summary_model
+        self.preserve_system = preserve_system
+        self.preserve_recent = preserve_recent
+        self.current_tokens = 0
+        self._summarization_count = 0
+        
+    @classmethod
+    def for_model(cls, model: str, threshold: float = 0.8, **kwargs) -> "SummarizationManager":
+        """Create a SummarizationManager configured for a specific model."""
+        # Normalize model name
+        model_lower = model.lower()
+        
+        # Find matching context window
+        context_window = 128000  # Default
+        for model_key, window in cls.MODEL_CONTEXT_WINDOWS.items():
+            if model_key in model_lower:
+                context_window = window
+                break
+                
+        return cls(context_window=context_window, threshold=threshold, **kwargs)
+    
+    def add_tokens(self, tokens: int) -> None:
+        """Add tokens to the current count."""
+        self.current_tokens += tokens
+        
+    def set_tokens(self, tokens: int) -> None:
+        """Set the current token count."""
+        self.current_tokens = tokens
+        
+    def reset_tokens(self) -> None:
+        """Reset token count after summarization."""
+        self.current_tokens = 0
+        
+    def should_summarize(self) -> bool:
+        """Check if summarization should be triggered."""
+        threshold_tokens = int(self.context_window * self.threshold)
+        return self.current_tokens >= threshold_tokens
+    
+    def get_usage_percentage(self) -> float:
+        """Get current context window usage as percentage."""
+        return self.current_tokens / self.context_window
+    
+    def generate_summary_prompt(self, messages: List[Dict[str, str]]) -> str:
+        """Generate prompt for summarizing conversation."""
+        conversation = "\n".join([
+            f"{msg['role'].upper()}: {msg['content']}"
+            for msg in messages
+            if msg['role'] != 'system'
+        ])
+        
+        return f"""Summarize the following conversation concisely, preserving:
+1. Key decisions and conclusions
+2. Important context and facts
+3. Any pending tasks or questions
+4. Technical details that may be needed later
+
+Keep the summary under 500 words.
+
+CONVERSATION:
+{conversation}
+
+SUMMARY:"""
+
+    def prepare_summarized_history(
+        self,
+        messages: List[Dict[str, str]],
+        summary: str
+    ) -> List[Dict[str, str]]:
+        """
+        Prepare new message history after summarization.
+        
+        Args:
+            messages: Original message history
+            summary: Generated summary
+            
+        Returns:
+            New message history with summary replacing old messages
+        """
+        new_history = []
+        
+        # Preserve system message if configured
+        if self.preserve_system and messages and messages[0].get('role') == 'system':
+            new_history.append(messages[0])
+            
+        # Add summary as assistant message
+        new_history.append({
+            "role": "assistant",
+            "content": f"[Previous conversation summary]\n{summary}"
+        })
+        
+        # Preserve recent messages
+        if self.preserve_recent > 0:
+            # Get last N pairs (user + assistant)
+            recent_count = self.preserve_recent * 2
+            recent_messages = [
+                m for m in messages[-recent_count:]
+                if m.get('role') != 'system'
+            ]
+            new_history.extend(recent_messages)
+            
+        self._summarization_count += 1
+        logger.info(f"Conversation summarized (count: {self._summarization_count})")
+        
+        return new_history
+    
+    @property
+    def summarization_count(self) -> int:
+        """Number of times summarization has been performed."""
+        return self._summarization_count
+
+
+async def summarize_conversation(
+    messages: List[Dict[str, str]],
+    llm_call: Callable,
+    manager: SummarizationManager,
+) -> List[Dict[str, str]]:
+    """
+    Summarize conversation using LLM.
+    
+    Args:
+        messages: Current message history
+        llm_call: Async function to call LLM
+        manager: SummarizationManager instance
+        
+    Returns:
+        New message history with summary
+    """
+    prompt = manager.generate_summary_prompt(messages)
+    
+    # Call LLM to generate summary
+    summary = await llm_call(prompt)
+    
+    # Prepare new history
+    new_history = manager.prepare_summarized_history(messages, summary)
+    
+    # Reset token count (will be recalculated on next message)
+    manager.reset_tokens()
+    
+    return new_history
+
+
+def summarize_conversation_sync(
+    messages: List[Dict[str, str]],
+    llm_call: Callable,
+    manager: SummarizationManager,
+) -> List[Dict[str, str]]:
+    """
+    Synchronous version of summarize_conversation.
+    """
+    prompt = manager.generate_summary_prompt(messages)
+    summary = llm_call(prompt)
+    new_history = manager.prepare_summarized_history(messages, summary)
+    manager.reset_tokens()
+    return new_history

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

@@ -1,5 +1,6 @@
 """Agents module for managing multiple AI agents"""
 from .agents import PraisonAIAgents
 from .autoagents import AutoAgents
+from .auto_rag_agent import AutoRagAgent, AutoRagConfig, RetrievalPolicy
 
-__all__ = ['PraisonAIAgents', 'AutoAgents'] 
+__all__ = ['PraisonAIAgents', 'AutoAgents', 'AutoRagAgent', 'AutoRagConfig', 'RetrievalPolicy'] 

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

@@ -127,7 +127,7 @@ def process_task_context(context_item, verbose=0, user_id=None):
         return str(context_item)  # Fallback for unknown types
 
 class PraisonAIAgents:
-    def __init__(self, agents, tasks=None, verbose=0, completion_checker=None, max_retries=5, process="sequential", manager_llm=None, memory=False, memory_config=None, embedder=None, user_id=None, max_iter=10, stream=True, name: Optional[str] = None, planning: bool = False, planning_llm: Optional[str] = None, auto_approve_plan: bool = False, planning_tools: Optional[List] = None, planning_reasoning: bool = False, on_task_start: Optional[Callable] = None, on_task_complete: Optional[Callable] = None, variables: Optional[Dict[str, Any]] = None):
+    def __init__(self, agents, tasks=None, verbose=0, completion_checker=None, max_retries=5, process="sequential", manager_llm=None, memory=False, memory_config=None, embedder=None, user_id=None, max_iter=10, stream=True, name: Optional[str] = None, planning: bool = False, planning_llm: Optional[str] = None, auto_approve_plan: bool = False, planning_tools: Optional[List] = None, planning_reasoning: bool = False, on_task_start: Optional[Callable] = None, on_task_complete: Optional[Callable] = None, variables: Optional[Dict[str, Any]] = None, context: Optional[Any] = False):
         # Add check at the start if memory is requested
         if memory:
             try:
@@ -218,6 +218,11 @@ class PraisonAIAgents:
         
         self._state = {}  # Add state storage at PraisonAIAgents level
         
+        # Context management (single param for all context features)
+        self._context_param = context  # Store raw param for lazy init
+        self._context_manager = None  # Lazy initialized on first use
+        self._context_manager_initialized = False
+        
         # Initialize planning mode
         self.planning = planning
         self.planning_llm = planning_llm or "gpt-4o-mini"
@@ -296,6 +301,51 @@ class PraisonAIAgents:
             cleaned = cleaned[:-3].strip()
         return cleaned
 
+    @property
+    def context_manager(self):
+        """
+        ContextManager instance for unified context management across all agents.
+        
+        Lazy initialized on first access when context=True or context=ManagerConfig.
+        Returns None when context=False (zero overhead).
+        
+        For multi-agent scenarios, uses MultiAgentContextManager for per-agent isolation.
+        """
+        if self._context_manager_initialized:
+            return self._context_manager
+        
+        # Initialize based on context param type
+        if self._context_param is False or self._context_param is None:
+            # Zero overhead - no context management
+            self._context_manager = None
+            self._context_manager_initialized = True
+            return None
+        
+        # Lazy import to avoid overhead when not used
+        try:
+            from ..context import MultiAgentContextManager, ManagerConfig
+        except ImportError:
+            # Context module not available
+            self._context_manager = None
+            self._context_manager_initialized = True
+            return None
+        
+        if self._context_param is True:
+            # Enable with safe defaults for multi-agent
+            self._context_manager = MultiAgentContextManager()
+        elif isinstance(self._context_param, ManagerConfig):
+            # Use provided config for all agents
+            self._context_manager = MultiAgentContextManager(config=self._context_param)
+        elif hasattr(self._context_param, 'get_agent_manager'):
+            # Already a MultiAgentContextManager instance
+            self._context_manager = self._context_param
+        else:
+            # Unknown type, disable
+            self._context_manager = None
+        
+        self._context_manager_initialized = True
+        return self._context_manager
+
     def default_completion_checker(self, task, agent_output):
         if task.output_json and task.result and task.result.json_dict:
             return True

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

@@ -0,0 +1,415 @@
+"""
+AutoRagAgent - Agent with automatic RAG retrieval decision.
+
+This module provides an agent wrapper that automatically decides when to
+retrieve context from knowledge bases vs direct chat.
+
+Usage:
+    from praisonaiagents import Agent, AutoRagAgent
+    
+    agent = Agent(
+        name="Research Assistant",
+        knowledge=["docs/manual.pdf"],
+    )
+    
+    auto_rag = AutoRagAgent(agent=agent)
+    result = auto_rag.chat("What are the key findings?")  # Auto retrieves
+    result = auto_rag.chat("Hello!")  # Skips retrieval
+"""
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Set, Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from praisonaiagents.agent import Agent
+    from praisonaiagents.rag import RAG, ContextPack
+
+logger = logging.getLogger(__name__)
+
+
+class RetrievalPolicy(Enum):
+    """Policy for when to perform RAG retrieval."""
+    AUTO = "auto"      # Decide based on query heuristics
+    ALWAYS = "always"  # Always retrieve
+    NEVER = "never"    # Never retrieve (direct chat only)
+
+
+@dataclass
+class AutoRagConfig:
+    """Configuration for AutoRagAgent."""
+    
+    retrieval_policy: RetrievalPolicy = RetrievalPolicy.AUTO
+    
+    top_k: int = 5
+    hybrid: bool = False
+    rerank: bool = False
+    
+    include_citations: bool = True
+    citations_mode: str = "append"  # append, hidden, none
+    
+    max_context_tokens: int = 4000
+    
+    auto_keywords: Set[str] = field(default_factory=lambda: {
+        "what", "how", "why", "when", "where", "who", "which",
+        "explain", "describe", "summarize", "find", "search",
+        "tell me", "show me", "according to", "based on",
+        "cite", "source", "reference", "document", "paper",
+    })
+    
+    auto_min_length: int = 10
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "retrieval_policy": self.retrieval_policy.value,
+            "top_k": self.top_k,
+            "hybrid": self.hybrid,
+            "rerank": self.rerank,
+            "include_citations": self.include_citations,
+            "citations_mode": self.citations_mode,
+            "max_context_tokens": self.max_context_tokens,
+            "auto_keywords": list(self.auto_keywords),
+            "auto_min_length": self.auto_min_length,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AutoRagConfig":
+        """Create from dictionary."""
+        policy = data.get("retrieval_policy", "auto")
+        if isinstance(policy, str):
+            policy = RetrievalPolicy(policy)
+        
+        keywords = data.get("auto_keywords", None)
+        if keywords is not None and isinstance(keywords, list):
+            keywords = set(keywords)
+        
+        kwargs = {
+            "retrieval_policy": policy,
+            "top_k": data.get("top_k", 5),
+            "hybrid": data.get("hybrid", False),
+            "rerank": data.get("rerank", False),
+            "include_citations": data.get("include_citations", True),
+            "max_context_tokens": data.get("max_context_tokens", 4000),
+            "auto_min_length": data.get("auto_min_length", 10),
+            "citations_mode": data.get("citations_mode", "append"),
+        }
+        if keywords:
+            kwargs["auto_keywords"] = keywords
+        
+        return cls(**kwargs)
+
+
+class AutoRagAgent:
+    """
+    Agent wrapper with automatic RAG retrieval decision.
+    
+    Decides when to perform retrieval based on policy and heuristics,
+    then composes RAG context with Agent chat.
+    
+    This follows the same pattern as AutoAgents but for RAG:
+    - AutoAgents: auto-generates agent configs from instructions
+    - AutoRagAgent: auto-decides when to retrieve context
+    
+    Usage:
+        from praisonaiagents import Agent, AutoRagAgent
+        
+        agent = Agent(
+            name="Research Assistant",
+            knowledge=["docs/manual.pdf"],
+        )
+        
+        auto_rag = AutoRagAgent(agent=agent)
+        
+        # Auto mode - decides based on query
+        result = auto_rag.chat("What are the key findings?")
+        
+        # Force retrieval
+        result = auto_rag.chat("Hello", force_retrieval=True)
+        
+        # Skip retrieval
+        result = auto_rag.chat("What is 2+2?", skip_retrieval=True)
+    """
+    
+    def __init__(
+        self,
+        agent: "Agent",
+        rag: Optional["RAG"] = None,
+        config: Optional[AutoRagConfig] = None,
+        *,
+        retrieval_policy: Optional[str] = None,
+        top_k: Optional[int] = None,
+        hybrid: Optional[bool] = None,
+        rerank: Optional[bool] = None,
+        citations: bool = True,
+    ):
+        """
+        Initialize AutoRagAgent.
+        
+        Args:
+            agent: Agent instance (must have knowledge configured for RAG)
+            rag: Optional RAG instance (uses agent.rag if not provided)
+            config: AutoRagConfig instance
+            retrieval_policy: Shorthand for config.retrieval_policy (auto/always/never)
+            top_k: Shorthand for config.top_k
+            hybrid: Shorthand for config.hybrid
+            rerank: Shorthand for config.rerank
+            citations: Shorthand for config.include_citations
+        """
+        self.agent = agent
+        self._rag = rag
+        
+        # Build config from kwargs or use provided
+        if config is not None:
+            self.config = config
+        else:
+            config_kwargs = {}
+            if retrieval_policy is not None:
+                config_kwargs["retrieval_policy"] = RetrievalPolicy(retrieval_policy)
+            if top_k is not None:
+                config_kwargs["top_k"] = top_k
+            if hybrid is not None:
+                config_kwargs["hybrid"] = hybrid
+            if rerank is not None:
+                config_kwargs["rerank"] = rerank
+            config_kwargs["include_citations"] = citations
+            self.config = AutoRagConfig(**config_kwargs)
+        
+        # Lazy RAG initialization flag
+        self._rag_initialized = False
+    
+    @property
+    def rag(self) -> Optional["RAG"]:
+        """Lazy load RAG from agent if not provided."""
+        if self._rag is not None:
+            return self._rag
+        
+        if not self._rag_initialized:
+            # Try to get RAG from agent
+            if hasattr(self.agent, 'rag') and self.agent.rag is not None:
+                self._rag = self.agent.rag
+            self._rag_initialized = True
+        
+        return self._rag
+    
+    @property
+    def name(self) -> str:
+        """Delegate name to wrapped agent."""
+        return getattr(self.agent, 'name', 'AutoRagAgent')
+    
+    def _needs_retrieval(self, query: str) -> bool:
+        """
+        Determine if query needs retrieval based on heuristics.
+        
+        Simple, local heuristics (no ML classifier):
+        1. Query length check
+        2. Keyword presence check
+        3. Question mark check
+        
+        Args:
+            query: User query
+            
+        Returns:
+            True if retrieval should be performed
+        """
+        # Check minimum length
+        if len(query.strip()) < self.config.auto_min_length:
+            return False
+        
+        # Check for keywords
+        query_lower = query.lower()
+        for keyword in self.config.auto_keywords:
+            if keyword in query_lower:
+                return True
+        
+        # Check for question marks (likely a question)
+        if "?" in query:
+            return True
+        
+        return False
+    
+    def _should_retrieve(
+        self,
+        query: str,
+        force_retrieval: bool = False,
+        skip_retrieval: bool = False,
+    ) -> bool:
+        """
+        Determine if retrieval should be performed.
+        
+        Args:
+            query: User query
+            force_retrieval: Override to force retrieval
+            skip_retrieval: Override to skip retrieval
+            
+        Returns:
+            True if retrieval should be performed
+        """
+        # Explicit overrides take precedence
+        if skip_retrieval:
+            return False
+        if force_retrieval:
+            return True
+        
+        # Check if RAG is available
+        if self.rag is None:
+            logger.debug("RAG not available, skipping retrieval")
+            return False
+        
+        # Apply policy
+        if self.config.retrieval_policy == RetrievalPolicy.ALWAYS:
+            return True
+        elif self.config.retrieval_policy == RetrievalPolicy.NEVER:
+            return False
+        else:  # AUTO
+            return self._needs_retrieval(query)
+    
+    def _format_response_with_citations(
+        self,
+        response: str,
+        context_pack: Optional["ContextPack"],
+    ) -> str:
+        """Format response with citations based on config."""
+        if context_pack is None or not context_pack.has_citations:
+            return response
+        
+        if self.config.citations_mode == "none":
+            return response
+        elif self.config.citations_mode == "hidden":
+            return response
+        else:  # append
+            if not self.config.include_citations:
+                return response
+            
+            sources = "\n\nSources:\n"
+            for citation in context_pack.citations:
+                sources += f"  [{citation.id}] {citation.source}\n"
+            return response + sources
+    
+    def chat(
+        self,
+        message: str,
+        *,
+        force_retrieval: bool = False,
+        skip_retrieval: bool = False,
+        top_k: Optional[int] = None,
+        hybrid: Optional[bool] = None,
+        rerank: Optional[bool] = None,
+        user_id: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        """
+        Chat with automatic RAG retrieval decision.
+        
+        Decides whether to retrieve context, then runs agent chat.
+        
+        Args:
+            message: User message/query
+            force_retrieval: Force retrieval regardless of policy
+            skip_retrieval: Skip retrieval regardless of policy
+            top_k: Override top_k for retrieval
+            hybrid: Override hybrid retrieval setting
+            rerank: Override rerank setting
+            user_id: User ID for RAG retrieval (uses agent.user_id if not provided)
+            **kwargs: Additional arguments passed to agent.chat()
+            
+        Returns:
+            Agent response (with citations if configured)
+        """
+        start_time = time.time()
+        context_pack = None
+        
+        # Determine if we should retrieve
+        should_retrieve = self._should_retrieve(
+            message,
+            force_retrieval=force_retrieval,
+            skip_retrieval=skip_retrieval,
+        )
+        
+        if should_retrieve and self.rag is not None:
+            logger.debug(f"AutoRagAgent: Performing retrieval for: {message[:50]}...")
+            
+            # Get user_id from parameter or agent
+            effective_user_id = user_id or getattr(self.agent, 'user_id', None)
+            
+            # Retrieve context
+            context_pack = self.rag.retrieve(
+                query=message,
+                top_k=top_k or self.config.top_k,
+                hybrid=hybrid if hybrid is not None else self.config.hybrid,
+                rerank=rerank if rerank is not None else self.config.rerank,
+                user_id=effective_user_id,
+            )
+            
+            # Use agent's chat_with_context if available
+            if hasattr(self.agent, 'chat_with_context'):
+                response = self.agent.chat_with_context(
+                    message=message,
+                    context=context_pack,
+                    citations_mode=self.config.citations_mode,
+                    **kwargs,
+                )
+            else:
+                # Fallback: inject context into message
+                augmented_message = self._augment_message(message, context_pack)
+                response = self.agent.chat(augmented_message, **kwargs)
+                response = self._format_response_with_citations(response, context_pack)
+        else:
+            # Direct agent chat without retrieval
+            logger.debug(f"AutoRagAgent: Skipping retrieval for: {message[:50]}...")
+            response = self.agent.chat(message, **kwargs)
+        
+        elapsed = time.time() - start_time
+        logger.debug(f"AutoRagAgent: chat completed in {elapsed:.2f}s")
+        
+        return response
+    
+    def _augment_message(self, message: str, context_pack: "ContextPack") -> str:
+        """Augment message with retrieved context."""
+        return f"""Based on the following context, answer the question.
+
+Context:
+{context_pack.context}
+
+Question: {message}
+
+Answer:"""
+    
+    async def achat(
+        self,
+        message: str,
+        *,
+        force_retrieval: bool = False,
+        skip_retrieval: bool = False,
+        top_k: Optional[int] = None,
+        hybrid: Optional[bool] = None,
+        rerank: Optional[bool] = None,
+        user_id: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        """
+        Async version of chat.
+        
+        Currently wraps sync version. Can be extended for true async.
+        """
+        import asyncio
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.chat(
+                message=message,
+                force_retrieval=force_retrieval,
+                skip_retrieval=skip_retrieval,
+                top_k=top_k,
+                hybrid=hybrid,
+                rerank=rerank,
+                user_id=user_id,
+                **kwargs,
+            ),
+        )
+    
+    # Alias for consistency with Orchestrator pattern
+    run = chat
+    arun = achat

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

@@ -56,7 +56,6 @@ class AutoAgents(PraisonAIAgents):
         min_reflect: int = 1,
         llm: Optional[str] = None,
         function_calling_llm: Optional[str] = None,
-        respect_context_window: bool = True,
         code_execution_mode: str = "safe",
         embedder_config: Optional[Dict[str, Any]] = None,
         knowledge_sources: Optional[List[Any]] = None,
@@ -94,7 +93,6 @@ class AutoAgents(PraisonAIAgents):
         self.min_reflect = min_reflect
         self.llm = llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-5-nano')
         self.function_calling_llm = function_calling_llm
-        self.respect_context_window = respect_context_window
         self.code_execution_mode = code_execution_mode
         self.embedder_config = embedder_config
         self.knowledge_sources = knowledge_sources
@@ -446,7 +444,6 @@ DO NOT use strings for tasks. Each task MUST be a complete object with all four
                 min_reflect=self.min_reflect,
                 llm=self.llm,
                 function_calling_llm=self.function_calling_llm,
-                respect_context_window=self.respect_context_window,
                 code_execution_mode=self.code_execution_mode,
                 embedder_config=self.embedder_config,
                 knowledge=self.knowledge_sources,

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

@@ -0,0 +1,238 @@
+"""
+Agent Profiles and Modes for PraisonAI Agents.
+
+Provides built-in agent profiles and mode configurations
+similar to OpenCode's agent system.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class AgentMode(str, Enum):
+    """Agent execution modes."""
+    
+    PRIMARY = "primary"      # Main agent, can spawn subagents
+    SUBAGENT = "subagent"    # Spawned by another agent
+    ALL = "all"              # Can be used in any context
+
+
+@dataclass
+class AgentProfile:
+    """
+    A built-in agent profile configuration.
+    
+    Attributes:
+        name: Unique agent name
+        description: What this agent does
+        mode: Execution mode (primary/subagent/all)
+        system_prompt: System prompt for the agent
+        tools: List of tool names this agent can use
+        temperature: LLM temperature setting
+        top_p: LLM top_p setting
+        max_steps: Maximum execution steps
+        hidden: Whether to hide from agent list
+        color: Display color (for UI)
+    """
+    
+    name: str
+    description: str = ""
+    mode: AgentMode = AgentMode.ALL
+    system_prompt: str = ""
+    tools: List[str] = field(default_factory=list)
+    temperature: float = 0.7
+    top_p: float = 1.0
+    max_steps: int = 50
+    hidden: bool = False
+    color: str = "#3B82F6"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert profile to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "mode": self.mode.value,
+            "system_prompt": self.system_prompt,
+            "tools": self.tools,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+            "max_steps": self.max_steps,
+            "hidden": self.hidden,
+            "color": self.color,
+            "metadata": self.metadata,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AgentProfile":
+        """Create profile from dictionary."""
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            mode=AgentMode(data.get("mode", "all")),
+            system_prompt=data.get("system_prompt", ""),
+            tools=data.get("tools", []),
+            temperature=data.get("temperature", 0.7),
+            top_p=data.get("top_p", 1.0),
+            max_steps=data.get("max_steps", 50),
+            hidden=data.get("hidden", False),
+            color=data.get("color", "#3B82F6"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+# Built-in agent profiles
+BUILTIN_PROFILES: Dict[str, AgentProfile] = {
+    "general": AgentProfile(
+        name="general",
+        description="General-purpose coding assistant",
+        mode=AgentMode.PRIMARY,
+        system_prompt=(
+            "You are a helpful coding assistant. You can help with a wide variety "
+            "of programming tasks including writing code, debugging, explaining "
+            "concepts, and answering questions about software development."
+        ),
+        tools=["read_file", "write_file", "bash", "search"],
+        temperature=0.7,
+        color="#3B82F6",
+    ),
+    
+    "coder": AgentProfile(
+        name="coder",
+        description="Focused code implementation agent",
+        mode=AgentMode.ALL,
+        system_prompt=(
+            "You are an expert code implementation agent. Your focus is on writing "
+            "clean, efficient, and well-documented code. You follow best practices "
+            "and design patterns. When implementing features, you consider edge cases "
+            "and error handling."
+        ),
+        tools=["read_file", "write_file", "bash"],
+        temperature=0.3,
+        color="#10B981",
+    ),
+    
+    "planner": AgentProfile(
+        name="planner",
+        description="Task planning and decomposition agent",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a planning agent. Your role is to break down complex tasks "
+            "into smaller, manageable steps. You create clear, actionable plans "
+            "with specific milestones and success criteria. You do not execute "
+            "tasks yourself, only plan them."
+        ),
+        tools=["read_file", "search"],
+        temperature=0.5,
+        max_steps=20,
+        color="#F59E0B",
+    ),
+    
+    "reviewer": AgentProfile(
+        name="reviewer",
+        description="Code review and quality agent",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a code review agent. Your role is to review code for quality, "
+            "correctness, security, and best practices. You provide constructive "
+            "feedback and suggest improvements. You look for bugs, security issues, "
+            "and opportunities for optimization."
+        ),
+        tools=["read_file", "search"],
+        temperature=0.3,
+        max_steps=30,
+        color="#EF4444",
+    ),
+    
+    "explorer": AgentProfile(
+        name="explorer",
+        description="Codebase exploration and understanding agent",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a codebase exploration agent. Your role is to understand and "
+            "navigate codebases. You can find relevant files, understand code "
+            "structure, and identify patterns. You help locate where changes need "
+            "to be made."
+        ),
+        tools=["read_file", "search", "grep"],
+        temperature=0.5,
+        max_steps=40,
+        color="#8B5CF6",
+    ),
+    
+    "debugger": AgentProfile(
+        name="debugger",
+        description="Debugging and troubleshooting agent",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a debugging agent. Your role is to identify and fix bugs. "
+            "You analyze error messages, trace code execution, and identify root "
+            "causes. You suggest minimal fixes that address the issue without "
+            "introducing new problems."
+        ),
+        tools=["read_file", "bash", "search"],
+        temperature=0.3,
+        max_steps=30,
+        color="#EC4899",
+    ),
+    
+    "compaction": AgentProfile(
+        name="compaction",
+        description="Context compaction agent (internal)",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a context compaction agent. Your role is to summarize "
+            "conversation history while preserving essential information. "
+            "You create concise summaries that maintain context for continued "
+            "work."
+        ),
+        tools=[],
+        temperature=0.3,
+        max_steps=5,
+        hidden=True,
+        color="#6B7280",
+    ),
+    
+    "title": AgentProfile(
+        name="title",
+        description="Session title generation agent (internal)",
+        mode=AgentMode.SUBAGENT,
+        system_prompt=(
+            "You are a title generation agent. Your role is to create short, "
+            "descriptive titles for conversations based on their content. "
+            "Titles should be concise (3-7 words) and capture the main topic."
+        ),
+        tools=[],
+        temperature=0.7,
+        max_steps=1,
+        hidden=True,
+        color="#6B7280",
+    ),
+}
+
+
+def get_profile(name: str) -> Optional[AgentProfile]:
+    """Get a built-in agent profile by name."""
+    return BUILTIN_PROFILES.get(name)
+
+
+def list_profiles(include_hidden: bool = False) -> List[AgentProfile]:
+    """List all built-in agent profiles."""
+    profiles = list(BUILTIN_PROFILES.values())
+    if not include_hidden:
+        profiles = [p for p in profiles if not p.hidden]
+    return profiles
+
+
+def register_profile(profile: AgentProfile) -> None:
+    """Register a custom agent profile."""
+    BUILTIN_PROFILES[profile.name] = profile
+
+
+def get_profiles_by_mode(mode: AgentMode) -> List[AgentProfile]:
+    """Get all profiles that can be used in a specific mode."""
+    return [
+        p for p in BUILTIN_PROFILES.values()
+        if p.mode == mode or p.mode == AgentMode.ALL
+    ]

src/praisonai-agents/praisonaiagents/approval.py

@@ -7,9 +7,12 @@ It extends the existing callback system to require human approval before executi
 
 import logging
 import asyncio
-from typing import Dict, Set, Optional, Callable, Any, Literal
+import json
+import os
+from typing import Dict, Set, Optional, Callable, Any, Literal, List
 from functools import wraps
 from contextvars import ContextVar
+from dataclasses import dataclass, field
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
@@ -28,6 +31,172 @@ approval_callback: Optional[Callable] = None
 # Context variable to track if we're in an approved execution context
 _approved_context: ContextVar[Set[str]] = ContextVar('approved_context', default=set())
 
+# Global permission allowlist
+_permission_allowlist: Optional["PermissionAllowlist"] = None
+
+
+@dataclass
+class ToolPermission:
+    """Permission entry for a tool."""
+    tool_name: str
+    allowed_paths: List[str] = field(default_factory=list)
+    session_only: bool = False  # If True, permission expires with session
+
+
+class PermissionAllowlist:
+    """
+    Persistent permission allowlist for tools.
+    
+    Allows pre-approving tools and paths to skip interactive approval.
+    Can be saved/loaded from JSON for persistence across sessions.
+    
+    Usage:
+        allowlist = PermissionAllowlist()
+        allowlist.add_tool("read_file")
+        allowlist.add_tool("write_file", paths=["./src", "./tests"])
+        
+        if allowlist.is_allowed("read_file"):
+            # Skip approval prompt
+            pass
+    """
+    
+    def __init__(self):
+        self._tools: Dict[str, ToolPermission] = {}
+        self._session_tools: Set[str] = set()
+        
+    def add_tool(
+        self, 
+        tool_name: str, 
+        paths: Optional[List[str]] = None,
+        session_only: bool = False
+    ) -> None:
+        """
+        Add a tool to the allowlist.
+        
+        Args:
+            tool_name: Name of the tool to allow
+            paths: Optional list of allowed paths (empty = all paths)
+            session_only: If True, permission expires with session
+        """
+        self._tools[tool_name] = ToolPermission(
+            tool_name=tool_name,
+            allowed_paths=paths or [],
+            session_only=session_only
+        )
+        if session_only:
+            self._session_tools.add(tool_name)
+            
+    def remove_tool(self, tool_name: str) -> bool:
+        """Remove a tool from the allowlist."""
+        if tool_name in self._tools:
+            del self._tools[tool_name]
+            self._session_tools.discard(tool_name)
+            return True
+        return False
+    
+    def is_allowed(self, tool_name: str, path: Optional[str] = None) -> bool:
+        """
+        Check if a tool is allowed.
+        
+        Args:
+            tool_name: Name of the tool
+            path: Optional path to check against allowed paths
+            
+        Returns:
+            True if tool is allowed (optionally for the given path)
+        """
+        if tool_name not in self._tools:
+            return False
+            
+        permission = self._tools[tool_name]
+        
+        # If no paths specified, tool is allowed for all paths
+        if not permission.allowed_paths:
+            return True
+            
+        # If path not provided, check if tool has any permissions
+        if path is None:
+            return True
+            
+        # Check if path matches any allowed path
+        for allowed_path in permission.allowed_paths:
+            # Normalize paths for comparison
+            norm_allowed = os.path.normpath(allowed_path)
+            norm_path = os.path.normpath(path)
+            
+            # Check if path starts with allowed path
+            if norm_path.startswith(norm_allowed):
+                return True
+                
+        return False
+    
+    def is_empty(self) -> bool:
+        """Check if allowlist is empty."""
+        return len(self._tools) == 0
+    
+    def list_tools(self) -> List[str]:
+        """List all allowed tools."""
+        return list(self._tools.keys())
+    
+    def clear_session_permissions(self) -> None:
+        """Clear session-only permissions."""
+        for tool_name in list(self._session_tools):
+            if tool_name in self._tools:
+                del self._tools[tool_name]
+        self._session_tools.clear()
+    
+    def save(self, filepath: str) -> None:
+        """Save allowlist to JSON file."""
+        data = {
+            "tools": {
+                name: {
+                    "allowed_paths": perm.allowed_paths,
+                    "session_only": perm.session_only
+                }
+                for name, perm in self._tools.items()
+                if not perm.session_only  # Don't persist session-only permissions
+            }
+        }
+        
+        os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+        with open(filepath, "w") as f:
+            json.dump(data, f, indent=2)
+    
+    @classmethod
+    def load(cls, filepath: str) -> "PermissionAllowlist":
+        """Load allowlist from JSON file."""
+        allowlist = cls()
+        
+        if not os.path.exists(filepath):
+            return allowlist
+            
+        with open(filepath, "r") as f:
+            data = json.load(f)
+            
+        for tool_name, tool_data in data.get("tools", {}).items():
+            allowlist.add_tool(
+                tool_name,
+                paths=tool_data.get("allowed_paths", []),
+                session_only=tool_data.get("session_only", False)
+            )
+            
+        return allowlist
+
+
+def get_permission_allowlist() -> PermissionAllowlist:
+    """Get the global permission allowlist."""
+    global _permission_allowlist
+    if _permission_allowlist is None:
+        _permission_allowlist = PermissionAllowlist()
+    return _permission_allowlist
+
+
+def set_permission_allowlist(allowlist: PermissionAllowlist) -> None:
+    """Set the global permission allowlist."""
+    global _permission_allowlist
+    _permission_allowlist = allowlist
+
+
 class ApprovalDecision:
     """Result of an approval request"""
     def __init__(self, approved: bool, modified_args: Optional[Dict[str, Any]] = None, reason: str = ""):

src/praisonai-agents/praisonaiagents/background/job_manager.py

@@ -0,0 +1,286 @@
+"""
+Background Job Manager for PraisonAI Agents.
+
+Provides job lifecycle tracking, auto-backgrounding based on threshold,
+and status inspection for long-running agent tasks.
+"""
+
+import threading
+import time
+import uuid
+from enum import Enum
+from typing import Any, Callable, Dict, Optional
+from dataclasses import dataclass, field
+from concurrent.futures import ThreadPoolExecutor, Future
+
+
+class JobStatus(str, Enum):
+    """Status of a background job."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class JobInfo:
+    """Information about a background job."""
+    job_id: str
+    status: JobStatus
+    created_at: float = field(default_factory=time.time)
+    started_at: Optional[float] = None
+    completed_at: Optional[float] = None
+    result: Any = None
+    error: Optional[str] = None
+    
+    @property
+    def duration(self) -> Optional[float]:
+        """Get job duration in seconds."""
+        if self.started_at is None:
+            return None
+        end_time = self.completed_at or time.time()
+        return end_time - self.started_at
+
+
+class BackgroundJobManager:
+    """
+    Manages background jobs for agent tasks.
+    
+    Features:
+    - Job lifecycle tracking (pending, running, completed, failed)
+    - Auto-backgrounding based on execution time threshold
+    - Thread-safe job status inspection
+    - Configurable thread pool for concurrent execution
+    """
+    
+    def __init__(
+        self,
+        max_workers: int = 4,
+        auto_background_threshold: float = 5.0,
+    ):
+        """
+        Initialize the background job manager.
+        
+        Args:
+            max_workers: Maximum number of concurrent background jobs
+            auto_background_threshold: Time in seconds after which a job
+                should be automatically backgrounded
+        """
+        self.max_workers = max_workers
+        self.auto_background_threshold = auto_background_threshold
+        self._executor = ThreadPoolExecutor(max_workers=max_workers)
+        self._jobs: Dict[str, JobInfo] = {}
+        self._futures: Dict[str, Future] = {}
+        self._lock = threading.Lock()
+    
+    @property
+    def active_jobs(self) -> int:
+        """Get the number of active (pending or running) jobs."""
+        with self._lock:
+            return sum(
+                1 for job in self._jobs.values()
+                if job.status in (JobStatus.PENDING, JobStatus.RUNNING)
+            )
+    
+    def start_job(
+        self,
+        func: Callable[[], Any],
+        job_id: Optional[str] = None,
+    ) -> str:
+        """
+        Start a new background job.
+        
+        Args:
+            func: The function to execute in the background
+            job_id: Optional custom job ID (auto-generated if not provided)
+            
+        Returns:
+            The job ID
+        """
+        job_id = job_id or str(uuid.uuid4())[:8]
+        
+        job_info = JobInfo(
+            job_id=job_id,
+            status=JobStatus.PENDING,
+        )
+        
+        with self._lock:
+            self._jobs[job_id] = job_info
+        
+        def _run_job():
+            with self._lock:
+                self._jobs[job_id].status = JobStatus.RUNNING
+                self._jobs[job_id].started_at = time.time()
+            
+            try:
+                result = func()
+                with self._lock:
+                    self._jobs[job_id].status = JobStatus.COMPLETED
+                    self._jobs[job_id].completed_at = time.time()
+                    self._jobs[job_id].result = result
+                return result
+            except Exception as e:
+                with self._lock:
+                    self._jobs[job_id].status = JobStatus.FAILED
+                    self._jobs[job_id].completed_at = time.time()
+                    self._jobs[job_id].error = str(e)
+                raise
+        
+        future = self._executor.submit(_run_job)
+        with self._lock:
+            self._futures[job_id] = future
+        
+        return job_id
+    
+    def get_status(self, job_id: str) -> JobStatus:
+        """
+        Get the status of a job.
+        
+        Args:
+            job_id: The job ID to check
+            
+        Returns:
+            The job status
+            
+        Raises:
+            KeyError: If job_id is not found
+        """
+        with self._lock:
+            if job_id not in self._jobs:
+                raise KeyError(f"Job {job_id} not found")
+            return self._jobs[job_id].status
+    
+    def get_job_info(self, job_id: str) -> JobInfo:
+        """
+        Get full information about a job.
+        
+        Args:
+            job_id: The job ID to check
+            
+        Returns:
+            The job information
+            
+        Raises:
+            KeyError: If job_id is not found
+        """
+        with self._lock:
+            if job_id not in self._jobs:
+                raise KeyError(f"Job {job_id} not found")
+            return self._jobs[job_id]
+    
+    def get_result(self, job_id: str, timeout: Optional[float] = None) -> Any:
+        """
+        Get the result of a completed job.
+        
+        Args:
+            job_id: The job ID
+            timeout: Maximum time to wait for completion
+            
+        Returns:
+            The job result
+            
+        Raises:
+            KeyError: If job_id is not found
+            TimeoutError: If timeout is reached before completion
+            RuntimeError: If job failed
+        """
+        with self._lock:
+            if job_id not in self._futures:
+                raise KeyError(f"Job {job_id} not found")
+            future = self._futures[job_id]
+        
+        try:
+            return future.result(timeout=timeout)
+        except TimeoutError:
+            raise TimeoutError(f"Job {job_id} did not complete within {timeout} seconds")
+    
+    def cancel_job(self, job_id: str) -> bool:
+        """
+        Attempt to cancel a job.
+        
+        Args:
+            job_id: The job ID to cancel
+            
+        Returns:
+            True if cancellation was successful, False otherwise
+        """
+        with self._lock:
+            if job_id not in self._futures:
+                return False
+            future = self._futures[job_id]
+            cancelled = future.cancel()
+            if cancelled:
+                self._jobs[job_id].status = JobStatus.CANCELLED
+                self._jobs[job_id].completed_at = time.time()
+            return cancelled
+    
+    def list_jobs(self, status: Optional[JobStatus] = None) -> Dict[str, JobInfo]:
+        """
+        List all jobs, optionally filtered by status.
+        
+        Args:
+            status: Optional status filter
+            
+        Returns:
+            Dictionary of job_id -> JobInfo
+        """
+        with self._lock:
+            if status is None:
+                return dict(self._jobs)
+            return {
+                job_id: info
+                for job_id, info in self._jobs.items()
+                if info.status == status
+            }
+    
+    def cleanup_completed(self, max_age: float = 3600.0) -> int:
+        """
+        Remove completed jobs older than max_age seconds.
+        
+        Args:
+            max_age: Maximum age in seconds for completed jobs
+            
+        Returns:
+            Number of jobs removed
+        """
+        now = time.time()
+        removed = 0
+        
+        with self._lock:
+            to_remove = []
+            for job_id, info in self._jobs.items():
+                if info.status in (JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED):
+                    if info.completed_at and (now - info.completed_at) > max_age:
+                        to_remove.append(job_id)
+            
+            for job_id in to_remove:
+                del self._jobs[job_id]
+                if job_id in self._futures:
+                    del self._futures[job_id]
+                removed += 1
+        
+        return removed
+    
+    def shutdown(self, wait: bool = True) -> None:
+        """
+        Shutdown the job manager.
+        
+        Args:
+            wait: Whether to wait for pending jobs to complete
+        """
+        self._executor.shutdown(wait=wait)
+
+
+# Global job manager instance (lazy initialized)
+_global_job_manager: Optional[BackgroundJobManager] = None
+_global_lock = threading.Lock()
+
+
+def get_job_manager() -> BackgroundJobManager:
+    """Get the global job manager instance."""
+    global _global_job_manager
+    with _global_lock:
+        if _global_job_manager is None:
+            _global_job_manager = BackgroundJobManager()
+        return _global_job_manager

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

@@ -0,0 +1,71 @@
+"""
+Event Bus Module for PraisonAI Agents.
+
+Provides a typed publish/subscribe event system for real-time communication
+between components. Extends the existing hooks system with a more general
+event-driven architecture.
+
+Features:
+- Typed event definitions with dataclass payloads
+- Sync and async subscribers
+- Event filtering by type
+- Global and scoped event buses
+- SSE-compatible event streaming
+
+Zero Performance Impact:
+- All imports are lazy loaded
+- No overhead when not subscribed
+- Optional dependency for server features
+
+Usage:
+    from praisonaiagents.bus import EventBus, Event
+    
+    # Create event bus
+    bus = EventBus()
+    
+    # Subscribe to events
+    @bus.on("session.created")
+    def handle_session(event):
+        print(f"Session created: {event.data}")
+    
+    # Publish events
+    bus.publish("session.created", {"session_id": "abc123"})
+"""
+
+__all__ = [
+    "EventBus",
+    "Event",
+    "EventType",
+    "Subscriber",
+    "get_default_bus",
+    "set_default_bus",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load module components."""
+    if name == "EventBus":
+        from .bus import EventBus
+        return EventBus
+    
+    if name == "Event":
+        from .event import Event
+        return Event
+    
+    if name == "EventType":
+        from .event import EventType
+        return EventType
+    
+    if name == "Subscriber":
+        from .bus import Subscriber
+        return Subscriber
+    
+    if name == "get_default_bus":
+        from .bus import get_default_bus
+        return get_default_bus
+    
+    if name == "set_default_bus":
+        from .bus import set_default_bus
+        return set_default_bus
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

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

@@ -0,0 +1,346 @@
+"""
+Event Bus implementation for PraisonAI Agents.
+
+Provides publish/subscribe functionality for typed events.
+"""
+
+import asyncio
+import logging
+import threading
+from typing import Any, Callable, Dict, List, Optional, Set, Union
+from dataclasses import dataclass, field
+from .event import Event, EventType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Subscriber:
+    """
+    A subscriber to the event bus.
+    
+    Attributes:
+        callback: Function to call when event is received
+        event_types: Set of event types to subscribe to (None = all)
+        is_async: Whether the callback is async
+        id: Unique subscriber identifier
+    """
+    callback: Callable[[Event], Any]
+    event_types: Optional[Set[str]] = None
+    is_async: bool = False
+    id: str = field(default_factory=lambda: str(__import__("uuid").uuid4()))
+    
+    def matches(self, event_type: str) -> bool:
+        """Check if subscriber should receive this event type."""
+        if self.event_types is None:
+            return True
+        return event_type in self.event_types
+
+
+class EventBus:
+    """
+    Event bus for publish/subscribe communication.
+    
+    Thread-safe implementation supporting both sync and async subscribers.
+    
+    Example:
+        bus = EventBus()
+        
+        # Subscribe with decorator
+        @bus.on(EventType.SESSION_CREATED)
+        def handle_session(event):
+            print(f"Session: {event.data}")
+        
+        # Subscribe to all events
+        bus.subscribe(lambda e: print(e))
+        
+        # Publish event
+        bus.publish(EventType.SESSION_CREATED, {"session_id": "abc"})
+    """
+    
+    def __init__(self):
+        """Initialize the event bus."""
+        self._subscribers: List[Subscriber] = []
+        self._lock = threading.RLock()
+        self._event_history: List[Event] = []
+        self._max_history = 1000
+    
+    def subscribe(
+        self,
+        callback: Callable[[Event], Any],
+        event_types: Optional[Union[str, List[str], Set[str]]] = None,
+    ) -> str:
+        """
+        Subscribe to events.
+        
+        Args:
+            callback: Function to call when event is received
+            event_types: Optional event type(s) to filter by
+            
+        Returns:
+            Subscriber ID for unsubscribing
+        """
+        # Normalize event_types to a set
+        if event_types is None:
+            types_set = None
+        elif isinstance(event_types, str):
+            types_set = {event_types}
+        else:
+            types_set = set(event_types)
+        
+        # Check if callback is async
+        is_async = asyncio.iscoroutinefunction(callback)
+        
+        subscriber = Subscriber(
+            callback=callback,
+            event_types=types_set,
+            is_async=is_async,
+        )
+        
+        with self._lock:
+            self._subscribers.append(subscriber)
+        
+        logger.debug(f"Subscribed {subscriber.id} to {types_set or 'all events'}")
+        return subscriber.id
+    
+    def unsubscribe(self, subscriber_id: str) -> bool:
+        """
+        Unsubscribe from events.
+        
+        Args:
+            subscriber_id: The subscriber ID returned from subscribe()
+            
+        Returns:
+            True if found and removed, False otherwise
+        """
+        with self._lock:
+            for i, sub in enumerate(self._subscribers):
+                if sub.id == subscriber_id:
+                    self._subscribers.pop(i)
+                    logger.debug(f"Unsubscribed {subscriber_id}")
+                    return True
+        return False
+    
+    def on(
+        self,
+        *event_types: Union[str, EventType],
+    ) -> Callable:
+        """
+        Decorator to subscribe a function to events.
+        
+        Args:
+            event_types: Event type(s) to subscribe to
+            
+        Returns:
+            Decorator function
+            
+        Example:
+            @bus.on(EventType.SESSION_CREATED)
+            def handle_session(event):
+                print(event.data)
+        """
+        # Convert EventType enums to strings
+        types = {
+            t.value if isinstance(t, EventType) else t
+            for t in event_types
+        } if event_types else None
+        
+        def decorator(func: Callable[[Event], Any]) -> Callable:
+            self.subscribe(func, types)
+            return func
+        
+        return decorator
+    
+    def publish(
+        self,
+        event_type: Union[str, EventType],
+        data: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Event:
+        """
+        Publish an event to all matching subscribers.
+        
+        Args:
+            event_type: The event type
+            data: Event payload data
+            source: Optional source identifier
+            metadata: Optional additional metadata
+            
+        Returns:
+            The published Event object
+        """
+        # Convert EventType enum to string
+        type_str = event_type.value if isinstance(event_type, EventType) else event_type
+        
+        event = Event(
+            type=type_str,
+            data=data or {},
+            source=source,
+            metadata=metadata or {},
+        )
+        
+        return self.publish_event(event)
+    
+    def publish_event(self, event: Event) -> Event:
+        """
+        Publish a pre-constructed event.
+        
+        Args:
+            event: The event to publish
+            
+        Returns:
+            The published event
+        """
+        logger.debug(f"Publishing event: {event.type}")
+        
+        # Store in history
+        with self._lock:
+            self._event_history.append(event)
+            if len(self._event_history) > self._max_history:
+                self._event_history = self._event_history[-self._max_history:]
+            
+            # Get matching subscribers
+            subscribers = [
+                sub for sub in self._subscribers
+                if sub.matches(event.type)
+            ]
+        
+        # Dispatch to subscribers
+        for sub in subscribers:
+            try:
+                if sub.is_async:
+                    # Schedule async callback
+                    try:
+                        loop = asyncio.get_running_loop()
+                        loop.create_task(sub.callback(event))
+                    except RuntimeError:
+                        # No running loop, run synchronously
+                        asyncio.run(sub.callback(event))
+                else:
+                    sub.callback(event)
+            except Exception as e:
+                logger.error(f"Error in subscriber {sub.id}: {e}")
+        
+        return event
+    
+    async def publish_async(
+        self,
+        event_type: Union[str, EventType],
+        data: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Event:
+        """
+        Async version of publish that awaits all async subscribers.
+        
+        Args:
+            event_type: The event type
+            data: Event payload data
+            source: Optional source identifier
+            metadata: Optional additional metadata
+            
+        Returns:
+            The published Event object
+        """
+        type_str = event_type.value if isinstance(event_type, EventType) else event_type
+        
+        event = Event(
+            type=type_str,
+            data=data or {},
+            source=source,
+            metadata=metadata or {},
+        )
+        
+        logger.debug(f"Publishing async event: {event.type}")
+        
+        # Store in history
+        with self._lock:
+            self._event_history.append(event)
+            if len(self._event_history) > self._max_history:
+                self._event_history = self._event_history[-self._max_history:]
+            
+            subscribers = [
+                sub for sub in self._subscribers
+                if sub.matches(event.type)
+            ]
+        
+        # Dispatch to subscribers
+        tasks = []
+        for sub in subscribers:
+            try:
+                if sub.is_async:
+                    tasks.append(sub.callback(event))
+                else:
+                    sub.callback(event)
+            except Exception as e:
+                logger.error(f"Error in subscriber {sub.id}: {e}")
+        
+        # Await all async tasks
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        
+        return event
+    
+    def get_history(
+        self,
+        event_type: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Event]:
+        """
+        Get recent event history.
+        
+        Args:
+            event_type: Optional filter by event type
+            limit: Maximum number of events to return
+            
+        Returns:
+            List of recent events
+        """
+        with self._lock:
+            events = self._event_history.copy()
+        
+        if event_type:
+            events = [e for e in events if e.type == event_type]
+        
+        return events[-limit:]
+    
+    def clear_history(self):
+        """Clear the event history."""
+        with self._lock:
+            self._event_history.clear()
+    
+    def clear_subscribers(self):
+        """Remove all subscribers."""
+        with self._lock:
+            self._subscribers.clear()
+    
+    @property
+    def subscriber_count(self) -> int:
+        """Get the number of subscribers."""
+        with self._lock:
+            return len(self._subscribers)
+    
+    def __repr__(self) -> str:
+        return f"EventBus(subscribers={self.subscriber_count})"
+
+
+# Global default bus
+_default_bus: Optional[EventBus] = None
+_bus_lock = threading.Lock()
+
+
+def get_default_bus() -> EventBus:
+    """Get the default global event bus."""
+    global _default_bus
+    with _bus_lock:
+        if _default_bus is None:
+            _default_bus = EventBus()
+        return _default_bus
+
+
+def set_default_bus(bus: EventBus):
+    """Set the default global event bus."""
+    global _default_bus
+    with _bus_lock:
+        _default_bus = bus

src/praisonai-agents/praisonaiagents/bus/event.py

@@ -0,0 +1,111 @@
+"""
+Event definitions for the Event Bus.
+
+Provides typed event structures for the publish/subscribe system.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+from enum import Enum
+import time
+import uuid
+
+
+class EventType(str, Enum):
+    """Standard event types for the agent system."""
+    
+    # Session events
+    SESSION_CREATED = "session.created"
+    SESSION_UPDATED = "session.updated"
+    SESSION_DELETED = "session.deleted"
+    SESSION_FORKED = "session.forked"
+    SESSION_REVERTED = "session.reverted"
+    
+    # Message events
+    MESSAGE_CREATED = "message.created"
+    MESSAGE_UPDATED = "message.updated"
+    MESSAGE_PART_CREATED = "message.part.created"
+    MESSAGE_PART_UPDATED = "message.part.updated"
+    
+    # Permission events
+    PERMISSION_ASKED = "permission.asked"
+    PERMISSION_REPLIED = "permission.replied"
+    
+    # Agent events
+    AGENT_STARTED = "agent.started"
+    AGENT_COMPLETED = "agent.completed"
+    AGENT_ERROR = "agent.error"
+    
+    # Tool events
+    TOOL_STARTED = "tool.started"
+    TOOL_COMPLETED = "tool.completed"
+    TOOL_ERROR = "tool.error"
+    
+    # Snapshot events
+    SNAPSHOT_CREATED = "snapshot.created"
+    SNAPSHOT_RESTORED = "snapshot.restored"
+    
+    # Server events
+    SERVER_STARTED = "server.started"
+    SERVER_STOPPED = "server.stopped"
+    CLIENT_CONNECTED = "client.connected"
+    CLIENT_DISCONNECTED = "client.disconnected"
+    
+    # Compaction events
+    COMPACTION_STARTED = "compaction.started"
+    COMPACTION_COMPLETED = "compaction.completed"
+    
+    # Custom event (for user-defined events)
+    CUSTOM = "custom"
+
+
+@dataclass
+class Event:
+    """
+    A typed event for the event bus.
+    
+    Attributes:
+        type: The event type (from EventType enum or custom string)
+        data: The event payload data
+        id: Unique event identifier
+        timestamp: Unix timestamp when event was created
+        source: Optional source identifier (e.g., session_id, agent_name)
+        metadata: Optional additional metadata
+    """
+    type: str
+    data: Dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: float = field(default_factory=time.time)
+    source: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert event to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "type": self.type,
+            "data": self.data,
+            "timestamp": self.timestamp,
+            "source": self.source,
+            "metadata": self.metadata,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Event":
+        """Create event from dictionary."""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            type=data.get("type", EventType.CUSTOM.value),
+            data=data.get("data", {}),
+            timestamp=data.get("timestamp", time.time()),
+            source=data.get("source"),
+            metadata=data.get("metadata", {}),
+        )
+    
+    def to_sse(self) -> str:
+        """Format event for Server-Sent Events."""
+        import json
+        return f"id: {self.id}\nevent: {self.type}\ndata: {json.dumps(self.to_dict())}\n\n"
+    
+    def __repr__(self) -> str:
+        return f"Event(type={self.type!r}, id={self.id[:8]}..., source={self.source!r})"

src/praisonai-agents/praisonaiagents/compaction/compactor.py

@@ -109,6 +109,10 @@ class ContextCompactor:
             compacted = self._summarize(messages)
         elif self.strategy == CompactionStrategy.SMART:
             compacted = self._smart_compact(messages)
+        elif self.strategy == CompactionStrategy.PRUNE:
+            compacted = self._prune(messages)
+        elif self.strategy == CompactionStrategy.LLM_SUMMARIZE:
+            compacted = self._llm_summarize(messages)
         else:
             compacted = self._truncate(messages)
         
@@ -223,6 +227,89 @@ class ContextCompactor:
         # For now, use sliding window as base
         return self._sliding_window(messages)
     
+    def _prune(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Prune old tool outputs while keeping tool calls.
+        
+        This reduces token usage by removing verbose tool outputs
+        from older messages while preserving the context of what
+        tools were called.
+        """
+        result = []
+        
+        # Separate system and other messages
+        system_msgs = [m for m in messages if m.get("role") == "system"]
+        other_msgs = [m for m in messages if m.get("role") != "system"]
+        
+        result.extend(system_msgs)
+        
+        # Keep recent messages intact
+        recent = other_msgs[-self.preserve_recent:]
+        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        
+        # Prune older messages
+        for msg in older:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            
+            # If this is a tool result, truncate it
+            if role == "tool" or msg.get("tool_call_id"):
+                if isinstance(content, str) and len(content) > 500:
+                    pruned_msg = msg.copy()
+                    pruned_msg["content"] = content[:200] + "\n...[output truncated]..."
+                    result.append(pruned_msg)
+                else:
+                    result.append(msg)
+            else:
+                result.append(msg)
+        
+        result.extend(recent)
+        return result
+    
+    def _llm_summarize(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Use LLM to summarize older messages.
+        
+        Note: This is a placeholder that returns a structured summary.
+        Actual LLM integration should be done at the agent level.
+        """
+        result = []
+        
+        # Keep system messages
+        system_msgs = [m for m in messages if m.get("role") == "system"]
+        other_msgs = [m for m in messages if m.get("role") != "system"]
+        
+        result.extend(system_msgs)
+        
+        # Keep recent messages
+        recent = other_msgs[-self.preserve_recent:]
+        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        
+        if older:
+            # Create structured summary for LLM to process
+            summary_parts = []
+            for msg in older:
+                role = msg.get("role", "unknown")
+                content = msg.get("content", "")
+                if isinstance(content, str) and content:
+                    # Extract key information
+                    summary_parts.append(f"[{role}]: {content[:150]}...")
+            
+            if summary_parts:
+                summary = (
+                    "[Compacted conversation history - summarize key points]\n"
+                    + "\n".join(summary_parts[:10])
+                )
+                result.append({
+                    "role": "system",
+                    "content": summary,
+                    "_compacted": True,
+                    "_original_count": len(older),
+                })
+        
+        result.extend(recent)
+        return result
+    
     def get_stats(self, messages: List[Dict[str, Any]]) -> Dict[str, Any]:
         """Get statistics about messages."""
         total_tokens = self.count_total_tokens(messages)

src/praisonai-agents/praisonaiagents/compaction/strategy.py

@@ -1,13 +1,16 @@
 """
-Compaction Strategies for PraisonAI Agents.
+Compaction strategies for context management.
 """
 
 from enum import Enum
 
 
 class CompactionStrategy(str, Enum):
-    """Strategy for compacting context."""
-    TRUNCATE = "truncate"      # Remove oldest messages
-    SUMMARIZE = "summarize"    # Summarize old messages
-    SLIDING = "sliding"        # Sliding window of recent messages
-    SMART = "smart"            # Intelligent selection based on relevance
+    """Available compaction strategies."""
+    
+    TRUNCATE = "truncate"
+    SLIDING = "sliding"
+    SUMMARIZE = "summarize"
+    SMART = "smart"
+    LLM_SUMMARIZE = "llm_summarize"  # Use LLM for summarization
+    PRUNE = "prune"  # Remove old tool outputs

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

@@ -1,30 +1,177 @@
 """
-Context module for PraisonAI Agents.
+Context Management Module for PraisonAI Agents.
 
-This module provides context retrieval capabilities including:
+This module provides comprehensive context management capabilities:
+- Token estimation and budgeting
+- Context composition within limits
+- Optimization strategies (truncate, sliding window, summarize, prune, smart)
+- Real-time context monitoring
+- Multi-agent context isolation
+
+Also includes:
 - Fast Context: Rapid parallel code search subagent
-"""
 
-# Lazy imports to avoid impacting package load time
-def __getattr__(name):
-    """Lazy import to avoid impacting package performance."""
-    if name == "FastContext":
-        from praisonaiagents.context.fast.fast_context import FastContext
-        return FastContext
-    elif name == "FastContextResult":
-        from praisonaiagents.context.fast.result import FastContextResult
-        return FastContextResult
-    elif name == "FileMatch":
-        from praisonaiagents.context.fast.result import FileMatch
-        return FileMatch
-    elif name == "LineRange":
-        from praisonaiagents.context.fast.result import LineRange
-        return LineRange
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+Zero Performance Impact:
+- All imports are lazy loaded via __getattr__
+- Features only activate when explicitly enabled
+- No overhead when context management is not used
+
+Usage:
+    from praisonaiagents.context import (
+        ContextBudgeter,
+        ContextComposer,
+        ContextMonitor,
+        get_optimizer,
+    )
+    
+    # Create budgeter for model
+    budgeter = ContextBudgeter(model="gpt-4o")
+    budget = budgeter.allocate()
+    
+    # Compose context within budget
+    composer = ContextComposer(budget=budget)
+    result = composer.compose(
+        system_prompt="You are helpful",
+        history=messages,
+        tools=tool_schemas,
+    )
+    
+    # Monitor context (opt-in)
+    monitor = ContextMonitor(enabled=True)
+    monitor.snapshot(ledger=result.ledger, budget=budget, messages=result.messages)
+"""
 
 __all__ = [
+    # Models
+    "ContextSegment",
+    "ContextLedger",
+    "BudgetAllocation",
+    "ContextSnapshot",
+    "OptimizerStrategy",
+    "OptimizationResult",
+    "MonitorConfig",
+    "ContextConfig",
+    # Token estimation
+    "estimate_tokens_heuristic",
+    "estimate_messages_tokens",
+    "estimate_tool_schema_tokens",
+    "TokenEstimatorImpl",
+    "get_estimator",
+    # Budgeting
+    "ContextBudgeter",
+    "get_model_limit",
+    "get_output_reserve",
+    # Ledger
+    "ContextLedgerManager",
+    "MultiAgentLedger",
+    # Composition
+    "ContextComposer",
+    "ComposedContext",
+    # Optimization
+    "BaseOptimizer",
+    "TruncateOptimizer",
+    "SlidingWindowOptimizer",
+    "PruneToolsOptimizer",
+    "NonDestructiveOptimizer",
+    "SummarizeOptimizer",
+    "SmartOptimizer",
+    "get_optimizer",
+    "get_effective_history",
+    # Monitoring
+    "ContextMonitor",
+    "MultiAgentMonitor",
+    "redact_sensitive",
+    "format_human_snapshot",
+    "format_json_snapshot",
+    "validate_monitor_path",
+    "should_include_content",
+    "load_ignore_patterns",
+    # Manager Facade (NEW)
+    "ContextManager",
+    "MultiAgentContextManager",
+    "create_context_manager",
+    "ManagerConfig",
+    "ContextPolicy",
+    "EstimationMode",
+    "ContextShareMode",
+    "ToolShareMode",
+    "OptimizationEvent",
+    "OptimizationEventType",
+    "EstimationMetrics",
+    "PerToolBudget",
+    "SnapshotHookData",
+    # Fast Context (legacy)
     "FastContext",
     "FastContextResult",
     "FileMatch",
     "LineRange",
 ]
+
+
+def __getattr__(name: str):
+    """Lazy load module components to avoid import overhead."""
+    # Models
+    if name in ("ContextSegment", "ContextLedger", "BudgetAllocation", 
+                "ContextSnapshot", "OptimizerStrategy", "OptimizationResult",
+                "MonitorConfig", "ContextConfig"):
+        from . import models
+        return getattr(models, name)
+    
+    # Token estimation
+    if name in ("estimate_tokens_heuristic", "estimate_messages_tokens",
+                "estimate_tool_schema_tokens", "TokenEstimatorImpl", "get_estimator"):
+        from . import tokens
+        return getattr(tokens, name)
+    
+    # Budgeting
+    if name in ("ContextBudgeter", "get_model_limit", "get_output_reserve"):
+        from . import budgeter
+        return getattr(budgeter, name)
+    
+    # Ledger
+    if name in ("ContextLedgerManager", "MultiAgentLedger"):
+        from . import ledger
+        return getattr(ledger, name)
+    
+    # Composition
+    if name in ("ContextComposer", "ComposedContext"):
+        from . import composer
+        return getattr(composer, name)
+    
+    # Optimization
+    if name in ("BaseOptimizer", "TruncateOptimizer", "SlidingWindowOptimizer",
+                "PruneToolsOptimizer", "NonDestructiveOptimizer", "SummarizeOptimizer",
+                "SmartOptimizer", "get_optimizer", "get_effective_history"):
+        from . import optimizer
+        return getattr(optimizer, name)
+    
+    # Monitoring
+    if name in ("ContextMonitor", "MultiAgentMonitor", "redact_sensitive",
+                "format_human_snapshot", "format_json_snapshot",
+                "validate_monitor_path", "should_include_content", "load_ignore_patterns"):
+        from . import monitor
+        return getattr(monitor, name)
+    
+    # Manager Facade
+    if name in ("ContextManager", "MultiAgentContextManager", "create_context_manager",
+                "ManagerConfig", "ContextPolicy", "EstimationMode", "ContextShareMode",
+                "ToolShareMode", "OptimizationEvent", "OptimizationEventType",
+                "EstimationMetrics", "PerToolBudget", "SnapshotHookData"):
+        from . import manager
+        return getattr(manager, name)
+    
+    # Fast Context (legacy)
+    if name == "FastContext":
+        from praisonaiagents.context.fast.fast_context import FastContext
+        return FastContext
+    if name == "FastContextResult":
+        from praisonaiagents.context.fast.result import FastContextResult
+        return FastContextResult
+    if name == "FileMatch":
+        from praisonaiagents.context.fast.result import FileMatch
+        return FileMatch
+    if name == "LineRange":
+        from praisonaiagents.context.fast.result import LineRange
+        return LineRange
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai-agents/praisonaiagents/context/budgeter.py

@@ -0,0 +1,229 @@
+"""
+Context Budgeter for PraisonAI Agents.
+
+Allocates token budgets across context segments based on model limits.
+"""
+
+from typing import Dict, Any, Optional
+from .models import BudgetAllocation
+
+
+# Model token limits (context window sizes)
+MODEL_LIMITS: Dict[str, int] = {
+    # OpenAI
+    "gpt-4o": 128000,
+    "gpt-4o-mini": 128000,
+    "gpt-4-turbo": 128000,
+    "gpt-4": 8192,
+    "gpt-3.5-turbo": 16385,
+    "gpt-3.5-turbo-16k": 16385,
+    # Anthropic
+    "claude-3-5-sonnet": 200000,
+    "claude-3-5-haiku": 200000,
+    "claude-3-opus": 200000,
+    "claude-3-sonnet": 200000,
+    "claude-3-haiku": 200000,
+    # Google
+    "gemini-2.0-flash": 1048576,
+    "gemini-1.5-pro": 2097152,
+    "gemini-1.5-flash": 1048576,
+    # Defaults
+    "default": 128000,
+}
+
+# Default output reserves by model family
+OUTPUT_RESERVES: Dict[str, int] = {
+    "gpt-4o": 16384,
+    "gpt-4o-mini": 16384,
+    "gpt-4-turbo": 4096,
+    "gpt-4": 4096,
+    "gpt-3.5-turbo": 4096,
+    "claude-3": 8192,
+    "gemini": 8192,
+    "default": 8000,
+}
+
+
+def get_model_limit(model: str) -> int:
+    """
+    Get context window limit for a model.
+    
+    Args:
+        model: Model name or identifier
+        
+    Returns:
+        Context window size in tokens
+    """
+    # Exact match
+    if model in MODEL_LIMITS:
+        return MODEL_LIMITS[model]
+    
+    # Partial match (e.g., "gpt-4o-2024-05-13" matches "gpt-4o")
+    model_lower = model.lower()
+    for key, limit in MODEL_LIMITS.items():
+        if key in model_lower or model_lower.startswith(key):
+            return limit
+    
+    return MODEL_LIMITS["default"]
+
+
+def get_output_reserve(model: str) -> int:
+    """
+    Get recommended output token reserve for a model.
+    
+    Args:
+        model: Model name
+        
+    Returns:
+        Output reserve in tokens
+    """
+    model_lower = model.lower()
+    
+    for key, reserve in OUTPUT_RESERVES.items():
+        if key in model_lower:
+            return reserve
+    
+    return OUTPUT_RESERVES["default"]
+
+
+class ContextBudgeter:
+    """
+    Allocates token budgets across context segments.
+    
+    Ensures context fits within model limits while reserving
+    space for output generation.
+    
+    Example:
+        budgeter = ContextBudgeter(model="gpt-4o")
+        allocation = budgeter.allocate()
+        print(f"History budget: {allocation.history_budget}")
+    """
+    
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        model_limit: Optional[int] = None,
+        output_reserve: Optional[int] = None,
+        # Segment budget overrides (absolute tokens)
+        system_prompt_budget: int = 2000,
+        rules_budget: int = 500,
+        skills_budget: int = 500,
+        memory_budget: int = 1000,
+        tools_schema_budget: int = 2000,
+        tool_outputs_budget: int = 20000,
+        buffer_budget: int = 1000,
+        # Ratio-based allocation (if set, overrides fixed budgets)
+        history_ratio: Optional[float] = None,
+    ):
+        """
+        Initialize budgeter.
+        
+        Args:
+            model: Model name for limit lookup
+            model_limit: Override model limit
+            output_reserve: Override output reserve
+            system_prompt_budget: Budget for system prompt
+            rules_budget: Budget for rules
+            skills_budget: Budget for skills
+            memory_budget: Budget for memory
+            tools_schema_budget: Budget for tool schemas
+            tool_outputs_budget: Budget for tool outputs
+            buffer_budget: Safety buffer
+            history_ratio: If set, allocate this ratio of usable for history
+        """
+        self.model = model
+        self.model_limit = model_limit or get_model_limit(model)
+        self.output_reserve = output_reserve or get_output_reserve(model)
+        
+        self.system_prompt_budget = system_prompt_budget
+        self.rules_budget = rules_budget
+        self.skills_budget = skills_budget
+        self.memory_budget = memory_budget
+        self.tools_schema_budget = tools_schema_budget
+        self.tool_outputs_budget = tool_outputs_budget
+        self.buffer_budget = buffer_budget
+        self.history_ratio = history_ratio
+    
+    @property
+    def usable(self) -> int:
+        """Usable tokens after output reserve."""
+        return self.model_limit - self.output_reserve
+    
+    def allocate(self) -> BudgetAllocation:
+        """
+        Create a budget allocation.
+        
+        Returns:
+            BudgetAllocation with segment budgets
+        """
+        allocation = BudgetAllocation(
+            model_limit=self.model_limit,
+            output_reserve=self.output_reserve,
+            system_prompt=self.system_prompt_budget,
+            rules=self.rules_budget,
+            skills=self.skills_budget,
+            memory=self.memory_budget,
+            tools_schema=self.tools_schema_budget,
+            tool_outputs=self.tool_outputs_budget,
+            buffer=self.buffer_budget,
+            history=-1,  # Dynamic
+        )
+        
+        # If history_ratio is set, compute history budget from ratio
+        if self.history_ratio is not None:
+            allocation.history = int(self.usable * self.history_ratio)
+        
+        return allocation
+    
+    def check_overflow(
+        self,
+        current_tokens: int,
+        threshold: float = 0.8
+    ) -> bool:
+        """
+        Check if current tokens exceed threshold.
+        
+        Args:
+            current_tokens: Current total tokens
+            threshold: Threshold as fraction of usable (0.0-1.0)
+            
+        Returns:
+            True if overflow threshold exceeded
+        """
+        return current_tokens > (self.usable * threshold)
+    
+    def get_remaining(self, current_tokens: int) -> int:
+        """
+        Get remaining tokens before hitting usable limit.
+        
+        Args:
+            current_tokens: Current total tokens
+            
+        Returns:
+            Remaining tokens (can be negative if over limit)
+        """
+        return self.usable - current_tokens
+    
+    def get_utilization(self, current_tokens: int) -> float:
+        """
+        Get current utilization as fraction.
+        
+        Args:
+            current_tokens: Current total tokens
+            
+        Returns:
+            Utilization (0.0-1.0+)
+        """
+        if self.usable == 0:
+            return 0.0
+        return current_tokens / self.usable
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert budgeter state to dictionary."""
+        return {
+            "model": self.model,
+            "model_limit": self.model_limit,
+            "output_reserve": self.output_reserve,
+            "usable": self.usable,
+            "allocation": self.allocate().to_dict(),
+        }

src/praisonai-agents/praisonaiagents/context/composer.py

@@ -0,0 +1,335 @@
+"""
+Context Composer for PraisonAI Agents.
+
+Assembles context from segments within budget constraints.
+"""
+
+from typing import Dict, List, Any, Optional
+from .models import (
+    ContextLedger, BudgetAllocation, ContextSegment, ContextSnapshot
+)
+from .tokens import estimate_tokens_heuristic, estimate_messages_tokens
+from .ledger import ContextLedgerManager
+
+
+class ContextComposer:
+    """
+    Composes context from segments within budget constraints.
+    
+    Assembles system prompt, rules, skills, memory, tools, and history
+    while respecting token budgets and applying trimming as needed.
+    
+    Example:
+        composer = ContextComposer(budget=budgeter.allocate())
+        
+        result = composer.compose(
+            system_prompt="You are a helpful assistant",
+            history=messages,
+            tools=tool_schemas,
+        )
+        
+        # Use composed messages
+        response = llm.chat(result.messages)
+    """
+    
+    def __init__(
+        self,
+        budget: Optional[BudgetAllocation] = None,
+        preserve_tool_pairs: bool = True,
+        max_tool_output_tokens: int = 10000,
+        keep_recent_turns: int = 5,
+    ):
+        """
+        Initialize composer.
+        
+        Args:
+            budget: Budget allocation (uses defaults if None)
+            preserve_tool_pairs: Keep tool_call/tool_result pairs together
+            max_tool_output_tokens: Max tokens per tool output
+            keep_recent_turns: Minimum recent turns to keep
+        """
+        self.budget = budget or BudgetAllocation()
+        self.preserve_tool_pairs = preserve_tool_pairs
+        self.max_tool_output_tokens = max_tool_output_tokens
+        self.keep_recent_turns = keep_recent_turns
+        
+        self._ledger = ContextLedgerManager()
+        self._ledger.set_budget(self.budget)
+    
+    def compose(
+        self,
+        system_prompt: str = "",
+        rules: str = "",
+        skills: str = "",
+        memory: str = "",
+        tools: Optional[List[Dict[str, Any]]] = None,
+        history: Optional[List[Dict[str, Any]]] = None,
+        agent_id: Optional[str] = None,
+    ) -> "ComposedContext":
+        """
+        Compose context from segments.
+        
+        Args:
+            system_prompt: System prompt content
+            rules: Rules content
+            skills: Skills content
+            memory: Memory content
+            tools: Tool schemas
+            history: Conversation history
+            agent_id: Agent identifier
+            
+        Returns:
+            ComposedContext with messages and ledger
+        """
+        self._ledger.reset()
+        tools = tools or []
+        history = history or []
+        
+        # Track fixed segments
+        self._ledger.track_system_prompt(system_prompt)
+        self._ledger.track_rules(rules)
+        self._ledger.track_skills(skills)
+        self._ledger.track_memory(memory)
+        self._ledger.track_tools(tools)
+        
+        # Build combined system message
+        system_parts = []
+        if system_prompt:
+            system_parts.append(system_prompt)
+        if rules:
+            system_parts.append(f"\n## Rules\n{rules}")
+        if skills:
+            system_parts.append(f"\n## Skills\n{skills}")
+        if memory:
+            system_parts.append(f"\n## Memory\n{memory}")
+        
+        combined_system = "\n".join(system_parts)
+        
+        # Process history with budget awareness
+        processed_history = self._process_history(history)
+        
+        # Build final messages
+        messages = []
+        if combined_system:
+            messages.append({"role": "system", "content": combined_system})
+        messages.extend(processed_history)
+        
+        # Track final history tokens
+        history_tokens = estimate_messages_tokens(processed_history)
+        self._ledger.track_segment(
+            ContextSegment.HISTORY, 
+            history_tokens, 
+            len(processed_history)
+        )
+        
+        # Check for overflow
+        total = self._ledger.get_total()
+        overflow = total > self.budget.usable
+        
+        return ComposedContext(
+            messages=messages,
+            tools=tools,
+            ledger=self._ledger.get_ledger(),
+            total_tokens=total,
+            overflow=overflow,
+            warnings=self._ledger.get_warnings(),
+            agent_id=agent_id,
+        )
+    
+    def _process_history(
+        self,
+        history: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Process history with budget constraints.
+        
+        Applies:
+        - Tool output truncation
+        - Sliding window if over budget
+        - Tool pair preservation
+        """
+        if not history:
+            return []
+        
+        # First pass: truncate large tool outputs
+        processed = []
+        for msg in history:
+            processed_msg = self._truncate_tool_output(msg)
+            processed.append(processed_msg)
+        
+        # Check if within budget
+        history_budget = self.budget.history_budget
+        current_tokens = estimate_messages_tokens(processed)
+        
+        if current_tokens <= history_budget:
+            return processed
+        
+        # Apply sliding window
+        return self._apply_sliding_window(processed, history_budget)
+    
+    def _truncate_tool_output(self, msg: Dict[str, Any]) -> Dict[str, Any]:
+        """Truncate tool output if too large."""
+        if msg.get("role") != "tool" and not msg.get("tool_call_id"):
+            return msg
+        
+        content = msg.get("content", "")
+        if not isinstance(content, str):
+            return msg
+        
+        tokens = estimate_tokens_heuristic(content)
+        if tokens <= self.max_tool_output_tokens:
+            return msg
+        
+        # Truncate to max tokens (rough: 4 chars per token)
+        max_chars = self.max_tool_output_tokens * 4
+        truncated = content[:max_chars] + "\n...[output truncated]..."
+        
+        result = msg.copy()
+        result["content"] = truncated
+        result["_truncated"] = True
+        return result
+    
+    def _apply_sliding_window(
+        self,
+        history: List[Dict[str, Any]],
+        budget: int
+    ) -> List[Dict[str, Any]]:
+        """Apply sliding window to fit within budget."""
+        if not history:
+            return []
+        
+        # Always keep at least recent turns
+        min_keep = self.keep_recent_turns * 2  # user + assistant per turn
+        
+        # Start from end, add messages until budget exceeded
+        result = []
+        current_tokens = 0
+        
+        # Track tool call IDs to preserve pairs
+        tool_call_ids = set()
+        
+        for msg in reversed(history):
+            msg_tokens = estimate_tokens_heuristic(str(msg.get("content", "")))
+            
+            if current_tokens + msg_tokens > budget and len(result) >= min_keep:
+                break
+            
+            result.insert(0, msg)
+            current_tokens += msg_tokens
+            
+            # Track tool calls for pair preservation
+            if self.preserve_tool_pairs:
+                if "tool_calls" in msg:
+                    for tc in msg.get("tool_calls", []):
+                        if isinstance(tc, dict) and "id" in tc:
+                            tool_call_ids.add(tc["id"])
+                if msg.get("tool_call_id"):
+                    tool_call_ids.add(msg["tool_call_id"])
+        
+        # Ensure tool pairs are complete
+        if self.preserve_tool_pairs:
+            result = self._ensure_tool_pairs(result, history, tool_call_ids)
+        
+        return result
+    
+    def _ensure_tool_pairs(
+        self,
+        result: List[Dict[str, Any]],
+        full_history: List[Dict[str, Any]],
+        tool_call_ids: set
+    ) -> List[Dict[str, Any]]:
+        """Ensure tool_call/tool_result pairs are complete."""
+        # Find tool calls in result
+        result_call_ids = set()
+        result_response_ids = set()
+        
+        for msg in result:
+            if "tool_calls" in msg:
+                for tc in msg.get("tool_calls", []):
+                    if isinstance(tc, dict) and "id" in tc:
+                        result_call_ids.add(tc["id"])
+            if msg.get("tool_call_id"):
+                result_response_ids.add(msg["tool_call_id"])
+        
+        # Find missing pairs
+        missing_calls = result_response_ids - result_call_ids
+        missing_responses = result_call_ids - result_response_ids
+        
+        if not missing_calls and not missing_responses:
+            return result
+        
+        # Add missing messages from full history
+        for msg in full_history:
+            # Add missing tool calls
+            if "tool_calls" in msg:
+                for tc in msg.get("tool_calls", []):
+                    if isinstance(tc, dict) and tc.get("id") in missing_calls:
+                        if msg not in result:
+                            result.insert(0, msg)
+                        break
+            
+            # Add missing tool responses
+            if msg.get("tool_call_id") in missing_responses:
+                if msg not in result:
+                    result.append(msg)
+        
+        return result
+    
+    def get_ledger(self) -> ContextLedger:
+        """Get current ledger."""
+        return self._ledger.get_ledger()
+    
+    def get_warnings(self) -> List[str]:
+        """Get current warnings."""
+        return self._ledger.get_warnings()
+
+
+class ComposedContext:
+    """Result of context composition."""
+    
+    def __init__(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        ledger: ContextLedger,
+        total_tokens: int,
+        overflow: bool,
+        warnings: List[str],
+        agent_id: Optional[str] = None,
+    ):
+        self.messages = messages
+        self.tools = tools
+        self.ledger = ledger
+        self.total_tokens = total_tokens
+        self.overflow = overflow
+        self.warnings = warnings
+        self.agent_id = agent_id
+    
+    def to_snapshot(
+        self,
+        session_id: str = "",
+        model_name: str = "",
+        budget: Optional[BudgetAllocation] = None,
+    ) -> ContextSnapshot:
+        """Convert to snapshot for monitoring."""
+        return ContextSnapshot(
+            session_id=session_id,
+            agent_name=self.agent_id or "",
+            model_name=model_name,
+            budget=budget,
+            ledger=self.ledger,
+            utilization=self.total_tokens / budget.usable if budget else 0.0,
+            history_content=self.messages,
+            warnings=self.warnings,
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "message_count": len(self.messages),
+            "tool_count": len(self.tools),
+            "total_tokens": self.total_tokens,
+            "overflow": self.overflow,
+            "warnings": self.warnings,
+            "ledger": self.ledger.to_dict(),
+        }

src/praisonai-agents/praisonaiagents/context/fast/fast_context.py

@@ -2,7 +2,7 @@
 FastContext - High-level API for fast parallel code search.
 
 This module provides the main FastContext class that can be used
-standalone or integrated with the main Agent class.
+standalone or integrated with the main Agent class via context= param.
 
 Example usage:
     # Standalone usage
@@ -12,13 +12,13 @@ Example usage:
     result = fc.search("find authentication handlers")
     print(result.to_context_string())
     
-    # With Agent integration
+    # With Agent integration via context= param
     from praisonaiagents import Agent
+    from praisonaiagents.context import ManagerConfig
     
     agent = Agent(
         name="CodeAssistant",
-        fast_context=True,
-        fast_context_path="/path/to/project"
+        context=True,  # Enable context management
     )
 """
 

src/praisonai-agents/praisonaiagents/context/ledger.py

@@ -0,0 +1,323 @@
+"""
+Context Ledger for PraisonAI Agents.
+
+Tracks token usage across context segments with per-agent and per-session support.
+"""
+
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass
+from .models import ContextLedger, ContextSegment, BudgetAllocation
+from .tokens import estimate_messages_tokens, estimate_tool_schema_tokens
+
+
+@dataclass
+class SegmentStats:
+    """Statistics for a context segment."""
+    tokens: int = 0
+    count: int = 0  # Number of items (messages, tools, etc.)
+    budget: int = 0
+    
+    @property
+    def utilization(self) -> float:
+        """Utilization as fraction of budget."""
+        if self.budget == 0:
+            return 0.0
+        return self.tokens / self.budget
+    
+    @property
+    def over_budget(self) -> bool:
+        """Check if over budget."""
+        return self.tokens > self.budget if self.budget > 0 else False
+
+
+class ContextLedgerManager:
+    """
+    Manages context token accounting.
+    
+    Tracks tokens per segment and provides utilization metrics.
+    Supports multi-agent scenarios with per-agent ledgers.
+    
+    Example:
+        manager = ContextLedgerManager()
+        manager.set_budget(budgeter.allocate())
+        
+        # Track segments
+        manager.track_system_prompt(system_prompt)
+        manager.track_history(messages)
+        manager.track_tools(tool_schemas)
+        
+        # Get stats
+        print(manager.get_utilization())
+        print(manager.get_warnings())
+    """
+    
+    def __init__(self, agent_id: Optional[str] = None):
+        """
+        Initialize ledger manager.
+        
+        Args:
+            agent_id: Optional agent identifier for multi-agent tracking
+        """
+        self.agent_id = agent_id
+        self._ledger = ContextLedger()
+        self._budget: Optional[BudgetAllocation] = None
+        self._segment_details: Dict[str, SegmentStats] = {}
+        
+        # Initialize segment stats
+        for segment in ContextSegment:
+            self._segment_details[segment.value] = SegmentStats()
+    
+    def set_budget(self, budget: BudgetAllocation) -> None:
+        """Set the budget allocation."""
+        self._budget = budget
+        
+        # Update segment budgets
+        for segment in ContextSegment:
+            self._segment_details[segment.value].budget = budget.get_segment_budget(segment)
+    
+    def reset(self) -> None:
+        """Reset all token counts."""
+        self._ledger = ContextLedger()
+        for segment in ContextSegment:
+            stats = self._segment_details[segment.value]
+            stats.tokens = 0
+            stats.count = 0
+    
+    def track_segment(
+        self,
+        segment: ContextSegment,
+        tokens: int,
+        count: int = 1
+    ) -> None:
+        """
+        Track tokens for a segment.
+        
+        Args:
+            segment: Context segment
+            tokens: Token count
+            count: Number of items
+        """
+        self._ledger.set_segment(segment, tokens)
+        stats = self._segment_details[segment.value]
+        stats.tokens = tokens
+        stats.count = count
+    
+    def add_to_segment(
+        self,
+        segment: ContextSegment,
+        tokens: int,
+        count: int = 1
+    ) -> None:
+        """
+        Add tokens to a segment.
+        
+        Args:
+            segment: Context segment
+            tokens: Tokens to add
+            count: Items to add
+        """
+        self._ledger.add_segment(segment, tokens)
+        stats = self._segment_details[segment.value]
+        stats.tokens += tokens
+        stats.count += count
+    
+    def track_system_prompt(self, content: str) -> int:
+        """Track system prompt tokens."""
+        from .tokens import estimate_tokens_heuristic
+        tokens = estimate_tokens_heuristic(content)
+        self.track_segment(ContextSegment.SYSTEM_PROMPT, tokens)
+        return tokens
+    
+    def track_rules(self, content: str) -> int:
+        """Track rules tokens."""
+        from .tokens import estimate_tokens_heuristic
+        tokens = estimate_tokens_heuristic(content)
+        self.track_segment(ContextSegment.RULES, tokens)
+        return tokens
+    
+    def track_skills(self, content: str) -> int:
+        """Track skills tokens."""
+        from .tokens import estimate_tokens_heuristic
+        tokens = estimate_tokens_heuristic(content)
+        self.track_segment(ContextSegment.SKILLS, tokens)
+        return tokens
+    
+    def track_memory(self, content: str) -> int:
+        """Track memory tokens."""
+        from .tokens import estimate_tokens_heuristic
+        tokens = estimate_tokens_heuristic(content)
+        self.track_segment(ContextSegment.MEMORY, tokens)
+        return tokens
+    
+    def track_history(self, messages: List[Dict[str, Any]]) -> int:
+        """
+        Track conversation history tokens.
+        
+        Args:
+            messages: List of message dicts
+            
+        Returns:
+            Total tokens
+        """
+        tokens = estimate_messages_tokens(messages)
+        self.track_segment(ContextSegment.HISTORY, tokens, len(messages))
+        self._ledger.message_count = len(messages)
+        
+        # Count turns (user messages)
+        turns = sum(1 for m in messages if m.get("role") == "user")
+        self._ledger.turn_count = turns
+        
+        return tokens
+    
+    def track_tools(self, tools: List[Dict[str, Any]]) -> int:
+        """
+        Track tool schema tokens.
+        
+        Args:
+            tools: List of tool definitions
+            
+        Returns:
+            Total tokens
+        """
+        tokens = estimate_tool_schema_tokens(tools)
+        self.track_segment(ContextSegment.TOOLS_SCHEMA, tokens, len(tools))
+        return tokens
+    
+    def track_tool_output(self, content: str) -> int:
+        """
+        Add a tool output to tracking.
+        
+        Args:
+            content: Tool output content
+            
+        Returns:
+            Tokens for this output
+        """
+        from .tokens import estimate_tokens_heuristic
+        tokens = estimate_tokens_heuristic(content)
+        self.add_to_segment(ContextSegment.TOOL_OUTPUTS, tokens)
+        self._ledger.tool_call_count += 1
+        return tokens
+    
+    def get_ledger(self) -> ContextLedger:
+        """Get current ledger."""
+        return self._ledger.copy()
+    
+    def get_total(self) -> int:
+        """Get total tokens across all segments."""
+        return self._ledger.total
+    
+    def get_utilization(self) -> float:
+        """Get overall utilization as fraction of usable budget."""
+        if self._budget is None:
+            return 0.0
+        usable = self._budget.usable
+        if usable == 0:
+            return 0.0
+        return self._ledger.total / usable
+    
+    def get_segment_stats(self, segment: ContextSegment) -> SegmentStats:
+        """Get stats for a segment."""
+        return self._segment_details[segment.value]
+    
+    def get_all_stats(self) -> Dict[str, SegmentStats]:
+        """Get stats for all segments."""
+        return self._segment_details.copy()
+    
+    def get_warnings(self, threshold: float = 0.9) -> List[str]:
+        """
+        Get warnings for segments near or over budget.
+        
+        Args:
+            threshold: Warning threshold (0.0-1.0)
+            
+        Returns:
+            List of warning messages
+        """
+        warnings = []
+        
+        for segment in ContextSegment:
+            stats = self._segment_details[segment.value]
+            if stats.budget > 0:
+                if stats.over_budget:
+                    warnings.append(
+                        f"{segment.value}: OVER BUDGET ({stats.tokens:,} / {stats.budget:,} tokens)"
+                    )
+                elif stats.utilization >= threshold:
+                    pct = int(stats.utilization * 100)
+                    warnings.append(
+                        f"{segment.value}: {pct}% of budget ({stats.tokens:,} / {stats.budget:,} tokens)"
+                    )
+        
+        # Overall utilization warning
+        if self._budget:
+            overall_util = self.get_utilization()
+            if overall_util >= threshold:
+                pct = int(overall_util * 100)
+                warnings.insert(0, f"Overall context: {pct}% of usable budget")
+        
+        return warnings
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "agent_id": self.agent_id,
+            "ledger": self._ledger.to_dict(),
+            "total": self._ledger.total,
+            "utilization": self.get_utilization(),
+            "segments": {
+                name: {
+                    "tokens": stats.tokens,
+                    "count": stats.count,
+                    "budget": stats.budget,
+                    "utilization": stats.utilization,
+                }
+                for name, stats in self._segment_details.items()
+            },
+            "warnings": self.get_warnings(),
+        }
+
+
+class MultiAgentLedger:
+    """
+    Manages ledgers for multiple agents.
+    
+    Provides per-agent tracking and combined views.
+    """
+    
+    def __init__(self):
+        """Initialize multi-agent ledger."""
+        self._agents: Dict[str, ContextLedgerManager] = {}
+        self._shared_tokens: int = 0  # Tokens shared across agents
+    
+    def get_agent_ledger(self, agent_id: str) -> ContextLedgerManager:
+        """Get or create ledger for an agent."""
+        if agent_id not in self._agents:
+            self._agents[agent_id] = ContextLedgerManager(agent_id)
+        return self._agents[agent_id]
+    
+    def set_shared_tokens(self, tokens: int) -> None:
+        """Set tokens shared across agents (e.g., team memory)."""
+        self._shared_tokens = tokens
+    
+    def get_combined_total(self) -> int:
+        """Get total tokens across all agents plus shared."""
+        total = self._shared_tokens
+        for ledger in self._agents.values():
+            total += ledger.get_total()
+        return total
+    
+    def get_agent_ids(self) -> List[str]:
+        """Get list of tracked agent IDs."""
+        return list(self._agents.keys())
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "agents": {
+                agent_id: ledger.to_dict()
+                for agent_id, ledger in self._agents.items()
+            },
+            "shared_tokens": self._shared_tokens,
+            "combined_total": self.get_combined_total(),
+        }

src/praisonai-agents/praisonaiagents/context/models.py

@@ -0,0 +1,300 @@
+"""
+Context Management Data Models for PraisonAI Agents.
+
+Provides dataclasses and protocols for context budgeting, composition,
+optimization, and monitoring.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Any, Optional, Literal, Protocol, runtime_checkable
+from enum import Enum
+
+
+class ContextSegment(str, Enum):
+    """Segments that contribute to context."""
+    SYSTEM_PROMPT = "system_prompt"
+    RULES = "rules"
+    SKILLS = "skills"
+    MEMORY = "memory"
+    TOOLS_SCHEMA = "tools_schema"
+    HISTORY = "history"
+    TOOL_OUTPUTS = "tool_outputs"
+    BUFFER = "buffer"
+
+
+@dataclass
+class ContextLedger:
+    """
+    Tracks token usage across context segments.
+    
+    Provides per-segment token counts and total usage.
+    """
+    system_prompt: int = 0
+    rules: int = 0
+    skills: int = 0
+    memory: int = 0
+    tools_schema: int = 0
+    history: int = 0
+    tool_outputs: int = 0
+    buffer: int = 0
+    
+    # Metadata
+    turn_count: int = 0
+    message_count: int = 0
+    tool_call_count: int = 0
+    
+    @property
+    def total(self) -> int:
+        """Total tokens across all segments."""
+        return (
+            self.system_prompt +
+            self.rules +
+            self.skills +
+            self.memory +
+            self.tools_schema +
+            self.history +
+            self.tool_outputs +
+            self.buffer
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+    
+    def get_segment(self, segment: ContextSegment) -> int:
+        """Get token count for a segment."""
+        return getattr(self, segment.value, 0)
+    
+    def set_segment(self, segment: ContextSegment, tokens: int) -> None:
+        """Set token count for a segment."""
+        setattr(self, segment.value, tokens)
+    
+    def add_segment(self, segment: ContextSegment, tokens: int) -> None:
+        """Add tokens to a segment."""
+        current = self.get_segment(segment)
+        self.set_segment(segment, current + tokens)
+    
+    def copy(self) -> "ContextLedger":
+        """Create a copy of this ledger."""
+        return ContextLedger(
+            system_prompt=self.system_prompt,
+            rules=self.rules,
+            skills=self.skills,
+            memory=self.memory,
+            tools_schema=self.tools_schema,
+            history=self.history,
+            tool_outputs=self.tool_outputs,
+            buffer=self.buffer,
+            turn_count=self.turn_count,
+            message_count=self.message_count,
+            tool_call_count=self.tool_call_count,
+        )
+
+
+@dataclass
+class BudgetAllocation:
+    """
+    Token budget allocation across segments.
+    
+    Specifies maximum tokens allowed per segment.
+    """
+    model_limit: int = 128000
+    output_reserve: int = 8000
+    
+    # Segment budgets (absolute tokens or -1 for dynamic)
+    system_prompt: int = 2000
+    rules: int = 500
+    skills: int = 500
+    memory: int = 1000
+    tools_schema: int = 2000
+    history: int = -1  # Dynamic: fills remaining
+    tool_outputs: int = 20000
+    buffer: int = 1000
+    
+    @property
+    def usable(self) -> int:
+        """Usable tokens after output reserve."""
+        return self.model_limit - self.output_reserve
+    
+    @property
+    def fixed_total(self) -> int:
+        """Total of fixed segment budgets."""
+        total = 0
+        for seg in [self.system_prompt, self.rules, self.skills, 
+                    self.memory, self.tools_schema, self.tool_outputs, self.buffer]:
+            if seg > 0:
+                total += seg
+        return total
+    
+    @property
+    def history_budget(self) -> int:
+        """Computed history budget (remainder after fixed segments)."""
+        if self.history > 0:
+            return self.history
+        return max(0, self.usable - self.fixed_total)
+    
+    def get_segment_budget(self, segment: ContextSegment) -> int:
+        """Get budget for a segment."""
+        if segment == ContextSegment.HISTORY:
+            return self.history_budget
+        return getattr(self, segment.value, 0)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        result = asdict(self)
+        result['usable'] = self.usable
+        result['history_budget'] = self.history_budget
+        return result
+
+
+@dataclass
+class ContextSnapshot:
+    """
+    A snapshot of the current context state.
+    
+    Used for monitoring and debugging.
+    """
+    timestamp: str = ""
+    session_id: str = ""
+    agent_name: str = ""
+    model_name: str = ""
+    
+    # Budget info
+    budget: Optional[BudgetAllocation] = None
+    
+    # Token accounting
+    ledger: Optional[ContextLedger] = None
+    
+    # Utilization
+    utilization: float = 0.0
+    
+    # Content segments (for dump)
+    system_prompt_content: str = ""
+    rules_content: str = ""
+    skills_content: str = ""
+    memory_content: str = ""
+    tools_schema_content: str = ""
+    history_content: List[Dict[str, Any]] = field(default_factory=list)
+    
+    # Warnings
+    warnings: List[str] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "timestamp": self.timestamp,
+            "session_id": self.session_id,
+            "agent_name": self.agent_name,
+            "model_name": self.model_name,
+            "budget": self.budget.to_dict() if self.budget else None,
+            "ledger": self.ledger.to_dict() if self.ledger else None,
+            "utilization": self.utilization,
+            "warnings": self.warnings,
+            "history_turn_count": len(self.history_content),
+        }
+
+
+class OptimizerStrategy(str, Enum):
+    """Context optimization strategies."""
+    TRUNCATE = "truncate"
+    SLIDING_WINDOW = "sliding_window"
+    SUMMARIZE = "summarize"
+    PRUNE_TOOLS = "prune_tools"
+    NON_DESTRUCTIVE = "non_destructive"
+    SMART = "smart"
+
+
+@dataclass
+class OptimizationResult:
+    """Result of context optimization."""
+    original_tokens: int = 0
+    optimized_tokens: int = 0
+    tokens_saved: int = 0
+    strategy_used: OptimizerStrategy = OptimizerStrategy.SMART
+    messages_removed: int = 0
+    messages_tagged: int = 0
+    tool_outputs_pruned: int = 0
+    summary_added: bool = False
+    
+    @property
+    def reduction_percent(self) -> float:
+        """Percentage of tokens reduced."""
+        if self.original_tokens == 0:
+            return 0.0
+        return (self.tokens_saved / self.original_tokens) * 100
+
+
+@dataclass
+class MonitorConfig:
+    """Configuration for context monitoring."""
+    enabled: bool = False
+    path: str = "./context.txt"
+    format: Literal["human", "json"] = "human"
+    frequency: Literal["turn", "tool_call", "manual", "overflow"] = "turn"
+    redact_sensitive: bool = True
+    multi_agent_files: bool = True
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+
+
+@dataclass
+class ContextConfig:
+    """
+    Complete context management configuration.
+    
+    Merges settings from CLI flags, env vars, and config files.
+    """
+    # Auto-compaction
+    auto_compact: bool = True
+    compact_threshold: float = 0.8  # Trigger at 80% of usable budget
+    strategy: OptimizerStrategy = OptimizerStrategy.SMART
+    
+    # Budget overrides
+    output_reserve: int = 8000
+    history_ratio: float = 0.6  # 60% of usable for history
+    tool_output_max: int = 10000  # Max tokens per tool output
+    
+    # Pruning
+    prune_after_tokens: int = 40000
+    protected_tools: List[str] = field(default_factory=list)
+    
+    # Monitoring
+    monitor: MonitorConfig = field(default_factory=MonitorConfig)
+    
+    # Sliding window
+    keep_recent_turns: int = 5
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        result = asdict(self)
+        result['strategy'] = self.strategy.value
+        return result
+
+
+@runtime_checkable
+class TokenEstimator(Protocol):
+    """Protocol for token estimation."""
+    
+    def estimate(self, text: str) -> int:
+        """Estimate tokens for text."""
+        ...
+    
+    def estimate_messages(self, messages: List[Dict[str, Any]]) -> int:
+        """Estimate tokens for a list of messages."""
+        ...
+
+
+@runtime_checkable
+class ContextOptimizer(Protocol):
+    """Protocol for context optimization strategies."""
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: ContextLedger,
+    ) -> tuple[List[Dict[str, Any]], OptimizationResult]:
+        """Optimize messages to fit within target tokens."""
+        ...

src/praisonai-agents/praisonaiagents/context/monitor.py

@@ -0,0 +1,641 @@
+"""
+Context Monitor for PraisonAI Agents.
+
+Writes runtime context to disk for inspection and debugging.
+"""
+
+from typing import Dict, List, Any, Optional, Literal, Tuple
+from pathlib import Path
+from datetime import datetime
+import json
+import re
+
+from .models import (
+    ContextSnapshot, ContextLedger, BudgetAllocation, MonitorConfig, ContextSegment
+)
+
+
+# Sensitive patterns for redaction
+SENSITIVE_PATTERNS = [
+    # OpenAI API keys
+    r'sk-[a-zA-Z0-9]{20,}',
+    r'sk-proj-[a-zA-Z0-9_-]+',
+    # Anthropic API keys
+    r'sk-ant-[a-zA-Z0-9_-]+',
+    r'sk-ant-api\d+-[a-zA-Z0-9_-]+',
+    # Google API keys and tokens
+    r'AIza[a-zA-Z0-9_-]{30,}',  # Google API keys (30+ chars after prefix)
+    r'ya29\.[a-zA-Z0-9_-]+',  # Google OAuth tokens
+    r'goog-[a-zA-Z0-9_-]{20,}',  # Google service tokens
+    # AWS credentials
+    r'AKIA[0-9A-Z]{16}',  # AWS access keys
+    r'ASIA[0-9A-Z]{16}',  # AWS temporary access keys
+    r'aws_secret_access_key["\s:=]+["\']?[^"\'\s]+',
+    # Azure credentials
+    r'[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}',  # Azure GUIDs
+    # Generic patterns
+    r'[a-zA-Z0-9]{40,}',  # Generic long tokens (conservative)
+    r'password["\s:=]+["\']?[^"\'\s]+',  # Password patterns
+    r'secret["\s:=]+["\']?[^"\'\s]+',  # Secret patterns
+    r'token["\s:=]+["\']?[^"\'\s]+',  # Token patterns
+    r'api[_-]?key["\s:=]+["\']?[^"\'\s]+',  # API key patterns
+    r'bearer\s+[a-zA-Z0-9_-]+',  # Bearer tokens
+    r'authorization["\s:=]+["\']?[^"\'\s]+',  # Authorization headers
+]
+
+
+def redact_sensitive(text: str) -> str:
+    """
+    Redact sensitive information from text.
+    
+    Args:
+        text: Text to redact
+        
+    Returns:
+        Redacted text
+    """
+    result = text
+    for pattern in SENSITIVE_PATTERNS:
+        result = re.sub(pattern, '[REDACTED]', result, flags=re.IGNORECASE)
+    return result
+
+
+def validate_monitor_path(
+    path: str,
+    allow_absolute: bool = False,
+    base_dir: Optional[str] = None,
+) -> Tuple[bool, str]:
+    """
+    Validate monitor output path for security.
+    
+    Prevents path traversal attacks and enforces path restrictions.
+    
+    Args:
+        path: Path to validate
+        allow_absolute: Whether to allow absolute paths
+        base_dir: Base directory for relative paths
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    from pathlib import Path as PathLib
+    
+    path_obj = PathLib(path)
+    
+    # Check for path traversal attempts
+    if '..' in path_obj.parts:
+        return False, "Path traversal (..) not allowed"
+    
+    # Check absolute path restriction
+    if path_obj.is_absolute() and not allow_absolute:
+        return False, "Absolute paths not allowed (set allow_absolute_paths=True to override)"
+    
+    # If base_dir specified, ensure path stays within it
+    if base_dir:
+        base = PathLib(base_dir).resolve()
+        try:
+            # For relative paths, resolve against base
+            if not path_obj.is_absolute():
+                full_path = (base / path_obj).resolve()
+            else:
+                full_path = path_obj.resolve()
+            
+            # Check if resolved path is under base
+            if not str(full_path).startswith(str(base)):
+                return False, f"Path must be within {base_dir}"
+        except Exception as e:
+            return False, f"Path validation error: {e}"
+    
+    # Check for suspicious patterns
+    suspicious = ['/etc/', '/var/', '/usr/', '/root/', '/home/', '~']
+    path_str = str(path_obj).lower()
+    for pattern in suspicious:
+        if pattern in path_str and not allow_absolute:
+            return False, f"Suspicious path pattern: {pattern}"
+    
+    return True, ""
+
+
+def should_include_content(
+    file_path: str,
+    ignore_patterns: Optional[List[str]] = None,
+    include_patterns: Optional[List[str]] = None,
+) -> bool:
+    """
+    Check if file content should be included based on ignore/include patterns.
+    
+    Respects .praisonignore and .praisoninclude rules.
+    
+    Args:
+        file_path: Path to check
+        ignore_patterns: Patterns to ignore (glob-style)
+        include_patterns: Patterns to include (glob-style)
+        
+    Returns:
+        True if content should be included
+    """
+    import fnmatch
+    from pathlib import Path as PathLib
+    
+    path = PathLib(file_path)
+    name = path.name
+    
+    # Default: include everything
+    if not ignore_patterns and not include_patterns:
+        return True
+    
+    # Check include patterns first (whitelist)
+    if include_patterns:
+        included = False
+        for pattern in include_patterns:
+            if fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(str(path), pattern):
+                included = True
+                break
+        if not included:
+            return False
+    
+    # Check ignore patterns (blacklist)
+    if ignore_patterns:
+        for pattern in ignore_patterns:
+            if fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(str(path), pattern):
+                return False
+    
+    return True
+
+
+def load_ignore_patterns(base_dir: str = ".") -> Tuple[List[str], List[str]]:
+    """
+    Load ignore and include patterns from .praisonignore and .praisoninclude files.
+    
+    Args:
+        base_dir: Directory to search for pattern files
+        
+    Returns:
+        Tuple of (ignore_patterns, include_patterns)
+    """
+    from pathlib import Path as PathLib
+    
+    ignore_patterns = []
+    include_patterns = []
+    
+    base = PathLib(base_dir)
+    
+    # Load .praisonignore
+    ignore_file = base / ".praisonignore"
+    if ignore_file.exists():
+        try:
+            content = ignore_file.read_text()
+            for line in content.splitlines():
+                line = line.strip()
+                if line and not line.startswith('#'):
+                    ignore_patterns.append(line)
+        except Exception:
+            pass
+    
+    # Load .praisoninclude
+    include_file = base / ".praisoninclude"
+    if include_file.exists():
+        try:
+            content = include_file.read_text()
+            for line in content.splitlines():
+                line = line.strip()
+                if line and not line.startswith('#'):
+                    include_patterns.append(line)
+        except Exception:
+            pass
+    
+    return ignore_patterns, include_patterns
+
+
+def format_human_snapshot(snapshot: ContextSnapshot, redact: bool = True) -> str:
+    """
+    Format snapshot as human-readable text.
+    
+    Args:
+        snapshot: Context snapshot
+        redact: Whether to redact sensitive info
+        
+    Returns:
+        Formatted text
+    """
+    lines = []
+    
+    # Header
+    lines.append("=" * 80)
+    lines.append("PRAISONAI CONTEXT SNAPSHOT")
+    lines.append("=" * 80)
+    lines.append(f"Timestamp: {snapshot.timestamp}")
+    lines.append(f"Session ID: {snapshot.session_id}")
+    lines.append(f"Agent: {snapshot.agent_name}")
+    lines.append(f"Model: {snapshot.model_name}")
+    
+    if snapshot.budget:
+        lines.append(f"Model Limit: {snapshot.budget.model_limit:,} tokens")
+        lines.append(f"Output Reserve: {snapshot.budget.output_reserve:,} tokens")
+        lines.append(f"Usable Budget: {snapshot.budget.usable:,} tokens")
+    
+    lines.append("")
+    
+    # Token Ledger
+    lines.append("-" * 80)
+    lines.append("TOKEN LEDGER")
+    lines.append("-" * 80)
+    lines.append(f"{'Component':<20} | {'Tokens':>10} | {'Budget':>10} | {'% Used':>8}")
+    lines.append("-" * 20 + "-+-" + "-" * 10 + "-+-" + "-" * 10 + "-+-" + "-" * 8)
+    
+    if snapshot.ledger and snapshot.budget:
+        segments = [
+            (ContextSegment.SYSTEM_PROMPT, "System Prompt"),
+            (ContextSegment.RULES, "Rules"),
+            (ContextSegment.SKILLS, "Skills"),
+            (ContextSegment.MEMORY, "Memory"),
+            (ContextSegment.TOOLS_SCHEMA, "Tool Schemas"),
+            (ContextSegment.HISTORY, "History"),
+            (ContextSegment.TOOL_OUTPUTS, "Tool Outputs"),
+        ]
+        
+        for seg, name in segments:
+            tokens = snapshot.ledger.get_segment(seg)
+            budget = snapshot.budget.get_segment_budget(seg)
+            pct = (tokens / budget * 100) if budget > 0 else 0
+            lines.append(f"{name:<20} | {tokens:>10,} | {budget:>10,} | {pct:>7.1f}%")
+        
+        lines.append("-" * 20 + "-+-" + "-" * 10 + "-+-" + "-" * 10 + "-+-" + "-" * 8)
+        lines.append(f"{'TOTAL':<20} | {snapshot.ledger.total:>10,} | {snapshot.budget.usable:>10,} | {snapshot.utilization * 100:>7.1f}%")
+    
+    lines.append("")
+    
+    # Warnings
+    if snapshot.warnings:
+        lines.append("-" * 80)
+        lines.append("WARNINGS")
+        lines.append("-" * 80)
+        for warning in snapshot.warnings:
+            lines.append(f"⚠ {warning}")
+        lines.append("")
+    
+    # History summary
+    if snapshot.history_content:
+        lines.append("-" * 80)
+        lines.append(f"CONVERSATION HISTORY ({len(snapshot.history_content)} messages)")
+        lines.append("-" * 80)
+        
+        for i, msg in enumerate(snapshot.history_content):
+            role = msg.get("role", "unknown").upper()
+            content = msg.get("content", "")
+            
+            if isinstance(content, str):
+                if redact:
+                    content = redact_sensitive(content)
+                # Truncate for display
+                if len(content) > 200:
+                    content = content[:200] + "..."
+                lines.append(f"[{i+1}] {role}: {content}")
+            else:
+                lines.append(f"[{i+1}] {role}: [complex content]")
+        
+        lines.append("")
+    
+    # Footer
+    lines.append("=" * 80)
+    lines.append("END CONTEXT SNAPSHOT")
+    lines.append("=" * 80)
+    
+    return "\n".join(lines)
+
+
+def format_json_snapshot(snapshot: ContextSnapshot, redact: bool = True) -> str:
+    """
+    Format snapshot as JSON.
+    
+    Args:
+        snapshot: Context snapshot
+        redact: Whether to redact sensitive info
+        
+    Returns:
+        JSON string
+    """
+    data = snapshot.to_dict()
+    
+    # Add history with optional redaction
+    if snapshot.history_content:
+        history = []
+        for msg in snapshot.history_content:
+            msg_copy = msg.copy()
+            content = msg_copy.get("content", "")
+            if isinstance(content, str) and redact:
+                msg_copy["content"] = redact_sensitive(content)
+            history.append(msg_copy)
+        data["history"] = history
+    
+    return json.dumps(data, indent=2, default=str)
+
+
+class ContextMonitor:
+    """
+    Monitors and writes context to disk.
+    
+    Provides real-time visibility into context state for debugging
+    and optimization.
+    
+    Example:
+        monitor = ContextMonitor(
+            enabled=True,
+            path="./context.txt",
+            format="human",
+        )
+        
+        # Write snapshot
+        monitor.snapshot(
+            ledger=ledger,
+            budget=budget,
+            messages=messages,
+            agent_name="Assistant",
+        )
+    """
+    
+    def __init__(
+        self,
+        enabled: bool = False,
+        path: str = "./context.txt",
+        format: Literal["human", "json"] = "human",
+        frequency: Literal["turn", "tool_call", "manual", "overflow"] = "turn",
+        redact_sensitive: bool = True,
+        multi_agent_files: bool = True,
+    ):
+        """
+        Initialize monitor.
+        
+        Args:
+            enabled: Whether monitoring is enabled
+            path: Output file path
+            format: Output format (human or json)
+            frequency: Update frequency
+            redact_sensitive: Redact sensitive info
+            multi_agent_files: Create per-agent files
+        """
+        self.enabled = enabled
+        self.path = Path(path)
+        self.format = format
+        self.frequency = frequency
+        self.redact = redact_sensitive
+        self.multi_agent_files = multi_agent_files
+        
+        self._last_snapshot: Optional[ContextSnapshot] = None
+        self._turn_count = 0
+        self._tool_call_count = 0
+    
+    @classmethod
+    def from_config(cls, config: MonitorConfig) -> "ContextMonitor":
+        """Create monitor from config."""
+        return cls(
+            enabled=config.enabled,
+            path=config.path,
+            format=config.format,
+            frequency=config.frequency,
+            redact_sensitive=config.redact_sensitive,
+            multi_agent_files=config.multi_agent_files,
+        )
+    
+    def enable(self) -> None:
+        """Enable monitoring."""
+        self.enabled = True
+    
+    def disable(self) -> None:
+        """Disable monitoring."""
+        self.enabled = False
+    
+    def set_path(self, path: str) -> None:
+        """Set output path."""
+        self.path = Path(path)
+    
+    def set_format(self, format: Literal["human", "json"]) -> None:
+        """Set output format."""
+        self.format = format
+    
+    def set_frequency(self, frequency: Literal["turn", "tool_call", "manual", "overflow"]) -> None:
+        """Set update frequency."""
+        self.frequency = frequency
+    
+    def should_write(
+        self,
+        trigger: Literal["turn", "tool_call", "manual", "overflow"]
+    ) -> bool:
+        """Check if should write based on frequency."""
+        if not self.enabled:
+            return False
+        
+        if trigger == "manual":
+            return True
+        
+        if self.frequency == "manual":
+            return trigger == "manual"
+        
+        if self.frequency == "overflow":
+            return trigger == "overflow"
+        
+        if self.frequency == "tool_call":
+            return trigger in ("tool_call", "overflow")
+        
+        # frequency == "turn"
+        return trigger in ("turn", "overflow")
+    
+    def snapshot(
+        self,
+        ledger: ContextLedger,
+        budget: BudgetAllocation,
+        messages: List[Dict[str, Any]],
+        session_id: str = "",
+        agent_name: str = "",
+        model_name: str = "",
+        trigger: Literal["turn", "tool_call", "manual", "overflow"] = "turn",
+    ) -> Optional[str]:
+        """
+        Create and write a context snapshot.
+        
+        Args:
+            ledger: Current token ledger
+            budget: Budget allocation
+            messages: Current messages
+            session_id: Session identifier
+            agent_name: Agent name
+            model_name: Model name
+            trigger: What triggered this snapshot
+            
+        Returns:
+            Path to written file, or None if not written
+        """
+        if not self.should_write(trigger):
+            return None
+        
+        # Track counts
+        if trigger == "turn":
+            self._turn_count += 1
+        elif trigger == "tool_call":
+            self._tool_call_count += 1
+        
+        # Create snapshot
+        snapshot = ContextSnapshot(
+            timestamp=datetime.utcnow().isoformat() + "Z",
+            session_id=session_id,
+            agent_name=agent_name,
+            model_name=model_name,
+            budget=budget,
+            ledger=ledger,
+            utilization=ledger.total / budget.usable if budget.usable > 0 else 0,
+            history_content=messages,
+            warnings=self._get_warnings(ledger, budget),
+        )
+        
+        self._last_snapshot = snapshot
+        
+        # Determine output path
+        output_path = self._get_output_path(agent_name)
+        
+        # Format content
+        if self.format == "json":
+            content = format_json_snapshot(snapshot, self.redact)
+        else:
+            content = format_human_snapshot(snapshot, self.redact)
+        
+        # Atomic write
+        self._atomic_write(output_path, content)
+        
+        return str(output_path)
+    
+    def _get_output_path(self, agent_name: str = "") -> Path:
+        """Get output path, optionally per-agent."""
+        if not self.multi_agent_files or not agent_name:
+            return self.path
+        
+        # Create per-agent path
+        stem = self.path.stem
+        suffix = self.path.suffix or (".json" if self.format == "json" else ".txt")
+        
+        # Sanitize agent name
+        safe_name = re.sub(r'[^\w\-]', '_', agent_name.lower())
+        
+        return self.path.parent / f"{stem}_{safe_name}{suffix}"
+    
+    def _get_warnings(
+        self,
+        ledger: ContextLedger,
+        budget: BudgetAllocation
+    ) -> List[str]:
+        """Generate warnings based on current state."""
+        warnings = []
+        
+        utilization = ledger.total / budget.usable if budget.usable > 0 else 0
+        
+        if utilization >= 1.0:
+            warnings.append(f"CRITICAL: Context overflow! {utilization*100:.1f}% of usable budget")
+        elif utilization >= 0.9:
+            warnings.append(f"WARNING: Context at {utilization*100:.1f}% of usable budget")
+        elif utilization >= 0.8:
+            warnings.append(f"NOTICE: Context at {utilization*100:.1f}% of usable budget")
+        
+        # Check individual segments
+        if budget.tool_outputs > 0:
+            tool_util = ledger.tool_outputs / budget.tool_outputs
+            if tool_util >= 0.9:
+                warnings.append(f"Tool outputs at {tool_util*100:.1f}% of budget")
+        
+        return warnings
+    
+    def _atomic_write(self, path: Path, content: str) -> None:
+        """Write content atomically using temp file + rename."""
+        # Ensure parent directory exists
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Write to temp file
+        temp_path = path.with_suffix(path.suffix + ".tmp")
+        
+        try:
+            temp_path.write_text(content, encoding="utf-8")
+            # Atomic rename
+            temp_path.rename(path)
+        except Exception:
+            # Clean up temp file on error
+            if temp_path.exists():
+                temp_path.unlink()
+            raise
+    
+    def get_last_snapshot(self) -> Optional[ContextSnapshot]:
+        """Get the last snapshot."""
+        return self._last_snapshot
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get monitor statistics."""
+        return {
+            "enabled": self.enabled,
+            "path": str(self.path),
+            "format": self.format,
+            "frequency": self.frequency,
+            "turn_count": self._turn_count,
+            "tool_call_count": self._tool_call_count,
+            "last_snapshot": self._last_snapshot.timestamp if self._last_snapshot else None,
+        }
+
+
+class MultiAgentMonitor:
+    """
+    Manages monitors for multiple agents.
+    
+    Creates per-agent monitors and optional combined view.
+    """
+    
+    def __init__(
+        self,
+        base_path: str = "./context",
+        format: Literal["human", "json"] = "human",
+        enabled: bool = False,
+        redact_sensitive: bool = True,
+    ):
+        """
+        Initialize multi-agent monitor.
+        
+        Args:
+            base_path: Base path for output files
+            format: Output format
+            enabled: Whether monitoring is enabled
+            redact_sensitive: Redact sensitive info
+        """
+        self.base_path = Path(base_path)
+        self.format = format
+        self.enabled = enabled
+        self.redact = redact_sensitive
+        
+        self._agents: Dict[str, ContextMonitor] = {}
+    
+    def get_agent_monitor(self, agent_id: str) -> ContextMonitor:
+        """Get or create monitor for an agent."""
+        if agent_id not in self._agents:
+            suffix = ".json" if self.format == "json" else ".txt"
+            safe_id = re.sub(r'[^\w\-]', '_', agent_id.lower())
+            path = self.base_path / f"context_{safe_id}{suffix}"
+            
+            self._agents[agent_id] = ContextMonitor(
+                enabled=self.enabled,
+                path=str(path),
+                format=self.format,
+                redact_sensitive=self.redact,
+                multi_agent_files=False,  # Already per-agent
+            )
+        
+        return self._agents[agent_id]
+    
+    def enable_all(self) -> None:
+        """Enable all monitors."""
+        self.enabled = True
+        for monitor in self._agents.values():
+            monitor.enable()
+    
+    def disable_all(self) -> None:
+        """Disable all monitors."""
+        self.enabled = False
+        for monitor in self._agents.values():
+            monitor.disable()
+    
+    def get_agent_ids(self) -> List[str]:
+        """Get list of monitored agent IDs."""
+        return list(self._agents.keys())

src/praisonai-agents/praisonaiagents/context/optimizer.py

@@ -0,0 +1,484 @@
+"""
+Context Optimizer for PraisonAI Agents.
+
+Provides strategies for reducing context size when approaching limits.
+"""
+
+from typing import Dict, List, Any, Optional
+from abc import ABC, abstractmethod
+from .models import ContextLedger, OptimizerStrategy, OptimizationResult
+from .tokens import estimate_messages_tokens
+
+
+class BaseOptimizer(ABC):
+    """Base class for optimization strategies."""
+    
+    @abstractmethod
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        """
+        Optimize messages to fit within target tokens.
+        
+        Args:
+            messages: Messages to optimize
+            target_tokens: Target token count
+            ledger: Current token ledger
+            
+        Returns:
+            Tuple of (optimized_messages, OptimizationResult)
+        """
+        pass
+
+
+class TruncateOptimizer(BaseOptimizer):
+    """Truncate oldest messages strategy."""
+    
+    def __init__(self, preserve_system: bool = True, preserve_recent: int = 5):
+        self.preserve_system = preserve_system
+        self.preserve_recent = preserve_recent
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        original_tokens = estimate_messages_tokens(messages)
+        
+        if original_tokens <= target_tokens:
+            return messages, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=original_tokens,
+                tokens_saved=0,
+                strategy_used=OptimizerStrategy.TRUNCATE,
+            )
+        
+        # Separate system and other messages
+        system_msgs = []
+        other_msgs = []
+        
+        for msg in messages:
+            if self.preserve_system and msg.get("role") == "system":
+                system_msgs.append(msg)
+            else:
+                other_msgs.append(msg)
+        
+        # Keep recent messages
+        recent = other_msgs[-self.preserve_recent:] if other_msgs else []
+        
+        result = system_msgs + recent
+        
+        # Continue removing until under target
+        while estimate_messages_tokens(result) > target_tokens and len(result) > 1:
+            for i, msg in enumerate(result):
+                if msg.get("role") != "system":
+                    result.pop(i)
+                    break
+        
+        optimized_tokens = estimate_messages_tokens(result)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.TRUNCATE,
+            messages_removed=len(messages) - len(result),
+        )
+
+
+class SlidingWindowOptimizer(BaseOptimizer):
+    """Keep a sliding window of recent messages."""
+    
+    def __init__(self, preserve_system: bool = True):
+        self.preserve_system = preserve_system
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        original_tokens = estimate_messages_tokens(messages)
+        
+        if original_tokens <= target_tokens:
+            return messages, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=original_tokens,
+                tokens_saved=0,
+                strategy_used=OptimizerStrategy.SLIDING_WINDOW,
+            )
+        
+        result = []
+        
+        # Keep system messages
+        for msg in messages:
+            if self.preserve_system and msg.get("role") == "system":
+                result.append(msg)
+        
+        # Add messages from end until target reached
+        non_system = [m for m in messages if m.get("role") != "system"]
+        
+        for msg in reversed(non_system):
+            test_result = result + [msg]
+            if estimate_messages_tokens(test_result) <= target_tokens:
+                result.insert(len([m for m in result if m.get("role") == "system"]), msg)
+            else:
+                break
+        
+        # Ensure order
+        system_msgs = [m for m in result if m.get("role") == "system"]
+        other_msgs = [m for m in result if m.get("role") != "system"]
+        result = system_msgs + other_msgs
+        
+        optimized_tokens = estimate_messages_tokens(result)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.SLIDING_WINDOW,
+            messages_removed=len(messages) - len(result),
+        )
+
+
+class PruneToolsOptimizer(BaseOptimizer):
+    """Prune old tool outputs while keeping tool calls."""
+    
+    def __init__(
+        self,
+        preserve_recent: int = 5,
+        max_output_chars: int = 500,
+        protected_tools: Optional[List[str]] = None,
+    ):
+        self.preserve_recent = preserve_recent
+        self.max_output_chars = max_output_chars
+        self.protected_tools = protected_tools or []
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        original_tokens = estimate_messages_tokens(messages)
+        
+        result = []
+        pruned_count = 0
+        
+        # Separate system and other messages
+        system_msgs = [m for m in messages if m.get("role") == "system"]
+        other_msgs = [m for m in messages if m.get("role") != "system"]
+        
+        result.extend(system_msgs)
+        
+        # Keep recent messages intact
+        recent = other_msgs[-self.preserve_recent:]
+        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        
+        # Prune older tool outputs
+        for msg in older:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            
+            # Check if this is a tool result
+            if role == "tool" or msg.get("tool_call_id"):
+                # Check if protected
+                tool_name = msg.get("name", "")
+                if tool_name in self.protected_tools:
+                    result.append(msg)
+                    continue
+                
+                # Truncate if too long
+                if isinstance(content, str) and len(content) > self.max_output_chars:
+                    pruned_msg = msg.copy()
+                    pruned_msg["content"] = content[:self.max_output_chars] + "\n...[output truncated]..."
+                    pruned_msg["_pruned"] = True
+                    result.append(pruned_msg)
+                    pruned_count += 1
+                else:
+                    result.append(msg)
+            else:
+                result.append(msg)
+        
+        result.extend(recent)
+        
+        optimized_tokens = estimate_messages_tokens(result)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.PRUNE_TOOLS,
+            tool_outputs_pruned=pruned_count,
+        )
+
+
+class NonDestructiveOptimizer(BaseOptimizer):
+    """
+    Tag messages for exclusion without deleting them.
+    
+    Messages are tagged with _condense_parent and excluded from
+    effective history, but can be restored on rewind.
+    """
+    
+    def __init__(self, preserve_recent: int = 3):
+        self.preserve_recent = preserve_recent
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        import uuid
+        
+        original_tokens = estimate_messages_tokens(messages)
+        
+        if original_tokens <= target_tokens:
+            return messages, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=original_tokens,
+                tokens_saved=0,
+                strategy_used=OptimizerStrategy.NON_DESTRUCTIVE,
+            )
+        
+        condense_id = str(uuid.uuid4())
+        
+        # Separate system and other messages
+        system_msgs = [m for m in messages if m.get("role") == "system"]
+        other_msgs = [m for m in messages if m.get("role") != "system"]
+        
+        # Keep recent, tag older
+        keep_start = max(0, len(other_msgs) - self.preserve_recent)
+        
+        result = []
+        tagged_count = 0
+        
+        # Add system messages
+        result.extend(system_msgs)
+        
+        # Tag older messages
+        for i, msg in enumerate(other_msgs):
+            if i < keep_start:
+                tagged_msg = msg.copy()
+                if "_condense_parent" not in tagged_msg:
+                    tagged_msg["_condense_parent"] = condense_id
+                    tagged_count += 1
+                result.append(tagged_msg)
+            else:
+                result.append(msg)
+        
+        # Calculate effective tokens (excluding tagged)
+        effective_msgs = [m for m in result if "_condense_parent" not in m]
+        optimized_tokens = estimate_messages_tokens(effective_msgs)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.NON_DESTRUCTIVE,
+            messages_tagged=tagged_count,
+        )
+
+
+class SummarizeOptimizer(BaseOptimizer):
+    """
+    Summarize older messages using LLM.
+    
+    Note: This is a placeholder that creates a structured summary.
+    Actual LLM summarization should be done at the agent level.
+    """
+    
+    def __init__(self, preserve_recent: int = 5, max_summary_items: int = 10):
+        self.preserve_recent = preserve_recent
+        self.max_summary_items = max_summary_items
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        original_tokens = estimate_messages_tokens(messages)
+        
+        if original_tokens <= target_tokens:
+            return messages, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=original_tokens,
+                tokens_saved=0,
+                strategy_used=OptimizerStrategy.SUMMARIZE,
+            )
+        
+        # Separate system and other messages
+        system_msgs = [m for m in messages if m.get("role") == "system"]
+        other_msgs = [m for m in messages if m.get("role") != "system"]
+        
+        result = list(system_msgs)
+        
+        # Keep recent messages
+        recent = other_msgs[-self.preserve_recent:]
+        older = other_msgs[:-self.preserve_recent] if len(other_msgs) > self.preserve_recent else []
+        
+        if older:
+            # Create summary
+            summary_parts = []
+            for msg in older[:self.max_summary_items]:
+                role = msg.get("role", "unknown")
+                content = msg.get("content", "")
+                if isinstance(content, str) and content:
+                    summary_parts.append(f"[{role}]: {content[:150]}...")
+            
+            if summary_parts:
+                summary = (
+                    "[Previous conversation summary]\n"
+                    + "\n".join(summary_parts)
+                )
+                result.append({
+                    "role": "system",
+                    "content": summary,
+                    "_summary": True,
+                    "_original_count": len(older),
+                })
+        
+        result.extend(recent)
+        
+        optimized_tokens = estimate_messages_tokens(result)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.SUMMARIZE,
+            messages_removed=len(older),
+            summary_added=bool(older),
+        )
+
+
+class SmartOptimizer(BaseOptimizer):
+    """
+    Smart optimization combining multiple strategies.
+    
+    Applies strategies in order:
+    1. Prune tool outputs
+    2. Sliding window
+    3. Summarize if still over
+    """
+    
+    def __init__(
+        self,
+        preserve_recent: int = 5,
+        protected_tools: Optional[List[str]] = None,
+    ):
+        self.preserve_recent = preserve_recent
+        self.protected_tools = protected_tools or []
+        
+        self._prune = PruneToolsOptimizer(
+            preserve_recent=preserve_recent,
+            protected_tools=protected_tools,
+        )
+        self._window = SlidingWindowOptimizer()
+        self._summarize = SummarizeOptimizer(preserve_recent=preserve_recent)
+    
+    def optimize(
+        self,
+        messages: List[Dict[str, Any]],
+        target_tokens: int,
+        ledger: Optional[ContextLedger] = None,
+    ) -> tuple:
+        original_tokens = estimate_messages_tokens(messages)
+        
+        if original_tokens <= target_tokens:
+            return messages, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=original_tokens,
+                tokens_saved=0,
+                strategy_used=OptimizerStrategy.SMART,
+            )
+        
+        # Step 1: Prune tool outputs
+        result, prune_result = self._prune.optimize(messages, target_tokens, ledger)
+        
+        if estimate_messages_tokens(result) <= target_tokens:
+            return result, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=prune_result.optimized_tokens,
+                tokens_saved=original_tokens - prune_result.optimized_tokens,
+                strategy_used=OptimizerStrategy.SMART,
+                tool_outputs_pruned=prune_result.tool_outputs_pruned,
+            )
+        
+        # Step 2: Sliding window
+        result, window_result = self._window.optimize(result, target_tokens, ledger)
+        
+        if estimate_messages_tokens(result) <= target_tokens:
+            return result, OptimizationResult(
+                original_tokens=original_tokens,
+                optimized_tokens=window_result.optimized_tokens,
+                tokens_saved=original_tokens - window_result.optimized_tokens,
+                strategy_used=OptimizerStrategy.SMART,
+                tool_outputs_pruned=prune_result.tool_outputs_pruned,
+                messages_removed=window_result.messages_removed,
+            )
+        
+        # Step 3: Summarize
+        result, summary_result = self._summarize.optimize(result, target_tokens, ledger)
+        
+        optimized_tokens = estimate_messages_tokens(result)
+        
+        return result, OptimizationResult(
+            original_tokens=original_tokens,
+            optimized_tokens=optimized_tokens,
+            tokens_saved=original_tokens - optimized_tokens,
+            strategy_used=OptimizerStrategy.SMART,
+            tool_outputs_pruned=prune_result.tool_outputs_pruned,
+            messages_removed=window_result.messages_removed + summary_result.messages_removed,
+            summary_added=summary_result.summary_added,
+        )
+
+
+# Strategy registry
+OPTIMIZER_REGISTRY: Dict[OptimizerStrategy, type] = {
+    OptimizerStrategy.TRUNCATE: TruncateOptimizer,
+    OptimizerStrategy.SLIDING_WINDOW: SlidingWindowOptimizer,
+    OptimizerStrategy.PRUNE_TOOLS: PruneToolsOptimizer,
+    OptimizerStrategy.NON_DESTRUCTIVE: NonDestructiveOptimizer,
+    OptimizerStrategy.SUMMARIZE: SummarizeOptimizer,
+    OptimizerStrategy.SMART: SmartOptimizer,
+}
+
+
+def get_optimizer(
+    strategy: OptimizerStrategy,
+    **kwargs
+) -> BaseOptimizer:
+    """
+    Get an optimizer instance for a strategy.
+    
+    Args:
+        strategy: Optimization strategy
+        **kwargs: Strategy-specific arguments
+        
+    Returns:
+        Optimizer instance
+    """
+    optimizer_class = OPTIMIZER_REGISTRY.get(strategy, SmartOptimizer)
+    return optimizer_class(**kwargs)
+
+
+def get_effective_history(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Get effective history excluding tagged messages.
+    
+    Filters out messages with _condense_parent tags.
+    
+    Args:
+        messages: Full message history
+        
+    Returns:
+        Effective messages for API calls
+    """
+    return [m for m in messages if "_condense_parent" not in m]

src/praisonai-agents/praisonaiagents/context/tokens.py

@@ -0,0 +1,238 @@
+"""
+Token Estimation for PraisonAI Agents.
+
+Provides fast, offline token estimation with optional accurate tokenizer support.
+"""
+
+from typing import List, Dict, Any, Optional
+import json
+
+
+# Token estimation constants (based on OpenAI tokenizer patterns)
+ASCII_TOKENS_PER_CHAR = 0.25  # ~4 chars per token for ASCII
+NON_ASCII_TOKENS_PER_CHAR = 1.3  # CJK and other scripts are denser
+
+# Optional tokenizer cache
+_tokenizer_cache: Dict[str, Any] = {}
+
+
+def estimate_tokens_heuristic(text: str) -> int:
+    """
+    Estimate token count using character-based heuristic.
+    
+    Fast and works offline. Accuracy: ~85-95% for English text.
+    
+    Args:
+        text: Text to estimate tokens for
+        
+    Returns:
+        Estimated token count
+    """
+    if not text:
+        return 0
+    
+    total = 0.0
+    for char in text:
+        code_point = ord(char)
+        if code_point <= 127:
+            total += ASCII_TOKENS_PER_CHAR
+        else:
+            total += NON_ASCII_TOKENS_PER_CHAR
+    
+    return max(1, int(total))
+
+
+def estimate_tokens_accurate(text: str, model: str = "gpt-4") -> int:
+    """
+    Estimate tokens using tiktoken if available, else fallback to heuristic.
+    
+    Args:
+        text: Text to estimate tokens for
+        model: Model name for tokenizer selection
+        
+    Returns:
+        Token count
+    """
+    try:
+        import tiktoken
+        
+        # Cache tokenizer
+        if model not in _tokenizer_cache:
+            try:
+                _tokenizer_cache[model] = tiktoken.encoding_for_model(model)
+            except KeyError:
+                # Fallback to cl100k_base for unknown models
+                _tokenizer_cache[model] = tiktoken.get_encoding("cl100k_base")
+        
+        enc = _tokenizer_cache[model]
+        return len(enc.encode(text))
+    except ImportError:
+        return estimate_tokens_heuristic(text)
+
+
+def estimate_message_tokens(message: Dict[str, Any], use_accurate: bool = False) -> int:
+    """
+    Estimate tokens for a single message.
+    
+    Handles various message formats including tool calls and multi-part content.
+    
+    Args:
+        message: Message dict with role and content
+        use_accurate: Use tiktoken if available
+        
+    Returns:
+        Estimated token count
+    """
+    estimate_fn = estimate_tokens_accurate if use_accurate else estimate_tokens_heuristic
+    
+    total = 0
+    
+    # Role overhead (~4 tokens for role markers)
+    total += 4
+    
+    # Content
+    content = message.get("content", "")
+    if isinstance(content, str):
+        total += estimate_fn(content)
+    elif isinstance(content, list):
+        # Multi-part content (text, images, etc.)
+        for part in content:
+            if isinstance(part, dict):
+                if "text" in part:
+                    total += estimate_fn(str(part["text"]))
+                elif "type" in part:
+                    # Image or other media - estimate based on type
+                    if part.get("type") == "image_url":
+                        total += 85  # Base image token cost
+                    else:
+                        total += estimate_fn(json.dumps(part))
+            else:
+                total += estimate_fn(str(part))
+    
+    # Tool calls
+    if "tool_calls" in message:
+        for tool_call in message.get("tool_calls", []):
+            if isinstance(tool_call, dict):
+                # Function name and arguments
+                func = tool_call.get("function", {})
+                total += estimate_fn(func.get("name", ""))
+                total += estimate_fn(func.get("arguments", ""))
+                total += 10  # Overhead for tool call structure
+    
+    # Tool call ID (for tool responses)
+    if "tool_call_id" in message:
+        total += 10
+    
+    # Name field
+    if "name" in message:
+        total += estimate_fn(message["name"])
+    
+    return total
+
+
+def estimate_messages_tokens(
+    messages: List[Dict[str, Any]],
+    use_accurate: bool = False
+) -> int:
+    """
+    Estimate total tokens for a list of messages.
+    
+    Args:
+        messages: List of message dicts
+        use_accurate: Use tiktoken if available
+        
+    Returns:
+        Total estimated token count
+    """
+    if not messages:
+        return 0
+    
+    total = 0
+    for msg in messages:
+        total += estimate_message_tokens(msg, use_accurate)
+    
+    # Add overhead for message array structure
+    total += 3  # Array markers
+    
+    return total
+
+
+def estimate_tool_schema_tokens(
+    tools: List[Dict[str, Any]],
+    use_accurate: bool = False
+) -> int:
+    """
+    Estimate tokens for tool/function schemas.
+    
+    Args:
+        tools: List of tool definitions
+        use_accurate: Use tiktoken if available
+        
+    Returns:
+        Estimated token count
+    """
+    if not tools:
+        return 0
+    
+    estimate_fn = estimate_tokens_accurate if use_accurate else estimate_tokens_heuristic
+    
+    # Serialize tools to JSON and estimate
+    try:
+        tools_json = json.dumps(tools)
+        return estimate_fn(tools_json)
+    except (TypeError, ValueError):
+        # Fallback: estimate per-tool
+        total = 0
+        for tool in tools:
+            if isinstance(tool, dict):
+                total += estimate_fn(json.dumps(tool))
+            else:
+                total += 100  # Default estimate per tool
+        return total
+
+
+class TokenEstimatorImpl:
+    """
+    Token estimator implementation.
+    
+    Provides both heuristic and accurate estimation methods.
+    """
+    
+    def __init__(self, use_accurate: bool = False, model: str = "gpt-4"):
+        """
+        Initialize estimator.
+        
+        Args:
+            use_accurate: Use tiktoken if available
+            model: Model name for tokenizer selection
+        """
+        self.use_accurate = use_accurate
+        self.model = model
+    
+    def estimate(self, text: str) -> int:
+        """Estimate tokens for text."""
+        if self.use_accurate:
+            return estimate_tokens_accurate(text, self.model)
+        return estimate_tokens_heuristic(text)
+    
+    def estimate_messages(self, messages: List[Dict[str, Any]]) -> int:
+        """Estimate tokens for messages."""
+        return estimate_messages_tokens(messages, self.use_accurate)
+    
+    def estimate_tools(self, tools: List[Dict[str, Any]]) -> int:
+        """Estimate tokens for tool schemas."""
+        return estimate_tool_schema_tokens(tools, self.use_accurate)
+
+
+# Default estimator instance
+_default_estimator: Optional[TokenEstimatorImpl] = None
+
+
+def get_estimator(use_accurate: bool = False, model: str = "gpt-4") -> TokenEstimatorImpl:
+    """Get or create a token estimator."""
+    global _default_estimator
+    
+    if _default_estimator is None or _default_estimator.use_accurate != use_accurate:
+        _default_estimator = TokenEstimatorImpl(use_accurate, model)
+    
+    return _default_estimator

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

@@ -16,6 +16,18 @@ from praisonaiagents.knowledge.chunking import Chunking
 
 # Lazy loading for protocols and registries to avoid import overhead
 _LAZY_IMPORTS = {
+    # Models and Protocols (new)
+    "SearchResultItem": ("praisonaiagents.knowledge.models", "SearchResultItem"),
+    "SearchResult": ("praisonaiagents.knowledge.models", "SearchResult"),
+    "AddResult": ("praisonaiagents.knowledge.models", "AddResult"),
+    "normalize_search_item": ("praisonaiagents.knowledge.models", "normalize_search_item"),
+    "normalize_search_result": ("praisonaiagents.knowledge.models", "normalize_search_result"),
+    "normalize_to_dict": ("praisonaiagents.knowledge.models", "normalize_to_dict"),
+    "KnowledgeStoreProtocol": ("praisonaiagents.knowledge.protocols", "KnowledgeStoreProtocol"),
+    "KnowledgeBackendError": ("praisonaiagents.knowledge.protocols", "KnowledgeBackendError"),
+    "ScopeRequiredError": ("praisonaiagents.knowledge.protocols", "ScopeRequiredError"),
+    "BackendNotAvailableError": ("praisonaiagents.knowledge.protocols", "BackendNotAvailableError"),
+    
     # Readers
     "Document": ("praisonaiagents.knowledge.readers", "Document"),
     "ReaderProtocol": ("praisonaiagents.knowledge.readers", "ReaderProtocol"),
@@ -85,6 +97,17 @@ __all__ = [
     # Core
     "Knowledge",
     "Chunking",
+    # Models and Protocols
+    "SearchResultItem",
+    "SearchResult",
+    "AddResult",
+    "normalize_search_item",
+    "normalize_search_result",
+    "normalize_to_dict",
+    "KnowledgeStoreProtocol",
+    "KnowledgeBackendError",
+    "ScopeRequiredError",
+    "BackendNotAvailableError",
     # Readers
     "Document",
     "ReaderProtocol",

src/praisonai-agents/praisonaiagents/knowledge/adapters/__init__.py

@@ -0,0 +1,38 @@
+"""
+Knowledge Store Adapters for PraisonAI Agents.
+
+Provides adapter implementations for various knowledge backends.
+All adapters implement KnowledgeStoreProtocol.
+
+Adapters are lazy-loaded to avoid importing heavy dependencies.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .mem0_adapter import Mem0Adapter
+
+# Lazy loading for adapters
+_LAZY_IMPORTS = {
+    "Mem0Adapter": ("praisonaiagents.knowledge.adapters.mem0_adapter", "Mem0Adapter"),
+}
+
+
+def __getattr__(name: str):
+    """Lazy load adapters."""
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+        module = importlib.import_module(module_path)
+        return getattr(module, attr_name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """List available attributes."""
+    return list(_LAZY_IMPORTS.keys())
+
+
+__all__ = [
+    "Mem0Adapter",
+]

src/praisonai-agents/praisonaiagents/knowledge/adapters/mem0_adapter.py

@@ -0,0 +1,459 @@
+"""
+Mem0 Adapter for PraisonAI Knowledge Store.
+
+Implements KnowledgeStoreProtocol using mem0 as the backend.
+Handles all normalization to ensure metadata is ALWAYS a dict (never None).
+
+LAZY IMPORT: mem0 is only imported when this adapter is instantiated.
+"""
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from ..models import (
+    AddResult,
+    SearchResult,
+    SearchResultItem,
+    normalize_search_item,
+)
+from ..protocols import ScopeRequiredError
+
+logger = logging.getLogger(__name__)
+
+
+class Mem0Adapter:
+    """
+    Adapter implementing KnowledgeStoreProtocol for mem0 backend.
+    
+    Features:
+    - Lazy imports mem0 only when instantiated
+    - Normalizes all results (metadata None → {})
+    - Enforces scope requirements (user_id/agent_id/run_id)
+    - Maps mem0 field names to standard schema (memory → text)
+    - Disables telemetry by default
+    
+    Usage:
+        adapter = Mem0Adapter(config={...})
+        results = adapter.search("query", user_id="user123")
+    """
+    
+    def __init__(
+        self,
+        config: Optional[Dict[str, Any]] = None,
+        disable_telemetry: bool = True,
+    ):
+        """
+        Initialize Mem0 adapter.
+        
+        Args:
+            config: mem0 configuration dict
+            disable_telemetry: Whether to disable mem0 telemetry (default True)
+        """
+        self._config = config or {}
+        self._memory = None
+        self._disable_telemetry = disable_telemetry
+        
+        # Disable telemetry before importing mem0
+        if disable_telemetry:
+            os.environ.setdefault("ANONYMIZED_TELEMETRY", "False")
+    
+    @property
+    def memory(self):
+        """Lazy load mem0 Memory instance."""
+        if self._memory is None:
+            self._memory = self._init_mem0()
+        return self._memory
+    
+    def _init_mem0(self):
+        """Initialize mem0 Memory with config."""
+        try:
+            from mem0 import Memory
+        except ImportError:
+            raise ImportError(
+                "mem0 is not installed. Install with: pip install mem0ai"
+            )
+        
+        if self._config:
+            return Memory.from_config(self._config)
+        return Memory()
+    
+    def _check_scope(
+        self,
+        user_id: Optional[str],
+        agent_id: Optional[str],
+        run_id: Optional[str],
+        operation: str = "operation",
+    ) -> None:
+        """
+        Check that at least one scope identifier is provided.
+        
+        mem0 requires at least one of user_id, agent_id, or run_id.
+        
+        Raises:
+            ScopeRequiredError: If no scope identifier is provided
+        """
+        if not any([user_id, agent_id, run_id]):
+            raise ScopeRequiredError(
+                message=(
+                    f"mem0 {operation} requires at least one of 'user_id', "
+                    f"'agent_id', or 'run_id'. Please provide at least one "
+                    f"identifier to scope the {operation}."
+                ),
+                backend="mem0",
+            )
+    
+    def _normalize_mem0_item(self, raw: Dict[str, Any]) -> SearchResultItem:
+        """
+        Normalize a mem0 result item to SearchResultItem.
+        
+        Handles mem0-specific field names and ensures metadata is dict.
+        
+        Args:
+            raw: Raw mem0 result dict
+            
+        Returns:
+            SearchResultItem with guaranteed schema
+        """
+        if raw is None:
+            return SearchResultItem()
+        
+        # Use the canonical normalization function
+        item = normalize_search_item(raw)
+        
+        # mem0 specific: extract user_id/agent_id/run_id from top level
+        # and add to metadata if present
+        for key in ["user_id", "agent_id", "run_id"]:
+            if key in raw and raw[key] is not None:
+                item.metadata[key] = raw[key]
+        
+        return item
+    
+    def _normalize_mem0_results(self, raw: Any) -> SearchResult:
+        """
+        Normalize mem0 search results to SearchResult.
+        
+        Args:
+            raw: Raw mem0 results (dict with 'results' key or list)
+            
+        Returns:
+            SearchResult with normalized items
+        """
+        if raw is None:
+            return SearchResult()
+        
+        # Handle dict with 'results' key (standard mem0 format)
+        if isinstance(raw, dict):
+            items = raw.get("results", []) or []
+            normalized_items = [
+                self._normalize_mem0_item(item)
+                for item in items
+                if item is not None
+            ]
+            return SearchResult(
+                results=normalized_items,
+                metadata=raw.get("relations", {}) if "relations" in raw else {},
+            )
+        
+        # Handle list of results
+        if isinstance(raw, list):
+            normalized_items = [
+                self._normalize_mem0_item(item)
+                for item in raw
+                if item is not None
+            ]
+            return SearchResult(results=normalized_items)
+        
+        return SearchResult()
+    
+    def search(
+        self,
+        query: str,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        limit: int = 100,
+        filters: Optional[Dict[str, Any]] = None,
+        rerank: bool = True,
+        **kwargs: Any,
+    ) -> SearchResult:
+        """
+        Search for relevant content in mem0.
+        
+        Args:
+            query: Search query string
+            user_id: User identifier for scoping
+            agent_id: Agent identifier for scoping
+            run_id: Run identifier for scoping
+            limit: Maximum number of results
+            filters: Optional metadata filters
+            rerank: Whether to use mem0 reranking (default True)
+            **kwargs: Additional mem0 search options
+            
+        Returns:
+            SearchResult with normalized items (metadata always dict)
+            
+        Raises:
+            ScopeRequiredError: If no scope identifier is provided
+        """
+        self._check_scope(user_id, agent_id, run_id, "search")
+        
+        try:
+            raw_results = self.memory.search(
+                query=query,
+                user_id=user_id,
+                agent_id=agent_id,
+                run_id=run_id,
+                limit=limit,
+                filters=filters,
+                rerank=rerank,
+                **kwargs,
+            )
+            return self._normalize_mem0_results(raw_results)
+        except Exception as e:
+            logger.warning(f"mem0 search failed: {e}")
+            return SearchResult(metadata={"error": str(e)})
+    
+    def add(
+        self,
+        content: Any,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> AddResult:
+        """
+        Add content to mem0.
+        
+        Args:
+            content: Content to add (string or messages list)
+            user_id: User identifier for scoping
+            agent_id: Agent identifier for scoping
+            run_id: Run identifier for scoping
+            metadata: Optional metadata to attach
+            **kwargs: Additional mem0 add options
+            
+        Returns:
+            AddResult with operation status
+            
+        Raises:
+            ScopeRequiredError: If no scope identifier is provided
+        """
+        self._check_scope(user_id, agent_id, run_id, "add")
+        
+        try:
+            # Convert content to messages format for mem0
+            if isinstance(content, str):
+                messages = [{"role": "user", "content": content}]
+            elif isinstance(content, list):
+                messages = content
+            else:
+                messages = [{"role": "user", "content": str(content)}]
+            
+            result = self.memory.add(
+                messages=messages,
+                user_id=user_id,
+                agent_id=agent_id,
+                run_id=run_id,
+                metadata=metadata,
+                **kwargs,
+            )
+            
+            # Extract ID from result
+            result_id = ""
+            if isinstance(result, dict):
+                result_id = result.get("id", "")
+            elif isinstance(result, list) and result:
+                result_id = result[0].get("id", "") if isinstance(result[0], dict) else ""
+            
+            return AddResult(
+                id=str(result_id),
+                success=True,
+                message="Content added successfully",
+                metadata={"raw_result": result} if result else {},
+            )
+        except Exception as e:
+            logger.error(f"mem0 add failed: {e}")
+            return AddResult(
+                success=False,
+                message=str(e),
+                metadata={"error": str(e)},
+            )
+    
+    def get(
+        self,
+        item_id: str,
+        **kwargs: Any,
+    ) -> Optional[SearchResultItem]:
+        """
+        Get a specific item by ID from mem0.
+        
+        Args:
+            item_id: ID of the item to retrieve
+            **kwargs: Additional options
+            
+        Returns:
+            SearchResultItem if found, None otherwise
+        """
+        try:
+            raw = self.memory.get(item_id)
+            if raw is None:
+                return None
+            return self._normalize_mem0_item(raw)
+        except Exception as e:
+            logger.warning(f"mem0 get failed: {e}")
+            return None
+    
+    def get_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        limit: int = 100,
+        **kwargs: Any,
+    ) -> SearchResult:
+        """
+        Get all items from mem0, optionally filtered by scope.
+        
+        Args:
+            user_id: User identifier for scoping
+            agent_id: Agent identifier for scoping
+            run_id: Run identifier for scoping
+            limit: Maximum number of results
+            **kwargs: Additional options
+            
+        Returns:
+            SearchResult with all matching items
+            
+        Raises:
+            ScopeRequiredError: If no scope identifier is provided
+        """
+        self._check_scope(user_id, agent_id, run_id, "get_all")
+        
+        try:
+            raw_results = self.memory.get_all(
+                user_id=user_id,
+                agent_id=agent_id,
+                run_id=run_id,
+                **kwargs,
+            )
+            return self._normalize_mem0_results(raw_results)
+        except Exception as e:
+            logger.warning(f"mem0 get_all failed: {e}")
+            return SearchResult(metadata={"error": str(e)})
+    
+    def update(
+        self,
+        item_id: str,
+        content: Any,
+        **kwargs: Any,
+    ) -> AddResult:
+        """
+        Update an existing item in mem0.
+        
+        Args:
+            item_id: ID of the item to update
+            content: New content
+            **kwargs: Additional options
+            
+        Returns:
+            AddResult with operation status
+        """
+        try:
+            result = self.memory.update(item_id, str(content))
+            return AddResult(
+                id=item_id,
+                success=True,
+                message=result.get("message", "Updated successfully") if isinstance(result, dict) else "Updated",
+            )
+        except Exception as e:
+            logger.error(f"mem0 update failed: {e}")
+            return AddResult(
+                id=item_id,
+                success=False,
+                message=str(e),
+                metadata={"error": str(e)},
+            )
+    
+    def delete(
+        self,
+        item_id: str,
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Delete an item by ID from mem0.
+        
+        Args:
+            item_id: ID of the item to delete
+            **kwargs: Additional options
+            
+        Returns:
+            True if deleted, False otherwise
+        """
+        try:
+            self.memory.delete(item_id)
+            return True
+        except Exception as e:
+            logger.warning(f"mem0 delete failed: {e}")
+            return False
+    
+    def delete_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Delete all items matching scope from mem0.
+        
+        Args:
+            user_id: User identifier for scoping
+            agent_id: Agent identifier for scoping
+            run_id: Run identifier for scoping
+            **kwargs: Additional options
+            
+        Returns:
+            True if operation succeeded
+            
+        Raises:
+            ScopeRequiredError: If no scope identifier is provided
+        """
+        self._check_scope(user_id, agent_id, run_id, "delete_all")
+        
+        try:
+            self.memory.delete_all(
+                user_id=user_id,
+                agent_id=agent_id,
+                run_id=run_id,
+            )
+            return True
+        except Exception as e:
+            logger.warning(f"mem0 delete_all failed: {e}")
+            return False
+    
+    def history(
+        self,
+        item_id: str,
+        **kwargs: Any,
+    ) -> List[Dict[str, Any]]:
+        """
+        Get history of changes for an item.
+        
+        Args:
+            item_id: ID of the item
+            **kwargs: Additional options
+            
+        Returns:
+            List of history entries
+        """
+        try:
+            return self.memory.history(item_id)
+        except Exception as e:
+            logger.warning(f"mem0 history failed: {e}")
+            return []

src/praisonai-agents/praisonaiagents/knowledge/indexing.py

@@ -0,0 +1,439 @@
+"""
+Incremental Indexing Infrastructure for PraisonAI Agents.
+
+Provides:
+- CorpusStats: Statistics about indexed corpus
+- IndexResult: Result of indexing operation
+- IgnoreMatcher: .praisonignore pattern matching
+- FileTracker: File hash/mtime tracking for incremental updates
+
+No heavy imports - only stdlib.
+"""
+
+import fnmatch
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+# Strategy thresholds based on corpus size
+STRATEGY_THRESHOLDS = {
+    10: "direct",        # < 10 files: load all
+    100: "basic",        # < 100 files: semantic search only
+    1000: "hybrid",      # < 1000 files: keyword + semantic
+    10000: "reranked",   # < 10000 files: hybrid + rerank
+    100000: "compressed", # < 100000 files: reranked + compression
+}
+DEFAULT_STRATEGY = "hierarchical"  # > 100000 files
+
+
+def estimate_tokens_simple(text: str) -> int:
+    """Simple token estimation (~4 chars per token)."""
+    if not text:
+        return 0
+    return len(text) // 4 + 1
+
+
+@dataclass
+class CorpusStats:
+    """
+    Statistics about an indexed corpus.
+    
+    Used for strategy selection and monitoring.
+    
+    Attributes:
+        file_count: Number of files in corpus
+        chunk_count: Number of chunks created
+        total_tokens: Estimated total tokens
+        indexed_at: Timestamp of last indexing
+        path: Path to corpus root
+        strategy_recommendation: Recommended retrieval strategy
+    """
+    file_count: int = 0
+    chunk_count: int = 0
+    total_tokens: int = 0
+    indexed_at: Optional[str] = None
+    path: Optional[str] = None
+    
+    @property
+    def strategy_recommendation(self) -> str:
+        """Recommend retrieval strategy based on corpus size."""
+        for threshold, strategy in sorted(STRATEGY_THRESHOLDS.items()):
+            if self.file_count < threshold:
+                return strategy
+        return DEFAULT_STRATEGY
+    
+    @classmethod
+    def from_directory(
+        cls,
+        path: str,
+        extensions: Optional[List[str]] = None,
+    ) -> "CorpusStats":
+        """
+        Create CorpusStats from directory scan.
+        
+        Args:
+            path: Directory path to scan
+            extensions: Optional list of extensions to include
+            
+        Returns:
+            CorpusStats with file count and token estimate
+        """
+        if extensions is None:
+            extensions = [
+                ".txt", ".md", ".py", ".js", ".ts", ".json", ".yaml", ".yml",
+                ".html", ".css", ".csv", ".xml", ".rst", ".pdf", ".docx",
+            ]
+        
+        file_count = 0
+        total_tokens = 0
+        
+        for root, _, files in os.walk(path):
+            for filename in files:
+                ext = os.path.splitext(filename)[1].lower()
+                if ext in extensions:
+                    file_count += 1
+                    filepath = os.path.join(root, filename)
+                    try:
+                        size = os.path.getsize(filepath)
+                        # Rough estimate: 4 chars per token
+                        total_tokens += size // 4
+                    except OSError:
+                        pass
+        
+        return cls(
+            file_count=file_count,
+            total_tokens=total_tokens,
+            path=path,
+            indexed_at=datetime.now().isoformat(),
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "file_count": self.file_count,
+            "chunk_count": self.chunk_count,
+            "total_tokens": self.total_tokens,
+            "indexed_at": self.indexed_at,
+            "path": self.path,
+            "strategy_recommendation": self.strategy_recommendation,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "CorpusStats":
+        """Create from dictionary."""
+        return cls(
+            file_count=data.get("file_count", 0),
+            chunk_count=data.get("chunk_count", 0),
+            total_tokens=data.get("total_tokens", 0),
+            indexed_at=data.get("indexed_at"),
+            path=data.get("path"),
+        )
+
+
+@dataclass
+class IndexResult:
+    """
+    Result of an indexing operation.
+    
+    Attributes:
+        success: Whether indexing succeeded
+        files_indexed: Number of files indexed
+        files_skipped: Number of files skipped (unchanged)
+        chunks_created: Number of chunks created
+        errors: List of error messages
+        duration_seconds: Time taken for indexing
+        corpus_stats: Stats about the indexed corpus
+    """
+    success: bool = True
+    files_indexed: int = 0
+    files_skipped: int = 0
+    chunks_created: int = 0
+    errors: List[str] = field(default_factory=list)
+    duration_seconds: float = 0.0
+    corpus_stats: Optional[CorpusStats] = None
+    
+    @property
+    def total_files(self) -> int:
+        """Total files processed (indexed + skipped)."""
+        return self.files_indexed + self.files_skipped
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "success": self.success,
+            "files_indexed": self.files_indexed,
+            "files_skipped": self.files_skipped,
+            "chunks_created": self.chunks_created,
+            "total_files": self.total_files,
+            "errors": self.errors,
+            "duration_seconds": self.duration_seconds,
+            "corpus_stats": self.corpus_stats.to_dict() if self.corpus_stats else None,
+        }
+
+
+class IgnoreMatcher:
+    """
+    Matcher for .praisonignore patterns.
+    
+    Supports gitignore-style patterns:
+    - * matches any sequence of characters
+    - ** matches any path segments
+    - ! negates a pattern
+    - # starts a comment
+    """
+    
+    def __init__(self, patterns: Optional[List[str]] = None):
+        """
+        Initialize with patterns.
+        
+        Args:
+            patterns: List of gitignore-style patterns
+        """
+        self._include_patterns: List[str] = []
+        self._exclude_patterns: List[str] = []
+        
+        if patterns:
+            for pattern in patterns:
+                pattern = pattern.strip()
+                if not pattern or pattern.startswith("#"):
+                    continue
+                if pattern.startswith("!"):
+                    self._include_patterns.append(pattern[1:])
+                else:
+                    self._exclude_patterns.append(pattern)
+    
+    def should_ignore(self, path: str) -> bool:
+        """
+        Check if path should be ignored.
+        
+        Args:
+            path: Path to check (relative or absolute)
+            
+        Returns:
+            True if path should be ignored
+        """
+        # Normalize path
+        path = path.replace("\\", "/")
+        basename = os.path.basename(path)
+        
+        # Check exclude patterns
+        ignored = False
+        for pattern in self._exclude_patterns:
+            if self._matches(path, pattern) or self._matches(basename, pattern):
+                ignored = True
+                break
+        
+        # Check include patterns (negation)
+        if ignored:
+            for pattern in self._include_patterns:
+                if self._matches(path, pattern) or self._matches(basename, pattern):
+                    return False
+        
+        return ignored
+    
+    def _matches(self, path: str, pattern: str) -> bool:
+        """Check if path matches pattern."""
+        # Handle ** for recursive matching
+        if "**" in pattern:
+            # Convert gitignore pattern to regex
+            # First escape special regex chars except * and /
+            regex_pattern = re.escape(pattern)
+            # Restore * and convert to regex
+            regex_pattern = regex_pattern.replace(r"\*\*", ".*")
+            regex_pattern = regex_pattern.replace(r"\*", "[^/]*")
+            # Match anywhere in path
+            try:
+                return bool(re.search(regex_pattern, path))
+            except re.error:
+                return False
+        
+        # Handle trailing slash for directories
+        if pattern.endswith("/"):
+            pattern = pattern[:-1]
+            return path == pattern or path.startswith(pattern + "/") or ("/" + pattern + "/") in ("/" + path + "/")
+        
+        # Standard fnmatch - check full path and basename
+        if fnmatch.fnmatch(path, pattern):
+            return True
+        if fnmatch.fnmatch(os.path.basename(path), pattern):
+            return True
+        # Also check if pattern matches any path segment
+        for segment in path.split("/"):
+            if fnmatch.fnmatch(segment, pattern):
+                return True
+        return False
+    
+    @classmethod
+    def from_file(cls, filepath: str) -> "IgnoreMatcher":
+        """
+        Load patterns from file.
+        
+        Args:
+            filepath: Path to .praisonignore file
+            
+        Returns:
+            IgnoreMatcher with loaded patterns
+        """
+        patterns = []
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                patterns = f.read().splitlines()
+        except (OSError, IOError):
+            pass
+        return cls(patterns=patterns)
+    
+    @classmethod
+    def from_directory(cls, directory: str) -> "IgnoreMatcher":
+        """
+        Auto-detect and load .praisonignore from directory.
+        
+        Also checks for .gitignore as fallback.
+        
+        Args:
+            directory: Directory to search
+            
+        Returns:
+            IgnoreMatcher with loaded patterns
+        """
+        patterns = []
+        
+        # Check for .praisonignore
+        praison_ignore = os.path.join(directory, ".praisonignore")
+        if os.path.exists(praison_ignore):
+            try:
+                with open(praison_ignore, "r", encoding="utf-8") as f:
+                    patterns.extend(f.read().splitlines())
+            except (OSError, IOError):
+                pass
+        
+        # Also check .gitignore
+        git_ignore = os.path.join(directory, ".gitignore")
+        if os.path.exists(git_ignore):
+            try:
+                with open(git_ignore, "r", encoding="utf-8") as f:
+                    patterns.extend(f.read().splitlines())
+            except (OSError, IOError):
+                pass
+        
+        return cls(patterns=patterns)
+
+
+class FileTracker:
+    """
+    Track file hashes and modification times for incremental indexing.
+    
+    Persists state to a JSON file for cross-session tracking.
+    """
+    
+    def __init__(self, state_file: Optional[str] = None):
+        """
+        Initialize tracker.
+        
+        Args:
+            state_file: Path to state file for persistence
+        """
+        self._state_file = state_file
+        self._tracked: Dict[str, Dict[str, Any]] = {}
+    
+    def get_file_info(self, filepath: str) -> Dict[str, Any]:
+        """
+        Get file information (hash, mtime, size).
+        
+        Args:
+            filepath: Path to file
+            
+        Returns:
+            Dict with path, hash, mtime, size
+        """
+        stat = os.stat(filepath)
+        
+        # Calculate hash for small files, use mtime+size for large files
+        if stat.st_size < 1024 * 1024:  # 1MB
+            with open(filepath, "rb") as f:
+                file_hash = hashlib.md5(f.read()).hexdigest()
+        else:
+            # For large files, use mtime + size as proxy
+            file_hash = f"{stat.st_mtime}:{stat.st_size}"
+        
+        return {
+            "path": filepath,
+            "hash": file_hash,
+            "mtime": stat.st_mtime,
+            "size": stat.st_size,
+        }
+    
+    def mark_indexed(self, filepath: str, info: Dict[str, Any]) -> None:
+        """
+        Mark file as indexed.
+        
+        Args:
+            filepath: Path to file
+            info: File info from get_file_info()
+        """
+        self._tracked[filepath] = info
+    
+    def has_changed(self, filepath: str) -> bool:
+        """
+        Check if file has changed since last indexing.
+        
+        Args:
+            filepath: Path to file
+            
+        Returns:
+            True if file is new or changed
+        """
+        if filepath not in self._tracked:
+            return True
+        
+        try:
+            current = self.get_file_info(filepath)
+            tracked = self._tracked[filepath]
+            
+            # Compare hash
+            if current["hash"] != tracked["hash"]:
+                return True
+            
+            # Compare mtime as backup
+            if current["mtime"] != tracked["mtime"]:
+                return True
+            
+            return False
+        except OSError:
+            return True
+    
+    def save(self) -> None:
+        """Save state to file."""
+        if not self._state_file:
+            return
+        
+        try:
+            os.makedirs(os.path.dirname(self._state_file), exist_ok=True)
+            with open(self._state_file, "w", encoding="utf-8") as f:
+                json.dump(self._tracked, f, indent=2)
+        except (OSError, IOError):
+            pass
+    
+    def load(self) -> None:
+        """Load state from file."""
+        if not self._state_file or not os.path.exists(self._state_file):
+            return
+        
+        try:
+            with open(self._state_file, "r", encoding="utf-8") as f:
+                self._tracked = json.load(f)
+        except (OSError, IOError, json.JSONDecodeError):
+            self._tracked = {}
+    
+    def clear(self) -> None:
+        """Clear all tracked files."""
+        self._tracked = {}
+        if self._state_file and os.path.exists(self._state_file):
+            try:
+                os.remove(self._state_file)
+            except OSError:
+                pass

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

@@ -683,7 +683,7 @@ class Knowledge:
         return self._process_single_input(file_path, user_id, agent_id, run_id, metadata)
 
     def _process_single_input(self, input_path, user_id=None, agent_id=None, run_id=None, metadata=None):
-        """Process a single input which can be a file path or URL."""
+        """Process a single input which can be a file path, directory, or URL."""
         try:
             # Define supported file extensions
             DOCUMENT_EXTENSIONS = {
@@ -692,11 +692,44 @@ class Knowledge:
                 'text': ('.txt', '.csv', '.json', '.xml', '.md', '.html', '.htm'),
                 'archive': '.zip'
             }
+            
+            # Get all supported extensions as a flat tuple
+            all_extensions = []
+            for exts in DOCUMENT_EXTENSIONS.values():
+                if isinstance(exts, tuple):
+                    all_extensions.extend(exts)
+                else:
+                    all_extensions.append(exts)
+            all_extensions = tuple(all_extensions)
 
             # Check if input is URL
             if isinstance(input_path, str) and (input_path.startswith('http://') or input_path.startswith('https://')):
                 self._log(f"Processing URL: {input_path}")
                 raise NotImplementedError("URL processing not yet implemented")
+            
+            # CRITICAL FIX: Check if input is a directory - recursively process all files
+            if os.path.isdir(input_path):
+                self._log(f"Processing directory: {input_path}")
+                all_results = []
+                
+                # Walk through directory and process all supported files
+                for root, dirs, files in os.walk(input_path):
+                    for filename in files:
+                        file_path = os.path.join(root, filename)
+                        # Only process files with supported extensions
+                        if filename.lower().endswith(all_extensions):
+                            try:
+                                result = self._process_single_input(
+                                    file_path, user_id, agent_id, run_id, metadata
+                                )
+                                all_results.extend(result.get('results', []))
+                            except Exception as e:
+                                logger.warning(f"Failed to process file {file_path}: {e}")
+                
+                if not all_results:
+                    logger.warning(f"No supported files found in directory: {input_path}")
+                
+                return {'results': all_results, 'relations': []}
 
             # Check if input ends with any supported extension
             is_supported_file = any(input_path.lower().endswith(ext) 
@@ -770,4 +803,158 @@ class Knowledge:
 
         except Exception as e:
             logger.error(f"Error processing input {input_path}: {str(e)}", exc_info=True)
-            raise
+            raise
+    
+    def index(
+        self,
+        path: str,
+        incremental: bool = True,
+        force: bool = False,
+        include_glob: list = None,
+        exclude_glob: list = None,
+        user_id: str = None,
+        agent_id: str = None,
+        run_id: str = None,
+    ):
+        """
+        Index a directory or file for knowledge retrieval.
+        
+        Supports incremental indexing - only changed files are re-indexed.
+        
+        Args:
+            path: Directory or file path to index
+            incremental: If True, only index changed files (default: True)
+            force: If True, re-index all files regardless of changes
+            include_glob: List of glob patterns to include (e.g., ["*.py", "*.md"])
+            exclude_glob: List of glob patterns to exclude (e.g., ["*.log", "test_*"])
+            user_id: Optional user ID for scoping
+            agent_id: Optional agent ID for scoping
+            run_id: Optional run ID for scoping
+            
+        Returns:
+            IndexResult with indexing statistics
+        """
+        from .indexing import IndexResult, CorpusStats, IgnoreMatcher, FileTracker
+        import time as time_module
+        import fnmatch as fnmatch_module
+        
+        start_time = time_module.time()
+        
+        result = IndexResult()
+        
+        # Initialize file tracker for incremental indexing
+        state_dir = os.path.join(os.path.dirname(path) if os.path.isfile(path) else path, ".praison")
+        os.makedirs(state_dir, exist_ok=True)
+        state_file = os.path.join(state_dir, ".index_state.json")
+        
+        tracker = FileTracker(state_file=state_file)
+        if incremental and not force:
+            tracker.load()
+        
+        # Initialize ignore matcher
+        ignore_matcher = IgnoreMatcher.from_directory(path if os.path.isdir(path) else os.path.dirname(path))
+        
+        # Collect files to index
+        files_to_index = []
+        
+        if os.path.isfile(path):
+            files_to_index = [path]
+        else:
+            for root, dirs, files in os.walk(path):
+                # Skip hidden directories
+                dirs[:] = [d for d in dirs if not d.startswith('.')]
+                
+                for filename in files:
+                    filepath = os.path.join(root, filename)
+                    rel_path = os.path.relpath(filepath, path)
+                    
+                    # Check ignore patterns
+                    if ignore_matcher.should_ignore(rel_path):
+                        continue
+                    
+                    # Check include patterns
+                    if include_glob:
+                        matched = False
+                        for pattern in include_glob:
+                            if fnmatch_module.fnmatch(filename, pattern):
+                                matched = True
+                                break
+                        if not matched:
+                            continue
+                    
+                    # Check exclude patterns
+                    if exclude_glob:
+                        excluded = False
+                        for pattern in exclude_glob:
+                            if fnmatch_module.fnmatch(filename, pattern) or fnmatch_module.fnmatch(rel_path, pattern):
+                                excluded = True
+                                break
+                        if excluded:
+                            continue
+                    
+                    files_to_index.append(filepath)
+        
+        # Index files
+        total_chunks = 0
+        for filepath in files_to_index:
+            try:
+                # Check if file has changed (for incremental indexing)
+                if incremental and not force and not tracker.has_changed(filepath):
+                    result.files_skipped += 1
+                    continue
+                
+                # Index the file
+                add_result = self.add(
+                    filepath,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    run_id=run_id,
+                )
+                
+                # Count chunks
+                if add_result and isinstance(add_result, dict):
+                    chunks = len(add_result.get('results', []))
+                    total_chunks += chunks
+                
+                # Mark as indexed
+                file_info = tracker.get_file_info(filepath)
+                tracker.mark_indexed(filepath, file_info)
+                
+                result.files_indexed += 1
+                
+            except Exception as e:
+                result.errors.append(f"{filepath}: {str(e)}")
+        
+        # Save tracker state
+        if incremental:
+            tracker.save()
+        
+        # Calculate stats
+        result.chunks_created = total_chunks
+        result.duration_seconds = time_module.time() - start_time
+        result.corpus_stats = CorpusStats(
+            file_count=result.files_indexed + result.files_skipped,
+            chunk_count=total_chunks,
+            path=path,
+            indexed_at=datetime.now().isoformat(),
+        )
+        
+        # Store corpus stats for later retrieval
+        self._corpus_stats = result.corpus_stats
+        
+        return result
+    
+    def get_corpus_stats(self):
+        """
+        Get statistics about the indexed corpus.
+        
+        Returns:
+            CorpusStats with file count, chunk count, and strategy recommendation
+        """
+        from .indexing import CorpusStats
+        
+        if hasattr(self, '_corpus_stats') and self._corpus_stats:
+            return self._corpus_stats
+        
+        # Return empty stats if not indexed
+        return CorpusStats()

src/praisonai-agents/praisonaiagents/knowledge/models.py

@@ -0,0 +1,249 @@
+"""
+Knowledge Models for PraisonAI Agents.
+
+Typed dataclasses for knowledge retrieval results.
+These models guarantee metadata is ALWAYS a dict (never None).
+
+No heavy imports - only stdlib.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class SearchResultItem:
+    """
+    A single search result item with guaranteed schema.
+    
+    CRITICAL: metadata is ALWAYS a dict, never None.
+    This is enforced at construction time.
+    
+    Attributes:
+        id: Unique identifier for the result
+        text: The text content (normalized from 'memory' field if needed)
+        score: Relevance score (default 0.0)
+        metadata: Additional metadata (ALWAYS dict, never None)
+        source: Optional source identifier
+        filename: Optional filename
+        created_at: Optional creation timestamp
+        updated_at: Optional update timestamp
+    """
+    id: str = ""
+    text: str = ""
+    score: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    source: Optional[str] = None
+    filename: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    
+    def __post_init__(self):
+        """Ensure metadata is never None."""
+        if self.metadata is None:
+            self.metadata = {}
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format."""
+        return {
+            "id": self.id,
+            "text": self.text,
+            "score": self.score,
+            "metadata": self.metadata,
+            "source": self.source,
+            "filename": self.filename,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+
+@dataclass
+class SearchResult:
+    """
+    Container for search results with guaranteed schema.
+    
+    Attributes:
+        results: List of SearchResultItem objects
+        metadata: Additional metadata about the search (ALWAYS dict)
+        query: The original query string
+        total_count: Total number of results (may differ from len(results) if paginated)
+    """
+    results: List[SearchResultItem] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    query: str = ""
+    total_count: Optional[int] = None
+    
+    def __post_init__(self):
+        """Ensure metadata is never None."""
+        if self.metadata is None:
+            self.metadata = {}
+        if self.results is None:
+            self.results = []
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format compatible with legacy code."""
+        return {
+            "results": [r.to_dict() if hasattr(r, 'to_dict') else r for r in self.results],
+            "metadata": self.metadata,
+            "query": self.query,
+            "total_count": self.total_count or len(self.results),
+        }
+    
+    def to_legacy_format(self) -> Dict[str, Any]:
+        """
+        Convert to legacy format for backward compatibility.
+        
+        Returns dict with 'results' key containing list of dicts.
+        """
+        return {
+            "results": [
+                {
+                    "id": r.id,
+                    "memory": r.text,  # Legacy field name
+                    "text": r.text,
+                    "score": r.score,
+                    "metadata": r.metadata,
+                    "source": r.source,
+                    "filename": r.filename,
+                    "created_at": r.created_at,
+                    "updated_at": r.updated_at,
+                }
+                for r in self.results
+            ]
+        }
+
+
+@dataclass
+class AddResult:
+    """
+    Result of adding content to knowledge store.
+    
+    Attributes:
+        id: ID of the added item
+        success: Whether the operation succeeded
+        message: Optional message about the operation
+        metadata: Additional metadata (ALWAYS dict)
+    """
+    id: str = ""
+    success: bool = True
+    message: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """Ensure metadata is never None."""
+        if self.metadata is None:
+            self.metadata = {}
+
+
+def normalize_search_item(raw: Dict[str, Any]) -> SearchResultItem:
+    """
+    Normalize a raw search result item to SearchResultItem.
+    
+    This is the SINGLE canonical normalization function.
+    Handles mem0 format, internal format, and any other variations.
+    
+    CRITICAL: Ensures metadata is ALWAYS a dict, never None.
+    
+    Args:
+        raw: Raw result dict from any backend
+        
+    Returns:
+        SearchResultItem with guaranteed schema
+    """
+    if raw is None:
+        return SearchResultItem()
+    
+    # Handle text field (mem0 uses 'memory', others use 'text')
+    text = raw.get("text") or raw.get("memory", "") or ""
+    
+    # Handle metadata - CRITICAL: ensure never None
+    metadata = raw.get("metadata")
+    if metadata is None:
+        metadata = {}
+    elif not isinstance(metadata, dict):
+        metadata = {}
+    
+    # Extract source/filename from metadata if not at top level
+    source = raw.get("source") or metadata.get("source")
+    filename = raw.get("filename") or metadata.get("filename")
+    
+    return SearchResultItem(
+        id=str(raw.get("id", "")),
+        text=str(text),
+        score=float(raw.get("score", 0.0) or 0.0),
+        metadata=metadata,
+        source=source,
+        filename=filename,
+        created_at=raw.get("created_at"),
+        updated_at=raw.get("updated_at"),
+    )
+
+
+def normalize_search_result(raw: Any) -> SearchResult:
+    """
+    Normalize raw search results to SearchResult.
+    
+    Handles various input formats:
+    - dict with 'results' key (mem0 format)
+    - list of results
+    - single result dict
+    - None
+    
+    Args:
+        raw: Raw search results from any backend
+        
+    Returns:
+        SearchResult with guaranteed schema
+    """
+    if raw is None:
+        return SearchResult()
+    
+    # Handle dict with 'results' key
+    if isinstance(raw, dict):
+        if "results" in raw:
+            items = raw.get("results", []) or []
+            normalized_items = [
+                normalize_search_item(item) 
+                for item in items 
+                if item is not None
+            ]
+            return SearchResult(
+                results=normalized_items,
+                metadata=raw.get("metadata") or {},
+                query=raw.get("query", ""),
+            )
+        else:
+            # Single result dict
+            return SearchResult(
+                results=[normalize_search_item(raw)],
+                metadata={},
+            )
+    
+    # Handle list of results
+    if isinstance(raw, list):
+        normalized_items = [
+            normalize_search_item(item) 
+            for item in raw 
+            if item is not None
+        ]
+        return SearchResult(results=normalized_items)
+    
+    # Fallback
+    return SearchResult()
+
+
+def normalize_to_dict(raw: Any) -> Dict[str, Any]:
+    """
+    Normalize raw search results to legacy dict format.
+    
+    Convenience function for code that expects dict format.
+    Ensures all items have metadata as dict (never None).
+    
+    Args:
+        raw: Raw search results from any backend
+        
+    Returns:
+        Dict with 'results' key containing normalized items
+    """
+    result = normalize_search_result(raw)
+    return result.to_legacy_format()

src/praisonai-agents/praisonaiagents/knowledge/protocols.py

@@ -0,0 +1,211 @@
+"""
+Knowledge Store Protocol for PraisonAI Agents.
+
+Defines the interface that knowledge backends must implement.
+Uses typing.Protocol for structural subtyping (duck typing with type hints).
+
+No heavy imports - only stdlib typing.
+"""
+
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from .models import AddResult, SearchResult, SearchResultItem
+
+
+@runtime_checkable
+class KnowledgeStoreProtocol(Protocol):
+    """
+    Protocol defining the interface for knowledge store backends.
+    
+    Implementations include:
+    - Mem0Adapter (mem0 backend)
+    - ChromaAdapter (direct chromadb)
+    - InternalAdapter (built-in storage)
+    
+    All implementations MUST:
+    1. Return SearchResult/SearchResultItem with metadata as dict (never None)
+    2. Handle identifier scoping (user_id/agent_id/run_id) appropriately
+    3. Provide clear error messages for missing required parameters
+    """
+    
+    def search(
+        self,
+        query: str,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        limit: int = 10,
+        filters: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> SearchResult:
+        """
+        Search for relevant content.
+        
+        Args:
+            query: Search query string
+            user_id: Optional user identifier for scoping
+            agent_id: Optional agent identifier for scoping
+            run_id: Optional run identifier for scoping
+            limit: Maximum number of results
+            filters: Optional metadata filters
+            **kwargs: Backend-specific options
+            
+        Returns:
+            SearchResult with normalized items (metadata always dict)
+        """
+        ...
+    
+    def add(
+        self,
+        content: Any,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> AddResult:
+        """
+        Add content to the knowledge store.
+        
+        Args:
+            content: Content to add (string, file path, or structured data)
+            user_id: Optional user identifier for scoping
+            agent_id: Optional agent identifier for scoping
+            run_id: Optional run identifier for scoping
+            metadata: Optional metadata to attach
+            **kwargs: Backend-specific options
+            
+        Returns:
+            AddResult with operation status
+        """
+        ...
+    
+    def get(
+        self,
+        item_id: str,
+        **kwargs: Any,
+    ) -> Optional[SearchResultItem]:
+        """
+        Get a specific item by ID.
+        
+        Args:
+            item_id: ID of the item to retrieve
+            **kwargs: Backend-specific options
+            
+        Returns:
+            SearchResultItem if found, None otherwise
+        """
+        ...
+    
+    def get_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        limit: int = 100,
+        **kwargs: Any,
+    ) -> SearchResult:
+        """
+        Get all items, optionally filtered by scope.
+        
+        Args:
+            user_id: Optional user identifier for scoping
+            agent_id: Optional agent identifier for scoping
+            run_id: Optional run identifier for scoping
+            limit: Maximum number of results
+            **kwargs: Backend-specific options
+            
+        Returns:
+            SearchResult with all matching items
+        """
+        ...
+    
+    def update(
+        self,
+        item_id: str,
+        content: Any,
+        **kwargs: Any,
+    ) -> AddResult:
+        """
+        Update an existing item.
+        
+        Args:
+            item_id: ID of the item to update
+            content: New content
+            **kwargs: Backend-specific options
+            
+        Returns:
+            AddResult with operation status
+        """
+        ...
+    
+    def delete(
+        self,
+        item_id: str,
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Delete an item by ID.
+        
+        Args:
+            item_id: ID of the item to delete
+            **kwargs: Backend-specific options
+            
+        Returns:
+            True if deleted, False otherwise
+        """
+        ...
+    
+    def delete_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Delete all items matching scope.
+        
+        Args:
+            user_id: Optional user identifier for scoping
+            agent_id: Optional agent identifier for scoping
+            run_id: Optional run identifier for scoping
+            **kwargs: Backend-specific options
+            
+        Returns:
+            True if operation succeeded
+        """
+        ...
+
+
+class KnowledgeBackendError(Exception):
+    """Base exception for knowledge backend errors."""
+    pass
+
+
+class ScopeRequiredError(KnowledgeBackendError):
+    """Raised when required scope identifiers are missing."""
+    
+    def __init__(self, message: str = None, backend: str = None):
+        self.backend = backend
+        default_msg = (
+            f"At least one of 'user_id', 'agent_id', or 'run_id' must be provided"
+            f"{f' for {backend} backend' if backend else ''}."
+        )
+        super().__init__(message or default_msg)
+
+
+class BackendNotAvailableError(KnowledgeBackendError):
+    """Raised when a requested backend is not available."""
+    
+    def __init__(self, backend: str, reason: str = None):
+        self.backend = backend
+        self.reason = reason
+        msg = f"Knowledge backend '{backend}' is not available"
+        if reason:
+            msg += f": {reason}"
+        super().__init__(msg)

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

@@ -58,6 +58,12 @@ class LLM:
     # Class-level flag for one-time logging configuration
     _logging_configured = False
     
+    # Class-level cache for LiteLLM module (avoids repeated import overhead)
+    _litellm_module = None
+    
+    # Class-level flag for LiteLLM global settings (set once)
+    _litellm_configured = False
+    
     # Default window sizes for different models (75% of actual to be safe)
     MODEL_WINDOWS = {
         # OpenAI
@@ -272,14 +278,16 @@ Respond with ONLY a valid JSON tool call in this format:
         if not LLM._logging_configured:
             LLM._configure_logging()
             
-        # Import litellm after logging is configured
-        try:
-            import litellm
-        except ImportError:
-            raise ImportError(
-                "LiteLLM is required but not installed. "
-                "Please install with: pip install 'praisonaiagents[llm]'"
-            )
+        # Use cached LiteLLM module or import once (avoids repeated import overhead)
+        if LLM._litellm_module is None:
+            try:
+                import litellm
+                LLM._litellm_module = litellm
+            except ImportError:
+                raise ImportError(
+                    "LiteLLM is required but not installed. "
+                    "Please install with: pip install 'praisonaiagents[llm]'"
+                )
 
         self.model = model
         self.timeout = timeout
@@ -341,11 +349,12 @@ Respond with ONLY a valid JSON tool call in this format:
         self._formatted_tools_cache = {}
         self._max_cache_size = 100
         
-        # Enable error dropping for cleaner output
-        import litellm
-        litellm.drop_params = True
-        # Enable parameter modification for providers like Anthropic
-        litellm.modify_params = True
+        # Configure LiteLLM global settings only once (avoids repeated setup cost)
+        if not LLM._litellm_configured:
+            litellm = LLM._litellm_module
+            litellm.drop_params = True
+            litellm.modify_params = True
+            LLM._litellm_configured = True
         self._setup_event_tracking(events)
         
         # Log all initialization parameters when in debug mode or verbose >= 10

src/praisonai-agents/praisonaiagents/mcp/mcp_utils.py

@@ -236,3 +236,46 @@ def functions_to_mcp_tools(functions: List[Callable]) -> List[Dict[str, Any]]:
         List of MCP tool schemas
     """
     return [function_to_mcp_schema(func) for func in functions]
+
+
+def filter_disabled_tools(
+    tools: List[Dict[str, Any]], 
+    disabled_tools: List[str]
+) -> List[Dict[str, Any]]:
+    """
+    Filter out disabled tools from a tool list.
+    
+    Args:
+        tools: List of tool definitions (dicts with 'name' key)
+        disabled_tools: List of tool names to disable
+        
+    Returns:
+        Filtered list of tools
+    """
+    if not disabled_tools:
+        return tools
+        
+    disabled_set = set(disabled_tools)
+    return [t for t in tools if t.get("name") not in disabled_set]
+
+
+def filter_tools_by_allowlist(
+    tools: List[Dict[str, Any]], 
+    allowed_tools: List[str]
+) -> List[Dict[str, Any]]:
+    """
+    Filter tools to only include those in allowlist.
+    
+    Args:
+        tools: List of tool definitions (dicts with 'name' key)
+        allowed_tools: List of tool names to allow (empty = allow all)
+        
+    Returns:
+        Filtered list of tools
+    """
+    if not allowed_tools:
+        return tools
+        
+    allowed_set = set(allowed_tools)
+    return [t for t in tools if t.get("name") in allowed_set]
+

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

@@ -0,0 +1,62 @@
+"""
+Permissions Module for PraisonAI Agents.
+
+Provides pattern-based permission rules, persistent approvals,
+and doom loop detection for safe agent execution.
+
+Features:
+- Pattern-based permission rules (allow, deny, ask)
+- Persistent approval storage
+- Per-agent permission rulesets
+- Doom loop detection and prevention
+- Integration with existing approval system
+
+Usage:
+    from praisonaiagents.permissions import PermissionManager, PermissionRule
+    
+    # Create permission manager
+    manager = PermissionManager()
+    
+    # Add rules
+    manager.add_rule(PermissionRule(
+        pattern="bash:*",
+        action="ask",
+        description="Require approval for shell commands"
+    ))
+    
+    # Check permission
+    result = manager.check("bash:rm -rf /tmp/test")
+"""
+
+__all__ = [
+    "PermissionManager",
+    "PermissionRule",
+    "PermissionAction",
+    "PermissionResult",
+    "DoomLoopDetector",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load module components."""
+    if name == "PermissionManager":
+        from .manager import PermissionManager
+        return PermissionManager
+    
+    if name == "PermissionRule":
+        from .rules import PermissionRule
+        return PermissionRule
+    
+    if name == "PermissionAction":
+        from .rules import PermissionAction
+        return PermissionAction
+    
+    if name == "PermissionResult":
+        from .rules import PermissionResult
+        return PermissionResult
+    
+    if name == "DoomLoopDetector":
+        from .doom_loop import DoomLoopDetector
+        return DoomLoopDetector
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai-agents/praisonaiagents/permissions/doom_loop.py

@@ -0,0 +1,256 @@
+"""
+Doom Loop Detection for PraisonAI Agents.
+
+Detects and prevents agents from getting stuck in repetitive loops.
+"""
+
+import logging
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Default thresholds
+DEFAULT_LOOP_THRESHOLD = 3
+DEFAULT_WINDOW_SECONDS = 60
+DEFAULT_MAX_TOOL_CALLS = 50
+
+
+@dataclass
+class ToolCallRecord:
+    """Record of a tool call for loop detection."""
+    
+    tool_name: str
+    arguments_hash: str
+    timestamp: float = field(default_factory=time.time)
+    session_id: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "tool_name": self.tool_name,
+            "arguments_hash": self.arguments_hash,
+            "timestamp": self.timestamp,
+            "session_id": self.session_id,
+        }
+
+
+@dataclass
+class DoomLoopResult:
+    """Result of a doom loop check."""
+    
+    is_loop: bool
+    reason: str = ""
+    loop_count: int = 0
+    tool_name: Optional[str] = None
+    recommendation: str = ""
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "is_loop": self.is_loop,
+            "reason": self.reason,
+            "loop_count": self.loop_count,
+            "tool_name": self.tool_name,
+            "recommendation": self.recommendation,
+        }
+
+
+class DoomLoopDetector:
+    """
+    Detects and prevents doom loops in agent execution.
+    
+    A doom loop occurs when an agent repeatedly calls the same
+    tool with the same arguments, indicating it's stuck.
+    
+    Example:
+        detector = DoomLoopDetector()
+        
+        # Record tool calls
+        detector.record("bash", {"command": "ls"})
+        detector.record("bash", {"command": "ls"})
+        detector.record("bash", {"command": "ls"})
+        
+        # Check for loop
+        result = detector.check("bash", {"command": "ls"})
+        if result.is_loop:
+            print(f"Doom loop detected: {result.reason}")
+    """
+    
+    def __init__(
+        self,
+        loop_threshold: int = DEFAULT_LOOP_THRESHOLD,
+        window_seconds: float = DEFAULT_WINDOW_SECONDS,
+        max_tool_calls: int = DEFAULT_MAX_TOOL_CALLS,
+    ):
+        """
+        Initialize the doom loop detector.
+        
+        Args:
+            loop_threshold: Number of identical calls to trigger loop detection
+            window_seconds: Time window for counting calls
+            max_tool_calls: Maximum total tool calls before warning
+        """
+        self.loop_threshold = loop_threshold
+        self.window_seconds = window_seconds
+        self.max_tool_calls = max_tool_calls
+        
+        self._records: List[ToolCallRecord] = []
+        self._call_counts: Dict[str, int] = defaultdict(int)
+        self._session_id: Optional[str] = None
+    
+    def set_session(self, session_id: str):
+        """Set the current session ID."""
+        self._session_id = session_id
+    
+    def _hash_arguments(self, arguments: Dict[str, Any]) -> str:
+        """Create a hash of tool arguments."""
+        import hashlib
+        import json
+        
+        try:
+            arg_str = json.dumps(arguments, sort_keys=True, default=str)
+            return hashlib.md5(arg_str.encode()).hexdigest()[:16]
+        except (TypeError, ValueError):
+            return "unhashable"
+    
+    def _cleanup_old_records(self):
+        """Remove records outside the time window."""
+        cutoff = time.time() - self.window_seconds
+        self._records = [r for r in self._records if r.timestamp > cutoff]
+    
+    def record(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> ToolCallRecord:
+        """
+        Record a tool call.
+        
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+            
+        Returns:
+            The recorded ToolCallRecord
+        """
+        self._cleanup_old_records()
+        
+        args_hash = self._hash_arguments(arguments or {})
+        
+        record = ToolCallRecord(
+            tool_name=tool_name,
+            arguments_hash=args_hash,
+            session_id=self._session_id,
+        )
+        
+        self._records.append(record)
+        self._call_counts[tool_name] += 1
+        
+        return record
+    
+    def check(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> DoomLoopResult:
+        """
+        Check if calling this tool would indicate a doom loop.
+        
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+            
+        Returns:
+            DoomLoopResult indicating if a loop is detected
+        """
+        self._cleanup_old_records()
+        
+        args_hash = self._hash_arguments(arguments or {})
+        
+        # Count identical calls in window
+        identical_count = sum(
+            1 for r in self._records
+            if r.tool_name == tool_name and r.arguments_hash == args_hash
+        )
+        
+        # Check for loop
+        if identical_count >= self.loop_threshold:
+            return DoomLoopResult(
+                is_loop=True,
+                reason=f"Tool '{tool_name}' called {identical_count} times with same arguments",
+                loop_count=identical_count,
+                tool_name=tool_name,
+                recommendation="Consider a different approach or ask for user guidance",
+            )
+        
+        # Check for excessive tool calls
+        total_calls = len(self._records)
+        if total_calls >= self.max_tool_calls:
+            return DoomLoopResult(
+                is_loop=True,
+                reason=f"Excessive tool calls ({total_calls}) in time window",
+                loop_count=total_calls,
+                recommendation="Reduce tool usage or break task into smaller steps",
+            )
+        
+        # Check for tool-specific excessive calls
+        tool_count = self._call_counts.get(tool_name, 0)
+        if tool_count >= self.max_tool_calls // 2:
+            return DoomLoopResult(
+                is_loop=True,
+                reason=f"Tool '{tool_name}' called excessively ({tool_count} times)",
+                loop_count=tool_count,
+                tool_name=tool_name,
+                recommendation=f"Consider alternative to '{tool_name}'",
+            )
+        
+        return DoomLoopResult(
+            is_loop=False,
+            loop_count=identical_count,
+            tool_name=tool_name,
+        )
+    
+    def record_and_check(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> DoomLoopResult:
+        """
+        Record a tool call and check for doom loop.
+        
+        Convenience method that combines record() and check().
+        
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+            
+        Returns:
+            DoomLoopResult indicating if a loop is detected
+        """
+        result = self.check(tool_name, arguments)
+        if not result.is_loop:
+            self.record(tool_name, arguments)
+        return result
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about tool calls."""
+        self._cleanup_old_records()
+        
+        return {
+            "total_calls": len(self._records),
+            "unique_tools": len(set(r.tool_name for r in self._records)),
+            "call_counts": dict(self._call_counts),
+            "window_seconds": self.window_seconds,
+            "loop_threshold": self.loop_threshold,
+        }
+    
+    def reset(self):
+        """Reset all records."""
+        self._records.clear()
+        self._call_counts.clear()
+    
+    def reset_tool(self, tool_name: str):
+        """Reset records for a specific tool."""
+        self._records = [r for r in self._records if r.tool_name != tool_name]
+        self._call_counts.pop(tool_name, None)

src/praisonai-agents/praisonaiagents/permissions/manager.py

@@ -0,0 +1,359 @@
+"""
+Permission Manager for PraisonAI Agents.
+
+Manages permission rules, persistent approvals, and integrates
+with doom loop detection.
+"""
+
+import json
+import logging
+import os
+import threading
+from typing import Any, Callable, Dict, List, Optional
+
+from .rules import PermissionRule, PermissionAction, PermissionResult, PersistentApproval
+from .doom_loop import DoomLoopDetector
+
+logger = logging.getLogger(__name__)
+
+# Default storage path
+DEFAULT_PERMISSIONS_DIR = os.path.expanduser("~/.praison/permissions")
+
+
+class PermissionManager:
+    """
+    Manages permission rules and approvals.
+    
+    Provides pattern-based permission checking with persistent
+    approval storage and doom loop detection.
+    
+    Example:
+        manager = PermissionManager()
+        
+        # Add rules
+        manager.add_rule(PermissionRule(
+            pattern="bash:rm *",
+            action=PermissionAction.ASK,
+            description="Require approval for rm commands"
+        ))
+        
+        manager.add_rule(PermissionRule(
+            pattern="read:*",
+            action=PermissionAction.ALLOW,
+            description="Allow all read operations"
+        ))
+        
+        # Check permission
+        result = manager.check("bash:rm -rf /tmp/test")
+        if result.needs_approval:
+            # Ask user
+            approved = ask_user(result.target)
+            manager.approve(result.target, approved)
+    """
+    
+    def __init__(
+        self,
+        storage_dir: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        approval_callback: Optional[Callable[[str, str], bool]] = None,
+    ):
+        """
+        Initialize the permission manager.
+        
+        Args:
+            storage_dir: Directory for persistent storage
+            agent_name: Optional agent name for filtering rules
+            approval_callback: Optional callback for user approval
+        """
+        self.storage_dir = storage_dir or DEFAULT_PERMISSIONS_DIR
+        self.agent_name = agent_name
+        self.approval_callback = approval_callback
+        
+        self._rules: List[PermissionRule] = []
+        self._approvals: List[PersistentApproval] = []
+        self._doom_detector = DoomLoopDetector()
+        self._lock = threading.RLock()
+        
+        # Ensure storage directory exists
+        os.makedirs(self.storage_dir, exist_ok=True)
+        
+        # Load persistent data
+        self._load_rules()
+        self._load_approvals()
+    
+    def _get_rules_path(self) -> str:
+        """Get path to rules file."""
+        return os.path.join(self.storage_dir, "rules.json")
+    
+    def _get_approvals_path(self) -> str:
+        """Get path to approvals file."""
+        return os.path.join(self.storage_dir, "approvals.json")
+    
+    def _load_rules(self):
+        """Load rules from disk."""
+        path = self._get_rules_path()
+        if os.path.exists(path):
+            try:
+                with open(path, "r") as f:
+                    data = json.load(f)
+                self._rules = [PermissionRule.from_dict(r) for r in data]
+            except (json.JSONDecodeError, IOError) as e:
+                logger.warning(f"Failed to load rules: {e}")
+    
+    def _save_rules(self):
+        """Save rules to disk."""
+        path = self._get_rules_path()
+        try:
+            with open(path, "w") as f:
+                json.dump([r.to_dict() for r in self._rules], f, indent=2)
+        except IOError as e:
+            logger.error(f"Failed to save rules: {e}")
+    
+    def _load_approvals(self):
+        """Load approvals from disk."""
+        path = self._get_approvals_path()
+        if os.path.exists(path):
+            try:
+                with open(path, "r") as f:
+                    data = json.load(f)
+                self._approvals = [PersistentApproval.from_dict(a) for a in data]
+                # Filter out expired approvals
+                self._approvals = [a for a in self._approvals if a.is_valid()]
+            except (json.JSONDecodeError, IOError) as e:
+                logger.warning(f"Failed to load approvals: {e}")
+    
+    def _save_approvals(self):
+        """Save approvals to disk."""
+        path = self._get_approvals_path()
+        try:
+            # Filter out expired and one-time approvals
+            persistent = [
+                a for a in self._approvals
+                if a.is_valid() and a.scope in ("session", "always")
+            ]
+            with open(path, "w") as f:
+                json.dump([a.to_dict() for a in persistent], f, indent=2)
+        except IOError as e:
+            logger.error(f"Failed to save approvals: {e}")
+    
+    def add_rule(self, rule: PermissionRule) -> str:
+        """
+        Add a permission rule.
+        
+        Args:
+            rule: The rule to add
+            
+        Returns:
+            The rule ID
+        """
+        with self._lock:
+            self._rules.append(rule)
+            # Sort by priority (higher first)
+            self._rules.sort(key=lambda r: r.priority, reverse=True)
+            self._save_rules()
+        return rule.id
+    
+    def remove_rule(self, rule_id: str) -> bool:
+        """
+        Remove a permission rule.
+        
+        Args:
+            rule_id: The rule ID to remove
+            
+        Returns:
+            True if found and removed
+        """
+        with self._lock:
+            for i, rule in enumerate(self._rules):
+                if rule.id == rule_id:
+                    self._rules.pop(i)
+                    self._save_rules()
+                    return True
+        return False
+    
+    def get_rules(self, agent_name: Optional[str] = None) -> List[PermissionRule]:
+        """
+        Get all rules, optionally filtered by agent.
+        
+        Args:
+            agent_name: Optional agent name to filter by
+            
+        Returns:
+            List of matching rules
+        """
+        with self._lock:
+            if agent_name is None:
+                return self._rules.copy()
+            return [
+                r for r in self._rules
+                if r.agent_name is None or r.agent_name == agent_name
+            ]
+    
+    def check(self, target: str, agent_name: Optional[str] = None) -> PermissionResult:
+        """
+        Check permission for a target.
+        
+        Args:
+            target: The target to check (e.g., "bash:rm -rf /tmp")
+            agent_name: Optional agent name
+            
+        Returns:
+            PermissionResult with the decision
+        """
+        agent = agent_name or self.agent_name
+        
+        with self._lock:
+            # Check persistent approvals first
+            for approval in self._approvals:
+                if approval.matches(target, agent):
+                    return PermissionResult(
+                        action=PermissionAction.ALLOW if approval.approved else PermissionAction.DENY,
+                        target=target,
+                        reason=f"Persistent approval: {'approved' if approval.approved else 'denied'}",
+                        approved=approval.approved,
+                    )
+            
+            # Check rules
+            for rule in self._rules:
+                if rule.agent_name and agent and rule.agent_name != agent:
+                    continue
+                
+                if rule.matches(target):
+                    return PermissionResult(
+                        action=rule.action,
+                        rule=rule,
+                        target=target,
+                        reason=rule.description or f"Matched rule: {rule.pattern}",
+                    )
+        
+        # Default: ask
+        return PermissionResult(
+            action=PermissionAction.ASK,
+            target=target,
+            reason="No matching rule, requires approval",
+        )
+    
+    def approve(
+        self,
+        target: str,
+        approved: bool,
+        scope: str = "once",
+        agent_name: Optional[str] = None,
+    ) -> PersistentApproval:
+        """
+        Record an approval decision.
+        
+        Args:
+            target: The target that was approved/denied
+            approved: Whether it was approved
+            scope: Scope of approval (once, session, always)
+            agent_name: Optional agent name
+            
+        Returns:
+            The created PersistentApproval
+        """
+        approval = PersistentApproval(
+            pattern=target,
+            approved=approved,
+            scope=scope,
+            agent_name=agent_name or self.agent_name,
+        )
+        
+        with self._lock:
+            self._approvals.append(approval)
+            if scope in ("session", "always"):
+                self._save_approvals()
+        
+        return approval
+    
+    def check_and_approve(
+        self,
+        target: str,
+        agent_name: Optional[str] = None,
+    ) -> PermissionResult:
+        """
+        Check permission and request approval if needed.
+        
+        Uses the approval_callback if set.
+        
+        Args:
+            target: The target to check
+            agent_name: Optional agent name
+            
+        Returns:
+            PermissionResult with final decision
+        """
+        result = self.check(target, agent_name)
+        
+        if result.needs_approval and self.approval_callback:
+            approved = self.approval_callback(target, result.reason)
+            result.approved = approved
+            self.approve(target, approved, scope="once", agent_name=agent_name)
+        
+        return result
+    
+    def check_doom_loop(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Check for doom loop and record tool call.
+        
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+            
+        Returns:
+            DoomLoopResult
+        """
+        return self._doom_detector.record_and_check(tool_name, arguments)
+    
+    def get_doom_stats(self) -> Dict[str, Any]:
+        """Get doom loop detector statistics."""
+        return self._doom_detector.get_stats()
+    
+    def reset_doom_detector(self):
+        """Reset the doom loop detector."""
+        self._doom_detector.reset()
+    
+    def clear_approvals(self, scope: Optional[str] = None):
+        """
+        Clear approvals.
+        
+        Args:
+            scope: Optional scope to clear (None = all)
+        """
+        with self._lock:
+            if scope is None:
+                self._approvals.clear()
+            else:
+                self._approvals = [a for a in self._approvals if a.scope != scope]
+            self._save_approvals()
+    
+    def clear_rules(self):
+        """Clear all rules."""
+        with self._lock:
+            self._rules.clear()
+            self._save_rules()
+    
+    def set_approval_callback(self, callback: Callable[[str, str], bool]):
+        """Set the approval callback."""
+        self.approval_callback = callback
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Export manager state to dictionary."""
+        with self._lock:
+            return {
+                "rules": [r.to_dict() for r in self._rules],
+                "approvals": [a.to_dict() for a in self._approvals],
+                "agent_name": self.agent_name,
+            }
+    
+    def from_dict(self, data: Dict[str, Any]):
+        """Import manager state from dictionary."""
+        with self._lock:
+            self._rules = [PermissionRule.from_dict(r) for r in data.get("rules", [])]
+            self._approvals = [PersistentApproval.from_dict(a) for a in data.get("approvals", [])]
+            if "agent_name" in data:
+                self.agent_name = data["agent_name"]

src/praisonai-agents/praisonaiagents/permissions/rules.py

@@ -0,0 +1,211 @@
+"""
+Permission rules for PraisonAI Agents.
+
+Provides pattern-based permission rules with allow/deny/ask actions.
+"""
+
+import fnmatch
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class PermissionAction(str, Enum):
+    """Actions for permission rules."""
+    
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+@dataclass
+class PermissionRule:
+    """
+    A pattern-based permission rule.
+    
+    Attributes:
+        pattern: Glob or regex pattern to match against
+        action: What to do when pattern matches (allow/deny/ask)
+        description: Human-readable description
+        is_regex: Whether pattern is a regex (default: glob)
+        priority: Higher priority rules are checked first
+        agent_name: Optional agent name this rule applies to
+        enabled: Whether the rule is active
+    """
+    
+    pattern: str
+    action: PermissionAction = PermissionAction.ASK
+    description: str = ""
+    is_regex: bool = False
+    priority: int = 0
+    agent_name: Optional[str] = None
+    enabled: bool = True
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: float = field(default_factory=time.time)
+    
+    def matches(self, target: str) -> bool:
+        """
+        Check if this rule matches the target.
+        
+        Args:
+            target: The string to match against (e.g., "bash:rm -rf /tmp")
+            
+        Returns:
+            True if the pattern matches
+        """
+        if not self.enabled:
+            return False
+        
+        if self.is_regex:
+            try:
+                return bool(re.match(self.pattern, target))
+            except re.error:
+                return False
+        else:
+            return fnmatch.fnmatch(target, self.pattern)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert rule to dictionary."""
+        return {
+            "id": self.id,
+            "pattern": self.pattern,
+            "action": self.action.value,
+            "description": self.description,
+            "is_regex": self.is_regex,
+            "priority": self.priority,
+            "agent_name": self.agent_name,
+            "enabled": self.enabled,
+            "created_at": self.created_at,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PermissionRule":
+        """Create rule from dictionary."""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            pattern=data.get("pattern", "*"),
+            action=PermissionAction(data.get("action", "ask")),
+            description=data.get("description", ""),
+            is_regex=data.get("is_regex", False),
+            priority=data.get("priority", 0),
+            agent_name=data.get("agent_name"),
+            enabled=data.get("enabled", True),
+            created_at=data.get("created_at", time.time()),
+        )
+
+
+@dataclass
+class PermissionResult:
+    """
+    Result of a permission check.
+    
+    Attributes:
+        action: The resulting action (allow/deny/ask)
+        rule: The rule that matched (if any)
+        target: The target that was checked
+        reason: Human-readable reason
+        approved: Whether the action was approved (for ask actions)
+    """
+    
+    action: PermissionAction
+    rule: Optional[PermissionRule] = None
+    target: str = ""
+    reason: str = ""
+    approved: Optional[bool] = None
+    
+    @property
+    def is_allowed(self) -> bool:
+        """Check if the action is allowed."""
+        if self.action == PermissionAction.ALLOW:
+            return True
+        if self.action == PermissionAction.ASK:
+            return self.approved is True
+        return False
+    
+    @property
+    def is_denied(self) -> bool:
+        """Check if the action is denied."""
+        if self.action == PermissionAction.DENY:
+            return True
+        if self.action == PermissionAction.ASK:
+            return self.approved is False
+        return False
+    
+    @property
+    def needs_approval(self) -> bool:
+        """Check if the action needs user approval."""
+        return self.action == PermissionAction.ASK and self.approved is None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary."""
+        return {
+            "action": self.action.value,
+            "rule_id": self.rule.id if self.rule else None,
+            "target": self.target,
+            "reason": self.reason,
+            "approved": self.approved,
+            "is_allowed": self.is_allowed,
+            "is_denied": self.is_denied,
+            "needs_approval": self.needs_approval,
+        }
+
+
+@dataclass
+class PersistentApproval:
+    """
+    A persistent approval for a pattern.
+    
+    Used to remember user decisions for future requests.
+    """
+    
+    pattern: str
+    approved: bool
+    scope: str = "once"  # once, session, always
+    created_at: float = field(default_factory=time.time)
+    expires_at: Optional[float] = None
+    agent_name: Optional[str] = None
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    
+    def is_valid(self) -> bool:
+        """Check if the approval is still valid."""
+        if self.expires_at and time.time() > self.expires_at:
+            return False
+        return True
+    
+    def matches(self, target: str, agent_name: Optional[str] = None) -> bool:
+        """Check if this approval applies to the target."""
+        if not self.is_valid():
+            return False
+        
+        if self.agent_name and agent_name and self.agent_name != agent_name:
+            return False
+        
+        return fnmatch.fnmatch(target, self.pattern)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert approval to dictionary."""
+        return {
+            "id": self.id,
+            "pattern": self.pattern,
+            "approved": self.approved,
+            "scope": self.scope,
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+            "agent_name": self.agent_name,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PersistentApproval":
+        """Create approval from dictionary."""
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            pattern=data.get("pattern", "*"),
+            approved=data.get("approved", False),
+            scope=data.get("scope", "once"),
+            created_at=data.get("created_at", time.time()),
+            expires_at=data.get("expires_at"),
+            agent_name=data.get("agent_name"),
+        )

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

@@ -0,0 +1,47 @@
+"""
+Plugin Module for PraisonAI Agents.
+
+Provides dynamic plugin loading and hook-based extension system.
+
+Features:
+- Dynamic plugin discovery and loading
+- Hook-based extension points
+- Tool plugins
+- Auth plugins
+- Configuration plugins
+
+Usage:
+    from praisonaiagents.plugins import PluginManager
+    
+    # Create plugin manager
+    manager = PluginManager()
+    
+    # Load plugins from directory
+    manager.load_from_directory("./plugins")
+    
+    # Get loaded plugins
+    plugins = manager.list_plugins()
+"""
+
+__all__ = [
+    "PluginManager",
+    "Plugin",
+    "PluginHook",
+]
+
+
+def __getattr__(name: str):
+    """Lazy load module components."""
+    if name == "PluginManager":
+        from .manager import PluginManager
+        return PluginManager
+    
+    if name == "Plugin":
+        from .plugin import Plugin
+        return Plugin
+    
+    if name == "PluginHook":
+        from .plugin import PluginHook
+        return PluginHook
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai-agents/praisonaiagents/plugins/manager.py

@@ -0,0 +1,299 @@
+"""
+Plugin Manager for PraisonAI Agents.
+
+Provides dynamic plugin discovery, loading, and lifecycle management.
+"""
+
+import importlib.util
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Type
+
+from .plugin import Plugin, PluginHook, PluginInfo, FunctionPlugin
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """
+    Manages plugin discovery, loading, and execution.
+    
+    Example:
+        manager = PluginManager()
+        
+        # Load plugins from directory
+        manager.load_from_directory("./plugins")
+        
+        # Register a plugin directly
+        manager.register(MyPlugin())
+        
+        # Execute hooks
+        args = manager.execute_hook(PluginHook.BEFORE_TOOL, "bash", {"cmd": "ls"})
+    """
+    
+    def __init__(self):
+        self._plugins: Dict[str, Plugin] = {}
+        self._enabled: Dict[str, bool] = {}
+    
+    def register(self, plugin: Plugin) -> bool:
+        """
+        Register a plugin.
+        
+        Args:
+            plugin: The plugin to register
+            
+        Returns:
+            True if registered successfully
+        """
+        try:
+            info = plugin.info
+            if info.name in self._plugins:
+                logger.warning(f"Plugin '{info.name}' already registered")
+                return False
+            
+            self._plugins[info.name] = plugin
+            self._enabled[info.name] = True
+            
+            # Initialize plugin
+            plugin.on_init({})
+            
+            logger.info(f"Registered plugin: {info.name} v{info.version}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to register plugin: {e}")
+            return False
+    
+    def unregister(self, name: str) -> bool:
+        """
+        Unregister a plugin.
+        
+        Args:
+            name: The plugin name
+            
+        Returns:
+            True if unregistered successfully
+        """
+        if name not in self._plugins:
+            return False
+        
+        try:
+            plugin = self._plugins[name]
+            plugin.on_shutdown()
+        except Exception as e:
+            logger.warning(f"Error during plugin shutdown: {e}")
+        
+        del self._plugins[name]
+        del self._enabled[name]
+        
+        logger.info(f"Unregistered plugin: {name}")
+        return True
+    
+    def enable(self, name: str) -> bool:
+        """Enable a plugin."""
+        if name in self._enabled:
+            self._enabled[name] = True
+            return True
+        return False
+    
+    def disable(self, name: str) -> bool:
+        """Disable a plugin."""
+        if name in self._enabled:
+            self._enabled[name] = False
+            return True
+        return False
+    
+    def is_enabled(self, name: str) -> bool:
+        """Check if a plugin is enabled."""
+        return self._enabled.get(name, False)
+    
+    def get_plugin(self, name: str) -> Optional[Plugin]:
+        """Get a plugin by name."""
+        return self._plugins.get(name)
+    
+    def list_plugins(self) -> List[PluginInfo]:
+        """List all registered plugins."""
+        return [p.info for p in self._plugins.values()]
+    
+    def load_from_directory(self, directory: str) -> int:
+        """
+        Load plugins from a directory.
+        
+        Looks for Python files with a `create_plugin` function
+        or classes that inherit from Plugin.
+        
+        Args:
+            directory: Path to the plugins directory
+            
+        Returns:
+            Number of plugins loaded
+        """
+        directory = Path(directory)
+        if not directory.exists():
+            logger.warning(f"Plugin directory does not exist: {directory}")
+            return 0
+        
+        loaded = 0
+        
+        for file_path in directory.glob("*.py"):
+            if file_path.name.startswith("_"):
+                continue
+            
+            try:
+                plugin = self._load_plugin_file(file_path)
+                if plugin and self.register(plugin):
+                    loaded += 1
+            except Exception as e:
+                logger.error(f"Failed to load plugin from {file_path}: {e}")
+        
+        return loaded
+    
+    def _load_plugin_file(self, file_path: Path) -> Optional[Plugin]:
+        """Load a plugin from a Python file."""
+        module_name = f"praison_plugin_{file_path.stem}"
+        
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            return None
+        
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            logger.error(f"Error loading module {file_path}: {e}")
+            del sys.modules[module_name]
+            return None
+        
+        # Look for create_plugin function
+        if hasattr(module, "create_plugin"):
+            return module.create_plugin()
+        
+        # Look for Plugin subclass
+        for name in dir(module):
+            obj = getattr(module, name)
+            if (
+                isinstance(obj, type)
+                and issubclass(obj, Plugin)
+                and obj is not Plugin
+                and obj is not FunctionPlugin
+            ):
+                return obj()
+        
+        return None
+    
+    def load_from_module(self, module_path: str) -> bool:
+        """
+        Load a plugin from a module path.
+        
+        Args:
+            module_path: Dotted module path (e.g., "mypackage.plugins.myplugin")
+            
+        Returns:
+            True if loaded successfully
+        """
+        try:
+            module = importlib.import_module(module_path)
+            
+            if hasattr(module, "create_plugin"):
+                plugin = module.create_plugin()
+                return self.register(plugin)
+            
+            # Look for Plugin subclass
+            for name in dir(module):
+                obj = getattr(module, name)
+                if (
+                    isinstance(obj, type)
+                    and issubclass(obj, Plugin)
+                    and obj is not Plugin
+                    and obj is not FunctionPlugin
+                ):
+                    return self.register(obj())
+            
+            return False
+        except Exception as e:
+            logger.error(f"Failed to load plugin from module {module_path}: {e}")
+            return False
+    
+    def execute_hook(
+        self,
+        hook: PluginHook,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Execute a hook across all enabled plugins.
+        
+        Args:
+            hook: The hook to execute
+            *args: Arguments to pass to hook
+            **kwargs: Keyword arguments to pass to hook
+            
+        Returns:
+            The result (may be modified by plugins)
+        """
+        result = args[0] if args else None
+        
+        for name, plugin in self._plugins.items():
+            if not self._enabled.get(name, False):
+                continue
+            
+            if hook not in plugin.info.hooks:
+                continue
+            
+            try:
+                method = getattr(plugin, hook.value, None)
+                if method:
+                    if hook == PluginHook.BEFORE_TOOL:
+                        result = method(args[0], args[1] if len(args) > 1 else {})
+                    elif hook == PluginHook.AFTER_TOOL:
+                        result = method(args[0], args[1] if len(args) > 1 else None)
+                    elif hook == PluginHook.BEFORE_AGENT:
+                        result = method(args[0], kwargs.get("context", {}))
+                    elif hook == PluginHook.AFTER_AGENT:
+                        result = method(args[0], kwargs.get("context", {}))
+                    elif hook == PluginHook.BEFORE_LLM:
+                        result = method(args[0], args[1] if len(args) > 1 else {})
+                    elif hook == PluginHook.AFTER_LLM:
+                        result = method(args[0], kwargs.get("usage", {}))
+                    else:
+                        result = method(*args, **kwargs)
+            except Exception as e:
+                logger.error(f"Error executing hook {hook.value} in plugin {name}: {e}")
+        
+        return result
+    
+    def get_all_tools(self) -> List[Dict[str, Any]]:
+        """Get all tools from all enabled plugins."""
+        tools = []
+        
+        for name, plugin in self._plugins.items():
+            if not self._enabled.get(name, False):
+                continue
+            
+            try:
+                plugin_tools = plugin.get_tools()
+                tools.extend(plugin_tools)
+            except Exception as e:
+                logger.error(f"Error getting tools from plugin {name}: {e}")
+        
+        return tools
+    
+    def shutdown(self):
+        """Shutdown all plugins."""
+        for name in list(self._plugins.keys()):
+            self.unregister(name)
+
+
+# Global plugin manager instance
+_default_manager: Optional[PluginManager] = None
+
+
+def get_plugin_manager() -> PluginManager:
+    """Get the global plugin manager."""
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = PluginManager()
+    return _default_manager