Release v3.4.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.7.9" \
+    "praisonai>=3.4.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.7.9" \
+    "praisonai>=3.4.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.7.9" \
+    "praisonai>=3.4.0" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

docs/templates-cli.md

@@ -1,53 +0,0 @@
-# Templates CLI
-
-```bash
-praisonai templates list
-```
-
-```bash
-praisonai templates search video
-```
-
-```bash
-praisonai templates info ai-video-editor
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --offline
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --output edited.mp4 --strict-tools
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --tools ./my_tools.py
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --tools-dir ./tools
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --tools-source praisonai_tools.video
-```
-
-```bash
-praisonai templates run ai-video-editor --input video.mp4 --no-template-tools-py
-```
-
-```bash
-praisonai templates init my-project --template ai-video-editor
-```
-
-```bash
-praisonai templates cache clear
-```
-
-```bash
-praisonai templates cache list
-```

docs/templates-module.md

@@ -1,104 +0,0 @@
-# Templates Module
-
-## Loading Templates
-
-```python
-from praisonai.templates.loader import TemplateLoader
-
-loader = TemplateLoader()
-
-# Load from local path
-template = loader.load("./my-template")
-
-# Load from URI
-template = loader.load("ai-video-editor")
-
-# Load offline
-template = loader.load("ai-video-editor", offline=True)
-
-# Check requirements
-missing = loader.check_requirements(template)
-```
-
-## Template Discovery
-
-```python
-from praisonai.templates.discovery import TemplateDiscovery
-
-discovery = TemplateDiscovery(
-    include_package=True,
-    include_defaults=True,
-)
-
-# Find template
-result = discovery.find_template("ai-video-editor")
-
-# List all templates
-templates = discovery.list_templates()
-```
-
-## Template Config
-
-```python
-from praisonai.templates.loader import TemplateConfig
-
-# Access template properties
-template.name
-template.description
-template.version
-template.author
-template.requires
-template.workflow_file
-template.agents_file
-template.path
-```
-
-## Tool Override Integration
-
-```python
-from praisonai.templates.tool_override import (
-    create_tool_registry_with_overrides,
-    resolve_tools,
-)
-
-# Build registry with template sources
-tools_sources = template.requires.get("tools_sources", [])
-
-registry = create_tool_registry_with_overrides(
-    tools_sources=tools_sources,
-    template_dir=str(template.path),
-    include_defaults=True,
-)
-
-# Resolve tool names
-tools = resolve_tools(["shell_tool"], registry=registry)
-```
-
-## TEMPLATE.yaml Schema
-
-```yaml
-name: my-template
-version: "1.0.0"
-description: Template description
-
-requires:
-  tools: [shell_tool]
-  packages: [praisonai-tools]
-  env: [OPENAI_API_KEY]
-  tools_sources:
-    - praisonai_tools.video
-    - ./local_tools.py
-
-workflow: workflow.yaml
-agents: agents.yaml
-
-config:
-  input:
-    type: string
-    required: true
-  output:
-    type: string
-
-defaults:
-  preset: podcast
-```

docs/tools-cli.md

@@ -1,65 +0,0 @@
-# Tools CLI
-
-```bash
-praisonai tools list
-```
-
-```bash
-praisonai tools info shell_tool
-```
-
-```bash
-praisonai tools info internet_search
-```
-
-```bash
-praisonai tools search "web"
-```
-
-```bash
-praisonai tools search "file"
-```
-
-```bash
-praisonai tools doctor
-```
-
-```bash
-praisonai tools doctor --json
-```
-
-```bash
-praisonai tools resolve shell_tool
-```
-
-```bash
-praisonai tools resolve internet_search --template ai-video-editor
-```
-
-```bash
-praisonai tools resolve my_tool --tools ./my_tools.py
-```
-
-```bash
-praisonai tools resolve my_tool --tools-dir ./tools
-```
-
-```bash
-praisonai tools discover
-```
-
-```bash
-praisonai tools discover --include praisonai_tools.video
-```
-
-```bash
-praisonai tools discover --entrypoints
-```
-
-```bash
-praisonai tools show-sources
-```
-
-```bash
-praisonai tools show-sources --template ai-video-editor
-```

docs/tools-module.md

@@ -1,90 +0,0 @@
-# Tools Module
-
-## Tool Registry
-
-```python
-from praisonai.templates.tool_override import (
-    create_tool_registry_with_overrides,
-    resolve_tools,
-)
-
-# Create registry with defaults
-registry = create_tool_registry_with_overrides(include_defaults=True)
-
-# Create registry with overrides
-registry = create_tool_registry_with_overrides(
-    override_files=["my_tools.py"],
-    override_dirs=["./tools"],
-    include_defaults=True,
-)
-
-# Create registry with tools_sources
-registry = create_tool_registry_with_overrides(
-    tools_sources=["praisonai_tools.video"],
-    template_dir="./my-template",
-    include_defaults=True,
-)
-
-# Resolve tool names to callables
-tools = resolve_tools(
-    ["shell_tool", "internet_search"],
-    registry=registry,
-)
-```
-
-## Tool Override Loader
-
-```python
-from praisonai.templates.tool_override import ToolOverrideLoader
-
-loader = ToolOverrideLoader()
-
-# Load from file
-tools = loader.load_from_file("my_tools.py")
-
-# Load from directory
-tools = loader.load_from_directory("./tools")
-
-# Load from module
-tools = loader.load_from_module("praisonai_tools.video")
-
-# Get default tool directories
-dirs = loader.get_default_tool_dirs()
-```
-
-## Resolution Order
-
-1. CLI `--tools` files (highest priority)
-2. CLI `--tools-dir` directories
-3. Template `tools_sources` (from TEMPLATE.yaml)
-4. Template-local `tools.py`
-5. Default dirs (`~/.praison/tools`, `~/.config/praison/tools`)
-6. Package discovery (`praisonai_tools`)
-7. Built-in tools (lowest priority)
-
-## Creating Custom Tools
-
-```python
-from praisonai_tools import tool
-
-@tool
-def my_custom_tool(query: str) -> str:
-    """My custom tool description.
-    
-    Args:
-        query: The search query
-    """
-    return f"Result for: {query}"
-```
-
-## Template tools_sources
-
-```yaml
-# TEMPLATE.yaml
-requires:
-  tools: [shell_tool]
-  tools_sources:
-    - praisonai_tools.video
-    - ./local_tools.py
-    - ./tools_dir/
-```

examples/acp/README.md

