Release v3.9.5

- MemoryConfig from praisonaiagents.config (not memory)
- FileMemory from praisonaiagents.memory
- OutputConfig, ExecutionConfig, PlanningConfig from config

.github/workflows/benchmark.yml

@@ -1,145 +0,0 @@
-name: Performance Benchmarks
-
-on:
-  workflow_dispatch:
-    inputs:
-      iterations:
-        description: 'Number of benchmark iterations'
-        required: false
-        default: '100'
-      fail_on_regression:
-        description: 'Fail if performance regresses'
-        required: false
-        default: 'true'
-
-jobs:
-  benchmark:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e src/praisonai-agents[all]
-          pip install agno crewai langgraph
-
-      - name: Run Import Time Benchmark
-        id: import_time
-        run: |
-          cd src/praisonai-agents
-          python benchmarks/import_time.py 2>&1 | tee import_time_output.txt
-          
-          # Extract import time
-          IMPORT_TIME=$(grep -oP 'Median:\s+\K[\d.]+' import_time_output.txt || echo "0")
-          echo "import_time=$IMPORT_TIME" >> $GITHUB_OUTPUT
-          
-          # Check threshold (200ms)
-          if (( $(echo "$IMPORT_TIME > 200" | bc -l) )); then
-            echo "::warning::Import time ${IMPORT_TIME}ms exceeds 200ms threshold"
-            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
-              echo "import_passed=false" >> $GITHUB_OUTPUT
-            fi
-          else
-            echo "import_passed=true" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Run Memory Usage Benchmark
-        id: memory
-        run: |
-          cd src/praisonai-agents
-          python benchmarks/memory_usage.py 2>&1 | tee memory_output.txt
-          
-          # Extract peak memory
-          PEAK_MEMORY=$(grep -oP 'Peak:\s+\K[\d.]+' memory_output.txt || echo "0")
-          echo "peak_memory=$PEAK_MEMORY" >> $GITHUB_OUTPUT
-          
-          # Check threshold (30MB)
-          if (( $(echo "$PEAK_MEMORY > 30" | bc -l) )); then
-            echo "::warning::Memory usage ${PEAK_MEMORY}MB exceeds 30MB threshold"
-            if [ "${{ inputs.fail_on_regression }}" == "true" ]; then
-              echo "memory_passed=false" >> $GITHUB_OUTPUT
-            fi
-          else
-            echo "memory_passed=true" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Run Simple Benchmark
-        id: simple
-        run: |
-          cd src/praisonai-agents
-          python benchmarks/simple_benchmark.py 2>&1 | tee simple_output.txt
-          
-          # Extract PraisonAI time
-          PRAISON_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' simple_output.txt | head -1 || echo "0")
-          echo "praison_time=$PRAISON_TIME" >> $GITHUB_OUTPUT
-
-      - name: Run Tools Benchmark
-        id: tools
-        run: |
-          cd src/praisonai-agents
-          python benchmarks/tools_benchmark.py 2>&1 | tee tools_output.txt
-          
-          # Extract PraisonAI time with tools
-          PRAISON_TOOLS_TIME=$(grep -oP 'PraisonAI\s+\K[\d.]+' tools_output.txt | head -1 || echo "0")
-          echo "praison_tools_time=$PRAISON_TOOLS_TIME" >> $GITHUB_OUTPUT
-
-      - name: Run Parameter Impact Benchmark
-        id: param_impact
-        run: |
-          cd src/praisonai-agents
-          python benchmarks/param_impact_benchmark.py --no-save --iterations ${{ inputs.iterations }} 2>&1 | tee param_impact_output.txt
-
-      - name: Check Lazy Imports
-        id: lazy_imports
-        run: |
-          cd src/praisonai-agents
-          python -c "
-          import sys
-          from praisonaiagents import Agent
-          agent = Agent(name='Test', output='silent')
-          
-          # Check litellm is NOT loaded
-          if 'litellm' in sys.modules:
-              print('FAIL: litellm loaded during silent agent creation')
-              exit(1)
-          else:
-              print('PASS: litellm not loaded (lazy import working)')
-          "
-
-      - name: Generate Benchmark Summary
-        if: always()
-        run: |
-          echo "## Performance Benchmark Results" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "| Metric | Value | Threshold | Status |" >> $GITHUB_STEP_SUMMARY
-          echo "|--------|-------|-----------|--------|" >> $GITHUB_STEP_SUMMARY
-          echo "| Import Time | ${{ steps.import_time.outputs.import_time }}ms | <200ms | ${{ steps.import_time.outputs.import_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| Peak Memory | ${{ steps.memory.outputs.peak_memory }}MB | <30MB | ${{ steps.memory.outputs.memory_passed == 'true' && '✅' || '❌' }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| Agent Instantiation | ${{ steps.simple.outputs.praison_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Agent with Tools | ${{ steps.tools.outputs.praison_tools_time }}μs | - | ℹ️ |" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Lazy Import Check" >> $GITHUB_STEP_SUMMARY
-          echo "✅ litellm not loaded during silent agent creation" >> $GITHUB_STEP_SUMMARY
-
-      - name: Fail on Regression
-        if: inputs.fail_on_regression == 'true'
-        run: |
-          if [ "${{ steps.import_time.outputs.import_passed }}" == "false" ]; then
-            echo "::error::Import time regression detected"
-            exit 1
-          fi
-          if [ "${{ steps.memory.outputs.memory_passed }}" == "false" ]; then
-            echo "::error::Memory usage regression detected"
-            exit 1
-          fi
-          echo "All performance checks passed!"

.github/workflows/update-parity-tracker.yml

@@ -1,58 +0,0 @@
-name: Update Feature Parity Tracker
-
-on:
-  push:
-    branches: [ "main" ]
-    paths:
-      - 'src/praisonai-agents/praisonaiagents/**/*.py'
-      - 'src/praisonai-ts/src/**/*.ts'
-      - 'src/praisonai-rust/src/**/*.rs'
-      - '.github/workflows/update-parity-tracker.yml'
-
-permissions:
-  contents: write
-
-jobs:
-  update-parity-tracker:
-    runs-on: ubuntu-latest
-    
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        ref: main
-        persist-credentials: true
-        fetch-depth: 0
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.11'
-
-    - name: Generate parity trackers
-      run: |
-        cd $GITHUB_WORKSPACE
-        python3 src/praisonai/scripts/generate_parity_tracker.py
-        
-    - name: Check for changes
-      id: check_changes
-      run: |
-        if git diff --quiet src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md src/praisonai-rust/FEATURE_PARITY_TRACKER.json src/praisonai-rust/PARITY.md 2>/dev/null; then
-          echo "changes=false" >> $GITHUB_OUTPUT
-          echo "No changes to parity trackers"
-        else
-          echo "changes=true" >> $GITHUB_OUTPUT
-          echo "Parity trackers have been updated"
-          git diff src/praisonai-ts/FEATURE_PARITY_TRACKER.json | head -50
-        fi
-
-    - name: Commit and push changes
-      if: steps.check_changes.outputs.changes == 'true'
-      uses: stefanzweifel/git-auto-commit-action@v5
-      with:
-        commit_message: "docs: auto-update feature parity trackers [skip ci]"
-        file_pattern: 'src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md src/praisonai-rust/FEATURE_PARITY_TRACKER.json src/praisonai-rust/PARITY.md'
-        commit_user_name: "github-actions[bot]"
-        commit_user_email: "41898282+github-actions[bot]@users.noreply.github.com"
-        commit_author: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
-

.gitignore

@@ -84,11 +84,4 @@ issue_details.json
 .mcpregistry_*
 
 *.log
