Release v2.5.0

.gitignore

@@ -80,4 +80,6 @@ CopilotKit*
 issue_details.json
 
 # MCP Registry tokens
-.mcpregistry_*
+.mcpregistry_*
+
+*.log

README.md

@@ -261,6 +261,10 @@ npm install praisonai
 | ↳ 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/models) |
 | ↳ Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/features/callbacks) |
 | ↳ Hooks | [Example](#9-hooks) | [📖](https://docs.praison.ai/features/hooks) |
+| ↳ Middleware System | [Example](examples/middleware/basic_middleware.py) | [📖](https://docs.praison.ai/features/middleware) |
+| ↳ Configurable Model | [Example](examples/middleware/configurable_model.py) | [📖](https://docs.praison.ai/features/configurable-model) |
+| ↳ Rate Limiter | [Example](examples/middleware/rate_limiter.py) | [📖](https://docs.praison.ai/features/rate-limiter) |
+| ↳ Injected Tool State | [Example](examples/middleware/injected_state.py) | [📖](https://docs.praison.ai/features/injected-state) |
 | ↳ Shadow Git Checkpoints | [Example](#10-shadow-git-checkpoints) | [📖](https://docs.praison.ai/features/checkpoints) |
 | ↳ Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/features/background-tasks) |
 | ↳ Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/features/policy-engine) |
@@ -2763,11 +2767,11 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | SurrealDB | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Qdrant | Knowledge | `pip install "praisonai[tools]"` | [knowledge_qdrant.py](examples/persistence/knowledge_qdrant.py) | [docs](https://docs.praison.ai/docs/databases/qdrant) |
 | ChromaDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Pinecone | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Weaviate | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| LanceDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Pinecone | Knowledge | `pip install pinecone` | [pinecone_wow.py](examples/vector/pinecone_wow.py) | [docs](https://docs.praison.ai/docs/databases/pinecone) |
+| Weaviate | Knowledge | `pip install weaviate-client` | [weaviate_wow.py](examples/vector/weaviate_wow.py) | [docs](https://docs.praison.ai/docs/databases/weaviate) |
+| LanceDB | Knowledge | `pip install lancedb` | [lancedb_real_wow.py](examples/vector/lancedb_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/lancedb) |
 | Milvus | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| PGVector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| PGVector | Knowledge | `pip install psycopg2-binary` | [pgvector_real_wow.py](examples/vector/pgvector_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/pgvector) |
 | Redis Vector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Cassandra | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | ClickHouse | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |

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.4.2" \
+    "praisonai>=2.5.0" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

examples/middleware/basic_middleware.py

@@ -0,0 +1,55 @@
+"""
+Basic Middleware Example - PraisonAI Agents
+
+Demonstrates before/after hooks and wrap decorators for model and tool calls.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.hooks import (
+    before_model, after_model, wrap_model_call,
+    before_tool, after_tool, wrap_tool_call,
+    InvocationContext, ModelRequest, ModelResponse
+)
+
+# Simple tool for demonstration
+@tool
+def get_weather(city: str) -> str:
+    """Get weather for a city."""
+    return f"Sunny, 22°C in {city}"
+
+# Before model hook - adds context
+@before_model
+def add_context(request: ModelRequest) -> ModelRequest:
+    print(f"[before_model] Adding context to request")
+    return request
+
+# After model hook - logs response
+@after_model  
+def log_response(response: ModelResponse) -> ModelResponse:
+    print(f"[after_model] Response received")
+    return response
+
+# Wrap tool call - retry on error
+@wrap_tool_call
+def retry_on_error(tool_call, call_next):
+    print(f"[wrap_tool_call] Executing tool")
+    try:
+        return call_next(tool_call)
+    except Exception as e:
+        print(f"[wrap_tool_call] Retrying after error: {e}")
+        return call_next(tool_call)
+
+# Create agent with hooks
+agent = Agent(
+    name="WeatherBot",
+    instructions="You help with weather queries.",
+    tools=[get_weather],
+    hooks=[add_context, log_response, retry_on_error]
+)
+
+if __name__ == "__main__":
+    # Test the tool directly
+    result = get_weather("London")
+    print(f"Weather: {result}")
+    
+    print("\n✓ Middleware example complete")

examples/middleware/configurable_model.py

@@ -0,0 +1,31 @@
+"""
+Configurable Model Example - PraisonAI Agents
+
+Demonstrates runtime model switching without recreating the agent.
+"""
+
+from praisonaiagents import Agent
+
+# Create agent with configurable model enabled
+agent = Agent(
+    name="FlexBot",
+    instructions="You are a helpful assistant.",
+    llm="gpt-4o-mini",
+    llm_config={"configurable": True}
+)
+
+if __name__ == "__main__":
+    # Default model call
+    print("Using default model (gpt-4o-mini)...")
+    # response = agent.chat("Say hello in 5 words")
+    
+    # Override model per-call
+    print("\nOverriding to different model...")
+    # response = agent.chat("Say hello in 5 words", config={"model": "gpt-4o"})
+    
+    # Override temperature
+    print("\nOverriding temperature...")
+    # response = agent.chat("Say hello creatively", config={"temperature": 0.9})
+    
+    print("\n✓ Configurable model example complete")
+    print("Note: Uncomment agent.chat() calls to run with API key")

examples/middleware/injected_state.py

@@ -0,0 +1,50 @@
+"""
+Injected State Example - PraisonAI Agents
+
+Demonstrates injecting agent state into tools without exposing it in the schema.
+"""
+
+from praisonaiagents import Agent, tool
+from praisonaiagents.tools import Injected
+from praisonaiagents.tools.injected import AgentState, with_injection_context
+
+# Tool with injected state - state param is NOT in the public schema
+@tool
+def show_context(query: str, state: Injected[dict]) -> str:
+    """Show the current agent context."""
+    session_id = state.get('session_id', 'unknown')
+    agent_id = state.get('agent_id', 'unknown')
+    return f"Query: {query}, Session: {session_id}, Agent: {agent_id}"
+
+# Create agent with the tool
+agent = Agent(
+    name="ContextBot",
+    instructions="You help show context information.",
+    tools=[show_context],
+    session_id="my-session-123"
+)
+
+if __name__ == "__main__":
+    # Verify injected param is not in schema
+    schema = show_context.get_schema()
+    params = schema['function']['parameters']['properties']
+    print(f"Schema params: {list(params.keys())}")
+    assert 'state' not in params, "state should NOT be in schema"
+    print("✓ 'state' correctly excluded from schema")
+    
+    # Test with manual injection context
+    mock_state = AgentState(
+        agent_id="test-agent",
+        run_id="run-1",
+        session_id="session-abc"
+    )
+    
+    with with_injection_context(mock_state):
+        result = show_context(query="hello")
+        print(f"Result: {result}")
+    
+    # Test via agent.execute_tool
+    result = agent.execute_tool("show_context", {"query": "test"})
+    print(f"Agent result: {result}")
+    
+    print("\n✓ Injected state example complete")

examples/middleware/rate_limiter.py

@@ -0,0 +1,29 @@
+"""
+Rate Limiter Example - PraisonAI Agents
+
+Demonstrates token bucket rate limiting for LLM API calls.
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.llm import RateLimiter
+
+# Create rate limiter: 60 requests per minute
+limiter = RateLimiter(requests_per_minute=60, burst=5)
+
+# Create agent with rate limiter
+agent = Agent(
+    name="RateLimitedBot",
+    instructions="You are a helpful assistant.",
+    rate_limiter=limiter
+)
+
+if __name__ == "__main__":
+    print(f"Rate limiter: {limiter}")
+    print(f"Available tokens: {limiter.available_tokens}")
+    
+    # Demonstrate rate limiting
+    for i in range(3):
+        limiter.acquire()
+        print(f"Request {i+1} acquired, tokens left: {limiter.available_tokens:.1f}")
+    
+    print("\n✓ Rate limiter example complete")

examples/multi_agent/multi_agent_persistence.py

@@ -0,0 +1,122 @@
+"""
+Multi-Agent Persistence Example
+
+Demonstrates how multiple agents can share or isolate conversation
+history using the persistence layer.
+"""
+
+from praisonai.persistence.factory import create_conversation_store, create_state_store
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+import uuid
+
+
+def main():
+    # Create stores
+    conv_store = create_conversation_store("sqlite", path=":memory:")
+    state_store = create_state_store("memory")
+    
+    print("=== Multi-Agent Persistence Demo ===\n")
+    
+    # Scenario 1: Shared session (agents collaborate)
+    print("--- Scenario 1: Shared Session ---")
+    shared_session_id = f"shared-{uuid.uuid4().hex[:8]}"
+    
+    session = ConversationSession(
+        session_id=shared_session_id,
+        user_id="user-123",
+        name="Shared Conversation"
+    )
+    conv_store.create_session(session)
+    
+    # Agent 1 (Researcher) adds context
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant",
+        content="[Researcher] I found relevant information about the topic.",
+        metadata={"agent_id": "researcher", "agent_role": "research"}
+    ))
+    
+    # Agent 2 (Writer) uses the context
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant", 
+        content="[Writer] Based on the research, here's a summary...",
+        metadata={"agent_id": "writer", "agent_role": "writing"}
+    ))
+    
+    # Agent 3 (Editor) reviews
+    conv_store.add_message(shared_session_id, ConversationMessage(
+        role="assistant",
+        content="[Editor] I've reviewed and polished the content.",
+        metadata={"agent_id": "editor", "agent_role": "editing"}
+    ))
+    
+    messages = conv_store.get_messages(shared_session_id)
+    print(f"Shared session has {len(messages)} messages from different agents")
+    for msg in messages:
+        agent = msg.metadata.get("agent_id", "unknown") if msg.metadata else "unknown"
+        print(f"  - {agent}: {msg.content[:50]}...")
+    
+    # Scenario 2: Isolated sessions (agents work independently)
+    print("\n--- Scenario 2: Isolated Sessions ---")
+    
+    agent_sessions = {}
+    for agent_name in ["planner", "executor", "validator"]:
+        session_id = f"{agent_name}-{uuid.uuid4().hex[:8]}"
+        agent_sessions[agent_name] = session_id
+        
+        conv_store.create_session(ConversationSession(
+            session_id=session_id,
+            agent_id=agent_name,
+            name=f"{agent_name.title()} Session"
+        ))
+        
+        # Each agent has its own conversation
+        conv_store.add_message(session_id, ConversationMessage(
+            role="user",
+            content=f"Task for {agent_name}"
+        ))
+        conv_store.add_message(session_id, ConversationMessage(
+            role="assistant",
+            content=f"[{agent_name.title()}] Processing task..."
+        ))
+    
+    print("Created isolated sessions for each agent:")
+    for agent, sid in agent_sessions.items():
+        msgs = conv_store.get_messages(sid)
+        print(f"  - {agent}: {len(msgs)} messages")
+    
+    # Scenario 3: Shared state across agents
+    print("\n--- Scenario 3: Shared State ---")
+    
+    # Agents share state for coordination
+    state_store.set("workflow:status", {"phase": "research", "progress": 0})
+    state_store.set("workflow:context", {"topic": "AI Agents", "deadline": "2024-12-31"})
+    
+    # Agent 1 updates progress
+    state = state_store.get("workflow:status")
+    state["progress"] = 33
+    state["phase"] = "writing"
+    state_store.set("workflow:status", state)
+    print(f"Agent 1 updated state: {state}")
+    
+    # Agent 2 reads and updates
+    state = state_store.get("workflow:status")
+    state["progress"] = 66
+    state["phase"] = "editing"
+    state_store.set("workflow:status", state)
+    print(f"Agent 2 updated state: {state}")
+    
+    # Agent 3 completes
+    state = state_store.get("workflow:status")
+    state["progress"] = 100
+    state["phase"] = "complete"
+    state_store.set("workflow:status", state)
+    print(f"Agent 3 completed: {state}")
+    
+    # Cleanup
+    conv_store.close()
+    state_store.close()
+    print("\n✅ Multi-agent persistence demo complete!")
+
+
+if __name__ == "__main__":
+    main()

examples/multi_agent/shared_db_session.py

@@ -0,0 +1,40 @@
+"""Multi-Agent Shared Session - DB Persistence Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_conversation_store
+from praisonai.persistence.conversation.base import ConversationSession, ConversationMessage
+
+# Create shared session for multiple agents
+store = create_conversation_store("sqlite", path="/tmp/multi_agent.db")
+session_id = "shared-session-123"
+
+# Create session
+session = ConversationSession(session_id=session_id, agent_id="multi")
+try:
+    store.create_session(session)
+except Exception:
+    pass
+
+# Agent 1 writes
+msg1 = ConversationMessage(session_id=session_id, role="user", content="Agent1: Hello")
+store.add_message(session_id, msg1)
+msg2 = ConversationMessage(session_id=session_id, role="assistant", content="Agent1: Hi there!")
+store.add_message(session_id, msg2)
+
+# Agent 2 writes to same session
+msg3 = ConversationMessage(session_id=session_id, role="user", content="Agent2: What did Agent1 say?")
+store.add_message(session_id, msg3)
+msg4 = ConversationMessage(session_id=session_id, role="assistant", content="Agent2: Agent1 said Hello")
+store.add_message(session_id, msg4)
+
+# Verify both agents' messages are in session
+messages = store.get_messages(session_id)
+print(f"Total messages in shared session: {len(messages)}")
+assert len(messages) >= 4, "Should have messages from both agents"
+
+# Verify content
+contents = [m.content for m in messages]
+assert any("Agent1" in c for c in contents), "Should have Agent1 messages"
+assert any("Agent2" in c for c in contents), "Should have Agent2 messages"
+
+print("PASSED: Multi-agent shared session persistence")

examples/multi_agent/shared_session_wow.py

@@ -0,0 +1,16 @@
+"""Multi-Agent Shared Session Demo"""
+from praisonaiagents import Agent
+from praisonai.persistence import create_conversation_store
+
+store = create_conversation_store("sqlite", path="/tmp/multi_agent.db")
+
+agent1 = Agent(name="Researcher", llm="gpt-4o-mini", db=store, session_id="shared-session")
+agent2 = Agent(name="Writer", llm="gpt-4o-mini", db=store, session_id="shared-session")
+
+r1 = agent1.chat("Research topic: AI in healthcare. Key finding: reduces diagnosis time by 50%")
+print(f"Researcher: {r1[:50]}...")
+
+r2 = agent2.chat("Based on the research, what was the key finding?")
+print(f"Writer: {r2[:50]}...")
+assert "50" in r2 or "diagnosis" in r2.lower(), "Writer should see Researcher's context"
+print("PASSED: Multi-agent shared session works")

examples/observability/basic_usage.py

@@ -0,0 +1,48 @@
+"""
+Basic Observability Usage Example
+
+This example demonstrates how to use the observability module
+with PraisonAI agents.
+
+Usage:
+    # Set your provider's API key first
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    
+    python basic_usage.py
+"""
+
+from praisonai_tools.observability import obs
+from praisonaiagents import Agent
+
+# Initialize observability (auto-detects provider from env vars)
+obs.init()
+
+# Or specify a provider explicitly
+# obs.init(provider="langfuse", project_name="my-project")
+
+# Create an agent
+agent = Agent(
+    instructions="You are a helpful assistant.",
+    model="gpt-4o-mini",
+)
+
+# Use trace context manager for complete workflow tracing
+with obs.trace("chat-session", session_id="user-123"):
+    # Use span context manager for individual operations
+    with obs.span("user-query", kind=obs.SpanKind.AGENT):
+        response = agent.chat("What is the capital of France?")
+        print(response)
+
+# Log LLM calls manually if needed
+obs.log_llm_call(
+    model="gpt-4o-mini",
+    input_messages="What is 2+2?",
+    output="4",
+    input_tokens=10,
+    output_tokens=1,
+)
+
+# Check diagnostics
+print("\nDiagnostics:")
+print(obs.doctor())

examples/observability/langfuse_example.py

@@ -0,0 +1,48 @@
+"""
+Langfuse Integration Example
+
+This example shows how to use Langfuse for LLM observability.
+
+Setup:
+    1. Sign up at https://langfuse.com/
+    2. Get your API keys from the project settings
+    3. Set environment variables:
+       export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+       export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    4. Install dependencies:
+       pip install opentelemetry-sdk opentelemetry-exporter-otlp
+
+Usage:
+    python langfuse_example.py
+"""
+
+import os
+from praisonai_tools.observability import obs
+from praisonaiagents import Agent
+
+# Initialize Langfuse
+success = obs.init(
+    provider="langfuse",
+    project_name="praisonai-demo",
+)
+
+if not success:
+    print("Failed to initialize Langfuse. Check your API keys.")
+    print("Required: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY")
+    exit(1)
+
+print("Langfuse initialized successfully!")
+print(f"View traces at: https://cloud.langfuse.com/")
+
+# Create agent
+agent = Agent(
+    instructions="You are a helpful coding assistant.",
+    model="gpt-4o-mini",
+)
+
+# Run with tracing
+with obs.trace("coding-session", user_id="developer-1"):
+    response = agent.chat("Write a Python function to calculate fibonacci numbers")
+    print(response)
+
+print("\nCheck Langfuse dashboard for traces!")

examples/observability/mlflow_local_wow.py

@@ -0,0 +1,22 @@
+"""MLflow Local Observability Demo (no API key needed)"""
+import mlflow
+import time
+
+mlflow.set_tracking_uri("file:///tmp/mlflow_demo")
+mlflow.set_experiment("praisonai-demo")
+
+with mlflow.start_run(run_name="agent-trace"):
+    mlflow.log_param("agent_name", "Assistant")
+    mlflow.log_param("model", "gpt-4o-mini")
+    
+    # Simulate agent work
+    start = time.time()
+    time.sleep(0.1)
+    latency = time.time() - start
+    
+    mlflow.log_metric("latency_ms", latency * 1000)
+    mlflow.log_metric("tokens_used", 150)
+    
+    print(f"Logged run to MLflow: latency={latency*1000:.1f}ms")
+
+print("PASSED: MLflow local observability works")

examples/observability/multi_agent_tracing.py

@@ -0,0 +1,53 @@
+"""
+Multi-Agent Tracing Example
+
+This example shows how to trace multi-agent workflows with
+parent/child span relationships.
+
+Usage:
+    # Set your provider's API key
+    export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+    export LANGFUSE_SECRET_KEY=sk-lf-xxx
+    
+    python multi_agent_tracing.py
+"""
+
+from praisonai_tools.observability import obs
+from praisonai_tools.observability.base import SpanKind
+from praisonaiagents import Agent, PraisonAIAgents
+
+# Initialize observability
+obs.init()
+
+# Create agents
+researcher = Agent(
+    name="Researcher",
+    instructions="You research topics and provide detailed information.",
+    model="gpt-4o-mini",
+)
+
+writer = Agent(
+    name="Writer", 
+    instructions="You write clear, engaging content based on research.",
+    model="gpt-4o-mini",
+)
+
+# Trace the multi-agent workflow
+with obs.trace("content-creation", metadata={"workflow": "research-write"}):
+    
+    # Research phase
+    with obs.span("research-phase", kind=SpanKind.AGENT) as research_span:
+        research_span.attributes["agent"] = "Researcher"
+        research_result = researcher.chat("Research the benefits of AI in healthcare")
+    
+    # Writing phase  
+    with obs.span("writing-phase", kind=SpanKind.AGENT) as write_span:
+        write_span.attributes["agent"] = "Writer"
+        write_span.attributes["input_length"] = len(str(research_result))
+        final_content = writer.chat(f"Write a blog post based on: {research_result}")
+
+print("Final Content:")
+print(final_content)
+
+# Check trace info
+print("\nDiagnostics:", obs.doctor())

examples/persistence/simple_db_agent.py

@@ -26,23 +26,18 @@ Expected Output:
     Messages persisted: 2
 """
 
-from praisonaiagents import Agent
-from praisonai.db import PostgresDB
+from praisonaiagents import Agent, db
 
-# Create database adapter
-db = PostgresDB(
-    host="localhost",
-    port=5432,
-    database="praisonai",
-    user="postgres",
-    password="praison123"
+# Create database adapter (simplified import)
+db_instance = db(
+    database_url="postgresql://postgres:praison123@localhost:5432/praisonai"
 )
 
 # Create agent with persistence enabled
 agent = Agent(
     name="Assistant",
     instructions="You are a helpful assistant. Keep responses brief.",
-    db=db,
+    db=db_instance,
     session_id="demo-session-001",  # Same session_id = resume conversation
     verbose=False
 )
@@ -57,7 +52,7 @@ print(f"Session ID: {agent.session_id}")
 print(f"Messages in history: {len(agent.chat_history)}")
 
 # Close DB connection
-db.close()
+db_instance.close()
 
 print("\n=== Session persisted! ===")
 print("Run again with same session_id to resume.")

examples/run_all_examples.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Run all examples and collect PASS/SKIP/FAIL results."""
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+EXAMPLES_DIR = Path(__file__).parent
+RESULTS = []
+
+def run_example(path: Path) -> tuple:
+    """Run an example and return (name, status, reason)."""
+    name = f"{path.parent.name}/{path.name}"
+    try:
+        result = subprocess.run(
+            [sys.executable, str(path)],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            env={**os.environ, "PYTHONPATH": str(EXAMPLES_DIR.parent / "src")}
+        )
+        output = result.stdout + result.stderr
+        if "PASSED" in output:
+            return (name, "PASS", "")
+        elif "SKIPPED" in output:
+            return (name, "SKIP", output.split("SKIPPED:")[-1].strip()[:50])
+        elif result.returncode != 0:
+            error = output.strip().split("\n")[-1][:80]
+            return (name, "FAIL", error)
+        else:
+            return (name, "PASS", "")
+    except subprocess.TimeoutExpired:
+        return (name, "FAIL", "Timeout")
+    except Exception as e:
+        return (name, "FAIL", str(e)[:50])
+
+def main():
+    print("=" * 70)
+    print("EXAMPLE RUNNER - PASS/SKIP/FAIL SUMMARY")
+    print("=" * 70)
+    
+    # Find all example files
+    examples = []
+    for subdir in ["db", "vector", "observability", "multi_agent", "workflows"]:
+        subpath = EXAMPLES_DIR / subdir
+        if subpath.exists():
+            examples.extend(sorted(subpath.glob("*_wow.py")))
+    
+    print(f"\nFound {len(examples)} examples to run\n")
+    
+    for ex in examples:
+        name, status, reason = run_example(ex)
+        RESULTS.append((name, status, reason))
+        icon = {"PASS": "✅", "SKIP": "⏭️", "FAIL": "❌"}.get(status, "?")
+        reason_str = f" ({reason})" if reason else ""
+        print(f"{icon} {status:4} | {name:45} {reason_str}")
+    
+    # Summary
+    print("\n" + "=" * 70)
+    passed = sum(1 for _, s, _ in RESULTS if s == "PASS")
+    skipped = sum(1 for _, s, _ in RESULTS if s == "SKIP")
+    failed = sum(1 for _, s, _ in RESULTS if s == "FAIL")
+    print(f"SUMMARY: {passed} PASS | {skipped} SKIP | {failed} FAIL | {len(RESULTS)} TOTAL")
+    print("=" * 70)
+    
+    return 0 if failed == 0 else 1
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/vector/chroma_wow.py

@@ -0,0 +1,21 @@
+"""ChromaDB Vector Store - Basic Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+store = create_knowledge_store("chroma", path="/tmp/chroma_demo")
+try:
+    store.delete_collection("demo")
+except Exception:
+    pass
+store.create_collection("demo", dimension=1536)
+docs = [
+    KnowledgeDocument(id="1", content="Python is a programming language", embedding=[0.1]*1536),
+    KnowledgeDocument(id="2", content="JavaScript runs in browsers", embedding=[0.2]*1536)
+]
+store.insert("demo", docs)
+results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+print(f"Found: {len(results)} results")
+assert len(results) >= 1
+print("PASSED: ChromaDB vector store")

examples/vector/lancedb_real_wow.py

@@ -0,0 +1,31 @@
+"""LanceDB Vector Store - Local Test"""
+import sys
+import os
+import shutil
+
+try:
+    import lancedb
+except ImportError:
+    print("SKIPPED: LanceDB - lancedb not installed")
+    sys.exit(0)
+
+# Clean up previous test
+db_path = "/tmp/lancedb_test"
+if os.path.exists(db_path):
+    shutil.rmtree(db_path)
+
+db = lancedb.connect(db_path)
+
+# Create table with vectors
+data = [
+    {"id": "1", "text": "Machine learning is AI", "vector": [0.1] * 128},
+    {"id": "2", "text": "Deep learning uses neural nets", "vector": [0.2] * 128},
+]
+table = db.create_table("demo", data)
+
+# Search
+results = table.search([0.1] * 128).limit(1).to_list()
+print(f"Found: {len(results)} results")
+print(f"Top result: {results[0]['text'][:30]}...")
+assert len(results) >= 1
+print("PASSED: LanceDB vector store")

examples/vector/lancedb_wow.py

@@ -0,0 +1,20 @@
+"""LanceDB Vector Store - Basic Test"""
+import sys
+sys.path.insert(0, 'src/praisonai')
+try:
+    from praisonai.persistence import create_knowledge_store
+    from praisonai.persistence.knowledge.base import KnowledgeDocument
+    
+    store = create_knowledge_store("lancedb", path="/tmp/lancedb_demo")
+    store.create_collection("demo", dimension=1536)
+    docs = [
+        KnowledgeDocument(id="doc1", content="The Eiffel Tower is in Paris", embedding=[0.1]*1536),
+        KnowledgeDocument(id="doc2", content="The Statue of Liberty is in New York", embedding=[0.2]*1536)
+    ]
+    store.insert("demo", docs)
+    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+    print(f"Found: {len(results)} results")
+    assert len(results) >= 1
+    print("PASSED: LanceDB vector store")
+except ImportError as e:
+    print(f"SKIPPED: LanceDB - {e}")

examples/vector/pgvector_real_wow.py

@@ -0,0 +1,59 @@
+"""PGVector Vector Store - Docker Test"""
+import sys
+import os
+
+# Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
+
+try:
+    import psycopg2
+except ImportError:
+    print("SKIPPED: PGVector - psycopg2 not installed")
+    sys.exit(0)
+
+try:
+    conn = psycopg2.connect(url)
+    cur = conn.cursor()
+    
+    # Ensure extension
+    cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+    conn.commit()
+    
+    # Create test table
+    cur.execute("DROP TABLE IF EXISTS test_vectors")
+    cur.execute("""
+        CREATE TABLE test_vectors (
+            id SERIAL PRIMARY KEY,
+            content TEXT,
+            embedding vector(128)
+        )
+    """)
+    conn.commit()
+    
+    # Insert vectors
+    cur.execute("""
+        INSERT INTO test_vectors (content, embedding) VALUES
+        ('Machine learning is AI', %s),
+        ('Deep learning uses neural nets', %s)
+    """, ([0.1] * 128, [0.2] * 128))
+    conn.commit()
+    
+    # Search (cosine similarity)
+    cur.execute("""
+        SELECT content, embedding <=> %s::vector AS distance
+        FROM test_vectors
+        ORDER BY distance
+        LIMIT 1
+    """, ([0.1] * 128,))
+    
+    row = cur.fetchone()
+    print(f"Top result: {row[0][:30]}... (distance: {row[1]:.4f})")
+    
+    # Cleanup
+    cur.execute("DROP TABLE test_vectors")
+    conn.commit()
+    conn.close()
+    
+    print("PASSED: PGVector vector store")
+except Exception as e:
+    print(f"SKIPPED: PGVector - {e}")

examples/vector/pgvector_wow.py

@@ -0,0 +1,23 @@
+"""PGVector Knowledge Store - Basic Test (requires Docker)"""
+import sys
+import os
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+# Docker: docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5433:5432 pgvector/pgvector:pg16
+url = os.getenv("PGVECTOR_URL", "postgresql://postgres:postgres@localhost:5433/postgres")
+try:
+    store = create_knowledge_store("pgvector", url=url)
+    store.create_collection("demo", dimension=1536)
+    docs = [
+        KnowledgeDocument(id="1", content="Kubernetes orchestrates containers", embedding=[0.1]*1536),
+        KnowledgeDocument(id="2", content="Docker packages applications", embedding=[0.2]*1536)
+    ]
+    store.insert("demo", docs)
+    results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+    print(f"Found: {len(results)} results")
+    assert len(results) >= 1
+    print("PASSED: PGVector vector store")
+except Exception as e:
+    print(f"SKIPPED: PGVector - {e}")

examples/vector/pinecone_wow.py

@@ -0,0 +1,27 @@
+"""Pinecone Vector Store - Real API Test"""
+import os
+import sys
+sys.path.insert(0, 'src/praisonai')
+
+# Requires: export PINECONE_API_KEY=...
+api_key = os.getenv("PINECONE_API_KEY")
+if not api_key:
+    print("SKIPPED: Pinecone - PINECONE_API_KEY not set")
+    sys.exit(0)
+
+from pinecone import Pinecone
+
+pc = Pinecone(api_key=api_key)
+indexes = pc.list_indexes()
+print(f"Pinecone connected! Found {len(list(indexes))} indexes")
+
+# Use existing 'test' index or create one
+index_name = "test"
+if index_name not in [idx.name for idx in pc.list_indexes()]:
+    print(f"SKIPPED: Pinecone - index '{index_name}' not found")
+    sys.exit(0)
+
+index = pc.Index(index_name)
+stats = index.describe_index_stats()
+print(f"Index '{index_name}' has {stats.total_vector_count} vectors")
+print("PASSED: Pinecone vector store")

examples/vector/qdrant_wow.py

@@ -0,0 +1,23 @@
+"""Qdrant Vector Store - Basic Test (requires Docker)"""
+import sys, os
+sys.path.insert(0, 'src/praisonai')
+from praisonai.persistence import create_knowledge_store
+from praisonai.persistence.knowledge.base import KnowledgeDocument
+
+# Docker: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
+url = os.getenv("QDRANT_URL", "http://localhost:6333")
+store = create_knowledge_store("qdrant", url=url)
+try:
+    store.delete_collection("demo")
+except Exception:
+    pass
+store.create_collection("demo", dimension=1536)
+docs = [
+    KnowledgeDocument(id="1", content="Machine learning is AI", embedding=[0.1]*1536),
+    KnowledgeDocument(id="2", content="Deep learning uses neural nets", embedding=[0.2]*1536)
+]
+store.insert("demo", docs)
+results = store.search("demo", query_embedding=[0.1]*1536, limit=1)
+print(f"Found: {len(results)} results")
+assert len(results) >= 1
+print("PASSED: Qdrant vector store")

examples/vector/weaviate_wow.py

@@ -0,0 +1,24 @@
+"""Weaviate Cloud Vector Store - Real API Test"""
+import os
+import sys
+
+# Requires: export WEAVIATE_URL=... and WEAVIATE_API_KEY=...
+weaviate_url = os.getenv("WEAVIATE_URL", "https://thhoyczshsawyt16ot3uw.c0.europe-west3.gcp.weaviate.cloud")
+weaviate_key = os.getenv("WEAVIATE_API_KEY")
+if not weaviate_key:
+    print("SKIPPED: Weaviate - WEAVIATE_API_KEY not set")
+    sys.exit(0)
+
+import weaviate
+from weaviate.classes.init import Auth
+
+client = weaviate.connect_to_weaviate_cloud(
+    cluster_url=weaviate_url,
+    auth_credentials=Auth.api_key(weaviate_key)
+)
+
+print(f"Weaviate connected: {client.is_ready()}")
+collections = client.collections.list_all()
+print(f"Found {len(collections)} collections")
+client.close()
+print("PASSED: Weaviate cloud vector store")

src/praisonai-agents/praisonaiagents/__init__.py

@@ -55,6 +55,7 @@ except ImportError:
 from .session import Session
 from .memory.memory import Memory
 from .db import db
+from .obs import obs
 # Workflows - import from dedicated workflows module
 from .workflows import (
     Workflow, WorkflowStep, WorkflowContext, StepResult,
@@ -259,6 +260,7 @@ __all__ = [
     'Session',
     'Memory',
     'db',
+    'obs',
     'display_interaction',
     'display_self_reflection',
     'display_instruction',

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

@@ -254,7 +254,10 @@ class Agent:
         skills: Optional[List[str]] = None,
         skills_dirs: Optional[List[str]] = None,
         db: Optional[Any] = None,
-        session_id: Optional[str] = None
+        session_id: Optional[str] = None,
+        hooks: Optional[List[Any]] = None,
+        llm_config: Optional[Dict[str, Any]] = None,
+        rate_limiter: Optional[Any] = None
     ):
         """Initialize an Agent instance.
 
@@ -395,6 +398,17 @@ class Agent:
         # Flag to track if final result has been displayed to prevent duplicates
         self._final_display_shown = False
         
+        # Store hooks for middleware system (zero overhead when empty)
+        self._hooks = hooks or []
+        self._middleware_manager = None  # Lazy init
+        
+        # Store llm_config for configurable model switching
+        self._llm_config = llm_config or {}
+        self._llm_configurable = self._llm_config.get('configurable', False)
+        
+        # Store rate limiter (optional, zero overhead when None)
+        self._rate_limiter = rate_limiter
+        
         # Store OpenAI client parameters for lazy initialization
         self._openai_api_key = api_key
         self._openai_base_url = base_url
@@ -1622,8 +1636,32 @@ Your Goal: {self.goal}"""
     def execute_tool(self, function_name, arguments):
         """
         Execute a tool dynamically based on the function name and arguments.
+        Injects agent state for tools with Injected[T] parameters.
         """
         logging.debug(f"{self.name} executing tool {function_name} with arguments: {arguments}")
+        
+        # Set up injection context for tools with Injected parameters
+        from ..tools.injected import AgentState, with_injection_context
+        state = AgentState(
+            agent_id=self.name,
+            run_id=getattr(self, '_current_run_id', 'unknown'),
+            session_id=getattr(self, '_session_id', None) or 'default',
+            last_user_message=self.chat_history[-1].get('content') if self.chat_history else None,
+            metadata={'agent_name': self.name}
+        )
+        
+        # Execute within injection context
+        return self._execute_tool_with_context(function_name, arguments, state)
+    
+    def _execute_tool_with_context(self, function_name, arguments, state):
+        """Execute tool within injection context."""
+        from ..tools.injected import with_injection_context
+        
+        with with_injection_context(state):
+            return self._execute_tool_impl(function_name, arguments)
+    
+    def _execute_tool_impl(self, function_name, arguments):
+        """Internal tool execution implementation."""
 
         # Check if approval is required for this tool
         from ..approval import is_approval_required, console_approval_callback, get_risk_level, mark_approved, ApprovalDecision, get_approval_callback
@@ -2058,7 +2096,11 @@ Your Goal: {self.goal}"""
         """Get the current session ID."""
         return self._session_id
 
-    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None):
+    def chat(self, prompt, temperature=1.0, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False, stream=None, task_name=None, task_description=None, task_id=None, config=None):
+        # Apply rate limiter if configured (before any LLM call)
+        if self._rate_limiter is not None:
+            self._rate_limiter.acquire()
+        
         # Initialize DB session on first chat (lazy)
         self._init_db_session()
         

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

@@ -65,6 +65,23 @@ __all__ = [
     "AfterAgentInput",
     "SessionStartInput",
     "SessionEndInput",
+    # Middleware types
+    "InvocationContext",
+    "ModelRequest",
+    "ModelResponse",
+    "ToolRequest",
+    "ToolResponse",
+    # Middleware decorators
+    "before_model",
+    "after_model",
+    "wrap_model_call",
+    "before_tool",
+    "after_tool",
+    "wrap_tool_call",
+    # Middleware utilities
+    "MiddlewareChain",
+    "AsyncMiddlewareChain",
+    "MiddlewareManager",
 ]
 
 
@@ -94,4 +111,27 @@ def __getattr__(name: str):
         )
         return locals()[name]
     
+    # Middleware types
+    if name in ("InvocationContext", "ModelRequest", "ModelResponse", 
+                "ToolRequest", "ToolResponse"):
+        from .middleware import (
+            InvocationContext, ModelRequest, ModelResponse,
+            ToolRequest, ToolResponse
+        )
+        return locals()[name]
+    
+    # Middleware decorators
+    if name in ("before_model", "after_model", "wrap_model_call",
+                "before_tool", "after_tool", "wrap_tool_call"):
+        from .middleware import (
+            before_model, after_model, wrap_model_call,
+            before_tool, after_tool, wrap_tool_call
+        )
+        return locals()[name]
+    
+    # Middleware utilities
+    if name in ("MiddlewareChain", "AsyncMiddlewareChain", "MiddlewareManager"):
+        from .middleware import MiddlewareChain, AsyncMiddlewareChain, MiddlewareManager
+        return locals()[name]
+    
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

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

@@ -0,0 +1,439 @@
+"""
+Middleware System for PraisonAI Agents.
+
+Provides wrap_model_call and wrap_tool_call patterns for intercepting
+and modifying agent behavior at model/tool call boundaries.
+
+Zero Performance Impact:
+- All middleware is optional
+- Empty middleware chain is O(1) fast path
+- No overhead when middleware not registered
+
+Usage:
+    from praisonaiagents.hooks import before_model, wrap_model_call, wrap_tool_call
+    
+    @before_model
+    def add_context(request):
+        request.messages.append({"role": "system", "content": "Extra"})
+        return request
+    
+    @wrap_model_call
+    def retry_on_error(request, call_next):
+        for _ in range(3):
+            try:
+                return call_next(request)
+            except Exception:
+                pass
+        raise RuntimeError("All retries failed")
+    
+    agent = Agent(name="Test", hooks=[add_context, retry_on_error])
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Generic
+from functools import wraps
+
+
+@dataclass
+class InvocationContext:
+    """Context passed through middleware chain.
+    
+    Contains identifiers for multi-agent safety and optional metadata.
+    """
+    agent_id: str
+    run_id: str
+    session_id: str
+    tool_name: Optional[str] = None
+    model_name: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ModelRequest:
+    """Request data for model calls."""
+    messages: List[Dict[str, Any]]
+    model: str
+    temperature: float = 1.0
+    context: Optional[InvocationContext] = None
+    tools: Optional[List[Any]] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ModelResponse:
+    """Response data from model calls."""
+    content: str
+    model: str
+    usage: Optional[Dict[str, int]] = None
+    context: Optional[InvocationContext] = None
+    tool_calls: Optional[List[Any]] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolRequest:
+    """Request data for tool calls."""
+    tool_name: str
+    arguments: Dict[str, Any]
+    context: Optional[InvocationContext] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolResponse:
+    """Response data from tool calls."""
+    tool_name: str
+    result: Any
+    error: Optional[str] = None
+    context: Optional[InvocationContext] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+# Type aliases for middleware functions
+T = TypeVar('T')
+BeforeModelFn = Callable[[ModelRequest], ModelRequest]
+AfterModelFn = Callable[[ModelResponse], ModelResponse]
+WrapModelCallFn = Callable[[ModelRequest, Callable[[ModelRequest], ModelResponse]], ModelResponse]
+BeforeToolFn = Callable[[ToolRequest], ToolRequest]
+AfterToolFn = Callable[[ToolResponse], ToolResponse]
+WrapToolCallFn = Callable[[ToolRequest, Callable[[ToolRequest], ToolResponse]], ToolResponse]
+
+
+class MiddlewareChain:
+    """Synchronous middleware chain executor.
+    
+    Composes middleware functions in registration order.
+    First registered middleware wraps all subsequent ones.
+    """
+    
+    def __init__(self, middlewares: Optional[List[Callable]] = None):
+        self._middlewares = middlewares or []
+    
+    def execute(self, request: Any, final_handler: Callable[[Any], Any]) -> Any:
+        """Execute the middleware chain with a final handler.
+        
+        Args:
+            request: The request object to pass through
+            final_handler: The actual operation to perform
+            
+        Returns:
+            The result from the chain
+        """
+        if not self._middlewares:
+            return final_handler(request)
+        
+        # Build the chain from inside out
+        # Last middleware wraps final_handler
+        # First middleware is outermost
+        def build_chain(index: int) -> Callable[[Any], Any]:
+            if index >= len(self._middlewares):
+                return final_handler
+            
+            middleware = self._middlewares[index]
+            next_handler = build_chain(index + 1)
+            
+            def handler(req: Any) -> Any:
+                return middleware(req, next_handler)
+            
+            return handler
+        
+        chain = build_chain(0)
+        return chain(request)
+    
+    def __len__(self) -> int:
+        return len(self._middlewares)
+
+
+class AsyncMiddlewareChain:
+    """Asynchronous middleware chain executor.
+    
+    Same as MiddlewareChain but for async middleware and handlers.
+    """
+    
+    def __init__(self, middlewares: Optional[List[Callable]] = None):
+        self._middlewares = middlewares or []
+    
+    async def execute(self, request: Any, final_handler: Callable) -> Any:
+        """Execute the async middleware chain.
+        
+        Args:
+            request: The request object to pass through
+            final_handler: The actual async operation to perform
+            
+        Returns:
+            The result from the chain
+        """
+        if not self._middlewares:
+            return await final_handler(request)
+        
+        # Build the chain from inside out
+        def build_chain(index: int) -> Callable:
+            if index >= len(self._middlewares):
+                return final_handler
+            
+            middleware = self._middlewares[index]
+            next_handler = build_chain(index + 1)
+            
+            async def handler(req: Any) -> Any:
+                return await middleware(req, next_handler)
+            
+            return handler
+        
+        chain = build_chain(0)
+        return await chain(request)
+    
+    def __len__(self) -> int:
+        return len(self._middlewares)
+
+
+# Decorator functions for tagging middleware
+
+def before_model(func: BeforeModelFn) -> BeforeModelFn:
+    """Decorator to mark a function as a before_model hook.
+    
+    The function receives a ModelRequest and should return a (possibly modified) ModelRequest.
+    
+    Example:
+        @before_model
+        def add_context(request):
+            request.messages.append({"role": "system", "content": "Extra"})
+            return request
+    """
+    func._hook_type = 'before_model'
+    return func
+
+
+def after_model(func: AfterModelFn) -> AfterModelFn:
+    """Decorator to mark a function as an after_model hook.
+    
+    The function receives a ModelResponse and should return a (possibly modified) ModelResponse.
+    
+    Example:
+        @after_model
+        def log_response(response):
+            print(f"Model returned: {response.content[:50]}")
+            return response
+    """
+    func._hook_type = 'after_model'
+    return func
+
+
+def wrap_model_call(func: WrapModelCallFn) -> WrapModelCallFn:
+    """Decorator to mark a function as a wrap_model_call middleware.
+    
+    The function receives (request, call_next) and should call call_next(request)
+    to continue the chain, or return early to short-circuit.
+    
+    Example:
+        @wrap_model_call
+        def retry_on_error(request, call_next):
+            for _ in range(3):
+                try:
+                    return call_next(request)
+                except Exception:
+                    pass
+            raise RuntimeError("All retries failed")
+    """
+    func._hook_type = 'wrap_model_call'
+    return func
+
+
+def before_tool(func: BeforeToolFn) -> BeforeToolFn:
+    """Decorator to mark a function as a before_tool hook.
+    
+    The function receives a ToolRequest and should return a (possibly modified) ToolRequest.
+    
+    Example:
+        @before_tool
+        def validate_args(request):
+            if 'dangerous' in request.arguments:
+                raise ValueError("Dangerous argument detected")
+            return request
+    """
+    func._hook_type = 'before_tool'
+    return func
+
+
+def after_tool(func: AfterToolFn) -> AfterToolFn:
+    """Decorator to mark a function as an after_tool hook.
+    
+    The function receives a ToolResponse and should return a (possibly modified) ToolResponse.
+    
+    Example:
+        @after_tool
+        def log_result(response):
+            print(f"Tool {response.tool_name} returned: {response.result}")
+            return response
+    """
+    func._hook_type = 'after_tool'
+    return func
+
+
+def wrap_tool_call(func: WrapToolCallFn) -> WrapToolCallFn:
+    """Decorator to mark a function as a wrap_tool_call middleware.
+    
+    The function receives (request, call_next) and should call call_next(request)
+    to continue the chain, or return early to short-circuit.
+    
+    Example:
+        @wrap_tool_call
+        def retry_flaky_tool(request, call_next):
+            last_error = None
+            for _ in range(3):
+                try:
+                    return call_next(request)
+                except Exception as e:
+                    last_error = e
+            raise last_error
+    """
+    func._hook_type = 'wrap_tool_call'
+    return func
+
+
+def get_hook_type(func: Callable) -> Optional[str]:
+    """Get the hook type of a decorated function."""
+    return getattr(func, '_hook_type', None)
+
+
+def is_middleware(func: Callable) -> bool:
+    """Check if a function is a middleware (wrap_* type)."""
+    hook_type = get_hook_type(func)
+    return hook_type in ('wrap_model_call', 'wrap_tool_call')
+
+
+def categorize_hooks(hooks: List[Callable]) -> Dict[str, List[Callable]]:
+    """Categorize hooks by their type.
+    
+    Returns:
+        Dict with keys: before_model, after_model, wrap_model_call,
+                       before_tool, after_tool, wrap_tool_call
+    """
+    categories = {
+        'before_model': [],
+        'after_model': [],
+        'wrap_model_call': [],
+        'before_tool': [],
+        'after_tool': [],
+        'wrap_tool_call': [],
+    }
+    
+    for hook in hooks or []:
+        hook_type = get_hook_type(hook)
+        if hook_type and hook_type in categories:
+            categories[hook_type].append(hook)
+    
+    return categories
+
+
+class MiddlewareManager:
+    """Manages middleware for an agent.
+    
+    Provides methods to execute before/after hooks and middleware chains
+    for both model and tool calls.
+    """
+    
+    def __init__(self, hooks: Optional[List[Callable]] = None):
+        self._hooks = hooks or []
+        self._categorized = categorize_hooks(self._hooks)
+        
+        # Pre-build chains for efficiency
+        self._model_chain = MiddlewareChain(self._categorized['wrap_model_call'])
+        self._tool_chain = MiddlewareChain(self._categorized['wrap_tool_call'])
+    
+    @property
+    def has_model_hooks(self) -> bool:
+        """Check if any model hooks are registered."""
+        return bool(
+            self._categorized['before_model'] or
+            self._categorized['after_model'] or
+            self._categorized['wrap_model_call']
+        )
+    
+    @property
+    def has_tool_hooks(self) -> bool:
+        """Check if any tool hooks are registered."""
+        return bool(
+            self._categorized['before_tool'] or
+            self._categorized['after_tool'] or
+            self._categorized['wrap_tool_call']
+        )
+    
+    def run_before_model(self, request: ModelRequest) -> ModelRequest:
+        """Run all before_model hooks."""
+        for hook in self._categorized['before_model']:
+            request = hook(request)
+        return request
+    
+    def run_after_model(self, response: ModelResponse) -> ModelResponse:
+        """Run all after_model hooks (in reverse order)."""
+        for hook in reversed(self._categorized['after_model']):
+            response = hook(response)
+        return response
+    
+    def run_before_tool(self, request: ToolRequest) -> ToolRequest:
+        """Run all before_tool hooks."""
+        for hook in self._categorized['before_tool']:
+            request = hook(request)
+        return request
+    
+    def run_after_tool(self, response: ToolResponse) -> ToolResponse:
+        """Run all after_tool hooks (in reverse order)."""
+        for hook in reversed(self._categorized['after_tool']):
+            response = hook(response)
+        return response
+    
+    def execute_model_call(
+        self,
+        request: ModelRequest,
+        model_fn: Callable[[ModelRequest], ModelResponse]
+    ) -> ModelResponse:
+        """Execute a model call with all hooks and middleware.
+        
+        Order:
+        1. before_model hooks (in order)
+        2. wrap_model_call middleware chain
+        3. actual model call
+        4. after_model hooks (in reverse order)
+        """
+        # Fast path: no hooks
+        if not self.has_model_hooks:
+            return model_fn(request)
+        
+        # Run before hooks
+        request = self.run_before_model(request)
+        
+        # Build wrapped handler that includes after hooks
+        def wrapped_model_fn(req: ModelRequest) -> ModelResponse:
+            response = model_fn(req)
+            return self.run_after_model(response)
+        
+        # Execute through middleware chain
+        return self._model_chain.execute(request, wrapped_model_fn)
+    
+    def execute_tool_call(
+        self,
+        request: ToolRequest,
+        tool_fn: Callable[[ToolRequest], ToolResponse]
+    ) -> ToolResponse:
+        """Execute a tool call with all hooks and middleware.
+        
+        Order:
+        1. before_tool hooks (in order)
+        2. wrap_tool_call middleware chain
+        3. actual tool call
+        4. after_tool hooks (in reverse order)
+        """
+        # Fast path: no hooks
+        if not self.has_tool_hooks:
+            return tool_fn(request)
+        
+        # Run before hooks
+        request = self.run_before_tool(request)
+        
+        # Build wrapped handler that includes after hooks
+        def wrapped_tool_fn(req: ToolRequest) -> ToolResponse:
+            response = tool_fn(req)
+            return self.run_after_tool(response)
+        
+        # Execute through middleware chain
+        return self._tool_chain.execute(request, wrapped_tool_fn)

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

@@ -27,6 +27,7 @@ from .model_router import (
     TaskComplexity,
     create_routing_agent
 )
+from .rate_limiter import RateLimiter
 
 __all__ = [
     "LLM", 
@@ -46,5 +47,6 @@ __all__ = [
     "ModelRouter",
     "ModelProfile",
     "TaskComplexity",
-    "create_routing_agent"
+    "create_routing_agent",
+    "RateLimiter"
 ]

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

@@ -0,0 +1,147 @@
+"""
+Rate Limiter for PraisonAI Agents.
+
+Provides token bucket rate limiting for LLM API calls.
+
+Zero Performance Impact:
+- When rate_limiter is None, no overhead
+- Uses monotonic clock for accuracy
+- Injectable clock/sleep for deterministic testing
+
+Usage:
+    from praisonaiagents.llm import RateLimiter
+    from praisonaiagents import Agent
+    
+    limiter = RateLimiter(requests_per_minute=60)
+    agent = Agent(name="Test", rate_limiter=limiter)
+"""
+
+import time
+import asyncio
+from dataclasses import dataclass, field
+from typing import Optional, Callable
+
+
+@dataclass
+class RateLimiter:
+    """Token bucket rate limiter for API calls.
+    
+    Uses the token bucket algorithm:
+    - Tokens are added at a fixed rate (requests_per_minute / 60 per second)
+    - Each request consumes one token
+    - If no tokens available, wait until one is available
+    - Burst allows multiple requests in quick succession
+    
+    Args:
+        requests_per_minute: Maximum requests per minute
+        tokens_per_minute: Optional token-based rate limiting (for future use)
+        burst: Maximum burst size (default: 1)
+    
+    Example:
+        limiter = RateLimiter(requests_per_minute=60)  # 1 req/sec
+        limiter.acquire()  # Blocks if rate exceeded
+        
+        # Async usage
+        await limiter.acquire_async()
+    """
+    requests_per_minute: int
+    tokens_per_minute: Optional[int] = None
+    burst: int = 1
+    
+    # Internal state
+    _tokens: float = field(default=None, init=False, repr=False)
+    _last_update: float = field(default=None, init=False, repr=False)
+    _lock: asyncio.Lock = field(default=None, init=False, repr=False)
+    
+    # Injectable functions for testing
+    _get_time: Callable[[], float] = field(default=None, init=False, repr=False)
+    _sleep: Callable[[float], None] = field(default=None, init=False, repr=False)
+    _async_sleep: Callable[[float], None] = field(default=None, init=False, repr=False)
+    
+    def __post_init__(self):
+        """Initialize internal state."""
+        self._tokens = float(self.burst)
+        self._last_update = time.monotonic()
+        self._lock = asyncio.Lock()
+        
+        # Default implementations (can be overridden for testing)
+        if self._get_time is None:
+            self._get_time = time.monotonic
+        if self._sleep is None:
+            self._sleep = time.sleep
+        if self._async_sleep is None:
+            self._async_sleep = asyncio.sleep
+    
+    @property
+    def _rate(self) -> float:
+        """Tokens per second."""
+        return self.requests_per_minute / 60.0
+    
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
+        now = self._get_time()
+        elapsed = now - self._last_update
+        self._tokens = min(self.burst, self._tokens + elapsed * self._rate)
+        self._last_update = now
+    
+    def _wait_time(self) -> float:
+        """Calculate time to wait for next token."""
+        if self._tokens >= 1.0:
+            return 0.0
+        return (1.0 - self._tokens) / self._rate
+    
+    def acquire(self) -> None:
+        """Acquire a token, blocking if necessary.
+        
+        This is the synchronous version. Use acquire_async() for async code.
+        """
+        self._refill()
+        
+        wait = self._wait_time()
+        if wait > 0:
+            self._sleep(wait)
+            self._refill()
+        
+        self._tokens -= 1.0
+    
+    async def acquire_async(self) -> None:
+        """Acquire a token asynchronously, waiting if necessary.
+        
+        This is the async version. Use acquire() for sync code.
+        """
+        async with self._lock:
+            self._refill()
+            
+            wait = self._wait_time()
+            if wait > 0:
+                await self._async_sleep(wait)
+                self._refill()
+            
+            self._tokens -= 1.0
+    
+    def try_acquire(self) -> bool:
+        """Try to acquire a token without blocking.
+        
+        Returns:
+            True if token acquired, False if rate limit exceeded
+        """
+        self._refill()
+        
+        if self._tokens >= 1.0:
+            self._tokens -= 1.0
+            return True
+        return False
+    
+    def reset(self) -> None:
+        """Reset the rate limiter to initial state."""
+        self._tokens = float(self.burst)
+        self._last_update = self._get_time()
+    
+    @property
+    def available_tokens(self) -> float:
+        """Get current available tokens (for monitoring)."""
+        self._refill()
+        return self._tokens
+    
+    def __repr__(self) -> str:
+        return f"RateLimiter(rpm={self.requests_per_minute}, burst={self.burst})"

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

@@ -0,0 +1,240 @@
+"""
+Observability interface for PraisonAI Agents.
+
+This module provides the protocol and types for observability/tracing.
+Implementations are provided by the wrapper layer (praisonai_tools.observability).
+
+Usage (simplest - recommended):
+    from praisonaiagents import Agent, obs
+    
+    agent = Agent(
+        name="Assistant",
+        observability=obs.auto(),  # Auto-detect from env vars
+    )
+    agent.chat("Hello!")  # Auto-traces to configured provider
+
+Alternative (explicit provider):
+    observability=obs.langfuse()     # Langfuse
+    observability=obs.langsmith()    # LangSmith
+    observability=obs.agentops()     # AgentOps
+    observability=obs.arize()        # Arize Phoenix
+    observability=obs.datadog()      # Datadog
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+from dataclasses import dataclass, field
+import time
+
+
+@dataclass
+class Span:
+    """Represents a span in a trace."""
+    span_id: str
+    trace_id: str
+    name: str
+    parent_span_id: Optional[str] = None
+    start_time: float = field(default_factory=time.time)
+    end_time: Optional[float] = None
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    status: str = "ok"
+
+
+@dataclass
+class Trace:
+    """Represents a complete trace."""
+    trace_id: str
+    session_id: Optional[str] = None
+    agent_name: Optional[str] = None
+    user_id: Optional[str] = None
+    start_time: float = field(default_factory=time.time)
+    end_time: Optional[float] = None
+    spans: List[Span] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    status: str = "ok"
+
+
+@runtime_checkable
+class ObservabilityAdapter(Protocol):
+    """Protocol for observability adapters."""
+    
+    def on_trace_start(
+        self,
+        trace_id: str,
+        session_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Called when a trace starts."""
+        ...
+    
+    def on_trace_end(
+        self,
+        trace_id: str,
+        status: str = "ok",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Called when a trace ends."""
+        ...
+    
+    def on_span_start(
+        self,
+        span_id: str,
+        trace_id: str,
+        name: str,
+        parent_span_id: Optional[str] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Called when a span starts."""
+        ...
+    
+    def on_span_end(
+        self,
+        span_id: str,
+        status: str = "ok",
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Called when a span ends."""
+        ...
+    
+    def on_llm_call(
+        self,
+        span_id: str,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response: Optional[str] = None,
+        tokens: Optional[Dict[str, int]] = None,
+        latency_ms: Optional[float] = None,
+    ) -> None:
+        """Called when an LLM call is made."""
+        ...
+    
+    def on_tool_call(
+        self,
+        span_id: str,
+        tool_name: str,
+        args: Dict[str, Any],
+        result: Any,
+        latency_ms: Optional[float] = None,
+    ) -> None:
+        """Called when a tool is invoked."""
+        ...
+    
+    def flush(self) -> None:
+        """Flush any pending data."""
+        ...
+    
+    def close(self) -> None:
+        """Close the adapter and release resources."""
+        ...
+
+
+class _LazyObsModule:
+    """
+    Lazy proxy for observability backends.
+    
+    Allows `from praisonaiagents import obs` without importing heavy deps.
+    Actual provider classes are loaded only when accessed.
+    """
+    
+    _PROVIDERS = {
+        "langfuse": "praisonai_tools.observability.providers.langfuse_provider",
+        "langsmith": "praisonai_tools.observability.providers.langsmith_provider",
+        "agentops": "praisonai_tools.observability.providers.agentops_provider",
+        "arize": "praisonai_tools.observability.providers.arize_phoenix_provider",
+        "phoenix": "praisonai_tools.observability.providers.arize_phoenix_provider",
+        "datadog": "praisonai_tools.observability.providers.datadog_provider",
+        "mlflow": "praisonai_tools.observability.providers.mlflow_provider",
+        "openlit": "praisonai_tools.observability.providers.openlit_provider",
+        "opik": "praisonai_tools.observability.providers.opik_provider",
+        "portkey": "praisonai_tools.observability.providers.portkey_provider",
+        "traceloop": "praisonai_tools.observability.providers.traceloop_provider",
+        "weave": "praisonai_tools.observability.providers.weave_provider",
+        "braintrust": "praisonai_tools.observability.providers.braintrust_provider",
+        "langtrace": "praisonai_tools.observability.providers.langtrace_provider",
+        "langwatch": "praisonai_tools.observability.providers.langwatch_provider",
+        "maxim": "praisonai_tools.observability.providers.maxim_provider",
+    }
+    
+    def __getattr__(self, name: str):
+        if name in self._PROVIDERS:
+            return self._create_provider_factory(name)
+        raise AttributeError(f"module 'obs' has no attribute {name!r}")
+    
+    def _create_provider_factory(self, provider_name: str):
+        """Create a factory function for a provider."""
+        def factory(**kwargs):
+            try:
+                import importlib
+                module = importlib.import_module(self._PROVIDERS[provider_name])
+                # Get the provider class (naming convention: XxxProvider)
+                class_name = f"{provider_name.title().replace('_', '')}Provider"
+                provider_cls = getattr(module, class_name, None)
+                if provider_cls:
+                    return provider_cls(**kwargs)
+                # Fallback: try to find any class ending with Provider
+                for attr_name in dir(module):
+                    if attr_name.endswith("Provider"):
+                        return getattr(module, attr_name)(**kwargs)
+                raise AttributeError(f"No provider class found in {module}")
+            except ImportError as e:
+                raise ImportError(
+                    f"Observability provider '{provider_name}' requires praisonai-tools. "
+                    f"Install with: pip install praisonai-tools\n"
+                    f"Original error: {e}"
+                ) from e
+        return factory
+    
+    def auto(self, **kwargs):
+        """
+        Auto-detect observability provider from environment variables.
+        
+        Checks for common env vars like LANGFUSE_PUBLIC_KEY, LANGSMITH_API_KEY, etc.
+        Returns None if no provider is detected.
+        """
+        import os
+        
+        # Check for common provider env vars
+        provider_env_map = {
+            "LANGFUSE_PUBLIC_KEY": "langfuse",
+            "LANGSMITH_API_KEY": "langsmith",
+            "AGENTOPS_API_KEY": "agentops",
+            "ARIZE_API_KEY": "arize",
+            "DATADOG_API_KEY": "datadog",
+            "MLFLOW_TRACKING_URI": "mlflow",
+            "OPENLIT_API_KEY": "openlit",
+            "OPIK_API_KEY": "opik",
+            "PORTKEY_API_KEY": "portkey",
+            "TRACELOOP_API_KEY": "traceloop",
+            "WANDB_API_KEY": "weave",
+            "BRAINTRUST_API_KEY": "braintrust",
+        }
+        
+        for env_var, provider in provider_env_map.items():
+            if os.getenv(env_var):
+                return self._create_provider_factory(provider)(**kwargs)
+        
+        return None
+    
+    def __repr__(self):
+        return "<module 'praisonaiagents.obs' (lazy observability backends)>"
+    
+    def __call__(self, provider: str = "auto", **kwargs):
+        """
+        Shortcut: obs("langfuse") or obs() for auto-detection.
+        """
+        if provider == "auto":
+            return self.auto(**kwargs)
+        return self._create_provider_factory(provider)(**kwargs)
+
+
+# Singleton lazy module instance
+obs = _LazyObsModule()
+
+
+__all__ = [
+    "ObservabilityAdapter",
+    "Span",
+    "Trace",
+    "obs",
+]

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

@@ -2,6 +2,9 @@
 from importlib import import_module
 from typing import Any
 
+# Export Injected type for tool state injection
+from .injected import Injected
+
 # Map of function names to their module and class (if any)
 TOOL_MAPPINGS = {
     # Direct functions
@@ -286,4 +289,4 @@ def __getattr__(name: str) -> Any:
         method = getattr(_instances[class_name], name)
         return method
 
-__all__ = list(TOOL_MAPPINGS.keys())
+__all__ = list(TOOL_MAPPINGS.keys()) + ['Injected']

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

@@ -14,6 +14,14 @@ Usage:
     @tool(name="web_search", description="Search the internet")
     def search(query: str, max_results: int = 5) -> list:
         return [...]
+    
+    # With injected state:
+    from praisonaiagents.tools import Injected
+    
+    @tool
+    def my_tool(query: str, state: Injected[dict]) -> str:
+        '''Tool with injected state.'''
+        return f"session={state.get('session_id')}"
 """
 
 import inspect
@@ -22,12 +30,19 @@ import logging
 from typing import Any, Callable, Dict, Optional, Union, get_type_hints
 
 from .base import BaseTool
+from .injected import (
+    is_injected_type, 
+    get_injected_params, 
+    inject_state_into_kwargs,
+    filter_injected_from_schema
+)
 
 
 class FunctionTool(BaseTool):
     """A BaseTool wrapper for plain functions.
     
     Created automatically by the @tool decorator.
+    Supports Injected[T] parameters for state injection.
     """
     
     def __init__(
@@ -42,6 +57,9 @@ class FunctionTool(BaseTool):
         self.description = description or func.__doc__ or f"Tool: {self.name}"
         self.version = version
         
+        # Detect injected parameters
+        self._injected_params = get_injected_params(func)
+        
         # Generate schema from the original function, not run()
         self.parameters = self._generate_schema_from_func(func)
         
@@ -55,8 +73,16 @@ class FunctionTool(BaseTool):
         if not self.description:
             self.description = self.__class__.__doc__ or f"Tool: {self.name}"
     
+    @property
+    def injected_params(self) -> Dict[str, Any]:
+        """Get the injected parameters for this tool."""
+        return self._injected_params
+    
     def _generate_schema_from_func(self, func: Callable) -> Dict[str, Any]:
-        """Generate JSON Schema from the wrapped function's signature."""
+        """Generate JSON Schema from the wrapped function's signature.
+        
+        Injected parameters are excluded from the schema.
+        """
         schema = {
             "type": "object",
             "properties": {},
@@ -71,8 +97,17 @@ class FunctionTool(BaseTool):
                 if param_name in ('self', 'cls'):
                     continue
                 
+                # Skip injected parameters - they don't go in schema
+                if param_name in self._injected_params:
+                    continue
+                
                 # Get type hint
                 param_type = hints.get(param_name, Any)
+                
+                # Double-check it's not an Injected type
+                if is_injected_type(param_type):
+                    continue
+                
                 json_type = BaseTool._python_type_to_json(param_type)
                 
                 schema["properties"][param_name] = {"type": json_type}
@@ -86,11 +121,18 @@ class FunctionTool(BaseTool):
         return schema
     
     def run(self, **kwargs) -> Any:
-        """Execute the wrapped function."""
+        """Execute the wrapped function with injected state."""
+        # Inject state for any Injected parameters
+        kwargs = inject_state_into_kwargs(kwargs, self._injected_params)
         return self._func(**kwargs)
     
     def __call__(self, *args, **kwargs) -> Any:
-        """Allow calling with positional args like the original function."""
+        """Allow calling with positional args like the original function.
+        
+        Injects state for Injected parameters.
+        """
+        # Inject state for any Injected parameters
+        kwargs = inject_state_into_kwargs(kwargs, self._injected_params)
         return self._func(*args, **kwargs)
 
 

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

@@ -0,0 +1,213 @@
+"""
+Injected State for PraisonAI Tools.
+
+Provides a mechanism for tools to receive injected state (agent context)
+without exposing it in the tool's public schema.
+
+Zero Performance Impact:
+- When no Injected params, no overhead
+- Context is thread-local for safety
+- Lazy evaluation of state
+
+Usage:
+    from praisonaiagents import tool
+    from praisonaiagents.tools import Injected
+    
+    @tool
+    def my_tool(query: str, state: Injected[dict]) -> str:
+        '''Tool with injected state.'''
+        session_id = state.get('session_id')
+        return f"Query: {query}, Session: {session_id}"
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generic, List, Optional, TypeVar, get_type_hints, get_origin, get_args
+from contextvars import ContextVar
+from contextlib import contextmanager
+
+
+T = TypeVar('T')
+
+
+class Injected(Generic[T]):
+    """Type marker for injected parameters.
+    
+    Parameters annotated with Injected[T] will:
+    - Not appear in the tool's public schema
+    - Be automatically injected at runtime with the current agent state
+    
+    Supported types:
+    - Injected[dict] - Receives state as a dictionary
+    - Injected[AgentState] - Receives state as AgentState dataclass
+    
+    Example:
+        @tool
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            return f"session={state.get('session_id')}"
+    """
+    pass
+
+
+@dataclass
+class AgentState:
+    """State object injected into tools.
+    
+    Contains context about the current agent execution.
+    """
+    agent_id: str
+    run_id: str
+    session_id: str
+    last_user_message: Optional[str] = None
+    last_agent_message: Optional[str] = None
+    memory: Optional[Any] = None
+    previous_tool_results: List[Any] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for Injected[dict] usage."""
+        return {
+            'agent_id': self.agent_id,
+            'run_id': self.run_id,
+            'session_id': self.session_id,
+            'last_user_message': self.last_user_message,
+            'last_agent_message': self.last_agent_message,
+            'previous_tool_results': self.previous_tool_results,
+            'metadata': self.metadata,
+        }
+
+
+# Thread-local context for current state
+_current_state: ContextVar[Optional[AgentState]] = ContextVar('current_state', default=None)
+
+
+def get_current_state() -> Optional[AgentState]:
+    """Get the current injection state."""
+    return _current_state.get()
+
+
+def set_current_state(state: Optional[AgentState]) -> None:
+    """Set the current injection state."""
+    _current_state.set(state)
+
+
+@contextmanager
+def with_injection_context(state: AgentState):
+    """Context manager for setting injection state.
+    
+    Usage:
+        with with_injection_context(state):
+            result = my_tool(query="test")
+    """
+    token = _current_state.set(state)
+    try:
+        yield
+    finally:
+        _current_state.reset(token)
+
+
+def is_injected_type(annotation: Any) -> bool:
+    """Check if a type annotation is Injected[T]."""
+    origin = get_origin(annotation)
+    if origin is Injected:
+        return True
+    # Handle string annotations
+    if isinstance(annotation, str) and 'Injected' in annotation:
+        return True
+    return False
+
+
+def get_injected_type(annotation: Any) -> Optional[type]:
+    """Get the inner type T from Injected[T]."""
+    origin = get_origin(annotation)
+    if origin is Injected:
+        args = get_args(annotation)
+        if args:
+            return args[0]
+    return None
+
+
+def resolve_injected_value(annotation: Any, state: Optional[AgentState]) -> Any:
+    """Resolve the value to inject based on annotation type.
+    
+    Args:
+        annotation: The Injected[T] annotation
+        state: The current agent state
+        
+    Returns:
+        The resolved value (dict or AgentState)
+    """
+    if state is None:
+        # Return empty dict if no state available
+        return {}
+    
+    inner_type = get_injected_type(annotation)
+    
+    if inner_type is dict or inner_type is Dict:
+        return state.to_dict()
+    elif inner_type is AgentState:
+        return state
+    else:
+        # Default to dict
+        return state.to_dict()
+
+
+def get_injected_params(func) -> Dict[str, Any]:
+    """Get all injected parameters from a function.
+    
+    Returns:
+        Dict mapping param name to its Injected[T] annotation
+    """
+    try:
+        hints = get_type_hints(func)
+    except Exception:
+        # If we can't get hints, return empty
+        return {}
+    
+    injected = {}
+    for name, hint in hints.items():
+        if name == 'return':
+            continue
+        if is_injected_type(hint):
+            injected[name] = hint
+    
+    return injected
+
+
+def filter_injected_from_schema(properties: Dict[str, Any], required: List[str], 
+                                 injected_params: Dict[str, Any]) -> tuple:
+    """Remove injected parameters from schema.
+    
+    Args:
+        properties: Schema properties dict
+        required: List of required param names
+        injected_params: Dict of injected param names
+        
+    Returns:
+        Tuple of (filtered_properties, filtered_required)
+    """
+    filtered_props = {k: v for k, v in properties.items() if k not in injected_params}
+    filtered_required = [r for r in required if r not in injected_params]
+    return filtered_props, filtered_required
+
+
+def inject_state_into_kwargs(kwargs: Dict[str, Any], injected_params: Dict[str, Any]) -> Dict[str, Any]:
+    """Inject state values into kwargs for injected parameters.
+    
+    Args:
+        kwargs: The original kwargs
+        injected_params: Dict of injected param names to annotations
+        
+    Returns:
+        Updated kwargs with injected values
+    """
+    if not injected_params:
+        return kwargs
+    
+    state = get_current_state()
+    result = kwargs.copy()
+    
+    for param_name, annotation in injected_params.items():
+        if param_name not in result:
+            result[param_name] = resolve_injected_value(annotation, state)
+    
+    return result

src/praisonai-agents/pyproject.toml

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

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

@@ -0,0 +1,234 @@
+"""
+TDD Tests for Configurable Model (runtime model switching).
+
+These tests are written FIRST before implementation.
+"""
+
+import pytest
+from unittest.mock import Mock, patch
+
+
+class TestConfigurableModelBasic:
+    """Test basic configurable model functionality."""
+    
+    def test_agent_accepts_llm_config_configurable(self):
+        """Agent should accept llm_config with configurable=True."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        assert agent is not None
+        assert getattr(agent, '_llm_configurable', False) is True
+    
+    def test_agent_chat_accepts_config_parameter(self):
+        """Agent.chat() should accept config parameter for model override."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        # Should not raise - config parameter should be accepted
+        # We'll mock the actual LLM call
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            result = agent.chat(
+                "Hello",
+                config={"model": "claude-3-5-sonnet"}
+            )
+    
+    def test_config_model_override(self):
+        """config.model should override default model for that call."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        # Track which model was used
+        used_model = [None]
+        
+        original_chat = agent._chat_completion
+        def mock_chat(*args, **kwargs):
+            # The model should be accessible somehow
+            used_model[0] = getattr(agent, '_current_model', agent.llm)
+            return "response"
+        
+        with patch.object(agent, '_chat_completion', side_effect=mock_chat):
+            agent.chat("Hello", config={"model": "claude-3-5-sonnet"})
+        
+        # Model should have been switched for this call
+        # Implementation will set _current_model or similar
+    
+    def test_config_does_not_mutate_default(self):
+        """Per-call config should not change agent's default model."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        original_llm = agent.llm
+        
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            agent.chat("Hello", config={"model": "claude-3-5-sonnet"})
+        
+        # Default should be unchanged
+        assert agent.llm == original_llm
+    
+    def test_config_temperature_override(self):
+        """config.temperature should override for that call."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        # Should accept temperature in config
+        with patch.object(agent, '_chat_completion', return_value="mocked") as mock:
+            agent.chat("Hello", config={"temperature": 0.2})
+            # Temperature should be passed through
+
+
+class TestConfigurableModelCaching:
+    """Test model client caching for configurable models."""
+    
+    def test_model_client_cached(self):
+        """Model clients should be cached to avoid recreation."""
+        from praisonaiagents.llm import LLM
+        
+        llm = LLM(model="gpt-4o", configurable=True)
+        
+        # First call with model A
+        # Second call with model A should reuse client
+        # This is internal behavior - we test via call count or similar
+    
+    def test_cache_size_limited(self):
+        """Model client cache should have a size limit."""
+        from praisonaiagents.llm import LLM
+        
+        llm = LLM(model="gpt-4o", configurable=True, cache_size=3)
+        
+        # Should not grow unbounded
+
+
+class TestConfigurableModelThreadSafety:
+    """Test thread safety of configurable models."""
+    
+    def test_concurrent_calls_different_models(self):
+        """Concurrent calls with different models should not interfere."""
+        import threading
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        results = {}
+        errors = []
+        
+        def call_with_model(model_name, thread_id):
+            try:
+                with patch.object(agent, '_chat_completion', return_value=f"response_{model_name}"):
+                    result = agent.chat("Hello", config={"model": model_name})
+                    results[thread_id] = result
+            except Exception as e:
+                errors.append(e)
+        
+        threads = [
+            threading.Thread(target=call_with_model, args=("model_a", 1)),
+            threading.Thread(target=call_with_model, args=("model_b", 2)),
+        ]
+        
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        
+        assert len(errors) == 0
+
+
+class TestConfigurableModelValidation:
+    """Test validation of configurable model settings."""
+    
+    def test_config_without_configurable_flag_ignored(self):
+        """If llm_config.configurable is False, config param should be ignored."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o"
+            # No llm_config or configurable=False
+        )
+        
+        # Should still work, just ignore the config
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            result = agent.chat("Hello", config={"model": "other"})
+            # Should use default model, not "other"
+    
+    def test_invalid_config_keys_ignored(self):
+        """Unknown keys in config should be ignored, not error."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        # Should not raise for unknown keys
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            result = agent.chat("Hello", config={"unknown_key": "value"})
+
+
+class TestConfigurableModelProvider:
+    """Test provider switching in configurable models."""
+    
+    def test_config_provider_override(self):
+        """config.provider should allow switching providers."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        # Should accept provider in config
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            agent.chat("Hello", config={"provider": "anthropic", "model": "claude-3-5-sonnet"})
+    
+    def test_model_string_with_provider_prefix(self):
+        """Model string like 'anthropic/claude-3' should work."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            llm="gpt-4o",
+            llm_config={"configurable": True}
+        )
+        
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            agent.chat("Hello", config={"model": "anthropic/claude-3-5-sonnet"})

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

@@ -0,0 +1,367 @@
+"""
+TDD Tests for InjectedState for Tools.
+
+These tests are written FIRST before implementation.
+"""
+
+import pytest
+from unittest.mock import Mock, patch
+
+
+class TestInjectedTypeExists:
+    """Test that Injected type marker exists."""
+    
+    def test_injected_type_exists(self):
+        """Injected type should exist in praisonaiagents.tools."""
+        from praisonaiagents.tools import Injected
+        
+        # Should be a generic type marker
+        assert Injected is not None
+    
+    def test_injected_generic_usage(self):
+        """Injected should work as a generic type annotation."""
+        from praisonaiagents.tools import Injected
+        
+        # Should be usable as Injected[dict], Injected[SomeType], etc.
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            return query
+        
+        # Should have annotations
+        annotations = my_tool.__annotations__
+        assert 'state' in annotations
+    
+    def test_injected_with_agent_state(self):
+        """Injected[AgentState] should work."""
+        from praisonaiagents.tools import Injected
+        from praisonaiagents.tools.injected import AgentState
+        
+        def my_tool(query: str, state: Injected[AgentState]) -> str:
+            return query
+        
+        annotations = my_tool.__annotations__
+        assert 'state' in annotations
+
+
+class TestAgentStateType:
+    """Test AgentState type for injection."""
+    
+    def test_agent_state_exists(self):
+        """AgentState type should exist."""
+        from praisonaiagents.tools.injected import AgentState
+        
+        assert AgentState is not None
+    
+    def test_agent_state_has_required_fields(self):
+        """AgentState should have agent_id, run_id, session_id."""
+        from praisonaiagents.tools.injected import AgentState
+        
+        state = AgentState(
+            agent_id="agent-123",
+            run_id="run-456",
+            session_id="session-789"
+        )
+        
+        assert state.agent_id == "agent-123"
+        assert state.run_id == "run-456"
+        assert state.session_id == "session-789"
+    
+    def test_agent_state_optional_fields(self):
+        """AgentState should have optional fields."""
+        from praisonaiagents.tools.injected import AgentState
+        
+        state = AgentState(
+            agent_id="a",
+            run_id="r",
+            session_id="s",
+            last_user_message="Hello",
+            last_agent_message="Hi there",
+            memory=Mock(),
+            previous_tool_results=["result1", "result2"]
+        )
+        
+        assert state.last_user_message == "Hello"
+        assert state.last_agent_message == "Hi there"
+        assert state.memory is not None
+        assert len(state.previous_tool_results) == 2
+
+
+class TestToolDecoratorInjection:
+    """Test @tool decorator handles Injected parameters."""
+    
+    def test_tool_decorator_detects_injected(self):
+        """@tool should detect Injected parameters."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        
+        @tool
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            """A tool with injected state."""
+            return f"query={query}, session={state.get('session_id')}"
+        
+        # Should have metadata about injected params
+        assert hasattr(my_tool, '_injected_params') or hasattr(my_tool, 'injected_params')
+    
+    def test_injected_params_not_in_schema(self):
+        """Injected parameters should not appear in tool schema."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        
+        @tool
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            """A tool with injected state."""
+            return query
+        
+        schema = my_tool.get_schema()
+        params = schema['function']['parameters']['properties']
+        
+        # 'query' should be in schema
+        assert 'query' in params
+        # 'state' should NOT be in schema (it's injected)
+        assert 'state' not in params
+    
+    def test_injected_params_not_required(self):
+        """Injected parameters should not be in required list."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        
+        @tool
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            """A tool with injected state."""
+            return query
+        
+        schema = my_tool.get_schema()
+        required = schema['function']['parameters'].get('required', [])
+        
+        assert 'state' not in required
+        assert 'query' in required
+
+
+class TestToolExecutionInjection:
+    """Test that injected state is provided at runtime."""
+    
+    def test_injected_state_provided_at_runtime(self):
+        """When tool is called, injected state should be provided."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        from praisonaiagents.tools.injected import AgentState
+        
+        received_state = [None]
+        
+        @tool
+        def my_tool(query: str, state: Injected[AgentState]) -> str:
+            """A tool with injected state."""
+            received_state[0] = state
+            return f"session={state.session_id}"
+        
+        # Simulate execution with injection context
+        from praisonaiagents.tools.injected import with_injection_context
+        
+        mock_state = AgentState(
+            agent_id="a",
+            run_id="r",
+            session_id="test-session"
+        )
+        
+        with with_injection_context(mock_state):
+            result = my_tool(query="hello")
+        
+        assert received_state[0] is not None
+        assert received_state[0].session_id == "test-session"
+    
+    def test_injected_dict_state(self):
+        """Injected[dict] should provide dict with state info."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        from praisonaiagents.tools.injected import with_injection_context, AgentState
+        
+        received_state = [None]
+        
+        @tool
+        def my_tool(query: str, state: Injected[dict]) -> str:
+            """A tool with injected dict state."""
+            received_state[0] = state
+            return "ok"
+        
+        mock_state = AgentState(
+            agent_id="a",
+            run_id="r",
+            session_id="s"
+        )
+        
+        with with_injection_context(mock_state):
+            my_tool(query="test")
+        
+        assert isinstance(received_state[0], dict)
+        assert 'session_id' in received_state[0]
+
+
+class TestAgentToolExecution:
+    """Test Agent executes tools with injection."""
+    
+    def test_agent_injects_state_to_tools(self):
+        """Agent should inject state when executing tools."""
+        from praisonaiagents import Agent, tool
+        from praisonaiagents.tools import Injected
+        
+        received_session = [None]
+        
+        @tool
+        def show_state(query: str, state: Injected[dict]) -> str:
+            """Show the injected state."""
+            received_session[0] = state.get('session_id')
+            return f"session={state.get('session_id')}"
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            tools=[show_state],
+            session_id="my-session-123"
+        )
+        
+        # Execute the tool directly through agent
+        result = agent.execute_tool("show_state", {"query": "test"})
+        
+        # State should have been injected
+        assert received_session[0] == "my-session-123"
+
+
+class TestInjectionContextManager:
+    """Test injection context manager."""
+    
+    def test_with_injection_context_exists(self):
+        """with_injection_context should exist."""
+        from praisonaiagents.tools.injected import with_injection_context
+        
+        assert with_injection_context is not None
+    
+    def test_context_manager_sets_state(self):
+        """Context manager should set current state."""
+        from praisonaiagents.tools.injected import (
+            with_injection_context, 
+            get_current_state,
+            AgentState
+        )
+        
+        state = AgentState(agent_id="a", run_id="r", session_id="s")
+        
+        with with_injection_context(state):
+            current = get_current_state()
+            assert current is state
+        
+        # After context, should be None
+        assert get_current_state() is None
+    
+    def test_nested_contexts(self):
+        """Nested contexts should work correctly."""
+        from praisonaiagents.tools.injected import (
+            with_injection_context,
+            get_current_state,
+            AgentState
+        )
+        
+        state1 = AgentState(agent_id="a1", run_id="r1", session_id="s1")
+        state2 = AgentState(agent_id="a2", run_id="r2", session_id="s2")
+        
+        with with_injection_context(state1):
+            assert get_current_state().agent_id == "a1"
+            
+            with with_injection_context(state2):
+                assert get_current_state().agent_id == "a2"
+            
+            # Back to state1
+            assert get_current_state().agent_id == "a1"
+
+
+class TestAsyncInjection:
+    """Test async tool injection."""
+    
+    @pytest.mark.asyncio
+    async def test_async_tool_injection(self):
+        """Async tools should also receive injected state."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        from praisonaiagents.tools.injected import with_injection_context, AgentState
+        
+        received_state = [None]
+        
+        @tool
+        async def async_tool(query: str, state: Injected[dict]) -> str:
+            """Async tool with injected state."""
+            received_state[0] = state
+            return "ok"
+        
+        state = AgentState(agent_id="a", run_id="r", session_id="async-session")
+        
+        with with_injection_context(state):
+            await async_tool(query="test")
+        
+        assert received_state[0] is not None
+        assert received_state[0].get('session_id') == "async-session"
+
+
+class TestInjectionZeroOverhead:
+    """Test that injection has zero overhead when not used."""
+    
+    def test_no_injected_params_no_overhead(self):
+        """Tools without Injected params should have no overhead."""
+        from praisonaiagents import tool
+        
+        @tool
+        def simple_tool(query: str) -> str:
+            """Simple tool without injection."""
+            return query
+        
+        # Should work normally without any injection context
+        result = simple_tool(query="hello")
+        assert result == "hello"
+    
+    def test_schema_generation_fast(self):
+        """Schema generation should be fast even with Injected params."""
+        from praisonaiagents import tool
+        from praisonaiagents.tools import Injected
+        import time
+        
+        @tool
+        def my_tool(a: str, b: int, c: Injected[dict], d: float) -> str:
+            """Tool with mixed params."""
+            return a
+        
+        start = time.monotonic()
+        for _ in range(100):
+            my_tool.get_schema()
+        elapsed = time.monotonic() - start
+        
+        # Should be very fast
+        assert elapsed < 0.1  # 100 calls in < 100ms
+
+
+class TestBackwardCompatibility:
+    """Test backward compatibility with existing tools."""
+    
+    def test_existing_tools_still_work(self):
+        """Existing tools without Injected should continue to work."""
+        from praisonaiagents import tool
+        
+        @tool
+        def legacy_tool(query: str, count: int = 5) -> str:
+            """Legacy tool."""
+            return f"{query} x {count}"
+        
+        result = legacy_tool(query="test", count=3)
+        assert result == "test x 3"
+    
+    def test_existing_tool_schema_unchanged(self):
+        """Existing tool schemas should be unchanged."""
+        from praisonaiagents import tool
+        
+        @tool
+        def legacy_tool(query: str, count: int = 5) -> str:
+            """Legacy tool."""
+            return f"{query} x {count}"
+        
+        schema = legacy_tool.get_schema()
+        params = schema['function']['parameters']['properties']
+        
+        assert 'query' in params
+        assert 'count' in params
+        assert len(params) == 2

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

@@ -0,0 +1,403 @@
+"""
+TDD Tests for Middleware System (wrap_model_call, wrap_tool_call).
+
+These tests are written FIRST before implementation.
+"""
+
+import pytest
+from unittest.mock import Mock, MagicMock, patch, AsyncMock
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+class TestMiddlewareTypes:
+    """Test middleware type definitions."""
+    
+    def test_invocation_context_exists(self):
+        """InvocationContext dataclass should exist with required fields."""
+        from praisonaiagents.hooks.middleware import InvocationContext
+        
+        ctx = InvocationContext(
+            agent_id="agent-123",
+            run_id="run-456",
+            session_id="session-789"
+        )
+        assert ctx.agent_id == "agent-123"
+        assert ctx.run_id == "run-456"
+        assert ctx.session_id == "session-789"
+    
+    def test_invocation_context_optional_fields(self):
+        """InvocationContext should have optional tool_name, model_name, metadata."""
+        from praisonaiagents.hooks.middleware import InvocationContext
+        
+        ctx = InvocationContext(
+            agent_id="a",
+            run_id="r",
+            session_id="s",
+            tool_name="my_tool",
+            model_name="gpt-4o",
+            metadata={"key": "value"}
+        )
+        assert ctx.tool_name == "my_tool"
+        assert ctx.model_name == "gpt-4o"
+        assert ctx.metadata == {"key": "value"}
+    
+    def test_model_request_exists(self):
+        """ModelRequest dataclass for before_model hooks."""
+        from praisonaiagents.hooks.middleware import ModelRequest
+        
+        req = ModelRequest(
+            messages=[{"role": "user", "content": "Hello"}],
+            model="gpt-4o",
+            temperature=0.7,
+            context=Mock()
+        )
+        assert req.messages == [{"role": "user", "content": "Hello"}]
+        assert req.model == "gpt-4o"
+        assert req.temperature == 0.7
+    
+    def test_model_response_exists(self):
+        """ModelResponse dataclass for after_model hooks."""
+        from praisonaiagents.hooks.middleware import ModelResponse
+        
+        resp = ModelResponse(
+            content="Hello back!",
+            model="gpt-4o",
+            usage={"prompt_tokens": 10, "completion_tokens": 5},
+            context=Mock()
+        )
+        assert resp.content == "Hello back!"
+        assert resp.model == "gpt-4o"
+    
+    def test_tool_request_exists(self):
+        """ToolRequest dataclass for before_tool hooks."""
+        from praisonaiagents.hooks.middleware import ToolRequest
+        
+        req = ToolRequest(
+            tool_name="get_weather",
+            arguments={"city": "Paris"},
+            context=Mock()
+        )
+        assert req.tool_name == "get_weather"
+        assert req.arguments == {"city": "Paris"}
+    
+    def test_tool_response_exists(self):
+        """ToolResponse dataclass for after_tool hooks."""
+        from praisonaiagents.hooks.middleware import ToolResponse
+        
+        resp = ToolResponse(
+            tool_name="get_weather",
+            result="Sunny, 22°C",
+            error=None,
+            context=Mock()
+        )
+        assert resp.result == "Sunny, 22°C"
+        assert resp.error is None
+
+
+class TestMiddlewareDecorators:
+    """Test middleware decorator functions."""
+    
+    def test_before_model_decorator_exists(self):
+        """before_model decorator should exist and tag functions."""
+        from praisonaiagents.hooks import before_model
+        
+        @before_model
+        def my_hook(request):
+            return request
+        
+        assert hasattr(my_hook, '_hook_type')
+        assert my_hook._hook_type == 'before_model'
+    
+    def test_after_model_decorator_exists(self):
+        """after_model decorator should exist and tag functions."""
+        from praisonaiagents.hooks import after_model
+        
+        @after_model
+        def my_hook(response):
+            return response
+        
+        assert hasattr(my_hook, '_hook_type')
+        assert my_hook._hook_type == 'after_model'
+    
+    def test_wrap_model_call_decorator_exists(self):
+        """wrap_model_call decorator should exist and tag functions."""
+        from praisonaiagents.hooks import wrap_model_call
+        
+        @wrap_model_call
+        def my_middleware(request, call_next):
+            return call_next(request)
+        
+        assert hasattr(my_middleware, '_hook_type')
+        assert my_middleware._hook_type == 'wrap_model_call'
+    
+    def test_before_tool_decorator_exists(self):
+        """before_tool decorator should exist and tag functions."""
+        from praisonaiagents.hooks import before_tool
+        
+        @before_tool
+        def my_hook(request):
+            return request
+        
+        assert hasattr(my_hook, '_hook_type')
+        assert my_hook._hook_type == 'before_tool'
+    
+    def test_after_tool_decorator_exists(self):
+        """after_tool decorator should exist and tag functions."""
+        from praisonaiagents.hooks import after_tool
+        
+        @after_tool
+        def my_hook(response):
+            return response
+        
+        assert hasattr(my_hook, '_hook_type')
+        assert my_hook._hook_type == 'after_tool'
+    
+    def test_wrap_tool_call_decorator_exists(self):
+        """wrap_tool_call decorator should exist and tag functions."""
+        from praisonaiagents.hooks import wrap_tool_call
+        
+        @wrap_tool_call
+        def my_middleware(request, call_next):
+            return call_next(request)
+        
+        assert hasattr(my_middleware, '_hook_type')
+        assert my_middleware._hook_type == 'wrap_tool_call'
+
+
+class TestMiddlewareChaining:
+    """Test middleware chain composition."""
+    
+    def test_wrap_model_call_chain_order(self):
+        """wrap_model_call hooks should compose in registration order."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        calls = []
+        
+        def mw1(req, call_next):
+            calls.append("mw1_before")
+            result = call_next(req)
+            calls.append("mw1_after")
+            return result
+        
+        def mw2(req, call_next):
+            calls.append("mw2_before")
+            result = call_next(req)
+            calls.append("mw2_after")
+            return result
+        
+        def final_handler(req):
+            calls.append("final")
+            return "response"
+        
+        chain = MiddlewareChain([mw1, mw2])
+        result = chain.execute({"test": True}, final_handler)
+        
+        assert calls == ["mw1_before", "mw2_before", "final", "mw2_after", "mw1_after"]
+        assert result == "response"
+    
+    def test_empty_middleware_chain(self):
+        """Empty middleware chain should just call final handler."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        def final_handler(req):
+            return "direct"
+        
+        chain = MiddlewareChain([])
+        result = chain.execute({"test": True}, final_handler)
+        assert result == "direct"
+    
+    def test_middleware_can_modify_request(self):
+        """Middleware should be able to modify request before passing on."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        def add_context(req, call_next):
+            req["extra"] = "added"
+            return call_next(req)
+        
+        def final_handler(req):
+            return req.get("extra")
+        
+        chain = MiddlewareChain([add_context])
+        result = chain.execute({"original": True}, final_handler)
+        assert result == "added"
+    
+    def test_middleware_can_modify_response(self):
+        """Middleware should be able to modify response after call_next."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        def uppercase_response(req, call_next):
+            result = call_next(req)
+            return result.upper()
+        
+        def final_handler(req):
+            return "hello"
+        
+        chain = MiddlewareChain([uppercase_response])
+        result = chain.execute({}, final_handler)
+        assert result == "HELLO"
+    
+    def test_middleware_can_short_circuit(self):
+        """Middleware can return early without calling call_next."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        def block_middleware(req, call_next):
+            if req.get("block"):
+                return "blocked"
+            return call_next(req)
+        
+        def final_handler(req):
+            return "reached"
+        
+        chain = MiddlewareChain([block_middleware])
+        
+        # Should be blocked
+        result = chain.execute({"block": True}, final_handler)
+        assert result == "blocked"
+        
+        # Should pass through
+        result = chain.execute({"block": False}, final_handler)
+        assert result == "reached"
+
+
+class TestMiddlewareRetry:
+    """Test retry logic in middleware."""
+    
+    def test_wrap_tool_call_retry_on_error(self):
+        """wrap_tool_call should support retry patterns."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        attempt_count = [0]
+        
+        def retry_middleware(req, call_next):
+            last_error = None
+            for i in range(3):
+                try:
+                    return call_next(req)
+                except Exception as e:
+                    last_error = e
+            raise last_error
+        
+        def flaky_handler(req):
+            attempt_count[0] += 1
+            if attempt_count[0] < 3:
+                raise RuntimeError("flaky")
+            return "success"
+        
+        chain = MiddlewareChain([retry_middleware])
+        result = chain.execute({}, flaky_handler)
+        assert result == "success"
+        assert attempt_count[0] == 3
+
+
+class TestAsyncMiddleware:
+    """Test async middleware support."""
+    
+    @pytest.mark.asyncio
+    async def test_async_wrap_model_call(self):
+        """Async middleware should work with async handlers."""
+        from praisonaiagents.hooks.middleware import AsyncMiddlewareChain
+        
+        calls = []
+        
+        async def async_mw(req, call_next):
+            calls.append("before")
+            result = await call_next(req)
+            calls.append("after")
+            return result
+        
+        async def async_handler(req):
+            calls.append("handler")
+            return "async_result"
+        
+        chain = AsyncMiddlewareChain([async_mw])
+        result = await chain.execute({}, async_handler)
+        
+        assert calls == ["before", "handler", "after"]
+        assert result == "async_result"
+    
+    @pytest.mark.asyncio
+    async def test_async_middleware_chain_order(self):
+        """Async middleware should maintain order."""
+        from praisonaiagents.hooks.middleware import AsyncMiddlewareChain
+        
+        order = []
+        
+        async def mw1(req, call_next):
+            order.append(1)
+            result = await call_next(req)
+            order.append(-1)
+            return result
+        
+        async def mw2(req, call_next):
+            order.append(2)
+            result = await call_next(req)
+            order.append(-2)
+            return result
+        
+        async def handler(req):
+            order.append(0)
+            return "done"
+        
+        chain = AsyncMiddlewareChain([mw1, mw2])
+        await chain.execute({}, handler)
+        
+        assert order == [1, 2, 0, -2, -1]
+
+
+class TestAgentMiddlewareIntegration:
+    """Test middleware integration with Agent class."""
+    
+    def test_agent_accepts_hooks_parameter(self):
+        """Agent should accept hooks parameter."""
+        from praisonaiagents import Agent
+        from praisonaiagents.hooks import before_model
+        
+        @before_model
+        def my_hook(req):
+            return req
+        
+        # Should not raise
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            hooks=[my_hook]
+        )
+        assert agent is not None
+    
+    def test_agent_hooks_empty_by_default(self):
+        """Agent should have empty hooks by default."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", instructions="Test")
+        # Should have no hooks or empty hooks list
+        hooks = getattr(agent, '_hooks', None) or getattr(agent, 'hooks', [])
+        assert hooks is None or len(hooks) == 0
+
+
+class TestMiddlewareZeroOverhead:
+    """Test that middleware has zero overhead when not used."""
+    
+    def test_no_hooks_fast_path(self):
+        """When no hooks registered, should take fast path."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        # Empty chain should be essentially a no-op
+        chain = MiddlewareChain([])
+        
+        call_count = [0]
+        def handler(req):
+            call_count[0] += 1
+            return "result"
+        
+        result = chain.execute({}, handler)
+        assert result == "result"
+        assert call_count[0] == 1
+    
+    def test_middleware_chain_is_none_check(self):
+        """Should handle None middleware list gracefully."""
+        from praisonaiagents.hooks.middleware import MiddlewareChain
+        
+        chain = MiddlewareChain(None)
+        result = chain.execute({}, lambda r: "ok")
+        assert result == "ok"

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

@@ -0,0 +1,260 @@
+"""
+TDD Tests for Rate Limiter.
+
+These tests are written FIRST before implementation.
+"""
+
+import pytest
+import time
+from unittest.mock import Mock, patch
+
+
+class TestRateLimiterBasic:
+    """Test basic rate limiter functionality."""
+    
+    def test_rate_limiter_exists(self):
+        """RateLimiter class should exist in praisonaiagents.llm."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        assert limiter is not None
+    
+    def test_rate_limiter_rpm_parameter(self):
+        """RateLimiter should accept requests_per_minute."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        assert limiter.requests_per_minute == 60
+    
+    def test_rate_limiter_acquire_sync(self):
+        """RateLimiter.acquire() should block if rate exceeded."""
+        from praisonaiagents.llm import RateLimiter
+        
+        # 1 request per second = 60 per minute
+        limiter = RateLimiter(requests_per_minute=60)
+        
+        # First acquire should be instant
+        start = time.monotonic()
+        limiter.acquire()
+        elapsed = time.monotonic() - start
+        assert elapsed < 0.1  # Should be nearly instant
+    
+    def test_rate_limiter_blocks_when_exceeded(self):
+        """RateLimiter should block when rate is exceeded."""
+        from praisonaiagents.llm import RateLimiter
+        
+        # Very low rate: 6 per minute = 1 per 10 seconds
+        # But we'll use a mock clock to test without waiting
+        limiter = RateLimiter(requests_per_minute=6)
+        
+        # Inject a mock clock for testing
+        mock_time = [0.0]
+        limiter._get_time = lambda: mock_time[0]
+        limiter._sleep = lambda s: mock_time.__setitem__(0, mock_time[0] + s)
+        
+        # First request should pass
+        limiter.acquire()
+        
+        # Second request should need to wait ~10 seconds
+        # (but our mock sleep just advances time)
+        limiter.acquire()
+        
+        # Time should have advanced
+        assert mock_time[0] >= 10.0
+    
+    def test_rate_limiter_token_bucket(self):
+        """RateLimiter should use token bucket algorithm."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60, burst=5)
+        
+        # Reset internal state with mock time
+        mock_time = [0.0]
+        limiter._get_time = lambda: mock_time[0]
+        limiter._sleep = lambda s: mock_time.__setitem__(0, mock_time[0] + s)
+        limiter._tokens = 5.0  # Reset tokens to burst size
+        limiter._last_update = 0.0  # Reset last update
+        
+        for _ in range(5):
+            limiter.acquire()
+        
+        # Should not have waited much (burst allows 5 instant requests)
+        assert mock_time[0] < 1.0
+
+
+class TestRateLimiterAsync:
+    """Test async rate limiter functionality."""
+    
+    @pytest.mark.asyncio
+    async def test_rate_limiter_acquire_async(self):
+        """RateLimiter.acquire_async() should work with async."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        
+        # Should have async acquire method
+        await limiter.acquire_async()
+    
+    @pytest.mark.asyncio
+    async def test_rate_limiter_async_blocks(self):
+        """Async acquire should also respect rate limits."""
+        from praisonaiagents.llm import RateLimiter
+        import asyncio
+        
+        limiter = RateLimiter(requests_per_minute=6)
+        
+        # Mock async sleep
+        sleep_times = []
+        original_sleep = asyncio.sleep
+        
+        async def mock_sleep(s):
+            sleep_times.append(s)
+            # Don't actually sleep in tests
+        
+        with patch('asyncio.sleep', mock_sleep):
+            await limiter.acquire_async()
+            await limiter.acquire_async()
+        
+        # Should have tried to sleep
+
+
+class TestRateLimiterAgentIntegration:
+    """Test rate limiter integration with Agent."""
+    
+    def test_agent_accepts_rate_limiter(self):
+        """Agent should accept rate_limiter parameter."""
+        from praisonaiagents import Agent
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            rate_limiter=limiter
+        )
+        assert agent is not None
+        assert getattr(agent, '_rate_limiter', None) is limiter or \
+               getattr(agent, 'rate_limiter', None) is limiter
+    
+    def test_agent_rate_limiter_applied_to_llm_calls(self):
+        """Rate limiter should be applied before LLM calls."""
+        from praisonaiagents import Agent
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        acquire_count = [0]
+        original_acquire = limiter.acquire
+        
+        def counting_acquire():
+            acquire_count[0] += 1
+            return original_acquire()
+        
+        limiter.acquire = counting_acquire
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent",
+            rate_limiter=limiter
+        )
+        
+        with patch.object(agent, '_chat_completion', return_value="mocked"):
+            agent.chat("Hello")
+        
+        # Rate limiter should have been called
+        assert acquire_count[0] >= 1
+
+
+class TestRateLimiterZeroOverhead:
+    """Test that rate limiter has zero overhead when not used."""
+    
+    def test_no_rate_limiter_no_overhead(self):
+        """When no rate limiter, should not add any overhead."""
+        from praisonaiagents import Agent
+        
+        agent = Agent(
+            name="Test",
+            instructions="Test agent"
+            # No rate_limiter
+        )
+        
+        # Should not have rate limiter
+        assert getattr(agent, '_rate_limiter', None) is None
+    
+    def test_rate_limiter_none_check_fast(self):
+        """Checking for None rate limiter should be O(1)."""
+        from praisonaiagents.llm import RateLimiter
+        
+        # This is more of a design requirement than a test
+        # The implementation should do: if self._rate_limiter: self._rate_limiter.acquire()
+
+
+class TestRateLimiterConfiguration:
+    """Test rate limiter configuration options."""
+    
+    def test_rate_limiter_default_burst(self):
+        """RateLimiter should have sensible default burst."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        # Default burst should be 1 or based on rpm
+        assert hasattr(limiter, 'burst') or hasattr(limiter, '_burst')
+    
+    def test_rate_limiter_custom_burst(self):
+        """RateLimiter should accept custom burst parameter."""
+        from praisonaiagents.llm import RateLimiter
+        
+        limiter = RateLimiter(requests_per_minute=60, burst=10)
+        burst = getattr(limiter, 'burst', None) or getattr(limiter, '_burst', None)
+        assert burst == 10
+    
+    def test_rate_limiter_tpm_optional(self):
+        """RateLimiter should optionally accept tokens_per_minute."""
+        from praisonaiagents.llm import RateLimiter
+        
+        # Should not raise
+        limiter = RateLimiter(
+            requests_per_minute=60,
+            tokens_per_minute=100000
+        )
+        assert limiter is not None
+
+
+class TestRateLimiterDeterministic:
+    """Test that rate limiter is deterministic for testing."""
+    
+    def test_injectable_clock(self):
+        """RateLimiter should allow injecting clock for testing."""
+        from praisonaiagents.llm import RateLimiter
+        
+        mock_time = [0.0]
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        limiter._get_time = lambda: mock_time[0]
+        
+        # Should use our mock time
+        t1 = limiter._get_time()
+        mock_time[0] = 100.0
+        t2 = limiter._get_time()
+        
+        assert t1 == 0.0
+        assert t2 == 100.0
+    
+    def test_injectable_sleep(self):
+        """RateLimiter should allow injecting sleep for testing."""
+        from praisonaiagents.llm import RateLimiter
+        
+        sleep_calls = []
+        
+        limiter = RateLimiter(requests_per_minute=60)
+        limiter._sleep = lambda s: sleep_calls.append(s)
+        
+        # Force a wait scenario
+        limiter._get_time = lambda: 0.0
+        limiter._tokens = 0  # No tokens available
+        limiter._last_update = 0.0
+        
+        limiter.acquire()
+        
+        # Should have called our mock sleep
+        # (actual behavior depends on implementation)

src/praisonai-agents/uv.lock

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

src/praisonai/README.md

@@ -261,6 +261,10 @@ npm install praisonai
 | ↳ 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/models) |
 | ↳ Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/features/callbacks) |
 | ↳ Hooks | [Example](#9-hooks) | [📖](https://docs.praison.ai/features/hooks) |
+| ↳ Middleware System | [Example](examples/middleware/basic_middleware.py) | [📖](https://docs.praison.ai/features/middleware) |
+| ↳ Configurable Model | [Example](examples/middleware/configurable_model.py) | [📖](https://docs.praison.ai/features/configurable-model) |
+| ↳ Rate Limiter | [Example](examples/middleware/rate_limiter.py) | [📖](https://docs.praison.ai/features/rate-limiter) |
+| ↳ Injected Tool State | [Example](examples/middleware/injected_state.py) | [📖](https://docs.praison.ai/features/injected-state) |
 | ↳ Shadow Git Checkpoints | [Example](#10-shadow-git-checkpoints) | [📖](https://docs.praison.ai/features/checkpoints) |
 | ↳ Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/features/background-tasks) |
 | ↳ Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/features/policy-engine) |
@@ -2763,11 +2767,11 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | SurrealDB | Conversation | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Qdrant | Knowledge | `pip install "praisonai[tools]"` | [knowledge_qdrant.py](examples/persistence/knowledge_qdrant.py) | [docs](https://docs.praison.ai/docs/databases/qdrant) |
 | ChromaDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Pinecone | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| Weaviate | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| LanceDB | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| Pinecone | Knowledge | `pip install pinecone` | [pinecone_wow.py](examples/vector/pinecone_wow.py) | [docs](https://docs.praison.ai/docs/databases/pinecone) |
+| Weaviate | Knowledge | `pip install weaviate-client` | [weaviate_wow.py](examples/vector/weaviate_wow.py) | [docs](https://docs.praison.ai/docs/databases/weaviate) |
+| LanceDB | Knowledge | `pip install lancedb` | [lancedb_real_wow.py](examples/vector/lancedb_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/lancedb) |
 | Milvus | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
-| PGVector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
+| PGVector | Knowledge | `pip install psycopg2-binary` | [pgvector_real_wow.py](examples/vector/pgvector_real_wow.py) | [docs](https://docs.praison.ai/docs/databases/pgvector) |
 | Redis Vector | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | Cassandra | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |
 | ClickHouse | Knowledge | `pip install "praisonai[tools]"` | - | [docs](https://docs.praison.ai/docs/databases/overview) |

src/praisonai/praisonai.rb

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

src/praisonai/praisonai/cli/features/observability.py

@@ -0,0 +1,293 @@
+"""
+Observability CLI Handler
+
+CLI commands for managing observability providers.
+Usage: praisonai obs <command>
+"""
+
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+from .base import FlagHandler
+
+
+class ObservabilityHandler(FlagHandler):
+    """
+    Handler for observability CLI commands.
+    
+    Commands:
+        praisonai obs list          - List available providers
+        praisonai obs doctor        - Check provider connectivity
+        praisonai obs init <name>   - Initialize a provider
+    """
+    
+    @property
+    def feature_name(self) -> str:
+        return "observability"
+    
+    @property
+    def flag_name(self) -> str:
+        return "obs"
+    
+    @property
+    def flag_help(self) -> str:
+        return "Observability commands (list, doctor, init)"
+    
+    def check_dependencies(self) -> Tuple[bool, str]:
+        """Check if observability module is available."""
+        try:
+            from praisonai_tools.observability import obs
+            return True, ""
+        except ImportError:
+            return False, "Observability requires praisonai-tools. Install with: pip install praisonai-tools"
+    
+    def list_providers(self) -> Dict[str, Any]:
+        """List all available observability providers."""
+        result = {
+            "registered": [],
+            "available": [],
+            "configured": [],
+        }
+        
+        try:
+            from praisonai_tools.observability.manager import ObservabilityManager
+            from praisonai_tools.observability.config import PROVIDER_ENV_KEYS
+            
+            mgr = ObservabilityManager()
+            
+            # Get all registered providers
+            result["registered"] = mgr.list_providers()
+            
+            # Check which have env vars configured
+            for provider, keys in PROVIDER_ENV_KEYS.items():
+                if all(os.getenv(key) for key in keys):
+                    result["configured"].append(provider)
+            
+            # Check which SDKs are available
+            for provider in result["registered"]:
+                try:
+                    mgr._load_provider(provider)
+                    if provider in mgr._providers:
+                        provider_class = mgr._providers[provider]
+                        instance = provider_class()
+                        if instance.is_available():
+                            result["available"].append(provider)
+                except Exception:
+                    pass
+            
+        except ImportError:
+            pass
+        
+        return result
+    
+    def doctor(self, provider: Optional[str] = None) -> Dict[str, Any]:
+        """Run diagnostics on observability setup."""
+        try:
+            from praisonai_tools.observability import obs
+            
+            if provider:
+                obs.init(provider=provider)
+            
+            return obs.doctor()
+            
+        except ImportError:
+            return {
+                "error": "praisonai-tools not installed",
+                "enabled": False,
+            }
+    
+    def init_provider(self, provider: str, **kwargs) -> bool:
+        """Initialize a specific provider."""
+        try:
+            from praisonai_tools.observability import obs
+            return obs.init(provider=provider, **kwargs)
+        except ImportError:
+            return False
+    
+    def execute(self, action: str = "list", **kwargs) -> Any:
+        """
+        Execute observability command.
+        
+        Args:
+            action: Command to execute (list, doctor, init)
+            **kwargs: Additional arguments
+            
+        Returns:
+            Command result
+        """
+        if action == "list":
+            return self._execute_list()
+        elif action == "doctor":
+            return self._execute_doctor(kwargs.get("provider"))
+        elif action == "init":
+            return self._execute_init(kwargs.get("provider"), **kwargs)
+        else:
+            self.print_status(f"Unknown action: {action}", "error")
+            return None
+    
+    def _execute_list(self) -> Dict[str, Any]:
+        """Execute list command."""
+        result = self.list_providers()
+        
+        self.print_status("\n📊 Observability Providers", "info")
+        self.print_status("=" * 40, "info")
+        
+        # Provider status table
+        all_providers = [
+            "agentops", "langfuse", "langsmith", "traceloop",
+            "arize_phoenix", "openlit", "langtrace", "langwatch",
+            "datadog", "mlflow", "opik", "portkey",
+            "braintrust", "maxim", "weave", "neatlogs",
+            "langdb", "atla", "patronus", "truefoundry",
+        ]
+        
+        for provider in all_providers:
+            status_parts = []
+            if provider in result.get("available", []):
+                status_parts.append("✅ SDK")
+            else:
+                status_parts.append("❌ SDK")
+            
+            if provider in result.get("configured", []):
+                status_parts.append("🔑 Keys")
+            else:
+                status_parts.append("⚪ Keys")
+            
+            status = " | ".join(status_parts)
+            self.print_status(f"  {provider:20} {status}", "info")
+        
+        self.print_status("\n✅ = Available  ❌ = Not installed  🔑 = API key configured", "info")
+        
+        return result
+    
+    def _execute_doctor(self, provider: Optional[str] = None) -> Dict[str, Any]:
+        """Execute doctor command."""
+        result = self.doctor(provider)
+        
+        self.print_status("\n🩺 Observability Diagnostics", "info")
+        self.print_status("=" * 40, "info")
+        
+        self.print_status(f"  Enabled: {result.get('enabled', False)}", "info")
+        self.print_status(f"  Provider: {result.get('provider', 'None')}", "info")
+        
+        if result.get("connection_status") is not None:
+            status = "✅" if result["connection_status"] else "❌"
+            self.print_status(f"  Connection: {status} {result.get('connection_message', '')}", "info")
+        
+        if result.get("available_providers"):
+            self.print_status(f"  Available: {', '.join(result['available_providers'])}", "info")
+        
+        return result
+    
+    def _execute_init(self, provider: str, **kwargs) -> bool:
+        """Execute init command."""
+        if not provider:
+            self.print_status("Provider name required. Usage: praisonai obs init <provider>", "error")
+            return False
+        
+        success = self.init_provider(provider, **kwargs)
+        
+        if success:
+            self.print_status(f"✅ {provider} initialized successfully", "success")
+        else:
+            self.print_status(f"❌ Failed to initialize {provider}", "error")
+            self.print_status(f"   Check that {provider} SDK is installed and API keys are set", "info")
+        
+        return success
+    
+    def apply_to_agent_config(self, config: Dict[str, Any], flag_value: Any) -> Dict[str, Any]:
+        """Apply observability to agent config."""
+        if flag_value:
+            try:
+                from praisonai_tools.observability import obs
+                
+                if isinstance(flag_value, str):
+                    obs.init(provider=flag_value)
+                else:
+                    obs.init()
+                
+                self.print_status("📊 Observability enabled", "success")
+            except ImportError:
+                self.print_status("Observability requires praisonai-tools", "warning")
+        
+        return config
+
+
+# Provider environment variable reference
+PROVIDER_SETUP_GUIDE = {
+    "agentops": {
+        "env_vars": ["AGENTOPS_API_KEY"],
+        "install": "pip install agentops",
+        "docs": "https://agentops.ai/",
+    },
+    "langfuse": {
+        "env_vars": ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"],
+        "install": "pip install opentelemetry-sdk opentelemetry-exporter-otlp",
+        "docs": "https://langfuse.com/",
+    },
+    "langsmith": {
+        "env_vars": ["LANGSMITH_API_KEY"],
+        "install": "pip install opentelemetry-sdk opentelemetry-exporter-otlp",
+        "docs": "https://smith.langchain.com/",
+    },
+    "traceloop": {
+        "env_vars": ["TRACELOOP_API_KEY"],
+        "install": "pip install traceloop-sdk",
+        "docs": "https://traceloop.com/",
+    },
+    "arize_phoenix": {
+        "env_vars": ["PHOENIX_API_KEY"],
+        "install": "pip install arize-phoenix openinference-instrumentation",
+        "docs": "https://phoenix.arize.com/",
+    },
+    "openlit": {
+        "env_vars": [],
+        "install": "pip install openlit",
+        "docs": "https://github.com/openlit/openlit",
+    },
+    "langtrace": {
+        "env_vars": ["LANGTRACE_API_KEY"],
+        "install": "pip install langtrace-python-sdk",
+        "docs": "https://langtrace.ai/",
+    },
+    "langwatch": {
+        "env_vars": ["LANGWATCH_API_KEY"],
+        "install": "pip install langwatch",
+        "docs": "https://langwatch.ai/",
+    },
+    "datadog": {
+        "env_vars": ["DD_API_KEY"],
+        "install": "pip install ddtrace",
+        "docs": "https://www.datadoghq.com/product/llm-observability/",
+    },
+    "mlflow": {
+        "env_vars": ["MLFLOW_TRACKING_URI"],
+        "install": "pip install mlflow",
+        "docs": "https://mlflow.org/",
+    },
+    "opik": {
+        "env_vars": ["OPIK_API_KEY"],
+        "install": "pip install opik",
+        "docs": "https://www.comet.com/docs/opik/",
+    },
+    "portkey": {
+        "env_vars": ["PORTKEY_API_KEY"],
+        "install": "pip install portkey-ai",
+        "docs": "https://portkey.ai/",
+    },
+    "braintrust": {
+        "env_vars": ["BRAINTRUST_API_KEY"],
+        "install": "pip install braintrust",
+        "docs": "https://www.braintrust.dev/",
+    },
+    "maxim": {
+        "env_vars": ["MAXIM_API_KEY"],
+        "install": "pip install maxim-py",
+        "docs": "https://getmaxim.ai/",
+    },
+    "weave": {
+        "env_vars": ["WANDB_API_KEY"],
+        "install": "pip install weave",
+        "docs": "https://weave-docs.wandb.ai/",
+    },
+}

src/praisonai/praisonai/cli/features/persistence.py

@@ -290,10 +290,9 @@ def handle_run(args: list) -> bool:
     
     # Run agent with persistence
     try:
-        from praisonai.db import PraisonDB
-        from praisonaiagents import Agent
+        from praisonaiagents import Agent, db
         
-        db = PraisonDB(
+        db_instance = db(
             database_url=config["conversation_url"],
             state_url=config["state_url"],
             knowledge_url=config["knowledge_url"],
@@ -302,7 +301,7 @@ def handle_run(args: list) -> bool:
         agent = Agent(
             name=config["agent_name"],
             instructions=config["agent_instructions"],
-            db=db,
+            db=db_instance,
             session_id=config["session_id"],
             verbose=True
         )
@@ -311,7 +310,7 @@ def handle_run(args: list) -> bool:
         response = agent.chat(config["prompt"])
         print(f"\nAgent: {response}")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")
@@ -334,12 +333,12 @@ def handle_resume(args: list) -> bool:
         return True
     
     try:
-        from praisonai.db import PraisonDB
+        from praisonaiagents import db
         
-        db = PraisonDB(database_url=config["conversation_url"])
+        db_instance = db(database_url=config["conversation_url"])
         
         # Get session history
-        history = db.on_agent_start(
+        history = db_instance.on_agent_start(
             agent_name="Resume",
             session_id=config["session_id"],
             user_id=config["user_id"]
@@ -362,7 +361,7 @@ def handle_resume(args: list) -> bool:
             agent = Agent(
                 name=config["agent_name"],
                 instructions=config["agent_instructions"],
-                db=db,
+                db=db_instance,
                 session_id=config["session_id"],
                 verbose=True
             )
@@ -370,7 +369,7 @@ def handle_resume(args: list) -> bool:
             response = agent.chat(config["continue_prompt"])
             print(f"\nAgent: {response}")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")
@@ -392,17 +391,17 @@ def handle_export(args: list) -> bool:
         return True
     
     try:
-        from praisonai.db import PraisonDB
+        from praisonaiagents import db
         import json
         
-        db = PraisonDB(database_url=config["conversation_url"])
+        db_instance = db(database_url=config["conversation_url"])
         
         # Export session
-        data = db.export_session(config["session_id"])
+        data = db_instance.export_session(config["session_id"])
         
         if not data:
             print(f"Error: Session {config['session_id']} not found")
-            db.close()
+            db_instance.close()
             return True
         
         # Determine output file
@@ -414,7 +413,7 @@ def handle_export(args: list) -> bool:
         print(f"Exported session to: {output_file}")
         print(f"Messages: {len(data.get('messages', []))}")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")
@@ -437,20 +436,20 @@ def handle_import(args: list) -> bool:
         return True
     
     try:
-        from praisonai.db import PraisonDB
+        from praisonaiagents import db
         import json
         
-        db = PraisonDB(database_url=config["conversation_url"])
+        db_instance = db(database_url=config["conversation_url"])
         
         with open(input_file, 'r') as f:
             data = json.loads(f.readline())
         
-        session_id = db.import_session(data)
+        session_id = db_instance.import_session(data)
         
         print(f"Imported session: {session_id}")
         print(f"Messages: {len(data.get('messages', []))}")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")
@@ -469,15 +468,15 @@ def handle_migrate(args: list) -> bool:
         return True
     
     try:
-        from praisonai.db import PraisonDB
+        from praisonaiagents import db
         from praisonai.persistence.migrations import MigrationManager
         
-        db = PraisonDB(
+        db_instance = db(
             database_url=config["conversation_url"],
             state_url=config["state_url"]
         )
         
-        manager = MigrationManager(db)
+        manager = MigrationManager(db_instance)
         
         # Check for --up or --down flags
         direction = "up"
@@ -506,7 +505,7 @@ def handle_migrate(args: list) -> bool:
             else:
                 print("No migrations to rollback")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")
@@ -524,15 +523,15 @@ def handle_status(args: list) -> bool:
         return True
     
     try:
-        from praisonai.db import PraisonDB
+        from praisonaiagents import db
         from praisonai.persistence.migrations import MigrationManager
         
-        db = PraisonDB(
+        db_instance = db(
             database_url=config["conversation_url"],
             state_url=config["state_url"]
         )
         
-        manager = MigrationManager(db)
+        manager = MigrationManager(db_instance)
         status = manager.get_migration_status()
         
         print("\n=== Schema Status ===")
@@ -543,7 +542,7 @@ def handle_status(args: list) -> bool:
         if status['pending_versions']:
             print(f"Pending versions: {', '.join(status['pending_versions'])}")
         
-        db.close()
+        db_instance.close()
         
     except Exception as e:
         print(f"Error: {e}")

src/praisonai/praisonai/cli/main.py

@@ -813,6 +813,15 @@ class PraisonAI:
         parser.add_argument('--max-cost', type=float, help='Maximum total cost budget in USD')
         parser.add_argument('--daemon', action='store_true', help=argparse.SUPPRESS)  # Hidden flag for daemon mode
         
+        # Rate Limiter - control API request rate
+        parser.add_argument("--rpm", type=int, help="Rate limit: requests per minute for LLM calls")
+        parser.add_argument("--tpm", type=int, help="Rate limit: tokens per minute for LLM calls (optional)")
+        
+        # Configurable Model - runtime model switching
+        parser.add_argument("--configurable-model", action="store_true", help="Enable runtime model switching via config parameter")
+        parser.add_argument("--temperature", type=float, help="Override temperature for LLM calls")
+        parser.add_argument("--llm-provider", type=str, help="Override LLM provider (openai, anthropic, google, etc.)")
+        
         # If we're in a test environment, parse with empty args to avoid pytest interference
         if in_test_env:
             args, unknown_args = parser.parse_known_args([])

src/praisonai/praisonai/deploy.py

@@ -57,7 +57,7 @@ class CloudDeployer:
             file.write("FROM python:3.11-slim\n")
             file.write("WORKDIR /app\n")
             file.write("COPY . .\n")
-            file.write("RUN pip install flask praisonai==2.4.2 gunicorn markdown\n")
+            file.write("RUN pip install flask praisonai==2.5.0 gunicorn markdown\n")
             file.write("EXPOSE 8080\n")
             file.write('CMD ["gunicorn", "-b", "0.0.0.0:8080", "api:app"]\n')
             

src/praisonai/praisonai/persistence/conversation/async_mysql.py

@@ -0,0 +1,427 @@
+"""
+Async MySQL implementation of ConversationStore.
+
+Requires: aiomysql
+Install: pip install aiomysql
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import List, Optional
+
+from .base import ConversationStore, ConversationSession, ConversationMessage
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncMySQLConversationStore(ConversationStore):
+    """
+    Async MySQL conversation store using aiomysql.
+    
+    Provides high-performance async database operations.
+    
+    Example:
+        store = AsyncMySQLConversationStore(
+            host="localhost",
+            user="root",
+            password="password",
+            database="praisonai"
+        )
+        await store.init()
+    """
+    
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        host: str = "localhost",
+        port: int = 3306,
+        database: str = "praisonai",
+        user: str = "root",
+        password: str = "",
+        table_prefix: str = "praisonai_",
+        pool_size: int = 10,
+    ):
+        """
+        Initialize async MySQL store.
+        
+        Args:
+            url: MySQL connection URL (takes precedence)
+            host: Database host
+            port: Database port
+            database: Database name
+            user: Database user
+            password: Database password
+            table_prefix: Prefix for table names
+            pool_size: Connection pool size
+        """
+        self.url = url
+        self.host = host
+        self.port = port
+        self.database = database
+        self.user = user
+        self.password = password
+        self.table_prefix = table_prefix
+        self.pool_size = pool_size
+        self._pool = None
+        self._initialized = False
+        
+        if url:
+            self._parse_url(url)
+    
+    def _parse_url(self, url: str):
+        """Parse MySQL URL into components."""
+        from urllib.parse import urlparse
+        parsed = urlparse(url)
+        self.host = parsed.hostname or "localhost"
+        self.port = parsed.port or 3306
+        self.database = parsed.path.lstrip('/') or "praisonai"
+        self.user = parsed.username or "root"
+        self.password = parsed.password or ""
+    
+    async def init(self):
+        """Initialize connection pool and create tables."""
+        if self._initialized:
+            return
+        
+        try:
+            import aiomysql
+        except ImportError:
+            raise ImportError(
+                "aiomysql is required for async MySQL support. "
+                "Install with: pip install aiomysql"
+            )
+        
+        self._pool = await aiomysql.create_pool(
+            host=self.host,
+            port=self.port,
+            user=self.user,
+            password=self.password,
+            db=self.database,
+            minsize=1,
+            maxsize=self.pool_size,
+            autocommit=True
+        )
+        
+        await self._create_tables()
+        self._initialized = True
+    
+    async def _create_tables(self):
+        """Create required tables if they don't exist."""
+        sessions_table = f"{self.table_prefix}sessions"
+        messages_table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    CREATE TABLE IF NOT EXISTS {sessions_table} (
+                        session_id VARCHAR(255) PRIMARY KEY,
+                        user_id VARCHAR(255),
+                        agent_id VARCHAR(255),
+                        name VARCHAR(255),
+                        metadata JSON,
+                        created_at DOUBLE,
+                        updated_at DOUBLE,
+                        INDEX idx_user_id (user_id),
+                        INDEX idx_agent_id (agent_id)
+                    )
+                """)
+                
+                await cur.execute(f"""
+                    CREATE TABLE IF NOT EXISTS {messages_table} (
+                        id VARCHAR(255) PRIMARY KEY,
+                        session_id VARCHAR(255),
+                        role VARCHAR(50),
+                        content TEXT,
+                        metadata JSON,
+                        created_at DOUBLE,
+                        INDEX idx_session_id (session_id),
+                        FOREIGN KEY (session_id) REFERENCES {sessions_table}(session_id) ON DELETE CASCADE
+                    )
+                """)
+    
+    async def async_create_session(self, session: ConversationSession) -> ConversationSession:
+        """Create a new session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    INSERT INTO {table} (session_id, user_id, agent_id, name, metadata, created_at, updated_at)
+                    VALUES (%s, %s, %s, %s, %s, %s, %s)
+                """, (session.session_id, session.user_id, session.agent_id, session.name,
+                      json.dumps(session.metadata) if session.metadata else None,
+                      session.created_at, session.updated_at))
+        
+        return session
+    
+    def create_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for create_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_create_session(session)
+        )
+    
+    async def async_get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Get a session by ID asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    SELECT session_id, user_id, agent_id, name, metadata, created_at, updated_at
+                    FROM {table} WHERE session_id = %s
+                """, (session_id,))
+                row = await cur.fetchone()
+        
+        if row:
+            return ConversationSession(
+                session_id=row[0],
+                user_id=row[1],
+                agent_id=row[2],
+                name=row[3],
+                metadata=json.loads(row[4]) if row[4] else None,
+                created_at=row[5],
+                updated_at=row[6]
+            )
+        return None
+    
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Sync wrapper for get_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_session(session_id)
+        )
+    
+    async def async_update_session(self, session: ConversationSession) -> ConversationSession:
+        """Update an existing session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        session.updated_at = time.time()
+        table = f"{self.table_prefix}sessions"
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    UPDATE {table} 
+                    SET name = %s, metadata = %s, updated_at = %s
+                    WHERE session_id = %s
+                """, (session.name, json.dumps(session.metadata) if session.metadata else None,
+                      session.updated_at, session.session_id))
+        
+        return session
+    
+    def update_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for update_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_update_session(session)
+        )
+    
+    async def async_delete_session(self, session_id: str) -> bool:
+        """Delete a session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    DELETE FROM {table} WHERE session_id = %s
+                """, (session_id,))
+                return cur.rowcount > 0
+    
+    def delete_session(self, session_id: str) -> bool:
+        """Sync wrapper for delete_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_session(session_id)
+        )
+    
+    async def async_list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """List sessions asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        conditions = []
+        params = []
+        
+        if user_id:
+            conditions.append("user_id = %s")
+            params.append(user_id)
+        
+        if agent_id:
+            conditions.append("agent_id = %s")
+            params.append(agent_id)
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        params.extend([limit, offset])
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    SELECT session_id, user_id, agent_id, name, metadata, created_at, updated_at
+                    FROM {table} {where_clause}
+                    ORDER BY updated_at DESC
+                    LIMIT %s OFFSET %s
+                """, params)
+                rows = await cur.fetchall()
+        
+        return [
+            ConversationSession(
+                session_id=row[0],
+                user_id=row[1],
+                agent_id=row[2],
+                name=row[3],
+                metadata=json.loads(row[4]) if row[4] else None,
+                created_at=row[5],
+                updated_at=row[6]
+            )
+            for row in rows
+        ]
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """Sync wrapper for list_sessions."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_list_sessions(user_id, agent_id, limit, offset)
+        )
+    
+    async def async_add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Add a message asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        message.session_id = session_id
+        table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    INSERT INTO {table} (id, session_id, role, content, metadata, created_at)
+                    VALUES (%s, %s, %s, %s, %s, %s)
+                """, (message.id, session_id, message.role, message.content,
+                      json.dumps(message.metadata) if message.metadata else None,
+                      message.created_at))
+        
+        return message
+    
+    def add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Sync wrapper for add_message."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_add_message(session_id, message)
+        )
+    
+    async def async_get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Get messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        conditions = ["session_id = %s"]
+        params = [session_id]
+        
+        if before:
+            conditions.append("created_at < %s")
+            params.append(before)
+        
+        if after:
+            conditions.append("created_at > %s")
+            params.append(after)
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}"
+        limit_clause = "LIMIT %s" if limit else ""
+        if limit:
+            params.append(limit)
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(f"""
+                    SELECT id, session_id, role, content, metadata, created_at
+                    FROM {table} {where_clause}
+                    ORDER BY created_at ASC {limit_clause}
+                """, params)
+                rows = await cur.fetchall()
+        
+        return [
+            ConversationMessage(
+                id=row[0],
+                session_id=row[1],
+                role=row[2],
+                content=row[3],
+                metadata=json.loads(row[4]) if row[4] else None,
+                created_at=row[5]
+            )
+            for row in rows
+        ]
+    
+    def get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Sync wrapper for get_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_messages(session_id, limit, before, after)
+        )
+    
+    async def async_delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Delete messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            async with conn.cursor() as cur:
+                if message_ids is None:
+                    await cur.execute(f"""
+                        DELETE FROM {table} WHERE session_id = %s
+                    """, (session_id,))
+                else:
+                    placeholders = ','.join(['%s'] * len(message_ids))
+                    await cur.execute(f"""
+                        DELETE FROM {table} WHERE session_id = %s AND id IN ({placeholders})
+                    """, [session_id] + message_ids)
+                return cur.rowcount
+    
+    def delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Sync wrapper for delete_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_messages(session_id, message_ids)
+        )
+    
+    async def async_close(self) -> None:
+        """Close the connection pool."""
+        if self._pool:
+            self._pool.close()
+            await self._pool.wait_closed()
+            self._pool = None
+            self._initialized = False
+    
+    def close(self) -> None:
+        """Sync wrapper for close."""
+        if self._pool:
+            asyncio.get_event_loop().run_until_complete(self.async_close())

src/praisonai/praisonai/persistence/conversation/async_postgres.py

@@ -0,0 +1,410 @@
+"""
+Async PostgreSQL implementation of ConversationStore.
+
+Requires: asyncpg
+Install: pip install asyncpg
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import List, Optional
+
+from .base import ConversationStore, ConversationSession, ConversationMessage
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncPostgresConversationStore(ConversationStore):
+    """
+    Async PostgreSQL conversation store using asyncpg.
+    
+    Provides high-performance async database operations.
+    
+    Example:
+        store = AsyncPostgresConversationStore(
+            url="postgresql://user:pass@localhost:5432/praisonai"
+        )
+        await store.init()
+    """
+    
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        host: str = "localhost",
+        port: int = 5432,
+        database: str = "praisonai",
+        user: str = "postgres",
+        password: str = "",
+        table_prefix: str = "praisonai_",
+        pool_size: int = 10,
+    ):
+        """
+        Initialize async PostgreSQL store.
+        
+        Args:
+            url: PostgreSQL connection URL (takes precedence)
+            host: Database host
+            port: Database port
+            database: Database name
+            user: Database user
+            password: Database password
+            table_prefix: Prefix for table names
+            pool_size: Connection pool size
+        """
+        self.url = url
+        self.host = host
+        self.port = port
+        self.database = database
+        self.user = user
+        self.password = password
+        self.table_prefix = table_prefix
+        self.pool_size = pool_size
+        self._pool = None
+        self._initialized = False
+    
+    async def init(self):
+        """Initialize connection pool and create tables."""
+        if self._initialized:
+            return
+        
+        try:
+            import asyncpg
+        except ImportError:
+            raise ImportError(
+                "asyncpg is required for async PostgreSQL support. "
+                "Install with: pip install asyncpg"
+            )
+        
+        if self.url:
+            self._pool = await asyncpg.create_pool(self.url, min_size=1, max_size=self.pool_size)
+        else:
+            self._pool = await asyncpg.create_pool(
+                host=self.host,
+                port=self.port,
+                database=self.database,
+                user=self.user,
+                password=self.password,
+                min_size=1,
+                max_size=self.pool_size
+            )
+        
+        await self._create_tables()
+        self._initialized = True
+    
+    async def _create_tables(self):
+        """Create required tables if they don't exist."""
+        sessions_table = f"{self.table_prefix}sessions"
+        messages_table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            await conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {sessions_table} (
+                    session_id VARCHAR(255) PRIMARY KEY,
+                    user_id VARCHAR(255),
+                    agent_id VARCHAR(255),
+                    name VARCHAR(255),
+                    metadata JSONB,
+                    created_at DOUBLE PRECISION,
+                    updated_at DOUBLE PRECISION
+                )
+            """)
+            
+            await conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {messages_table} (
+                    id VARCHAR(255) PRIMARY KEY,
+                    session_id VARCHAR(255) REFERENCES {sessions_table}(session_id) ON DELETE CASCADE,
+                    role VARCHAR(50),
+                    content TEXT,
+                    metadata JSONB,
+                    created_at DOUBLE PRECISION
+                )
+            """)
+            
+            await conn.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_{messages_table}_session 
+                ON {messages_table}(session_id)
+            """)
+    
+    async def async_create_session(self, session: ConversationSession) -> ConversationSession:
+        """Create a new session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            await conn.execute(f"""
+                INSERT INTO {table} (session_id, user_id, agent_id, name, metadata, created_at, updated_at)
+                VALUES ($1, $2, $3, $4, $5, $6, $7)
+            """, session.session_id, session.user_id, session.agent_id, session.name,
+                json.dumps(session.metadata) if session.metadata else None,
+                session.created_at, session.updated_at)
+        
+        return session
+    
+    def create_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for create_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_create_session(session)
+        )
+    
+    async def async_get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Get a session by ID asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(f"""
+                SELECT * FROM {table} WHERE session_id = $1
+            """, session_id)
+        
+        if row:
+            return ConversationSession(
+                session_id=row['session_id'],
+                user_id=row['user_id'],
+                agent_id=row['agent_id'],
+                name=row['name'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at'],
+                updated_at=row['updated_at']
+            )
+        return None
+    
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Sync wrapper for get_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_session(session_id)
+        )
+    
+    async def async_update_session(self, session: ConversationSession) -> ConversationSession:
+        """Update an existing session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        session.updated_at = time.time()
+        table = f"{self.table_prefix}sessions"
+        
+        async with self._pool.acquire() as conn:
+            await conn.execute(f"""
+                UPDATE {table} 
+                SET name = $2, metadata = $3, updated_at = $4
+                WHERE session_id = $1
+            """, session.session_id, session.name,
+                json.dumps(session.metadata) if session.metadata else None,
+                session.updated_at)
+        
+        return session
+    
+    def update_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for update_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_update_session(session)
+        )
+    
+    async def async_delete_session(self, session_id: str) -> bool:
+        """Delete a session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._pool.acquire() as conn:
+            result = await conn.execute(f"""
+                DELETE FROM {table} WHERE session_id = $1
+            """, session_id)
+        
+        return "DELETE 1" in result
+    
+    def delete_session(self, session_id: str) -> bool:
+        """Sync wrapper for delete_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_session(session_id)
+        )
+    
+    async def async_list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """List sessions asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        conditions = []
+        params = []
+        param_idx = 1
+        
+        if user_id:
+            conditions.append(f"user_id = ${param_idx}")
+            params.append(user_id)
+            param_idx += 1
+        
+        if agent_id:
+            conditions.append(f"agent_id = ${param_idx}")
+            params.append(agent_id)
+            param_idx += 1
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        params.extend([limit, offset])
+        
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(f"""
+                SELECT * FROM {table} {where_clause}
+                ORDER BY updated_at DESC
+                LIMIT ${param_idx} OFFSET ${param_idx + 1}
+            """, *params)
+        
+        return [
+            ConversationSession(
+                session_id=row['session_id'],
+                user_id=row['user_id'],
+                agent_id=row['agent_id'],
+                name=row['name'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at'],
+                updated_at=row['updated_at']
+            )
+            for row in rows
+        ]
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """Sync wrapper for list_sessions."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_list_sessions(user_id, agent_id, limit, offset)
+        )
+    
+    async def async_add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Add a message asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        message.session_id = session_id
+        table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            await conn.execute(f"""
+                INSERT INTO {table} (id, session_id, role, content, metadata, created_at)
+                VALUES ($1, $2, $3, $4, $5, $6)
+            """, message.id, session_id, message.role, message.content,
+                json.dumps(message.metadata) if message.metadata else None,
+                message.created_at)
+        
+        return message
+    
+    def add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Sync wrapper for add_message."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_add_message(session_id, message)
+        )
+    
+    async def async_get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Get messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        conditions = ["session_id = $1"]
+        params = [session_id]
+        param_idx = 2
+        
+        if before:
+            conditions.append(f"created_at < ${param_idx}")
+            params.append(before)
+            param_idx += 1
+        
+        if after:
+            conditions.append(f"created_at > ${param_idx}")
+            params.append(after)
+            param_idx += 1
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}"
+        limit_clause = f"LIMIT ${param_idx}" if limit else ""
+        if limit:
+            params.append(limit)
+        
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(f"""
+                SELECT * FROM {table} {where_clause}
+                ORDER BY created_at ASC {limit_clause}
+            """, *params)
+        
+        return [
+            ConversationMessage(
+                id=row['id'],
+                session_id=row['session_id'],
+                role=row['role'],
+                content=row['content'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at']
+            )
+            for row in rows
+        ]
+    
+    def get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Sync wrapper for get_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_messages(session_id, limit, before, after)
+        )
+    
+    async def async_delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Delete messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        
+        async with self._pool.acquire() as conn:
+            if message_ids is None:
+                result = await conn.execute(f"""
+                    DELETE FROM {table} WHERE session_id = $1
+                """, session_id)
+            else:
+                result = await conn.execute(f"""
+                    DELETE FROM {table} WHERE session_id = $1 AND id = ANY($2)
+                """, session_id, message_ids)
+        
+        # Parse count from result like "DELETE 5"
+        try:
+            return int(result.split()[-1])
+        except (ValueError, IndexError):
+            return 0
+    
+    def delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Sync wrapper for delete_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_messages(session_id, message_ids)
+        )
+    
+    async def async_close(self) -> None:
+        """Close the connection pool."""
+        if self._pool:
+            await self._pool.close()
+            self._pool = None
+            self._initialized = False
+    
+    def close(self) -> None:
+        """Sync wrapper for close."""
+        if self._pool:
+            asyncio.get_event_loop().run_until_complete(self.async_close())

src/praisonai/praisonai/persistence/conversation/async_sqlite.py

@@ -0,0 +1,371 @@
+"""
+Async SQLite implementation of ConversationStore.
+
+Requires: aiosqlite
+Install: pip install aiosqlite
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import List, Optional
+
+from .base import ConversationStore, ConversationSession, ConversationMessage
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncSQLiteConversationStore(ConversationStore):
+    """
+    Async SQLite conversation store using aiosqlite.
+    
+    Provides async database operations for SQLite.
+    
+    Example:
+        store = AsyncSQLiteConversationStore(path="./conversations.db")
+        await store.init()
+    """
+    
+    def __init__(
+        self,
+        path: str = "praisonai_conversations.db",
+        table_prefix: str = "praisonai_",
+    ):
+        """
+        Initialize async SQLite store.
+        
+        Args:
+            path: Path to SQLite database file
+            table_prefix: Prefix for table names
+        """
+        self.path = path
+        self.table_prefix = table_prefix
+        self._conn = None
+        self._initialized = False
+    
+    async def init(self):
+        """Initialize connection and create tables."""
+        if self._initialized:
+            return
+        
+        try:
+            import aiosqlite
+        except ImportError:
+            raise ImportError(
+                "aiosqlite is required for async SQLite support. "
+                "Install with: pip install aiosqlite"
+            )
+        
+        self._aiosqlite = aiosqlite
+        self._conn = await aiosqlite.connect(self.path)
+        self._conn.row_factory = aiosqlite.Row
+        await self._create_tables()
+        self._initialized = True
+    
+    async def _create_tables(self):
+        """Create required tables if they don't exist."""
+        sessions_table = f"{self.table_prefix}sessions"
+        messages_table = f"{self.table_prefix}messages"
+        
+        await self._conn.execute(f"""
+            CREATE TABLE IF NOT EXISTS {sessions_table} (
+                session_id TEXT PRIMARY KEY,
+                user_id TEXT,
+                agent_id TEXT,
+                name TEXT,
+                metadata TEXT,
+                created_at REAL,
+                updated_at REAL
+            )
+        """)
+        
+        await self._conn.execute(f"""
+            CREATE TABLE IF NOT EXISTS {messages_table} (
+                id TEXT PRIMARY KEY,
+                session_id TEXT REFERENCES {sessions_table}(session_id) ON DELETE CASCADE,
+                role TEXT,
+                content TEXT,
+                metadata TEXT,
+                created_at REAL
+            )
+        """)
+        
+        await self._conn.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_{messages_table}_session 
+            ON {messages_table}(session_id)
+        """)
+        
+        await self._conn.commit()
+    
+    async def async_create_session(self, session: ConversationSession) -> ConversationSession:
+        """Create a new session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        await self._conn.execute(f"""
+            INSERT INTO {table} (session_id, user_id, agent_id, name, metadata, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (session.session_id, session.user_id, session.agent_id, session.name,
+              json.dumps(session.metadata) if session.metadata else None,
+              session.created_at, session.updated_at))
+        await self._conn.commit()
+        
+        return session
+    
+    def create_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for create_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_create_session(session)
+        )
+    
+    async def async_get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Get a session by ID asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        async with self._conn.execute(f"""
+            SELECT * FROM {table} WHERE session_id = ?
+        """, (session_id,)) as cursor:
+            row = await cursor.fetchone()
+        
+        if row:
+            return ConversationSession(
+                session_id=row['session_id'],
+                user_id=row['user_id'],
+                agent_id=row['agent_id'],
+                name=row['name'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at'],
+                updated_at=row['updated_at']
+            )
+        return None
+    
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Sync wrapper for get_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_session(session_id)
+        )
+    
+    async def async_update_session(self, session: ConversationSession) -> ConversationSession:
+        """Update an existing session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        session.updated_at = time.time()
+        table = f"{self.table_prefix}sessions"
+        
+        await self._conn.execute(f"""
+            UPDATE {table} 
+            SET name = ?, metadata = ?, updated_at = ?
+            WHERE session_id = ?
+        """, (session.name, json.dumps(session.metadata) if session.metadata else None,
+              session.updated_at, session.session_id))
+        await self._conn.commit()
+        
+        return session
+    
+    def update_session(self, session: ConversationSession) -> ConversationSession:
+        """Sync wrapper for update_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_update_session(session)
+        )
+    
+    async def async_delete_session(self, session_id: str) -> bool:
+        """Delete a session asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        cursor = await self._conn.execute(f"""
+            DELETE FROM {table} WHERE session_id = ?
+        """, (session_id,))
+        await self._conn.commit()
+        
+        return cursor.rowcount > 0
+    
+    def delete_session(self, session_id: str) -> bool:
+        """Sync wrapper for delete_session."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_session(session_id)
+        )
+    
+    async def async_list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """List sessions asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}sessions"
+        conditions = []
+        params = []
+        
+        if user_id:
+            conditions.append("user_id = ?")
+            params.append(user_id)
+        
+        if agent_id:
+            conditions.append("agent_id = ?")
+            params.append(agent_id)
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        params.extend([limit, offset])
+        
+        async with self._conn.execute(f"""
+            SELECT * FROM {table} {where_clause}
+            ORDER BY updated_at DESC
+            LIMIT ? OFFSET ?
+        """, params) as cursor:
+            rows = await cursor.fetchall()
+        
+        return [
+            ConversationSession(
+                session_id=row['session_id'],
+                user_id=row['user_id'],
+                agent_id=row['agent_id'],
+                name=row['name'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at'],
+                updated_at=row['updated_at']
+            )
+            for row in rows
+        ]
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """Sync wrapper for list_sessions."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_list_sessions(user_id, agent_id, limit, offset)
+        )
+    
+    async def async_add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Add a message asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        message.session_id = session_id
+        table = f"{self.table_prefix}messages"
+        
+        await self._conn.execute(f"""
+            INSERT INTO {table} (id, session_id, role, content, metadata, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """, (message.id, session_id, message.role, message.content,
+              json.dumps(message.metadata) if message.metadata else None,
+              message.created_at))
+        await self._conn.commit()
+        
+        return message
+    
+    def add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Sync wrapper for add_message."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_add_message(session_id, message)
+        )
+    
+    async def async_get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Get messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        conditions = ["session_id = ?"]
+        params = [session_id]
+        
+        if before:
+            conditions.append("created_at < ?")
+            params.append(before)
+        
+        if after:
+            conditions.append("created_at > ?")
+            params.append(after)
+        
+        where_clause = f"WHERE {' AND '.join(conditions)}"
+        limit_clause = f"LIMIT ?" if limit else ""
+        if limit:
+            params.append(limit)
+        
+        async with self._conn.execute(f"""
+            SELECT * FROM {table} {where_clause}
+            ORDER BY created_at ASC {limit_clause}
+        """, params) as cursor:
+            rows = await cursor.fetchall()
+        
+        return [
+            ConversationMessage(
+                id=row['id'],
+                session_id=row['session_id'],
+                role=row['role'],
+                content=row['content'],
+                metadata=json.loads(row['metadata']) if row['metadata'] else None,
+                created_at=row['created_at']
+            )
+            for row in rows
+        ]
+    
+    def get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Sync wrapper for get_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_get_messages(session_id, limit, before, after)
+        )
+    
+    async def async_delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Delete messages asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        table = f"{self.table_prefix}messages"
+        
+        if message_ids is None:
+            cursor = await self._conn.execute(f"""
+                DELETE FROM {table} WHERE session_id = ?
+            """, (session_id,))
+        else:
+            placeholders = ','.join(['?' for _ in message_ids])
+            cursor = await self._conn.execute(f"""
+                DELETE FROM {table} WHERE session_id = ? AND id IN ({placeholders})
+            """, [session_id] + message_ids)
+        
+        await self._conn.commit()
+        return cursor.rowcount
+    
+    def delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Sync wrapper for delete_messages."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.async_delete_messages(session_id, message_ids)
+        )
+    
+    async def async_close(self) -> None:
+        """Close the connection."""
+        if self._conn:
+            await self._conn.close()
+            self._conn = None
+            self._initialized = False
+    
+    def close(self) -> None:
+        """Sync wrapper for close."""
+        if self._conn:
+            asyncio.get_event_loop().run_until_complete(self.async_close())

src/praisonai/praisonai/persistence/conversation/json_store.py

@@ -0,0 +1,250 @@
+"""
+JSON file-based implementation of ConversationStore.
+
+Simple file-based storage for development and testing.
+No external dependencies required.
+"""
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+import threading
+
+from .base import ConversationStore, ConversationSession, ConversationMessage
+
+logger = logging.getLogger(__name__)
+
+
+class JSONConversationStore(ConversationStore):
+    """
+    JSON file-based conversation store.
+    
+    Stores sessions and messages in JSON files.
+    Suitable for development, testing, and small-scale deployments.
+    
+    Example:
+        store = JSONConversationStore(path="./data/conversations")
+    """
+    
+    def __init__(
+        self,
+        path: str = "./praisonai_conversations",
+        pretty: bool = True,
+    ):
+        """
+        Initialize JSON conversation store.
+        
+        Args:
+            path: Directory path for JSON files
+            pretty: Use pretty-printed JSON (default: True)
+        """
+        self.path = Path(path)
+        self.pretty = pretty
+        self._lock = threading.Lock()
+        
+        # Create directory if it doesn't exist
+        self.path.mkdir(parents=True, exist_ok=True)
+        
+        # Sessions index file
+        self._index_file = self.path / "_sessions_index.json"
+        self._load_index()
+    
+    def _load_index(self):
+        """Load or create sessions index."""
+        if self._index_file.exists():
+            with open(self._index_file, 'r') as f:
+                self._index = json.load(f)
+        else:
+            self._index = {"sessions": {}}
+            self._save_index()
+    
+    def _save_index(self):
+        """Save sessions index."""
+        with open(self._index_file, 'w') as f:
+            if self.pretty:
+                json.dump(self._index, f, indent=2, default=str)
+            else:
+                json.dump(self._index, f, default=str)
+    
+    def _session_file(self, session_id: str) -> Path:
+        """Get path to session file."""
+        return self.path / f"{session_id}.json"
+    
+    def _load_session_data(self, session_id: str) -> Optional[Dict]:
+        """Load session data from file."""
+        file_path = self._session_file(session_id)
+        if file_path.exists():
+            with open(file_path, 'r') as f:
+                return json.load(f)
+        return None
+    
+    def _save_session_data(self, session_id: str, data: Dict):
+        """Save session data to file."""
+        file_path = self._session_file(session_id)
+        with open(file_path, 'w') as f:
+            if self.pretty:
+                json.dump(data, f, indent=2, default=str)
+            else:
+                json.dump(data, f, default=str)
+    
+    def create_session(self, session: ConversationSession) -> ConversationSession:
+        """Create a new session."""
+        with self._lock:
+            data = {
+                "session": session.to_dict(),
+                "messages": []
+            }
+            self._save_session_data(session.session_id, data)
+            
+            # Update index
+            self._index["sessions"][session.session_id] = {
+                "user_id": session.user_id,
+                "agent_id": session.agent_id,
+                "name": session.name,
+                "created_at": session.created_at,
+                "updated_at": session.updated_at,
+            }
+            self._save_index()
+            
+            return session
+    
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Get a session by ID."""
+        data = self._load_session_data(session_id)
+        if data and "session" in data:
+            return ConversationSession.from_dict(data["session"])
+        return None
+    
+    def update_session(self, session: ConversationSession) -> ConversationSession:
+        """Update an existing session."""
+        with self._lock:
+            data = self._load_session_data(session.session_id)
+            if not data:
+                raise ValueError(f"Session {session.session_id} not found")
+            
+            session.updated_at = time.time()
+            data["session"] = session.to_dict()
+            self._save_session_data(session.session_id, data)
+            
+            # Update index
+            self._index["sessions"][session.session_id].update({
+                "name": session.name,
+                "updated_at": session.updated_at,
+            })
+            self._save_index()
+            
+            return session
+    
+    def delete_session(self, session_id: str) -> bool:
+        """Delete a session and all its messages."""
+        with self._lock:
+            file_path = self._session_file(session_id)
+            if file_path.exists():
+                file_path.unlink()
+                
+                # Update index
+                if session_id in self._index["sessions"]:
+                    del self._index["sessions"][session_id]
+                    self._save_index()
+                
+                return True
+            return False
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> List[ConversationSession]:
+        """List sessions, optionally filtered by user or agent."""
+        sessions = []
+        
+        for sid, info in self._index["sessions"].items():
+            if user_id and info.get("user_id") != user_id:
+                continue
+            if agent_id and info.get("agent_id") != agent_id:
+                continue
+            
+            session = self.get_session(sid)
+            if session:
+                sessions.append(session)
+        
+        # Sort by updated_at descending
+        sessions.sort(key=lambda s: s.updated_at, reverse=True)
+        
+        return sessions[offset:offset + limit]
+    
+    def add_message(self, session_id: str, message: ConversationMessage) -> ConversationMessage:
+        """Add a message to a session."""
+        with self._lock:
+            data = self._load_session_data(session_id)
+            if not data:
+                raise ValueError(f"Session {session_id} not found")
+            
+            message.session_id = session_id
+            data["messages"].append(message.to_dict())
+            
+            # Update session timestamp
+            data["session"]["updated_at"] = time.time()
+            
+            self._save_session_data(session_id, data)
+            
+            # Update index
+            if session_id in self._index["sessions"]:
+                self._index["sessions"][session_id]["updated_at"] = time.time()
+                self._save_index()
+            
+            return message
+    
+    def get_messages(
+        self,
+        session_id: str,
+        limit: Optional[int] = None,
+        before: Optional[float] = None,
+        after: Optional[float] = None
+    ) -> List[ConversationMessage]:
+        """Get messages from a session."""
+        data = self._load_session_data(session_id)
+        if not data:
+            return []
+        
+        messages = [ConversationMessage.from_dict(m) for m in data.get("messages", [])]
+        
+        # Apply filters
+        if before:
+            messages = [m for m in messages if m.created_at < before]
+        if after:
+            messages = [m for m in messages if m.created_at > after]
+        
+        # Sort by created_at
+        messages.sort(key=lambda m: m.created_at)
+        
+        if limit:
+            messages = messages[-limit:]
+        
+        return messages
+    
+    def delete_messages(self, session_id: str, message_ids: Optional[List[str]] = None) -> int:
+        """Delete messages. If message_ids is None, delete all messages in session."""
+        with self._lock:
+            data = self._load_session_data(session_id)
+            if not data:
+                return 0
+            
+            if message_ids is None:
+                count = len(data["messages"])
+                data["messages"] = []
+            else:
+                original_count = len(data["messages"])
+                data["messages"] = [m for m in data["messages"] if m.get("id") not in message_ids]
+                count = original_count - len(data["messages"])
+            
+            self._save_session_data(session_id, data)
+            return count
+    
+    def close(self) -> None:
+        """Close the store."""
+        pass  # No resources to release

src/praisonai/praisonai/persistence/factory.py

@@ -62,10 +62,29 @@ def create_conversation_store(
         from .conversation.surrealdb import SurrealDBConversationStore
         return SurrealDBConversationStore(url=url, **options)
     
+    elif backend == "json":
+        from .conversation.json_store import JSONConversationStore
+        path = url or options.pop("path", None) or "./praisonai_conversations"
+        return JSONConversationStore(path=path, **options)
+    
+    elif backend in ("async_postgres", "asyncpg", "postgres_async"):
+        from .conversation.async_postgres import AsyncPostgresConversationStore
+        return AsyncPostgresConversationStore(url=url, **options)
+    
+    elif backend in ("async_sqlite", "aiosqlite", "sqlite_async"):
+        from .conversation.async_sqlite import AsyncSQLiteConversationStore
+        path = url or options.pop("path", None)
+        return AsyncSQLiteConversationStore(path=path, **options)
+    
+    elif backend in ("async_mysql", "aiomysql", "mysql_async"):
+        from .conversation.async_mysql import AsyncMySQLConversationStore
+        return AsyncMySQLConversationStore(url=url, **options)
+    
     else:
         raise ValueError(
             f"Unknown conversation store backend: {backend}. "
-            f"Supported: postgres, mysql, sqlite, singlestore, supabase, surrealdb"
+            f"Supported: postgres, mysql, sqlite, json, singlestore, supabase, surrealdb, "
+            f"async_postgres, async_sqlite, async_mysql"
         )
 
 
@@ -135,10 +154,47 @@ def create_knowledge_store(
         from .knowledge.clickhouse import ClickHouseKnowledgeStore
         return ClickHouseKnowledgeStore(**options)
     
+    elif backend == "couchbase":
+        from .knowledge.couchbase import CouchbaseKnowledgeStore
+        return CouchbaseKnowledgeStore(**options)
+    
+    elif backend in ("mongodb_vector", "mongodb_atlas", "mongo_vector"):
+        from .knowledge.mongodb_vector import MongoDBVectorKnowledgeStore
+        return MongoDBVectorKnowledgeStore(url=url, **options)
+    
+    elif backend in ("singlestore_vector", "singlestore_v"):
+        from .knowledge.singlestore_vector import SingleStoreVectorKnowledgeStore
+        return SingleStoreVectorKnowledgeStore(url=url, **options)
+    
+    elif backend in ("surrealdb_vector", "surrealdb_v"):
+        from .knowledge.surrealdb_vector import SurrealDBVectorKnowledgeStore
+        return SurrealDBVectorKnowledgeStore(url=url, **options)
+    
+    elif backend in ("upstash_vector", "upstash_v"):
+        from .knowledge.upstash_vector import UpstashVectorKnowledgeStore
+        return UpstashVectorKnowledgeStore(url=url, **options)
+    
+    elif backend == "lightrag":
+        from .knowledge.lightrag_adapter import LightRAGKnowledgeStore
+        return LightRAGKnowledgeStore(**options)
+    
+    elif backend in ("langchain", "langchain_adapter"):
+        from .knowledge.langchain_adapter import LangChainKnowledgeStore
+        return LangChainKnowledgeStore(**options)
+    
+    elif backend in ("llamaindex", "llama_index", "llamaindex_adapter"):
+        from .knowledge.llamaindex_adapter import LlamaIndexKnowledgeStore
+        return LlamaIndexKnowledgeStore(**options)
+    
+    elif backend in ("cosmosdb", "cosmos", "azure_cosmos", "cosmosdb_vector"):
+        from .knowledge.cosmosdb_vector import CosmosDBVectorKnowledgeStore
+        return CosmosDBVectorKnowledgeStore(**options)
+    
     else:
         raise ValueError(
             f"Unknown knowledge store backend: {backend}. "
-            f"Supported: qdrant, pinecone, chroma, weaviate, lancedb, milvus, pgvector, redis, cassandra, clickhouse"
+            f"Supported: qdrant, pinecone, chroma, weaviate, lancedb, milvus, pgvector, redis, cassandra, clickhouse, "
+            f"couchbase, mongodb_vector, singlestore_vector, surrealdb_vector, upstash_vector, lightrag, langchain, llamaindex, cosmosdb"
         )
 
 
@@ -190,10 +246,21 @@ def create_state_store(
         from .state.memory import MemoryStateStore
         return MemoryStateStore(**options)
     
+    elif backend == "gcs":
+        from .state.gcs import GCSStateStore
+        bucket = options.pop("bucket_name", None) or options.pop("bucket", None)
+        if not bucket:
+            raise ValueError("GCS state store requires 'bucket_name' option")
+        return GCSStateStore(bucket_name=bucket, **options)
+    
+    elif backend in ("async_mongodb", "motor", "mongodb_async"):
+        from .state.async_mongodb import AsyncMongoDBStateStore
+        return AsyncMongoDBStateStore(url=url, **options)
+    
     else:
         raise ValueError(
             f"Unknown state store backend: {backend}. "
-            f"Supported: redis, dynamodb, firestore, mongodb, upstash, memory"
+            f"Supported: redis, dynamodb, firestore, mongodb, upstash, memory, gcs, async_mongodb"
         )
 
 

src/praisonai/praisonai/persistence/knowledge/cosmosdb_vector.py

@@ -0,0 +1,438 @@
+"""
+Azure Cosmos DB Vector implementation of KnowledgeStore.
+
+Supports both MongoDB API and vCore modes.
+
+Requires: pymongo (for MongoDB API) or azure-cosmos (for SQL API)
+Install: pip install pymongo  # or pip install azure-cosmos
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class CosmosDBVectorKnowledgeStore(KnowledgeStore):
+    """
+    Azure Cosmos DB vector store for knowledge/RAG.
+    
+    Supports MongoDB API with vector search capabilities.
+    
+    Example:
+        store = CosmosDBVectorKnowledgeStore(
+            connection_string="mongodb+srv://...",
+            database="praisonai",
+            collection="vectors"
+        )
+    """
+    
+    def __init__(
+        self,
+        connection_string: Optional[str] = None,
+        database: str = "praisonai",
+        collection: str = "vectors",
+        index_name: str = "vector_index",
+        embedding_field: str = "embedding",
+        text_field: str = "content",
+        embedding_dim: int = 1536,
+        api_mode: str = "mongodb",  # "mongodb" or "sql"
+    ):
+        """
+        Initialize Cosmos DB Vector store.
+        
+        Args:
+            connection_string: Azure Cosmos DB connection string
+            database: Database name
+            collection: Collection name
+            index_name: Vector search index name
+            embedding_field: Field name for embeddings
+            text_field: Field name for text content
+            embedding_dim: Embedding dimension
+            api_mode: API mode ("mongodb" or "sql")
+        """
+        self.connection_string = connection_string
+        self.database_name = database
+        self.collection_name = collection
+        self.index_name = index_name
+        self.embedding_field = embedding_field
+        self.text_field = text_field
+        self.embedding_dim = embedding_dim
+        self.api_mode = api_mode
+        
+        self._client = None
+        self._db = None
+        self._collection = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize Cosmos DB client lazily."""
+        if self._initialized:
+            return
+        
+        if not self.connection_string:
+            import os
+            self.connection_string = os.getenv("COSMOS_CONNECTION_STRING")
+            if not self.connection_string:
+                raise ValueError(
+                    "connection_string required. Set COSMOS_CONNECTION_STRING env var."
+                )
+        
+        if self.api_mode == "mongodb":
+            self._init_mongodb_client()
+        else:
+            self._init_sql_client()
+        
+        self._initialized = True
+    
+    def _init_mongodb_client(self):
+        """Initialize MongoDB API client."""
+        try:
+            from pymongo import MongoClient
+        except ImportError:
+            raise ImportError(
+                "pymongo is required for Cosmos DB MongoDB API. "
+                "Install with: pip install pymongo"
+            )
+        
+        self._client = MongoClient(self.connection_string)
+        self._db = self._client[self.database_name]
+        self._collection = self._db[self.collection_name]
+    
+    def _init_sql_client(self):
+        """Initialize SQL API client."""
+        try:
+            from azure.cosmos import CosmosClient
+        except ImportError:
+            raise ImportError(
+                "azure-cosmos is required for Cosmos DB SQL API. "
+                "Install with: pip install azure-cosmos"
+            )
+        
+        self._client = CosmosClient.from_connection_string(self.connection_string)
+        self._db = self._client.get_database_client(self.database_name)
+        self._collection = self._db.get_container_client(self.collection_name)
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection with vector index."""
+        self._init_client()
+        
+        if self.api_mode == "mongodb":
+            # Create vector search index via MongoDB command
+            try:
+                self._db.command({
+                    "createIndexes": name,
+                    "indexes": [{
+                        "name": self.index_name,
+                        "key": {self.embedding_field: "cosmosSearch"},
+                        "cosmosSearchOptions": {
+                            "kind": "vector-ivf",
+                            "numLists": 100,
+                            "similarity": distance,
+                            "dimensions": dimension
+                        }
+                    }]
+                })
+            except Exception as e:
+                logger.warning(f"Index creation may require manual setup: {e}")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete collection."""
+        self._init_client()
+        try:
+            if self.api_mode == "mongodb":
+                self._db.drop_collection(name)
+            else:
+                self._db.delete_container(name)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete collection: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if collection exists."""
+        self._init_client()
+        if self.api_mode == "mongodb":
+            return name in self._db.list_collection_names()
+        return True  # SQL API containers are pre-created
+    
+    def list_collections(self) -> List[str]:
+        """List collections."""
+        self._init_client()
+        if self.api_mode == "mongodb":
+            return self._db.list_collection_names()
+        return [c["id"] for c in self._db.list_containers()]
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        coll = self._db[collection] if self.api_mode == "mongodb" else self._db.get_container_client(collection)
+        ids = []
+        
+        for doc in documents:
+            item = {
+                "_id" if self.api_mode == "mongodb" else "id": doc.id,
+                self.text_field: doc.content,
+                self.embedding_field: doc.embedding,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            try:
+                if self.api_mode == "mongodb":
+                    coll.insert_one(item)
+                else:
+                    coll.create_item(item)
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to insert {doc.id}: {e}")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents."""
+        self._init_client()
+        
+        coll = self._db[collection] if self.api_mode == "mongodb" else self._db.get_container_client(collection)
+        ids = []
+        
+        for doc in documents:
+            item = {
+                "_id" if self.api_mode == "mongodb" else "id": doc.id,
+                self.text_field: doc.content,
+                self.embedding_field: doc.embedding,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            try:
+                if self.api_mode == "mongodb":
+                    coll.replace_one({"_id": doc.id}, item, upsert=True)
+                else:
+                    coll.upsert_item(item)
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to upsert {doc.id}: {e}")
+        
+        return ids
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents using vector search."""
+        self._init_client()
+        
+        if self.api_mode == "mongodb":
+            return self._search_mongodb(collection, query_embedding, limit, filters, score_threshold)
+        else:
+            return self._search_sql(collection, query_embedding, limit, filters, score_threshold)
+    
+    def _search_mongodb(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int,
+        filters: Optional[Dict[str, Any]],
+        score_threshold: Optional[float]
+    ) -> List[KnowledgeDocument]:
+        """MongoDB API vector search."""
+        coll = self._db[collection]
+        
+        pipeline = [
+            {
+                "$search": {
+                    "cosmosSearch": {
+                        "vector": query_embedding,
+                        "path": self.embedding_field,
+                        "k": limit
+                    },
+                    "returnStoredSource": True
+                }
+            },
+            {
+                "$project": {
+                    "similarityScore": {"$meta": "searchScore"},
+                    self.text_field: 1,
+                    "metadata": 1,
+                    "content_hash": 1,
+                    "created_at": 1
+                }
+            }
+        ]
+        
+        if filters:
+            pipeline.insert(1, {"$match": filters})
+        
+        try:
+            results = list(coll.aggregate(pipeline))
+            
+            documents = []
+            for doc in results:
+                score = doc.get("similarityScore", 0)
+                if score_threshold and score < score_threshold:
+                    continue
+                
+                documents.append(KnowledgeDocument(
+                    id=str(doc.get("_id", "")),
+                    content=doc.get(self.text_field, ""),
+                    metadata={**(doc.get("metadata") or {}), "score": score},
+                    content_hash=doc.get("content_hash"),
+                    created_at=doc.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}")
+            return []
+    
+    def _search_sql(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int,
+        filters: Optional[Dict[str, Any]],
+        score_threshold: Optional[float]
+    ) -> List[KnowledgeDocument]:
+        """SQL API vector search (requires DiskANN index)."""
+        coll = self._db.get_container_client(collection)
+        
+        # SQL API uses VectorDistance function
+        query = f"""
+            SELECT TOP {limit} c.id, c.{self.text_field}, c.metadata, c.content_hash, c.created_at,
+                   VectorDistance(c.{self.embedding_field}, @embedding) AS score
+            FROM c
+            ORDER BY VectorDistance(c.{self.embedding_field}, @embedding)
+        """
+        
+        try:
+            results = list(coll.query_items(
+                query=query,
+                parameters=[{"name": "@embedding", "value": query_embedding}],
+                enable_cross_partition_query=True
+            ))
+            
+            documents = []
+            for doc in results:
+                score = doc.get("score", 0)
+                if score_threshold and score < score_threshold:
+                    continue
+                
+                documents.append(KnowledgeDocument(
+                    id=doc.get("id", ""),
+                    content=doc.get(self.text_field, ""),
+                    metadata={**(doc.get("metadata") or {}), "score": score},
+                    content_hash=doc.get("content_hash"),
+                    created_at=doc.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        coll = self._db[collection] if self.api_mode == "mongodb" else self._db.get_container_client(collection)
+        documents = []
+        
+        for doc_id in ids:
+            try:
+                if self.api_mode == "mongodb":
+                    doc = coll.find_one({"_id": doc_id})
+                else:
+                    doc = coll.read_item(item=doc_id, partition_key=doc_id)
+                
+                if doc:
+                    documents.append(KnowledgeDocument(
+                        id=str(doc.get("_id" if self.api_mode == "mongodb" else "id", "")),
+                        content=doc.get(self.text_field, ""),
+                        embedding=doc.get(self.embedding_field),
+                        metadata=doc.get("metadata"),
+                        content_hash=doc.get("content_hash"),
+                        created_at=doc.get("created_at", 0)
+                    ))
+            except Exception as e:
+                logger.warning(f"Failed to get {doc_id}: {e}")
+        
+        return documents
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        coll = self._db[collection] if self.api_mode == "mongodb" else self._db.get_container_client(collection)
+        
+        if ids:
+            count = 0
+            for doc_id in ids:
+                try:
+                    if self.api_mode == "mongodb":
+                        coll.delete_one({"_id": doc_id})
+                    else:
+                        coll.delete_item(item=doc_id, partition_key=doc_id)
+                    count += 1
+                except Exception as e:
+                    logger.warning(f"Failed to delete {doc_id}: {e}")
+            return count
+        
+        return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents."""
+        self._init_client()
+        
+        if self.api_mode == "mongodb":
+            return self._db[collection].count_documents({})
+        else:
+            # SQL API count
+            coll = self._db.get_container_client(collection)
+            result = list(coll.query_items(
+                query="SELECT VALUE COUNT(1) FROM c",
+                enable_cross_partition_query=True
+            ))
+            return result[0] if result else 0
+    
+    def close(self) -> None:
+        """Close the connection."""
+        if self._client:
+            if self.api_mode == "mongodb":
+                self._client.close()
+            self._client = None
+            self._db = None
+            self._collection = None
+            self._initialized = False

src/praisonai/praisonai/persistence/knowledge/couchbase.py

@@ -0,0 +1,286 @@
+"""
+Couchbase implementation of KnowledgeStore.
+
+Requires: couchbase
+Install: pip install couchbase
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class CouchbaseKnowledgeStore(KnowledgeStore):
+    """
+    Couchbase vector store for knowledge/RAG.
+    
+    Uses Couchbase's vector search capabilities.
+    
+    Example:
+        store = CouchbaseKnowledgeStore(
+            connection_string="couchbase://localhost",
+            username="admin",
+            password="password",
+            bucket_name="praisonai"
+        )
+    """
+    
+    def __init__(
+        self,
+        connection_string: str = "couchbase://localhost",
+        username: str = "Administrator",
+        password: str = "",
+        bucket_name: str = "praisonai",
+        scope_name: str = "_default",
+        collection_name: str = "vectors",
+        index_name: str = "vector_index",
+        vector_field: str = "embedding",
+        text_field: str = "content",
+        embedding_dim: int = 1536,
+    ):
+        """
+        Initialize Couchbase knowledge store.
+        
+        Args:
+            connection_string: Couchbase connection string
+            username: Couchbase username
+            password: Couchbase password
+            bucket_name: Bucket name
+            scope_name: Scope name
+            collection_name: Collection name
+            index_name: Vector search index name
+            vector_field: Field name for embeddings
+            text_field: Field name for text content
+            embedding_dim: Embedding dimension
+        """
+        self.connection_string = connection_string
+        self.username = username
+        self.password = password
+        self.bucket_name = bucket_name
+        self.scope_name = scope_name
+        self.collection_name = collection_name
+        self.index_name = index_name
+        self.vector_field = vector_field
+        self.text_field = text_field
+        self.embedding_dim = embedding_dim
+        
+        self._cluster = None
+        self._bucket = None
+        self._collection = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize Couchbase client lazily."""
+        if self._initialized:
+            return
+        
+        try:
+            from couchbase.cluster import Cluster
+            from couchbase.options import ClusterOptions
+            from couchbase.auth import PasswordAuthenticator
+            from datetime import timedelta
+        except ImportError:
+            raise ImportError(
+                "couchbase is required for Couchbase support. "
+                "Install with: pip install couchbase"
+            )
+        
+        auth = PasswordAuthenticator(self.username, self.password)
+        options = ClusterOptions(auth)
+        
+        self._cluster = Cluster(self.connection_string, options)
+        self._cluster.wait_until_ready(timedelta(seconds=10))
+        
+        self._bucket = self._cluster.bucket(self.bucket_name)
+        scope = self._bucket.scope(self.scope_name)
+        self._collection = scope.collection(self.collection_name)
+        
+        self._initialized = True
+    
+    def insert(
+        self,
+        collection_name: str,
+        documents: List[KnowledgeDocument],
+        embeddings: Optional[List[List[float]]] = None,
+    ) -> List[str]:
+        """Insert documents into the store."""
+        self._init_client()
+        
+        ids = []
+        for i, doc in enumerate(documents):
+            doc_id = doc.id or f"doc_{i}_{hash(doc.content)}"
+            
+            data = {
+                self.text_field: doc.content,
+                "metadata": doc.metadata or {},
+            }
+            
+            if embeddings and i < len(embeddings):
+                data[self.vector_field] = embeddings[i]
+            
+            self._collection.upsert(doc_id, data)
+            ids.append(doc_id)
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection_name: str,
+        documents: List[KnowledgeDocument],
+        embeddings: Optional[List[List[float]]] = None,
+    ) -> List[str]:
+        """Upsert documents (same as insert for Couchbase)."""
+        return self.insert(collection_name, documents, embeddings)
+    
+    def search(
+        self,
+        collection_name: str,
+        query_embedding: List[float],
+        limit: int = 10,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents using vector search."""
+        self._init_client()
+        
+        try:
+            from couchbase.vector_search import VectorQuery, VectorSearch
+        except ImportError:
+            logger.warning("Vector search not available in this Couchbase version")
+            return []
+        
+        vector_query = VectorQuery(
+            self.vector_field,
+            query_embedding,
+            num_candidates=limit * 2
+        )
+        
+        search_req = VectorSearch.from_vector_query(vector_query)
+        
+        try:
+            scope = self._bucket.scope(self.scope_name)
+            result = scope.search(
+                self.index_name,
+                search_req,
+                limit=limit
+            )
+            
+            documents = []
+            for row in result.rows():
+                doc_id = row.id
+                try:
+                    doc_data = self._collection.get(doc_id).content_as[dict]
+                    documents.append(KnowledgeDocument(
+                        id=doc_id,
+                        content=doc_data.get(self.text_field, ""),
+                        metadata=doc_data.get("metadata", {}),
+                        score=row.score if hasattr(row, 'score') else None
+                    ))
+                except Exception as e:
+                    logger.warning(f"Failed to fetch document {doc_id}: {e}")
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}")
+            return []
+    
+    def delete(
+        self,
+        collection_name: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Delete documents by ID."""
+        self._init_client()
+        
+        if not ids:
+            return 0
+        
+        count = 0
+        for doc_id in ids:
+            try:
+                self._collection.remove(doc_id)
+                count += 1
+            except Exception as e:
+                logger.warning(f"Failed to delete {doc_id}: {e}")
+        
+        return count
+    
+    def get(
+        self,
+        collection_name: str,
+        ids: List[str],
+    ) -> List[KnowledgeDocument]:
+        """Get documents by ID."""
+        self._init_client()
+        
+        documents = []
+        for doc_id in ids:
+            try:
+                doc_data = self._collection.get(doc_id).content_as[dict]
+                documents.append(KnowledgeDocument(
+                    id=doc_id,
+                    content=doc_data.get(self.text_field, ""),
+                    metadata=doc_data.get("metadata", {})
+                ))
+            except Exception as e:
+                logger.warning(f"Failed to get {doc_id}: {e}")
+        
+        return documents
+    
+    def count(self, collection_name: str) -> int:
+        """Count documents in collection."""
+        self._init_client()
+        
+        try:
+            query = f"SELECT COUNT(*) as count FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.collection_name}`"
+            result = self._cluster.query(query)
+            for row in result:
+                return row.get("count", 0)
+        except Exception as e:
+            logger.error(f"Count query failed: {e}")
+        
+        return 0
+    
+    def create_collection(self, collection_name: str, **kwargs) -> bool:
+        """Create collection (Couchbase collections are pre-created)."""
+        self._init_client()
+        return True
+    
+    def delete_collection(self, collection_name: str) -> bool:
+        """Delete all documents in collection."""
+        self._init_client()
+        
+        try:
+            query = f"DELETE FROM `{self.bucket_name}`.`{self.scope_name}`.`{self.collection_name}`"
+            self._cluster.query(query)
+            return True
+        except Exception as e:
+            logger.error(f"Delete collection failed: {e}")
+            return False
+    
+    def list_collections(self) -> List[str]:
+        """List available collections."""
+        self._init_client()
+        
+        try:
+            collections = self._bucket.collections().get_all_scopes()
+            result = []
+            for scope in collections:
+                for coll in scope.collections:
+                    result.append(f"{scope.name}.{coll.name}")
+            return result
+        except Exception as e:
+            logger.error(f"List collections failed: {e}")
+            return []
+    
+    def close(self) -> None:
+        """Close the connection."""
+        if self._cluster:
+            self._cluster.close()
+            self._cluster = None
+            self._bucket = None
+            self._collection = None
+            self._initialized = False

src/praisonai/praisonai/persistence/knowledge/langchain_adapter.py

@@ -0,0 +1,291 @@
+"""
+LangChain VectorStore adapter implementation of KnowledgeStore.
+
+Wraps any LangChain VectorStore for use with PraisonAI.
+
+Requires: langchain-core
+Install: pip install langchain-core
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class LangChainKnowledgeStore(KnowledgeStore):
+    """
+    LangChain VectorStore adapter for knowledge/RAG.
+    
+    Wraps any LangChain VectorStore for use with PraisonAI's interface.
+    
+    Example:
+        from langchain_chroma import Chroma
+        
+        lc_store = Chroma(persist_directory="./chroma_db")
+        store = LangChainKnowledgeStore(vectorstore=lc_store)
+    """
+    
+    def __init__(
+        self,
+        vectorstore: Any = None,
+        vectorstore_cls: Optional[str] = None,
+        vectorstore_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize LangChain adapter.
+        
+        Args:
+            vectorstore: Pre-initialized LangChain VectorStore instance
+            vectorstore_cls: Class name to import (e.g., "langchain_chroma.Chroma")
+            vectorstore_kwargs: Kwargs for vectorstore initialization
+        """
+        self._vectorstore = vectorstore
+        self._vectorstore_cls = vectorstore_cls
+        self._vectorstore_kwargs = vectorstore_kwargs or {}
+        self._initialized = vectorstore is not None
+    
+    def _init_client(self):
+        """Initialize vectorstore lazily."""
+        if self._initialized:
+            return
+        
+        if not self._vectorstore_cls:
+            raise ValueError(
+                "Either vectorstore or vectorstore_cls must be provided"
+            )
+        
+        # Dynamic import of vectorstore class
+        parts = self._vectorstore_cls.rsplit(".", 1)
+        if len(parts) == 2:
+            module_name, class_name = parts
+            import importlib
+            module = importlib.import_module(module_name)
+            cls = getattr(module, class_name)
+            self._vectorstore = cls(**self._vectorstore_kwargs)
+        else:
+            raise ValueError(f"Invalid vectorstore_cls: {self._vectorstore_cls}")
+        
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection (handled by underlying vectorstore)."""
+        self._init_client()
+        logger.info(f"Collection creation handled by LangChain vectorstore")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete collection."""
+        self._init_client()
+        try:
+            if hasattr(self._vectorstore, 'delete_collection'):
+                self._vectorstore.delete_collection()
+                return True
+            logger.warning("Underlying vectorstore doesn't support delete_collection")
+            return False
+        except Exception as e:
+            logger.error(f"Failed to delete collection: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if collection exists."""
+        self._init_client()
+        return self._vectorstore is not None
+    
+    def list_collections(self) -> List[str]:
+        """List collections."""
+        self._init_client()
+        if hasattr(self._vectorstore, 'list_collections'):
+            return self._vectorstore.list_collections()
+        return ["default"]
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        try:
+            from langchain_core.documents import Document as LCDocument
+        except ImportError:
+            raise ImportError(
+                "langchain-core is required. Install with: pip install langchain-core"
+            )
+        
+        lc_docs = []
+        ids = []
+        for doc in documents:
+            lc_doc = LCDocument(
+                page_content=doc.content,
+                metadata={
+                    **(doc.metadata or {}),
+                    "id": doc.id,
+                    "content_hash": doc.content_hash,
+                    "created_at": doc.created_at,
+                }
+            )
+            lc_docs.append(lc_doc)
+            ids.append(doc.id)
+        
+        if hasattr(self._vectorstore, 'add_documents'):
+            self._vectorstore.add_documents(lc_docs, ids=ids)
+        else:
+            logger.warning("Vectorstore doesn't support add_documents")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents."""
+        # Most LangChain vectorstores handle upsert via add_documents
+        return self.insert(collection, documents)
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents."""
+        self._init_client()
+        
+        try:
+            if hasattr(self._vectorstore, 'similarity_search_by_vector'):
+                results = self._vectorstore.similarity_search_by_vector(
+                    query_embedding,
+                    k=limit,
+                    filter=filters
+                )
+            else:
+                logger.warning("Vectorstore doesn't support vector search")
+                return []
+            
+            documents = []
+            for lc_doc in results:
+                metadata = lc_doc.metadata or {}
+                documents.append(KnowledgeDocument(
+                    id=metadata.get("id", ""),
+                    content=lc_doc.page_content,
+                    metadata=metadata,
+                    content_hash=metadata.get("content_hash"),
+                    created_at=metadata.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            return []
+    
+    def similarity_search(
+        self,
+        query_text: str,
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> List[KnowledgeDocument]:
+        """
+        Text-based similarity search (native LangChain method).
+        
+        Args:
+            query_text: Query string
+            limit: Maximum results
+            filters: Metadata filters
+        
+        Returns:
+            List of matching documents
+        """
+        self._init_client()
+        
+        try:
+            results = self._vectorstore.similarity_search(
+                query_text,
+                k=limit,
+                filter=filters
+            )
+            
+            documents = []
+            for lc_doc in results:
+                metadata = lc_doc.metadata or {}
+                documents.append(KnowledgeDocument(
+                    id=metadata.get("id", ""),
+                    content=lc_doc.page_content,
+                    metadata=metadata,
+                    content_hash=metadata.get("content_hash"),
+                    created_at=metadata.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Similarity search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        if hasattr(self._vectorstore, 'get'):
+            try:
+                results = self._vectorstore.get(ids)
+                documents = []
+                for lc_doc in results:
+                    metadata = lc_doc.metadata or {}
+                    documents.append(KnowledgeDocument(
+                        id=metadata.get("id", ""),
+                        content=lc_doc.page_content,
+                        metadata=metadata
+                    ))
+                return documents
+            except Exception as e:
+                logger.warning(f"Get by ID failed: {e}")
+        
+        return []
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        if ids and hasattr(self._vectorstore, 'delete'):
+            try:
+                self._vectorstore.delete(ids)
+                return len(ids)
+            except Exception as e:
+                logger.error(f"Delete failed: {e}")
+        
+        return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents."""
+        self._init_client()
+        
+        if hasattr(self._vectorstore, '__len__'):
+            return len(self._vectorstore)
+        
+        logger.warning("Vectorstore doesn't support counting")
+        return -1
+    
+    def close(self) -> None:
+        """Close the client."""
+        self._vectorstore = None
+        self._initialized = False

src/praisonai/praisonai/persistence/knowledge/lightrag_adapter.py

@@ -0,0 +1,212 @@
+"""
+LightRAG adapter implementation of KnowledgeStore.
+
+Requires: lightrag
+Install: pip install lightrag
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class LightRAGKnowledgeStore(KnowledgeStore):
+    """
+    LightRAG adapter for knowledge/RAG.
+    
+    Wraps LightRAG for use with PraisonAI's KnowledgeStore interface.
+    
+    Example:
+        store = LightRAGKnowledgeStore(
+            working_dir="./lightrag_data"
+        )
+    """
+    
+    def __init__(
+        self,
+        working_dir: str = "./lightrag_data",
+        llm_model: str = "gpt-4o-mini",
+        embedding_model: str = "text-embedding-3-small",
+        **kwargs
+    ):
+        """
+        Initialize LightRAG adapter.
+        
+        Args:
+            working_dir: Directory for LightRAG data
+            llm_model: LLM model for graph extraction
+            embedding_model: Embedding model name
+            **kwargs: Additional LightRAG options
+        """
+        self.working_dir = working_dir
+        self.llm_model = llm_model
+        self.embedding_model = embedding_model
+        self.kwargs = kwargs
+        
+        self._rag = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize LightRAG client lazily."""
+        if self._initialized:
+            return
+        
+        try:
+            from lightrag import LightRAG, QueryParam
+            from lightrag.llm import gpt_4o_mini_complete, openai_embedding
+        except ImportError:
+            raise ImportError(
+                "lightrag is required for LightRAG support. "
+                "Install with: pip install lightrag"
+            )
+        
+        self._QueryParam = QueryParam
+        self._rag = LightRAG(
+            working_dir=self.working_dir,
+            llm_model_func=gpt_4o_mini_complete,
+            embedding_func=openai_embedding,
+            **self.kwargs
+        )
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection (LightRAG uses working directory)."""
+        self._init_client()
+        logger.info(f"LightRAG uses working_dir: {self.working_dir}")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete collection data."""
+        import shutil
+        import os
+        
+        try:
+            if os.path.exists(self.working_dir):
+                shutil.rmtree(self.working_dir)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete collection: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if working directory exists."""
+        import os
+        return os.path.exists(self.working_dir)
+    
+    def list_collections(self) -> List[str]:
+        """List collections (single collection per working_dir)."""
+        import os
+        if os.path.exists(self.working_dir):
+            return ["default"]
+        return []
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents into LightRAG."""
+        self._init_client()
+        
+        ids = []
+        for doc in documents:
+            try:
+                self._rag.insert(doc.content)
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to insert document {doc.id}: {e}")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents (same as insert for LightRAG)."""
+        return self.insert(collection, documents)
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search using LightRAG's query method."""
+        self._init_client()
+        
+        # LightRAG uses text query, not embeddings directly
+        # This is a limitation - we need the original query text
+        logger.warning(
+            "LightRAG search requires text query, not embeddings. "
+            "Use query() method directly for best results."
+        )
+        return []
+    
+    def query(
+        self,
+        query_text: str,
+        mode: str = "hybrid",
+        limit: int = 5
+    ) -> str:
+        """
+        Query LightRAG with text (native method).
+        
+        Args:
+            query_text: The query string
+            mode: Query mode (naive, local, global, hybrid)
+            limit: Maximum results
+        
+        Returns:
+            Query response as string
+        """
+        self._init_client()
+        
+        try:
+            result = self._rag.query(
+                query_text,
+                param=self._QueryParam(mode=mode, top_k=limit)
+            )
+            return result
+        except Exception as e:
+            logger.error(f"Query failed: {e}")
+            return ""
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs (not supported by LightRAG)."""
+        logger.warning("LightRAG does not support get by ID")
+        return []
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents (not directly supported)."""
+        logger.warning("LightRAG does not support individual document deletion")
+        return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents (not directly supported)."""
+        logger.warning("LightRAG does not support document counting")
+        return -1
+    
+    def close(self) -> None:
+        """Close the client."""
+        self._rag = None
+        self._initialized = False

src/praisonai/praisonai/persistence/knowledge/llamaindex_adapter.py

@@ -0,0 +1,256 @@
+"""
+LlamaIndex VectorStore adapter implementation of KnowledgeStore.
+
+Wraps any LlamaIndex VectorStore for use with PraisonAI.
+
+Requires: llama-index-core
+Install: pip install llama-index-core
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class LlamaIndexKnowledgeStore(KnowledgeStore):
+    """
+    LlamaIndex VectorStore adapter for knowledge/RAG.
+    
+    Wraps any LlamaIndex VectorStore for use with PraisonAI's interface.
+    
+    Example:
+        from llama_index.vector_stores.chroma import ChromaVectorStore
+        
+        li_store = ChromaVectorStore(chroma_collection=collection)
+        store = LlamaIndexKnowledgeStore(vector_store=li_store)
+    """
+    
+    def __init__(
+        self,
+        vector_store: Any = None,
+        vector_store_cls: Optional[str] = None,
+        vector_store_kwargs: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize LlamaIndex adapter.
+        
+        Args:
+            vector_store: Pre-initialized LlamaIndex VectorStore instance
+            vector_store_cls: Class name to import (e.g., "llama_index.vector_stores.chroma.ChromaVectorStore")
+            vector_store_kwargs: Kwargs for vector_store initialization
+        """
+        self._vector_store = vector_store
+        self._vector_store_cls = vector_store_cls
+        self._vector_store_kwargs = vector_store_kwargs or {}
+        self._initialized = vector_store is not None
+    
+    def _init_client(self):
+        """Initialize vector store lazily."""
+        if self._initialized:
+            return
+        
+        if not self._vector_store_cls:
+            raise ValueError(
+                "Either vector_store or vector_store_cls must be provided"
+            )
+        
+        # Dynamic import of vector store class
+        parts = self._vector_store_cls.rsplit(".", 1)
+        if len(parts) == 2:
+            module_name, class_name = parts
+            import importlib
+            module = importlib.import_module(module_name)
+            cls = getattr(module, class_name)
+            self._vector_store = cls(**self._vector_store_kwargs)
+        else:
+            raise ValueError(f"Invalid vector_store_cls: {self._vector_store_cls}")
+        
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection (handled by underlying vector store)."""
+        self._init_client()
+        logger.info("Collection creation handled by LlamaIndex vector store")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete collection."""
+        self._init_client()
+        try:
+            if hasattr(self._vector_store, 'delete'):
+                self._vector_store.delete(delete_all=True)
+                return True
+            logger.warning("Underlying vector store doesn't support delete")
+            return False
+        except Exception as e:
+            logger.error(f"Failed to delete collection: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if collection exists."""
+        self._init_client()
+        return self._vector_store is not None
+    
+    def list_collections(self) -> List[str]:
+        """List collections."""
+        self._init_client()
+        return ["default"]
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        try:
+            from llama_index.core.schema import TextNode
+        except ImportError:
+            raise ImportError(
+                "llama-index-core is required. Install with: pip install llama-index-core"
+            )
+        
+        nodes = []
+        ids = []
+        for doc in documents:
+            node = TextNode(
+                text=doc.content,
+                id_=doc.id,
+                metadata={
+                    **(doc.metadata or {}),
+                    "content_hash": doc.content_hash,
+                    "created_at": doc.created_at,
+                },
+                embedding=doc.embedding
+            )
+            nodes.append(node)
+            ids.append(doc.id)
+        
+        if hasattr(self._vector_store, 'add'):
+            self._vector_store.add(nodes)
+        else:
+            logger.warning("Vector store doesn't support add")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents."""
+        return self.insert(collection, documents)
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents."""
+        self._init_client()
+        
+        try:
+            from llama_index.core.vector_stores import VectorStoreQuery
+        except ImportError:
+            raise ImportError(
+                "llama-index-core is required. Install with: pip install llama-index-core"
+            )
+        
+        try:
+            query = VectorStoreQuery(
+                query_embedding=query_embedding,
+                similarity_top_k=limit,
+            )
+            
+            result = self._vector_store.query(query)
+            
+            documents = []
+            for i, node in enumerate(result.nodes or []):
+                score = result.similarities[i] if result.similarities else None
+                if score_threshold and score and score < score_threshold:
+                    continue
+                
+                metadata = node.metadata or {}
+                if score:
+                    metadata["score"] = score
+                
+                documents.append(KnowledgeDocument(
+                    id=node.node_id or node.id_,
+                    content=node.text or node.get_content(),
+                    embedding=node.embedding,
+                    metadata=metadata,
+                    content_hash=metadata.get("content_hash"),
+                    created_at=metadata.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        documents = []
+        for doc_id in ids:
+            try:
+                if hasattr(self._vector_store, 'get'):
+                    node = self._vector_store.get(doc_id)
+                    if node:
+                        metadata = node.metadata or {}
+                        documents.append(KnowledgeDocument(
+                            id=node.node_id or node.id_,
+                            content=node.text or node.get_content(),
+                            embedding=node.embedding,
+                            metadata=metadata
+                        ))
+            except Exception as e:
+                logger.warning(f"Get by ID failed for {doc_id}: {e}")
+        
+        return documents
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        if ids and hasattr(self._vector_store, 'delete'):
+            try:
+                self._vector_store.delete(ref_doc_id=ids[0] if len(ids) == 1 else None)
+                return len(ids)
+            except Exception as e:
+                logger.error(f"Delete failed: {e}")
+        
+        return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents."""
+        self._init_client()
+        logger.warning("LlamaIndex vector stores don't typically support counting")
+        return -1
+    
+    def close(self) -> None:
+        """Close the client."""
+        self._vector_store = None
+        self._initialized = False

src/praisonai/praisonai/persistence/knowledge/mongodb_vector.py

@@ -0,0 +1,306 @@
+"""
+MongoDB Vector Search implementation of KnowledgeStore.
+
+Requires: pymongo
+Install: pip install pymongo
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class MongoDBVectorKnowledgeStore(KnowledgeStore):
+    """
+    MongoDB Atlas Vector Search store for knowledge/RAG.
+    
+    Uses MongoDB Atlas Vector Search capabilities.
+    
+    Example:
+        store = MongoDBVectorKnowledgeStore(
+            url="mongodb+srv://...",
+            database="praisonai",
+            collection="vectors"
+        )
+    """
+    
+    def __init__(
+        self,
+        url: str = "mongodb://localhost:27017",
+        database: str = "praisonai",
+        collection: str = "vectors",
+        index_name: str = "vector_index",
+        embedding_field: str = "embedding",
+        text_field: str = "content",
+        embedding_dim: int = 1536,
+    ):
+        """
+        Initialize MongoDB Vector store.
+        
+        Args:
+            url: MongoDB connection URL
+            database: Database name
+            collection: Collection name
+            index_name: Vector search index name
+            embedding_field: Field name for embeddings
+            text_field: Field name for text content
+            embedding_dim: Embedding dimension
+        """
+        self.url = url
+        self.database_name = database
+        self.collection_name = collection
+        self.index_name = index_name
+        self.embedding_field = embedding_field
+        self.text_field = text_field
+        self.embedding_dim = embedding_dim
+        
+        self._client = None
+        self._db = None
+        self._collection = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize MongoDB client lazily."""
+        if self._initialized:
+            return
+        
+        try:
+            from pymongo import MongoClient
+        except ImportError:
+            raise ImportError(
+                "pymongo is required for MongoDB Vector support. "
+                "Install with: pip install pymongo"
+            )
+        
+        self._client = MongoClient(self.url)
+        self._db = self._client[self.database_name]
+        self._collection = self._db[self.collection_name]
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection (MongoDB creates on first insert)."""
+        self._init_client()
+        # MongoDB creates collections automatically on first insert
+        # Vector search index must be created via Atlas UI or API
+        logger.info(
+            f"Collection '{name}' will be created on first insert. "
+            f"Note: Vector search index must be created via MongoDB Atlas."
+        )
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete a collection."""
+        self._init_client()
+        try:
+            self._db.drop_collection(name)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete collection {name}: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if collection exists."""
+        self._init_client()
+        return name in self._db.list_collection_names()
+    
+    def list_collections(self) -> List[str]:
+        """List all collections."""
+        self._init_client()
+        return self._db.list_collection_names()
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents into collection."""
+        self._init_client()
+        
+        coll = self._db[collection]
+        ids = []
+        
+        for doc in documents:
+            mongo_doc = {
+                "_id": doc.id,
+                self.text_field: doc.content,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            if doc.embedding:
+                mongo_doc[self.embedding_field] = doc.embedding
+            
+            try:
+                coll.insert_one(mongo_doc)
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to insert document {doc.id}: {e}")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents into collection."""
+        self._init_client()
+        
+        coll = self._db[collection]
+        ids = []
+        
+        for doc in documents:
+            mongo_doc = {
+                self.text_field: doc.content,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            if doc.embedding:
+                mongo_doc[self.embedding_field] = doc.embedding
+            
+            try:
+                coll.replace_one(
+                    {"_id": doc.id},
+                    {"_id": doc.id, **mongo_doc},
+                    upsert=True
+                )
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to upsert document {doc.id}: {e}")
+        
+        return ids
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents using vector search."""
+        self._init_client()
+        
+        coll = self._db[collection]
+        
+        # Build aggregation pipeline for vector search
+        pipeline = [
+            {
+                "$vectorSearch": {
+                    "index": self.index_name,
+                    "path": self.embedding_field,
+                    "queryVector": query_embedding,
+                    "numCandidates": limit * 10,
+                    "limit": limit
+                }
+            },
+            {
+                "$project": {
+                    "_id": 1,
+                    self.text_field: 1,
+                    "metadata": 1,
+                    "content_hash": 1,
+                    "created_at": 1,
+                    "score": {"$meta": "vectorSearchScore"}
+                }
+            }
+        ]
+        
+        # Add filter if provided
+        if filters:
+            pipeline[0]["$vectorSearch"]["filter"] = filters
+        
+        try:
+            results = list(coll.aggregate(pipeline))
+            
+            documents = []
+            for doc in results:
+                score = doc.get("score", 0)
+                if score_threshold and score < score_threshold:
+                    continue
+                
+                documents.append(KnowledgeDocument(
+                    id=str(doc["_id"]),
+                    content=doc.get(self.text_field, ""),
+                    metadata={**(doc.get("metadata") or {}), "score": score},
+                    content_hash=doc.get("content_hash"),
+                    created_at=doc.get("created_at", 0)
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        coll = self._db[collection]
+        documents = []
+        
+        for doc_id in ids:
+            try:
+                doc = coll.find_one({"_id": doc_id})
+                if doc:
+                    documents.append(KnowledgeDocument(
+                        id=str(doc["_id"]),
+                        content=doc.get(self.text_field, ""),
+                        embedding=doc.get(self.embedding_field),
+                        metadata=doc.get("metadata"),
+                        content_hash=doc.get("content_hash"),
+                        created_at=doc.get("created_at", 0)
+                    ))
+            except Exception as e:
+                logger.warning(f"Failed to get document {doc_id}: {e}")
+        
+        return documents
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents by IDs or filters."""
+        self._init_client()
+        
+        coll = self._db[collection]
+        
+        if ids:
+            result = coll.delete_many({"_id": {"$in": ids}})
+            return result.deleted_count
+        elif filters:
+            result = coll.delete_many(filters)
+            return result.deleted_count
+        else:
+            return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents in collection."""
+        self._init_client()
+        return self._db[collection].count_documents({})
+    
+    def close(self) -> None:
+        """Close the connection."""
+        if self._client:
+            self._client.close()
+            self._client = None
+            self._db = None
+            self._collection = None
+            self._initialized = False

src/praisonai/praisonai/persistence/knowledge/singlestore_vector.py

@@ -0,0 +1,299 @@
+"""
+SingleStore Vector implementation of KnowledgeStore.
+
+Requires: singlestoredb
+Install: pip install singlestoredb
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class SingleStoreVectorKnowledgeStore(KnowledgeStore):
+    """
+    SingleStore vector store for knowledge/RAG.
+    
+    Uses SingleStore's native vector capabilities.
+    
+    Example:
+        store = SingleStoreVectorKnowledgeStore(
+            url="singlestoredb://user:pass@host:3306/db"
+        )
+    """
+    
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        host: str = "localhost",
+        port: int = 3306,
+        database: str = "praisonai",
+        user: str = "root",
+        password: str = "",
+        table_prefix: str = "praisonai_",
+        embedding_dim: int = 1536,
+    ):
+        """
+        Initialize SingleStore Vector store.
+        
+        Args:
+            url: SingleStore connection URL
+            host: Database host
+            port: Database port
+            database: Database name
+            user: Database user
+            password: Database password
+            table_prefix: Prefix for table names
+            embedding_dim: Embedding dimension
+        """
+        self.url = url
+        self.host = host
+        self.port = port
+        self.database = database
+        self.user = user
+        self.password = password
+        self.table_prefix = table_prefix
+        self.embedding_dim = embedding_dim
+        
+        self._conn = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize SingleStore client lazily."""
+        if self._initialized:
+            return
+        
+        try:
+            import singlestoredb as s2
+        except ImportError:
+            raise ImportError(
+                "singlestoredb is required for SingleStore Vector support. "
+                "Install with: pip install singlestoredb"
+            )
+        
+        if self.url:
+            self._conn = s2.connect(self.url)
+        else:
+            self._conn = s2.connect(
+                host=self.host,
+                port=self.port,
+                database=self.database,
+                user=self.user,
+                password=self.password
+            )
+        
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create a vector table."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{name}"
+        
+        with self._conn.cursor() as cur:
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {table_name} (
+                    id VARCHAR(255) PRIMARY KEY,
+                    content TEXT,
+                    embedding VECTOR({dimension}),
+                    metadata JSON,
+                    content_hash VARCHAR(64),
+                    created_at DOUBLE
+                )
+            """)
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete a vector table."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{name}"
+        try:
+            with self._conn.cursor() as cur:
+                cur.execute(f"DROP TABLE IF EXISTS {table_name}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete collection {name}: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if table exists."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{name}"
+        with self._conn.cursor() as cur:
+            cur.execute(f"""
+                SELECT COUNT(*) FROM information_schema.tables 
+                WHERE table_schema = %s AND table_name = %s
+            """, (self.database, table_name))
+            return cur.fetchone()[0] > 0
+    
+    def list_collections(self) -> List[str]:
+        """List all vector tables."""
+        self._init_client()
+        
+        with self._conn.cursor() as cur:
+            cur.execute(f"""
+                SELECT table_name FROM information_schema.tables 
+                WHERE table_schema = %s AND table_name LIKE %s
+            """, (self.database, f"{self.table_prefix}%"))
+            return [row[0][len(self.table_prefix):] for row in cur.fetchall()]
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        ids = []
+        
+        with self._conn.cursor() as cur:
+            for doc in documents:
+                embedding_str = str(doc.embedding) if doc.embedding else None
+                cur.execute(f"""
+                    INSERT INTO {table_name} (id, content, embedding, metadata, content_hash, created_at)
+                    VALUES (%s, %s, %s, %s, %s, %s)
+                """, (doc.id, doc.content, embedding_str,
+                      str(doc.metadata) if doc.metadata else None,
+                      doc.content_hash, doc.created_at))
+                ids.append(doc.id)
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        ids = []
+        
+        with self._conn.cursor() as cur:
+            for doc in documents:
+                embedding_str = str(doc.embedding) if doc.embedding else None
+                cur.execute(f"""
+                    REPLACE INTO {table_name} (id, content, embedding, metadata, content_hash, created_at)
+                    VALUES (%s, %s, %s, %s, %s, %s)
+                """, (doc.id, doc.content, embedding_str,
+                      str(doc.metadata) if doc.metadata else None,
+                      doc.content_hash, doc.created_at))
+                ids.append(doc.id)
+        
+        return ids
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents using vector search."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        embedding_str = str(query_embedding)
+        
+        with self._conn.cursor() as cur:
+            cur.execute(f"""
+                SELECT id, content, metadata, content_hash, created_at,
+                       DOT_PRODUCT(embedding, %s) as score
+                FROM {table_name}
+                ORDER BY score DESC
+                LIMIT %s
+            """, (embedding_str, limit))
+            
+            documents = []
+            for row in cur.fetchall():
+                score = row[5] if len(row) > 5 else 0
+                if score_threshold and score < score_threshold:
+                    continue
+                
+                documents.append(KnowledgeDocument(
+                    id=row[0],
+                    content=row[1],
+                    metadata=eval(row[2]) if row[2] else None,
+                    content_hash=row[3],
+                    created_at=row[4]
+                ))
+            
+            return documents
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        placeholders = ','.join(['%s'] * len(ids))
+        
+        with self._conn.cursor() as cur:
+            cur.execute(f"""
+                SELECT id, content, metadata, content_hash, created_at
+                FROM {table_name}
+                WHERE id IN ({placeholders})
+            """, ids)
+            
+            return [
+                KnowledgeDocument(
+                    id=row[0],
+                    content=row[1],
+                    metadata=eval(row[2]) if row[2] else None,
+                    content_hash=row[3],
+                    created_at=row[4]
+                )
+                for row in cur.fetchall()
+            ]
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        
+        with self._conn.cursor() as cur:
+            if ids:
+                placeholders = ','.join(['%s'] * len(ids))
+                cur.execute(f"DELETE FROM {table_name} WHERE id IN ({placeholders})", ids)
+            else:
+                cur.execute(f"DELETE FROM {table_name}")
+            return cur.rowcount
+    
+    def count(self, collection: str) -> int:
+        """Count documents."""
+        self._init_client()
+        
+        table_name = f"{self.table_prefix}{collection}"
+        with self._conn.cursor() as cur:
+            cur.execute(f"SELECT COUNT(*) FROM {table_name}")
+            return cur.fetchone()[0]
+    
+    def close(self) -> None:
+        """Close the connection."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+            self._initialized = False

src/praisonai/praisonai/persistence/knowledge/surrealdb_vector.py

@@ -0,0 +1,309 @@
+"""
+SurrealDB Vector implementation of KnowledgeStore.
+
+Requires: surrealdb
+Install: pip install surrealdb
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class SurrealDBVectorKnowledgeStore(KnowledgeStore):
+    """
+    SurrealDB vector store for knowledge/RAG.
+    
+    Uses SurrealDB's vector capabilities.
+    
+    Example:
+        store = SurrealDBVectorKnowledgeStore(
+            url="ws://localhost:8000/rpc",
+            namespace="praisonai",
+            database="vectors"
+        )
+    """
+    
+    def __init__(
+        self,
+        url: str = "ws://localhost:8000/rpc",
+        namespace: str = "praisonai",
+        database: str = "vectors",
+        username: str = "root",
+        password: str = "root",
+        embedding_dim: int = 1536,
+    ):
+        """
+        Initialize SurrealDB Vector store.
+        
+        Args:
+            url: SurrealDB WebSocket URL
+            namespace: SurrealDB namespace
+            database: SurrealDB database
+            username: Authentication username
+            password: Authentication password
+            embedding_dim: Embedding dimension
+        """
+        self.url = url
+        self.namespace = namespace
+        self.database = database
+        self.username = username
+        self.password = password
+        self.embedding_dim = embedding_dim
+        
+        self._client = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize SurrealDB client lazily."""
+        if self._initialized:
+            return
+        
+        try:
+            from surrealdb import Surreal
+        except ImportError:
+            raise ImportError(
+                "surrealdb is required for SurrealDB Vector support. "
+                "Install with: pip install surrealdb"
+            )
+        
+        import asyncio
+        
+        async def connect():
+            client = Surreal(self.url)
+            await client.connect()
+            await client.signin({"user": self.username, "pass": self.password})
+            await client.use(self.namespace, self.database)
+            return client
+        
+        loop = asyncio.get_event_loop()
+        self._client = loop.run_until_complete(connect())
+        self._initialized = True
+    
+    def _run_async(self, coro):
+        """Run async coroutine synchronously."""
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(coro)
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create a collection (SurrealDB creates tables on insert)."""
+        self._init_client()
+        # SurrealDB creates tables automatically
+        logger.info(f"Collection '{name}' will be created on first insert")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete a collection."""
+        self._init_client()
+        try:
+            self._run_async(self._client.query(f"REMOVE TABLE {name}"))
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete collection {name}: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if collection exists."""
+        self._init_client()
+        try:
+            result = self._run_async(self._client.query(f"INFO FOR TABLE {name}"))
+            return bool(result)
+        except Exception:
+            return False
+    
+    def list_collections(self) -> List[str]:
+        """List all collections."""
+        self._init_client()
+        try:
+            result = self._run_async(self._client.query("INFO FOR DB"))
+            if result and len(result) > 0:
+                tables = result[0].get("result", {}).get("tables", {})
+                return list(tables.keys())
+            return []
+        except Exception as e:
+            logger.error(f"Failed to list collections: {e}")
+            return []
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        ids = []
+        for doc in documents:
+            record = {
+                "content": doc.content,
+                "embedding": doc.embedding,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            try:
+                result = self._run_async(
+                    self._client.create(f"{collection}:{doc.id}", record)
+                )
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to insert document {doc.id}: {e}")
+        
+        return ids
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents."""
+        self._init_client()
+        
+        ids = []
+        for doc in documents:
+            record = {
+                "content": doc.content,
+                "embedding": doc.embedding,
+                "metadata": doc.metadata or {},
+                "content_hash": doc.content_hash,
+                "created_at": doc.created_at,
+            }
+            
+            try:
+                self._run_async(
+                    self._client.update(f"{collection}:{doc.id}", record)
+                )
+                ids.append(doc.id)
+            except Exception as e:
+                logger.warning(f"Failed to upsert document {doc.id}: {e}")
+        
+        return ids
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents using vector search."""
+        self._init_client()
+        
+        # SurrealDB vector search query
+        embedding_str = str(query_embedding)
+        query = f"""
+            SELECT *, vector::similarity::cosine(embedding, {embedding_str}) AS score
+            FROM {collection}
+            ORDER BY score DESC
+            LIMIT {limit}
+        """
+        
+        try:
+            result = self._run_async(self._client.query(query))
+            
+            documents = []
+            if result and len(result) > 0:
+                for row in result[0].get("result", []):
+                    score = row.get("score", 0)
+                    if score_threshold and score < score_threshold:
+                        continue
+                    
+                    doc_id = str(row.get("id", "")).split(":")[-1]
+                    documents.append(KnowledgeDocument(
+                        id=doc_id,
+                        content=row.get("content", ""),
+                        embedding=row.get("embedding"),
+                        metadata={**(row.get("metadata") or {}), "score": score},
+                        content_hash=row.get("content_hash"),
+                        created_at=row.get("created_at", 0)
+                    ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        documents = []
+        for doc_id in ids:
+            try:
+                result = self._run_async(self._client.select(f"{collection}:{doc_id}"))
+                if result:
+                    row = result if isinstance(result, dict) else result[0]
+                    documents.append(KnowledgeDocument(
+                        id=doc_id,
+                        content=row.get("content", ""),
+                        embedding=row.get("embedding"),
+                        metadata=row.get("metadata"),
+                        content_hash=row.get("content_hash"),
+                        created_at=row.get("created_at", 0)
+                    ))
+            except Exception as e:
+                logger.warning(f"Failed to get document {doc_id}: {e}")
+        
+        return documents
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        count = 0
+        if ids:
+            for doc_id in ids:
+                try:
+                    self._run_async(self._client.delete(f"{collection}:{doc_id}"))
+                    count += 1
+                except Exception as e:
+                    logger.warning(f"Failed to delete {doc_id}: {e}")
+        else:
+            try:
+                self._run_async(self._client.query(f"DELETE FROM {collection}"))
+                count = -1  # Unknown count
+            except Exception as e:
+                logger.error(f"Failed to delete all: {e}")
+        
+        return count
+    
+    def count(self, collection: str) -> int:
+        """Count documents."""
+        self._init_client()
+        
+        try:
+            result = self._run_async(
+                self._client.query(f"SELECT count() FROM {collection} GROUP ALL")
+            )
+            if result and len(result) > 0:
+                return result[0].get("result", [{}])[0].get("count", 0)
+            return 0
+        except Exception as e:
+            logger.error(f"Count failed: {e}")
+            return 0
+    
+    def close(self) -> None:
+        """Close the connection."""
+        if self._client:
+            self._run_async(self._client.close())
+            self._client = None
+            self._initialized = False

src/praisonai/praisonai/persistence/knowledge/upstash_vector.py

@@ -0,0 +1,266 @@
+"""
+Upstash Vector implementation of KnowledgeStore.
+
+Requires: upstash-vector
+Install: pip install upstash-vector
+"""
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from .base import KnowledgeStore, KnowledgeDocument
+
+logger = logging.getLogger(__name__)
+
+
+class UpstashVectorKnowledgeStore(KnowledgeStore):
+    """
+    Upstash Vector store for knowledge/RAG.
+    
+    Uses Upstash's serverless vector database.
+    
+    Example:
+        store = UpstashVectorKnowledgeStore(
+            url="https://xxx.upstash.io",
+            token="your-token"
+        )
+    """
+    
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        token: Optional[str] = None,
+        embedding_dim: int = 1536,
+    ):
+        """
+        Initialize Upstash Vector store.
+        
+        Args:
+            url: Upstash Vector REST URL (or UPSTASH_VECTOR_REST_URL env)
+            token: Upstash Vector REST token (or UPSTASH_VECTOR_REST_TOKEN env)
+            embedding_dim: Embedding dimension
+        """
+        self.url = url or os.getenv("UPSTASH_VECTOR_REST_URL")
+        self.token = token or os.getenv("UPSTASH_VECTOR_REST_TOKEN")
+        self.embedding_dim = embedding_dim
+        
+        self._index = None
+        self._initialized = False
+    
+    def _init_client(self):
+        """Initialize Upstash client lazily."""
+        if self._initialized:
+            return
+        
+        if not self.url or not self.token:
+            raise ValueError(
+                "Upstash Vector requires url and token. "
+                "Set UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN env vars."
+            )
+        
+        try:
+            from upstash_vector import Index
+        except ImportError:
+            raise ImportError(
+                "upstash-vector is required for Upstash Vector support. "
+                "Install with: pip install upstash-vector"
+            )
+        
+        self._index = Index(url=self.url, token=self.token)
+        self._initialized = True
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: int = 1536,
+        distance: str = "cosine",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Create collection (Upstash uses namespaces)."""
+        self._init_client()
+        # Upstash Vector uses a single index with namespaces
+        logger.info(f"Using namespace '{name}' in Upstash Vector index")
+    
+    def delete_collection(self, name: str) -> bool:
+        """Delete all vectors in namespace."""
+        self._init_client()
+        try:
+            self._index.delete_namespace(name)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to delete namespace {name}: {e}")
+            return False
+    
+    def collection_exists(self, name: str) -> bool:
+        """Check if namespace has vectors."""
+        self._init_client()
+        try:
+            info = self._index.info()
+            namespaces = info.namespaces if hasattr(info, 'namespaces') else {}
+            return name in namespaces
+        except Exception:
+            return False
+    
+    def list_collections(self) -> List[str]:
+        """List all namespaces."""
+        self._init_client()
+        try:
+            info = self._index.info()
+            namespaces = info.namespaces if hasattr(info, 'namespaces') else {}
+            return list(namespaces.keys())
+        except Exception as e:
+            logger.error(f"Failed to list namespaces: {e}")
+            return []
+    
+    def insert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Insert documents."""
+        self._init_client()
+        
+        vectors = []
+        for doc in documents:
+            if not doc.embedding:
+                logger.warning(f"Document {doc.id} has no embedding, skipping")
+                continue
+            
+            vectors.append({
+                "id": doc.id,
+                "vector": doc.embedding,
+                "metadata": {
+                    "content": doc.content,
+                    **(doc.metadata or {}),
+                    "content_hash": doc.content_hash,
+                    "created_at": doc.created_at,
+                }
+            })
+        
+        if vectors:
+            self._index.upsert(vectors, namespace=collection)
+        
+        return [v["id"] for v in vectors]
+    
+    def upsert(
+        self,
+        collection: str,
+        documents: List[KnowledgeDocument]
+    ) -> List[str]:
+        """Upsert documents (same as insert for Upstash)."""
+        return self.insert(collection, documents)
+    
+    def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        limit: int = 5,
+        filters: Optional[Dict[str, Any]] = None,
+        score_threshold: Optional[float] = None
+    ) -> List[KnowledgeDocument]:
+        """Search for similar documents."""
+        self._init_client()
+        
+        try:
+            results = self._index.query(
+                vector=query_embedding,
+                top_k=limit,
+                include_metadata=True,
+                namespace=collection,
+                filter=filters
+            )
+            
+            documents = []
+            for result in results:
+                score = result.score if hasattr(result, 'score') else 0
+                if score_threshold and score < score_threshold:
+                    continue
+                
+                metadata = result.metadata if hasattr(result, 'metadata') else {}
+                content = metadata.pop("content", "") if metadata else ""
+                
+                documents.append(KnowledgeDocument(
+                    id=result.id,
+                    content=content,
+                    metadata={**metadata, "score": score},
+                    content_hash=metadata.get("content_hash") if metadata else None,
+                    created_at=metadata.get("created_at", 0) if metadata else 0
+                ))
+            
+            return documents
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            return []
+    
+    def get(
+        self,
+        collection: str,
+        ids: List[str]
+    ) -> List[KnowledgeDocument]:
+        """Get documents by IDs."""
+        self._init_client()
+        
+        documents = []
+        try:
+            results = self._index.fetch(ids, include_metadata=True, namespace=collection)
+            
+            for result in results:
+                if result:
+                    metadata = result.metadata if hasattr(result, 'metadata') else {}
+                    content = metadata.pop("content", "") if metadata else ""
+                    
+                    documents.append(KnowledgeDocument(
+                        id=result.id,
+                        content=content,
+                        embedding=result.vector if hasattr(result, 'vector') else None,
+                        metadata=metadata,
+                        content_hash=metadata.get("content_hash") if metadata else None,
+                        created_at=metadata.get("created_at", 0) if metadata else 0
+                    ))
+        except Exception as e:
+            logger.error(f"Fetch failed: {e}")
+        
+        return documents
+    
+    def delete(
+        self,
+        collection: str,
+        ids: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None
+    ) -> int:
+        """Delete documents."""
+        self._init_client()
+        
+        try:
+            if ids:
+                self._index.delete(ids, namespace=collection)
+                return len(ids)
+            elif filters:
+                # Upstash doesn't support filter-based delete directly
+                logger.warning("Filter-based delete not supported, use IDs")
+                return 0
+            else:
+                self._index.delete_namespace(collection)
+                return -1  # Unknown count
+        except Exception as e:
+            logger.error(f"Delete failed: {e}")
+            return 0
+    
+    def count(self, collection: str) -> int:
+        """Count documents in namespace."""
+        self._init_client()
+        
+        try:
+            info = self._index.info()
+            namespaces = info.namespaces if hasattr(info, 'namespaces') else {}
+            ns_info = namespaces.get(collection, {})
+            return ns_info.get("vector_count", 0) if isinstance(ns_info, dict) else 0
+        except Exception as e:
+            logger.error(f"Count failed: {e}")
+            return 0
+    
+    def close(self) -> None:
+        """Close the client."""
+        self._index = None
+        self._initialized = False

src/praisonai/praisonai/persistence/state/async_mongodb.py

@@ -0,0 +1,200 @@
+"""
+Async MongoDB implementation of StateStore.
+
+Requires: motor
+Install: pip install motor
+"""
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from .base import StateStore
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncMongoDBStateStore(StateStore):
+    """
+    Async MongoDB state store using motor.
+    
+    Provides high-performance async database operations.
+    
+    Example:
+        store = AsyncMongoDBStateStore(
+            url="mongodb://localhost:27017",
+            database="praisonai"
+        )
+        await store.init()
+    """
+    
+    def __init__(
+        self,
+        url: str = "mongodb://localhost:27017",
+        database: str = "praisonai",
+        collection: str = "state",
+    ):
+        """
+        Initialize async MongoDB store.
+        
+        Args:
+            url: MongoDB connection URL
+            database: Database name
+            collection: Collection name
+        """
+        self.url = url
+        self.database_name = database
+        self.collection_name = collection
+        self._client = None
+        self._db = None
+        self._collection = None
+        self._initialized = False
+    
+    async def init(self):
+        """Initialize connection."""
+        if self._initialized:
+            return
+        
+        try:
+            from motor.motor_asyncio import AsyncIOMotorClient
+        except ImportError:
+            raise ImportError(
+                "motor is required for async MongoDB support. "
+                "Install with: pip install motor"
+            )
+        
+        self._client = AsyncIOMotorClient(self.url)
+        self._db = self._client[self.database_name]
+        self._collection = self._db[self.collection_name]
+        
+        # Create TTL index for expiration
+        await self._collection.create_index("expires_at", expireAfterSeconds=0)
+        
+        self._initialized = True
+    
+    async def async_get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Get state by key asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        doc = await self._collection.find_one({"_id": key})
+        if doc:
+            # Check TTL manually (in case index hasn't cleaned up yet)
+            if "expires_at" in doc and doc["expires_at"]:
+                if time.time() > doc["expires_at"]:
+                    await self.async_delete(key)
+                    return None
+            
+            # Remove internal fields
+            result = dict(doc)
+            result.pop("_id", None)
+            result.pop("expires_at", None)
+            return result.get("value", result)
+        return None
+    
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Sync wrapper for get."""
+        return asyncio.get_event_loop().run_until_complete(self.async_get(key))
+    
+    async def async_set(self, key: str, value: Dict[str, Any], ttl: Optional[int] = None) -> bool:
+        """Set state by key with optional TTL asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        doc = {
+            "_id": key,
+            "value": value,
+            "updated_at": time.time(),
+        }
+        
+        if ttl:
+            doc["expires_at"] = time.time() + ttl
+        
+        try:
+            await self._collection.replace_one(
+                {"_id": key},
+                doc,
+                upsert=True
+            )
+            return True
+        except Exception as e:
+            logger.error(f"Error setting state {key}: {e}")
+            return False
+    
+    def set(self, key: str, value: Dict[str, Any], ttl: Optional[int] = None) -> bool:
+        """Sync wrapper for set."""
+        return asyncio.get_event_loop().run_until_complete(self.async_set(key, value, ttl))
+    
+    async def async_delete(self, key: str) -> bool:
+        """Delete state by key asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        result = await self._collection.delete_one({"_id": key})
+        return result.deleted_count > 0
+    
+    def delete(self, key: str) -> bool:
+        """Sync wrapper for delete."""
+        return asyncio.get_event_loop().run_until_complete(self.async_delete(key))
+    
+    async def async_exists(self, key: str) -> bool:
+        """Check if key exists asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        count = await self._collection.count_documents({"_id": key}, limit=1)
+        return count > 0
+    
+    def exists(self, key: str) -> bool:
+        """Sync wrapper for exists."""
+        return asyncio.get_event_loop().run_until_complete(self.async_exists(key))
+    
+    async def async_list_keys(self, prefix: Optional[str] = None) -> List[str]:
+        """List all keys with optional prefix filter asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        query = {}
+        if prefix:
+            query["_id"] = {"$regex": f"^{prefix}"}
+        
+        cursor = self._collection.find(query, {"_id": 1})
+        keys = []
+        async for doc in cursor:
+            keys.append(doc["_id"])
+        return keys
+    
+    def list_keys(self, prefix: Optional[str] = None) -> List[str]:
+        """Sync wrapper for list_keys."""
+        return asyncio.get_event_loop().run_until_complete(self.async_list_keys(prefix))
+    
+    async def async_clear(self, prefix: Optional[str] = None) -> int:
+        """Clear all keys with optional prefix filter asynchronously."""
+        if not self._initialized:
+            await self.init()
+        
+        query = {}
+        if prefix:
+            query["_id"] = {"$regex": f"^{prefix}"}
+        
+        result = await self._collection.delete_many(query)
+        return result.deleted_count
+    
+    def clear(self, prefix: Optional[str] = None) -> int:
+        """Sync wrapper for clear."""
+        return asyncio.get_event_loop().run_until_complete(self.async_clear(prefix))
+    
+    async def async_close(self) -> None:
+        """Close the connection."""
+        if self._client:
+            self._client.close()
+            self._client = None
+            self._db = None
+            self._collection = None
+            self._initialized = False
+    
+    def close(self) -> None:
+        """Sync wrapper for close."""
+        if self._client:
+            asyncio.get_event_loop().run_until_complete(self.async_close())

src/praisonai/praisonai/persistence/state/gcs.py

@@ -0,0 +1,155 @@
+"""
+Google Cloud Storage implementation of StateStore.
+
+Requires: google-cloud-storage
+Install: pip install google-cloud-storage
+"""
+
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from .base import StateStore
+
+logger = logging.getLogger(__name__)
+
+
+class GCSStateStore(StateStore):
+    """
+    Google Cloud Storage-based state store.
+    
+    Stores state as JSON objects in GCS buckets.
+    
+    Example:
+        store = GCSStateStore(
+            bucket_name="my-praisonai-state",
+            prefix="state/"
+        )
+    """
+    
+    def __init__(
+        self,
+        bucket_name: str,
+        prefix: str = "praisonai_state/",
+        project: Optional[str] = None,
+        credentials_path: Optional[str] = None,
+    ):
+        """
+        Initialize GCS state store.
+        
+        Args:
+            bucket_name: GCS bucket name
+            prefix: Object prefix for state keys
+            project: GCP project ID (optional)
+            credentials_path: Path to service account JSON (optional)
+        """
+        try:
+            from google.cloud import storage
+            if credentials_path:
+                self._client = storage.Client.from_service_account_json(
+                    credentials_path, project=project
+                )
+            else:
+                self._client = storage.Client(project=project)
+        except ImportError:
+            raise ImportError(
+                "google-cloud-storage is required for GCS support. "
+                "Install with: pip install google-cloud-storage"
+            )
+        
+        self.bucket_name = bucket_name
+        self.prefix = prefix
+        self._bucket = self._client.bucket(bucket_name)
+    
+    def _key_to_path(self, key: str) -> str:
+        """Convert key to GCS object path."""
+        return f"{self.prefix}{key}.json"
+    
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Get state by key."""
+        try:
+            blob = self._bucket.blob(self._key_to_path(key))
+            if blob.exists():
+                data = json.loads(blob.download_as_text())
+                # Check TTL
+                if "_ttl_expires" in data:
+                    if time.time() > data["_ttl_expires"]:
+                        self.delete(key)
+                        return None
+                    del data["_ttl_expires"]
+                return data
+            return None
+        except Exception as e:
+            logger.error(f"Error getting state {key}: {e}")
+            return None
+    
+    def set(self, key: str, value: Dict[str, Any], ttl: Optional[int] = None) -> bool:
+        """Set state by key with optional TTL in seconds."""
+        try:
+            data = value.copy()
+            if ttl:
+                data["_ttl_expires"] = time.time() + ttl
+            
+            blob = self._bucket.blob(self._key_to_path(key))
+            blob.upload_from_string(
+                json.dumps(data, default=str),
+                content_type="application/json"
+            )
+            return True
+        except Exception as e:
+            logger.error(f"Error setting state {key}: {e}")
+            return False
+    
+    def delete(self, key: str) -> bool:
+        """Delete state by key."""
+        try:
+            blob = self._bucket.blob(self._key_to_path(key))
+            if blob.exists():
+                blob.delete()
+                return True
+            return False
+        except Exception as e:
+            logger.error(f"Error deleting state {key}: {e}")
+            return False
+    
+    def exists(self, key: str) -> bool:
+        """Check if key exists."""
+        try:
+            blob = self._bucket.blob(self._key_to_path(key))
+            return blob.exists()
+        except Exception:
+            return False
+    
+    def list_keys(self, prefix: Optional[str] = None) -> List[str]:
+        """List all keys with optional prefix filter."""
+        try:
+            search_prefix = self.prefix
+            if prefix:
+                search_prefix = f"{self.prefix}{prefix}"
+            
+            blobs = self._client.list_blobs(self.bucket_name, prefix=search_prefix)
+            keys = []
+            for blob in blobs:
+                # Remove prefix and .json suffix
+                key = blob.name[len(self.prefix):]
+                if key.endswith(".json"):
+                    key = key[:-5]
+                keys.append(key)
+            return keys
+        except Exception as e:
+            logger.error(f"Error listing keys: {e}")
+            return []
+    
+    def clear(self, prefix: Optional[str] = None) -> int:
+        """Clear all keys with optional prefix filter."""
+        keys = self.list_keys(prefix)
+        count = 0
+        for key in keys:
+            if self.delete(key):
+                count += 1
+        return count
+    
+    def close(self) -> None:
+        """Close the store."""
+        self._client.close()

src/praisonai/praisonai/version.py

@@ -1 +1 @@
-__version__ = "2.4.2"
+__version__ = "2.5.0"

src/praisonai/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "rich>=13.7",
     "markdown>=3.5",
     "pyparsing>=3.0.0",
-    "praisonaiagents>=0.2.1",
+    "praisonaiagents>=0.3.0",
     "python-dotenv>=0.19.0",
     "instructor>=1.3.3",
     "PyYAML>=6.0",

src/praisonai/tests/unit/test_db_deprecation.py

@@ -0,0 +1,162 @@
+"""
+Tests for db import deprecation warnings.
+
+These tests verify that:
+1. New simplified imports work: from praisonaiagents import db
+2. New simplified imports work: from praisonai import db
+3. Old imports emit DeprecationWarning: from praisonai.db import PraisonDB
+"""
+
+import warnings
+import pytest
+
+
+class TestNewDbImports:
+    """Test that new simplified db imports work correctly."""
+    
+    def test_import_db_from_praisonaiagents(self):
+        """Test: from praisonaiagents import db"""
+        from praisonaiagents import db
+        assert db is not None
+        assert hasattr(db, 'PraisonDB')
+        assert callable(db)  # db(...) should work as shortcut
+    
+    def test_import_db_from_praisonai(self):
+        """Test: from praisonai import db
+        
+        Note: This returns the praisonai.db module (for backwards compat).
+        The recommended pattern is: from praisonaiagents import db
+        """
+        from praisonai import db
+        assert db is not None
+        # praisonai.db is a module with lazy-loaded classes
+        assert hasattr(db, 'PraisonDB')
+    
+    def test_db_callable_shortcut(self):
+        """Test that db(...) works as shortcut for db.PraisonDB(...)"""
+        from praisonaiagents import db
+        # Should not raise - just creates the adapter
+        # (actual DB connection is lazy)
+        instance = db(database_url="sqlite:///test.db")
+        assert instance is not None
+    
+    def test_import_agent_and_db_together(self):
+        """Test: from praisonaiagents import Agent, db"""
+        from praisonaiagents import Agent, db
+        assert Agent is not None
+        assert db is not None
+    
+    def test_import_all_common_symbols(self):
+        """Test: from praisonaiagents import Agent, Agents, Task, tool, db"""
+        from praisonaiagents import Agent, Agents, Task, tool, db
+        assert Agent is not None
+        assert Agents is not None
+        assert Task is not None
+        assert tool is not None
+        assert db is not None
+
+
+class TestDeprecationWarnings:
+    """Test that old imports emit DeprecationWarning."""
+    
+    def test_praisondb_import_warns(self):
+        """Test: from praisonai.db import PraisonDB emits warning"""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from praisonai.db import PraisonDB
+            
+            # Should have at least one deprecation warning
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+            
+            # Check warning message content
+            msg = str(deprecation_warnings[0].message)
+            assert "deprecated" in msg.lower()
+            assert "praisonaiagents" in msg or "praisonai" in msg
+    
+    def test_postgresdb_import_warns(self):
+        """Test: from praisonai.db import PostgresDB emits warning"""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from praisonai.db import PostgresDB
+            
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+    
+    def test_sqlitedb_import_warns(self):
+        """Test: from praisonai.db import SQLiteDB emits warning"""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from praisonai.db import SQLiteDB
+            
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+    
+    def test_redisdb_import_warns(self):
+        """Test: from praisonai.db import RedisDB emits warning"""
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from praisonai.db import RedisDB
+            
+            deprecation_warnings = [
+                x for x in w 
+                if issubclass(x.category, DeprecationWarning)
+            ]
+            assert len(deprecation_warnings) >= 1
+
+
+class TestBackwardsCompatibility:
+    """Test that old imports still work (just with warnings)."""
+    
+    def test_praisondb_still_works(self):
+        """Old PraisonDB import should still work."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            from praisonai.db import PraisonDB
+            
+            # Should be usable
+            instance = PraisonDB(database_url="sqlite:///test.db")
+            assert instance is not None
+    
+    def test_postgresdb_still_works(self):
+        """Old PostgresDB import should still work."""
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            from praisonai.db import PostgresDB
+            
+            # Should be a class
+            assert PostgresDB is not None
+
+
+class TestNoHeavyImports:
+    """Test that db import doesn't load heavy dependencies."""
+    
+    def test_db_import_is_lightweight(self):
+        """Importing db should not import heavy DB clients."""
+        import sys
+        
+        # Clear any cached imports
+        modules_before = set(sys.modules.keys())
+        
+        from praisonaiagents import db
+        
+        modules_after = set(sys.modules.keys())
+        new_modules = modules_after - modules_before
+        
+        # Should not have imported heavy DB clients
+        heavy_modules = ['psycopg2', 'pymysql', 'redis', 'qdrant_client']
+        for heavy in heavy_modules:
+            assert heavy not in new_modules, f"Heavy module {heavy} was imported"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/praisonai/uv.lock

@@ -4197,7 +4197,7 @@ requires-dist = [
     { name = "praisonai-tools", marker = "extra == 'autogen'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'autogen-v4'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'crewai'", specifier = ">=0.0.22" },
-    { name = "praisonaiagents", specifier = ">=0.2.1" },
+    { name = "praisonaiagents", specifier = ">=0.3.0" },
     { name = "pyautogen", marker = "extra == 'autogen'", specifier = "==0.2.29" },
     { name = "pydantic", marker = "extra == 'chat'", specifier = "<=2.10.1" },
     { name = "pydantic", marker = "extra == 'code'", specifier = "<=2.10.1" },
@@ -4252,7 +4252,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.2.1"
+version = "0.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -4261,9 +4261,9 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/24/58/16b6bd1bb1c9b3932a5e106f72ba1ca2d23b2dad87b45fb0e912b61ab9f7/praisonaiagents-0.2.1.tar.gz", hash = "sha256:7d392c635359696d22ecd92acf90bd2dd1ac24282211ef651612f3d194ea06e5", size = 730640, upload-time = "2025-12-24T14:57:46.426Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/fc/79/08c9f2d8c12f9521f9fcc3df2510bd0d09377fd68b27413c64e501c1d47b/praisonaiagents-0.3.0.tar.gz", hash = "sha256:6fac4b754ec924ba804ef09ebef9919f276861d9f6d8c66cc33721063cb0d04c", size = 741299, upload-time = "2025-12-26T02:18:18.235Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/07/d5/a1776b1ad798dce02a896de62f693cee0f6556ac6a2cf06598bf114041a1/praisonaiagents-0.2.1-py3-none-any.whl", hash = "sha256:cf6394986a9d3e701cca49b3e57f5798fdb9066f689c61633e6bdc8421fa995b", size = 678483, upload-time = "2025-12-24T14:57:44.376Z" },
+    { url = "https://files.pythonhosted.org/packages/18/4e/2165feb9897d9b17522d7653b9111e40262bcf5172fc6fb549e5f0b2413f/praisonaiagents-0.3.0-py3-none-any.whl", hash = "sha256:fdbe3cf290e274ffd518b932d0ad8fd516b1600324bde2bf1970c5efd26c4292", size = 689391, upload-time = "2025-12-26T02:18:16.247Z" },
 ]
 
 [[package]]