@@ -0,0 +1,137 @@
+# ACP (Agent Client Protocol) Examples
+
+This directory contains examples for using PraisonAI with the Agent Client Protocol (ACP).
+
+## What is ACP?
+
+The Agent Client Protocol (ACP) is a standardized JSON-RPC 2.0 protocol that allows code editors and IDEs to communicate with AI coding agents. It enables seamless integration between PraisonAI and editors like:
+
+- **Zed**
+- **JetBrains IDEs** (IntelliJ, PyCharm, WebStorm, etc.)
+- **VSCode** (via extensions)
+- **Toad**
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Start ACP server with defaults
+praisonai acp
+
+# Enable debug logging
+praisonai acp --debug
+
+# Allow file writes
+praisonai acp --allow-write
+
+# Use a specific model
+praisonai acp -m gpt-4o
+
+# Resume last session
+praisonai acp --resume --last
+```
+
+### Python API
+
+```python
+from praisonai.acp import serve
+
+serve(
+    workspace=".",
+    debug=True,
+    allow_write=True,
+)
+```
+
+## Editor Configuration
+
+### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "PraisonAI": {
+      "command": "praisonai",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### JetBrains
+
+Add to `~/.jetbrains/acp.json`:
+
+```json
+{
+  "agent_servers": {
+    "PraisonAI": {
+      "command": "praisonai",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Toad
+
+```bash
+toad acp "praisonai acp"
+```
+
+## Examples
+
+- `basic_acp_server.py` - Simple ACP server with default settings
+- `custom_agent_acp.py` - ACP server with a custom agent
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-w, --workspace` | Workspace root directory |
+| `-a, --agent` | Agent name or config file |
+| `-m, --model` | LLM model to use |
+| `-r, --resume` | Resume session by ID |
+| `--last` | Resume the last session |
+| `--approve` | Approval mode: manual, auto, scoped |
+| `--read-only` | Read-only mode (default) |
+| `--allow-write` | Allow file writes |
+| `--allow-shell` | Allow shell commands |
+| `--debug` | Enable debug logging |
+
+## Installation
+
+```bash
+pip install praisonai[acp]
+```
+
+## Protocol Details
+
+ACP uses JSON-RPC 2.0 over stdio:
+- **stdin**: Receives JSON-RPC requests from the client
+- **stdout**: Sends JSON-RPC responses to the client
+- **stderr**: Debug/log output (never pollutes stdout)
+
+### Supported Methods
+
+**Agent Methods (client → agent):**
+- `initialize` - Negotiate protocol version and capabilities
+- `authenticate` - Optional authentication
+- `session/new` - Create a new session
+- `session/load` - Load an existing session
+- `session/prompt` - Send user message
+- `session/cancel` - Cancel ongoing operations
+- `session/set_mode` - Change operating mode
+
+**Client Methods (agent → client):**
+- `session/update` - Send progress updates
+- `session/request_permission` - Request user approval
+- `fs/read_text_file` - Read file contents
+- `fs/write_text_file` - Write file contents
+- `terminal/create` - Create terminal
+- `terminal/output` - Get terminal output

examples/acp/basic_acp_server.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""
+Basic ACP Server Example
+
+This example demonstrates how to run PraisonAI as an ACP server
+that can be connected to by IDEs like Zed, JetBrains, VSCode, or Toad.
+
+Usage:
+    # Run from command line
+    praisonai acp
+    
+    # Or run this script directly
+    python basic_acp_server.py
+"""
+
+from praisonai.acp import serve
+
+if __name__ == "__main__":
+    # Start ACP server with default settings
+    # This will listen on stdin/stdout for JSON-RPC messages
+    serve(
+        workspace=".",           # Current directory as workspace
+        agent="default",         # Use default agent
+        debug=False,             # Set to True for debug logging to stderr
+        read_only=True,          # Safe by default
+        approval_mode="manual",  # Require approval for actions
+    )

examples/acp/custom_agent_acp.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+Custom Agent ACP Server Example
+
+This example shows how to run a custom PraisonAI agent as an ACP server.
+
+Usage:
+    python custom_agent_acp.py
+"""
+
+from praisonai.acp import serve, ACPServer, ACPConfig
+from praisonaiagents import Agent
+
+# Create a custom agent
+agent = Agent(
+    name="CodeAssistant",
+    instructions="""You are an expert coding assistant. You help users:
+    - Write clean, efficient code
+    - Debug issues
+    - Explain complex concepts
+    - Review code for best practices
+    
+    Always provide clear explanations with your code suggestions.""",
+    model="gpt-4o-mini",
+)
+
+if __name__ == "__main__":
+    # Create config
+    config = ACPConfig(
+        workspace=".",
+        debug=True,
+        allow_write=True,  # Allow file modifications
+        approval_mode="manual",
+    )
+    
+    # Create server with custom agent
+    server = ACPServer(config=config, agent=agent)
+    
+    # Run the server
+    serve(
+        workspace=".",
+        debug=True,
+        allow_write=True,
+        approval_mode="manual",
+    )

examples/agent_centric_api.py

@@ -0,0 +1,158 @@
+"""
+Agent-Centric API Example
+
+Demonstrates the new consolidated feature parameters for PraisonAI Agents.
+These params provide a cleaner, more intuitive API with progressive disclosure.
+
+New Consolidated Params:
+- memory: Union[bool, MemoryConfig, MemoryManager] - Memory and session management
+- knowledge: Union[bool, List[str], KnowledgeConfig, KnowledgeBase] - RAG and retrieval
+- planning: Union[bool, PlanningConfig] - Planning mode
+- reflection: Union[bool, ReflectionConfig] - Self-reflection
+- guardrails: Union[bool, Callable, GuardrailConfig] - Safety validation
+- web: Union[bool, WebConfig] - Web search and fetch
+- context: Union[bool, ManagerConfig, ContextManager] - Context management
+"""
+
+from praisonaiagents import (
+    Agent,
+    # Config classes for progressive disclosure
+    MemoryConfig,
+    KnowledgeConfig,
+    PlanningConfig,
+    ReflectionConfig,
+    GuardrailConfig,
+    WebConfig,
+)
+
+
+def example_simple_enable():
+    """Example 1: Simple boolean enable (easiest)"""
+    print("\n=== Example 1: Simple Boolean Enable ===")
+    
+    agent = Agent(
+        instructions="You are a helpful assistant",
+        memory=True,      # Enable memory with defaults
+        reflection=True,  # Enable self-reflection
+        web=True,         # Enable web search + fetch
+    )
+    print(f"Agent created with memory={agent._memory_instance is not None}")
+    print(f"  self_reflect={agent.self_reflect}")
+    print(f"  web_search={agent.web_search}")
+
+
+def example_with_config():
+    """Example 2: Using config objects (more control)"""
+    print("\n=== Example 2: Using Config Objects ===")
+    
+    agent = Agent(
+        instructions="You are a research assistant",
+        memory=MemoryConfig(
+            backend="file",
+            user_id="researcher_001",
+            auto_memory=True,
+        ),
+        reflection=ReflectionConfig(
+            min_iterations=1,
+            max_iterations=5,
+            llm="gpt-4o-mini",
+        ),
+        web=WebConfig(
+            search=True,
+            fetch=False,  # Only search, no full page fetch
+            max_results=3,
+        ),
+    )
+    print(f"Agent created with user_id={agent.user_id}")
+    print(f"  {agent.max_reflect}")
+    print(f"  web_search={agent.web_search}, web_fetch={agent.web_fetch}")
+
+
+def example_guardrails():
+    """Example 3: Guardrails with callable or config"""
+    print("\n=== Example 3: Guardrails ===")
+    
+    # Option A: Direct callable
+    def my_validator(output):
+        """Simple validator that checks response length."""
+        is_valid = len(output.raw) < 1000
+        return (is_valid, output if is_valid else "Response too long")
+    
+    agent_a = Agent(
+        instructions="Be concise",
+        guardrails=my_validator,  # Direct callable
+    )
+    print(f"Agent A: guardrail is callable = {callable(agent_a.guardrail)}")
+    
+    # Option B: Using GuardrailConfig
+    agent_b = Agent(
+        instructions="Be helpful and safe",
+        guardrails=GuardrailConfig(
+            llm_validator="Ensure the response is helpful, accurate, and safe",
+            max_retries=3,
+        ),
+    )
+    print(f"Agent B: guardrail = {agent_b.guardrail}")
+    print(f"  max_retries = {agent_b.max_guardrail_retries}")
+
+
+def example_planning():
+    """Example 4: Planning mode"""
+    print("\n=== Example 4: Planning Mode ===")
+    
+    agent = Agent(
+        instructions="You are a project planner",
+        planning=PlanningConfig(
+            reasoning=True,
+            read_only=True,  # Plan mode - only read operations
+        ),
+    )
+    print(f"Agent created with planning={agent.planning}")
+    print(f"  plan_mode={agent.plan_mode}")
+    print(f"  planning_reasoning={agent.planning_reasoning}")
+
+
+def example_backward_compatible():
+    """Example 5: Using new consolidated params"""
+    print("\n=== Example 5: Consolidated Params ===")
+    
+    # New consolidated params
+    agent = Agent(
+        instructions="Test agent",
+        reflection=True,
+        web=WebConfig(search=True, fetch=False),
+    )
+    print(f"Consolidated params work: self_reflect={agent.self_reflect}")
+    print(f"  web_search={agent.web_search}, web_fetch={agent.web_fetch}")
+
+
+def example_real_chat():
+    """Example 6: Real chat with new API"""
+    print("\n=== Example 6: Real Chat ===")
+    
+    agent = Agent(
+        instructions="You are a helpful math tutor. Be concise.",
+        reflection=False,
+        web=False,
+        verbose=False,
+    )
+    
+    response = agent.start("What is the square root of 144?")
+    print(f"Response: {response}")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("PraisonAI Agent-Centric API Examples")
+    print("=" * 60)
+    
+    example_simple_enable()
+    example_with_config()
+    example_guardrails()
+    example_planning()
+    example_backward_compatible()
+    example_real_chat()
+    
+    print("\n" + "=" * 60)
+    print("All examples completed!")
+    print("=" * 60)

examples/agent_tools/agent_centric_example.py

@@ -0,0 +1,135 @@
+"""
+Agent-Centric Tools Example
+
+This example demonstrates how to use LSP/ACP-powered tools that make
+the Agent the central orchestrator for file operations.
+
+How to run:
+    export OPENAI_API_KEY=your_key
+    python examples/agent_tools/agent_centric_example.py
+
+Prerequisites:
+    pip install praisonai praisonaiagents
+"""
+
+import asyncio
+import os
+import sys
+import tempfile
+import shutil
+
+# 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'))
+
+
+async def main():
+    print("=" * 60)
+    print("AGENT-CENTRIC TOOLS EXAMPLE")
+    print("=" * 60)
+    print()
+    
+    # Create temporary workspace
+    workspace = tempfile.mkdtemp(prefix="praisonai_example_")
+    print(f"Workspace: {workspace}")
+    print()
+    
+    try:
+        # Import after path setup
+        from praisonai.cli.features import (
+            create_agent_centric_tools,
+            InteractiveRuntime,
+            RuntimeConfig
+        )
+        from praisonaiagents import Agent
+        
+        # 1. Create runtime with ACP enabled
+        print("1. Creating InteractiveRuntime with ACP...")
+        config = RuntimeConfig(
+            workspace=workspace,
+            lsp_enabled=False,  # Skip LSP for this example
+            acp_enabled=True,
+            approval_mode="auto"  # Auto-approve for demo
+        )
+        runtime = InteractiveRuntime(config)
+        status = await runtime.start()
+        
+        print(f"   ACP ready: {runtime.acp_ready}")
+        print(f"   Read-only: {runtime.read_only}")
+        print()
+        
+        # 2. Create agent-centric tools
+        print("2. Creating agent-centric tools...")
+        tools = create_agent_centric_tools(runtime)
+        print(f"   Tools created: {len(tools)}")
+        for tool in tools:
+            print(f"     - {tool.__name__}")
+        print()
+        
+        # 3. Create Agent with ACP-powered tools
+        print("3. Creating Agent with ACP-powered tools...")
+        agent = Agent(
+            name="FileAgent",
+            instructions="""You help create and manage files. 
+            Use acp_create_file to create files.
+            Use read_file to read files.
+            Use list_files to list directory contents.""",
+            tools=tools,
+            verbose=True
+        )
+        print()
+        
+        # 4. Ask agent to create a file
+        print("4. Asking agent to create a Python file...")
+        print("-" * 40)
+        result = agent.start(
+            "Create a Python file called calculator.py with add and subtract functions"
+        )
+        print("-" * 40)
+        print(f"Agent response: {result[:200]}..." if len(str(result)) > 200 else f"Agent response: {result}")
+        print()
+        
+        # 5. Verify file was created
+        print("5. Verifying file creation...")
+        calc_path = os.path.join(workspace, "calculator.py")
+        if os.path.exists(calc_path):
+            print(f"   ✓ File created at {calc_path}")
+            with open(calc_path) as f:
+                content = f.read()
+                print(f"   Content preview:")
+                for line in content.split('\n')[:10]:
+                    print(f"     {line}")
+        else:
+            # Check what files exist
+            files = os.listdir(workspace)
+            print(f"   Files in workspace: {files}")
+            for f in files:
+                fp = os.path.join(workspace, f)
+                if os.path.isfile(fp):
+                    print(f"   ✓ Found: {f}")
+        print()
+        
+        # 6. Ask agent to read the file
+        print("6. Asking agent to read the file...")
+        print("-" * 40)
+        result2 = agent.start("Read the calculator.py file and tell me what functions it has")
+        print("-" * 40)
+        print(f"Agent response: {result2[:300]}..." if len(str(result2)) > 300 else f"Agent response: {result2}")
+        print()
+        
+        # Cleanup
+        await runtime.stop()
+        
+    finally:
+        # Clean up workspace
+        shutil.rmtree(workspace, ignore_errors=True)
+        print(f"Cleaned up workspace: {workspace}")
+    
+    print()
+    print("=" * 60)
+    print("EXAMPLE COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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,209 @@
+#!/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}")
+    
+    # Example 6: Overflow handling strategies overview
+    print("\n6. Overflow Handling Strategies")
+    print("-" * 40)
+    strategies = [
+        ("truncate", "Remove oldest messages first", "Fast, simple", "Loses early context"),
+        ("sliding_window", "Keep N most recent messages", "Preserves recent", "Loses early context"),
+        ("prune_tools", "Truncate old tool outputs", "Keeps messages", "May lose tool details"),
+        ("summarize", "Replace old messages with summary", "Preserves meaning", "Slower, uses API"),
+        ("smart", "Combine strategies intelligently", "Best balance", "More complex"),
+    ]
+    print(f"{'Strategy':<15} | {'Description':<30} | {'Pros':<18} | {'Cons'}")
+    print("-" * 90)
+    for name, desc, pros, cons in strategies:
+        print(f"{name:<15} | {desc:<30} | {pros:<18} | {cons}")
+    
+    # Example 7: Simulated overflow playbook
+    print("\n7. Overflow Playbook (Thresholds → Actions)")
+    print("-" * 40)
+    playbook = [
+        (0.70, "INFO", "Monitor usage, no action needed"),
+        (0.80, "NOTICE", "Consider optimization soon"),
+        (0.90, "WARNING", "Trigger auto-compact if enabled"),
+        (0.95, "CRITICAL", "Aggressive optimization required"),
+        (1.00, "OVERFLOW", "Immediate truncation to prevent API error"),
+    ]
+    print(f"{'Usage':<8} | {'Level':<10} | {'Action'}")
+    print("-" * 60)
+    for threshold, level, action in playbook:
+        print(f"{threshold:>6.0%}   | {level:<10} | {action}")
+    
+    # Example 8: Strategy comparison table
+    print("\n8. Strategy Comparison")
+    print("-" * 40)
+    print("Strategy         | Preserves      | Loses          | Best For")
+    print("-" * 70)
+    print("truncate         | Recent msgs    | Old msgs       | Simple chats")
+    print("sliding_window   | Last N msgs    | Earlier msgs   | Long conversations")
+    print("prune_tools      | All messages   | Tool details   | Tool-heavy agents")
+    print("summarize        | Context meaning| Exact wording  | Important history")
+    print("smart            | Balanced       | Minimal        | Production use")
+    
+    # Example 9: Default strategy for interactive mode
+    print("\n9. Default Strategy: Interactive Mode")
+    print("-" * 40)
+    print("Interactive mode default: context=False (zero overhead)")
+    print("To enable context management in interactive mode:")
+    print("  praisonai chat --context  # Enable with defaults")
+    print("  Or in code:")
+    print("    agent = Agent(instructions='...', context=True)")
+    print("")
+    print("When enabled, defaults are:")
+    print("  - auto_compact: True")
+    print("  - compact_threshold: 0.8 (80% usage)")
+    print("  - strategy: smart")
+    print("  - output_reserve: model-specific (8K-16K)")
+    
+    # Example 10: Default strategy for auto-agents mode
+    print("\n10. Default Strategy: Auto-Agents Mode")
+    print("-" * 40)
+    print("Auto-agents mode default: context=False (zero overhead)")
+    print("To enable for multi-agent workflows:")
+    print("    from praisonaiagents import PraisonAIAgents")
+    print("    agents = PraisonAIAgents(agents=[...], context=True)")
+    print("")
+    print("Recommended config for long tasks:")
+    print("    context=ManagerConfig(")
+    print("        auto_compact=True,")
+    print("        compact_threshold=0.7,  # Earlier trigger for safety")
+    print("        strategy='smart',")
+    print("        output_reserve=16384,   # Larger reserve for complex outputs")
+    print("    )")
+    
+    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,
+    get_optimizer,
+    OptimizerStrategy,
+    estimate_messages_tokens,
+    format_percent,
+)
+
+
+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("\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, {format_percent(utilization)} 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: {format_percent(final_utilization)}")
+    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/debug/debug_interactive_example.py

@@ -0,0 +1,228 @@
+"""
+Debug Interactive Mode Example
+
+This example demonstrates how to use the debug CLI commands to test
+the Interactive Coding Assistant without entering TUI mode.
+
+Features demonstrated:
+- LSP symbol listing
+- LSP definition lookup
+- ACP action planning
+- ACP action execution
+- Trace capture and JSON output
+"""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+# Add the src directory to path for development
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src" / "praisonai"))
+
+from praisonai.cli.features.interactive_runtime import create_runtime
+from praisonai.cli.features.code_intelligence import CodeIntelligenceRouter
+from praisonai.cli.features.action_orchestrator import ActionOrchestrator
+
+
+async def demo_lsp_queries(workspace: str):
+    """Demonstrate LSP-based code queries."""
+    print("\n" + "=" * 60)
+    print("LSP CODE QUERIES DEMO")
+    print("=" * 60)
+    
+    runtime = create_runtime(
+        workspace=workspace,
+        lsp=True,
+        acp=False,
+        trace=True
+    )
+    
+    try:
+        await runtime.start()
+        router = CodeIntelligenceRouter(runtime)
+        
+        # Query 1: List symbols
+        print("\n[Query 1] List all symbols in app.py")
+        result = await router.handle_query("list all functions in app.py", "app.py")
+        print(f"  Success: {result.success}")
+        print(f"  LSP Used: {result.lsp_used}")
+        print(f"  Fallback Used: {result.fallback_used}")
+        if result.data:
+            print(f"  Symbols found: {len(result.data)}")
+            for symbol in result.data[:5]:
+                print(f"    - {symbol['name']} ({symbol['kind']}) at line {symbol['line']}")
+        
+        # Query 2: Find definition
+        print("\n[Query 2] Find definition of Calculator")
+        result = await router.handle_query("where is Calculator defined", "app.py")
+        print(f"  Success: {result.success}")
+        if result.citations:
+            print(f"  Found at: {result.citations[0]}")
+        
+        # Get trace
+        trace = runtime.get_trace()
+        print(f"\n[Trace] {len(trace.entries)} entries captured")
+        
+    finally:
+        await runtime.stop()
+
+
+async def demo_acp_actions(workspace: str):
+    """Demonstrate ACP-based code modifications."""
+    print("\n" + "=" * 60)
+    print("ACP CODE MODIFICATIONS DEMO")
+    print("=" * 60)
+    
+    runtime = create_runtime(
+        workspace=workspace,
+        lsp=False,
+        acp=True,
+        approval="auto",
+        trace=True
+    )
+    
+    try:
+        await runtime.start()
+        print(f"\n  ACP Ready: {runtime.acp_ready}")
+        print(f"  Read Only: {runtime.read_only}")
+        
+        orchestrator = ActionOrchestrator(runtime)
+        
+        # Action 1: Create a plan
+        print("\n[Action 1] Create plan for new file")
+        result = await orchestrator.create_plan("create a new file called demo_output.py")
+        print(f"  Success: {result.success}")
+        if result.plan:
+            print(f"  Plan ID: {result.plan.id}")
+            print(f"  Steps: {len(result.plan.steps)}")
+            for step in result.plan.steps:
+                print(f"    - {step.action_type.value}: {step.target}")
+        
+        # Action 2: Execute with auto-approve
+        print("\n[Action 2] Execute file creation")
+        exec_result = await orchestrator.execute(
+            "create a new file called demo_output.py with a hello function",
+            auto_approve=True
+        )
+        print(f"  Success: {exec_result.success}")
+        print(f"  Applied Steps: {exec_result.applied_steps}")
+        
+        # Verify file was created
+        output_file = Path(workspace) / "demo_output.py"
+        if output_file.exists():
+            print(f"  File created: {output_file}")
+            print(f"  Content preview: {output_file.read_text()[:100]}...")
+        
+        # Get trace
+        trace = runtime.get_trace()
+        print(f"\n[Trace] {len(trace.entries)} entries captured")
+        for entry in trace.entries:
+            print(f"    [{entry.category}] {entry.action}")
+        
+    finally:
+        await runtime.stop()
+
+
+async def demo_full_interactive_turn(workspace: str):
+    """Demonstrate full interactive turn simulation."""
+    print("\n" + "=" * 60)
+    print("FULL INTERACTIVE TURN SIMULATION")
+    print("=" * 60)
+    
+    runtime = create_runtime(
+        workspace=workspace,
+        lsp=True,
+        acp=True,
+        approval="auto",
+        trace=True
+    )
+    
+    try:
+        status = await runtime.start()
+        print("\n  Runtime Status:")
+        print(f"    LSP: {'ready' if status['lsp']['ready'] else 'fallback'}")
+        print(f"    ACP: {'ready' if status['acp']['ready'] else 'unavailable'}")
+        
+        router = CodeIntelligenceRouter(runtime)
+        orchestrator = ActionOrchestrator(runtime)
+        
+        # Simulate user prompt: code query
+        prompt1 = "What functions are in app.py?"
+        print(f"\n[Turn 1] User: {prompt1}")
+        
+        # Classify and route
+        result = await router.handle_query(prompt1, "app.py")
+        print(f"  Intent: {result.intent.value}")
+        print(f"  Response: Found {len(result.data) if result.data else 0} symbols")
+        
+        # Simulate user prompt: code modification
+        prompt2 = "Create a new test file"
+        print(f"\n[Turn 2] User: {prompt2}")
+        
+        exec_result = await orchestrator.execute(
+            "create a new file called test_demo.py",
+            auto_approve=True
+        )
+        print("  Action: file_create")
+        print(f"  Result: {'success' if exec_result.success else 'failed'}")
+        
+        # Export trace as JSON
+        trace = runtime.get_trace()
+        trace_json = trace.to_dict()
+        print("[Trace Export]")
+        print(json.dumps(trace_json, indent=2, default=str)[:500] + "...")
+        
+    finally:
+        await runtime.stop()
+
+
+def main():
+    """Run the debug demo."""
+    # Create a temporary workspace
+    workspace = Path(__file__).parent / "_demo_workspace"
+    workspace.mkdir(exist_ok=True)
+    
+    # Create a sample app.py
+    app_file = workspace / "app.py"
+    app_file.write_text('''"""Sample application."""
+
+def greet(name: str) -> str:
+    """Greet someone."""
+    return f"Hello, {name}!"
+
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+class Calculator:
+    """Simple calculator."""
+    
+    def __init__(self):
+        self.value = 0
+    
+    def add(self, x):
+        self.value += x
+        return self.value
+
+if __name__ == "__main__":
+    print(greet("World"))
+''')
+    
+    print("=" * 60)
+    print("PRAISONAI DEBUG MODE DEMO")
+    print("=" * 60)
+    print(f"Workspace: {workspace}")
+    
+    # Run demos
+    asyncio.run(demo_lsp_queries(str(workspace)))
+    asyncio.run(demo_acp_actions(str(workspace)))
+    asyncio.run(demo_full_interactive_turn(str(workspace)))
+    
+    print("\n" + "=" * 60)
+    print("DEMO COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/guardrail_example_fixed.py

@@ -67,7 +67,7 @@ agent = Agent(
     goal="Summarize web content concisely",
     instructions="You are a helpful assistant that summarizes web content",
     llm="gemini/gemini-2.5-flash-lite-preview-06-17",
-    self_reflect=False,
+    reflection=False,
     verbose=True,
     tools=[get_url_context]  # FIX: tools must be a list, not a single function
 )
@@ -77,7 +77,7 @@ task_with_guardrailresult = Task(
     name="summarise article with GuardrailResult",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary below 500 characters",
     agent=agent,
-    guardrail=validate_length_guardrailresult,  # Using GuardrailResult
+    guardrails=validate_length_guardrailresult,  # Using GuardrailResult
     expected_output="summary of the article below 500 characters",
     max_retries=3  # Will retry up to 3 times if guardrail fails
 )
@@ -87,7 +87,7 @@ task_with_tuple = Task(
     name="summarise article with tuple",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary below 500 characters",
     agent=agent,
-    guardrail=validate_length_tuple,  # Using Tuple[bool, Any]
+    guardrails=validate_length_tuple,  # Using Tuple[bool, Any]
     expected_output="summary of the article below 500 characters",
     max_retries=3
 )
@@ -97,7 +97,7 @@ task_with_llm_guardrail = Task(
     name="summarise with LLM guardrail",
     description="get the context of this url: https://blog.google/technology/ai/dolphingemma/ and produce a summary",
     agent=agent,
-    guardrail="Ensure the summary is professional, factual, and between 100-500 characters",
+    guardrails="Ensure the summary is professional, factual, and between 100-500 characters",
     expected_output="professional summary of the article"
 )
 

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/js/ai-sdk/README.md

@@ -0,0 +1,41 @@
+# AI SDK Examples
+
+Examples demonstrating the AI SDK integration in PraisonAI TypeScript.
+
+## Prerequisites
+
+```bash
+npm install praisonai ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod
+```
+
+## Environment Variables
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIza...
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `basic-chat.ts` | Simple text generation |
+| `streaming.ts` | Streaming text output |
+| `tool-calling.ts` | Function/tool calling |
+| `multi-provider.ts` | Using multiple providers |
+| `structured-output.ts` | JSON schema output |
+| `multi-agent.ts` | Multi-agent attribution |
+
+## Running Examples
+
+```bash
+npx ts-node basic-chat.ts
+npx ts-node streaming.ts
+npx ts-node tool-calling.ts
+```
+
+## More Information
+
+- [AI SDK Documentation](https://docs.praisonai.com/docs/js/ai-sdk)
+- [AI SDK CLI](https://docs.praisonai.com/docs/js/ai-sdk-cli)

examples/js/ai-sdk/basic-chat.ts

@@ -0,0 +1,39 @@
+/**
+ * AI SDK Basic Chat Example
+ * 
+ * Demonstrates simple text generation using the AI SDK backend.
+ * 
+ * Usage:
+ *   npx ts-node basic-chat.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ */
+
+import { createAISDKBackend } from 'praisonai';
+
+async function main() {
+  // Create backend with model string
+  const backend = createAISDKBackend('openai/gpt-4o-mini');
+
+  console.log('Sending message to OpenAI...\n');
+
+  // Generate text
+  const result = await backend.generateText({
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'What are the three primary colors?' }
+    ],
+    maxTokens: 200,
+    temperature: 0.7,
+  });
+
+  console.log('Response:', result.text);
+  console.log('\nFinish reason:', result.finishReason);
+  
+  if (result.usage) {
+    console.log('Token usage:', result.usage);
+  }
+}
+
+main().catch(console.error);

examples/js/ai-sdk/generate-text.ts

@@ -0,0 +1,32 @@
+/**
+ * Generate Text Example
+ * 
+ * Demonstrates basic text generation using AI SDK v6 via praisonai-ts.
+ * 
+ * Run: npx ts-node generate-text.ts
+ * Required: OPENAI_API_KEY
+ */
+
+// Import from local praisonai-ts package
+// In production: import { Agent } from 'praisonai';
+import { Agent } from '../../../src/praisonai-ts/src';
+
+async function main() {
+  // Simple text generation with Agent
+  const agent = new Agent({
+    instructions: 'You are a helpful assistant that provides concise answers.',
+    llm: 'openai/gpt-4o-mini',
+  });
+
+  console.log('=== Generate Text Example ===\n');
+
+  // Basic chat
+  const response = await agent.chat('What is the capital of France?');
+  console.log('Response:', response);
+
+  // With context
+  const response2 = await agent.chat('What is its population?');
+  console.log('\nFollow-up:', response2);
+}
+
+main().catch(console.error);

examples/js/ai-sdk/mcp-client.ts

@@ -0,0 +1,91 @@
+/**
+ * MCP Client Example (AI SDK v6 Parity)
+ * 
+ * Demonstrates Model Context Protocol client with HTTP/SSE transports.
+ * 
+ * Run: npx ts-node mcp-client.ts
+ * Note: Requires an MCP server running
+ */
+
+import { 
+  createMCP,
+  closeMCPClient,
+  type MCPConfig,
+} from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== MCP Client Example ===\n');
+
+  // Example configurations for different transports
+  const configs: Record<string, MCPConfig> = {
+    // HTTP transport (recommended for production)
+    http: {
+      transport: {
+        type: 'http',
+        url: 'https://mcp-server.example.com/mcp',
+        headers: { Authorization: 'Bearer token' },
+      },
+      name: 'http-client',
+    },
+    // SSE transport
+    sse: {
+      transport: {
+        type: 'sse',
+        url: 'https://mcp-server.example.com/sse',
+      },
+      name: 'sse-client',
+    },
+    // Stdio transport (for local servers)
+    stdio: {
+      transport: {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-everything'],
+      },
+      name: 'stdio-client',
+    },
+  };
+
+  console.log('MCP Transport Configurations:');
+  console.log('');
+  console.log('1. HTTP Transport (recommended):');
+  console.log(`   ${JSON.stringify(configs.http.transport, null, 2)}`);
+  console.log('');
+  console.log('2. SSE Transport:');
+  console.log(`   ${JSON.stringify(configs.sse.transport, null, 2)}`);
+  console.log('');
+  console.log('3. Stdio Transport (local):');
+  console.log(`   ${JSON.stringify(configs.stdio.transport, null, 2)}`);
+
+  console.log('\n--- Example Usage ---\n');
+  console.log(`
+// Create MCP client
+const client = await createMCP({
+  transport: {
+    type: 'http',
+    url: 'https://your-mcp-server.com/mcp',
+    headers: { Authorization: 'Bearer your-token' },
+  }
+});
+
+// Get available tools
+const tools = await client.tools();
+console.log('Available tools:', Object.keys(tools));
+
+// List resources
+const resources = await client.listResources();
+console.log('Resources:', resources);
+
+// List prompts
+const prompts = await client.listPrompts();
+console.log('Prompts:', prompts);
+
+// Close when done
+await closeMCPClient('default');
+`);
+
+  console.log('\n✅ MCP Client demo completed!');
+  console.log('Note: To run with a real MCP server, uncomment the connection code.');
+}
+
+main().catch(console.error);

examples/js/ai-sdk/multi-agent.ts

@@ -0,0 +1,96 @@
+/**
+ * AI SDK Multi-Agent Attribution Example
+ * 
+ * Demonstrates how to propagate attribution context (agentId, runId, traceId)
+ * to LLM calls for multi-agent observability and safety.
+ * 
+ * Usage:
+ *   npx ts-node multi-agent.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ */
+
+import { createAISDKBackend } from 'praisonai';
+
+// Simulate a multi-agent system with attribution
+interface AgentContext {
+  agentId: string;
+  runId: string;
+  traceId: string;
+  sessionId?: string;
+}
+
+async function runAgent(name: string, task: string, context: AgentContext) {
+  console.log(`\n[${name}] Starting task: ${task}`);
+  console.log(`  Attribution: agentId=${context.agentId}, runId=${context.runId}`);
+
+  const backend = createAISDKBackend('openai/gpt-4o-mini', {
+    attribution: context,
+    timeout: 30000,
+  });
+
+  const result = await backend.generateText({
+    messages: [
+      { role: 'system', content: `You are ${name}, a specialized AI agent.` },
+      { role: 'user', content: task }
+    ],
+    maxTokens: 100,
+  });
+
+  console.log(`  Response: ${result.text.slice(0, 100)}...`);
+  return result.text;
+}
+
+async function main() {
+  // Create a shared trace ID for the entire workflow
+  const traceId = `trace-${Date.now().toString(36)}`;
+  const sessionId = 'session-user123';
+
+  console.log('Multi-Agent Workflow with Attribution');
+  console.log('=====================================');
+  console.log(`Trace ID: ${traceId}`);
+  console.log(`Session ID: ${sessionId}`);
+
+  // Agent 1: Research Agent
+  const researchResult = await runAgent(
+    'ResearchAgent',
+    'What are the key benefits of TypeScript?',
+    {
+      agentId: 'agent-research',
+      runId: `run-${Date.now().toString(36)}-1`,
+      traceId,
+      sessionId,
+    }
+  );
+
+  // Agent 2: Summary Agent
+  const summaryResult = await runAgent(
+    'SummaryAgent',
+    `Summarize this in one sentence: ${researchResult}`,
+    {
+      agentId: 'agent-summary',
+      runId: `run-${Date.now().toString(36)}-2`,
+      traceId,
+      sessionId,
+    }
+  );
+
+  // Agent 3: Review Agent
+  await runAgent(
+    'ReviewAgent',
+    `Review this summary for accuracy: ${summaryResult}`,
+    {
+      agentId: 'agent-review',
+      runId: `run-${Date.now().toString(36)}-3`,
+      traceId,
+      sessionId,
+    }
+  );
+
+  console.log('\n\nWorkflow complete!');
+  console.log('All requests were tagged with the same trace ID for observability.');
+  console.log('Check your LLM provider dashboard to see the correlated requests.');
+}
+
+main().catch(console.error);

examples/js/ai-sdk/multi-provider.ts

@@ -0,0 +1,59 @@
+/**
+ * AI SDK Multi-Provider Example
+ * 
+ * Demonstrates using multiple LLM providers with the same interface.
+ * 
+ * Usage:
+ *   npx ts-node multi-provider.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ *   ANTHROPIC_API_KEY - Your Anthropic API key
+ *   GOOGLE_API_KEY - Your Google API key
+ */
+
+import { createAISDKBackend } from 'praisonai';
+
+const PROMPT = 'Explain what an API is in one sentence.';
+
+async function testProvider(modelString: string) {
+  try {
+    const backend = createAISDKBackend(modelString, {
+      timeout: 30000,
+    });
+
+    const startTime = Date.now();
+    const result = await backend.generateText({
+      messages: [{ role: 'user', content: PROMPT }],
+      maxTokens: 100,
+    });
+    const duration = Date.now() - startTime;
+
+    console.log(`\n${modelString}:`);
+    console.log(`  Response: ${result.text}`);
+    console.log(`  Duration: ${duration}ms`);
+    return true;
+  } catch (error: any) {
+    console.log(`\n${modelString}:`);
+    console.log(`  Error: ${error.message}`);
+    return false;
+  }
+}
+
+async function main() {
+  console.log('Testing multiple providers with the same prompt...');
+  console.log(`Prompt: "${PROMPT}"`);
+
+  const providers = [
+    'openai/gpt-4o-mini',
+    'anthropic/claude-3-haiku-20240307',
+    'google/gemini-1.5-flash',
+  ];
+
+  const results = await Promise.all(providers.map(testProvider));
+  
+  const successful = results.filter(Boolean).length;
+  console.log(`\n\nSummary: ${successful}/${providers.length} providers succeeded`);
+}
+
+main().catch(console.error);

examples/js/ai-sdk/speech-transcription.ts

@@ -0,0 +1,87 @@
+/**
+ * Speech & Transcription Example (AI SDK v6 Parity)
+ * 
+ * Demonstrates speech generation and transcription wrappers.
+ * 
+ * Run: npx ts-node speech-transcription.ts
+ * Required: OPENAI_API_KEY or ELEVENLABS_API_KEY
+ */
+
+import { 
+  generateSpeech,
+  transcribe,
+  SPEECH_MODELS,
+  TRANSCRIPTION_MODELS,
+} from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== Speech & Transcription Example ===\n');
+
+  // Show available models
+  console.log('1. Available Speech Models:');
+  Object.entries(SPEECH_MODELS).forEach(([key, value]) => {
+    console.log(`   ${key}: ${value}`);
+  });
+
+  console.log('\n2. Available Transcription Models:');
+  Object.entries(TRANSCRIPTION_MODELS).forEach(([key, value]) => {
+    console.log(`   ${key}: ${value}`);
+  });
+
+  // Example: Generate speech (requires API key)
+  console.log('\n3. Speech Generation Example:');
+  console.log(`
+// Generate speech from text
+const result = await generateSpeech({
+  text: 'Hello, this is a test of speech synthesis.',
+  model: 'openai/tts-1',
+  voice: 'alloy',
+});
+
+// Save to file
+await fs.writeFile('output.mp3', result.audio);
+console.log('Audio saved to output.mp3');
+`);
+
+  // Example: Transcribe audio (requires API key)
+  console.log('4. Transcription Example:');
+  console.log(`
+// Transcribe audio file
+const result = await transcribe({
+  audio: await fs.readFile('audio.mp3'),
+  model: 'openai/whisper-1',
+});
+
+console.log('Transcription:', result.text);
+console.log('Language:', result.language);
+console.log('Duration:', result.durationInSeconds, 'seconds');
+
+// With segments
+if (result.segments) {
+  result.segments.forEach(seg => {
+    console.log(\`[\${seg.start}s - \${seg.end}s]: \${seg.text}\`);
+  });
+}
+`);
+
+  // Live test if API key is available
+  if (process.env.OPENAI_API_KEY) {
+    console.log('\n5. Live Speech Generation Test:');
+    try {
+      const result = await generateSpeech({
+        text: 'Hello from PraisonAI!',
+        model: 'openai/tts-1',
+        voice: 'alloy',
+      });
+      console.log(`   ✅ Generated ${result.audio.length} bytes of audio`);
+    } catch (error: any) {
+      console.log(`   ⚠️ Speech generation failed: ${error.message}`);
+    }
+  } else {
+    console.log('\n5. Live Test: Skipped (OPENAI_API_KEY not set)');
+  }
+
+  console.log('\n✅ Speech & Transcription demo completed!');
+}
+
+main().catch(console.error);

examples/js/ai-sdk/stream-text.ts

@@ -0,0 +1,27 @@
+/**
+ * Stream Text Example
+ * 
+ * Demonstrates streaming text generation using AI SDK v6 via praisonai-ts.
+ * 
+ * Run: npx ts-node stream-text.ts
+ * Required: OPENAI_API_KEY
+ */
+
+import { Agent } from '../../../src/praisonai-ts/src';
+
+async function main() {
+  const agent = new Agent({
+    instructions: 'You are a helpful assistant that provides detailed answers.',
+    llm: 'openai/gpt-4o-mini',
+    stream: true,
+  });
+
+  console.log('=== Stream Text Example ===\n');
+  console.log('Streaming response:\n');
+
+  // Stream the response
+  const response = await agent.chat('Explain quantum computing in 3 paragraphs.');
+  console.log('\n\nFinal response:', response);
+}
+
+main().catch(console.error);

examples/js/ai-sdk/streaming.ts

@@ -0,0 +1,39 @@
+/**
+ * AI SDK Streaming Example
+ * 
+ * Demonstrates streaming text generation with real-time output.
+ * 
+ * Usage:
+ *   npx ts-node streaming.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ */
+
+import { createAISDKBackend } from 'praisonai';
+
+async function main() {
+  const backend = createAISDKBackend('openai/gpt-4o-mini');
+
+  console.log('Streaming response from OpenAI...\n');
+
+  const stream = await backend.streamText({
+    messages: [
+      { role: 'user', content: 'Write a short poem about coding.' }
+    ],
+    maxTokens: 200,
+  });
+
+  // Stream chunks as they arrive
+  for await (const chunk of stream) {
+    if (chunk.text) {
+      process.stdout.write(chunk.text);
+    }
+    
+    if (chunk.finishReason) {
+      console.log('\n\nFinish reason:', chunk.finishReason);
+    }
+  }
+}
+
+main().catch(console.error);

examples/js/ai-sdk/structured-output.ts

@@ -0,0 +1,72 @@
+/**
+ * AI SDK Structured Output Example
+ * 
+ * Demonstrates generating typed JSON objects with Zod schemas.
+ * 
+ * Usage:
+ *   npx ts-node structured-output.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ */
+
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+// Define schema for a person profile
+const PersonSchema = z.object({
+  name: z.string().describe('Full name'),
+  age: z.number().describe('Age in years'),
+  occupation: z.string().describe('Job title'),
+  city: z.string().describe('City of residence'),
+  interests: z.array(z.string()).describe('List of hobbies/interests'),
+  bio: z.string().describe('Short biography'),
+});
+
+// Define schema for a recipe
+const RecipeSchema = z.object({
+  name: z.string().describe('Recipe name'),
+  cuisine: z.string().describe('Type of cuisine'),
+  prepTime: z.number().describe('Preparation time in minutes'),
+  cookTime: z.number().describe('Cooking time in minutes'),
+  servings: z.number().describe('Number of servings'),
+  ingredients: z.array(z.object({
+    item: z.string(),
+    amount: z.string(),
+  })).describe('List of ingredients'),
+  instructions: z.array(z.string()).describe('Step-by-step instructions'),
+});
+
+async function main() {
+  console.log('Generating structured output with Zod schemas...\n');
+
+  // Generate a person profile
+  console.log('1. Generating a fictional person profile...');
+  const personResult = await generateObject({
+    model: openai('gpt-4o-mini'),
+    schema: PersonSchema,
+    prompt: 'Generate a fictional software engineer profile.',
+  });
+
+  console.log('Person:', JSON.stringify(personResult.object, null, 2));
+
+  // Generate a recipe
+  console.log('\n2. Generating a recipe...');
+  const recipeResult = await generateObject({
+    model: openai('gpt-4o-mini'),
+    schema: RecipeSchema,
+    prompt: 'Generate a simple pasta recipe.',
+  });
+
+  console.log('Recipe:', JSON.stringify(recipeResult.object, null, 2));
+
+  // Type-safe access
+  console.log('\n3. Type-safe access:');
+  console.log(`  Person name: ${personResult.object.name}`);
+  console.log(`  Person age: ${personResult.object.age}`);
+  console.log(`  Recipe name: ${recipeResult.object.name}`);
+  console.log(`  Total time: ${recipeResult.object.prepTime + recipeResult.object.cookTime} minutes`);
+}
+
+main().catch(console.error);

examples/js/ai-sdk/telemetry.ts

@@ -0,0 +1,78 @@
+/**
+ * Telemetry Example (AI SDK v6 Parity)
+ * 
+ * Demonstrates telemetry and tracing with optional OpenTelemetry integration.
+ * 
+ * Run: npx ts-node telemetry.ts
+ * Required: OPENAI_API_KEY
+ */
+
+import { 
+  configureTelemetry,
+  isTelemetryEnabled,
+  createAISpan,
+  recordEvent,
+  getEvents,
+  clearEvents,
+  Agent,
+} from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== Telemetry Example ===\n');
+
+  // Configure telemetry
+  configureTelemetry({
+    isEnabled: true,
+    functionId: 'telemetry-demo',
+    metadata: {
+      version: '1.0.0',
+      environment: 'development',
+    },
+  });
+
+  console.log('1. Telemetry Status:');
+  console.log(`   Enabled: ${isTelemetryEnabled()}`);
+
+  // Create a span for an operation
+  console.log('\n2. Creating AI Span:');
+  const span = createAISpan('generateText', {
+    model: 'gpt-4o-mini',
+    provider: 'openai',
+  });
+
+  try {
+    // Simulate AI operation
+    console.log('   Performing AI operation...');
+    await new Promise(resolve => setTimeout(resolve, 100));
+    
+    span.setAttribute('tokens', 150);
+    span.setStatus({ code: 'ok' });
+    console.log('   Span completed successfully');
+  } catch (error: any) {
+    span.recordException(error);
+    span.setStatus({ code: 'error', message: error.message });
+  } finally {
+    span.end();
+  }
+
+  // Record custom events
+  console.log('\n3. Recording Events:');
+  recordEvent('agent.started', { agentName: 'demo-agent' });
+  recordEvent('tool.called', { toolName: 'search', duration: 250 });
+  recordEvent('agent.completed', { success: true });
+
+  const events = getEvents();
+  console.log(`   Recorded ${events.length} events:`);
+  events.forEach(e => {
+    console.log(`   - ${e.name}: ${JSON.stringify(e.attributes)}`);
+  });
+
+  // Clear events
+  console.log('\n4. Clearing Events:');
+  clearEvents();
+  console.log(`   Events after clear: ${getEvents().length}`);
+
+  console.log('\n✅ Telemetry demo completed!');
+}
+
+main().catch(console.error);

examples/js/ai-sdk/tool-approval.ts

@@ -0,0 +1,71 @@
+/**
+ * Tool Approval Example (AI SDK v6 Parity)
+ * 
+ * Demonstrates human-in-the-loop tool approval using needsApproval.
+ * 
+ * Run: npx ts-node tool-approval.ts
+ * Required: OPENAI_API_KEY
+ */
+
+import { 
+  Agent,
+  withApproval,
+  getApprovalManager,
+  createDangerousPatternChecker,
+} from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== Tool Approval Example ===\n');
+
+  // Set up approval handler
+  const manager = getApprovalManager();
+  manager.onApprovalRequest(async (request) => {
+    console.log(`\n🔐 APPROVAL REQUESTED`);
+    console.log(`   Tool: ${request.toolName}`);
+    console.log(`   Input: ${JSON.stringify(request.input)}`);
+    console.log(`   Reason: ${request.reason || 'No reason provided'}`);
+    
+    // Auto-approve for demo (in production, prompt user)
+    console.log(`   ✅ Auto-approved for demo\n`);
+    return true;
+  });
+
+  // Create a tool that always requires approval
+  const deleteFile = withApproval({
+    name: 'deleteFile',
+    description: 'Delete a file from the filesystem',
+    needsApproval: true, // Always require approval
+    execute: async (input: { path: string }) => {
+      console.log(`   Executing: Would delete ${input.path}`);
+      return { success: true, deleted: input.path };
+    },
+  });
+
+  // Create a tool with conditional approval (dangerous patterns only)
+  const runCommand = withApproval({
+    name: 'runCommand',
+    description: 'Run a shell command',
+    needsApproval: createDangerousPatternChecker(),
+    execute: async (input: { command: string }) => {
+      console.log(`   Executing: ${input.command}`);
+      return { output: 'command executed' };
+    },
+  });
+
+  // Test the tools
+  console.log('1. Testing deleteFile (always requires approval):');
+  const result1 = await deleteFile({ path: '/tmp/test.txt' });
+  console.log('   Result:', result1);
+
+  console.log('\n2. Testing runCommand with safe command (no approval needed):');
+  const result2 = await runCommand({ command: 'ls -la' });
+  console.log('   Result:', result2);
+
+  console.log('\n3. Testing runCommand with dangerous command (requires approval):');
+  const result3 = await runCommand({ command: 'rm -rf /tmp/test' });
+  console.log('   Result:', result3);
+
+  console.log('\n✅ Tool approval demo completed!');
+}
+
+main().catch(console.error);

examples/js/ai-sdk/tool-calling.ts

@@ -0,0 +1,75 @@
+/**
+ * AI SDK Tool Calling Example
+ * 
+ * Demonstrates function/tool calling with Zod schemas.
+ * 
+ * Usage:
+ *   npx ts-node tool-calling.ts
+ * 
+ * Environment:
+ *   OPENAI_API_KEY - Your OpenAI API key
+ */
+
+import { generateText, tool } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+// Define tools with Zod schemas
+const tools = {
+  get_weather: tool({
+    description: 'Get the current weather for a city',
+    inputSchema: z.object({
+      city: z.string().describe('The city name'),
+      unit: z.enum(['celsius', 'fahrenheit']).optional().describe('Temperature unit'),
+    }),
+    execute: async ({ city, unit = 'celsius' }) => {
+      // Mock weather data
+      const weather = {
+        city,
+        temperature: unit === 'celsius' ? 22 : 72,
+        unit,
+        condition: 'sunny',
+        humidity: 45,
+      };
+      return weather;
+    },
+  }),
+  
+  get_time: tool({
+    description: 'Get the current time in a timezone',
+    inputSchema: z.object({
+      timezone: z.string().describe('Timezone like "America/New_York"'),
+    }),
+    execute: async ({ timezone }) => {
+      const time = new Date().toLocaleString('en-US', { timeZone: timezone });
+      return { timezone, time };
+    },
+  }),
+};
+
+async function main() {
+  console.log('Asking about weather with tool calling...\n');
+
+  const result = await generateText({
+    model: openai('gpt-4o-mini'),
+    messages: [
+      { role: 'user', content: 'What is the weather in Paris and what time is it in New York?' }
+    ],
+    tools,
+    maxSteps: 5, // Allow multiple tool calls
+  });
+
+  console.log('Tool Calls:');
+  for (const toolCall of result.toolCalls) {
+    console.log(`  - ${toolCall.toolName}:`, toolCall.args);
+  }
+
+  console.log('\nTool Results:');
+  for (const toolResult of result.toolResults) {
+    console.log(`  - ${toolResult.toolName}:`, toolResult.result);
+  }
+
+  console.log('\nFinal Response:', result.text);
+}
+
+main().catch(console.error);

examples/js/ai-sdk/ui-message.ts

@@ -0,0 +1,63 @@
+/**
+ * UI Message Example (AI SDK v6 Parity)
+ * 
+ * Demonstrates UIMessage protocol for Next.js/React integration.
+ * 
+ * Run: npx ts-node ui-message.ts
+ * Required: OPENAI_API_KEY
+ */
+
+import { 
+  createTextMessage,
+  createSystemMessage,
+  convertToModelMessages,
+  convertToUIMessages,
+  validateUIMessages,
+  hasPendingApprovals,
+  type UIMessage,
+} from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== UI Message Example ===\n');
+
+  // Create UI messages
+  const messages: UIMessage[] = [
+    createSystemMessage('You are a helpful assistant.'),
+    createTextMessage('user', 'What is the capital of France?'),
+    createTextMessage('assistant', 'The capital of France is Paris.'),
+    createTextMessage('user', 'What is its population?'),
+  ];
+
+  console.log('1. Created UI Messages:');
+  messages.forEach((msg, i) => {
+    const text = msg.parts.find(p => p.type === 'text');
+    console.log(`   [${i}] ${msg.role}: ${text ? (text as any).text.substring(0, 50) : '...'}`);
+  });
+
+  // Validate messages
+  console.log('\n2. Validating messages:');
+  const isValid = validateUIMessages(messages);
+  console.log(`   Valid: ${isValid}`);
+
+  // Convert to model messages (for AI SDK)
+  console.log('\n3. Converting to Model Messages:');
+  const modelMessages = await convertToModelMessages(messages);
+  modelMessages.forEach((msg, i) => {
+    const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+    console.log(`   [${i}] ${msg.role}: ${content.substring(0, 50)}...`);
+  });
+
+  // Check for pending approvals
+  console.log('\n4. Checking for pending approvals:');
+  const hasPending = messages.some(m => hasPendingApprovals(m));
+  console.log(`   Has pending approvals: ${hasPending}`);
+
+  // Convert model messages back to UI messages
+  console.log('\n5. Round-trip conversion:');
+  const uiMessages = convertToUIMessages(modelMessages);
+  console.log(`   Converted ${uiMessages.length} messages back to UI format`);
+
+  console.log('\n✅ UI Message demo completed!');
+}
+
+main().catch(console.error);

examples/js/embeddings/embed-basic.ts

@@ -0,0 +1,65 @@
+/**
+ * Basic Embedding Example
+ * 
+ * Demonstrates using Agent.embed() for text embeddings
+ * 
+ * Run: npx ts-node examples/js/embeddings/embed-basic.ts
+ */
+
+import { Agent } from '../../../src/praisonai-ts/dist/agent/simple';
+import { embed, embedMany, cosineSimilarity } from '../../../src/praisonai-ts/dist/llm/embeddings';
+
+async function main() {
+  console.log('=== Basic Embedding Example ===\n');
+
+  // Method 1: Using Agent.embed()
+  console.log('1. Agent.embed() - Single text');
+  const agent = new Agent({
+    instructions: 'You are a helpful assistant',
+    llm: 'openai/gpt-4o-mini',
+    verbose: false
+  });
+
+  const singleEmbedding = await agent.embed('Hello world');
+  console.log(`   Dimensions: ${(singleEmbedding as number[]).length}`);
+  console.log(`   First 5 values: [${(singleEmbedding as number[]).slice(0, 5).map(v => v.toFixed(4)).join(', ')}...]`);
+
+  // Method 2: Using Agent.embed() with multiple texts
+  console.log('\n2. Agent.embed() - Multiple texts');
+  const multiEmbeddings = await agent.embed(['Hello', 'World', 'How are you?']);
+  console.log(`   Count: ${(multiEmbeddings as number[][]).length}`);
+  console.log(`   Each has ${(multiEmbeddings as number[][])[0].length} dimensions`);
+
+  // Method 3: Direct embed function
+  console.log('\n3. Direct embed() function');
+  const result = await embed('PraisonAI is an AI agent framework');
+  console.log(`   Dimensions: ${result.embedding.length}`);
+  console.log(`   Tokens used: ${result.usage?.tokens || 'N/A'}`);
+
+  // Method 4: Batch embeddings
+  console.log('\n4. Batch embedMany() function');
+  const texts = [
+    'Machine learning is a subset of AI',
+    'Deep learning uses neural networks',
+    'Natural language processing handles text'
+  ];
+  const batchResult = await embedMany(texts);
+  console.log(`   Embedded ${batchResult.embeddings.length} texts`);
+  console.log(`   Total tokens: ${batchResult.usage?.tokens || 'N/A'}`);
+
+  // Method 5: Similarity comparison
+  console.log('\n5. Cosine Similarity');
+  const emb1 = await embed('I love programming');
+  const emb2 = await embed('Coding is my passion');
+  const emb3 = await embed('The weather is nice today');
+
+  const sim12 = cosineSimilarity(emb1.embedding, emb2.embedding);
+  const sim13 = cosineSimilarity(emb1.embedding, emb3.embedding);
+
+  console.log(`   "I love programming" vs "Coding is my passion": ${(sim12 * 100).toFixed(1)}%`);
+  console.log(`   "I love programming" vs "The weather is nice": ${(sim13 * 100).toFixed(1)}%`);
+
+  console.log('\n=== Complete ===');
+}
+
+main().catch(console.error);

examples/js/embeddings/embed-docs.ts

@@ -0,0 +1,119 @@
+/**
+ * Document Embedding Example
+ * 
+ * Demonstrates chunking and embedding documents for retrieval
+ * 
+ * Run: npx ts-node examples/js/embeddings/embed-docs.ts
+ */
+
+import { embedMany, cosineSimilarity } from '../../../src/praisonai-ts/dist/llm/embeddings';
+
+// Sample documents
+const documents = [
+  {
+    id: 'doc1',
+    title: 'Introduction to AI',
+    content: 'Artificial Intelligence (AI) is the simulation of human intelligence by machines. It includes machine learning, natural language processing, and computer vision.'
+  },
+  {
+    id: 'doc2',
+    title: 'Machine Learning Basics',
+    content: 'Machine learning is a subset of AI that enables systems to learn from data. It includes supervised learning, unsupervised learning, and reinforcement learning.'
+  },
+  {
+    id: 'doc3',
+    title: 'Deep Learning',
+    content: 'Deep learning uses neural networks with multiple layers. It excels at tasks like image recognition, speech processing, and natural language understanding.'
+  },
+  {
+    id: 'doc4',
+    title: 'Natural Language Processing',
+    content: 'NLP enables computers to understand human language. Applications include chatbots, translation, sentiment analysis, and text summarization.'
+  },
+  {
+    id: 'doc5',
+    title: 'Computer Vision',
+    content: 'Computer vision allows machines to interpret visual information. It powers applications like facial recognition, autonomous vehicles, and medical imaging.'
+  }
+];
+
+interface EmbeddedDocument {
+  id: string;
+  title: string;
+  content: string;
+  embedding: number[];
+}
+
+async function main() {
+  console.log('=== Document Embedding Example ===\n');
+
+  // Step 1: Embed all documents
+  console.log('1. Embedding documents...');
+  const contents = documents.map(d => d.content);
+  const { embeddings } = await embedMany(contents);
+  
+  const embeddedDocs: EmbeddedDocument[] = documents.map((doc, i) => ({
+    ...doc,
+    embedding: embeddings[i]
+  }));
+  
+  console.log(`   Embedded ${embeddedDocs.length} documents`);
+  console.log(`   Embedding dimensions: ${embeddings[0].length}`);
+
+  // Step 2: Search function
+  async function search(query: string, topK: number = 3): Promise<Array<{ doc: EmbeddedDocument; score: number }>> {
+    const { embedding: queryEmbedding } = await (await import('../../../src/praisonai-ts/dist/llm/embeddings')).embed(query);
+    
+    const results = embeddedDocs.map(doc => ({
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding)
+    }));
+    
+    return results
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK);
+  }
+
+  // Step 3: Test queries
+  console.log('\n2. Testing search queries...\n');
+
+  const queries = [
+    'How do machines learn from data?',
+    'What is image recognition?',
+    'Tell me about chatbots and translation'
+  ];
+
+  for (const query of queries) {
+    console.log(`Query: "${query}"`);
+    const results = await search(query);
+    
+    console.log('Top results:');
+    results.forEach((r, i) => {
+      console.log(`  ${i + 1}. [${(r.score * 100).toFixed(1)}%] ${r.doc.title}`);
+    });
+    console.log('');
+  }
+
+  // Step 4: Show document similarity matrix
+  console.log('3. Document Similarity Matrix');
+  console.log('');
+  
+  // Header
+  process.stdout.write('         ');
+  documents.forEach((_, i) => process.stdout.write(`Doc${i + 1}  `));
+  console.log('');
+  
+  // Matrix
+  for (let i = 0; i < embeddedDocs.length; i++) {
+    process.stdout.write(`Doc${i + 1}     `);
+    for (let j = 0; j < embeddedDocs.length; j++) {
+      const sim = cosineSimilarity(embeddedDocs[i].embedding, embeddedDocs[j].embedding);
+      process.stdout.write(`${(sim * 100).toFixed(0).padStart(3)}%  `);
+    }
+    console.log('');
+  }
+
+  console.log('\n=== Complete ===');
+}
+
+main().catch(console.error);

