Release v3.4.1

## 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:
@@ -575,11 +538,11 @@ python app.py
 
 Create app.py file and add the code below:
 ```python
-from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents import Agent, Agents
 
 research_agent = Agent(instructions="Research about AI")
 summarise_agent = Agent(instructions="Summarise research agent's findings")
-agents = PraisonAIAgents(agents=[research_agent, summarise_agent])
+agents = Agents(agents=[research_agent, summarise_agent])
 agents.start()
 ```
 
@@ -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
@@ -3341,11 +3380,11 @@ See [Agent Memory](#6-agent-memory-zero-dependencies) for more options.
 <summary><strong>How do I run multiple agents together?</strong></summary>
 
 ```python
-from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents import Agent, Agents
 
 agent1 = Agent(instructions="Research topics")
 agent2 = Agent(instructions="Summarize findings")
-agents = PraisonAIAgents(agents=[agent1, agent2])
+agents = Agents(agents=[agent1, agent2])
 agents.start()
 ```
 

api_server.py

@@ -1,71 +0,0 @@
-"""
-Auto-generated API server for PraisonAI agents.
-"""
-from flask import Flask, request, jsonify
-from flask_cors import CORS
-from praisonai import PraisonAI
-import os
-
-app = Flask(__name__)
-
-# CORS configuration
-CORS(app)
-
-# Authentication
-AUTH_ENABLED = False
-AUTH_TOKEN = None
-
-def check_auth():
-    """Check authentication if enabled."""
-    if not AUTH_ENABLED:
-        return True
-    
-    token = request.headers.get('Authorization', '').replace('Bearer ', '')
-    return token == AUTH_TOKEN
-
-@app.route('/health', methods=['GET'])
-def health():
-    """Health check endpoint."""
-    return jsonify({"status": "ok", "service": "praisonai-api"})
-
-@app.route('/chat', methods=['POST'])
-def chat():
-    """Chat endpoint for agent interaction."""
-    if not check_auth():
-        return jsonify({"error": "Unauthorized"}), 401
-    
-    data = request.get_json()
-    if not data or 'message' not in data:
-        return jsonify({"error": "Message required"}), 400
-    
-    try:
-        praisonai = PraisonAI(agent_file="agents.yaml")
-        result = praisonai.run()
-        
-        return jsonify({
-            "response": result,
-            "status": "success"
-        })
-    except Exception as e:
-        return jsonify({
-            "error": str(e),
-            "status": "error"
-        }), 500
-
-@app.route('/agents', methods=['GET'])
-def list_agents():
-    """List available agents."""
-    if not check_auth():
-        return jsonify({"error": "Unauthorized"}), 401
-    
-    return jsonify({
-        "agents": ["default"],
-        "agent_file": "agents.yaml"
-    })
-
-if __name__ == '__main__':
-    app.run(
-        host='0.0.0.0',
-        port=8080,
-        debug=False
-    )

docker/Dockerfile.chat

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.9.2" \
+    "praisonai>=3.4.1" \
     "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/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/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 Agents")
+    print("    agents = Agents(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 Agents via context= param,
+and also shows low-level MultiAgentLedger usage for advanced scenarios.
+
+Agent-Centric Quick Start:
+    from praisonaiagents import Agent, Agents
+    from praisonaiagents.context import ManagerConfig
+    
+    agents = Agents(
+        agents=[agent1, agent2],
+        context=ManagerConfig(policy="isolated"),  # or "shared"
+    )
+"""
+
+import os
+import tempfile
+from praisonaiagents import Agent, Agents
+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 Agents(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 Agents, 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 = Agents(
+        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/guardrail_example_fixed.py

@@ -4,7 +4,7 @@ Fixed example demonstrating proper guardrail usage with PraisonAI Agents.
 This addresses the issues reported in issue #875.
 """
 
-from praisonaiagents import Agent, Task, GuardrailResult, PraisonAIAgents, TaskOutput
+from praisonaiagents import Agent, Task, GuardrailResult, Agents, TaskOutput
 from typing import Tuple, Any
 import trafilatura
 
@@ -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,13 +97,13 @@ 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"
 )
 
 # Run with GuardrailResult example
 print("=== Running with GuardrailResult guardrail ===")
-agents_gr = PraisonAIAgents(
+agents_gr = Agents(
     agents=[agent],
     tasks=[task_with_guardrailresult]
 )
@@ -113,7 +113,7 @@ agents_gr = PraisonAIAgents(
 
 # Run with Tuple example
 print("\n=== Running with Tuple[bool, Any] guardrail ===")
-agents_tuple = PraisonAIAgents(
+agents_tuple = Agents(
     agents=[agent],
     tasks=[task_with_tuple]
 )
@@ -123,7 +123,7 @@ agents_tuple = PraisonAIAgents(
 
 # Run with LLM guardrail example
 print("\n=== Running with LLM-based guardrail ===")
-agents_llm = PraisonAIAgents(
+agents_llm = Agents(
     agents=[agent],
     tasks=[task_with_llm_guardrail]
 )

examples/interactive_defaults/interactive_tools_example.py

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

examples/knowledge/compression_demo.py

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

examples/knowledge/context_required_example.py

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

examples/knowledge/hierarchical_summaries_demo.py

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

examples/knowledge/large_corpus_strategy_demo.py

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

examples/knowledge/mem0_backend_example.py

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

examples/knowledge/scope_identifiers_example.py

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

examples/knowledge/scope_isolation_example.py

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

examples/observability/multi_agent_tracing.py

@@ -14,7 +14,7 @@ Usage:
 
 from praisonai_tools.observability import obs
 from praisonai_tools.observability.base import SpanKind
-from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents import Agent, Agents
 
 # Initialize observability
 obs.init()

examples/output_ux/basic_output_example.py

@@ -13,7 +13,7 @@ Features demonstrated:
 
 import sys
 sys.path.insert(0, '/Users/praison/praisonai-package/src/praisonai-agents')
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 
 def get_weather(city: str) -> str:
@@ -106,7 +106,7 @@ def example_multi_agent():
         agent=writer
     )
     
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[researcher, writer],
         tasks=[task1, task2],
         process="sequential",

examples/policy/basic_policy.py

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

examples/python/agents/autoagents-hierarchical-generation.py

@@ -5,7 +5,7 @@ This example demonstrates hierarchical agent patterns using PraisonAI
 for structured task delegation and coordinated workflows.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== AutoAgents Hierarchical Generation Example ===\n")
@@ -58,7 +58,7 @@ execution_task = Task(
 )
 
 # Run hierarchical workflow
-agents_system = PraisonAIAgents(
+agents_system = Agents(
     agents=[manager_agent, research_agent],
     tasks=[planning_task, execution_task],
     process="sequential",

examples/python/agents/code-agent.py

@@ -5,7 +5,7 @@ This example demonstrates a comprehensive code agent that can write, analyze, de
 It includes self-reflection for improving code quality and multiple specialized tools.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import CodeInterpreter
 
 # Initialize code execution tool
@@ -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(
@@ -84,7 +84,7 @@ def demonstrate_code_agent():
     )
     
     # Create workflow
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[code_writer, code_reviewer, code_executor],
         tasks=[write_task, review_task, execute_task],
         process="sequential",
@@ -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

@@ -4,7 +4,7 @@ from praisonaiagents.tools import duckduckgo
 agent = Agent(instructions="You are a Image Analysis Agent", tools=[duckduckgo])
 agent.start("I want to go London next week, find me a good hotel and flight")
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Create Image Analysis Agent
 image_agent = Agent(
@@ -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
@@ -35,8 +35,8 @@ task2 = Task(
     images=["image.jpg"] 
 )
 
-# Create PraisonAIAgents instance
-agents = PraisonAIAgents(
+# Create Agents instance
+agents = Agents(
     agents=[image_agent],
     tasks=[task1, task2],
     process="sequential",

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

@@ -4,7 +4,7 @@ from praisonaiagents.tools import duckduckgo
 agent = Agent(instructions="You are a Image Analysis Agent", tools=[duckduckgo])
 agent.start("I want to go London next week, find me a good hotel and flight")
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Create Image Analysis Agent
 image_agent = Agent(
@@ -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
@@ -35,8 +35,8 @@ task2 = Task(
     images=["image.jpg"] 
 )
 
-# Create PraisonAIAgents instance
-agents = PraisonAIAgents(
+# Create Agents instance
+agents = Agents(
     agents=[image_agent],
     tasks=[task1, task2],
     process="sequential",

examples/python/agents/math-agent.py

@@ -5,7 +5,7 @@ This example demonstrates a mathematical problem-solving agent that can handle v
 including calculations, equation solving, and step-by-step explanations.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import Dict, Any
 import math
 import re
@@ -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(
@@ -123,7 +123,7 @@ def solve_math_problem_workflow():
         context=[solve_task]
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[problem_solver_agent, calculation_agent, math_tutor_agent],
         tasks=[understand_task, solve_task, verify_task],
         process="sequential",
@@ -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/multi-provider-agent.py

@@ -6,7 +6,7 @@ agent-based selection for cost optimization and performance.
 """
 
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.agent import RouterAgent
 from praisonaiagents.llm.model_router import ModelRouter, ModelProfile, TaskComplexity
 
@@ -49,7 +49,7 @@ def example_auto_routing():
     )
     
     # Run the tasks
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[research_agent],
         tasks=[simple_task, moderate_task, complex_task],
         process="sequential",
@@ -118,7 +118,7 @@ def example_cost_optimized_workflow():
     )
     
     # Run workflow
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[analyzer, writer],
         tasks=[analysis_task, writing_task],
         process="sequential",
@@ -249,7 +249,7 @@ def example_custom_routing():
     ]
     
     # Run tasks
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[coder],
         tasks=tasks,
         process="sequential",

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

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Create Video Analysis Agent
 video_agent = Agent(
@@ -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
@@ -24,8 +24,8 @@ task1 = Task(
     images=["video.mp4"]  
 )
 
-# Create PraisonAIAgents instance
-agents = PraisonAIAgents(
+# Create Agents instance
+agents = Agents(
     agents=[video_agent],
     tasks=[task1],
     process="sequential",

examples/python/agents/wikipedia-agent.py

@@ -1,12 +1,12 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import wiki_search, wiki_summary, wiki_page, wiki_random, wiki_language
 
 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/api/secondary-market-research-api.py

@@ -32,7 +32,7 @@ import os
 from pathlib import Path
 
 # Import our market research system
-from praisonaiagents import Agent, Task, PraisonAIAgents, Tools
+from praisonaiagents import Agent, Task, Agents, Tools
 
 # Create FastAPI app
 app = FastAPI(
@@ -266,7 +266,7 @@ async def generate_market_research_report(job_id: str, config: MarketResearchCon
         job_status[job_id]["message"] = "Setting up research workflow..."
         
         # Create workflow
-        workflow = PraisonAIAgents(
+        workflow = Agents(
             agents=list(agents.values()),
             tasks=tasks,
             process="sequential",

examples/python/camera/camera-basic.py

@@ -16,7 +16,7 @@ Environment Variables:
 
 import cv2
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 
 def capture_and_analyze():
@@ -58,7 +58,7 @@ def capture_and_analyze():
             )
             
             # Run analysis
-            agents = PraisonAIAgents(
+            agents = Agents(
                 agents=[vision_agent],
                 tasks=[task],
                 process="sequential",

examples/python/camera/camera-continuous.py

@@ -18,7 +18,7 @@ import cv2
 import time
 import os
 from datetime import datetime
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 
 class ContinuousCameraMonitor:
@@ -71,7 +71,7 @@ class ContinuousCameraMonitor:
             images=[image_path]
         )
         
-        agents = PraisonAIAgents(
+        agents = Agents(
             agents=[self.vision_agent],
             tasks=[task],
             process="sequential",

examples/python/camera/camera-multi-agent.py

@@ -17,7 +17,7 @@ Environment Variables:
 import cv2
 import os
 from datetime import datetime
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 
 def capture_camera_frame(camera_id=0):
@@ -114,7 +114,7 @@ def analyze_with_multiple_agents():
     )
     
     # Run multi-agent analysis
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[security_agent, object_detector, scene_analyst],
         tasks=[security_task, object_task, scene_task],
         process="parallel",  # Run all analyses in parallel

examples/python/camera/camera-video-analysis.py

@@ -18,7 +18,7 @@ import cv2
 import os
 import time
 from datetime import datetime
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 
 class CameraVideoAnalyzer:
@@ -131,7 +131,7 @@ class CameraVideoAnalyzer:
             images=[video_path]  # PraisonAI supports video files in images parameter
         )
         
-        agents = PraisonAIAgents(
+        agents = Agents(
             agents=[self.video_agent],
             tasks=[task],
             process="sequential",

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/context-engineering-workflow.py

@@ -24,7 +24,7 @@ from pathlib import Path
 project_root = Path(__file__).parent.parent.parent.parent / "src" / "praisonai-agents"
 sys.path.insert(0, str(project_root))
 
-from praisonaiagents import Agent, Task, PraisonAIAgents, create_context_agent
+from praisonaiagents import Agent, Task, Agents, create_context_agent
 
 class ContextEngineeringWorkflow:
     """
@@ -312,7 +312,7 @@ class ContextEngineeringWorkflow:
         print("\n⚙️ Executing Context Engineering Workflow")
         print("-" * 50)
         
-        agents_workflow = PraisonAIAgents(
+        agents_workflow = Agents(
             agents=[
                 self.product_manager,
                 self.architect, 

examples/python/concepts/csv-processing-agents.py

@@ -11,7 +11,7 @@ Author: Generated for GitHub Issue #23
 """
 
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import read_csv, write_csv
 
 def create_sample_urls_csv():
@@ -81,7 +81,7 @@ def method_1_simple_loop():
     )
     
     # Initialize the agents system
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[loop_agent],
         tasks=[loop_task],
         process="workflow",
@@ -145,7 +145,7 @@ def method_2_manual_csv():
     )
     
     # Initialize and run
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[csv_agent],
         tasks=[csv_task],
         process="sequential"
@@ -211,7 +211,7 @@ def method_3_url_processing():
     )
     
     # Initialize and run
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[url_agent],
         tasks=[url_task],
         process="sequential"
@@ -319,7 +319,7 @@ def method_4_advanced_processing():
     )
     
     # Initialize and run with sequential processing
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[validator_agent, processor_agent],
         tasks=[validation_task, processing_task],
         process="sequential"  # Validation must complete before processing

examples/python/concepts/knowledge-agents-task.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import logging
 import os
 
@@ -37,7 +37,7 @@ knowledge_task = Task(
 )
 
 # Create and start the agents
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[knowledge_agent],
     tasks=[knowledge_task],
     process="sequential",

examples/python/concepts/rag-agents.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Define the configuration for the Knowledge instance
 config = {
@@ -29,7 +29,7 @@ rag_task = Task(
 )
 
 # Build Agents
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[rag_agent],
     tasks=[rag_task],
     user_id="user1"

examples/python/concepts/reasoning-extraction.py

@@ -8,7 +8,7 @@ This example demonstrates how to extract and utilize reasoning patterns in Prais
 - Decision rationale extraction
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import Dict, List, Tuple
 from pydantic import BaseModel
 import json
@@ -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
@@ -100,7 +100,7 @@ def demonstrate_reasoning_extraction():
         context=[problem_task]
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[cot_agent, reasoning_extractor],
         tasks=[problem_task, extract_task],
         process="sequential",
@@ -184,7 +184,7 @@ def advanced_reasoning_patterns():
         context=[deductive_task, inductive_task, abductive_task]
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[cot_agent, reasoning_validator],
         tasks=[deductive_task, inductive_task, abductive_task, validation_task],
         process="sequential",
@@ -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/repetitive-agents.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 agent = Agent(
     instructions="You are a loop agent that creating a loop of tasks.",
@@ -12,7 +12,7 @@ task = Task(
     input_file="tasks.csv"
 )
 
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[agent],
     tasks=[task],
     process="workflow",

examples/python/concepts/routing-patterns.py

@@ -8,7 +8,7 @@ This example demonstrates various routing patterns in PraisonAI including:
 - Dynamic task selection
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import Dict, Any
 import random
 
@@ -77,7 +77,7 @@ def conditional_routing_example():
         agent=processor_agent
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[analyzer_agent, processor_agent],
         tasks=[analysis_task, premium_task, standard_task, basic_task],
         process="workflow",
@@ -110,7 +110,7 @@ def loop_pattern_example():
         agent=validator_agent
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[processor_agent, validator_agent],
         tasks=[process_task, finalize_task],
         process="workflow",
@@ -185,7 +185,7 @@ def decision_tree_example():
     
     all_tasks = [categorize_task, technical_task, business_task] + terminal_tasks
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[analyzer_agent, processor_agent],
         tasks=all_tasks,
         process="workflow",
@@ -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():
@@ -272,7 +272,7 @@ def dynamic_routing_example():
         agent=processor_agent
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[dynamic_router, processor_agent],
         tasks=[route_task, escalate_task, automate_task, review_task, standard_task],
         process="workflow",

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

@@ -8,7 +8,7 @@ This example demonstrates the self-reflection capabilities in PraisonAI agents:
 - Impact on output quality
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import Dict, Any
 import time
 
@@ -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
@@ -162,7 +162,7 @@ def reflection_workflow_example():
         context=[create_task, review_task]
     )
     
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[creator_agent, reviewer_agent, polisher_agent],
         tasks=[create_task, review_task, polish_task],
         process="sequential",
@@ -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

@@ -5,7 +5,7 @@ This example demonstrates self-reflection capabilities using PraisonAI's
 built-in reflection features for iterative improvement and quality optimization.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== Self-Reflection Optimization Patterns Example ===\n")
@@ -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/concepts/simple-csv-url-processor.py

@@ -9,7 +9,7 @@ This is the simplest possible implementation for processing URLs from a CSV file
 Author: Generated for GitHub Issue #23
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import write_csv
 
 def create_url_csv():
@@ -59,7 +59,7 @@ def main():
     )
     
     # Step 4: Run the agents
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[url_agent],
         tasks=[url_task],
         process="workflow",

examples/python/custom_tools/example_latency_tracking.py

@@ -4,7 +4,7 @@ Example: Using Latency Tracking Tool with PraisonAI
 This example shows how to track latency without modifying core files.
 """
 
-from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents import Agent, Agents
 from latency_tracker_tool import (
     latency_tracking_tool, 
     create_tracked_agent,

examples/python/custom_tools/mcp_server_latency_example.py

@@ -5,7 +5,7 @@ This shows how to add latency tracking to an MCP server
 without modifying PraisonAI core files.
 """
 
-from praisonaiagents import Agent, PraisonAIAgents
+from praisonaiagents import Agent, Agents
 from hosted_server import HostedMCPServer  # Import from local file
 from latency_tracker_tool import tracker, get_latency_metrics
 import json

examples/python/data/cot-agents.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import cot_save, cot_upload_to_huggingface
 from pydantic import BaseModel
 import os
@@ -131,7 +131,7 @@ upload_to_huggingface_task = Task(
 )
 
 # Initialize workflow
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[qa_generator, total_questions_evaluator, cot_generator, upload_to_huggingface],
     tasks=[generate_task, evaluate_total_questions_task, generate_cot_task, upload_to_huggingface_task],
     process="workflow",

examples/python/escalation_example.py

@@ -0,0 +1,192 @@
+"""
+Escalation Pipeline Example.
+
+Demonstrates the progressive escalation from direct response to autonomous mode.
+"""
+
+import asyncio
+from praisonaiagents.escalation import (
+    EscalationPipeline,
+    EscalationStage,
+    EscalationConfig,
+    EscalationTrigger,
+    DoomLoopDetector,
+    ObservabilityHooks,
+    EventType,
+)
+
+
+def demo_signal_detection():
+    """Demonstrate signal detection from prompts."""
+    print("\n" + "="*60)
+    print("SIGNAL DETECTION DEMO")
+    print("="*60)
+    
+    trigger = EscalationTrigger()
+    
+    # Test various prompts
+    test_prompts = [
+        ("What is Python?", "Simple question"),
+        ("Read the file src/main.py", "File reference"),
+        ("Refactor the authentication module and add tests", "Complex task"),
+        ("First, analyze the code. Then, fix the bug. Finally, test it.", "Multi-step"),
+    ]
+    
+    for prompt, description in test_prompts:
+        signals = trigger.analyze(prompt)
+        stage = trigger.recommend_stage(signals)
+        
+        print(f"\n📝 Prompt: {prompt[:50]}...")
+        print(f"   Description: {description}")
+        print(f"   Signals: {[s.value for s in signals]}")
+        print(f"   Recommended Stage: {stage.name}")
+
+
+def demo_doom_loop_detection():
+    """Demonstrate doom loop detection."""
+    print("\n" + "="*60)
+    print("DOOM LOOP DETECTION DEMO")
+    print("="*60)
+    
+    detector = DoomLoopDetector()
+    detector.start_session()
+    
+    # Simulate repeated identical actions
+    print("\n🔄 Simulating repeated identical actions...")
+    for i in range(4):
+        detector.record_action(
+            action_type="read_file",
+            args={"path": "config.py"},
+            result="same content",
+            success=True,
+        )
+        
+        if detector.is_doom_loop():
+            loop_type = detector.get_loop_type()
+            recovery = detector.get_recovery_action()
+            print(f"   ⚠️  Doom loop detected after {i+1} actions!")
+            print(f"   Type: {loop_type.value}")
+            print(f"   Recovery: {recovery.value}")
+            break
+        else:
+            print(f"   Action {i+1}: No loop detected")
+    
+    # Show stats
+    stats = detector.get_stats()
+    print(f"\n📊 Stats: {stats}")
+
+
+def demo_observability():
+    """Demonstrate observability hooks."""
+    print("\n" + "="*60)
+    print("OBSERVABILITY DEMO")
+    print("="*60)
+    
+    hooks = ObservabilityHooks()
+    
+    # Register event handlers
+    def on_stage_change(event):
+        print(f"   📍 Stage changed: {event.data}")
+    
+    def on_tool_call(event):
+        print(f"   🔧 Tool called: {event.data}")
+    
+    hooks.on(EventType.STAGE_ESCALATE, on_stage_change)
+    hooks.on(EventType.TOOL_CALL_END, on_tool_call)
+    
+    # Simulate events
+    print("\n🎯 Simulating execution events...")
+    hooks.start_execution("session_123")
+    
+    hooks.set_stage(EscalationStage.DIRECT)
+    hooks.emit(EventType.STEP_START, {"step": 1})
+    hooks.emit(EventType.TOOL_CALL_END, {"tool": "read_file", "path": "main.py"})
+    hooks.emit(EventType.STEP_END, {"step": 1})
+    
+    hooks.emit(EventType.STAGE_ESCALATE, {"from": "DIRECT", "to": "HEURISTIC"})
+    hooks.set_stage(EscalationStage.HEURISTIC)
+    
+    hooks.end_execution(1500.0)
+    
+    # Show summary
+    summary = hooks.get_summary()
+    print(f"\n📊 Summary: {summary}")
+
+
+def demo_stage_descriptions():
+    """Show descriptions of each escalation stage."""
+    print("\n" + "="*60)
+    print("ESCALATION STAGES")
+    print("="*60)
+    
+    trigger = EscalationTrigger()
+    
+    stages = [
+        (EscalationStage.DIRECT, "Simple questions, no tools needed"),
+        (EscalationStage.HEURISTIC, "File references, code blocks"),
+        (EscalationStage.PLANNED, "Edit intent, test/build tasks"),
+        (EscalationStage.AUTONOMOUS, "Multi-step, refactoring tasks"),
+    ]
+    
+    for stage, example in stages:
+        desc = trigger.get_stage_description(stage)
+        print(f"\n🎯 Stage {stage.value}: {stage.name}")
+        print(f"   Description: {desc}")
+        print(f"   Example use: {example}")
+
+
+async def demo_pipeline_analysis():
+    """Demonstrate pipeline analysis."""
+    print("\n" + "="*60)
+    print("PIPELINE ANALYSIS DEMO")
+    print("="*60)
+    
+    config = EscalationConfig(
+        max_steps=20,
+        max_time_seconds=60,
+        auto_escalate=True,
+    )
+    
+    pipeline = EscalationPipeline(config=config)
+    
+    prompts = [
+        "What is a Python decorator?",
+        "Read the file src/auth.py and explain it",
+        "Refactor the user authentication to use JWT tokens",
+    ]
+    
+    for prompt in prompts:
+        stage = pipeline.analyze(prompt)
+        print(f"\n📝 Prompt: {prompt[:50]}...")
+        print(f"   Recommended Stage: {stage.name}")
+
+
+def main():
+    """Run all demos."""
+    print("\n" + "="*60)
+    print("PRAISONAI ESCALATION PIPELINE DEMO")
+    print("="*60)
+    print("\nThis demo shows the progressive escalation system that")
+    print("automatically adjusts execution complexity based on task signals.")
+    
+    # Run demos
+    demo_stage_descriptions()
+    demo_signal_detection()
+    demo_doom_loop_detection()
+    demo_observability()
+    asyncio.run(demo_pipeline_analysis())
+    
+    print("\n" + "="*60)
+    print("DEMO COMPLETE")
+    print("="*60)
+    print("\nKey takeaways:")
+    print("1. Simple tasks stay at DIRECT stage (no tools)")
+    print("2. File references trigger HEURISTIC stage")
+    print("3. Edit/test tasks trigger PLANNED stage")
+    print("4. Multi-step/refactor tasks trigger AUTONOMOUS stage")
+    print("5. Doom loop detection prevents infinite loops")
+    print("6. Observability hooks enable monitoring")
+
+
+if __name__ == "__main__":
+    main()

examples/python/general/advanced-callback-systems.py

@@ -5,7 +5,7 @@ This example demonstrates callback systems using PraisonAI's built-in
 callback functionality for monitoring agent interactions and tool usage.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.display_callback import register_display_callback
 from praisonaiagents.tools import internet_search
 

examples/python/general/async_example.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 from typing import List, Dict
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+from praisonaiagents import Agent, Task, Agents, TaskOutput
 from praisonaiagents.main import (
     display_error,
     display_interaction,
@@ -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
 )
@@ -160,7 +160,7 @@ workflow_async_task = Task(
 def run_sync_example():
     """Run synchronous example"""
     display_instruction("\nRunning Synchronous Example...", console)
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[sync_agent],
         tasks=[sync_task],
         verbose=1,
@@ -172,7 +172,7 @@ def run_sync_example():
 async def run_async_example():
     """Run asynchronous example"""
     display_instruction("\nRunning Asynchronous Example...", console)
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[async_agent],
         tasks=[async_task],
         verbose=1,
@@ -184,7 +184,7 @@ async def run_async_example():
 async def run_mixed_example():
     """Run mixed sync/async example"""
     display_instruction("\nRunning Mixed Sync/Async Example...", console)
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[sync_agent, async_agent],
         tasks=[sync_task, async_task],
         verbose=1,
@@ -196,7 +196,7 @@ async def run_mixed_example():
 async def run_workflow_example():
     """Run workflow example with both sync and async tasks"""
     display_instruction("\nRunning Workflow Example...", console)
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[sync_agent, async_agent],
         tasks=[workflow_sync_task, workflow_async_task],
         verbose=1,

examples/python/general/async_example_full.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 from typing import List, Dict
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+from praisonaiagents import Agent, Task, Agents, TaskOutput
 from duckduckgo_search import DDGS
 from pydantic import BaseModel
 
@@ -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
 )
@@ -114,8 +114,8 @@ async def run_parallel_tasks():
         context=parallel_tasks
     )
     
-    # Create a single PraisonAIAgents instance with both agents
-    agents = PraisonAIAgents(
+    # Create a single Agents instance with both agents
+    agents = Agents(
         agents=[async_agent, summary_agent],
         tasks=parallel_tasks + [summary_task],
         verbose=1,

examples/python/general/async_example_full_multigroups.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 from typing import List, Dict
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+from praisonaiagents import Agent, Task, Agents, TaskOutput
 from duckduckgo_search import DDGS
 from pydantic import BaseModel
 
@@ -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
 )
@@ -103,7 +103,7 @@ async_task = Task(
 async def run_single_task():
     """Run single async task"""
     print("\nRunning Single Async Task...")
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[async_agent],
         tasks=[async_task],
         verbose=1,
@@ -187,7 +187,7 @@ Present the summary in a clear, structured format with sections for findings, pa
     )
     
     # First run parallel search tasks
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[async_agent],
         tasks=parallel_tasks,  # Only run search tasks first
         verbose=1,
@@ -212,7 +212,7 @@ Present the summary in a clear, structured format with sections for findings, pa
     summary_task.context = completed_tasks
     
     # Run summarization task with summary agent
-    summary_agents = PraisonAIAgents(
+    summary_agents = Agents(
         agents=[summary_agent],  # Use summary agent for synthesis
         tasks=[summary_task],
         verbose=1,

examples/python/general/autonomous-agent.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import time
 
 def get_environment_state():
@@ -86,7 +86,7 @@ feedback_task = Task(
 )
 
 # Create workflow manager
-workflow = PraisonAIAgents(
+workflow = Agents(
     agents=[llm_caller, action_agent, feedback_agent],
     tasks=[monitor_task, action_task, feedback_task],
     process="workflow",

examples/python/general/code_agents_example.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import json
 from e2b_code_interpreter import Sandbox
 
@@ -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]
 )
 
@@ -46,5 +46,5 @@ execution_agent_task = Task(
     agent=execution_agent
 )
 
-agents = PraisonAIAgents(agents=[code_agent, execution_agent], tasks=[code_agent_task, execution_agent_task])
+agents = Agents(agents=[code_agent, execution_agent], tasks=[code_agent_task, execution_agent_task])
 agents.start()

examples/python/general/evaluator-optimiser.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Create generator and evaluator agents
 generator = Agent(
@@ -53,7 +53,7 @@ evaluate_task = Task(
 )
 
 # Create workflow manager
-workflow = PraisonAIAgents(
+workflow = Agents(
     agents=[generator, evaluator],
     tasks=[generate_task, evaluate_task],
     process="workflow",

examples/python/general/example_callback.py

@@ -1,7 +1,7 @@
 from praisonaiagents import (
     Agent, 
     Task, 
-    PraisonAIAgents, 
+    Agents, 
     error_logs, 
     register_display_callback,
     sync_display_callbacks,
@@ -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(
@@ -190,7 +190,7 @@ def main():
     )
 
     # Create and run agents manager
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[researcher, writer],
         tasks=[task1, task2, task3, task4],
         verbose=True,

examples/python/general/example_custom_tools.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import List, Dict, Union
 from duckduckgo_search import DDGS
 from langchain_community.tools import YouTubeSearchTool
@@ -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
@@ -141,7 +141,7 @@ validate_task = Task(
 )
 
 # 4. Workflow
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[data_agent],
     tasks=[collect_task, validate_task],
     verbose=1,

examples/python/general/example_sequential.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents, error_logs
+from praisonaiagents import Agent, Task, Agents, error_logs
 from duckduckgo_search import DDGS
 
 def my_callback(output):
@@ -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",
@@ -99,7 +99,7 @@ task4 = Task(
 )
 
 # Create and run agents manager
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[researcher, writer],
     tasks=[task1, task2, task3, task4],
     verbose=False,

examples/python/general/human_approval_example.py

@@ -24,7 +24,7 @@ import sys
 # Add the local development path to use the current implementation
 sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..', 'src', 'praisonai-agents'))
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import python_tools, file_tools, shell_tools
 from praisonaiagents.main import register_approval_callback
 from praisonaiagents.approval import (
@@ -111,7 +111,7 @@ def main():
     ]
     
     # Create and run process
-    process = PraisonAIAgents(
+    process = Agents(
         agents=[agent],
         tasks=tasks,
         verbose=True
@@ -171,7 +171,7 @@ async def async_demo():
         expected_output="Async execution result"
     )
     
-    process = PraisonAIAgents(
+    process = Agents(
         agents=[agent],
         tasks=[task],
         verbose=True

examples/python/general/langchain_example.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from langchain_community.tools import YouTubeSearchTool
 from langchain_community.utilities import WikipediaAPIWrapper
 
@@ -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
@@ -21,7 +21,7 @@ task = Task(
 )
 
 # Create and start the workflow
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[agent],
     tasks=[task],
     verbose=True

examples/python/general/memory_example.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import logging
 import os
 
@@ -25,7 +25,7 @@ def main():
     # else:
     #     logger.info("Creating new memory database")
     
-    # Create task config (without memory config since it's moved to PraisonAIAgents)
+    # Create task config (without memory config since it's moved to Agents)
     task_config = {}
 
     # Create agents with different roles
@@ -100,8 +100,8 @@ def main():
         agent=retriever
     )
 
-    # Initialize PraisonAIAgents with memory configuration
-    agents = PraisonAIAgents(
+    # Initialize Agents with memory configuration
+    agents = Agents(
         agents=[researcher, retriever],
         tasks=[store_task, verify_task, query_task, query_both_task],
         verbose=True,  # Use same verbose level as memory
@@ -114,7 +114,7 @@ def main():
         }
     )
 
-    # agents = PraisonAIAgents(
+    # agents = Agents(
     #     agents=[researcher, retriever],
     #     tasks=[store_task, verify_task, query_task, query_both_task],
     #     verbose=True,  # Use same verbose level as memory

examples/python/general/memory_simple.py

@@ -1,4 +1,4 @@
-from praisonaiagents.agents.agents import Agent, Task, PraisonAIAgents
+from praisonaiagents.agents.agents import Agent, Task, Agents
 from praisonaiagents.tools import duckduckgo
 
 # Test facts
@@ -54,7 +54,7 @@ blog_task = Task(
     agent=blog_agent
 )
 
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[fact_agent, research_agent, blog_agent],
     tasks=[fact_task, research_task, research_task2, research_task3, research_task4, blog_task],
     memory=True

examples/python/general/multimodal.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Create Vision Analysis Agent
 vision_agent = Agent(
@@ -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
@@ -42,8 +42,8 @@ task3 = Task(
     images=["video.mp4"]  
 )
 
-# Create PraisonAIAgents instance
-agents = PraisonAIAgents(
+# Create Agents instance
+agents = Agents(
     agents=[vision_agent],
     tasks=[task1, task2, task3],
     process="sequential",

examples/python/general/orchestrator-workers.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import time
 
 def get_time_check():
@@ -93,7 +93,7 @@ synthesize_task = Task(
 )
 
 # Create workflow manager
-workflow = PraisonAIAgents(
+workflow = Agents(
     agents=[router, worker1, worker2, worker3, synthesizer],
     tasks=[router_task, worker1_task, worker2_task, worker3_task, synthesize_task],
     process="workflow",

examples/python/general/parallelisation.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from datetime import datetime
 import asyncio
 
@@ -75,7 +75,7 @@ aggregate_task = Task(
 async def main():
 
     # Create workflow manager
-    workflow = PraisonAIAgents(
+    workflow = Agents(
         agents=[agent1, agent2, agent3, aggregator],
         tasks=[task1, task2, task3, aggregate_task],
         process="workflow"

examples/python/general/prompt_chaining.py

@@ -1,6 +1,6 @@
 from praisonaiagents.agent import Agent
 from praisonaiagents.task import Task
-from praisonaiagents.agents import PraisonAIAgents
+from praisonaiagents.agents import Agents
 from typing import List, Dict
 import time
 
@@ -64,7 +64,7 @@ final_task = Task(
 )
 
 # Create the workflow manager
-workflow = PraisonAIAgents(
+workflow = Agents(
     agents=[agent1, agent2, agent3],
     tasks=[initial_task, analysis_task, final_task],
     process="workflow",  # Use workflow process type

examples/python/general/structured_agents_example.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents, Tools
+from praisonaiagents import Agent, Task, Agents, Tools
 from pydantic import BaseModel
 
 class AnalysisReport(BaseModel):
@@ -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
@@ -46,7 +46,7 @@ analysis_task = Task(
 )
 
 # Initialize and run agents
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[researcher, analyst],
     tasks=[research_task, analysis_task],
     process="sequential",

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

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import os
 import requests
 from typing import Any, Dict, List, Optional
@@ -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
@@ -106,7 +106,7 @@ task = Task(
 )
 
 # Create and start the workflow
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[agent],
     tasks=[task],
     verbose=True

examples/python/general/tools_example.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import get_article, get_news_sources, get_articles_from_source, get_trending_topics
 
 # Create Wikipedia agent
@@ -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
 )
 
 
@@ -22,7 +22,7 @@ news_task = Task(
 
 
 # Run agent
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[news_agent],
     tasks=[news_task],
     process="sequential"

examples/python/general/workflow_example_basic.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from typing import List, Dict
 from duckduckgo_search import DDGS
 
@@ -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
@@ -64,7 +64,7 @@ validate_task = Task(
 )
 
 # 4. AI Agents Workflow
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[data_agent],
     tasks=[collect_task, validate_task],
     verbose=1,

examples/python/general/workflow_example_detailed.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 import random
 from typing import List, Dict, Union
 import json
@@ -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
@@ -224,8 +224,8 @@ process_task = Task(
     output_json=ProcessedPerson
 )
 
-# Create PraisonAIAgents instance with workflow process
-workflow = PraisonAIAgents(
+# Create Agents instance with workflow process
+workflow = Agents(
     agents=[data_agent, process_agent],
     tasks=[collect_task, validate_task, process_task],
     verbose=1,

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

@@ -12,7 +12,7 @@ Features demonstrated:
 - Quality assurance workflows
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.task import TaskOutput
 from typing import Tuple, Any
 import re
@@ -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,12 +176,12 @@ 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
 )
 
 # Execute tasks with guardrails
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[email_agent, content_agent, business_agent, research_agent, llm_guardrail_agent],
     tasks=[email_task, content_task, business_task, research_task, llm_guardrail_task],
     verbose=True

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

@@ -5,7 +5,7 @@ This example demonstrates production guardrail patterns using PraisonAI's
 built-in validation and safety mechanisms for secure agent operations.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== Production Guardrails Patterns Example ===\n")
@@ -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

@@ -5,7 +5,7 @@ This example demonstrates an advanced system that dynamically creates agents and
 based on user inputs, including conditional logic, custom configurations, and file output.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import duckduckgo
 import os
 from typing import Dict, List
@@ -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)
@@ -137,7 +137,7 @@ class DynamicAgentSystem:
         
         # Run the system
         print(f"\n🚀 Starting {process} analysis for '{inputs['topic']}'...")
-        praison_agents = PraisonAIAgents(
+        praison_agents = Agents(
             agents=agents,
             tasks=tasks,
             process=process,

examples/python/input/environment_variable_input.py

@@ -6,7 +6,7 @@ to create flexible agent configurations that can be pre-configured via environme
 """
 
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Set via environment or use default
 default_topic = os.getenv("RESEARCH_TOPIC", "AI trends")
@@ -46,7 +46,7 @@ print(f"  - Max Retries: {max_retries}")
 print("\n" + "="*50 + "\n")
 
 # Run agents
-agents = PraisonAIAgents(agents=[agent], tasks=[task])
+agents = Agents(agents=[agent], tasks=[task])
 result = agents.start()
 
 # Save to environment-specified location if provided

examples/python/input/medium_complexity_input.py

@@ -5,7 +5,7 @@ This example shows how to use multiple user inputs to create a more sophisticate
 agent system with tools, multiple agents, and context passing between tasks.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import duckduckgo
 
 # Get multiple inputs
@@ -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
@@ -47,7 +47,7 @@ analyze_task = Task(
 )
 
 # Run sequential process
-agents = PraisonAIAgents(
+agents = Agents(
     agents=[search_agent, analysis_agent],
     tasks=[search_task, analyze_task],
     process="sequential"

examples/python/input/simple_input.py

@@ -5,7 +5,7 @@ This example demonstrates how to use basic user input to create dynamic agents a
 The user is prompted for a search query, and the agent searches for information about it.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 # Get user input
 user_query = input("What would you like to search for? ")
@@ -26,5 +26,5 @@ task = Task(
 )
 
 # Run
-agents = PraisonAIAgents(agents=[agent], tasks=[task])
+agents = Agents(agents=[agent], tasks=[task])
 agents.start()

examples/python/input/streamlit_ui_input.py

@@ -10,7 +10,7 @@ To run this example:
 """
 
 import streamlit as st
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import duckduckgo
 
 # Set page configuration
@@ -125,7 +125,7 @@ if st.button("🚀 Submit", type="primary", use_container_width=True):
                     )
                     
                     # Run agents
-                    agents = PraisonAIAgents(
+                    agents = Agents(
                         agents=[agent],
                         tasks=[task],
                         process=process_type

examples/python/memory/advanced-graph-memory-integration.py

@@ -5,7 +5,7 @@ This example demonstrates graph memory capabilities with PraisonAI agents
 for knowledge graph construction and relationship-aware memory retrieval.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== Advanced Graph Memory Integration Example ===\n")
@@ -59,7 +59,7 @@ query_task = Task(
 )
 
 # Run with graph memory integration
-agents_system = PraisonAIAgents(
+agents_system = Agents(
     agents=[knowledge_agent],
     tasks=[build_task, query_task],
     memory=True,

examples/python/memory/advanced-memory-search-optimization.py

@@ -5,7 +5,7 @@ This example demonstrates memory search optimization using PraisonAI's
 built-in memory capabilities with semantic search and quality filtering.
 """
 
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== Advanced Memory Search and Optimization Example ===\n")
@@ -60,7 +60,7 @@ search_task = Task(
 )
 
 # Run with memory optimization
-agents_system = PraisonAIAgents(
+agents_system = Agents(
     agents=[research_agent],
     tasks=[build_memory_task, search_task],
     memory=True,

examples/python/memory/gemini-embedding-example.py

@@ -20,7 +20,7 @@ Prerequisites:
 """
 
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 def main():
     """Demonstrate Gemini embedding usage"""
@@ -82,7 +82,7 @@ def main():
     
     # Configure with Gemini embeddings
     # Option 1: Using stable text-embedding-004
-    agents = PraisonAIAgents(
+    agents = Agents(
         agents=[researcher, retriever],
         tasks=[store_task, retrieve_task],
         verbose=True,
@@ -98,7 +98,7 @@ def main():
     )
     
     # Alternative: Using experimental model with advanced features
-    # agents = PraisonAIAgents(
+    # agents = Agents(
     #     agents=[researcher, retriever],
     #     tasks=[store_task, retrieve_task],
     #     verbose=True,

examples/python/memory/graph-memory-agent.py

@@ -16,7 +16,7 @@ Setup:
 """
 
 import os
-from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents import Agent, Task, Agents
 
 def main():
     # Example with Neo4j (uncomment and configure as needed)
@@ -150,7 +150,7 @@ def main():
     )
     
     # Run the multi-agent system with graph memory
-    agents_system = PraisonAIAgents(
+    agents_system = Agents(
         agents=[researcher],
         tasks=[build_knowledge_task, query_knowledge_task, expand_knowledge_task],
         verbose=1,

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

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

@@ -4,7 +4,7 @@ from praisonaiagents import Agent
 agent = Agent(
     instructions="You are a helpful assistant",
     llm="gemini/gemini-1.5-flash-8b",
-    self_reflect=True,
+    reflection=True,
     verbose=True
 )