-.internal
-.praisonai
-
-# Rust / Cargo
-target/
-Cargo.lock
-**/*.rs.bk
-*.pdb
+.internal

README.md

@@ -137,6 +137,7 @@ PraisonAI Agents is the **fastest AI agent framework** for agent instantiation.
 | PraisonAI (LiteLLM) | 7.56 | 2.00x |
 | PydanticAI | 226.94 | 60.16x |
 | LangGraph | 4,558.71 | 1,209x |
+| CrewAI | 15,607.92 | 4,138x |
 
 <details>
 <summary>Run benchmarks yourself</summary>

docker/.env.template

@@ -13,12 +13,6 @@ GOOGLE_API_KEY=your_google_api_key_here
 GROQ_API_KEY=your_groq_api_key_here
 COHERE_API_KEY=your_cohere_api_key_here
 
-# Bot Tokens (for messaging bot services)
-SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
-SLACK_APP_TOKEN=xapp-your-slack-app-token
-DISCORD_BOT_TOKEN=your-discord-bot-token
-TELEGRAM_BOT_TOKEN=your-telegram-bot-token
-
 # Optional: Service Configuration
 FLASK_ENV=development
 CHAINLIT_HOST=0.0.0.0

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>=4.4.4" \
+    "praisonai>=3.9.5" \
     "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>=4.4.4" \
+    "praisonai>=3.9.5" \
     "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>=4.4.4" \
+    "praisonai>=3.9.5" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

docker/bots/.env.template

@@ -1,15 +0,0 @@
-# Bot Environment Variables
-# Copy to .env and fill in your values
-
-# Required: LLM API Key
-OPENAI_API_KEY=your_openai_api_key_here
-
-# Slack Bot (Socket Mode)
-SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
-SLACK_APP_TOKEN=xapp-your-slack-app-token
-
-# Discord Bot
-DISCORD_BOT_TOKEN=your-discord-bot-token
-
-# Telegram Bot
-TELEGRAM_BOT_TOKEN=your-telegram-bot-token

docker/bots/Dockerfile

@@ -1,42 +0,0 @@
-# Dockerfile for PraisonAI Slack Bot
-# Secrets are passed at runtime via environment variables
-
-FROM python:3.11-slim
-
-WORKDIR /app
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    gcc \
-    python3-dev \
-    curl \
-    git \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create praison config directory
-RUN mkdir -p /root/.praison
-
-# Install praisonai with bot dependencies
-RUN pip install --no-cache-dir \
-    praisonai \
-    slack-bolt \
-    slack-sdk \
-    "discord.py>=2.0.0" \
-    "python-telegram-bot>=20.0"
-
-# Set environment variables for directory management
-ENV PRAISON_CONFIG_DIR=/root/.praison
-ENV DOCKER_CONTAINER=true
-
-# Bot tokens should be passed at runtime (not baked into image)
-# SLACK_BOT_TOKEN=xoxb-...
-# SLACK_APP_TOKEN=xapp-...
-
-# Optional: Copy custom agent configuration
-# COPY agent.yaml /app/agent.yaml
-
-# Expose no ports - Socket Mode doesn't need them
-# For webhook mode, expose port 3000
-
-# Default command - tokens from environment
-CMD ["praisonai", "bot", "slack"]

docker/bots/README.md

@@ -1,66 +0,0 @@
-# PraisonAI Bot Docker Deployment
-
-Deploy Slack, Discord, or Telegram bots using Docker.
-
-## Quick Start
-
-```bash
-# 1. Copy environment template
-cp .env.template .env
-
-# 2. Edit .env with your tokens
-nano .env
-
-# 3. Run specific bot
-docker compose up slack-bot -d
-
-# Or run all bots
-docker compose up -d
-```
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPENAI_API_KEY` | Yes | LLM API key |
-| `SLACK_BOT_TOKEN` | For Slack | Bot token (xoxb-...) |
-| `SLACK_APP_TOKEN` | For Slack | App token (xapp-...) |
-| `DISCORD_BOT_TOKEN` | For Discord | Bot token |
-| `TELEGRAM_BOT_TOKEN` | For Telegram | Bot token |
-
-## Slack Setup
-
-1. Create app at https://api.slack.com/apps
-2. Enable **Socket Mode** → Generate App-Level Token with `connections:write`
-3. Add **OAuth Scopes**: `chat:write`, `app_mentions:read`, `im:history`
-4. Enable **Event Subscriptions** → Subscribe to `app_mention`, `message.im`
-5. **Install to Workspace**
-6. Copy Bot Token and App Token to `.env`
-
-## Commands
-
-```bash
-# Start Slack bot
-docker compose up slack-bot -d
-
-# View logs
-docker compose logs -f slack-bot
-
-# Stop bot
-docker compose down slack-bot
-
-# Rebuild after updates
-docker compose build --no-cache slack-bot
-```
-
-## Custom Agent Configuration
-
-Mount your agent config:
-
-```yaml
-services:
-  slack-bot:
-    volumes:
-      - ./agent.yaml:/app/agent.yaml
-    command: ["praisonai", "bot", "slack", "--agent", "/app/agent.yaml"]
-```

docker/bots/docker-compose.yml

@@ -1,53 +0,0 @@
-version: '3.8'
-
-# PraisonAI Bot Services
-# Run specific bots: docker compose up slack-bot
-# Run all bots: docker compose up
-
-services:
-  # Slack Bot
-  slack-bot:
-    build:
-      context: ../..
-      dockerfile: docker/bots/Dockerfile
-    volumes:
-      - praison_data:/root/.praison
-    environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}
-      SLACK_APP_TOKEN: ${SLACK_APP_TOKEN}
-      PRAISON_CONFIG_DIR: /root/.praison
-    command: [ "praisonai", "bot", "slack" ]
-    restart: unless-stopped
-
-  # Discord Bot
-  discord-bot:
-    build:
-      context: ../..
-      dockerfile: docker/bots/Dockerfile
-    volumes:
-      - praison_data:/root/.praison
-    environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN}
-      PRAISON_CONFIG_DIR: /root/.praison
-    command: [ "praisonai", "bot", "discord" ]
-    restart: unless-stopped
-
-  # Telegram Bot
-  telegram-bot:
-    build:
-      context: ../..
-      dockerfile: docker/bots/Dockerfile
-    volumes:
-      - praison_data:/root/.praison
-    environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
-      PRAISON_CONFIG_DIR: /root/.praison
-    command: [ "praisonai", "bot", "telegram" ]
-    restart: unless-stopped
-
-volumes:
-  praison_data:
-    driver: local

docker/docker-compose.yml

@@ -22,7 +22,7 @@ services:
       CHAINLIT_DB_DIR: /root/.praison
     command: praisonai ui --host 0.0.0.0
     healthcheck:
-      test: [ "CMD", "curl", "-f", "http://localhost:8082" ]
+      test: ["CMD", "curl", "-f", "http://localhost:8082"]
       interval: 10s
       timeout: 5s
       retries: 3
@@ -49,7 +49,7 @@ services:
       CHAINLIT_DB_DIR: /root/.praison
     command: praisonai chat --host 0.0.0.0 --port 8083
     healthcheck:
-      test: [ "CMD", "curl", "-f", "http://localhost:8083" ]
+      test: ["CMD", "curl", "-f", "http://localhost:8083"]
       interval: 10s
       timeout: 5s
       retries: 3
@@ -69,7 +69,7 @@ services:
       OPENAI_API_KEY: ${OPENAI_API_KEY}
       PRAISON_CONFIG_DIR: /root/.praison
     healthcheck:
-      test: [ "CMD", "curl", "-f", "http://localhost:8080/health" ]
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
       interval: 10s
       timeout: 5s
       retries: 3
@@ -89,7 +89,6 @@ services:
       PRAISON_CONFIG_DIR: /root/.praison
     networks:
       - praison_network
-  # For bot services (Slack, Discord, Telegram), see docker/bots/
 
 volumes:
   praison_data:
@@ -97,4 +96,4 @@ volumes:
 
 networks:
   praison_network:
-    driver: bridge
+    driver: bridge

examples/capabilities/embeddings_example.py

@@ -2,14 +2,12 @@
 Embeddings Capability Example
 
 Demonstrates text embedding generation using PraisonAI capabilities.
-Both `embed` and `embedding` work identically - use whichever you prefer.
 """
 
-from praisonai import embed, embedding  # Both work from top-level
-# Or: from praisonai.capabilities import embed, embedding
+from praisonai.capabilities import embed
 
-# Single text embedding using embed()
-print("=== Single Text Embedding (using embed) ===")
+# Single text embedding
+print("=== Single Text Embedding ===")
 result = embed(
     input="Hello, world!",
     model="text-embedding-3-small"
@@ -18,14 +16,6 @@ print(f"Embedding dimensions: {len(result.embeddings[0])}")
 print(f"First 5 values: {result.embeddings[0][:5]}")
 print(f"Usage: {result.usage}")
 
-# Same thing using embedding() alias
-print("\n=== Single Text Embedding (using embedding alias) ===")
-result = embedding(
-    input="Hello, world!",
-    model="text-embedding-3-small"
-)
-print(f"Embedding dimensions: {len(result.embeddings[0])}")
-
 # Multiple text embeddings
 print("\n=== Multiple Text Embeddings ===")
 result = embed(
@@ -35,12 +25,3 @@ result = embed(
 print(f"Number of embeddings: {len(result.embeddings)}")
 for i, emb in enumerate(result.embeddings):
     print(f"  Text {i+1}: {len(emb)} dimensions")
-
-# With custom dimensions (for models that support it)
-print("\n=== Custom Dimensions ===")
-result = embed(
-    input="Hello world",
-    model="text-embedding-3-large",
-    dimensions=256
-)
-print(f"Reduced dimensions: {len(result.embeddings[0])}")

examples/consolidated_params/advanced_workflow_full_features.py

@@ -1,30 +1,30 @@
 """Advanced Workflow with all consolidated params configured."""
 from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
+from praisonaiagents.workflows import Workflow, WorkflowStep
 from praisonaiagents.workflows.workflow_configs import (
     WorkflowOutputConfig, WorkflowPlanningConfig, WorkflowMemoryConfig,
 )
 
 # Full-featured workflow with all consolidated params
-workflow = AgentFlow(
+workflow = Workflow(
     name="FullFeaturedWorkflow",
     description="Demonstrates all agent-like consolidated params",
     steps=[
-        Task(
+        WorkflowStep(
             name="researcher",
             action="Research: {{input}}",
             agent=Agent(instructions="You are a researcher."),
             knowledge=["research_docs/"],  # Step-specific knowledge
             web="duckduckgo",  # Use DuckDuckGo for this step
         ),
-        Task(
+        WorkflowStep(
             name="analyzer",
             action="Analyze the research",
             agent=Agent(instructions="You are an analyst."),
             reflection="thorough",  # Thorough reflection for analysis
             guardrails="strict",  # Strict validation
         ),
-        Task(
+        WorkflowStep(
             name="writer",
             action="Write the final report",
             agent=Agent(instructions="You are a writer."),

examples/consolidated_params/basic_agents.py

@@ -1,12 +1,12 @@
 """Basic Agents (multi-agent) example with consolidated params."""
-from praisonaiagents import Agent, AgentTeam
+from praisonaiagents import Agent, Agents
 
 # Create agents
 writer = Agent(instructions="You write content.")
 editor = Agent(instructions="You edit content.")
 
 # Multi-agent with consolidated params
-agents = AgentTeam(
+agents = Agents(
     agents=[writer, editor],
     memory=True,
     planning=True,

examples/consolidated_params/basic_memory.py

@@ -1,24 +1,21 @@
-"""Basic memory example - minimal usage."""
+"""
+Basic Memory Example - Agent-Centric API
+
+Demonstrates the simplest memory usage with consolidated params.
+"""
+
 from praisonaiagents import Agent
 
-# Simple enable (uses default file-based memory)
+# Basic: Enable memory with preset
 agent = Agent(
     instructions="You are a helpful assistant with memory.",
-    memory=True,
+    memory="sqlite",  # Preset: sqlite, redis, postgres, file
 )
 
-# With preset
-agent_redis = Agent(
-    instructions="You are a helpful assistant.",
-    memory="redis",  # Uses redis preset
-)
+# Run a simple task
+response = agent.start("Remember that my favorite color is blue.")
+print(response)
 
-# With URL
-agent_postgres = Agent(
-    instructions="You are a helpful assistant.",
-    memory="postgresql://localhost/mydb",  # URL auto-detected
-)
-
-if __name__ == "__main__":
-    response = agent.chat("Remember that my favorite color is blue.")
-    print(response)
+# Follow-up to test memory
+response = agent.start("What is my favorite color?")
+print(response)

examples/consolidated_params/basic_step_override.py

@@ -1,18 +1,18 @@
 """Basic example showing step-level override of workflow defaults."""
 from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
+from praisonaiagents.workflows import Workflow, WorkflowStep
 
 # Workflow with defaults
-workflow = AgentFlow(
+workflow = Workflow(
     name="StepOverrideWorkflow",
     steps=[
-        Task(
+        WorkflowStep(
             name="step1",
             action="Process with workflow defaults",
             agent=Agent(instructions="You are a processor."),
             # Uses workflow-level web=True (inherited)
         ),
-        Task(
+        WorkflowStep(
             name="step2",
             action="Process with step override",
             agent=Agent(instructions="You are a processor."),

examples/consolidated_params/basic_workflow.py

@@ -1,22 +1,26 @@
-"""Basic workflow example with consolidated params."""
+"""
+Basic Workflow Example - Agent-Centric API
+
+Demonstrates minimal workflow with consolidated params.
+"""
+
 from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
+from praisonaiagents.workflows import Workflow, WorkflowStep
 
-# Create agents
-writer = Agent(instructions="You are a content writer.")
-editor = Agent(instructions="You are an editor.")
-
-# Create workflow with consolidated params
-workflow = AgentFlow(
-    name="Content Pipeline",
-    steps=[
-        Task(name="write", agent=writer, action="Write about {{topic}}"),
-        Task(name="edit", agent=editor, action="Edit the content", context=["write"]),
-    ],
-    output="verbose",
-    planning=True,
+# Create a simple workflow
+workflow = Workflow(
+    name="simple_workflow",
+    output="verbose",  # Workflow-level output preset
 )
 
-if __name__ == "__main__":
-    result = workflow.run(variables={"topic": "AI agents"})
-    print(result)
+# Add a step
+step = WorkflowStep(
+    name="writer",
+    action="Write a haiku about programming",
+    agent=Agent(instructions="You are a creative poet."),
+    output="result.txt",  # Save output to file
+)
+
+# Note: This is a structural example - actual execution requires workflow.run()
+print("Workflow created with output preset:", workflow.output)
+print("Step output file:", step.output_file)

examples/consolidated_params/basic_workflow_agentlike.py

@@ -1,17 +1,17 @@
 """Basic Workflow with Agent-like consolidated params."""
 from praisonaiagents import Agent
-from praisonaiagents import AgentFlow, Task
+from praisonaiagents.workflows import Workflow, WorkflowStep
 
 # Workflow with agent-like params (knowledge, web, guardrails, reflection)
-workflow = AgentFlow(
+workflow = Workflow(
     name="AgentLikeWorkflow",
     steps=[
-        Task(
+        WorkflowStep(
             name="researcher",
             action="Research the topic: {{input}}",
             agent=Agent(instructions="You are a researcher."),
         ),
-        Task(
+        WorkflowStep(
             name="writer",
             action="Write about the research findings",
             agent=Agent(instructions="You are a writer."),

examples/context/01_basic_context.py

@@ -1,59 +0,0 @@
-"""
-Basic Context Management Example
-
-Demonstrates enabling context management with ContextConfig.
-This manages token budgets, auto-compaction, and prevents context overflow.
-"""
-
-from praisonaiagents import Agent
-from praisonaiagents.context import ContextConfig, OptimizerStrategy
-
-# Example 1: Enable context with defaults
-agent_basic = Agent(
-    name="Assistant",
-    instructions="You are a helpful assistant",
-    context=True  # Auto-compact at 80% utilization
-)
-
-# Example 2: Custom configuration
-agent_custom = Agent(
-    name="CustomAgent",
-    instructions="You are a helpful assistant with custom context settings",
-    context=ContextConfig(
-        auto_compact=True,
-        compact_threshold=0.8,      # Trigger at 80% utilization
-        strategy=OptimizerStrategy.SMART,
-        output_reserve=8000,        # Reserve tokens for output
-        keep_recent_turns=5,        # Always keep last 5 turns
-        tool_output_max=10000,      # Max tokens per tool output
-    )
-)
-
-# Example 3: Sliding window strategy
-agent_sliding = Agent(
-    name="SlidingAgent",
-    instructions="You are a helpful assistant using sliding window",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.SLIDING_WINDOW,
-        keep_recent_turns=10,       # Keep last 10 turns
-    )
-)
-
-if __name__ == "__main__":
-    print("=== Basic Context Example ===")
-    print("Context management is automatically enabled.")
-    print()
-    
-    # Test basic agent
-    result = agent_basic.chat("Hello! What is 2 + 2?")
-    print(f"Response: {result}")
-    print()
-    
-    # Show context config
-    print("=== Context Configuration ===")
-    config = ContextConfig(
-        auto_compact=True,
-        compact_threshold=0.8,
-        strategy=OptimizerStrategy.SMART,
-    )
-    print(f"Config: {config.to_dict()}")

examples/context/02_session_tracking.py

@@ -1,71 +0,0 @@
-"""
-Session Tracking Example
-
-Demonstrates tracking conversation state (goal, plan, progress) across turns.
-Inspired by Agno's SessionContextStore pattern.
-"""
-
-from praisonaiagents.context import SessionContextTracker
-
-# Create session tracker
-tracker = SessionContextTracker(
-    session_id="user123",
-    track_summary=True,
-    track_goal=True,
-    track_plan=True,
-    track_progress=True,
-)
-
-# Set the user's goal
-tracker.update_goal("Build a Python web application with Flask")
-
-# Define the plan
-tracker.update_plan([
-    "Create Flask project structure",
-    "Add routes for API endpoints",
-    "Implement database models",
-    "Add authentication",
-    "Write tests",
-    "Deploy to cloud"
-])
-
-# Mark completed steps
-tracker.add_progress("Created Flask project structure")
-tracker.add_progress("Added routes for API endpoints")
-
-# Update summary
-tracker.update_summary(
-    "User is building a Flask web app. Completed project setup and API routes. "
-    "Next: implement database models."
-)
-
-if __name__ == "__main__":
-    print("=== Session Tracking Example ===")
-    print()
-    
-    # Show current state
-    print(f"Session ID: {tracker.session_id}")
-    print(f"Goal: {tracker.goal}")
-    print(f"Plan: {tracker.plan}")
-    print(f"Progress: {tracker.progress}")
-    print()
-    
-    # Get context string (simple format)
-    print("=== Context String ===")
-    print(tracker.to_context_string())
-    print()
-    
-    # Get system prompt section (XML format with guidelines)
-    print("=== System Prompt Section ===")
-    print(tracker.to_system_prompt_section())
-    print()
-    
-    # Export to dict for persistence
-    print("=== Export as Dict ===")
-    data = tracker.to_dict()
-    print(f"Exported: {data.keys()}")
-    print()
-    
-    # Recreate from dict
-    new_tracker = SessionContextTracker.from_dict(data)
-    print(f"Restored goal: {new_tracker.goal}")

examples/context/03_multi_memory.py

@@ -1,81 +0,0 @@
-"""
-Multi-Memory Aggregation Example
-
-Demonstrates concurrent fetching from multiple context sources.
-Inspired by CrewAI's ContextualMemory pattern.
-"""
-
-import asyncio
-from praisonaiagents.context import ContextAggregator, create_aggregator_from_config
-
-# Example 1: Basic aggregator with mock sources
-def mock_memory_search(query: str) -> str:
-    """Mock memory search - returns recent conversation context."""
-    return f"[Memory] User previously asked about: {query}. They prefer Python."
-
-def mock_knowledge_search(query: str) -> str:
-    """Mock knowledge search - returns facts from knowledge base."""
-    return f"[Knowledge] Relevant facts: Python is a high-level programming language."
-
-def mock_rag_retrieve(query: str) -> str:
-    """Mock RAG retrieval - returns document chunks."""
-    return f"[RAG] Retrieved: Documentation about {query} from the codebase."
-
-# Create aggregator
-aggregator = ContextAggregator(
-    max_tokens=4000,
-    separator="\n\n---\n\n",
-    include_source_labels=True
-)
-
-# Register sources with priorities (lower = higher priority)
-aggregator.register_source("memory", mock_memory_search, priority=10)
-aggregator.register_source("knowledge", mock_knowledge_search, priority=20)
-aggregator.register_source("rag", mock_rag_retrieve, priority=30)
-
-async def demo_async():
-    """Demo async aggregation."""
-    print("=== Async Aggregation ===")
-    result = await aggregator.aggregate("Python web development")
-    print(f"Sources used: {result.sources_used}")
-    print(f"Tokens used: {result.tokens_used}")
-    print(f"Fetch times: {result.fetch_times}")
-    print()
-    print("Context:")
-    print(result.context)
-    return result
-
-def demo_sync():
-    """Demo sync aggregation."""
-    print("=== Sync Aggregation ===")
-    result = aggregator.aggregate_sync("Flask API development")
-    print(f"Sources used: {result.sources_used}")
-    print(f"Tokens used: {result.tokens_used}")
-    print()
-    print("Context:")
-    print(result.context)
-    return result
-
-if __name__ == "__main__":
-    print("=== Multi-Memory Aggregation Example ===")
-    print()
-    
-    # Show registered sources
-    print(f"Registered sources: {aggregator.sources}")
-    print()
-    
-    # Demo sync aggregation
-    demo_sync()
-    print()
-    
-    # Demo async aggregation
-    asyncio.run(demo_async())
-    print()
-    
-    # Demo selective sources
-    print("=== Selective Sources ===")
-    result = aggregator.aggregate_sync(
-        "Find database info",
-        sources=["memory", "knowledge"]  # Only use these
-    )
-    print(f"Sources used: {result.sources_used}")

examples/context/04_compaction_strategies.py

@@ -1,76 +0,0 @@
-"""
-Compaction Strategies Example
-
-Demonstrates different context compaction strategies.
-"""
-
-from praisonaiagents import Agent
-from praisonaiagents.context import ContextConfig, OptimizerStrategy
-
-# Strategy 1: TRUNCATE - Fast, removes oldest messages
-agent_truncate = Agent(
-    name="TruncateAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.TRUNCATE,
-        compact_threshold=0.8,
-    )
-)
-
-# Strategy 2: SLIDING_WINDOW - Keeps recent N turns
-agent_sliding = Agent(
-    name="SlidingAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.SLIDING_WINDOW,
-        keep_recent_turns=10,
-    )
-)
-
-# Strategy 3: SMART - Importance-based (default)
-agent_smart = Agent(
-    name="SmartAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.SMART,  # Default
-        compact_threshold=0.8,
-    )
-)
-
-# Strategy 4: PRUNE_TOOLS - Truncate old tool outputs
-agent_prune = Agent(
-    name="PruneAgent",
-    instructions="You are a helpful assistant with tools",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.PRUNE_TOOLS,
-        tool_output_max=5000,  # Max tokens per tool output
-    )
-)
-
-# Strategy 5: NON_DESTRUCTIVE - Only prune tools, keep all history
-agent_safe = Agent(
-    name="SafeAgent",
-    instructions="You are a helpful assistant (safety-critical)",
-    context=ContextConfig(
-        strategy=OptimizerStrategy.NON_DESTRUCTIVE,
-    )
-)
-
-if __name__ == "__main__":
-    print("=== Compaction Strategies Example ===")
-    print()
-    
-    strategies = [
-        ("TRUNCATE", OptimizerStrategy.TRUNCATE, "Remove oldest messages"),
-        ("SLIDING_WINDOW", OptimizerStrategy.SLIDING_WINDOW, "Keep last N turns"),
-        ("SMART", OptimizerStrategy.SMART, "Importance-based (default)"),
-        ("PRUNE_TOOLS", OptimizerStrategy.PRUNE_TOOLS, "Truncate tool outputs"),
-        ("NON_DESTRUCTIVE", OptimizerStrategy.NON_DESTRUCTIVE, "Only prune tools"),
-    ]
-    
-    for name, strategy, description in strategies:
-        print(f"  {name:20} - {description}")
-    
-    print()
-    print("Usage:")
-    print("  context=ContextConfig(strategy=OptimizerStrategy.SLIDING_WINDOW)")

examples/context/05_monitoring.py

@@ -1,85 +0,0 @@
-"""
-Context Monitoring Example
-
-Demonstrates monitoring context usage with logging and metrics.
-"""
-
-from praisonaiagents import Agent
-from praisonaiagents.context import ContextConfig, MonitorConfig, OptimizerStrategy
-
-# Example 1: Human-readable monitoring
-agent_human = Agent(
-    name="MonitoredAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        auto_compact=True,
-        monitor=MonitorConfig(
-            enabled=True,
-            path="./context_logs/",
-            format="human",           # Human-readable format
-            frequency="turn",         # Log on every turn
-            redact_sensitive=True,    # Redact sensitive data
-            multi_agent_files=True,   # Separate files per agent
-        )
-    )
-)
-
-# Example 2: JSON monitoring (for parsing)
-agent_json = Agent(
-    name="JSONMonitorAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        monitor=MonitorConfig(
-            enabled=True,
-            path="./context_logs/",
-            format="json",            # JSON format for parsing
-            frequency="tool_call",    # Log on tool calls
-        )
-    )
-)
-
-# Example 3: Overflow-only monitoring
-agent_overflow = Agent(
-    name="OverflowAgent",
-    instructions="You are a helpful assistant",
-    context=ContextConfig(
-        monitor=MonitorConfig(
-            enabled=True,
-            path="./context_logs/",
-            format="human",
-            frequency="overflow",     # Only log on overflow
-        )
-    )
-)
-
-if __name__ == "__main__":
-    print("=== Context Monitoring Example ===")
-    print()
-    
-    # Show monitor configuration
-    config = MonitorConfig(
-        enabled=True,
-        path="./context_logs/",
-        format="human",
-        frequency="turn",
-        redact_sensitive=True,
-    )
-    
-    print("Monitor Config:")
-    print(f"  enabled: {config.enabled}")
-    print(f"  path: {config.path}")
-    print(f"  format: {config.format}")
-    print(f"  frequency: {config.frequency}")
-    print(f"  redact_sensitive: {config.redact_sensitive}")
-    print()
-    
-    print("Frequency options:")
-    print("  'turn'      - Log on every conversation turn")
-    print("  'tool_call' - Log when tools are called")
-    print("  'manual'    - Manual logging only")
-    print("  'overflow'  - Log only when context overflows")
-    print()
-    
-    print("Format options:")
-    print("  'human' - Human-readable format")
-    print("  'json'  - JSON format for parsing")

examples/context/09_context_budgeting.py

@@ -189,8 +189,8 @@ def main():
     print("-" * 40)
     print("Auto-agents mode default: context=False (zero overhead)")
     print("To enable for multi-agent workflows:")
-    print("    from praisonaiagents import AgentTeam")
-    print("    agents = AgentTeam(agents=[...], context=True)")
+    print("    from praisonaiagents import Agents")
+    print("    agents = Agents(agents=[...], context=True)")
     print("")
     print("Recommended config for long tasks:")
     print("    context=ManagerConfig(")

examples/context/12_multi_agent_context.py

@@ -6,10 +6,10 @@ Demonstrates how to use multi-agent context with Agents via context= param,
 and also shows low-level MultiAgentLedger usage for advanced scenarios.
 
 Agent-Centric Quick Start:
-    from praisonaiagents import Agent, AgentTeam
+    from praisonaiagents import Agent, Agents
     from praisonaiagents.context import ManagerConfig
     
-    agents = AgentTeam(
+    agents = Agents(
         agents=[agent1, agent2],
         context=ManagerConfig(policy="isolated"),  # or "shared"
     )
@@ -17,7 +17,7 @@ Agent-Centric Quick Start:
 
 import os
 import tempfile
-from praisonaiagents import Agent, AgentTeam
+from praisonaiagents import Agent, Agents
 from praisonaiagents.context import (
     ManagerConfig,
     MultiAgentLedger,
@@ -49,7 +49,7 @@ def agent_centric_example():
     # Multi-agent setup with isolated context policy
     # (each agent maintains its own context)
     print("Created agents with context=True")
-    print("Use AgentTeam(agents=[...], context=ManagerConfig(policy='isolated'))")
+    print("Use Agents(agents=[...], context=ManagerConfig(policy='isolated'))")
     print("for multi-agent context isolation")
 
 

examples/context/14_agent_context_param.py

@@ -156,7 +156,7 @@ def example_5_multi_agent():
     print("Example 5: Multi-Agent Context Management")
     print("=" * 60)
     
-    from praisonaiagents import AgentTeam, Task
+    from praisonaiagents import Agents, Task
     
     config = ManagerConfig(
         auto_compact=True,
@@ -181,7 +181,7 @@ def example_5_multi_agent():
     task2 = Task(description="Write a summary", agent=writer)
     
     # Create multi-agent system with context management
-    agents = AgentTeam(
+    agents = Agents(
         agents=[researcher, writer],
         tasks=[task1, task2],
         context=config,  # Shared context config

examples/context/15_recursive_context.py

@@ -1,274 +0,0 @@
-"""
-Example 15: Recursive Context Pattern
-
-Demonstrates the RLM (Recursive Language Model) pattern for handling large context:
-- Store large documents as artifacts (not in LLM context)
-- Agent uses tools (grep/head/tail/chunk) to explore artifacts
-- Dramatically reduces token usage (~2K vs ~10K+)
-
-This pattern solves "context rot" by treating context as programmatically
-explorable data instead of dumping everything into the LLM's context window.
-"""
-
-import tempfile
-import os
-from praisonaiagents import Agent
-from praisonai.context import FileSystemArtifactStore
-from praisonai.context.queue import create_artifact_tools
-from praisonaiagents.context.artifacts import ArtifactMetadata
-
-
-def create_sample_document():
-    """Create a sample large document for testing."""
-    # Simulate a research paper / large document
-    content = """
-# Attention Is All You Need
-
-## Abstract
-
-The dominant sequence transduction models are based on complex recurrent or 
-convolutional neural networks that include an encoder and a decoder. The best
-performing models also connect the encoder and decoder through an attention
-mechanism. We propose a new simple network architecture, the Transformer,
-based solely on attention mechanisms, dispensing with recurrence and convolutions
-entirely. 
-
-## Introduction
-
-Recurrent neural networks, long short-term memory and gated recurrent neural 
-networks in particular, have been firmly established as state of the art 
-approaches in sequence modeling and transduction problems such as language 
-modeling and machine translation. 
-
-## Background
-
-The goal of reducing sequential computation also forms the foundation of the 
-Extended Neural GPU, ByteNet and ConvS2S, all of which use convolutional neural
-networks as basic building block.
-
-## Model Architecture
-
-### Encoder and Decoder Stacks
-
-The encoder is composed of a stack of N = 6 identical layers. Each layer has 
-two sub-layers. The first is a multi-head self-attention mechanism, and the 
-second is a simple, position-wise fully connected feed-forward network.
-
-### Attention
-
-An attention function can be described as mapping a query and a set of key-value
-pairs to an output, where the query, keys, values, and output are all vectors.
-
-#### Scaled Dot-Product Attention
-
-We call our particular attention "Scaled Dot-Product Attention". The input 
-consists of queries and keys of dimension dk, and values of dimension dv.
-
-The formula is: Attention(Q, K, V) = softmax(QK^T / sqrt(d_k))V
-
-### Multi-Head Attention
-
-Multi-head attention allows the model to jointly attend to information from
-different representation subspaces at different positions.
-
-## Results
-
-### Machine Translation
-
-On the WMT 2014 English-to-German translation task, the big transformer model
-outperforms the best previously reported models including ensembles.
-
-The model achieved a BLEU score of 28.4 on the WMT 2014 English-to-German 
-translation task, improving over the existing best results by over 2 BLEU.
-
-On the WMT 2014 English-to-French translation task, our big model achieves 
-a BLEU score of 41.8, outperforming all published single models.
-
-### Training
-
-Training took 3.5 days on 8 P100 GPUs. The big model was trained for 300,000
-steps (3.5 days) at a cost of approximately $1000 in cloud compute.
-
-## Model Variations
-
-| Model | Parameters | BLEU EN-DE | BLEU EN-FR |
-|-------|------------|------------|------------|
-| Base  | 65M        | 27.3       | 38.1       |
-| Big   | 213M       | 28.4       | 41.8       |
-
-The base model has 65 million parameters (65 × 10^6).
-The big model has 213 million parameters.
-
-## Conclusion
-
-In this work, we presented the Transformer, the first sequence transduction
-model based entirely on attention, replacing the recurrent layers most commonly
-used in encoder-decoder architectures with multi-headed self-attention.
-
-The Transformer can be trained significantly faster than architectures based
-on recurrent or convolutional layers.
-
-## Authors
-
-Ashish Vaswani (Google Brain)
-Noam Shazeer (Google Brain)
-Niki Parmar (Google Research)
-Jakob Uszkoreit (Google Research)
-Llion Jones (Google Research)
-Aidan N. Gomez (University of Toronto)
-Łukasz Kaiser (Google Brain)
-Illia Polosukhin
-
-## References
-
-[1] Neural Machine Translation by Jointly Learning to Align and Translate
-[2] Sequence to Sequence Learning with Neural Networks
-[3] Learning Phrase Representations using RNN Encoder-Decoder
-"""
-    # Repeat content to make it larger
-    full_content = (content + "\n\n") * 10  # ~35KB
-    return full_content
-
-
-def main():
-    print("=" * 70)
-    print("Recursive Context Pattern - Token Efficiency Demo")
-    print("=" * 70)
-    
-    # Track token usage across methods
-    token_stats = {
-        "traditional": {"input": 0, "output": 0},
-        "recursive": {"input": 0, "output": 0},
-    }
-    
-    with tempfile.TemporaryDirectory() as tmpdir:
-        # 1. Create artifact store and tools
-        store = FileSystemArtifactStore(base_dir=tmpdir)
-        artifact_tools = create_artifact_tools(store=store)
-        
-        print(f"\n1. Created FileSystemArtifactStore")
-        print(f"   Location: {tmpdir}")
-        print(f"   Tools available: {[t.__name__ for t in artifact_tools]}")
-        
-        # 2. Create sample document and store as artifact
-        document = create_sample_document()
-        doc_size = len(document)
-        doc_tokens = doc_size // 4  # Rough estimate: 4 chars per token
-        
-        metadata = ArtifactMetadata(
-            agent_id="research_agent",
-            run_id="demo_run",
-            tool_name="document_loader",
-            turn_id=1
-        )
-        
-        ref = store.store(document, metadata)
-        
-        print(f"\n2. Stored document as artifact")
-        print(f"   Size: {doc_size:,} chars (~{doc_tokens:,} tokens)")
-        print(f"   Path: {ref.path}")
-        print(f"   Summary: {ref.summary[:80]}...")
-        
-        # 3. Create agent WITH artifact tools (Recursive Context approach)
-        agent = Agent(
-            instructions="""You are a research paper analyst with access to artifact exploration tools.
-When given an artifact path, use the tools to explore it efficiently:
-- artifact_grep: Search for patterns (USE THIS FIRST)
-- artifact_head: See first N lines
-- artifact_tail: See last N lines
-- artifact_chunk: Get specific line ranges
-
-Be precise and cite line numbers when finding information.""",
-            tools=artifact_tools,
-            output='silent'  # Quiet output for cleaner demo
-        )
-        
-        print(f"\n3. Created agent with {len(agent.tools)} artifact tools")
-        
-        # 4. Query using RECURSIVE CONTEXT (small prompt + tools)
-        print(f"\n4. RECURSIVE CONTEXT APPROACH")
-        print("-" * 40)
-        
-        prompt = f"""I have a research paper stored at: {ref.path}
-
-Find the BLEU score on the WMT 2014 English-to-German translation task.
-Use artifact_grep to search, then report the answer with line number."""
-
-        prompt_tokens = len(prompt) // 4
-        print(f"   Prompt size: {len(prompt)} chars (~{prompt_tokens} tokens)")
-        print(f"   Document NOT in prompt context!")
-        
-        response = agent.chat(prompt)
-        
-        # Estimate output tokens (could use actual LiteLLM response if available)
-        output_tokens = len(response) // 4
-        
-        # Calculate recursive approach tokens (prompt + tool calls + response)
-        # Tool call: ~200 tokens for tool desc + call
-        # Tool response: ~300 tokens for grep results
-        estimated_total = prompt_tokens + 200 + 300 + output_tokens
-        token_stats["recursive"]["input"] = estimated_total
-        
-        print(f"\n   Agent Response:")
-        print(f"   {response[:200]}...")
-        print(f"\n   Estimated tokens used: ~{estimated_total:,}")
-        
-        # 5. Compare with TRADITIONAL approach (full context)
-        print(f"\n5. TRADITIONAL APPROACH (for comparison)")
-        print("-" * 40)
-        
-        traditional_prompt_tokens = prompt_tokens + doc_tokens
-        token_stats["traditional"]["input"] = traditional_prompt_tokens
-        
-        print(f"   If we passed FULL document in prompt:")
-        print(f"   Prompt: {prompt_tokens} + Document: {doc_tokens} = {traditional_prompt_tokens:,} tokens")
-        
-        # 6. Show token savings
-        print(f"\n6. TOKEN COMPARISON")
-        print("=" * 40)
-        
-        savings = token_stats["traditional"]["input"] - token_stats["recursive"]["input"]
-        savings_pct = (savings / token_stats["traditional"]["input"]) * 100
-        
-        print(f"   Traditional approach: ~{token_stats['traditional']['input']:,} tokens")
-        print(f"   Recursive approach:   ~{token_stats['recursive']['input']:,} tokens")
-        print(f"   -----------------------------------")
-        print(f"   SAVINGS:             ~{savings:,} tokens ({savings_pct:.0f}%)")
-        
-        # 7. Demonstrate other artifact operations
-        print(f"\n7. ARTIFACT OPERATIONS DEMO")
-        print("-" * 40)
-        
-        # head
-        head_result = store.head(ref, lines=5)
-        print(f"   head(5 lines):")
-        for line in head_result.split('\n')[:3]:
-            print(f"      {line[:60]}")
-        
-        # grep
-        grep_results = store.grep(ref, pattern=r"BLEU.*\d+", max_matches=3)
-        print(f"\n   grep('BLEU.*\\d+'):")
-        for match in grep_results[:2]:
-            print(f"      Line {match.line_number}: {match.line_content[:50].strip()}...")
-        
-        # chunk
-        chunk_result = store.chunk(ref, start_line=50, end_line=55)
-        print(f"\n   chunk(lines 50-55):")
-        for line in chunk_result.split('\n')[:3]:
-            print(f"      {line[:60]}")
-        
-        print("\n" + "=" * 70)
-        print("CONCLUSION: Recursive Context Pattern")
-        print("=" * 70)
-        print("""
-The Recursive Context pattern (RLM) provides:
-✓ Token efficiency: ~{savings_pct:.0f}% reduction in token usage
-✓ Scalability: Handle documents of any size
-✓ Precision: Agent searches for exactly what it needs
-✓ Cost savings: Lower API costs due to fewer tokens
-✓ Better accuracy: Avoids "context rot" from large contexts
-""".format(savings_pct=savings_pct))
-
-
-if __name__ == "__main__":
-    main()

examples/embedding/agent_with_embedding.py

@@ -1,145 +0,0 @@
-"""
-Agent-centric Embedding Example
-
-This example shows how to use embeddings with PraisonAI Agents.
-Embeddings are used internally by Agent for:
-- Knowledge retrieval (RAG)
-- Memory storage and search
-- Semantic similarity
-
-You can also use the embedding API directly for custom use cases.
-"""
-
-from praisonaiagents import Agent, embedding
-
-# =============================================================================
-# Example 1: Direct Embedding API
-# =============================================================================
-
-def example_direct_embedding():
-    """Use the embedding API directly."""
-    
-    # Single text embedding
-    result = embedding("Hello, world!")
-    print(f"Single embedding: {len(result.embeddings[0])} dimensions")
-    
-    # Batch embedding
-    texts = ["AI agents are powerful", "Machine learning is fascinating"]
-    result = embedding(texts, model="text-embedding-3-small")
-    print(f"Batch embeddings: {len(result.embeddings)} vectors")
-    
-    # Custom dimensions (for models that support it)
-    result = embedding("Hello", model="text-embedding-3-large", dimensions=256)
-    print(f"Custom dimensions: {len(result.embeddings[0])} dimensions")
-    
-    return result
-
-
-# =============================================================================
-# Example 2: Agent with Knowledge (uses embeddings internally)
-# =============================================================================
-
-def example_agent_with_knowledge():
-    """Agent with knowledge uses embeddings for RAG."""
-    
-    agent = Agent(
-        instructions="You are a helpful assistant with knowledge about AI.",
-        knowledge=["AI agents can use tools to accomplish tasks."],
-        knowledge_config={
-            "embedder": {
-                "provider": "openai",
-                "config": {"model": "text-embedding-3-small"}
-            }
-        }
-    )
-    
-    # The agent uses embeddings internally for knowledge retrieval
-    response = agent.chat("What can AI agents do?")
-    print(f"Agent response: {response}")
-    
-    return agent
-
-
-# =============================================================================
-# Example 3: Agent with Memory (uses embeddings internally)
-# =============================================================================
-
-def example_agent_with_memory():
-    """Agent with memory uses embeddings for semantic search."""
-    
-    agent = Agent(
-        instructions="You are a helpful assistant that remembers conversations.",
-        memory=True,
-        memory_config={
-            "embedding_model": "text-embedding-3-small"
-        }
-    )
-    
-    # The agent uses embeddings internally for memory storage/retrieval
-    agent.chat("My name is Alice and I love Python programming.")
-    response = agent.chat("What do I love?")
-    print(f"Agent remembered: {response}")
-    
-    return agent
-
-
-# =============================================================================
-# Example 4: Custom Embedding for Similarity Search
-# =============================================================================
-
-def example_similarity_search():
-    """Use embeddings for custom similarity search."""
-    import math
-    
-    def cosine_similarity(a, b):
-        dot = sum(x * y for x, y in zip(a, b))
-        norm_a = math.sqrt(sum(x * x for x in a))
-        norm_b = math.sqrt(sum(x * x for x in b))
-        return dot / (norm_a * norm_b) if norm_a and norm_b else 0
-    
-    # Embed documents
-    documents = [
-        "Python is a programming language",
-        "JavaScript runs in browsers",
-        "AI agents can automate tasks"
-    ]
-    doc_embeddings = embedding(documents)
-    
-    # Embed query
-    query = "What language is used for web development?"
-    query_embedding = embedding(query)
-    
-    # Find most similar document
-    similarities = [
-        cosine_similarity(query_embedding.embeddings[0], doc_emb)
-        for doc_emb in doc_embeddings.embeddings
-    ]
-    
-    best_idx = similarities.index(max(similarities))
-    print(f"Most similar document: {documents[best_idx]}")
-    print(f"Similarity score: {similarities[best_idx]:.4f}")
-    
-    return similarities
-
-
-if __name__ == "__main__":
-    print("=" * 60)
-    print("Example 1: Direct Embedding API")
-    print("=" * 60)
-    example_direct_embedding()
-    
-    print("\n" + "=" * 60)
-    print("Example 4: Custom Similarity Search")
-    print("=" * 60)
-    example_similarity_search()
-    
-    # Uncomment to run agent examples (requires API key)
-    # print("\n" + "=" * 60)
-    # print("Example 2: Agent with Knowledge")
-    # print("=" * 60)
-    # example_agent_with_knowledge()
-    
-    # print("\n" + "=" * 60)
-    # print("Example 3: Agent with Memory")
-    # print("=" * 60)
-    # example_agent_with_memory()

examples/guardrail_example_fixed.py

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

examples/hooks/basic_hooks.py

@@ -2,34 +2,32 @@
 """
 Basic Hooks Example for PraisonAI Agents.
 
-This example demonstrates the simplified hook API using add_hook():
+This example demonstrates how to use the hooks system to:
 1. Log tool calls before execution
 2. Block dangerous operations
 3. Add context to agent responses
 4. Monitor session lifecycle
 
-For the simplest example, see simple_hooks.py
-
 Usage:
     python basic_hooks.py
 """
 
 import asyncio
+from praisonaiagents import Agent
 from praisonaiagents.hooks import (
-    add_hook, remove_hook, has_hook, get_default_registry,
-    HookRunner, HookEvent, HookResult,
+    HookRegistry, HookRunner, HookEvent, HookResult,
     BeforeToolInput, AfterToolInput
 )
 
 
 def main():
-    # Clear any existing hooks from previous runs
-    get_default_registry().clear()
+    # Create a hook registry
+    registry = HookRegistry()
     
     # ==========================================================================
-    # Hook 1: Log all tool calls (using string event name)
+    # Hook 1: Log all tool calls
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.BEFORE_TOOL)
     def log_tool_calls(event_data: BeforeToolInput) -> HookResult:
         """Log every tool call before execution."""
         print(f"\n📝 [LOG] Tool: {event_data.tool_name}")
@@ -37,9 +35,9 @@ def main():
         return HookResult.allow()
     
     # ==========================================================================
-    # Hook 2: Block dangerous file operations
+    # Hook 2: Block dangerous file operations (using function logic)
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.BEFORE_TOOL)
     def block_delete_operations(event_data: BeforeToolInput) -> HookResult:
         """Block any delete or remove operations."""
         dangerous_keywords = ['delete', 'remove', 'rm', 'unlink']
@@ -55,7 +53,7 @@ def main():
     # ==========================================================================
     # Hook 3: Require confirmation for write operations
     # ==========================================================================
-    @add_hook('before_tool')
+    @registry.on(HookEvent.BEFORE_TOOL)
     def confirm_write_operations(event_data: BeforeToolInput) -> HookResult:
         """Request confirmation for write operations."""
         write_keywords = ['write', 'save', 'create', 'update']
@@ -64,13 +62,14 @@ def main():
         if any(kw in tool_lower for kw in write_keywords):
             print(f"\n⚠️  [CONFIRM] Write operation: {event_data.tool_name}")
             # In a real scenario, you might prompt the user here
+            # For this example, we'll auto-approve
             return HookResult.allow("Auto-approved for demo")
         return HookResult.allow()
     
     # ==========================================================================
     # Hook 4: Add timing information after tool execution
     # ==========================================================================
-    @add_hook('after_tool')
+    @registry.on(HookEvent.AFTER_TOOL)
     def log_tool_completion(event_data: AfterToolInput) -> HookResult:
         """Log tool completion with timing."""
         print(f"\n✅ [DONE] Tool: {event_data.tool_name}")
@@ -83,14 +82,10 @@ def main():
     # Test the hooks
     # ==========================================================================
     print("=" * 60)
-    print("Testing Hooks System (using add_hook API)")
+    print("Testing Hooks System")
     print("=" * 60)
     
-    # Check hooks are registered
-    print(f"\nHooks registered for 'before_tool': {has_hook('before_tool')}")
-    print(f"Hooks registered for 'after_tool': {has_hook('after_tool')}")
-    
-    runner = HookRunner(get_default_registry())
+    runner = HookRunner(registry)
     
     # Test 1: Normal tool call (should be logged and allowed)
     print("\n--- Test 1: Normal read operation ---")
@@ -137,7 +132,7 @@ def main():
     print("\n" + "=" * 60)
     print("Registered Hooks:")
     print("=" * 60)
-    for event, hooks in get_default_registry().list_hooks().items():
+    for event, hooks in registry.list_hooks().items():
         print(f"\n{event}:")
         for hook in hooks:
             print(f"  - {hook['name']} (matcher: {hook['matcher'] or '*'})")

examples/hooks/simple_hooks.py

@@ -1,67 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple Hooks Example for PraisonAI Agents.
-
-This example shows the SIMPLEST way to use hooks with the add_hook API.
-Just a few lines of code to intercept tool calls!
-
-No need to import HookResult - just return None/True to allow, 
-False to deny, or a string to deny with a reason.
-
-Usage:
-    python simple_hooks.py
-"""
-
-from praisonaiagents.hooks import add_hook, has_hook
-
-
-# =============================================================================
-# Register hooks with simple string event names
-# =============================================================================
-
-@add_hook('before_tool')
-def log_tools(event_data):
-    """Log every tool call. Return nothing (None) to allow."""
-    print(f"🔧 Tool: {event_data.tool_name}")
-    # No return needed - defaults to allow
-
-
-@add_hook('before_tool')
-def block_dangerous(event_data):
-    """Block delete operations. Return False or string to deny."""
-    if 'delete' in event_data.tool_name.lower():
-        print(f"🚫 Blocked: {event_data.tool_name}")
-        return "Delete operations are not allowed"  # String = deny with reason
-    # No return = allow
-
-
-@add_hook('after_tool')
-def log_completion(event_data):
-    """Log tool completion."""
-    print(f"✅ Done: {event_data.tool_name} ({event_data.execution_time_ms:.0f}ms)")
-
-
-# =============================================================================
-# Test the hooks
-# =============================================================================
-
-if __name__ == "__main__":
-    print("=" * 50)
-    print("Simple Hooks Example")
-    print("=" * 50)
-    
-    # Check hooks are registered
-    print(f"\nHooks registered for 'before_tool': {has_hook('before_tool')}")
-    print(f"Hooks registered for 'after_tool': {has_hook('after_tool')}")
-    
-    # You can now create an Agent and the hooks will be applied
-    print("\n💡 Hooks are now globally registered!")
-    print("   Any Agent will automatically use these hooks.")
-    print("\n   Example:")
-    print("   from praisonaiagents import Agent")
-    print("   agent = Agent(instructions='You are helpful')")
-    print("   agent.start('Help me with files')")
-    print("\n📝 Hook returns:")
-    print("   - None or True  → Allow the operation")
-    print("   - False         → Deny the operation")
-    print("   - 'reason'      → Deny with a custom message")

examples/js/agents/audio-agent.ts

@@ -1,128 +0,0 @@
-/**
- * AudioAgent Integration Test
- * 
- * Tests the AudioAgent for TTS and STT using AI SDK.
- * Requires OPENAI_API_KEY for live tests.
- * 
- * Run: npx ts-node audio-agent.ts
- */
-
-import { AudioAgent, createAudioAgent } from '../../../src/praisonai-ts/dist';
-import * as fs from 'fs';
-import * as path from 'path';
-
-async function main() {
-    console.log('=== AudioAgent Integration Test ===\n');
-
-    // Test 1: Create AudioAgent with defaults
-    console.log('1. Testing AudioAgent creation:');
-    const agent = new AudioAgent({
-        name: 'TestAudioAgent',
-        provider: 'openai',
-        voice: 'alloy',
-        verbose: true
-    });
-    console.log('   Agent ID:', agent.id);
-    console.log('   Agent Name:', agent.name);
-    console.log('   Success: ✅');
-
-    // Test 2: Factory function
-    console.log('\n2. Testing createAudioAgent() factory:');
-    const agent2 = createAudioAgent({ provider: 'openai', voice: 'nova' });
-    console.log('   Agent created:', typeof agent2);
-    console.log('   Success: ✅');
-
-    // Test 3: Live TTS (requires API key)
-    if (process.env.OPENAI_API_KEY) {
-        console.log('\n3. Testing Text-to-Speech (live API):');
-        try {
-            const ttsAgent = new AudioAgent({
-                provider: 'openai',
-                voice: 'alloy',
-                verbose: false
-            });
-
-            const result = await ttsAgent.speak('Hello from PraisonAI AudioAgent!');
-            console.log('   Audio format:', result.format);
-            console.log('   Audio size:', result.audio.byteLength || result.audio.length, 'bytes');
-
-            // Optionally save to file
-            const outputPath = path.join(__dirname, 'test-output.mp3');
-            if (result.audio instanceof Buffer) {
-                fs.writeFileSync(outputPath, result.audio);
-                console.log('   Saved to:', outputPath);
-            }
-            console.log('   Success: ✅');
-        } catch (error: any) {
-            console.log('   ⚠️ TTS failed:', error.message);
-        }
-
-        // Test 4: Live Transcription (requires audio file)
-        console.log('\n4. Testing Speech-to-Text (live API):');
-        try {
-            const sttAgent = new AudioAgent({
-                provider: 'openai',
-                verbose: false
-            });
-
-            // Check if we have the test output from TTS
-            const audioPath = path.join(__dirname, 'test-output.mp3');
-            if (fs.existsSync(audioPath)) {
-                const result = await sttAgent.transcribe(audioPath);
-                console.log('   Transcribed text:', result.text);
-                console.log('   Language:', result.language || 'auto-detected');
-                console.log('   Success: ✅');
-
-                // Cleanup
-                fs.unlinkSync(audioPath);
-                console.log('   Cleaned up test file');
-            } else {
-                console.log('   Skipped (no test audio file available)');
-            }
-        } catch (error: any) {
-            console.log('   ⚠️ STT failed:', error.message);
-        }
-
-        // Test 5: Chat method (auto-detect mode)
-        console.log('\n5. Testing chat() method:');
-        try {
-            const chatAgent = new AudioAgent({ provider: 'openai', voice: 'echo' });
-
-            // Text input -> TTS
-            const chatResult = await chatAgent.chat('Testing audio chat interface');
-            console.log('   Chat result:', chatResult);
-            console.log('   Success: ✅');
-        } catch (error: any) {
-            console.log('   ⚠️ Chat failed:', error.message);
-        }
-
-    } else {
-        console.log('\n3-5. Live API Tests: Skipped (OPENAI_API_KEY not set)');
-        console.log('   Set OPENAI_API_KEY to run live tests');
-    }
-
-    // Test 6: Different providers (just creation, no live calls)
-    console.log('\n6. Testing provider configurations:');
-    const providers = ['openai', 'elevenlabs', 'groq', 'deepgram'] as const;
-
-    for (const provider of providers) {
-        try {
-            const a = new AudioAgent({ provider });
-            console.log(`   ${provider}: ✅ (created)`);
-        } catch (error: any) {
-            console.log(`   ${provider}: ⚠️ ${error.message}`);
-        }
-    }
-
-    // Test 7: Voice options
-    console.log('\n7. Testing OpenAI voice options:');
-    const voices = ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'];
-    for (const voice of voices) {
-        const a = new AudioAgent({ provider: 'openai', voice });
-        console.log(`   ${voice}: ✅`);
-    }
-
-    console.log('\n=== AudioAgent Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/knowledge/chonkie-adapter.ts

@@ -1,124 +0,0 @@
-/**
- * ChonkieAdapter Integration Test
- * 
- * Tests the ChonkieJS adapter for text chunking.
- * Works without ChonkieJS installed (uses native fallback).
- * 
- * Run: npx ts-node chonkie-adapter.ts
- */
-
-import {
-  ChonkieAdapter,
-  createChonkieAdapter,
-  hasChonkie,
-  Chunking
-} from '../../../src/praisonai-ts/dist';
-
-async function main() {
-  console.log('=== ChonkieAdapter Integration Test ===\n');
-
-  // Test 1: Check ChonkieJS availability
-  console.log('1. Checking ChonkieJS availability:');
-  const chonkieAvailable = await hasChonkie();
-  console.log(`   ChonkieJS installed: ${chonkieAvailable ? '✅' : '❌ (using native fallback)'}`);
-
-  // Test 2: Create adapter with default config
-  console.log('\n2. Testing ChonkieAdapter creation:');
-  const adapter = new ChonkieAdapter({
-    strategy: 'token',
-    chunkSize: 100,
-    overlap: 20
-  });
-  console.log('   Adapter created: ✅');
-  console.log('   Info:', adapter.getInfo());
-
-  // Test 3: Chunk text
-  console.log('\n3. Testing text chunking:');
-  const sampleText = `
-    PraisonAI is a high-performance, agentic AI framework designed with minimal client-side API.
-    It features extreme performance sensitivity, lazy loading everywhere, and optional dependencies only.
-    The framework supports clean separation between Core SDK, Wrapper/integrations, and Tools/plugins.
-    All features must have a relevant CLI integration and representation.
-  `.trim();
-
-  const chunks = await adapter.chunk(sampleText);
-  console.log(`   Input length: ${sampleText.length} characters`);
-  console.log(`   Chunks created: ${chunks.length}`);
-  chunks.forEach((chunk, i) => {
-    console.log(`   [${i}]: "${chunk.content.slice(0, 50)}..." (${chunk.content.length} chars)`);
-  });
-  console.log('   Success: ✅');
-
-  // Test 4: Different strategies
-  console.log('\n4. Testing different chunking strategies:');
-  const strategies = ['size', 'sentence', 'paragraph', 'semantic'] as const;
-
-  for (const strategy of strategies) {
-    const strategyAdapter = createChonkieAdapter({ strategy, chunkSize: 80 });
-    const strategyChunks = await strategyAdapter.chunk(sampleText);
-    console.log(`   ${strategy}: ${strategyChunks.length} chunks`);
-  }
-  console.log('   Success: ✅');
-
-  // Test 5: Native Chunking class
-  console.log('\n5. Testing native Chunking class:');
-  const nativeChunker = new Chunking({ chunkSize: 100, overlap: 10, strategy: 'sentence' });
-  const nativeChunks = nativeChunker.chunk(sampleText);
-  console.log(`   Native chunks: ${nativeChunks.length}`);
-  console.log('   Success: ✅');
-
-  // Test 6: Factory function
-  console.log('\n6. Testing createChunking() factory:');
-  const factoryChunker = createChunking({ chunkSize: 200 });
-  const factoryChunks = factoryChunker.chunk(sampleText);
-  console.log(`   Factory chunks: ${factoryChunks.length}`);
-  console.log('   Success: ✅');
-
-  // Test 7: Merge small chunks
-  console.log('\n7. Testing mergeSmallChunks:');
-  const tinyChunker = new Chunking({ chunkSize: 20, overlap: 5 });
-  const tinyChunks = tinyChunker.chunk(sampleText);
-  const mergedChunks = tinyChunker.mergeSmallChunks(tinyChunks, 50);
-  console.log(`   Before merge: ${tinyChunks.length} chunks`);
-  console.log(`   After merge: ${mergedChunks.length} chunks`);
-  console.log('   Success: ✅');
-
-  // Test 8: Code chunking (if ChonkieJS available)
-  if (chonkieAvailable) {
-    console.log('\n8. Testing code chunking (ChonkieJS):');
-    const codeAdapter = createChonkieAdapter({ strategy: 'code', language: 'typescript' });
-    const codeText = `
-function hello() {
-  console.log('Hello');
-}
-
-class MyClass {
-  constructor() {
-    this.value = 42;
-  }
-  
-  getValue() {
-    return this.value;
-  }
-}
-    `.trim();
-
-    const codeChunks = await codeAdapter.chunk(codeText);
-    console.log(`   Code chunks: ${codeChunks.length}`);
-    console.log('   Success: ✅');
-  } else {
-    console.log('\n8. Code chunking: Skipped (ChonkieJS not installed)');
-  }
-
-  // Test 9: Verify adapter info
-  console.log('\n9. Verifying adapter state:');
-  const info = adapter.getInfo();
-  console.log(`   Strategy: ${info.strategy}`);
-  console.log(`   Using ChonkieJS: ${info.usingChonkie}`);
-  console.log(`   Chunk size: ${info.config.chunkSize}`);
-  console.log('   Success: ✅');
-
-  console.log('\n=== ChonkieAdapter Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/knowledge/query-engine.ts

@@ -1,97 +0,0 @@
-/**
- * QueryEngine Integration Test
- * 
- * Tests semantic and keyword search for RAG applications.
- * 
- * Run: npx ts-node query-engine.ts
- */
-
-import {
-    QueryEngine,
-    createQueryEngine,
-    createSimpleQueryEngine
-} from '../../../src/praisonai-ts/dist';
-
-async function main() {
-    console.log('=== QueryEngine Integration Test ===\n');
-
-    // Test 1: Simple in-memory engine
-    console.log('1. Testing simple in-memory QueryEngine:');
-    const docs = [
-        { id: 'doc1', content: 'PraisonAI is a high-performance AI agent framework designed for production use.' },
-        { id: 'doc2', content: 'TypeScript provides static typing and better tooling for JavaScript projects.' },
-        { id: 'doc3', content: 'Agents can use tools, memory, and knowledge to complete complex tasks.' },
-        { id: 'doc4', content: 'RAG (Retrieval-Augmented Generation) improves AI responses with relevant context.' },
-        { id: 'doc5', content: 'Workflows enable sequential and parallel execution of agent tasks.' }
-    ];
-
-    const engine = createSimpleQueryEngine(docs);
-
-    const results1 = await engine.query('agent framework', { topK: 2 });
-    console.log('   Query: "agent framework"');
-    console.log(`   Found: ${results1.length} results`);
-    results1.forEach((r, i) => {
-        console.log(`   [${i + 1}] ${r.content.slice(0, 50)}... (score: ${r.score.toFixed(2)})`);
-    });
-    console.log('   Success: ✅');
-
-    // Test 2: Different queries
-    console.log('\n2. Testing various queries:');
-    const queries = ['TypeScript', 'RAG', 'workflow', 'tools memory'];
-
-    for (const q of queries) {
-        const results = await engine.query(q, { topK: 1 });
-        console.log(`   "${q}" → ${results.length > 0 ? results[0].content.slice(0, 40) + '...' : 'No results'}`);
-    }
-    console.log('   Success: ✅');
-
-    // Test 3: Query for context string
-    console.log('\n3. Testing queryForContext:');
-    const context = await engine.queryForContext('agent tasks', { topK: 2 });
-    console.log('   Context string (preview):');
-    console.log('   ' + context.split('\n')[0]);
-    console.log('   Success: ✅');
-
-    // Test 4: Cache behavior
-    console.log('\n4. Testing caching:');
-    const start = Date.now();
-    await engine.query('agent framework', { topK: 2 });
-    const cachedTime = Date.now() - start;
-    console.log(`   Cached query time: ${cachedTime}ms (should be fast)`);
-
-    engine.clearCache();
-    const start2 = Date.now();
-    await engine.query('agent framework', { topK: 2 });
-    const uncachedTime = Date.now() - start2;
-    console.log(`   Uncached query time: ${uncachedTime}ms`);
-    console.log('   Success: ✅');
-
-    // Test 5: QueryEngine configuration
-    console.log('\n5. Testing custom QueryEngine configuration:');
-    const customEngine = new QueryEngine({
-        keywordSearch: async (query, options) => {
-            return docs
-                .filter(d => d.content.toLowerCase().includes(query.toLowerCase()))
-                .map(d => ({ id: d.id, content: d.content, score: 0.8 }))
-                .slice(0, options?.topK ?? 5);
-        },
-        defaultOptions: { mode: 'keyword', topK: 3 }
-    });
-
-    const customResults = await customEngine.query('TypeScript');
-    console.log(`   Custom engine results: ${customResults.length}`);
-    console.log('   Success: ✅');
-
-    // Test 6: Empty results handling
-    console.log('\n6. Testing empty results:');
-    const emptyResults = await engine.query('nonexistent_query_12345');
-    console.log(`   Results for nonsense query: ${emptyResults.length}`);
-
-    const emptyContext = await engine.queryForContext('nonexistent_query_12345');
-    console.log(`   Context: "${emptyContext}"`);
-    console.log('   Success: ✅');
-
-    console.log('\n=== QueryEngine Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/mcp/mcp-client-test.ts

@@ -1,136 +0,0 @@
-/**
- * MCP Client Integration Test
- * 
- * Tests the MCP (Model Context Protocol) client.
- * Note: Requires an MCP server for full integration tests.
- * 
- * Run: npx ts-node mcp-client.ts
- */
-
-import {
-    MCPClient,
-    createMCPClient,
-    getMCPTools,
-    type MCPClientConfig
-} from '../../../src/praisonai-ts/dist/mcp';
-
-async function main() {
-    console.log('=== MCPClient Integration Test ===\n');
-
-    // Test 1: Create MCP client
-    console.log('1. Testing MCPClient creation:');
-    const client = new MCPClient({
-        serverUrl: 'http://localhost:3000',
-        transport: 'http',
-        timeout: 5000,
-        verbose: true
-    });
-    console.log('   Client ID:', client.id);
-    console.log('   Connected:', client.isConnected());
-    console.log('   Success: ✅');
-
-    // Test 2: Factory function
-    console.log('\n2. Testing createMCPClient() factory:');
-    const client2 = createMCPClient({ serverUrl: 'http://localhost:8080' });
-    console.log('   Client created:', typeof client2);
-    console.log('   Success: ✅');
-
-    // Test 3: Transport configurations
-    console.log('\n3. Testing transport configurations:');
-    const transports: MCPClientConfig['transport'][] = ['http', 'websocket', 'sse', 'stdio'];
-
-    for (const transport of transports) {
-        try {
-            const c = new MCPClient({
-                transport,
-                serverUrl: transport !== 'stdio' ? 'http://localhost:3000' : undefined,
-                command: transport === 'stdio' ? 'npx' : undefined,
-                args: transport === 'stdio' ? ['mcp-server'] : undefined
-            });
-            console.log(`   ${transport}: ✅ (configured)`);
-        } catch (error: any) {
-            console.log(`   ${transport}: ⚠️ ${error.message}`);
-        }
-    }
-
-    // Test 4: Session info
-    console.log('\n4. Testing session management:');
-    const session = client.getSession();
-    console.log('   Session ID:', session.id);
-    console.log('   Connected:', session.connected);
-    console.log('   Tools:', session.tools.length);
-    console.log('   Resources:', session.resources.length);
-    console.log('   Success: ✅');
-
-    // Test 5: Live connection test (optional - requires running server)
-    const testServerUrl = process.env.MCP_SERVER_URL;
-    if (testServerUrl) {
-        console.log('\n5. Testing live MCP connection:');
-        try {
-            const liveClient = new MCPClient({
-                serverUrl: testServerUrl,
-                transport: 'http',
-                timeout: 10000,
-                verbose: false
-            });
-
-            await liveClient.connect();
-            console.log('   Connected: ✅');
-
-            const tools = await liveClient.listTools();
-            console.log(`   Tools discovered: ${tools.length}`);
-
-            for (const tool of tools.slice(0, 3)) {
-                console.log(`   - ${tool.name}: ${tool.description || 'No description'}`);
-            }
-
-            // Get tools in AI SDK format
-            const aiTools = await liveClient.getToolsAsAISDK();
-            console.log(`   AI SDK tools: ${aiTools.length}`);
-
-            await liveClient.disconnect();
-            console.log('   Disconnected: ✅');
-        } catch (error: any) {
-            console.log(`   ⚠️ Connection failed: ${error.message}`);
-        }
-    } else {
-        console.log('\n5. Live connection: Skipped (MCP_SERVER_URL not set)');
-        console.log('   Set MCP_SERVER_URL to test live connections');
-    }
-
-    // Test 6: Mock tool call simulation
-    console.log('\n6. Testing tool call preparation:');
-    const mockTool = {
-        name: 'search',
-        description: 'Search for information',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: { type: 'string', description: 'Search query' }
-            },
-            required: ['query']
-        }
-    };
-    console.log('   Mock tool:', mockTool.name);
-    console.log('   Schema:', JSON.stringify(mockTool.inputSchema));
-    console.log('   Success: ✅');
-
-    // Test 7: API Key configuration
-    console.log('\n7. Testing API key configuration:');
-    const authClient = new MCPClient({
-        serverUrl: 'http://api.example.com',
-        apiKey: 'test-api-key-12345'
-    });
-    console.log('   Client with API key: ✅');
-
-    // Test 8: getMCPTools helper
-    console.log('\n8. Testing getMCPTools helper signature:');
-    console.log('   getMCPTools function:', typeof getMCPTools);
-    console.log('   Returns: { client, tools }');
-    console.log('   Success: ✅');
-
-    console.log('\n=== MCPClient Tests Complete ===');
-    console.log('\nNote: For full integration tests, run an MCP server and set MCP_SERVER_URL');
-}
-
-main().catch(console.error);

examples/js/memory/memory-hooks.ts

@@ -1,137 +0,0 @@
-/**
- * MemoryHooks Integration Test
- * 
- * Tests pre/post hooks for memory operations.
- * 
- * Run: npx ts-node memory-hooks.ts
- */
-
-import {
-    MemoryHooks,
-    createMemoryHooks,
-    createLoggingHooks,
-    createValidationHooks,
-    Memory,
-    createMemory
-} from '../../../src/praisonai-ts/dist';
-
-async function main() {
-    console.log('=== MemoryHooks Integration Test ===\n');
-
-    // Test 1: Basic hooks
-    console.log('1. Testing basic MemoryHooks:');
-    const logs: string[] = [];
-
-    const hooks = new MemoryHooks({
-        beforeStore: async (key, value) => {
-            logs.push(`beforeStore: ${key}`);
-            return { key, value };
-        },
-        afterStore: async (key) => {
-            logs.push(`afterStore: ${key}`);
-        },
-        beforeRetrieve: async (key) => {
-            logs.push(`beforeRetrieve: ${key}`);
-            return key;
-        },
-        afterRetrieve: async (key, value) => {
-            logs.push(`afterRetrieve: ${key}`);
-            return value;
-        }
-    });
-
-    await hooks.beforeStore('key1', { data: 'value1' });
-    await hooks.afterStore('key1', { data: 'value1' });
-    await hooks.beforeRetrieve('key1');
-    await hooks.afterRetrieve('key1', { data: 'value1' });
-
-    console.log('   Triggered hooks:', logs);
-    console.log('   Success: ✅');
-
-    // Test 2: Logging hooks
-    console.log('\n2. Testing createLoggingHooks:');
-    const logMessages: string[] = [];
-    const loggingHooks = createLoggingHooks((msg) => logMessages.push(msg));
-
-    await loggingHooks.beforeStore('test', 'data');
-    await loggingHooks.afterStore('test', 'data');
-    await loggingHooks.beforeRetrieve('test');
-    await loggingHooks.afterRetrieve('test', 'data');
-
-    console.log('   Log messages:', logMessages.length);
-    logMessages.forEach(m => console.log('    -', m));
-    console.log('   Success: ✅');
-
-    // Test 3: Validation hooks
-    console.log('\n3. Testing createValidationHooks:');
-    const validationHooks = createValidationHooks((key, value) => {
-        // Only allow non-empty strings
-        if (typeof value !== 'string' || value.length === 0) {
-            return { valid: false, reason: 'Value must be non-empty string' };
-        }
-        return { valid: true };
-    });
-
-    const validResult = await validationHooks.beforeStore('good', 'valid string');
-    console.log('   Valid data allowed:', validResult !== null);
-
-    const invalidResult = await validationHooks.beforeStore('bad', '');
-    console.log('   Invalid data blocked:', invalidResult === null);
-    console.log('   Success: ✅');
-
-    // Test 4: Delete hooks
-    console.log('\n4. Testing delete hooks:');
-    const deleteHooks = new MemoryHooks({
-        beforeDelete: async (key) => {
-            console.log(`   [Hook] About to delete: ${key}`);
-            return true; // Allow deletion
-        },
-        afterDelete: async (key, success) => {
-            console.log(`   [Hook] Delete ${key}: ${success ? 'succeeded' : 'failed'}`);
-        }
-    });
-
-    const canDelete = await deleteHooks.beforeDelete('item-to-delete');
-    console.log('   Deletion allowed:', canDelete);
-    await deleteHooks.afterDelete('item-to-delete', true);
-    console.log('   Success: ✅');
-
-    // Test 5: Search hooks
-    console.log('\n5. Testing search hooks:');
-    const searchHooks = new MemoryHooks({
-        beforeSearch: async (query, options) => {
-            console.log(`   [Hook] Searching: "${query}"`);
-            // Could modify query here
-            return { query: query.toLowerCase(), options };
-        },
-        afterSearch: async (query, results) => {
-            console.log(`   [Hook] Found ${results.length} results for "${query}"`);
-            return results;
-        }
-    });
-
-    const searchParams = await searchHooks.beforeSearch('UPPERCASE QUERY');
-    console.log('   Modified query:', searchParams?.query);
-
-    await searchHooks.afterSearch('query', [{ id: '1' }, { id: '2' }]);
-    console.log('   Success: ✅');
-
-    // Test 6: Dynamic hook management
-    console.log('\n6. Testing dynamic hook management:');
-    const dynamicHooks = new MemoryHooks({});
-
-    console.log('   Initial config:', Object.keys(dynamicHooks.getConfig()).length === 0 ? 'empty' : 'has hooks');
-
-    dynamicHooks.addHook('logging', true);
-    dynamicHooks.setLogging(true);
-
-    console.log('   After adding logging:', dynamicHooks.getConfig().logging);
-
-    dynamicHooks.removeHook('logging');
-    console.log('   After removing:', dynamicHooks.getConfig().logging ?? 'undefined');
-    console.log('   Success: ✅');
-
-    console.log('\n=== MemoryHooks Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/run-feature-tests.ts

@@ -1,181 +0,0 @@
-/**
- * Feature Parity Integration Test Runner
- * 
- * Runs all integration tests for the new TypeScript features.
- * Tests include real API calls when OPENAI_API_KEY is available.
- * 
- * Run: npx ts-node run-feature-tests.ts
- */
-
-import { execSync, spawn } from 'child_process';
-import * as path from 'path';
-import * as fs from 'fs';
-
-interface TestResult {
-    name: string;
-    passed: boolean;
-    duration: number;
-    output: string;
-    error?: string;
-}
-
-const TEST_FILES = [
-    // Workflow patterns
-    'workflows/loop-pattern.ts',
-    'workflows/repeat-pattern.ts',
-    // Agents
-    'agents/audio-agent.ts',
-    // Knowledge
-    'knowledge/chonkie-adapter.ts',
-    // MCP
-    'mcp/mcp-client-test.ts',
-];
-
-async function runTest(testFile: string): Promise<TestResult> {
-    const startTime = Date.now();
-    const fullPath = path.join(__dirname, testFile);
-    const name = path.basename(testFile, '.ts');
-
-    return new Promise((resolve) => {
-        const proc = spawn('npx', ['ts-node', fullPath], {
-            cwd: __dirname,
-            env: { ...process.env },
-            stdio: ['pipe', 'pipe', 'pipe']
-        });
-
-        let stdout = '';
-        let stderr = '';
-
-        proc.stdout.on('data', (data) => {
-            stdout += data.toString();
-        });
-
-        proc.stderr.on('data', (data) => {
-            stderr += data.toString();
-        });
-
-        proc.on('close', (code) => {
-            const duration = Date.now() - startTime;
-            resolve({
-                name,
-                passed: code === 0,
-                duration,
-                output: stdout,
-                error: stderr || undefined
-            });
-        });
-
-        proc.on('error', (error) => {
-            const duration = Date.now() - startTime;
-            resolve({
-                name,
-                passed: false,
-                duration,
-                output: '',
-                error: error.message
-            });
-        });
-
-        // Timeout after 60 seconds
-        setTimeout(() => {
-            proc.kill();
-            resolve({
-                name,
-                passed: false,
-                duration: 60000,
-                output: stdout,
-                error: 'Test timed out after 60 seconds'
-            });
-        }, 60000);
-    });
-}
-
-async function main() {
-    console.log('╔════════════════════════════════════════════════════════════╗');
-    console.log('║     PraisonAI TypeScript Feature Parity Integration Tests  ║');
-    console.log('╚════════════════════════════════════════════════════════════╝\n');
-
-    // Environment info
-    console.log('Environment:');
-    console.log(`  OPENAI_API_KEY: ${process.env.OPENAI_API_KEY ? '✅ Set' : '❌ Not set'}`);
-    console.log(`  MCP_SERVER_URL: ${process.env.MCP_SERVER_URL ? '✅ Set' : '❌ Not set'}`);
-    console.log(`  Node version: ${process.version}`);
-    console.log('');
-
-    // Check if test files exist
-    console.log('Test Files:');
-    for (const file of TEST_FILES) {
-        const fullPath = path.join(__dirname, file);
-        const exists = fs.existsSync(fullPath);
-        console.log(`  ${exists ? '✅' : '❌'} ${file}`);
-    }
-    console.log('');
-
-    // Run tests
-    console.log('Running Tests...\n');
-    console.log('─'.repeat(60));
-
-    const results: TestResult[] = [];
-    for (const testFile of TEST_FILES) {
-        const fullPath = path.join(__dirname, testFile);
-        if (!fs.existsSync(fullPath)) {
-            results.push({
-                name: path.basename(testFile, '.ts'),
-                passed: false,
-                duration: 0,
-                output: '',
-                error: 'File not found'
-            });
-            continue;
-        }
-
-        console.log(`\n▶ Running: ${testFile}`);
-        const result = await runTest(testFile);
-        results.push(result);
-
-        if (result.passed) {
-            console.log(`  ✅ PASSED (${result.duration}ms)`);
-        } else {
-            console.log(`  ❌ FAILED (${result.duration}ms)`);
-            if (result.error) {
-                console.log(`     Error: ${result.error.slice(0, 200)}...`);
-            }
-        }
-    }
-
-    console.log('\n' + '─'.repeat(60));
-
-    // Summary
-    const passed = results.filter(r => r.passed).length;
-    const failed = results.filter(r => !r.passed).length;
-    const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
-
-    console.log('\n╔════════════════════════════════════════════════════════════╗');
-    console.log('║                      TEST SUMMARY                          ║');
-    console.log('╚════════════════════════════════════════════════════════════╝');
-    console.log(`  Total Tests: ${results.length}`);
-    console.log(`  Passed: ${passed} ✅`);
-    console.log(`  Failed: ${failed} ${failed > 0 ? '❌' : ''}`);
-    console.log(`  Duration: ${(totalDuration / 1000).toFixed(2)}s`);
-    console.log('');
-
-    // Detailed results
-    if (failed > 0) {
-        console.log('Failed Tests:');
-        for (const result of results.filter(r => !r.passed)) {
-            console.log(`  ❌ ${result.name}`);
-            if (result.error) {
-                console.log(`     ${result.error.slice(0, 100)}`);
-            }
-        }
-        console.log('');
-    }
-
-    // Exit with appropriate code
-    process.exit(failed > 0 ? 1 : 0);
-}
-
-main().catch((error) => {
-    console.error('Test runner failed:', error);
-    process.exit(1);
-});

examples/js/tools/subagent-tool.ts

@@ -1,112 +0,0 @@
-/**
- * SubagentTool Integration Test
- * 
- * Tests the agent-as-tool pattern with real agents.
- * 
- * Run: npx ts-node subagent-tool.ts
- * Requires: OPENAI_API_KEY
- */
-
-import {
-    Agent,
-    SubagentTool,
-    createSubagentTool,
-    createSubagentTools,
-    createDelegator
-} from '../../../src/praisonai-ts/dist';
-
-async function main() {
-    console.log('=== SubagentTool Integration Test ===\n');
-
-    // Test 1: Create SubagentTool
-    console.log('1. Testing SubagentTool creation:');
-    const mockAgent = {
-        name: 'MockAgent',
-        chat: async (input: string) => `Echo: ${input}`
-    };
-
-    const tool = new SubagentTool(mockAgent, {
-        name: 'echo',
-        description: 'Echo the input'
-    });
-
-    console.log('   Tool name:', tool.name);
-    console.log('   Tool ID:', tool.id);
-    console.log('   Schema:', JSON.stringify(tool.getSchema()));
-    console.log('   Success: ✅');
-
-    // Test 2: Execute tool with mock agent
-    console.log('\n2. Testing tool execution:');
-    const mockResult = await tool.execute({ input: 'Hello World' });
-    console.log('   Input: "Hello World"');
-    console.log('   Output:', mockResult);
-    console.log('   Success: ✅');
-
-    // Test 3: Factory function
-    console.log('\n3. Testing createSubagentTool factory:');
-    const factoryTool = createSubagentTool(mockAgent, { name: 'factory_echo' });
-    console.log('   Tool name:', factoryTool.name);
-    console.log('   Success: ✅');
-
-    // Test 4: Multiple subagent tools
-    console.log('\n4. Testing createSubagentTools (batch):');
-    const agents = [
-        { name: 'Agent1', chat: async (i: string) => `A1: ${i}` },
-        { name: 'Agent2', chat: async (i: string) => `A2: ${i}` }
-    ];
-    const tools = createSubagentTools(agents);
-    console.log('   Created tools:', tools.length);
-    tools.forEach(t => console.log('    -', t.name));
-    console.log('   Success: ✅');
-
-    // Test 5: AI SDK format conversion
-    console.log('\n5. Testing AI SDK format conversion:');
-    const aiTool = tool.toAISDKTool();
-    console.log('   Type:', aiTool.type);
-    console.log('   Function name:', aiTool.function.name);
-    console.log('   Has execute:', typeof aiTool.execute === 'function');
-    console.log('   Success: ✅');
-
-    // Test 6: Live test with real agent
-    if (process.env.OPENAI_API_KEY) {
-        console.log('\n6. Testing with real Agent (live API):');
-        try {
-            const researcher = new Agent({
-                name: 'QuickResearcher',
-                instructions: 'Answer in exactly 5 words.',
-                llm: 'openai/gpt-4o-mini'
-            });
-
-            const researchTool = createSubagentTool(researcher, {
-                name: 'quick_research',
-                description: 'Get a quick 5-word answer'
-            });
-
-            const result = await researchTool.execute({ input: 'What is AI?' });
-            console.log('   Question: "What is AI?"');
-            console.log('   Answer:', result);
-            console.log('   Success: ✅');
-        } catch (error: any) {
-            console.log('   Error:', error.message);
-        }
-    } else {
-        console.log('\n6. Live test: Skipped (OPENAI_API_KEY not set)');
-    }
-
-    // Test 7: Input/Output transforms
-    console.log('\n7. Testing transforms:');
-    const transformTool = createSubagentTool(mockAgent, {
-        name: 'transform_echo',
-        inputTransform: (input) => input.toUpperCase(),
-        outputTransform: (output) => `[TRANSFORMED] ${output}`
-    });
-
-    const transformResult = await transformTool.execute({ input: 'hello' });
-    console.log('   Input: "hello"');
-    console.log('   Output:', transformResult);
-    console.log('   Success: ✅');
-
-    console.log('\n=== SubagentTool Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/workflows/loop-pattern.ts

@@ -1,88 +0,0 @@
-/**
- * Loop Pattern Integration Test
- * 
- * Tests the Loop workflow pattern with real data.
- * 
- * Run: npx ts-node loop-pattern.ts
- */
-
-import { Loop, loopPattern, Agent, Workflow } from '../../../src/praisonai-ts/dist';
-
-async function main() {
-    console.log('=== Loop Pattern Integration Test ===\n');
-
-    // Test 1: Basic Loop with array
-    console.log('1. Testing Loop with array iteration:');
-    const items = ['apple', 'banana', 'cherry'];
-
-    const processor = (item: string) => `Processed: ${item.toUpperCase()}`;
-    const arrayLoop = new Loop(processor, { over: 'items' });
-
-    const result1 = await arrayLoop.run({ items });
-    console.log('   Results:', result1.results);
-    console.log('   Iterations:', result1.iterations);
-    console.log('   Success:', result1.success ? '✅' : '❌');
-
-    // Test 2: Loop with convenience function
-    console.log('\n2. Testing loop() convenience function:');
-    const doubler = (n: number) => n * 2;
-    const numberLoop = loopPattern(doubler, { over: 'numbers' });
-
-    const result2 = await numberLoop.run({ numbers: [1, 2, 3, 4, 5] });
-    console.log('   Input: [1, 2, 3, 4, 5]');
-    console.log('   Output:', result2.results);
-    console.log('   Success:', result2.success ? '✅' : '❌');
-
-    // Test 3: Loop with Agent (requires OPENAI_API_KEY)
-    if (process.env.OPENAI_API_KEY) {
-        console.log('\n3. Testing Loop with Agent (live API):');
-        try {
-            const agent = new Agent({
-                name: 'Summarizer',
-                instructions: 'Summarize the given topic in one sentence.',
-                llm: 'openai/gpt-4o-mini'
-            });
-
-            const topics = ['AI', 'TypeScript'];
-            const agentLoop = new Loop(agent, { over: 'topics', varName: 'topic' });
-
-            console.log('   Processing topics:', topics);
-            const result3 = await agentLoop.run({ topics });
-
-            result3.results.forEach((res, i) => {
-                console.log(`   [${topics[i]}]: ${res.slice(0, 80)}...`);
-            });
-            console.log('   Success:', result3.success ? '✅' : '❌');
-        } catch (error: any) {
-            console.log('   ⚠️ Agent test failed:', error.message);
-        }
-    } else {
-        console.log('\n3. Agent Loop Test: Skipped (OPENAI_API_KEY not set)');
-    }
-
-    // Test 4: Loop with error handling
-    console.log('\n4. Testing Loop with continueOnError:');
-    const errorProneProcessor = (item: string) => {
-        if (item === 'fail') throw new Error('Intentional failure');
-        return `OK: ${item}`;
-    };
-
-    const errorLoop = new Loop(errorProneProcessor, {
-        over: 'items',
-        continueOnError: true
-    });
-
-    const result4 = await errorLoop.run({ items: ['a', 'fail', 'b'] });
-    console.log('   Results:', result4.results);
-    console.log('   Errors:', result4.errors.length);
-    console.log('   Success:', result4.success ? '✅' : '❌ (expected - has errors)');
-
-    // Test 5: Loop type exports
-    console.log('\n5. Verifying exports:');
-    console.log('   Loop class:', typeof Loop);
-    console.log('   loop function:', typeof loopPattern);
-
-    console.log('\n=== Loop Pattern Tests Complete ===');
-}
-
-main().catch(console.error);

examples/js/workflows/repeat-pattern.ts

@@ -1,114 +0,0 @@
-/**
- * Repeat Pattern Integration Test
- * 
- * Tests the Repeat workflow pattern for evaluator-optimizer loops.
- * 
- * Run: npx ts-node repeat-pattern.ts
- */
-
-import { Repeat, repeatPattern, Agent } from '../../../src/praisonai-ts/dist';
-
-async function main() {
-    console.log('=== Repeat Pattern Integration Test ===\n');
-
-    // Test 1: Basic repeat until condition
-    console.log('1. Testing Repeat with condition:');
-    let counter = 0;
-    const incrementer = () => {
-        counter++;
-        return `Iteration ${counter}`;
-    };
-
-    const repeat1 = new Repeat(incrementer, {
-        until: (ctx) => ctx.iteration >= 3,
-        maxIterations: 10
-    });
-
-    const result1 = await repeat1.run('start');
-    console.log('   Results:', result1.iterations);
-    console.log('   Final:', result1.result);
-    console.log('   Condition met:', result1.conditionMet ? '✅' : '❌');
-    console.log('   Max reached:', result1.maxReached ? '⚠️' : 'No');
-
-    // Test 2: Repeat with content condition
-    console.log('\n2. Testing Repeat with content-based condition:');
-    let quality = 0;
-    const improver = (input: string, prev: string | null) => {
-        quality += 25;
-        return `Quality: ${quality}% - ${prev || input}`;
-    };
-
-    const repeat2 = new Repeat(improver, {
-        until: (ctx) => ctx.lastResult?.includes('100%') ?? false,
-        maxIterations: 5
-    });
-
-    quality = 0; // Reset
-    const result2 = await repeat2.run('Initial draft');
-    console.log('   Iterations:', result2.count);
-    console.log('   Final:', result2.result);
-    console.log('   Condition met:', result2.conditionMet ? '✅' : '❌');
-
-    // Test 3: Repeat reaching max iterations
-    console.log('\n3. Testing Repeat hitting max iterations:');
-    const neverDone = () => 'still working...';
-
-    const repeat3 = new Repeat(neverDone, {
-        until: () => false, // Never satisfied
-        maxIterations: 3
-    });
-
-    const result3 = await repeat3.run('start');
-    console.log('   Iterations:', result3.count);
-    console.log('   Max reached:', result3.maxReached ? '✅ (expected)' : '❌');
-
-    // Test 4: Repeat with Agent (requires OPENAI_API_KEY)
-    if (process.env.OPENAI_API_KEY) {
-        console.log('\n4. Testing Repeat with Agent (live API):');
-        try {
-            const agent = new Agent({
-                name: 'Optimizer',
-                instructions: 'Improve the given text. Add more detail and clarity. Say "DONE" when satisfied.',
-                llm: 'openai/gpt-4o-mini'
-            });
-
-            const repeat4 = new Repeat(agent, {
-                until: (ctx) => ctx.lastResult?.includes('DONE') ?? false,
-                maxIterations: 3
-            });
-
-            const result4 = await repeat4.run('Make this better: Hello world');
-            console.log('   Iterations:', result4.count);
-            console.log('   Final (truncated):', result4.result.slice(0, 100) + '...');
-            console.log('   Condition met:', result4.conditionMet ? '✅' : 'Max reached');
-        } catch (error: any) {
-            console.log('   ⚠️ Agent test failed:', error.message);
-        }
-    } else {
-        console.log('\n4. Agent Repeat Test: Skipped (OPENAI_API_KEY not set)');
-    }
-
-    // Test 5: Convenience function
-    console.log('\n5. Testing repeatPattern() convenience function:');
-    let seq = 0;
-    const sequencer = () => `seq-${++seq}`;
-
-    const repeat5 = repeatPattern(sequencer, {
-        until: (ctx) => ctx.iteration >= 2,
-        maxIterations: 5
-    });
-
-    seq = 0; // Reset
-    const result5 = await repeat5.run('');
-    console.log('   Results:', result5.iterations);
-    console.log('   Success:', result5.conditionMet ? '✅' : '❌');
-
-    // Test 6: Verify exports
-    console.log('\n6. Verifying exports:');
-    console.log('   Repeat class:', typeof Repeat);
-    console.log('   repeatPattern function:', typeof repeatPattern);
-
-    console.log('\n=== Repeat Pattern Tests Complete ===');
-}
-
-main().catch(console.error);

examples/observability/multi_agent_tracing.py

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

examples/output_ux/basic_output_example.py

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

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

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

examples/python/agents/code-agent.py

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

examples/python/agents/image-agent.py

@@ -4,7 +4,7 @@ from praisonaiagents.tools import duckduckgo
 agent = Agent(instructions="You are a Image Analysis Agent", tools=[duckduckgo])
 agent.start("I want to go London next week, find me a good hotel and flight")
 
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 
 # Create Image Analysis Agent
 image_agent = Agent(
@@ -36,7 +36,7 @@ task2 = Task(
 )
 
 # Create Agents instance
-agents = AgentTeam(
+agents = Agents(
     agents=[image_agent],
     tasks=[task1, task2],
     process="sequential",

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

@@ -4,7 +4,7 @@ from praisonaiagents.tools import duckduckgo
 agent = Agent(instructions="You are a Image Analysis Agent", tools=[duckduckgo])
 agent.start("I want to go London next week, find me a good hotel and flight")
 
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 
 # Create Image Analysis Agent
 image_agent = Agent(
@@ -36,7 +36,7 @@ task2 = Task(
 )
 
 # Create Agents instance
-agents = AgentTeam(
+agents = Agents(
     agents=[image_agent],
     tasks=[task1, task2],
     process="sequential",

examples/python/agents/math-agent.py

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

examples/python/agents/multi-provider-agent.py

@@ -6,7 +6,7 @@ agent-based selection for cost optimization and performance.
 """
 
 import os
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.agent import RouterAgent
 from praisonaiagents.llm.model_router import ModelRouter, ModelProfile, TaskComplexity
 
@@ -48,7 +48,7 @@ def example_auto_routing():
     )
     
     # Run the tasks
-    agents = AgentTeam(
+    agents = Agents(
         agents=[research_agent],
         tasks=[simple_task, moderate_task, complex_task],
         process="sequential", output="verbose"
@@ -113,7 +113,7 @@ def example_cost_optimized_workflow():
     )
     
     # Run workflow
-    workflow = AgentTeam(
+    workflow = Agents(
         agents=[analyzer, writer],
         tasks=[analysis_task, writing_task],
         process="sequential", output="verbose"
@@ -135,7 +135,7 @@ def example_auto_agents_multi_provider():
     from praisonaiagents.agents import AutoAgents
     
     # Create AutoAgents that will automatically assign appropriate models
-    auto_agents = AutoAgentTeam(
+    auto_agents = AutoAgents(
         instructions="Create a market research report on electric vehicles. Include data analysis, competitor analysis, and future projections.",
         max_agents=3,
         llm="gpt-4o-mini",  # Default model for agent generation
@@ -239,7 +239,7 @@ def example_custom_routing():
     ]
     
     # Run tasks
-    agents = AgentTeam(
+    agents = Agents(
         agents=[coder],
         tasks=tasks,
         process="sequential", output="verbose"

examples/python/agents/video-agent.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 
 # Create Video Analysis Agent
 video_agent = Agent(
@@ -25,7 +25,7 @@ task1 = Task(
 )
 
 # Create Agents instance
-agents = AgentTeam(
+agents = Agents(
     agents=[video_agent],
     tasks=[task1],
     process="sequential",

examples/python/agents/wikipedia-agent.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import wiki_search, wiki_summary, wiki_page, wiki_random, wiki_language
 
 agent = Agent(

examples/python/api/multi-agents-api.py

@@ -1,6 +1,6 @@
-from praisonaiagents import Agent, AgentTeam, Tools
+from praisonaiagents import Agent, Agents, Tools
 
 research_agent = Agent(name="Research", instructions="You are a research agent to search internet about AI 2024", tools=[Tools.internet_search])
 summarise_agent = Agent(name="Summarise", instructions="You are a summarize agent to summarise in points")
-agents = AgentTeam(agents=[research_agent, summarise_agent])
+agents = Agents(agents=[research_agent, summarise_agent])
 agents.launch(path="/agents", port=3030)

examples/python/api/multi-agents-group-api.py

@@ -1,8 +1,8 @@
-from praisonaiagents import Agent, AgentTeam, Tools
+from praisonaiagents import Agent, Agents, Tools
 
 research_agent = Agent(name="Research", instructions="You are a research agent to search internet about AI 2024", tools=[Tools.internet_search])
 summarise_agent = Agent(name="Summarise", instructions="You are a summarize agent to summarise in points")
-agents = AgentTeam(agents=[research_agent, summarise_agent])
-agents2 = AgentTeam(agents=[research_agent])
+agents = Agents(agents=[research_agent, summarise_agent])
+agents2 = Agents(agents=[research_agent])
 agents.launch(path="/agents", port=3030)
 agents2.launch(path="/agents2", port=3030)

examples/python/api/secondary-market-research-api.py

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

examples/python/api/simple-mcp-multi-agents-server.py

@@ -1,4 +1,4 @@
-from praisonaiagents import Agent, AgentTeam
+from praisonaiagents import Agent, Agents
 from duckduckgo_search import DDGS
 
 def internet_search_tool(query: str):
@@ -15,5 +15,5 @@ def internet_search_tool(query: str):
 agent = Agent(name="SearchAgent", instructions="You Search the internet for information", tools=[internet_search_tool])
 agent2 = Agent(name="SummariseAgent", instructions="You Summarise the information")
 
-agents = AgentTeam(name="MultiAgents", agents=[agent, agent2])
+agents = Agents(name="MultiAgents", agents=[agent, agent2])
 agents.launch(port=8080, protocol="mcp")

examples/python/audio/roundtrip.py

@@ -1,10 +0,0 @@
-from praisonaiagents import AudioAgent
-
-# Text to Speech
-tts = AudioAgent(llm="openai/tts-1")
-tts.say("Hello!", output="hello.mp3")
-
-# Speech to Text
-stt = AudioAgent(llm="openai/whisper-1")
-text = stt.listen("hello.mp3")
-print(text)

examples/python/audio/stt_advanced.py

@@ -1,7 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="groq/whisper-large-v3")  # 10x faster
-text = agent.transcribe("audio.mp3", language="en")
-print(text)
-
-# Models: openai/whisper-1, groq/whisper-large-v3, deepgram/nova-2

examples/python/audio/stt_basic.py

@@ -1,8 +0,0 @@
-# Speech-to-Text with Groq (fastest)
-# Requires: export GROQ_API_KEY=your-key
-
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="groq/whisper-large-v3")
-text = agent.listen("audio.mp3")  # Replace with your audio file
-print(text)

examples/python/audio/stt_deepgram.py

@@ -1,5 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="deepgram/nova-2")
-text = agent.listen("audio.mp3")
-print(text)

examples/python/audio/stt_groq.py

@@ -1,5 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="groq/whisper-large-v3")
-text = agent.listen("audio.mp3")
-print(text)

examples/python/audio/stt_openai.py

@@ -1,5 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="openai/whisper-1")
-text = agent.listen("audio.mp3")
-print(text)

examples/python/audio/tts_advanced.py

@@ -1,7 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="openai/tts-1-hd")
-agent.speech("Hello!", voice="nova", speed=1.2, output="hello.mp3")
-
-# Voices: alloy, echo, fable, onyx, nova, shimmer
-# Models: openai/tts-1, openai/tts-1-hd, openai/gpt-4o-mini-tts

examples/python/audio/tts_basic.py

@@ -1,8 +0,0 @@
-# Text-to-Speech with OpenAI
-# Requires: export OPENAI_API_KEY=your-key
-
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="openai/tts-1")
-agent.say("Hello world!", output="hello.mp3")
-print("Saved to hello.mp3")

examples/python/audio/tts_elevenlabs.py

@@ -1,4 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="elevenlabs/eleven_multilingual_v2")
-agent.say("Hello world!", output="hello.mp3")

examples/python/audio/tts_gemini.py

@@ -1,4 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="gemini/gemini-2.5-flash-preview-tts")
-agent.say("Hello world!", output="hello.mp3", voice="leda")

examples/python/audio/tts_openai.py

@@ -1,4 +0,0 @@
-from praisonaiagents import AudioAgent
-
-agent = AudioAgent(llm="openai/tts-1")
-agent.say("Hello world!", output="hello.mp3")

examples/python/bot_example.py

@@ -1,76 +0,0 @@
-"""
-Messaging Bot Example - Deploy Agents to Telegram, Discord, Slack
-
-This example demonstrates how to configure bots for different
-messaging platforms.
-"""
-
-import os
-from praisonaiagents import Agent, BotConfig
-
-# Telegram Bot Configuration
-telegram_config = BotConfig(
-    token=os.environ.get("TELEGRAM_BOT_TOKEN", ""),
-    command_prefix="/",
-    mention_required=True,
-    typing_indicator=True,
-    max_message_length=4096,
-    metadata={"platform": "telegram"}
-)
-
-# Discord Bot Configuration
-discord_config = BotConfig(
-    token=os.environ.get("DISCORD_BOT_TOKEN", ""),
-    command_prefix="!",
-    mention_required=True,
-    typing_indicator=True,
-    metadata={
-        "platform": "discord",
-        "guild_ids": []  # Add your guild IDs here
-    }
-)
-
-# Slack Bot Configuration
-slack_config = BotConfig(
-    token=os.environ.get("SLACK_BOT_TOKEN", ""),
-    command_prefix="/",
-    mention_required=True,
-    typing_indicator=True,
-    metadata={
-        "platform": "slack",
-        "app_token": os.environ.get("SLACK_APP_TOKEN", "")
-    }
-)
-
-# Create the agent that will handle messages
-assistant = Agent(
-    name="assistant",
-    instructions="""You are a helpful assistant that responds to messages 
-    from users on messaging platforms. Be friendly and concise.""",
-    llm="gpt-4o-mini"
-)
-
-if __name__ == "__main__":
-    print("Bot Configurations:")
-    print()
-    
-    print("Telegram Config:")
-    print(f"  Token configured: {bool(telegram_config.token)}")
-    print(f"  Command prefix: {telegram_config.command_prefix}")
-    print(f"  Mention required: {telegram_config.mention_required}")
-    print()
-    
-    print("Discord Config:")
-    print(f"  Token configured: {bool(discord_config.token)}")
-    print(f"  Command prefix: {discord_config.command_prefix}")
-    print()
-    
-    print("Slack Config:")
-    print(f"  Token configured: {bool(slack_config.token)}")
-    print(f"  Command prefix: {slack_config.command_prefix}")
-    print()
-    
-    print("To start a bot, use the CLI:")
-    print("  praisonai bot telegram --token $TELEGRAM_BOT_TOKEN")
-    print("  praisonai bot discord --token $DISCORD_BOT_TOKEN")
-    print("  praisonai bot slack --token $SLACK_BOT_TOKEN")

examples/python/camera/camera-basic.py

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

examples/python/camera/camera-continuous.py

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

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

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

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

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

examples/python/concepts/context-engineering-workflow.py

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

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

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

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

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

examples/python/concepts/rag-agents.py

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

examples/python/concepts/reasoning-extraction.py

@@ -8,7 +8,7 @@ This example demonstrates how to extract and utilize reasoning patterns in Prais
 - Decision rationale extraction
 """
 
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 from typing import Dict, List, Tuple
 from pydantic import BaseModel
 import json
@@ -100,7 +100,7 @@ def demonstrate_reasoning_extraction():
         context=[problem_task]
     )
     
-    workflow = AgentTeam(
+    workflow = Agents(
         agents=[cot_agent, reasoning_extractor],
         tasks=[problem_task, extract_task],
         process="sequential", output="verbose"
@@ -183,7 +183,7 @@ def advanced_reasoning_patterns():
         context=[deductive_task, inductive_task, abductive_task]
     )
     
-    workflow = AgentTeam(
+    workflow = Agents(
         agents=[cot_agent, reasoning_validator],
         tasks=[deductive_task, inductive_task, abductive_task, validation_task],
         process="sequential", output="verbose"

examples/python/concepts/repetitive-agents.py

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

examples/python/concepts/routing-patterns.py

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

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

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

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

@@ -5,7 +5,7 @@ This example demonstrates self-reflection capabilities using PraisonAI's
 built-in reflection features for iterative improvement and quality optimization.
 """
 
-from praisonaiagents import Agent, Task, AgentTeam
+from praisonaiagents import Agent, Task, Agents
 from praisonaiagents.tools import internet_search
 
 print("=== Self-Reflection Optimization Patterns Example ===\n")

examples/python/concepts/simple-csv-url-processor.py

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

examples/python/conditional_branching_example.py

@@ -1,391 +0,0 @@
-"""
-Conditional Branching Example - PraisonAI Agents
-
-This example demonstrates the `if:` pattern for conditional workflow execution:
-1. Basic if/then/else branching
-2. Numeric condition evaluation (>, <, >=, <=, ==, !=)
-3. String condition evaluation (==, !=)
-4. Contains condition (in, contains)
-5. Combining if: with loop: for per-item decisions
-
-The if: pattern enables dynamic workflow paths based on
-runtime conditions and variable values.
-"""
-
-from praisonaiagents import AgentFlow, WorkflowContext, StepResult
-from praisonaiagents.workflows import if_, loop
-
-
-# =============================================================================
-# Example 1: Basic If/Then/Else - Score-Based Routing
-# =============================================================================
-
-def basic_if_example():
-    """
-    Route to different handlers based on a score threshold.
-    """
-    print("\n" + "="*60)
-    print("Example 1: Basic If/Then/Else - Score Routing")
-    print("="*60)
-    
-    def approve(ctx: WorkflowContext) -> StepResult:
-        score = ctx.variables.get("score", 0)
-        print(f"  ✅ APPROVED: Score {score} meets threshold")
-        return StepResult(output="Application approved")
-    
-    def reject(ctx: WorkflowContext) -> StepResult:
-        score = ctx.variables.get("score", 0)
-        print(f"  ❌ REJECTED: Score {score} below threshold")
-        return StepResult(output="Application rejected")
-    
-    # Test with passing score
-    workflow_pass = AgentFlow(
-        steps=[
-            if_(
-                condition="{{score}} >= 70",
-                then_steps=[approve],
-                else_steps=[reject]
-            )
-        ],
-        variables={"score": 85}
-    )
-    
-    print("\nTest 1: Score = 85")
-    workflow_pass.start("Evaluate application")
-    
-    # Test with failing score
-    workflow_fail = AgentFlow(
-        steps=[
-            if_(
-                condition="{{score}} >= 70",
-                then_steps=[approve],
-                else_steps=[reject]
-            )
-        ],
-        variables={"score": 55}
-    )
-    
-    print("\nTest 2: Score = 55")
-    workflow_fail.start("Evaluate application")
-
-
-# =============================================================================
-# Example 2: String Condition - Status-Based Processing
-# =============================================================================
-
-def string_condition_example():
-    """
-    Branch based on string equality.
-    """
-    print("\n" + "="*60)
-    print("Example 2: String Condition - Status Processing")
-    print("="*60)
-    
-    def process_active(ctx: WorkflowContext) -> StepResult:
-        print("  🟢 Processing ACTIVE user")
-        return StepResult(output="Active user processed")
-    
-    def process_inactive(ctx: WorkflowContext) -> StepResult:
-        print("  🔴 Processing INACTIVE user")
-        return StepResult(output="Inactive user archived")
-    
-    # Test with active status
-    workflow = AgentFlow(
-        steps=[
-            if_(
-                condition="{{status}} == active",
-                then_steps=[process_active],
-                else_steps=[process_inactive]
-            )
-        ],
-        variables={"status": "active"}
-    )
-    
-    print("\nTest: status = 'active'")
-    workflow.start("Process user")
-    
-    # Test with inactive status
-    workflow2 = AgentFlow(
-        steps=[
-            if_(
-                condition="{{status}} == active",
-                then_steps=[process_active],
-                else_steps=[process_inactive]
-            )
-        ],
-        variables={"status": "inactive"}
-    )
-    
-    print("\nTest: status = 'inactive'")
-    workflow2.start("Process user")
-
-
-# =============================================================================
-# Example 3: Contains Condition - Content Filtering
-# =============================================================================
-
-def contains_condition_example():
-    """
-    Branch based on whether a string contains a substring.
-    """
-    print("\n" + "="*60)
-    print("Example 3: Contains Condition - Content Filtering")
-    print("="*60)
-    
-    def flag_content(ctx: WorkflowContext) -> StepResult:
-        print("  🚨 FLAGGED: Message contains sensitive content")
-        return StepResult(output="Content flagged for review")
-    
-    def approve_content(ctx: WorkflowContext) -> StepResult:
-        print("  ✅ APPROVED: Message is clean")
-        return StepResult(output="Content approved")
-    
-    # Test with flagged content
-    workflow1 = AgentFlow(
-        steps=[
-            if_(
-                condition="error in {{message}}",
-                then_steps=[flag_content],
-                else_steps=[approve_content]
-            )
-        ],
-        variables={"message": "System error: connection failed"}
-    )
-    
-    print("\nTest 1: Message contains 'error'")
-    workflow1.start("Filter content")
-    
-    # Test with clean content
-    workflow2 = AgentFlow(
-        steps=[
-            if_(
-                condition="error in {{message}}",
-                then_steps=[flag_content],
-                else_steps=[approve_content]
-            )
-        ],
-        variables={"message": "Operation completed successfully"}
-    )
-    
-    print("\nTest 2: Message is clean")
-    workflow2.start("Filter content")
-
-
-# =============================================================================
-# Example 4: If Inside Loop - Per-Item Decisions
-# =============================================================================
-
-def if_inside_loop_example():
-    """
-    Make decisions for each item in a collection.
-    Combines iteration with conditional branching.
-    """
-    print("\n" + "="*60)
-    print("Example 4: If Inside Loop - Per-Item Decisions")
-    print("="*60)
-    
-    results = {"premium": [], "standard": []}
-    
-    def premium_service(ctx: WorkflowContext) -> StepResult:
-        customer = ctx.variables.get("customer", {})
-        name = customer.get("name", "Unknown")
-        results["premium"].append(name)
-        print(f"  ⭐ {name}: Premium service activated")
-        return StepResult(output=f"Premium service for {name}")
-    
-    def standard_service(ctx: WorkflowContext) -> StepResult:
-        customer = ctx.variables.get("customer", {})
-        name = customer.get("name", "Unknown")
-        results["standard"].append(name)
-        print(f"  📦 {name}: Standard service activated")
-        return StepResult(output=f"Standard service for {name}")
-    
-    workflow = AgentFlow(
-        steps=[
-            loop(
-                steps=[
-                    if_(
-                        condition="{{customer.tier}} == premium",
-                        then_steps=[premium_service],
-                        else_steps=[standard_service]
-                    )
-                ],
-                over="customers",
-                var_name="customer"
-            )
-        ],
-        variables={
-            "customers": [
-                {"name": "Alice", "tier": "premium"},
-                {"name": "Bob", "tier": "standard"},
-                {"name": "Charlie", "tier": "premium"},
-                {"name": "Diana", "tier": "standard"}
-            ]
-        }
-    )
-    
-    print("\nProcessing customers:")
-    workflow.start("Assign service tiers")
-    
-    print(f"\nSummary:")
-    print(f"  Premium customers: {results['premium']}")
-    print(f"  Standard customers: {results['standard']}")
-
-
-# =============================================================================
-# Example 5: Nested Conditions - Multi-Level Decision Tree
-# =============================================================================
-
-def nested_conditions_example():
-    """
-    Demonstrate nested if conditions for complex decision trees.
-    """
-    print("\n" + "="*60)
-    print("Example 5: Nested Conditions - Decision Tree")
-    print("="*60)
-    
-    def vip_treatment(ctx: WorkflowContext) -> StepResult:
-        print("  👑 VIP Treatment: Dedicated support + Priority queue")
-        return StepResult(output="VIP treatment applied")  # noqa: ARG001
-    
-    def regular_premium(ctx: WorkflowContext) -> StepResult:
-        print("  ⭐ Premium: Priority support")
-        return StepResult(output="Premium support applied")
-    
-    def basic_support(ctx: WorkflowContext) -> StepResult:
-        print("  📞 Basic: Standard support queue")
-        return StepResult(output="Basic support applied")
-    
-    # Outer condition: Is premium?
-    # Inner condition (if premium): Is VIP?
-    workflow = AgentFlow(
-        steps=[
-            if_(
-                condition="{{tier}} == premium",
-                then_steps=[
-                    if_(
-                        condition="{{spend}} > 10000",
-                        then_steps=[vip_treatment],
-                        else_steps=[regular_premium]
-                    )
-                ],
-                else_steps=[basic_support]
-            )
-        ],
-        variables={"tier": "premium", "spend": 15000}
-    )
-    
-    print("\nTest 1: Premium tier, high spend")
-    workflow.start("Determine support level")
-    
-    workflow2 = AgentFlow(
-        steps=[
-            if_(
-                condition="{{tier}} == premium",
-                then_steps=[
-                    if_(
-                        condition="{{spend}} > 10000",
-                        then_steps=[vip_treatment],
-                        else_steps=[regular_premium]
-                    )
-                ],
-                else_steps=[basic_support]
-            )
-        ],
-        variables={"tier": "premium", "spend": 5000}
-    )
-    
-    print("\nTest 2: Premium tier, low spend")
-    workflow2.start("Determine support level")
-    
-    workflow3 = AgentFlow(
-        steps=[
-            if_(
-                condition="{{tier}} == premium",
-                then_steps=[
-                    if_(
-                        condition="{{spend}} > 10000",
-                        then_steps=[vip_treatment],
-                        else_steps=[regular_premium]
-                    )
-                ],
-                else_steps=[basic_support]
-            )
-        ],
-        variables={"tier": "basic", "spend": 20000}
-    )
-    
-    print("\nTest 3: Basic tier (regardless of spend)")
-    workflow3.start("Determine support level")
-
-
-# =============================================================================
-# Example 6: No Else Branch - Optional Processing
-# =============================================================================
-
-def no_else_example():
-    """
-    If condition without else branch - only execute if true.
-    """
-    print("\n" + "="*60)
-    print("Example 6: No Else Branch - Optional Processing")
-    print("="*60)
-    
-    def send_notification(ctx: WorkflowContext) -> StepResult:
-        print("  📧 Notification sent!")
-        return StepResult(output="Notification sent")
-    
-    def continue_processing(ctx: WorkflowContext) -> StepResult:
-        print("  ➡️ Continuing with main workflow...")
-        return StepResult(output="Continued")
-    
-    # Only send notification if opted in
-    workflow = AgentFlow(
-        steps=[
-            if_(
-                condition="{{notify}} == true",
-                then_steps=[send_notification]
-                # No else_steps - just skip if false
-            ),
-            continue_processing
-        ],
-        variables={"notify": "true"}
-    )
-    
-    print("\nTest 1: notify = true")
-    workflow.start("Process with notification")
-    
-    workflow2 = AgentFlow(
-        steps=[
-            if_(
-                condition="{{notify}} == true",
-                then_steps=[send_notification]
-            ),
-            continue_processing
-        ],
-        variables={"notify": "false"}
-    )
-    
-    print("\nTest 2: notify = false")
-    workflow2.start("Process without notification")
-
-
-# =============================================================================
-# Main - Run All Examples
-# =============================================================================
-
-if __name__ == "__main__":
-    print("\n" + "="*60)
-    print("PraisonAI Conditional Branching Examples")
-    print("="*60)
-    
-    basic_if_example()
-    string_condition_example()
-    contains_condition_example()
-    if_inside_loop_example()
-    nested_conditions_example()
-    no_else_example()
-    
-    print("\n" + "="*60)
-    print("All conditional branching examples completed!")
-    print("="*60)

examples/python/custom_tools/example_latency_tracking.py

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

examples/python/custom_tools/mcp_server_latency_example.py

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

examples/python/data/cot-agents.py

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

examples/python/eval/README.md

@@ -1,43 +0,0 @@
-# EvaluationLoop Examples
-
-Examples demonstrating iterative evaluation and improvement patterns.
-
-## Quick Start
-
-```bash
-pip install praisonaiagents
-export OPENAI_API_KEY=your-key
-```
-
-## Examples
-
-| File | Description |
-|------|-------------|
-| `basic_evaluation_loop.py` | Simple loop: Run → Judge → Improve |
-| `multi_step_task_loop.py` | Sequential tasks with context passing |
-| `recipe_optimization_loop.py` | CLI-based recipe optimization |
-
-## Pattern
-
-```
-┌─────────┐     ┌─────────┐     ┌──────────┐
-│  Agent  │ ──► │  Judge  │ ──► │ Feedback │
-│  runs   │     │ scores  │     │ improves │
-└─────────┘     └─────────┘     └──────────┘
-     ▲                               │
-     └───────────────────────────────┘
-           (repeat until 8.0+)
-```
-
-## Run Examples
-
-```bash
-# Basic loop
-python basic_evaluation_loop.py
-
-# Multi-step with context
-python multi_step_task_loop.py
-
-# CLI recipe loop
-python recipe_optimization_loop.py "research AI trends"
-```

examples/python/eval/basic_evaluation_loop.py

@@ -1,73 +0,0 @@
-"""
-Basic EvaluationLoop Example
-
-Demonstrates the iterative evaluation loop pattern:
-Run agent → Judge output → Improve → Repeat until threshold met.
-
-Usage:
-    pip install praisonaiagents
-    export OPENAI_API_KEY=your-key
-    python basic_evaluation_loop.py
-"""
-from praisonaiagents import Agent
-from praisonaiagents.eval import EvaluationLoop
-
-
-def on_iteration(result):
-    """Callback showing progress after each iteration."""
-    status = "✅" if result.score >= 8.0 else "⚠️" if result.score >= 6.0 else "❌"
-    print(f"{status} Iteration {result.iteration}: {result.score:.1f}/10")
-    if result.findings:
-        print(f"   → {result.findings[0][:60]}...")
-
-
-def main():
-    # Create an agent
-    agent = Agent(
-        name="writer",
-        instructions="You are a technical content writer. Write clear, accurate explanations."
-    )
-
-    # Run evaluation loop
-    loop = EvaluationLoop(
-        agent=agent,
-        criteria="""
-        Evaluate the response on:
-        1. CLARITY: Is the explanation easy to understand?
-        2. ACCURACY: Is the technical content correct?
-        3. COMPLETENESS: Does it cover the key aspects?
-        4. EXAMPLES: Does it include practical examples?
-        
-        Score 1-10 based on all criteria.
-        """,
-        threshold=8.0,
-        max_iterations=5,
-        on_iteration=on_iteration,
-        verbose=False,
-    )
-
-    print("╔════════════════════════════════════════════════════════════╗")
-    print("║            Basic EvaluationLoop Example                     ║")
-    print("║  Pattern: Run → Judge → Improve → Repeat                   ║")
-    print("║  Target: 8.0/10 score                                       ║")
-    print("╚════════════════════════════════════════════════════════════╝\n")
-
-    result = loop.run("Explain how API rate limiting works and why it matters")
-
-    print("\n" + "─" * 60)
-    print("RESULTS:")
-    print("─" * 60)
-    print(f"Success: {result.success}")
-    print(f"Final Score: {result.final_score:.1f}/10")
-    print(f"Iterations: {result.num_iterations}")
-    print(f"Score History: {[f'{s:.1f}' for s in result.score_history]}")
-    print(f"Duration: {result.total_duration_seconds:.2f}s")
-
-    print("\n" + "─" * 60)
-    print("FINAL OUTPUT (first 500 chars):")
-    print("─" * 60)
-    print(result.final_output[:500] + "..." if len(result.final_output) > 500 else result.final_output)
-
-
-if __name__ == "__main__":
-    main()

examples/python/eval/multi_step_task_loop.py

@@ -1,144 +0,0 @@
-"""
-Multi-Step Task Loop Example
-
-Demonstrates evaluating sequential task steps where each step can
-reference output from previous steps.
-
-Pattern:
-1. Research → Evaluate → Improve
-2. Analyze (using research) → Evaluate → Improve  
-3. Report (using analysis) → Evaluate → Improve
-
-Usage:
-    pip install praisonaiagents
-    export OPENAI_API_KEY=your-key
-    python multi_step_task_loop.py
-"""
-from praisonaiagents import Agent
-from praisonaiagents.eval import EvaluationLoop
-
-
-def on_iteration(result):
-    """Show iteration progress."""
-    status = "✅" if result.score >= 8.0 else "⚠️" if result.score >= 6.0 else "❌"
-    print(f"  {status} Iteration {result.iteration}: {result.score:.1f}/10")
-
-
-def run_step(step_name: str, agent: Agent, task: str, criteria: str, context: str = "") -> dict:
-    """Run a single step through an evaluation loop."""
-    print(f"\n{'─'*60}")
-    print(f"STEP: {step_name}")
-    print(f"{'─'*60}")
-    
-    # Include context from previous step if provided
-    full_task = task
-    if context:
-        full_task = f"{task}\n\nContext from previous step:\n{context[:1000]}"
-    
-    loop = EvaluationLoop(
-        agent=agent,
-        criteria=criteria,
-        threshold=8.0,
-        max_iterations=3,
-        on_iteration=on_iteration,
-        verbose=False,
-    )
-    
-    result = loop.run(full_task)
-    
-    print(f"  → Final: {result.final_score:.1f}/10 ({result.num_iterations} iterations)")
-    
-    return {
-        "name": step_name,
-        "output": result.final_output,
-        "score": result.final_score,
-        "success": result.success,
-        "iterations": result.num_iterations,
-    }
-
-
-def main():
-    print("╔════════════════════════════════════════════════════════════╗")
-    print("║         Multi-Step Task Loop Example                       ║")
-    print("║  Pattern: Step1 → Step2 → Step3 (with context passing)    ║")
-    print("║  Each step: Run → Judge → Improve until 8.0+              ║")
-    print("╚════════════════════════════════════════════════════════════╝")
-
-    # Create specialized agents
-    researcher = Agent(
-        name="researcher",
-        instructions="You are a research specialist. Find and summarize key information."
-    )
-    
-    analyst = Agent(
-        name="analyst", 
-        instructions="You are an analyst. Identify patterns, insights, and implications."
-    )
-    
-    writer = Agent(
-        name="writer",
-        instructions="You are a report writer. Create clear, actionable summaries."
-    )
-
-    # Define task steps
-    steps = [
-        {
-            "name": "Research",
-            "agent": researcher,
-            "task": "Research the top 3 trends in AI for 2024-2025. Provide brief descriptions.",
-            "criteria": "Covers 3 distinct trends with accurate descriptions.",
-        },
-        {
-            "name": "Analysis",
-            "agent": analyst,
-            "task": "Analyze the implications of these AI trends for software development.",
-            "criteria": "Identifies actionable insights and potential challenges.",
-        },
-        {
-            "name": "Report",
-            "agent": writer,
-            "task": "Create a brief executive summary (3-4 bullet points) for a CTO.",
-            "criteria": "Concise, actionable, appropriate for executive audience.",
-        },
-    ]
-
-    # Run all steps with context passing
-    results = []
-    context = ""
-    
-    for step in steps:
-        result = run_step(
-            step_name=step["name"],
-            agent=step["agent"],
-            task=step["task"],
-            criteria=step["criteria"],
-            context=context,
-        )
-        results.append(result)
-        context = result["output"]  # Pass output as context to next step
-
-    # Summary
-    print("\n" + "═"*60)
-    print("SUMMARY")
-    print("═"*60)
-    
-    total_iterations = sum(r["iterations"] for r in results)
-    avg_score = sum(r["score"] for r in results) / len(results)
-    all_success = all(r["success"] for r in results)
-    
-    for r in results:
-        status = "✅" if r["success"] else "❌"
-        print(f"  {status} {r['name']}: {r['score']:.1f}/10 ({r['iterations']} iterations)")
-    
-    print(f"\n  Total Iterations: {total_iterations}")
-    print(f"  Average Score: {avg_score:.1f}/10")
-    print(f"  All Steps Passed: {'Yes' if all_success else 'No'}")
-
-    print("\n" + "─"*60)
-    print("FINAL REPORT OUTPUT:")
-    print("─"*60)
-    print(results[-1]["output"][:600])
-
-
-if __name__ == "__main__":
-    main()

examples/python/eval/recipe_optimization_loop.py

@@ -1,183 +0,0 @@
-"""
-Recipe Optimization Loop (CLI-based)
-
-Demonstrates the 5-cycle recipe improvement pattern using CLI commands:
-    Create (once) → Run → Judge → Optimize (loop 5x)
-
-Usage:
-    pip install praisonai
-    export OPENAI_API_KEY=your-key
-    export TAVILY_API_KEY=your-key
-    python recipe_optimization_loop.py "research AI trends in healthcare"
-"""
-import subprocess
-import sys
-import os
-import json
-from pathlib import Path
-
-
-def run_cli(cmd: str, cwd: str = None) -> tuple[int, str, str]:
-    """Run a CLI command and return (exit_code, stdout, stderr)."""
-    result = subprocess.run(
-        cmd,
-        shell=True,
-        capture_output=True,
-        text=True,
-        cwd=cwd,
-    )
-    return result.returncode, result.stdout, result.stderr
-
-
-def create_recipe(goal: str, work_dir: str) -> str:
-    """Create a recipe once. Returns recipe name."""
-    print(f"\n{'═'*60}")
-    print("STEP 1: CREATE RECIPE (once)")
-    print(f"{'═'*60}")
-    print(f"Goal: {goal}")
-    
-    cmd = f'praisonai recipe create "{goal}" --no-optimize'
-    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
-    
-    if code != 0:
-        print(f"❌ Failed to create recipe: {stderr}")
-        return None
-    
-    # Extract recipe name from output
-    for line in stdout.split('\n'):
-        if 'Created recipe:' in line:
-            recipe_name = line.split('Created recipe:')[1].strip()
-            print(f"✅ Created: {recipe_name}")
-            return recipe_name
-    
-    print(f"✅ Recipe created")
-    return None
-
-
-def run_recipe(recipe_name: str, trace_name: str, work_dir: str) -> tuple[bool, str]:
-    """Run the recipe and save trace. Returns (success, output)."""
-    cmd = f'praisonai recipe run {recipe_name} --save --name {trace_name}'
-    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
-    
-    success = code == 0 and 'status: completed' in stdout.lower()
-    return success, stdout
-
-
-def judge_recipe(trace_name: str, work_dir: str) -> tuple[float, str]:
-    """Judge the trace. Returns (score, feedback)."""
-    cmd = f'praisonai recipe judge {trace_name}'
-    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
-    
-    # Extract score from output
-    score = 0.0
-    for line in stdout.split('\n'):
-        if 'Overall Score:' in line:
-            try:
-                score = float(line.split(':')[1].strip().split('/')[0])
-            except:
-                pass
-    
-    return score, stdout
-
-
-def optimize_recipe(recipe_name: str, iterations: int, work_dir: str) -> tuple[float, str]:
-    """Optimize the recipe. Returns (final_score, output)."""
-    cmd = f'praisonai recipe optimize {recipe_name} --iterations {iterations}'
-    code, stdout, stderr = run_cli(cmd, cwd=work_dir)
-    
-    # Extract final score
-    score = 0.0
-    for line in stdout.split('\n'):
-        if 'Final score:' in line or 'score:' in line.lower():
-            try:
-                score = float(line.split(':')[1].strip().split('/')[0])
-            except:
-                pass
-    
-    return score, stdout
-
-
-def run_optimization_loop(goal: str, num_cycles: int = 5, threshold: float = 8.0):
-    """Run the full Create → Run → Judge → Optimize loop."""
-    
-    print("╔════════════════════════════════════════════════════════════╗")
-    print("║       Recipe Optimization Loop (CLI-based)                 ║")
-    print("║  Pattern: Create (once) → Run → Judge → Optimize (loop)   ║")
-    print(f"║  Cycles: {num_cycles} | Threshold: {threshold}/10                         ║")
-    print("╚════════════════════════════════════════════════════════════╝")
-    
-    # Create work directory
-    work_dir = Path("/tmp/recipe-optimization-loop")
-    work_dir.mkdir(parents=True, exist_ok=True)
-    os.chdir(work_dir)
-    
-    # Step 1: Create recipe (once)
-    recipe_name = create_recipe(goal, str(work_dir))
-    if not recipe_name:
-        print("Failed to create recipe. Exiting.")
-        return
-    
-    # Step 2-N: Run → Judge → Optimize loop
-    results = []
-    
-    for cycle in range(1, num_cycles + 1):
-        print(f"\n{'─'*60}")
-        print(f"CYCLE {cycle}/{num_cycles}")
-        print(f"{'─'*60}")
-        
-        trace_name = f"cycle-{cycle}"
-        
-        # Run
-        print(f"  📝 Running recipe...")
-        success, run_output = run_recipe(recipe_name, trace_name, str(work_dir))
-        run_status = "✅" if success else "⚠️"
-        print(f"  {run_status} Run complete")
-        
-        # Judge
-        print(f"  ⚖️ Judging output...")
-        score, judge_output = judge_recipe(trace_name, str(work_dir))
-        score_status = "✅" if score >= threshold else "⚠️" if score >= 6.0 else "❌"
-        print(f"  {score_status} Score: {score}/10")
-        
-        # Check if threshold met
-        if score >= threshold:
-            print(f"  🎉 Threshold {threshold}/10 reached!")
-            results.append({"cycle": cycle, "score": score, "status": "passed"})
-            break
-        
-        # Optimize
-        print(f"  🔧 Optimizing recipe...")
-        opt_score, opt_output = optimize_recipe(recipe_name, 1, str(work_dir))
-        print(f"  → Optimized score: {opt_score}/10")
-        
-        results.append({
-            "cycle": cycle,
-            "initial_score": score,
-            "optimized_score": opt_score,
-            "status": "optimized" if opt_score > score else "no_change"
-        })
-    
-    # Summary
-    print(f"\n{'═'*60}")
-    print("SUMMARY")
-    print(f"{'═'*60}")
-    
-    for r in results:
-        if "initial_score" in r:
-            print(f"  Cycle {r['cycle']}: {r['initial_score']} → {r['optimized_score']}/10")
-        else:
-            print(f"  Cycle {r['cycle']}: {r['score']}/10 ✅ PASSED")
-    
-    final_score = results[-1].get("optimized_score", results[-1].get("score", 0))
-    success = final_score >= threshold
-    
-    print(f"\n  Final Score: {final_score}/10")
-    print(f"  Success: {'Yes ✅' if success else 'No ❌'}")
-    print(f"  Recipe: {work_dir}/{recipe_name}")
-    
-    return results
-
-
-if __name__ == "__main__":
-    goal = sys.argv[1] if len(sys.argv) > 1 else "research latest AI trends and create a summary report"
-    run_optimization_loop(goal, num_cycles=5, threshold=8.0)

examples/python/extensibility/merge_strategies_example.py

@@ -1,214 +0,0 @@
-"""Example: Merge Strategies for Multi-Agent Workflows
-
-This example demonstrates how to use and create custom merge strategies
-for combining outputs from parallel agent executions.
-"""
-from praisonaiagents.agents import (
-    MergeStrategyProtocol,
-    FirstWinsMerge,
-    ConcatMerge,
-    DictMerge,
-)
-
-
-def example_first_wins_merge():
-    """Demonstrate FirstWinsMerge strategy."""
-    print("=" * 50)
-    print("FirstWinsMerge Examples")
-    print("=" * 50)
-    
-    merge = FirstWinsMerge()
-    
-    # 1. Basic usage - returns first non-None
-    print("\n1. Basic Usage:")
-    outputs = [None, "Agent 2 response", "Agent 3 response"]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 2. All None returns None
-    print("\n2. All None:")
-    outputs = [None, None, None]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 3. First value wins
-    print("\n3. First Value Wins:")
-    outputs = ["Fast agent", "Slow agent", "Slowest agent"]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 4. Works with any type
-    print("\n4. Various Types:")
-    print(f"   Dict: {merge.merge([None, {'key': 'value'}])}")
-    print(f"   List: {merge.merge([None, [1, 2, 3]])}")
-    print(f"   Number: {merge.merge([None, 42])}")
-
-
-def example_concat_merge():
-    """Demonstrate ConcatMerge strategy."""
-    print("\n" + "=" * 50)
-    print("ConcatMerge Examples")
-    print("=" * 50)
-    
-    # 1. Default separator (double newline)
-    print("\n1. Default Separator:")
-    merge = ConcatMerge()
-    outputs = ["Part 1: Introduction", "Part 2: Analysis", "Part 3: Conclusion"]
-    result = merge.merge(outputs)
-    print(f"   Result:\n{result}")
-    
-    # 2. Custom separator
-    print("\n2. Custom Separator:")
-    merge = ConcatMerge(separator=" | ")
-    outputs = ["Alice", "Bob", "Charlie"]
-    result = merge.merge(outputs)
-    print(f"   Result: {result}")
-    
-    # 3. Skips None values
-    print("\n3. Skips None:")
-    merge = ConcatMerge(separator=", ")
-    outputs = ["A", None, "C", None, "E"]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 4. Converts non-strings
-    print("\n4. Converts Non-Strings:")
-    merge = ConcatMerge(separator=" + ")
-    outputs = [1, 2, 3]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-
-
-def example_dict_merge():
-    """Demonstrate DictMerge strategy."""
-    print("\n" + "=" * 50)
-    print("DictMerge Examples")
-    print("=" * 50)
-    
-    # 1. Basic shallow merge
-    print("\n1. Shallow Merge (default):")
-    merge = DictMerge()
-    outputs = [
-        {"name": "Alice", "score": 10},
-        {"name": "Bob", "level": 5},
-        {"score": 20, "rank": 1}
-    ]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 2. Later values override
-    print("\n2. Override Behavior:")
-    merge = DictMerge()
-    outputs = [
-        {"status": "pending"},
-        {"status": "processing"},
-        {"status": "complete"}
-    ]
-    result = merge.merge(outputs)
-    print(f"   Result: {result}")
-    
-    # 3. Deep merge for nested dicts
-    print("\n3. Deep Merge:")
-    merge = DictMerge(deep=True)
-    outputs = [
-        {"config": {"a": 1, "b": 2}},
-        {"config": {"b": 3, "c": 4}},
-        {"config": {"d": 5}}
-    ]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 4. Skips non-dict values
-    print("\n4. Skips Non-Dict Values:")
-    merge = DictMerge()
-    outputs = [{"a": 1}, "not a dict", None, {"b": 2}]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-
-
-def example_custom_merge():
-    """Demonstrate creating custom merge strategies."""
-    print("\n" + "=" * 50)
-    print("Custom Merge Strategy Examples")
-    print("=" * 50)
-    
-    # 1. Longest output merge
-    class LongestOutputMerge:
-        """Returns the longest output."""
-        def merge(self, outputs, context=None):
-            valid = [o for o in outputs if o is not None]
-            if not valid:
-                return None
-            return max(valid, key=lambda x: len(str(x)))
-    
-    print("\n1. LongestOutputMerge:")
-    merge = LongestOutputMerge()
-    outputs = ["short", "medium length", "this is the longest response"]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result}")
-    
-    # 2. Majority vote merge
-    class MajorityVoteMerge:
-        """Returns the most common output."""
-        def merge(self, outputs, context=None):
-            from collections import Counter
-            valid = [o for o in outputs if o is not None]
-            if not valid:
-                return None
-            counts = Counter(valid)
-            return counts.most_common(1)[0][0]
-    
-    print("\n2. MajorityVoteMerge:")
-    merge = MajorityVoteMerge()
-    outputs = ["yes", "yes", "no", "yes", "no"]
-    result = merge.merge(outputs)
-    print(f"   Inputs: {outputs}")
-    print(f"   Result: {result} (3 votes)")
-    
-    # 3. Weighted merge
-    class WeightedMerge:
-        """Merges with agent weights from context."""
-        def merge(self, outputs, context=None):
-            weights = context.get("weights", [1] * len(outputs)) if context else [1] * len(outputs)
-            best_idx = 0
-            best_weight = 0
-            for i, (output, weight) in enumerate(zip(outputs, weights)):
-                if output is not None and weight > best_weight:
-                    best_idx = i
-                    best_weight = weight
-            return outputs[best_idx] if outputs else None
-    
-    print("\n3. WeightedMerge:")
-    merge = WeightedMerge()
-    outputs = ["junior answer", "senior answer", "expert answer"]
-    context = {"weights": [1, 5, 10]}
-    result = merge.merge(outputs, context=context)
-    print(f"   Inputs: {outputs}")
-    print(f"   Weights: {context['weights']}")
-    print(f"   Result: {result}")
-    
-    # 4. Protocol compliance
-    print("\n4. Protocol Compliance:")
-    print(f"   LongestOutputMerge: {isinstance(LongestOutputMerge(), MergeStrategyProtocol)}")
-    print(f"   MajorityVoteMerge: {isinstance(MajorityVoteMerge(), MergeStrategyProtocol)}")
-    print(f"   WeightedMerge: {isinstance(WeightedMerge(), MergeStrategyProtocol)}")
-
-
-if __name__ == "__main__":
-    example_first_wins_merge()
-    example_concat_merge()
-    example_dict_merge()
-    example_custom_merge()
-    
-    print("\n" + "=" * 50)
-    print("All examples completed!")
-    print("=" * 50)

examples/python/extensibility/retry_example.py

@@ -1,174 +0,0 @@
-"""Example: Retry Policies and Fallback Chains
-
-This example demonstrates how to configure retry behavior with
-exponential backoff, jitter, and fallback chains.
-"""
-from praisonaiagents.tools import (
-    RetryPolicy,
-    FallbackChain,
-    ToolExecutionConfig,
-)
-
-
-def example_retry_policy():
-    """Demonstrate RetryPolicy configuration and usage."""
-    print("=" * 50)
-    print("RetryPolicy Examples")
-    print("=" * 50)
-    
-    # 1. Default policy
-    print("\n1. Default RetryPolicy:")
-    policy = RetryPolicy()
-    print(f"   max_attempts: {policy.max_attempts}")
-    print(f"   backoff_factor: {policy.backoff_factor}")
-    print(f"   initial_delay_ms: {policy.initial_delay_ms}")
-    print(f"   max_delay_ms: {policy.max_delay_ms}")
-    print(f"   retry_on: {policy.retry_on}")
-    
-    # 2. Exponential backoff calculation
-    print("\n2. Exponential Backoff (no jitter):")
-    policy = RetryPolicy(
-        initial_delay_ms=1000,
-        backoff_factor=2.0,
-        max_delay_ms=30000,
-        jitter=False
-    )
-    for attempt in range(5):
-        delay = policy.get_delay_ms(attempt)
-        print(f"   Attempt {attempt}: delay = {delay}ms")
-    
-    # 3. With jitter for production
-    print("\n3. With Jitter (production-ready):")
-    policy = RetryPolicy(
-        initial_delay_ms=1000,
-        backoff_factor=2.0,
-        jitter=True,
-        jitter_factor=0.25  # ±25%
-    )
-    print("   Delays for attempt 0 (10 samples):")
-    delays = [policy.get_delay_ms(0) for _ in range(10)]
-    print(f"   {delays}")
-    print(f"   Range: {min(delays)} - {max(delays)} (expected: 750-1250)")
-    
-    # 4. should_retry logic
-    print("\n4. should_retry Logic:")
-    policy = RetryPolicy(max_attempts=3, retry_on={"timeout", "rate_limit"})
-    
-    test_cases = [
-        ("timeout", 0),
-        ("timeout", 2),
-        ("timeout", 3),  # At max_attempts
-        ("unknown_error", 0),  # Not in retry_on
-    ]
-    for error_type, attempt in test_cases:
-        result = policy.should_retry(error_type, attempt)
-        print(f"   should_retry('{error_type}', {attempt}) = {result}")
-    
-    # 5. Custom error types
-    print("\n5. Custom Error Types:")
-    policy = RetryPolicy(retry_on={"api_error", "network_error", "throttled"})
-    print(f"   Retries on: {policy.retry_on}")
-    print(f"   should_retry('api_error', 0) = {policy.should_retry('api_error', 0)}")
-    print(f"   should_retry('timeout', 0) = {policy.should_retry('timeout', 0)}")
-
-
-def example_fallback_chain():
-    """Demonstrate FallbackChain configuration."""
-    print("\n" + "=" * 50)
-    print("FallbackChain Examples")
-    print("=" * 50)
-    
-    # 1. Basic chain
-    print("\n1. Basic FallbackChain:")
-    chain = FallbackChain(
-        tools=["web_search", "cached_search", "default_response"]
-    )
-    print(f"   Tools: {chain.tools}")
-    print(f"   Length: {len(chain)}")
-    print(f"   stop_on_success: {chain.stop_on_success}")
-    
-    # 2. Iteration
-    print("\n2. Iterating over chain:")
-    for i, tool in enumerate(chain):
-        print(f"   {i+1}. {tool}")
-    
-    # 3. Try all (don't stop on success)
-    print("\n3. Try All Mode:")
-    chain = FallbackChain(
-        tools=["validator_1", "validator_2", "validator_3"],
-        stop_on_success=False
-    )
-    print(f"   stop_on_success: {chain.stop_on_success}")
-    print("   (All tools will be tried regardless of success)")
-
-
-def example_tool_execution_config():
-    """Demonstrate ToolExecutionConfig combining retry and fallback."""
-    print("\n" + "=" * 50)
-    print("ToolExecutionConfig Examples")
-    print("=" * 50)
-    
-    # 1. Default config
-    print("\n1. Default Config:")
-    config = ToolExecutionConfig()
-    print(f"   retry_policy: {config.retry_policy}")
-    print(f"   fallback_chain: {config.fallback_chain}")
-    print(f"   timeout_ms: {config.timeout_ms}")
-    
-    # 2. Using default() factory
-    print("\n2. Default Factory:")
-    config = ToolExecutionConfig.default()
-    print(f"   retry_policy.max_attempts: {config.retry_policy.max_attempts}")
-    
-    # 3. Full configuration
-    print("\n3. Full Configuration:")
-    config = ToolExecutionConfig(
-        retry_policy=RetryPolicy(
-            max_attempts=5,
-            backoff_factor=1.5,
-            initial_delay_ms=500,
-            jitter=True
-        ),
-        fallback_chain=FallbackChain(
-            tools=["primary_api", "backup_api", "cache"]
-        ),
-        timeout_ms=10000
-    )
-    print(f"   retry_policy.max_attempts: {config.retry_policy.max_attempts}")
-    print(f"   retry_policy.jitter: {config.retry_policy.jitter}")
-    print(f"   fallback_chain tools: {config.fallback_chain.tools}")
-    print(f"   timeout_ms: {config.timeout_ms}")
-
-
-def example_validation():
-    """Demonstrate validation of RetryPolicy parameters."""
-    print("\n" + "=" * 50)
-    print("Validation Examples")
-    print("=" * 50)
-    
-    invalid_configs = [
-        ("max_attempts=0", {"max_attempts": 0}),
-        ("backoff_factor=0.5", {"backoff_factor": 0.5}),
-        ("initial_delay_ms=-1", {"initial_delay_ms": -1}),
-        ("max_delay < initial", {"initial_delay_ms": 1000, "max_delay_ms": 500}),
-        ("jitter_factor=1.5", {"jitter_factor": 1.5}),
-    ]
-    
-    for name, kwargs in invalid_configs:
-        try:
-            RetryPolicy(**kwargs)
-            print(f"\n   {name}: No error (unexpected!)")
-        except ValueError as e:
-            print(f"\n   {name}:")
-            print(f"   → ValueError: {e}")
-
-
-if __name__ == "__main__":
-    example_retry_policy()
-    example_fallback_chain()
-    example_tool_execution_config()
-    example_validation()
-    
-    print("\n" + "=" * 50)
-    print("All examples completed!")
-    print("=" * 50)

examples/python/extensibility/validators_example.py

@@ -1,163 +0,0 @@
-"""Example: Tool Validation with Custom Validators
-
-This example demonstrates how to use ValidationResult and implement
-custom validators using the ToolValidatorProtocol.
-"""
-from praisonaiagents.tools import (
-    ValidationResult,
-    ToolValidatorProtocol,
-    PassthroughValidator,
-)
-
-
-def example_validation_result():
-    """Demonstrate ValidationResult usage."""
-    print("=" * 50)
-    print("ValidationResult Examples")
-    print("=" * 50)
-    
-    # 1. Success factory
-    success = ValidationResult.success()
-    print(f"\n1. Success: valid={success.valid}, bool={bool(success)}")
-    
-    # 2. Failure factory
-    failure = ValidationResult.failure(
-        errors=["Query cannot be empty", "Missing required field"],
-        remediation="Provide a non-empty query string"
-    )
-    print(f"\n2. Failure: valid={failure.valid}")
-    print(f"   Errors: {failure.errors}")
-    print(f"   Remediation: {failure.remediation}")
-    
-    # 3. Fluent API - building incrementally
-    result = ValidationResult(valid=True)
-    result.add_warning("Query is very long, may be slow")
-    result.add_warning("Consider using pagination")
-    print(f"\n3. With warnings: valid={result.valid}, warnings={result.warnings}")
-    
-    # 4. Adding errors changes validity
-    result.add_error("Rate limit exceeded")
-    print(f"\n4. After error: valid={result.valid}, errors={result.errors}")
-
-
-class InputLengthValidator:
-    """Custom validator that checks string input lengths."""
-    
-    def __init__(self, max_length: int = 100):
-        self.max_length = max_length
-    
-    def validate_args(self, tool_name, args, context=None):
-        """Validate that string arguments don't exceed max length."""
-        for key, value in args.items():
-            if isinstance(value, str) and len(value) > self.max_length:
-                return ValidationResult.failure(
-                    errors=[f"Argument '{key}' ({len(value)} chars) exceeds limit ({self.max_length})"],
-                    remediation=f"Truncate '{key}' to {self.max_length} characters or less"
-                )
-        return ValidationResult.success()
-    
-    def validate_result(self, tool_name, result, context=None):
-        """Validate tool results."""
-        return ValidationResult.success()
-
-
-class TypeValidator:
-    """Custom validator that checks argument types."""
-    
-    def __init__(self, type_specs: dict):
-        """
-        Args:
-            type_specs: Dict mapping arg names to expected types
-                       e.g., {"query": str, "limit": int}
-        """
-        self.type_specs = type_specs
-    
-    def validate_args(self, tool_name, args, context=None):
-        result = ValidationResult(valid=True)
-        
-        for arg_name, expected_type in self.type_specs.items():
-            if arg_name in args:
-                actual_value = args[arg_name]
-                if not isinstance(actual_value, expected_type):
-                    result.add_error(
-                        f"Argument '{arg_name}' must be {expected_type.__name__}, "
-                        f"got {type(actual_value).__name__}"
-                    )
-        
-        if not result.valid:
-            result.remediation = "Check argument types and try again"
-        
-        return result
-    
-    def validate_result(self, tool_name, result, context=None):
-        return ValidationResult.success()
-
-
-def example_custom_validators():
-    """Demonstrate custom validator implementations."""
-    print("\n" + "=" * 50)
-    print("Custom Validator Examples")
-    print("=" * 50)
-    
-    # 1. InputLengthValidator
-    print("\n1. InputLengthValidator:")
-    validator = InputLengthValidator(max_length=50)
-    
-    # Valid input
-    result = validator.validate_args("search", {"query": "short query"})
-    print(f"   Short query: valid={result.valid}")
-    
-    # Invalid input
-    long_query = "x" * 100
-    result = validator.validate_args("search", {"query": long_query})
-    print(f"   Long query: valid={result.valid}")
-    print(f"   Error: {result.errors[0]}")
-    print(f"   Fix: {result.remediation}")
-    
-    # 2. TypeValidator
-    print("\n2. TypeValidator:")
-    validator = TypeValidator({"query": str, "limit": int, "offset": int})
-    
-    # Valid types
-    result = validator.validate_args("search", {"query": "test", "limit": 10})
-    print(f"   Correct types: valid={result.valid}")
-    
-    # Invalid types
-    result = validator.validate_args("search", {"query": 123, "limit": "ten"})
-    print(f"   Wrong types: valid={result.valid}")
-    for error in result.errors:
-        print(f"   - {error}")
-    
-    # 3. Protocol compliance check
-    print("\n3. Protocol Compliance:")
-    print(f"   InputLengthValidator: {isinstance(InputLengthValidator(), ToolValidatorProtocol)}")
-    print(f"   TypeValidator: {isinstance(TypeValidator({}), ToolValidatorProtocol)}")
-    print(f"   PassthroughValidator: {isinstance(PassthroughValidator(), ToolValidatorProtocol)}")
-
-
-def example_passthrough_validator():
-    """Demonstrate the default PassthroughValidator."""
-    print("\n" + "=" * 50)
-    print("PassthroughValidator Example")
-    print("=" * 50)
-    
-    validator = PassthroughValidator()
-    
-    # Always returns valid
-    result = validator.validate_args("any_tool", {"any": "args"})
-    print(f"\nvalidate_args: valid={result.valid}")
-    
-    result = validator.validate_result("any_tool", {"any": "result"})
-    print(f"validate_result: valid={result.valid}")
-    
-    print("\nPassthroughValidator is useful as a default when no validation is needed.")
-
-
-if __name__ == "__main__":
-    example_validation_result()
-    example_custom_validators()
-    example_passthrough_validator()
-    
-    print("\n" + "=" * 50)
-    print("All examples completed!")
-    print("=" * 50)

examples/python/failover_example.py

@@ -1,170 +0,0 @@
-"""
-Model Failover Example - Automatic Provider Switching
-
-This example demonstrates how to configure model failover
-for reliability and cost optimization.
-"""
-
-import os
-from praisonaiagents import (
-    AuthProfile,
-    FailoverConfig,
-    FailoverManager,
-)
-
-# Create auth profiles for different providers
-openai_profile = AuthProfile(
-    name="openai-primary",
-    provider="openai",
-    api_key=os.environ.get("OPENAI_API_KEY", "sk-..."),
-    priority=1,  # Highest priority
-    rate_limit=100,
-)
-
-anthropic_profile = AuthProfile(
-    name="anthropic-backup",
-    provider="anthropic",
-    api_key=os.environ.get("ANTHROPIC_API_KEY", "sk-ant-..."),
-    priority=2,  # Second priority
-    rate_limit=50,
-)
-
-groq_profile = AuthProfile(
-    name="groq-fallback",
-    provider="groq",
-    api_key=os.environ.get("GROQ_API_KEY", "gsk-..."),
-    priority=3,  # Third priority (fast but limited)
-    rate_limit=30,
-)
-
-# Configure failover behavior
-failover_config = FailoverConfig(
-    max_retries=3,
-    retry_delay=1.0,
-    exponential_backoff=True,
-    max_retry_delay=60.0,
-    failover_on_rate_limit=True,
-    failover_on_timeout=True,
-    failover_on_error=True,
-)
-
-# Create failover manager
-manager = FailoverManager(failover_config)
-manager.add_profile(openai_profile)
-manager.add_profile(anthropic_profile)
-manager.add_profile(groq_profile)
-
-def demonstrate_failover():
-    """Demonstrate failover functionality."""
-    
-    print("Failover Manager Status:")
-    print()
-    
-    # Get current status
-    status = manager.status()
-    for name, info in status.items():
-        print(f"  {name}:")
-        print(f"    Status: {info.get('status', 'unknown')}")
-        print(f"    Priority: {info.get('priority', 'N/A')}")
-        print(f"    Failures: {info.get('failure_count', 0)}")
-    print()
-    
-    # Get next available profile
-    next_profile = manager.get_next_profile()
-    if next_profile:
-        print(f"Next profile to use: {next_profile.name}")
-        print(f"  Provider: {next_profile.provider}")
-        print(f"  Priority: {next_profile.priority}")
-    print()
-    
-    # Simulate marking a failure
-    print("Simulating failure on primary provider...")
-    manager.mark_failure("openai-primary", "Rate limit exceeded")
-    
-    # Get next profile after failure
-    next_profile = manager.get_next_profile()
-    if next_profile:
-        print(f"After failure, next profile: {next_profile.name}")
-    print()
-    
-    # Get retry delay
-    delay = manager.get_retry_delay("openai-primary")
-    print(f"Retry delay for openai-primary: {delay}s")
-    print()
-    
-    # Reset all providers
-    print("Resetting all providers...")
-    manager.reset_all()
-    
-    next_profile = manager.get_next_profile()
-    if next_profile:
-        print(f"After reset, next profile: {next_profile.name}")
-
-def cost_optimization_example():
-    """Example of cost-optimized failover."""
-    
-    print("\nCost Optimization Example:")
-    print("-" * 40)
-    
-    # Create cost-optimized manager
-    cost_manager = FailoverManager()
-    
-    # Cheaper model first
-    cost_manager.add_profile(AuthProfile(
-        name="gpt-4o-mini",
-        provider="openai",
-        api_key=os.environ.get("OPENAI_API_KEY", ""),
-        priority=1,
-        metadata={"model": "gpt-4o-mini", "cost_per_1k": 0.00015}
-    ))
-    
-    # Premium model as fallback
-    cost_manager.add_profile(AuthProfile(
-        name="gpt-4o",
-        provider="openai",
-        api_key=os.environ.get("OPENAI_API_KEY", ""),
-        priority=2,
-        metadata={"model": "gpt-4o", "cost_per_1k": 0.005}
-    ))
-    
-    # Most expensive as last resort
-    cost_manager.add_profile(AuthProfile(
-        name="claude-opus",
-        provider="anthropic",
-        api_key=os.environ.get("ANTHROPIC_API_KEY", ""),
-        priority=3,
-        metadata={"model": "claude-3-opus", "cost_per_1k": 0.015}
-    ))
-    
-    print("Cost-optimized failover chain:")
-    for profile in [
-        cost_manager.get_profile("gpt-4o-mini"),
-        cost_manager.get_profile("gpt-4o"),
-        cost_manager.get_profile("claude-opus"),
-    ]:
-        if profile:
-            cost = profile.metadata.get("cost_per_1k", "N/A")
-            print(f"  {profile.priority}. {profile.name} (${cost}/1K tokens)")
-
-if __name__ == "__main__":
-    print("Model Failover Configuration")
-    print("=" * 40)
-    print()
-    
-    print("Failover Config:")
-    print(f"  Max retries: {failover_config.max_retries}")
-    print(f"  Initial delay: {failover_config.retry_delay}s")
-    print(f"  Exponential backoff: {failover_config.exponential_backoff}")
-    print(f"  Max delay: {failover_config.max_retry_delay}s")
-    print()
-    
-    print("Auth Profiles:")
-    for profile in [openai_profile, anthropic_profile, groq_profile]:
-        print(f"  {profile.name}:")
-        print(f"    Provider: {profile.provider}")
-        print(f"    Priority: {profile.priority}")
-        print(f"    Rate limit: {profile.rate_limit} req/min")
-    print()
-    
-    demonstrate_failover()
-    cost_optimization_example()

examples/python/gateway_example.py

@@ -1,47 +0,0 @@
-"""
-Gateway Example - Multi-Agent Coordination
-
-This example demonstrates how to use the Gateway for coordinating
-multiple agents and managing real-time communication.
-"""
-
-from praisonaiagents import Agent, GatewayConfig, SessionConfig
-
-# Configure the gateway
-gateway_config = GatewayConfig(
-    host="127.0.0.1",
-    port=8765,
-    max_connections=100,
-    heartbeat_interval=30,
-    session_config=SessionConfig(
-        timeout=3600,  # 1 hour session timeout
-        max_messages=500,
-    )
-)
-
-# Create specialized agents
-researcher = Agent(
-    name="researcher",
-    instructions="You research topics thoroughly and provide detailed information.",
-    llm="gpt-4o-mini"
-)
-
-writer = Agent(
-    name="writer",
-    instructions="You write clear, engaging content based on research.",
-    llm="gpt-4o-mini"
-)
-
-# Example: Simple agent interaction
-if __name__ == "__main__":
-    print("Gateway Configuration:")
-    print(f"  Host: {gateway_config.host}")
-    print(f"  Port: {gateway_config.port}")
-    print(f"  WebSocket URL: {gateway_config.ws_url}")
-    print(f"  Max Connections: {gateway_config.max_connections}")
-    print()
-    
-    # Test agent
-    response = researcher.start("What are the key benefits of multi-agent systems?")
-    print("Researcher Response:")
-    print(response)

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

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

examples/python/general/async_example.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 from typing import List, Dict
-from praisonaiagents import Agent, Task, AgentTeam, TaskOutput
+from praisonaiagents import Agent, Task, Agents, TaskOutput
 from praisonaiagents.main import (
     display_error,
     display_interaction,
@@ -156,7 +156,7 @@ workflow_async_task = Task(
 def run_sync_example():
     """Run synchronous example"""
     display_instruction("\nRunning Synchronous Example...", console)
-    agents = AgentTeam(
+    agents = Agents(
         agents=[sync_agent],
         tasks=[sync_task],
         process="sequential"
@@ -167,7 +167,7 @@ def run_sync_example():
 async def run_async_example():
     """Run asynchronous example"""
     display_instruction("\nRunning Asynchronous Example...", console)
-    agents = AgentTeam(
+    agents = Agents(
         agents=[async_agent],
         tasks=[async_task],
         process="sequential"
@@ -178,7 +178,7 @@ async def run_async_example():
 async def run_mixed_example():
     """Run mixed sync/async example"""
     display_instruction("\nRunning Mixed Sync/Async Example...", console)
-    agents = AgentTeam(
+    agents = Agents(
         agents=[sync_agent, async_agent],
         tasks=[sync_task, async_task],
         process="sequential"
@@ -189,7 +189,7 @@ async def run_mixed_example():
 async def run_workflow_example():
     """Run workflow example with both sync and async tasks"""
     display_instruction("\nRunning Workflow Example...", console)
-    agents = AgentTeam(
+    agents = Agents(
         agents=[sync_agent, async_agent],
         tasks=[workflow_sync_task, workflow_async_task],
         process="workflow"

examples/python/general/async_example_full.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 from typing import List, Dict
-from praisonaiagents import Agent, Task, AgentTeam, TaskOutput
+from praisonaiagents import Agent, Task, Agents, TaskOutput
 from duckduckgo_search import DDGS
 from pydantic import BaseModel
 
@@ -111,7 +111,7 @@ async def run_parallel_tasks():
     )
     
     # Create a single Agents instance with both agents
-    agents = AgentTeam(
+    agents = Agents(
         agents=[async_agent, summary_agent],
         tasks=parallel_tasks + [summary_task],
         process="sequential"

examples/python/general/async_example_full_multigroups.py

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