examples/js/embeddings/retrieval.ts

@@ -0,0 +1,131 @@
+/**
+ * Retrieval Example - Simple Vector Search
+ * 
+ * Demonstrates building a simple retrieval system with embeddings
+ * 
+ * Run: npx ts-node examples/js/embeddings/retrieval.ts
+ */
+
+import { embed, embedMany, cosineSimilarity } from '../../../src/praisonai-ts/dist/llm/embeddings';
+
+interface Document {
+  id: string;
+  content: string;
+  embedding?: number[];
+}
+
+interface SearchResult {
+  document: Document;
+  score: number;
+}
+
+// Simple in-memory vector store
+class SimpleVectorStore {
+  private documents: Document[] = [];
+
+  async add(doc: Document): Promise<void> {
+    const { embedding } = await embed(doc.content);
+    this.documents.push({ ...doc, embedding });
+  }
+
+  async addBatch(docs: Document[]): Promise<void> {
+    const contents = docs.map(d => d.content);
+    const { embeddings } = await embedMany(contents);
+    docs.forEach((doc, i) => {
+      this.documents.push({ ...doc, embedding: embeddings[i] });
+    });
+  }
+
+  async search(query: string, topK: number = 3): Promise<SearchResult[]> {
+    const { embedding: queryEmb } = await embed(query);
+    
+    const results = this.documents
+      .filter(doc => doc.embedding)
+      .map(doc => ({
+        document: doc,
+        score: cosineSimilarity(queryEmb, doc.embedding!)
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK);
+    
+    return results;
+  }
+
+  get(id: string): Document | undefined {
+    return this.documents.find(d => d.id === id);
+  }
+
+  delete(id: string): boolean {
+    const idx = this.documents.findIndex(d => d.id === id);
+    if (idx >= 0) {
+      this.documents.splice(idx, 1);
+      return true;
+    }
+    return false;
+  }
+}
+
+async function main() {
+  console.log('=== Simple Vector Retrieval ===\n');
+
+  // Create vector store
+  console.log('1. Creating vector store...');
+  const store = new SimpleVectorStore();
+
+  // Add documents
+  console.log('2. Adding documents...');
+  const docs: Document[] = [
+    { id: '1', content: 'PraisonAI is an AI agent framework for building intelligent applications.' },
+    { id: '2', content: 'Agents can use tools to interact with external systems and APIs.' },
+    { id: '3', content: 'Workflows allow orchestrating multiple agents in sequence or parallel.' },
+    { id: '4', content: 'Memory systems help agents maintain context across conversations.' },
+    { id: '5', content: 'The AI SDK provides a unified interface for multiple LLM providers.' },
+    { id: '6', content: 'Embeddings enable semantic search and similarity matching.' },
+    { id: '7', content: 'Guardrails ensure agent outputs meet safety and quality standards.' },
+    { id: '8', content: 'Sessions persist conversation state for multi-turn interactions.' }
+  ];
+
+  await store.addBatch(docs);
+  console.log(`   Added ${docs.length} documents`);
+
+  // Search queries
+  console.log('\n3. Running search queries...\n');
+
+  const queries = [
+    'How do I build an AI application?',
+    'Can agents call external APIs?',
+    'How to maintain conversation context?',
+    'What providers are supported?'
+  ];
+
+  for (const query of queries) {
+    console.log(`Query: "${query}"`);
+    const results = await store.search(query);
+    
+    if (results.length > 0) {
+      console.log('Results:');
+      results.forEach((r, i) => {
+        console.log(`  ${i + 1}. [${(r.score * 100).toFixed(1)}%] ${r.document.content.substring(0, 60)}...`);
+      });
+    } else {
+      console.log('  No results found');
+    }
+    console.log('');
+  }
+
+  // Get specific document
+  console.log('4. Get document by ID...');
+  const doc = store.get('5');
+  if (doc) {
+    console.log(`   Found: ${doc.content}`);
+  }
+
+  // Delete document
+  console.log('\n5. Delete document...');
+  const deleted = store.delete('8');
+  console.log(`   Deleted doc 8: ${deleted}`);
+
+  console.log('\n=== Complete ===');
+}
+
+main().catch(console.error);

examples/js/mcp/filesystem-mcp.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP Filesystem Server Example
+ * 
+ * Demonstrates using MCP to connect to a filesystem server.
+ * 
+ * Prerequisites:
+ *   npm install praisonai-ts
+ *   export OPENAI_API_KEY=your-api-key
+ * 
+ * Run:
+ *   npx ts-node filesystem-mcp.ts
+ */
+
+import { Agent, createMCP } from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== MCP Filesystem Server Example ===\n');
+
+  // Connect to MCP filesystem server
+  const mcp = await createMCP({
+    transport: {
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+    },
+  });
+
+  console.log('Connected to MCP filesystem server\n');
+
+  // Get tools from MCP server
+  const tools = await mcp.tools();
+  console.log('Available tools:', Object.keys(tools));
+
+  // Create agent with MCP tools
+  const agent = new Agent({
+    name: 'FileAgent',
+    instructions: 'You help manage files using the filesystem tools.',
+    tools: Object.values(tools),
+  });
+
+  // Ask the agent to list files
+  const response = await agent.chat('List all TypeScript files in the current directory');
+  console.log('\nResponse:', response);
+
+  // Cleanup
+  await mcp.close();
+}
+
+main().catch(console.error);

examples/js/multimodal/image-analysis.ts

@@ -0,0 +1,41 @@
+/**
+ * Multimodal Image Analysis Example
+ * 
+ * Demonstrates analyzing images with a vision-capable model.
+ * 
+ * Prerequisites:
+ *   npm install praisonai-ts
+ *   export OPENAI_API_KEY=your-api-key
+ * 
+ * Run:
+ *   npx ts-node image-analysis.ts
+ */
+
+import { Agent } from '../../../src/praisonai-ts/src';
+
+async function main() {
+  console.log('=== Multimodal Image Analysis Example ===\n');
+
+  // Create an agent with a vision-capable model
+  const agent = new Agent({
+    name: 'VisionAgent',
+    llm: 'gpt-4o', // Vision-capable model
+    instructions: 'You analyze images and describe what you see in detail.',
+  });
+
+  // For multimodal, we describe the image in the prompt
+  // The agent will use its vision capabilities
+  const imageUrl = 'https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/300px-PNG_transparency_demonstration_1.png';
+  
+  console.log('Analyzing image...\n');
+  console.log('Image URL:', imageUrl, '\n');
+  
+  // Ask the agent to analyze (in production, use multimodal message format)
+  const response = await agent.chat(
+    `Please analyze this image: ${imageUrl}\nDescribe what you see in detail.`
+  );
+  
+  console.log('Analysis:', response);
+}
+
+main().catch(console.error);

examples/js/observability/README.md

@@ -0,0 +1,50 @@
+# Observability Examples
+
+Examples demonstrating how to use observability integrations with PraisonAI TypeScript.
+
+## Setup
+
+```bash
+# Install dependencies
+cd /path/to/praisonai-ts
+pnpm install
+
+# Set API keys for observability tools
+export LANGFUSE_SECRET_KEY=sk-...
+export LANGFUSE_PUBLIC_KEY=pk-...
+# Or use built-in tools (no API key needed)
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `basic-tracing.ts` | Basic tracing with memory adapter |
+| `langfuse-integration.ts` | Langfuse observability integration |
+| `multi-agent-attribution.ts` | Track agent_id/run_id across agents |
+| `switchable-tools.ts` | Switch between observability tools via env |
+
+## Running Examples
+
+```bash
+# Run with ts-node or tsx
+npx tsx examples/js/observability/basic-tracing.ts
+npx tsx examples/js/observability/multi-agent-attribution.ts
+
+# With Langfuse (requires API keys)
+LANGFUSE_SECRET_KEY=sk-... npx tsx examples/js/observability/langfuse-integration.ts
+```
+
+## Supported Tools
+
+| Tool | Env Variable | Package |
+|------|--------------|---------|
+| Langfuse | `LANGFUSE_SECRET_KEY` | `langfuse` |
+| LangSmith | `LANGCHAIN_API_KEY` | `langsmith` |
+| LangWatch | `LANGWATCH_API_KEY` | `langwatch` |
+| Arize | `ARIZE_API_KEY` | `arize-phoenix` |
+| Axiom | `AXIOM_TOKEN` | `@axiomhq/js` |
+| Braintrust | `BRAINTRUST_API_KEY` | `braintrust` |
+| Helicone | `HELICONE_API_KEY` | `@helicone/helicone` |
+| Console | (none) | built-in |
+| Memory | (none) | built-in |

examples/js/observability/basic-tracing.ts

@@ -0,0 +1,45 @@
+/**
+ * Basic Tracing Example
+ * 
+ * Demonstrates basic observability with the built-in memory adapter.
+ * No external API keys required.
+ */
+
+import { Agent, MemoryObservabilityAdapter, setObservabilityAdapter } from 'praisonai';
+
+async function main() {
+  // Create memory adapter (stores traces in memory)
+  const obs = new MemoryObservabilityAdapter();
+  setObservabilityAdapter(obs);
+
+  // Create agent with observability enabled
+  const agent = new Agent({
+    name: 'TracedAgent',
+    instructions: 'You are a helpful assistant. Answer questions concisely.'
+  });
+
+  console.log('Running agent with tracing...\n');
+
+  // Run some interactions
+  await agent.chat('What is 2 + 2?');
+  await agent.chat('What is the capital of France?');
+
+  // View traces
+  const traces = obs.getAllTraces();
+  
+  console.log('\n=== Trace Summary ===');
+  console.log(`Total traces: ${traces.length}`);
+  
+  for (const trace of traces) {
+    console.log(`\nTrace: ${trace.name}`);
+    console.log(`  Status: ${trace.status}`);
+    console.log(`  Spans: ${trace.spans.length}`);
+    
+    for (const span of trace.spans) {
+      const duration = span.endTime ? span.endTime - span.startTime : 'running';
+      console.log(`    - ${span.kind}: ${span.name} (${duration}ms)`);
+    }
+  }
+}
+
+main().catch(console.error);

examples/js/observability/multi-agent-attribution.ts

@@ -0,0 +1,60 @@
+/**
+ * Multi-Agent Attribution Example
+ * 
+ * Demonstrates tracking agent_id, run_id, and trace_id across
+ * multi-agent workflows for proper attribution.
+ */
+
+import { Agent, Agents, MemoryObservabilityAdapter, setObservabilityAdapter } from 'praisonai';
+
+async function main() {
+  // Create memory adapter
+  const obs = new MemoryObservabilityAdapter();
+  setObservabilityAdapter(obs);
+
+  // Create agents
+  const researcher = new Agent({
+    name: 'Researcher',
+    instructions: 'Research topics and gather information.'
+  });
+
+  const writer = new Agent({
+    name: 'Writer',
+    instructions: 'Write clear summaries based on research.'
+  });
+
+  // Create multi-agent workflow
+  const agents = new Agents({
+    agents: [researcher, writer],
+    tasks: [
+      { agent: researcher, description: 'Research: {topic}' },
+      { agent: writer, description: 'Summarize the research findings' }
+    ]
+  });
+
+  console.log('Running multi-agent workflow with attribution...\n');
+
+  await agents.start({ topic: 'TypeScript best practices' });
+
+  // View traces with attribution
+  const traces = obs.getAllTraces();
+  
+  console.log('\n=== Attribution Report ===');
+  for (const trace of traces) {
+    console.log(`\nTrace ID: ${trace.id}`);
+    console.log(`  Name: ${trace.name}`);
+    
+    if (trace.attribution) {
+      console.log(`  Agent ID: ${trace.attribution.agentId || 'N/A'}`);
+      console.log(`  Run ID: ${trace.attribution.runId || 'N/A'}`);
+      console.log(`  Session ID: ${trace.attribution.sessionId || 'N/A'}`);
+    }
+    
+    console.log(`  Spans: ${trace.spans.length}`);
+    for (const span of trace.spans) {
+      console.log(`    - [${span.kind}] ${span.name}`);
+    }
+  }
+}
+
+main().catch(console.error);

examples/js/observability/switchable-tools.ts

@@ -0,0 +1,40 @@
+/**
+ * Switchable Observability Tools Example
+ * 
+ * Demonstrates switching between observability tools via environment variable.
+ * Set OBS_TOOL env var to: langfuse, langsmith, console, memory, noop
+ * 
+ * Usage:
+ *   OBS_TOOL=console npx tsx switchable-tools.ts
+ *   OBS_TOOL=langfuse LANGFUSE_SECRET_KEY=sk-... npx tsx switchable-tools.ts
+ */
+
+import { Agent, createObservabilityAdapter, setObservabilityAdapter } from 'praisonai';
+
+async function main() {
+  // Get tool from environment (default to memory)
+  const toolName = process.env.OBS_TOOL || 'memory';
+  
+  console.log(`Using observability tool: ${toolName}\n`);
+
+  // Create adapter dynamically
+  const obs = await createObservabilityAdapter(toolName as any);
+  setObservabilityAdapter(obs);
+
+  // Create agent
+  const agent = new Agent({
+    name: 'ObservedAgent',
+    instructions: 'You are a helpful assistant.'
+  });
+
+  // Run interaction
+  console.log('Running agent...\n');
+  const response = await agent.chat('Hello! What is 2 + 2?');
+  console.log('Response:', response);
+
+  // Flush traces to backend
+  await obs.flush();
+  console.log('\nTraces flushed to', toolName);
+}
+
+main().catch(console.error);

examples/js/providers/README.md

@@ -0,0 +1,47 @@
+# Provider Examples
+
+Examples demonstrating how to use different LLM providers with PraisonAI TypeScript.
+
+## Setup
+
+```bash
+# Install dependencies
+cd /path/to/praisonai-ts
+pnpm install
+
+# Set API keys
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIza...
+```
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `multi-provider.ts` | Use multiple providers in one workflow |
+| `openai-compatible.ts` | Use OpenAI-compatible APIs (LM Studio, etc.) |
+| `local-ollama.ts` | Use local Ollama models |
+| `provider-selection.ts` | Dynamic provider selection based on task |
+
+## Running Examples
+
+```bash
+# Run with ts-node or tsx
+npx tsx examples/js/providers/multi-provider.ts
+npx tsx examples/js/providers/openai-compatible.ts
+npx tsx examples/js/providers/local-ollama.ts
+```
+
+## Environment Variables
+
+| Provider | Variable | Example |
+|----------|----------|---------|
+| OpenAI | `OPENAI_API_KEY` | `sk-...` |
+| Anthropic | `ANTHROPIC_API_KEY` | `sk-ant-...` |
+| Google | `GOOGLE_API_KEY` | `AIza...` |
+| xAI | `XAI_API_KEY` | `xai-...` |
+| Groq | `GROQ_API_KEY` | `gsk_...` |
+| Mistral | `MISTRAL_API_KEY` | `...` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `...` |
+| Ollama | `OLLAMA_BASE_URL` | `http://localhost:11434` |

examples/js/providers/local-ollama.ts

@@ -0,0 +1,40 @@
+/**
+ * Local Ollama Provider Example
+ * 
+ * Demonstrates using local Ollama models with PraisonAI.
+ * 
+ * Setup:
+ * 1. Install Ollama: https://ollama.ai
+ * 2. Pull a model: ollama pull llama3.2
+ * 3. Run this example
+ * 
+ * Optional env var:
+ * - OLLAMA_BASE_URL (default: http://localhost:11434)
+ */
+
+import { Agent } from 'praisonai';
+
+async function main() {
+  // Ollama with llama3.2
+  const ollamaAgent = new Agent({
+    name: 'LocalLlama',
+    instructions: 'You are a helpful local AI assistant running on Ollama.',
+    llm: 'ollama/llama3.2',
+    llmConfig: {
+      baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434'
+    }
+  });
+
+  console.log('Testing Ollama local model...\n');
+
+  try {
+    const response = await ollamaAgent.chat('Hello! What model are you running?');
+    console.log('Response:', response);
+  } catch (error: any) {
+    console.log('Note: Ollama not running or model not pulled.');
+    console.log('Start Ollama and run: ollama pull llama3.2');
+    console.log('Error:', error.message);
+  }
+}
+
+main().catch(console.error);

examples/js/providers/multi-provider.ts

@@ -0,0 +1,57 @@
+/**
+ * Multi-Provider Example
+ * 
+ * Demonstrates using multiple LLM providers in a single workflow.
+ * Each agent uses a different provider optimized for its task.
+ * 
+ * Required env vars:
+ * - OPENAI_API_KEY
+ * - ANTHROPIC_API_KEY
+ * - GOOGLE_API_KEY
+ */
+
+import { Agent, Agents } from 'praisonai';
+
+async function main() {
+  // Fast model for quick categorization
+  const triageAgent = new Agent({
+    name: 'Triage',
+    instructions: 'Quickly categorize the user request into: technical, creative, or general.',
+    llm: 'openai/gpt-4o-mini'  // Fast and cheap
+  });
+
+  // Powerful model for complex reasoning
+  const analysisAgent = new Agent({
+    name: 'Analyst',
+    instructions: 'Analyze the request in depth and provide detailed insights.',
+    llm: 'anthropic/claude-3-5-sonnet'  // Best reasoning
+  });
+
+  // Creative model for content generation
+  const writerAgent = new Agent({
+    name: 'Writer',
+    instructions: 'Write a clear, engaging response based on the analysis.',
+    llm: 'google/gemini-2.0-flash'  // Good for creative tasks
+  });
+
+  // Create multi-agent workflow
+  const agents = new Agents({
+    agents: [triageAgent, analysisAgent, writerAgent],
+    tasks: [
+      { agent: triageAgent, description: 'Categorize: {input}' },
+      { agent: analysisAgent, description: 'Analyze the categorized request' },
+      { agent: writerAgent, description: 'Write the final response' }
+    ]
+  });
+
+  console.log('Starting multi-provider workflow...\n');
+  
+  const result = await agents.start({
+    input: 'Explain how neural networks learn'
+  });
+
+  console.log('\n=== Final Result ===');
+  console.log(result);
+}
+
+main().catch(console.error);

examples/js/providers/openai-compatible.ts

@@ -0,0 +1,48 @@
+/**
+ * OpenAI-Compatible Provider Example
+ * 
+ * Demonstrates using any OpenAI-compatible API endpoint.
+ * Works with LM Studio, vLLM, LocalAI, and other compatible servers.
+ * 
+ * Required env vars:
+ * - OPENAI_COMPATIBLE_BASE_URL (e.g., http://localhost:1234/v1)
+ * - OPENAI_COMPATIBLE_API_KEY (optional, use 'not-needed' for local)
+ */
+
+import { Agent } from 'praisonai';
+
+async function main() {
+  // LM Studio example (local)
+  const lmStudioAgent = new Agent({
+    name: 'LocalAssistant',
+    instructions: 'You are a helpful local AI assistant.',
+    llm: 'openai-compatible/local-model',
+    llmConfig: {
+      baseUrl: process.env.LM_STUDIO_BASE_URL || 'http://localhost:1234/v1',
+      apiKey: 'not-needed'
+    }
+  });
+
+  // Custom OpenAI-compatible endpoint
+  const customAgent = new Agent({
+    name: 'CustomAssistant',
+    instructions: 'You are a helpful assistant.',
+    llm: 'openai-compatible/my-model',
+    llmConfig: {
+      baseUrl: process.env.OPENAI_COMPATIBLE_BASE_URL || 'http://localhost:8000/v1',
+      apiKey: process.env.OPENAI_COMPATIBLE_API_KEY || 'not-needed'
+    }
+  });
+
+  console.log('Testing OpenAI-compatible endpoint...\n');
+
+  try {
+    const response = await lmStudioAgent.chat('Hello! What model are you?');
+    console.log('Response:', response);
+  } catch (error: any) {
+    console.log('Note: LM Studio not running. Start it with a model loaded.');
+    console.log('Error:', error.message);
+  }
+}
+
+main().catch(console.error);

examples/js/rag/basic-rag.ts

@@ -0,0 +1,57 @@
+/**
+ * Basic RAG Agent Example
+ * 
+ * Demonstrates building a RAG agent with context injection.
+ * 
+ * Prerequisites:
+ *   npm install praisonai-ts
+ *   export OPENAI_API_KEY=your-api-key
+ * 
+ * Run:
+ *   npx ts-node basic-rag.ts
+ */
+
+import { Agent } from '../../../src/praisonai-ts/src';
+
+// Simulated knowledge base (in production, use a vector store)
+const knowledgeBase = [
+  { id: '1', content: 'PraisonAI is an AI agent framework for building intelligent applications.' },
+  { id: '2', content: 'Agents can use tools to accomplish tasks like web search and calculations.' },
+  { id: '3', content: 'RAG combines retrieval with generation for accurate, grounded responses.' },
+];
+
+// Simple search function (in production, use vector similarity)
+function searchKnowledge(query: string): string[] {
+  const queryLower = query.toLowerCase();
+  return knowledgeBase
+    .filter(doc => doc.content.toLowerCase().includes(queryLower.split(' ')[0]))
+    .map(doc => doc.content);
+}
+
+async function main() {
+  console.log('=== Basic RAG Agent Example ===\n');
+
+  // Create an agent with RAG-style instructions
+  const agent = new Agent({
+    name: 'RAGAgent',
+    instructions: `You are a helpful assistant that answers questions using provided context.
+Always base your answers on the context provided.
+If the context doesn't contain relevant information, say so.`,
+  });
+
+  // Query with context injection
+  const query = 'What is PraisonAI?';
+  console.log(`Q: ${query}`);
+  
+  // Retrieve relevant context
+  const context = searchKnowledge(query).join('\n\n');
+  
+  // Ask the agent with context
+  const response = await agent.chat(
+    `Context:\n${context}\n\nQuestion: ${query}`
+  );
+  
+  console.log(`A: ${response}\n`);
+}
+
+main().catch(console.error);

examples/js/server-adapters/express-server.ts

@@ -0,0 +1,77 @@
+/**
+ * Express Server Adapter Example
+ * 
+ * Demonstrates deploying an AI agent as an Express HTTP server.
+ * 
+ * Prerequisites:
+ *   npm install praisonai-ts express
+ *   export OPENAI_API_KEY=your-api-key
+ * 
+ * Run:
+ *   npx ts-node express-server.ts
+ * 
+ * Test:
+ *   curl -X POST http://localhost:3000/api/chat \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"message": "Hello!"}'
+ */
+
+import { Agent } from '../../../src/praisonai-ts/src';
+
+// Simple HTTP server without Express dependency for this example
+import http from 'http';
+
+async function main() {
+  console.log('=== Express Server Adapter Example ===\n');
+
+  // Create an agent
+  const agent = new Agent({
+    name: 'APIAgent',
+    instructions: 'You are a helpful API assistant. Keep responses concise.',
+  });
+
+  // Create HTTP server
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    if (req.method === 'POST' && req.url === '/api/chat') {
+      let body = '';
+      req.on('data', chunk => body += chunk);
+      req.on('end', async () => {
+        try {
+          const { message } = JSON.parse(body);
+          const response = await agent.chat(message);
+          
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ response }));
+        } catch (error: any) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: error.message }));
+        }
+      });
+    } else {
+      res.writeHead(404);
+      res.end('Not Found');
+    }
+  });
+
+  const PORT = process.env.PORT || 3000;
+  server.listen(PORT, () => {
+    console.log(`Server running on http://localhost:${PORT}`);
+    console.log('\nTest with:');
+    console.log(`  curl -X POST http://localhost:${PORT}/api/chat \\`);
+    console.log('    -H "Content-Type: application/json" \\');
+    console.log('    -d \'{"message": "Hello!"}\'');
+  });
+}
+
+main().catch(console.error);

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/lsp/lsp_code_analysis_example.py

@@ -0,0 +1,130 @@
+"""
+LSP Code Intelligence Example
+
+This example demonstrates how to use LSP-powered tools through an Agent
+for semantic code analysis (listing symbols, finding definitions, etc.).
+
+How to run:
+    export OPENAI_API_KEY=your_key
+    python examples/lsp/lsp_code_analysis_example.py
+
+Prerequisites:
+    pip install praisonai praisonaiagents
+    pip install python-lsp-server  # Optional, for full LSP support
+"""
+
+import asyncio
+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'))
+
+
+async def main():
+    print("=" * 60)
+    print("LSP CODE INTELLIGENCE EXAMPLE")
+    print("=" * 60)
+    print()
+    
+    # Import after path setup
+    from praisonai.cli.features import (
+        create_agent_centric_tools,
+        InteractiveRuntime,
+        RuntimeConfig
+    )
+    from praisonaiagents import Agent
+    
+    # Use the praisonaiagents source as workspace for analysis
+    workspace = os.path.join(
+        os.path.dirname(__file__), 
+        '../../src/praisonai-agents/praisonaiagents'
+    )
+    workspace = os.path.abspath(workspace)
+    
+    print(f"Workspace: {workspace}")
+    print()
+    
+    # 1. Create runtime with LSP enabled
+    print("1. Creating InteractiveRuntime with LSP...")
+    config = RuntimeConfig(
+        workspace=workspace,
+        lsp_enabled=True,  # Enable LSP for code intelligence
+        acp_enabled=False,  # Disable ACP for this example
+        approval_mode="auto"
+    )
+    runtime = InteractiveRuntime(config)
+    status = await runtime.start()
+    
+    print(f"   LSP enabled: {status['lsp']['enabled']}")
+    print(f"   LSP ready: {runtime.lsp_ready}")
+    print(f"   LSP status: {status['lsp']['status']}")
+    if not runtime.lsp_ready:
+        print("   Note: LSP not available, will use regex fallback")
+    print()
+    
+    # 2. Create agent-centric tools
+    print("2. Creating agent-centric tools...")
+    tools = create_agent_centric_tools(runtime)
+    
+    # Filter to show only LSP tools
+    lsp_tools = [t for t in tools if t.__name__.startswith('lsp_')]
+    print(f"   LSP tools available:")
+    for tool in lsp_tools:
+        print(f"     - {tool.__name__}")
+    print()
+    
+    # 3. Create Agent with LSP-powered tools
+    print("3. Creating Agent with LSP tools...")
+    agent = Agent(
+        name="CodeAnalyzer",
+        instructions="""You are a code analysis assistant.
+        Use lsp_list_symbols to list functions and classes in files.
+        Use lsp_find_definition to find where symbols are defined.
+        Use lsp_find_references to find where symbols are used.
+        Provide clear, organized summaries of code structure.""",
+        tools=tools,
+        verbose=True
+    )
+    print()
+    
+    # 4. Test 1: List symbols in a file
+    print("4. TEST 1: List symbols in agent/agent.py")
+    print("-" * 50)
+    result1 = agent.start("List all the main classes and public methods in agent/agent.py. Give me a brief summary.")
+    print("-" * 50)
+    print(f"Summary: {str(result1)[:300]}...")
+    print()
+    
+    # 5. Test 2: Find definition of a symbol
+    print("5. TEST 2: Find where 'Agent' class is defined")
+    print("-" * 50)
+    result2 = agent.start("Where is the Agent class defined? Use lsp_find_definition to find it.")
+    print("-" * 50)
+    print(f"Result: {str(result2)[:300]}...")
+    print()
+    
+    # 6. Test 3: Analyze main.py
+    print("6. TEST 3: Analyze main.py structure")
+    print("-" * 50)
+    result3 = agent.start("List all the functions in main.py and briefly describe what the file does.")
+    print("-" * 50)
+    print(f"Analysis: {str(result3)[:300]}...")
+    print()
+    
+    # Cleanup
+    await runtime.stop()
+    
+    print("=" * 60)
+    print("EXAMPLE COMPLETE")
+    print("=" * 60)
+    print()
+    print("Key takeaways:")
+    print("- LSP tools work through the Agent (agentic LSP)")
+    print("- Falls back to regex if LSP server not available")
+    print("- Returns structured data with citations")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/output_ux/basic_output_example.py

@@ -0,0 +1,133 @@
+"""
+PraisonAI Output UX Examples
+
+This example demonstrates the various output modes and configurations
+available in PraisonAI agents.
+
+Features demonstrated:
+- verbose=True: Full output with agent info, task, and response panels
+- verbose=False: Clean output with just the result
+- Tool call display with consolidated output
+- Multi-agent output with clear attribution
+"""
+
+import sys
+sys.path.insert(0, '/Users/praison/praisonai-package/src/praisonai-agents')
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+    
+    Args:
+        city: The name of the city to get weather for
+    
+    Returns:
+        Weather information string
+    """
+    return f"The weather in {city} is sunny and 72°F"
+
+
+def example_verbose_true():
+    """Example with verbose=True (default) - shows full output panels."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 1: verbose=True (Full Output)")
+    print("=" * 60)
+    
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful assistant. Be concise.",
+        verbose=True  # Default - shows Agent Info, Task, and Response panels
+    )
+    result = agent.start("What is the capital of France? Answer in one sentence.")
+    print(f"\nReturned value: {result}")
+
+
+def example_verbose_false():
+    """Example with verbose=False - clean output, just the result."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 2: verbose=False (Clean Output)")
+    print("=" * 60)
+    
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful assistant. Be concise.",
+        verbose=False  # No panels, just returns the result
+    )
+    result = agent.start("What is 2+2? Answer in one word.")
+    print(f"Result: {result}")
+
+
+def example_with_tools():
+    """Example showing tool call output."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 3: Agent with Tools")
+    print("=" * 60)
+    
+    agent = Agent(
+        name="Weather Bot",
+        instructions="You help users check the weather. Use the get_weather tool.",
+        tools=[get_weather],
+        verbose=True
+    )
+    result = agent.start("What's the weather in Tokyo?")
+    print(f"\nReturned value: {result}")
+
+
+def example_multi_agent():
+    """Example showing multi-agent output with clear attribution."""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 4: Multi-Agent Output")
+    print("=" * 60)
+    
+    researcher = Agent(
+        name="Researcher",
+        role="Research Analyst",
+        instructions="You research topics and provide factual information.",
+        verbose=True
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Content Writer",
+        instructions="You write clear summaries based on research.",
+        verbose=True
+    )
+    
+    task1 = Task(
+        description="Research what AI is in one sentence",
+        expected_output="A brief factual description",
+        agent=researcher
+    )
+    
+    task2 = Task(
+        description="Write a one-sentence summary about AI",
+        expected_output="A clear summary",
+        agent=writer
+    )
+    
+    agents = PraisonAIAgents(
+        agents=[researcher, writer],
+        tasks=[task1, task2],
+        process="sequential",
+        verbose=1
+    )
+    
+    result = agents.start()
+    print(f"\nFinal result: {result}")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("PRAISONAI OUTPUT UX EXAMPLES")
+    print("=" * 60)
+    
+    # Run examples
+    example_verbose_true()
+    example_verbose_false()
+    example_with_tools()
+    example_multi_agent()
+    
+    print("\n" + "=" * 60)
+    print("ALL EXAMPLES COMPLETE")
+    print("=" * 60)

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/provider-registry/isolated_registry_example.py

@@ -0,0 +1,197 @@
+"""
+Isolated Registry Example - Multi-Agent Safety
+
+This example demonstrates how to use isolated registries to prevent
+provider registration collisions in multi-agent scenarios.
+
+Key concepts:
+- Each agent/context can have its own registry
+- No global state mutation
+- Safe for concurrent/parallel runs
+- Different agents can use different provider implementations
+
+Requirements:
+- pip install praisonai
+"""
+
+import sys
+sys.path.insert(0, '../../src/praisonai')
+
+from praisonai.llm import (
+    LLMProviderRegistry,
+    create_llm_provider,
+    register_llm_provider,
+    get_default_llm_registry,
+    _reset_default_registry
+)
+
+
+# Define two different provider implementations with the same name
+class Agent1Provider:
+    """Provider implementation for Agent 1."""
+    provider_id = "custom"
+    
+    def __init__(self, model_id, config=None):
+        self.model_id = model_id
+        self.config = config or {}
+        self.agent_name = "Agent1"
+    
+    def generate(self, prompt):
+        return f"[{self.agent_name}] Response to: {prompt}"
+
+
+class Agent2Provider:
+    """Provider implementation for Agent 2 - different behavior."""
+    provider_id = "custom"
+    
+    def __init__(self, model_id, config=None):
+        self.model_id = model_id
+        self.config = config or {}
+        self.agent_name = "Agent2"
+    
+    def generate(self, prompt):
+        return f"[{self.agent_name}] Different response to: {prompt}"
+
+
+def demonstrate_collision_problem():
+    """Show what happens with global registry collisions."""
+    print("=== Problem: Global Registry Collision ===\n")
+    
+    # Reset to clean state
+    _reset_default_registry()
+    
+    # Agent 1 registers "custom" provider
+    register_llm_provider("custom", Agent1Provider)
+    print("Agent 1 registered 'custom' provider")
+    
+    # Agent 2 tries to register same name - ERROR!
+    try:
+        register_llm_provider("custom", Agent2Provider)
+        print("Agent 2 registered 'custom' provider")
+    except ValueError as e:
+        print(f"Agent 2 FAILED: {e}")
+    
+    print()
+    print("Problem: Both agents want to use 'custom' but with different implementations.")
+    print("Solution: Use isolated registries.\n")
+
+
+def demonstrate_isolated_solution():
+    """Show how isolated registries solve the collision problem."""
+    print("=== Solution: Isolated Registries ===\n")
+    
+    # Create isolated registries for each agent
+    agent1_registry = LLMProviderRegistry()
+    agent2_registry = LLMProviderRegistry()
+    
+    # Each agent registers its own "custom" provider
+    agent1_registry.register("custom", Agent1Provider)
+    agent2_registry.register("custom", Agent2Provider)
+    
+    print("Agent 1 registry providers:", agent1_registry.list())
+    print("Agent 2 registry providers:", agent2_registry.list())
+    print()
+    
+    # Create providers from each registry
+    provider1 = create_llm_provider("custom/model-v1", registry=agent1_registry)
+    provider2 = create_llm_provider("custom/model-v1", registry=agent2_registry)
+    
+    # They have different implementations!
+    print("Provider 1 response:", provider1.generate("Hello"))
+    print("Provider 2 response:", provider2.generate("Hello"))
+    print()
+    
+    # Verify isolation
+    print("Verification:")
+    print(f"  provider1.agent_name = {provider1.agent_name}")
+    print(f"  provider2.agent_name = {provider2.agent_name}")
+    print(f"  Same class? {type(provider1) == type(provider2)}")
+    print()
+
+
+def demonstrate_parallel_agents():
+    """Simulate parallel agent execution with isolated registries."""
+    print("=== Parallel Agent Simulation ===\n")
+    
+    def run_agent(agent_id, registry):
+        """Simulate an agent run with its own registry."""
+        provider = create_llm_provider("custom/model", registry=registry)
+        result = provider.generate(f"Query from agent {agent_id}")
+        return result
+    
+    # Setup registries
+    registries = {}
+    for i in range(3):
+        reg = LLMProviderRegistry()
+        # Each agent gets a slightly different provider
+        class DynamicProvider:
+            provider_id = "custom"
+            def __init__(self, model_id, config=None):
+                self.model_id = model_id
+                self.agent_id = i  # Capture agent ID
+            def generate(self, prompt):
+                return f"Agent-{self.agent_id} processed: {prompt}"
+        
+        reg.register("custom", DynamicProvider)
+        registries[i] = reg
+    
+    # Simulate parallel execution
+    print("Simulating parallel agent runs:")
+    for agent_id, registry in registries.items():
+        result = run_agent(agent_id, registry)
+        print(f"  {result}")
+    
+    print()
+    print("Each agent used its own isolated registry - no collisions!")
+    print()
+
+
+def demonstrate_shared_vs_isolated():
+    """Compare shared (global) vs isolated registry patterns."""
+    print("=== Shared vs Isolated Patterns ===\n")
+    
+    # Reset global registry
+    _reset_default_registry()
+    
+    # Pattern 1: Shared (global) registry
+    print("Pattern 1: Shared Registry (use for app-wide providers)")
+    register_llm_provider("shared-provider", Agent1Provider)
+    
+    # All code sees the same provider
+    global_reg = get_default_llm_registry()
+    print(f"  Global registry has 'shared-provider': {global_reg.has('shared-provider')}")
+    
+    # Pattern 2: Isolated registry
+    print("\nPattern 2: Isolated Registry (use for per-agent/per-run providers)")
+    isolated = LLMProviderRegistry()
+    isolated.register("isolated-provider", Agent2Provider)
+    
+    # Only code with reference to this registry sees it
+    print(f"  Isolated registry has 'isolated-provider': {isolated.has('isolated-provider')}")
+    print(f"  Global registry has 'isolated-provider': {global_reg.has('isolated-provider')}")
+    
+    print()
+    print("Recommendation:")
+    print("  - Use global registry for app-wide, stable providers")
+    print("  - Use isolated registries for per-agent or per-run customization")
+    print()
+
+
+def main():
+    print("=" * 60)
+    print("Isolated Registry Example - Multi-Agent Safety")
+    print("=" * 60)
+    print()
+    
+    demonstrate_collision_problem()
+    demonstrate_isolated_solution()
+    demonstrate_parallel_agents()
+    demonstrate_shared_vs_isolated()
+    
+    print("=" * 60)
+    print("Example Complete")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/python/agents/code-agent.py

@@ -32,9 +32,9 @@ code_writer = Agent(
     goal="Write clean, efficient, and well-documented Python code",
     backstory="You are a senior Python developer with 10+ years of experience in writing production-quality code.",
     instructions="Write Python code that follows PEP 8 standards, includes proper error handling, and has clear documentation.",
-    self_reflect=True,
-    min_reflect=2,
-    max_reflect=5
+    reflection=True,
+    
+    
 )
 
 code_reviewer = Agent(
@@ -108,9 +108,9 @@ general_code_agent = Agent(
 4. Refactor code for better performance
 5. Add tests and documentation""",
     tools=[code_interpreter, analyze_code_complexity],
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=3
+    reflection=True,
+    
+    
 )
 
 if __name__ == "__main__":

examples/python/agents/image-agent.py

@@ -14,7 +14,7 @@ image_agent = Agent(
     backstory="""You are an expert in computer vision and image analysis.
     You excel at describing images, detecting objects, and understanding visual content.""",
     llm="gpt-5-nano",
-    self_reflect=False
+    reflection=False
 )
 
 # 1. Task with Image URL

examples/python/agents/image-to-text-agent.py

@@ -14,7 +14,7 @@ image_agent = Agent(
     backstory="""You are an expert in computer vision and image analysis.
     You excel at describing images, detecting objects, and understanding visual content.""",
     llm="gpt-5-nano",
-    self_reflect=False
+    reflection=False
 )
 
 # 1. Task with Image URL

examples/python/agents/math-agent.py

@@ -65,9 +65,9 @@ calculation_agent = Agent(
     backstory="You are an expert mathematician who can handle complex calculations with precision.",
     instructions="Perform the requested calculations step by step, showing your work clearly.",
     tools=[basic_calculator, solve_quadratic, calculate_statistics],
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=2
+    reflection=True,
+    
+    
 )
 
 problem_solver_agent = Agent(
@@ -81,9 +81,9 @@ problem_solver_agent = Agent(
 3. Determine what needs to be found
 4. Show each step of the solution
 5. Verify the answer makes sense""",
-    self_reflect=True,
-    min_reflect=2,
-    max_reflect=4
+    reflection=True,
+    
+    
 )
 
 math_tutor_agent = Agent(
@@ -148,9 +148,9 @@ math_assistant = Agent(
 
 Always show your work step by step.""",
     tools=[basic_calculator, solve_quadratic, calculate_statistics],
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=3
+    reflection=True,
+    
+    
 )
 
 if __name__ == "__main__":

examples/python/agents/programming-agent.py

@@ -1,10 +1,11 @@
-from praisonaiagents import Agent, Tools
+from praisonaiagents import Agent, Tools, ReflectionConfig
 from praisonaiagents.tools import execute_code, analyze_code, format_code, lint_code, disassemble_code # Code Tools
 from praisonaiagents.tools import execute_command, list_processes, kill_process, get_system_info # Shell Tools
 from praisonaiagents.tools import duckduckgo # Web Search Tool
 
 agent = Agent(
-    instructions="You are a Programming Agent", self_reflect=True, min_reflect=5, max_reflect=10, 
+    instructions="You are a Programming Agent",
+    reflection=ReflectionConfig(min_iterations=5, max_iterations=10),
     tools=[execute_code, analyze_code, format_code, lint_code, disassemble_code, execute_command, list_processes, kill_process, get_system_info, duckduckgo]
 )
 agent.start(

examples/python/agents/video-agent.py

@@ -8,7 +8,7 @@ video_agent = Agent(
     backstory="""You are an expert in computer vision and image analysis.
     You excel at describing images, detecting objects, and understanding visual content.""",
     llm="gpt-5-nano",
-    self_reflect=False
+    reflection=False
 )
 
 # Task with Video File

examples/python/agents/wikipedia-agent.py

@@ -4,9 +4,9 @@ from praisonaiagents.tools import wiki_search, wiki_summary, wiki_page, wiki_ran
 agent = Agent(
     instructions="You are a Wikipedia Agent", 
     tools=[wiki_search, wiki_summary, wiki_page, wiki_random, wiki_language],
-    self_reflect=True,
-    min_reflect=3,
-    max_reflect=5,
+    reflection=True,
+    
+    
 )
 agent.start(
     "What is the history of AI?"

examples/python/concepts/chat-with-pdf.py

@@ -27,9 +27,9 @@ pdf_agent = Agent(
     instructions="Read the provided PDF document and answer questions about its content. Be specific and cite relevant sections when possible.",
     knowledge=["document.pdf"],  # Replace with your PDF file path
     knowledge_config=config,
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=3
+    reflection=True,
+    
+    
 )
 
 # Example usage

examples/python/concepts/reasoning-extraction.py

@@ -49,9 +49,9 @@ cot_agent = Agent(
 6. Assess your confidence level
 
 Always make your thinking process explicit and transparent.""",
-    self_reflect=True,
-    min_reflect=2,
-    max_reflect=3
+    reflection=True,
+    
+    
 )
 
 # Example 2: Reasoning Extractor Agent
@@ -224,7 +224,7 @@ pattern_reasoning_agent = Agent(
 3. Counterfactual: Explore what-if scenarios
 4. Systems thinking: Consider interconnections
 5. Probabilistic: Assess likelihoods""",
-    self_reflect=True
+    reflection=True
 )
 
 # Example 8: Interactive Reasoning Extraction

examples/python/concepts/routing-patterns.py

@@ -208,7 +208,7 @@ dynamic_router = Agent(
 5. Current system load
 
 Provide clear routing decisions with reasoning.""",
-    self_reflect=True
+    reflection=True
 )
 
 def dynamic_routing_example():

examples/python/concepts/self-reflection-details.py

@@ -24,9 +24,9 @@ basic_reflection_agent = Agent(
 3. Identify areas for improvement
 4. Revise and enhance
 5. Repeat until satisfied""",
-    self_reflect=True,  # Enable self-reflection
-    min_reflect=1,      # Minimum 1 reflection iteration
-    max_reflect=3       # Maximum 3 reflection iterations
+    reflection=True,  # Enable self-reflection
+          # Minimum 1 reflection iteration
+           # Maximum 3 reflection iterations
 )
 
 # Example 2: Advanced Reflection with Different Strategies
@@ -41,9 +41,9 @@ quality_focused_agent = Agent(
 - Clarity of presentation
 - Logical flow
 - Supporting evidence""",
-    self_reflect=True,
-    min_reflect=3,  # Higher minimum for quality
-    max_reflect=5   # Allow more iterations
+    reflection=True,
+      # Higher minimum for quality
+       # Allow more iterations
 )
 
 efficiency_balanced_agent = Agent(
@@ -52,9 +52,9 @@ efficiency_balanced_agent = Agent(
     goal="Achieve good quality with reasonable reflection time",
     backstory="You balance quality with efficiency, knowing when good enough is sufficient.",
     instructions="Create good content with 1-2 rounds of improvement.",
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=2  # Limit iterations for efficiency
+    reflection=True,
+    
+      # Limit iterations for efficiency
 )
 
 # Example 3: No Reflection for Comparison
@@ -64,7 +64,7 @@ no_reflection_agent = Agent(
     goal="Provide immediate responses without reflection",
     backstory="You provide quick, first-draft responses.",
     instructions="Respond immediately with your first thought.",
-    self_reflect=False  # Disable reflection
+    reflection=False  # Disable reflection
 )
 
 # Demonstration function to show reflection in action
@@ -113,9 +113,9 @@ def reflection_workflow_example():
         role="Initial content creator",
         goal="Create first draft with self-improvement",
         backstory="You create initial drafts and refine them through reflection.",
-        self_reflect=True,
-        min_reflect=2,
-        max_reflect=3
+        reflection=True,
+        
+        
     )
     
     # Reviewer without reflection (provides feedback)
@@ -124,7 +124,7 @@ def reflection_workflow_example():
         role="Content reviewer",
         goal="Provide constructive feedback",
         backstory="You review content and provide specific improvement suggestions.",
-        self_reflect=False  # No reflection needed for reviewing
+        reflection=False  # No reflection needed for reviewing
     )
     
     # Final polisher with reflection
@@ -133,9 +133,9 @@ def reflection_workflow_example():
         role="Final content polisher",
         goal="Perfect the content based on feedback",
         backstory="You take feedback and create the final, polished version.",
-        self_reflect=True,
-        min_reflect=1,
-        max_reflect=2
+        reflection=True,
+        
+        
     )
     
     # Workflow tasks
@@ -202,9 +202,9 @@ custom_reflection_agent = Agent(
     backstory="You adapt your reflection process based on content quality.",
     instructions="""Create content and reflect on it.
 Continue improving until quality standards are met or maximum iterations reached.""",
-    self_reflect=True,
-    min_reflect=1,
-    max_reflect=5
+    reflection=True,
+    
+    
 )
 
 # Example 6: Reflection Impact Analysis

examples/python/concepts/self-reflection-optimization-patterns.py

@@ -17,10 +17,10 @@ reflection_agent = Agent(
     goal="Demonstrate self-reflection and iterative improvement patterns",
     backstory="Expert researcher with strong self-reflection and continuous improvement capabilities",
     tools=[internet_search],
-    self_reflect=True,
-    min_reflect=2,
-    max_reflect=4,
-    reflect_llm="gpt-5-nano",
+    reflection=True,
+    
+    
+    
     verbose=True
 )
 

examples/python/general/async_example.py

@@ -98,7 +98,7 @@ sync_agent = Agent(
     goal="Perform synchronous searches and return structured results",
     backstory="Expert in sync operations and data organization",
     tools=[sync_search_tool],
-    self_reflect=False,
+    reflection=False,
     verbose=True,
     markdown=True
 )
@@ -109,7 +109,7 @@ async_agent = Agent(
     goal="Perform asynchronous searches and return structured results",
     backstory="Expert in async operations and data organization",
     tools=[async_search_tool],
-    self_reflect=False,
+    reflection=False,
     verbose=True,
     markdown=True
 )

examples/python/general/async_example_full.py

@@ -53,7 +53,7 @@ async_agent = Agent(
     goal="Perform fast parallel searches with structured results",
     backstory="Expert in efficient data retrieval and parallel search operations",
     tools=[async_search_tool],
-    self_reflect=False,
+    reflection=False,
     verbose=True,
     markdown=True
 )
@@ -63,7 +63,7 @@ summary_agent = Agent(
     role="Research Synthesizer",
     goal="Create concise summaries from multiple search results",
     backstory="Expert in analyzing and synthesizing information from multiple sources",
-    self_reflect=True,
+    reflection=True,
     verbose=True,
     markdown=True
 )

examples/python/general/async_example_full_multigroups.py

@@ -60,7 +60,7 @@ async_agent = Agent(
     goal="Perform fast and efficient asynchronous searches with structured results",
     backstory="Expert in parallel search operations and data retrieval",
     tools=[async_search_tool],
-    self_reflect=False,
+    reflection=False,
     verbose=True,
     markdown=True
 )
@@ -72,7 +72,7 @@ summary_agent = Agent(
     backstory="""Expert in analyzing and synthesizing information from multiple sources.
 Skilled at identifying patterns, trends, and connections between different topics.
 Specializes in creating clear, structured summaries that highlight key insights.""",
-    self_reflect=True,  # Enable self-reflection for better summary quality
+    reflection=True,  # Enable self-reflection for better summary quality
     verbose=True,
     markdown=True
 )

examples/python/general/code_agents_example.py

@@ -25,13 +25,13 @@ code_agent = Agent(
     name="code_agent",
     llm="gpt-5-nano",
     backstory="Expert in writing Python scripts",
-    self_reflect=False
+    reflection=False
 )
 execution_agent = Agent(
     name="execution_agent",
     llm="gpt-5-nano",
     backstory="Expert in executing Python scripts",
-    self_reflect=False,
+    reflection=False,
     tools=[code_interpreter]
 )
 

examples/python/general/example_callback.py

@@ -129,9 +129,9 @@ def main():
         tools=[internet_search_tool],
         llm="gpt-5-nano",
         markdown=True,
-        reflect_llm="gpt-5-nano",
-        min_reflect=2,
-        max_reflect=4
+        
+        
+        
     )
     
     writer = Agent(

examples/python/general/example_custom_tools.py

@@ -112,7 +112,7 @@ data_agent = Agent(
     goal="Perform internet searches to collect relevant information.",
     backstory="Expert in finding and organizing internet data from multiple sources.",
     tools=[internet_search_tool, youtube_search_tool, wikipedia_search_tool],
-    self_reflect=False
+    reflection=False
 )
 
 # 3. Tasks

examples/python/general/example_sequential.py

@@ -41,9 +41,9 @@ researcher = Agent(
     tools=[internet_search_tool],
     llm="gpt-5-nano",
     markdown=True,
-    reflect_llm="gpt-5-nano",
-    min_reflect=2,
-    max_reflect=4
+    
+    
+    
 )
 writer = Agent(
     name="Writer",

examples/python/general/langchain_example.py

@@ -9,7 +9,7 @@ agent = Agent(
     goal="Search for information from multiple sources",
     backstory="I am an AI assistant that can search YouTube and Wikipedia.",
     tools=[YouTubeSearchTool, WikipediaAPIWrapper],
-    self_reflect=False
+    reflection=False
 )
 
 # Create tasks to demonstrate both tools

examples/python/general/multimodal.py

@@ -8,7 +8,7 @@ vision_agent = Agent(
     backstory="""You are an expert in computer vision and image analysis.
     You excel at describing images, detecting objects, and understanding visual content.""",
     llm="gpt-5-nano",
-    self_reflect=False
+    reflection=False
 )
 
 # 1. Task with Image URL

examples/python/general/structured_agents_example.py

@@ -15,7 +15,7 @@ researcher = Agent(
     verbose=True,
     llm="gpt-5-nano",
     tools=[Tools.internet_search],
-    self_reflect=False
+    reflection=False
 )
 
 # Create an analyst agent
@@ -26,7 +26,7 @@ analyst = Agent(
     backstory="Senior data analyst with expertise in pattern recognition",
     verbose=True,
     llm="gpt-5-nano",
-    self_reflect=False
+    reflection=False
 )
 
 # Define structured tasks

examples/python/general/structured_response_example.py

@@ -33,7 +33,7 @@ def get_structured_analysis(query: str, verbose: bool = True) -> AnalysisReport:
         goal="Analyze topics and provide structured reports",
         backstory="Expert at gathering information and providing structured analysis",
         verbose=verbose,
-        self_reflect=True,  # Enable self-reflection for better quality
+        reflection=True,  # Enable self-reflection for better quality
         markdown=True,
         llm="gpt-5-nano"
     )

examples/python/general/tools-class.py

@@ -94,7 +94,7 @@ agent = Agent(
     goal="Search for information about 'AI Agents Framework'",
     backstory="I am an AI assistant that can search GitHub.",
     tools=[EXASearchTool],
-    self_reflect=False
+    reflection=False
 )
 
 # Create tasks to demonstrate both tools

examples/python/general/tools_example.py

@@ -8,7 +8,7 @@ news_agent = Agent(
     goal="Collect and analyze news articles from various sources.",
     backstory="Expert in news gathering and content analysis.",
     tools=[get_article, get_news_sources, get_articles_from_source, get_trending_topics],
-    self_reflect=False
+    reflection=False
 )
 
 

examples/python/general/workflow_example_basic.py

@@ -35,7 +35,7 @@ data_agent = Agent(
     goal="Perform internet searches to collect relevant information.",
     backstory="Expert in finding and organising internet data.",
     tools=[internet_search_tool],
-    self_reflect=False
+    reflection=False
 )
 
 # 3. Tasks

examples/python/general/workflow_example_detailed.py

@@ -158,7 +158,7 @@ data_agent = Agent(
     goal="Collect and validate data about individuals",
     backstory="Expert in gathering and validating demographic data",
     tools=[random_data_of_individuals],
-    self_reflect=False
+    reflection=False
 )
 
 process_agent = Agent(
@@ -167,7 +167,7 @@ process_agent = Agent(
     goal="Process and categorize individual data",
     backstory="Expert in data analysis and categorization",
     tools=[process_data_of_individuals],
-    self_reflect=False
+    reflection=False
 )
 
 # Modify tasks to use Pydantic models

examples/python/guardrails/comprehensive-guardrails-example.py

@@ -125,7 +125,7 @@ email_task = Task(
     description="Write a business proposal for a new software project, including contact information",
     expected_output="Professional business proposal with contact email addresses",
     agent=email_agent,
-    guardrail=email_format_guardrail,
+    guardrails=email_format_guardrail,
     max_retries=3
 )
 
@@ -135,7 +135,7 @@ content_task = Task(
     description="Write an analysis of cloud computing benefits for small businesses",
     expected_output="Comprehensive analysis of cloud computing benefits (minimum 50 words)",
     agent=content_agent,
-    guardrail=word_count_guardrail,
+    guardrails=word_count_guardrail,
     max_retries=3
 )
 
@@ -145,7 +145,7 @@ business_task = Task(
     description="Provide advice on handling difficult client relationships",
     expected_output="Professional advice maintaining appropriate business tone",
     agent=business_agent,
-    guardrail=professional_tone_guardrail,
+    guardrails=professional_tone_guardrail,
     max_retries=3
 )
 
@@ -155,7 +155,7 @@ research_task = Task(
     description="Analyze the impact of artificial intelligence on job markets",
     expected_output="Research-backed analysis with citations and evidence",
     agent=research_agent,
-    guardrail=factual_accuracy_guardrail,
+    guardrails=factual_accuracy_guardrail,
     max_retries=3
 )
 
@@ -176,7 +176,7 @@ llm_guardrail_task = Task(
     agent=llm_guardrail_agent,
     
     # LLM-based guardrail using natural language validation
-    guardrail="Validate that this marketing content is: 1) Factually accurate with no false claims, 2) Compliant with advertising standards (no misleading statements), 3) Engaging and professional in tone, 4) Includes a clear call-to-action. If any criteria are not met, explain what needs to be improved.",
+    guardrails="Validate that this marketing content is: 1) Factually accurate with no false claims, 2) Compliant with advertising standards (no misleading statements), 3) Engaging and professional in tone, 4) Includes a clear call-to-action. If any criteria are not met, explain what needs to be improved.",
     max_retries=2
 )
 

examples/python/guardrails/production-guardrails-patterns.py

@@ -38,7 +38,7 @@ production_agent = Agent(
     goal="Generate safe, compliant content for production use",
     backstory="Production-ready agent with built-in safety and compliance checks",
     tools=[internet_search],
-    guardrail=content_guardrail,
+    guardrails=content_guardrail,
     max_retries=3,
     verbose=True
 )

examples/python/input/advanced_dynamic_input.py

@@ -40,7 +40,7 @@ class DynamicAgentSystem:
             goal=f"Conduct {inputs['depth']} research on {inputs['topic']} in {inputs['language']}",
             backstory=f"Multilingual expert specializing in {inputs['depth']} analysis",
             tools=[duckduckgo],
-            self_reflect=inputs['depth'] == 'detailed',
+            reflection=inputs['depth'] == 'detailed',
             llm=self.llm_config
         )
         agents.append(research_agent)

examples/python/input/medium_complexity_input.py

@@ -19,7 +19,7 @@ search_agent = Agent(
     goal=f"Find {num_results} relevant results about {topic}",
     backstory="Expert in internet research and data collection",
     tools=[duckduckgo],
-    self_reflect=False
+    reflection=False
 )
 
 # Create analysis agent

examples/python/models/googlegemini/any-llm-agents-advanced.py

@@ -34,9 +34,7 @@ agent = Agent(
     llm=llm_config,                  # Pass the detailed configuration
     verbose=True,                    # Enable detailed output
     markdown=True,                   # Format responses in markdown
-    self_reflect=True,              # Enable self-reflection
-    max_reflect=3,                  # Maximum reflection iterations
-    min_reflect=1                   # Minimum reflection iterations
+    reflection=True               # Enable self-reflection
 )
 
 # Test the agent