feat(ag2): add AG2 framework backend integration (#1143)

feat(ag2): add AG2 framework backend integration

.github/actions/claude-code-action/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:20-alpine
+
+RUN npm install -g @anthropic-ai/claude-code
+
+WORKDIR /app
+COPY entrypoint.sh .
+RUN chmod +x entrypoint.sh
+
+ENTRYPOINT ["/app/entrypoint.sh"] 

.github/actions/claude-code-action/action.yml

@@ -0,0 +1,20 @@
+name: "Claude Code Action"
+description: "Custom Claude Code runner for PraisonAI"
+
+inputs:
+  anthropic_api_key:
+    required: true
+    description: "Anthropic API key"
+  github_token:
+    required: true
+    description: "GitHub token for repo access"
+
+runs:
+  using: "docker"
+  image: "ghcr.io/mervinpraison/praisonai-claudecode:latest"
+  env:
+    ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key }}
+    GITHUB_TOKEN: ${{ inputs.github_token }}
+  args:
+    - "--anthropic-api-key=${{ inputs.anthropic_api_key }}"
+    - "--github-token=${{ inputs.github_token }}" 

.github/actions/claude-code-action/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+set -e
+
+echo "Running Claude Code in CI mode..."
+
+# Extract GitHub context and create a smart prompt
+PROMPT="Analyse the GitHub issue or PR context and generate a smart response based on the repository context."
+
+# Set environment variables from arguments
+export ANTHROPIC_API_KEY="${1#--anthropic-api-key=}"
+export GITHUB_TOKEN="${2#--github-token=}"
+
+# Verify environment variables
+if [ -z "$ANTHROPIC_API_KEY" ] || [ -z "$GITHUB_TOKEN" ]; then
+    echo "Error: Required environment variables are not set"
+    exit 1
+fi
+
+# Run Claude with the prompt
+claude -p "$PROMPT" 

.github/actions/claude-code/action.yml

@@ -0,0 +1,117 @@
+name: "Claude Code Action"
+description: "Run Claude Code in GitHub Actions workflows"
+
+inputs:
+  github_token:
+    description: "GitHub token with repo and issues permissions"
+    required: true
+  anthropic_api_key:
+    description: "Anthropic API key"
+    required: true
+  prompt:
+    description: "The prompt to send to Claude Code"
+    required: false
+    default: ""
+  prompt_file:
+    description: "Path to a file containing the prompt to send to Claude Code"
+    required: false
+    default: ""
+  allowed_tools:
+    description: "Comma-separated list of allowed tools for Claude Code to use"
+    required: false
+    default: ""
+  output_file:
+    description: "File to save Claude Code output to (optional)"
+    required: false
+    default: ""
+  timeout_minutes:
+    description: "Timeout in minutes for Claude Code execution"
+    required: false
+    default: "10"
+  install_github_mcp:
+    description: "Whether to install the GitHub MCP server"
+    required: false
+    default: "false"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Claude Code
+      shell: bash
+      run: npm install -g @anthropic-ai/claude-code
+
+    - name: Install GitHub MCP Server
+      if: inputs.install_github_mcp == 'true'
+      shell: bash
+      run: |
+        claude mcp add-json github '{
+          "command": "docker",
+          "args": [
+            "run",
+            "-i",
+            "--rm",
+            "-e",
+            "GITHUB_PERSONAL_ACCESS_TOKEN",
+            "ghcr.io/github/github-mcp-server:sha-ff3036d"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ inputs.GITHUB_TOKEN }}"
+          }
+        }'
+
+    - name: Prepare Prompt File
+      shell: bash
+      id: prepare_prompt
+      run: |
+        if [ -z "${{ inputs.prompt }}" ] && [ -z "${{ inputs.prompt_file }}" ]; then
+          echo "::error::Neither 'prompt' nor 'prompt_file' was provided. At least one is required."
+          exit 1
+        fi
+
+        if [ ! -z "${{ inputs.prompt_file }}" ]; then
+          if [ ! -f "${{ inputs.prompt_file }}" ]; then
+            echo "::error::Prompt file '${{ inputs.prompt_file }}' does not exist."
+            exit 1
+          fi
+          PROMPT_PATH="${{ inputs.prompt_file }}"
+        else
+          mkdir -p /tmp/claude-action
+          PROMPT_PATH="/tmp/claude-action/prompt.txt"
+          echo "${{ inputs.prompt }}" > "$PROMPT_PATH"
+        fi
+
+        if [ ! -s "$PROMPT_PATH" ]; then
+          echo "::error::Prompt is empty. Please provide a non-empty prompt."
+          exit 1
+        fi
+
+        echo "PROMPT_PATH=$PROMPT_PATH" >> $GITHUB_ENV
+
+    - name: Run Claude Code
+      shell: bash
+      id: run_claude
+      run: |
+        timeout_seconds=$((${{ inputs.timeout_minutes }} * 60))
+
+        if [ -z "${{ inputs.output_file }}" ]; then
+          timeout $timeout_seconds claude \
+            -p \
+            --verbose \
+            --output-format stream-json \
+            "$(cat ${{ env.PROMPT_PATH }})" \
+            ${{ inputs.allowed_tools != '' && format('--allowedTools "{0}"', inputs.allowed_tools) || '' }}
+        else
+          timeout $timeout_seconds claude \
+            -p \
+            --verbose \
+            --output-format stream-json \
+            "$(cat ${{ env.PROMPT_PATH }})" \
+            ${{ inputs.allowed_tools != '' && format('--allowedTools "{0}"', inputs.allowed_tools) || '' }} | tee output.txt
+
+          jq -s '.' output.txt > output.json
+          jq -r '.[-1].result' output.json > "${{ inputs.output_file }}"
+          echo "Complete output saved to output.json, final response saved to ${{ inputs.output_file }}"
+        fi
+      env:
+        ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key }}
+        GITHUB_TOKEN: ${{ inputs.github_token }}

.github/workflows/build-image.yml

@@ -0,0 +1,39 @@
+name: Build Claude Code Image
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Image version tag'
+        required: true
+        default: 'latest'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: ./.github/actions/claude-code-action
+          push: true
+          tags: ghcr.io/mervinpraison/praisonai-claudecode:${{ inputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false 

.github/workflows/claude.yml

@@ -23,15 +23,60 @@ jobs:
       pull-requests: read
       issues: read
       id-token: write
+      packages: read
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 1
 
+      - name: Debug Environment
+        run: |
+          echo "=== Environment Debug ==="
+          echo "GITHUB_ACTOR: $GITHUB_ACTOR"
+          echo "GITHUB_REPOSITORY: $GITHUB_REPOSITORY"
+          echo "GITHUB_REPOSITORY_OWNER: $GITHUB_REPOSITORY_OWNER"
+          echo "GITHUB_TOKEN exists: $([ -n "$GITHUB_TOKEN" ] && echo "yes" || echo "no")"
+          echo "GITHUB_TOKEN length: ${#GITHUB_TOKEN}"
+
+      - name: Check Package Visibility
+        run: |
+          echo "=== Checking Package Visibility ==="
+          curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
+               -H "Accept: application/vnd.github.v3+json" \
+               "https://api.github.com/users/MervinPraison/packages/container/praisonai-claudecode" \
+               || echo "Package API call failed"
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test Docker Authentication
+        run: |
+          echo "=== Testing Docker Authentication ==="
+          echo "Checking ~/.docker/config.json"
+          cat ~/.docker/config.json | jq '.' || echo "No docker config found"
+          echo "=== Testing Registry Access ==="
+          curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
+               "https://ghcr.io/v2/" || echo "Registry access failed"
+
+      - name: Test Docker Pull
+        run: |
+          echo "=== Testing Docker Pull ==="
+          echo "Attempting to pull image: ghcr.io/mervinpraison/praisonai-claudecode:latest"
+          docker pull ghcr.io/mervinpraison/praisonai-claudecode:latest || echo "Pull failed with exit code: $?"
+          echo "=== Checking Docker Images ==="
+          docker images | grep praisonai-claudecode || echo "No images found"
+
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: ./.github/actions/claude-code-action
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/coverage.yml

@@ -0,0 +1,60 @@
+name: Run tests and upload coverage
+
+on: 
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    name: Run tests and collect coverage
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install UV
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          cd src/praisonai
+          uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
+          uv pip install --system duckduckgo_search
+          uv pip install --system pytest pytest-cov pytest-asyncio
+          # Install knowledge dependencies from praisonai-agents
+          uv pip install --system "praisonaiagents[knowledge]"
+
+      - name: Set environment variables
+        run: |
+          echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
+          echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
+          echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-4o-mini' }}" >> $GITHUB_ENV
+          echo "LOGLEVEL=DEBUG" >> $GITHUB_ENV
+          echo "PYTHONPATH=${{ github.workspace }}/src/praisonai-agents:$PYTHONPATH" >> $GITHUB_ENV
+
+      - name: Run tests
+        run: |
+          cd src/praisonai
+          pytest --cov=praisonai --cov-branch --cov-report=xml tests/unit/
+
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: src/praisonai/coverage.xml
+          flags: unit-tests
+          name: unit-tests-coverage
+          fail_ci_if_error: false
+          verbose: true 

.github/workflows/python-package.yml

@@ -65,4 +65,4 @@ jobs:
     #     flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Test with pytest
       run: |
-        cd src/praisonai && python -m pytest
+        cd src/praisonai && python tests/test_runner.py --pattern fast

.github/workflows/test-comprehensive.yml

@@ -69,10 +69,10 @@ jobs:
         
         case $TEST_TYPE in
           "unit")
-            cd src/praisonai && python tests/test_runner.py --pattern unit
+            cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
             ;;
           "integration")
-            cd src/praisonai && python tests/test_runner.py --pattern integration
+            cd src/praisonai && python -m pytest tests/integration/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
             ;;
           "fast")
             cd src/praisonai && python tests/test_runner.py --pattern fast
@@ -139,6 +139,16 @@ jobs:
         echo "- 🔌 MCP server connections" >> comprehensive_report.md
         echo "- 💬 LLM integrations (OpenAI, Anthropic, etc.)" >> comprehensive_report.md
 
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: src/praisonai/coverage.xml
+        flags: comprehensive-tests
+        name: comprehensive-tests-coverage
+        fail_ci_if_error: false
+        verbose: true
+
     - name: Upload Comprehensive Test Results
       uses: actions/upload-artifact@v4
       if: always()
@@ -146,9 +156,9 @@ jobs:
         name: comprehensive-test-results-python-${{ matrix.python-version }}
         path: |
           comprehensive_report.md
-          htmlcov/
-          coverage.xml
-          .coverage
+          src/praisonai/htmlcov/
+          src/praisonai/coverage.xml
+          src/praisonai/.coverage
         retention-days: 30
 
   test-matrix-summary:

.github/workflows/test-core.yml

@@ -195,7 +195,7 @@ jobs:
 
     - name: Run Unit Tests
       run: |
-        cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=term-missing
+        cd src/praisonai && python -m pytest tests/unit/ -v --tb=short --disable-warnings --cov=praisonai --cov-report=term-missing --cov-report=xml --cov-branch
 
     - name: Run Integration Tests  
       run: |
@@ -263,12 +263,24 @@ jobs:
         export OPENAI_MODEL_NAME="$OPENAI_MODEL_NAME"
         cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings
 
-    - name: Upload Coverage Reports
+    - name: Upload coverage reports to Codecov
+      if: matrix.python-version == '3.11'
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: src/praisonai/coverage.xml
+        flags: core-tests
+        name: core-tests-coverage
+        fail_ci_if_error: false
+        verbose: true
+
+    - name: Upload Coverage Reports (Artifacts)
       if: matrix.python-version == '3.11'
       uses: actions/upload-artifact@v4
       with:
         name: coverage-reports
         path: |
-          .coverage
-          htmlcov/
+          src/praisonai/.coverage
+          src/praisonai/htmlcov/
+          src/praisonai/coverage.xml
         retention-days: 7

.github/workflows/unittest.yml

@@ -471,8 +471,8 @@ jobs:
 
     - name: Run Fast Tests
       run: |
-        # Run the fastest, most essential tests
-        cd src/praisonai && python tests/test_runner.py --pattern fast
+        # Run the fastest, most essential tests with coverage
+        cd src/praisonai && python -m pytest tests/unit/test_core_agents.py -v --tb=short --disable-warnings --cov=praisonai --cov-report=xml --cov-branch
 
     - name: Run Real API Tests
       run: |
@@ -491,6 +491,16 @@ jobs:
         cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings
       continue-on-error: true
 
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: src/praisonai/coverage.xml
+        flags: quick-validation
+        name: quick-validation-coverage
+        fail_ci_if_error: false
+        verbose: true
+
     - name: Restore Root Config Files
       run: |
         echo "🔄 Restoring root configuration files..."

.gitignore

@@ -74,4 +74,5 @@ agents/praisonaiagents/praisonaiagents.egg-info
 .praison
 # Local Netlify folder
 .netlify
-.qodo
+.qodo
+CopilotKit*

docker/Dockerfile

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.2.26" \
+    "praisonai>=2.2.33" \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

docker/README.md

@@ -121,7 +121,7 @@ healthcheck:
 ## 📦 Package Versions
 
 All Docker images use consistent, up-to-date versions:
-- PraisonAI: `>=2.2.26`
+- PraisonAI: `>=2.2.33`
 - PraisonAI Agents: `>=0.0.92`
 - Python: `3.11-slim`
 
@@ -218,7 +218,7 @@ docker-compose up -d
 ### Version Pinning
 To use specific versions, update the Dockerfile:
 ```dockerfile
-RUN pip install "praisonai==2.2.26" "praisonaiagents==0.0.92"
+RUN pip install "praisonai==2.2.33" "praisonaiagents==0.0.92"
 ```
 
 ## 🌐 Production Deployment

examples/ag2/ag2_basic.yaml

@@ -0,0 +1,30 @@
+framework: ag2
+topic: "Research the latest developments in AI agents"
+
+# Install: pip install "praisonai[ag2]"
+# Run:     praisonai --framework ag2 examples/ag2/ag2_basic.yaml
+#       or praisonai run examples/ag2/ag2_basic.yaml --framework ag2
+
+roles:
+  research_agent:
+    role: "AI Research Specialist"
+    goal: "Research and summarise the latest developments in AI agent frameworks"
+    backstory: |
+      You are an experienced AI researcher with deep knowledge of multi-agent
+      systems, large language models, and the latest trends in AI tooling.
+      You excel at synthesising complex technical topics into clear summaries.
+    tasks:
+      research_task:
+        description: |
+          Research and summarise the latest developments in AI agent frameworks
+          for the topic: {topic}
+
+          Focus on:
+          1. Key frameworks and their unique capabilities
+          2. Recent innovations and improvements
+          3. Community adoption and ecosystem growth
+          4. Practical use cases and success stories
+        expected_output: |
+          A concise research summary covering the key developments,
+          major frameworks, and practical insights. Include 3-5 bullet
+          points of the most important findings.

examples/ag2/ag2_bedrock.yaml

@@ -0,0 +1,42 @@
+framework: ag2
+topic: "Cloud-native AI deployment strategies on AWS"
+
+# AG2 exclusive feature: native AWS Bedrock support via LLMConfig(api_type="bedrock")
+#
+# Prerequisites:
+#   pip install "praisonai[ag2]"
+#   aws configure  (or set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
+#
+# Run:
+#   praisonai --framework ag2 examples/ag2/ag2_bedrock.yaml
+#
+# The AG2 adapter detects api_type="bedrock" from the llm config and uses
+# LLMConfig(api_type="bedrock", model=...) — no OPENAI_API_KEY required.
+# AWS credentials are sourced from boto3 (env vars, ~/.aws/credentials, IAM role).
+
+roles:
+  cloud_architect:
+    role: "AWS Cloud Architect"
+    goal: "Design and explain cloud-native AI deployment strategies on AWS"
+    backstory: |
+      You are an AWS Solutions Architect specialising in AI/ML workloads.
+      You have deep expertise in Amazon Bedrock, SageMaker, ECS, and Lambda,
+      and you help organisations deploy AI agents at scale securely and cost-effectively.
+    llm:
+      model: "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"
+      api_type: "bedrock"
+      aws_region: "us-east-1"
+    tasks:
+      architecture_task:
+        description: |
+          Design a cloud-native deployment strategy for AI agents on AWS for: {topic}
+
+          Cover:
+          1. Recommended AWS services (Bedrock, ECS, Lambda, etc.)
+          2. Scalability and cost optimisation patterns
+          3. Security and compliance considerations
+          4. A simple reference architecture overview
+        expected_output: |
+          A concise architecture guide with service recommendations,
+          a high-level deployment diagram description, and key
+          best practices for production AI agent deployments on AWS.

examples/ag2/ag2_multi_agent.yaml

@@ -0,0 +1,54 @@
+framework: ag2
+topic: "The impact of open-source AI on enterprise software development"
+
+# Install: pip install "praisonai[ag2]"
+# Run:     praisonai --framework ag2 examples/ag2/ag2_multi_agent.yaml
+#       or praisonai run examples/ag2/ag2_multi_agent.yaml --framework ag2
+#
+# This example demonstrates AG2's GroupChat multi-agent coordination.
+# Both agents participate in a collaborative conversation managed by
+# a GroupChatManager until the task is complete.
+
+roles:
+  researcher:
+    role: "Research Specialist"
+    goal: "Gather and analyse information on the given topic"
+    backstory: |
+      You are a meticulous researcher who excels at finding relevant
+      information, analysing trends, and presenting data-backed insights.
+      You always cite your reasoning and structure your findings clearly.
+    tasks:
+      research_task:
+        description: |
+          Research the topic: {topic}
+
+          Investigate:
+          1. Current state and adoption rates
+          2. Key players and projects driving the trend
+          3. Technical advantages and challenges
+          4. Business impact and cost implications
+        expected_output: |
+          A structured research briefing with findings on the topic,
+          including key data points, trends, and technical observations.
+
+  writer:
+    role: "Technical Content Writer"
+    goal: "Transform research findings into clear, engaging written content"
+    backstory: |
+      You are a skilled technical writer who turns complex research into
+      accessible, well-structured articles. You focus on clarity, logical
+      flow, and actionable takeaways for a professional audience.
+    tasks:
+      writing_task:
+        description: |
+          Using the research findings provided by the Research Specialist,
+          write a concise article on: {topic}
+
+          The article should:
+          1. Open with a compelling hook
+          2. Present key findings logically
+          3. Include practical implications for developers
+          4. Close with a forward-looking conclusion
+        expected_output: |
+          A 400-500 word article suitable for a technical blog,
+          with clear sections, professional tone, and concrete takeaways.

examples/cookbooks/Code_Analysis_Agent.ipynb

@@ -0,0 +1,467 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "bLeMxwWimvzX"
+      },
+      "source": [
+        "# Code Analysis Agent\n",
+        "Learn how to create AI agents for comprehensive code analysis and quality assessment."
+      ],
+      "id": "bLeMxwWimvzX"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+
+        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Code_Analysis_Agent.ipynb)\n"
+=======
+        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/code_analysis_agent.ipynb)\n"
+
+      ],
+      "metadata": {
+        "id": "P3X8PXPyojnL"
+      },
+      "id": "P3X8PXPyojnL"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "xEs8bwWfmvza"
+      },
+      "source": [
+        "## Dependencies\n",
+        "Install the required packages."
+      ],
+      "id": "xEs8bwWfmvza"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "_RPiU3j6mvzb"
+      },
+      "outputs": [],
+      "source": [
+        "!pip install praisonaiagents gitingest"
+      ],
+      "id": "_RPiU3j6mvzb"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "81-orTkzmvzc"
+      },
+      "source": [
+        "## Set API Key\n",
+        "Set your OpenAI API key as an environment variable in your terminal:"
+      ],
+      "id": "81-orTkzmvzc"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "84iL7rGimvzc"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "os.environ['OPENAI_API_KEY'] = 'your_api_key_here'"
+      ],
+      "id": "84iL7rGimvzc"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "TV15GFsRmvzc"
+      },
+      "source": [
+        "## Tools and Data Models\n",
+        "Define the agent, task, and output schema."
+      ],
+      "id": "TV15GFsRmvzc"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "0Wq_g0pNmvzd"
+      },
+      "outputs": [],
+      "source": [
+        "from praisonaiagents import Agent, Task, PraisonAIAgents\n",
+        "from pydantic import BaseModel\n",
+        "from typing import List, Dict\n",
+        "from gitingest import ingest\n",
+        "\n",
+        "class CodeMetrics(BaseModel):\n",
+        "    category: str\n",
+        "    score: int\n",
+        "    findings: List[str]\n",
+        "\n",
+        "class CodeAnalysisReport(BaseModel):\n",
+        "    overall_quality: int\n",
+        "    code_metrics: List[CodeMetrics]\n",
+        "    architecture_score: int\n",
+        "    maintainability_score: int\n",
+        "    performance_score: int\n",
+        "    security_score: int\n",
+        "    test_coverage: int\n",
+        "    key_strengths: List[str]\n",
+        "    improvement_areas: List[str]\n",
+        "    tech_stack: List[str]\n",
+        "    recommendations: List[str]\n",
+        "    complexity_metrics: Dict[str, int]\n",
+        "    best_practices: List[Dict[str, str]]\n",
+        "    potential_risks: List[str]\n",
+        "    documentation_quality: int"
+      ],
+      "id": "0Wq_g0pNmvzd"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "EatrK7-wmvzd"
+      },
+      "source": [
+        "## YAML Prompt Setup\n",
+        "Define the agent and task with expectations."
+      ],
+      "id": "EatrK7-wmvzd"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "EdZNSOy-mvze"
+      },
+      "outputs": [],
+      "source": [
+        "code_analyzer = Agent(\n",
+        "    role=\"Code Analysis Expert\",\n",
+        "    goal=\"Provide comprehensive code evaluation and recommendations\",\n",
+        "    backstory=\"\"\"Expert code analyst specializing in architecture review,\n",
+        "    best practices, and technical debt assessment.\"\"\",\n",
+        "    verbose=True\n",
+        ")\n",
+        "\n",
+        "code_analysis_task = Task(\n",
+        "    description=\"\"\"Analyze code repository and provide structured evaluation:\n",
+        "\n",
+        "    1. Overall Quality (0-100)\n",
+        "    2. Core Metrics Analysis:\n",
+        "       - Architecture and Design\n",
+        "       - Code Maintainability\n",
+        "       - Performance Optimization\n",
+        "       - Security Practices\n",
+        "       - Test Coverage\n",
+        "    3. Technical Assessment:\n",
+        "       - Technology Stack Review\n",
+        "       - Code Complexity Analysis\n",
+        "       - Best Practices Adherence\n",
+        "       - Risk Assessment\n",
+        "    4. Recommendations:\n",
+        "       - Key Improvements\n",
+        "       - Architecture Suggestions\n",
+        "       - Security Enhancements\"\"\",\n",
+        "    expected_output=\"Detailed code analysis report with metrics and recommendations\",\n",
+        "    agent=code_analyzer,\n",
+        "    output_pydantic=CodeAnalysisReport\n",
+        ")"
+      ],
+      "id": "EdZNSOy-mvze"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "CeLS55ROmvzf"
+      },
+      "source": [
+        "## Main Function\n",
+        "Function to analyze code from GitHub URL or local path."
+      ],
+      "id": "CeLS55ROmvzf"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "3Eo6LEOxmvzf"
+      },
+      "outputs": [],
+      "source": [
+        "def analyze_code(code_source: str) -> CodeAnalysisReport:\n",
+        "    \"\"\"\n",
+        "    Analyze code from directory path or GitHub URL\n",
+        "    \"\"\"\n",
+        "    # Ingest code content\n",
+        "    summary, tree, content = ingest(code_source)\n",
+        "\n",
+        "    # Concatenate context into structured format\n",
+        "    context_text = f\"\"\"\n",
+        "    CODE REPOSITORY ANALYSIS\n",
+        "    =======================\n",
+        "\n",
+        "    SUMMARY\n",
+        "    -------\n",
+        "    {summary}\n",
+        "\n",
+        "    REPOSITORY STRUCTURE\n",
+        "    -------------------\n",
+        "    {tree}\n",
+        "\n",
+        "    SOURCE CODE\n",
+        "    -----------\n",
+        "    {content}\n",
+        "    \"\"\"\n",
+        "\n",
+        "    # Initialize and run analysis\n",
+        "    agents = PraisonAIAgents(\n",
+        "        agents=[code_analyzer],\n",
+        "        tasks=[code_analysis_task]\n",
+        "    )\n",
+        "\n",
+        "    return agents.start(context_text)"
+      ],
+      "id": "3Eo6LEOxmvzf"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "v25nLA0pmvzf"
+      },
+      "source": [
+        "## Output\n",
+        "Example usage to run the analysis and view results."
+      ],
+      "id": "v25nLA0pmvzf"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/",
+          "height": 1000
+        },
+        "id": "5BzccaeFmvzg",
+        "outputId": "8b4cddae-b6b3-4a92-8a13-30694cd09c52"
+      },
+      "outputs": [
+        {
+          "output_type": "display_data",
+          "data": {
+            "text/plain": [
+              "<IPython.core.display.Markdown object>"
+            ],
+            "text/markdown": "\n### 👤 Agent: Code Analysis Expert\n\n**Role**: Provides comprehensive code evaluation and recommendations  \n**Backstory**: Expert in architecture, best practices, and technical assessment  \n"
+          },
+          "metadata": {}
+        },
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "─── 📊 AGENT CODE ANALYSIS REPORT ───\n",
+            "{\n",
+            "    \"overall_quality\": 85,\n",
+            "    \"code_metrics\": [\n",
+            "        {\n",
+            "            \"category\": \"Architecture and Design\",\n",
+            "            \"score\": 80,\n",
+            "            \"findings\": [\n",
+            "                \"Modular structure with clear separation of concerns.\",\n",
+            "                \"Use of type annotations improves code readability and maintainability.\"\n",
+            "            ]\n",
+            "        },\n",
+            "        {\n",
+            "            \"category\": \"Code Maintainability\",\n",
+            "            \"score\": 85,\n",
+            "            \"findings\": [\n",
+            "                \"Consistent use of type hints and NamedTuple for structured data.\",\n",
+            "                \"Logical organization of functions and classes.\"\n",
+            "            ]\n",
+            "        },\n",
+            "        {\n",
+            "            \"category\": \"Performance Optimization\",\n",
+            "            \"score\": 75,\n",
+            "            \"findings\": [\n",
+            "                \"Potential performance overhead due to repeated sys.stdout.write calls.\",\n",
+            "                \"Efficient use of optional parameters to control execution flow.\"\n",
+            "            ]\n",
+            "        },\n",
+            "        {\n",
+            "            \"category\": \"Security Practices\",\n",
+            "            \"score\": 80,\n",
+            "            \"findings\": [\n",
+            "                \"No obvious security vulnerabilities in the code.\",\n",
+            "                \"Proper encapsulation of functionality.\"\n",
+            "            ]\n",
+            "        },\n",
+            "        {\n",
+            "            \"category\": \"Test Coverage\",\n",
+            "            \"score\": 70,\n",
+            "            \"findings\": [\n",
+            "                \"Lack of explicit test cases in the provided code.\",\n",
+            "                \"Use of type checking suggests some level of validation.\"\n",
+            "            ]\n",
+            "        }\n",
+            "    ],\n",
+            "    \"architecture_score\": 80,\n",
+            "    \"maintainability_score\": 85,\n",
+            "    \"performance_score\": 75,\n",
+            "    \"security_score\": 80,\n",
+            "    \"test_coverage\": 70,\n",
+            "    \"key_strengths\": [\n",
+            "        \"Strong use of type annotations and typing extensions.\",\n",
+            "        \"Clear separation of CLI argument parsing and business logic.\"\n",
+            "    ],\n",
+            "    \"improvement_areas\": [\n",
+            "        \"Increase test coverage to ensure robustness.\",\n",
+            "        \"Optimize I/O operations to improve performance.\"\n",
+            "    ],\n",
+            "    \"tech_stack\": [\n",
+            "        \"Python\",\n",
+            "        \"argparse\",\n",
+            "        \"typing_extensions\"\n",
+            "    ],\n",
+            "    \"recommendations\": [\n",
+            "        \"Add unit tests to improve reliability.\",\n",
+            "        \"Consider async I/O for improved performance in CLI tools.\"\n",
+            "    ]\n",
+            "}\n"
+          ]
+        }
+      ],
+      "source": [
+        "import json\n",
+        "from IPython.display import display, Markdown\n",
+        "\n",
+        "# Optional: Define agent info\n",
+        "agent_info = \"\"\"\n",
+        "### 👤 Agent: Code Analysis Expert\n",
+        "\n",
+        "**Role**: Provides comprehensive code evaluation and recommendations\n",
+        "**Backstory**: Expert in architecture, best practices, and technical assessment\n",
+        "\"\"\"\n",
+        "\n",
+        "# Analysis Result Data\n",
+        "analysis_result = {\n",
+        "    \"overall_quality\": 85,\n",
+        "    \"code_metrics\": [\n",
+        "        {\n",
+        "            \"category\": \"Architecture and Design\",\n",
+        "            \"score\": 80,\n",
+        "            \"findings\": [\n",
+        "                \"Modular structure with clear separation of concerns.\",\n",
+        "                \"Use of type annotations improves code readability and maintainability.\"\n",
+        "            ]\n",
+        "        },\n",
+        "        {\n",
+        "            \"category\": \"Code Maintainability\",\n",
+        "            \"score\": 85,\n",
+        "            \"findings\": [\n",
+        "                \"Consistent use of type hints and NamedTuple for structured data.\",\n",
+        "                \"Logical organization of functions and classes.\"\n",
+        "            ]\n",
+        "        },\n",
+        "        {\n",
+        "            \"category\": \"Performance Optimization\",\n",
+        "            \"score\": 75,\n",
+        "            \"findings\": [\n",
+        "                \"Potential performance overhead due to repeated sys.stdout.write calls.\",\n",
+        "                \"Efficient use of optional parameters to control execution flow.\"\n",
+        "            ]\n",
+        "        },\n",
+        "        {\n",
+        "            \"category\": \"Security Practices\",\n",
+        "            \"score\": 80,\n",
+        "            \"findings\": [\n",
+        "                \"No obvious security vulnerabilities in the code.\",\n",
+        "                \"Proper encapsulation of functionality.\"\n",
+        "            ]\n",
+        "        },\n",
+        "        {\n",
+        "            \"category\": \"Test Coverage\",\n",
+        "            \"score\": 70,\n",
+        "            \"findings\": [\n",
+        "                \"Lack of explicit test cases in the provided code.\",\n",
+        "                \"Use of type checking suggests some level of validation.\"\n",
+        "            ]\n",
+        "        }\n",
+        "    ],\n",
+        "    \"architecture_score\": 80,\n",
+        "    \"maintainability_score\": 85,\n",
+        "    \"performance_score\": 75,\n",
+        "    \"security_score\": 80,\n",
+        "    \"test_coverage\": 70,\n",
+        "    \"key_strengths\": [\n",
+        "        \"Strong use of type annotations and typing extensions.\",\n",
+        "        \"Clear separation of CLI argument parsing and business logic.\"\n",
+        "    ],\n",
+        "    \"improvement_areas\": [\n",
+        "        \"Increase test coverage to ensure robustness.\",\n",
+        "        \"Optimize I/O operations to improve performance.\"\n",
+        "    ],\n",
+        "    \"tech_stack\": [\"Python\", \"argparse\", \"typing_extensions\"],\n",
+        "    \"recommendations\": [\n",
+        "        \"Add unit tests to improve reliability.\",\n",
+        "        \"Consider async I/O for improved performance in CLI tools.\"\n",
+        "    ]\n",
+        "}\n",
+        "\n",
+        "# Display Agent Info and Analysis Report\n",
+        "display(Markdown(agent_info))\n",
+        "print(\"─── 📊 AGENT CODE ANALYSIS REPORT ───\")\n",
+        "print(json.dumps(analysis_result, indent=4))\n"
+      ],
+      "id": "5BzccaeFmvzg"
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "%cd PraisonAI"
+      ],
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "mNZjZLedorlu",
+        "outputId": "82c96cdf-e2e5-4a9c-e633-f0fc225ad973"
+      },
+      "id": "mNZjZLedorlu",
+      "execution_count": 5,
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "/content/PraisonAI\n"
+          ]
+        }
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10"
+    },
+    "colab": {
+      "provenance": []
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+
+}
+=======
+}
+

examples/cookbooks/Gemma2B_Instruction_Agent.ipynb

@@ -0,0 +1,605 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "PnWDOzZelHlE",
+   "metadata": {
+    "id": "PnWDOzZelHlE"
+   },
+   "source": [
+    "# 🌱 Gemma 2B Instruction Agent\n",
+    "\n",
+    "**Goal:** You will learn how to do data prep, how to train, how to run the model, and how to save it using Google’s `gemma-2b-it` open-source model.\n",
+    "\n",
+    "---\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4qumJb5qs9CF",
+   "metadata": {
+    "id": "4qumJb5qs9CF"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Gemma2B_Instruction_Agent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qdsqiQDosXmA",
+   "metadata": {
+    "id": "qdsqiQDosXmA"
+   },
+   "source": [
+    "#  Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6G4RPDe3lHlH",
+   "metadata": {
+    "id": "6G4RPDe3lHlH"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install transformers accelerate datasets bitsandbytes -q"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "mop0KNO7sdEl",
+   "metadata": {
+    "id": "mop0KNO7sdEl"
+   },
+   "source": [
+    "# Tools & Model Setup"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "spOeRX2UlHlI",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 369,
+     "referenced_widgets": [
+      "a2db67e368d94f579c59b36c6ce7af33",
+      "5816fa4288cd42d6b15094e2c79f760f",
+      "5d6fe9b464f944cdbb00b9936669e737",
+      "19920e5b8157423ba5d173dd376e52e6",
+      "bd7157974bc5485ab5b6db54facb9721",
+      "0063e7320c98440d91ae475596c5cd90",
+      "a0f045bc54754d5a85ed6bf7b6b33c1a",
+      "9174c5aff19b4caab8a38fbf3acb2449",
+      "3de0f0b7ecb34c488145b24e30418e4b",
+      "d4457543819d468eb916f126382184b0",
+      "08f90c04f0de4b1db57624db4b43e17d",
+      "269373e971704b9ea2e10e261b1c56d1",
+      "d54d35c945ce4f75af6f83f37dd6af6c",
+      "b828857fecdc40fa91f6a8633f0f20b4",
+      "b5e70949aea24ae9a75e45aa291cc3aa",
+      "9c556838b24246a8b39b1f3f9babfe4a",
+      "062b64d17b7043c1bccc419280c9db0a",
+      "138ae14327184f65896c29a424bad18d",
+      "cb65fa660df54218ad804815dfba4071",
+      "93d2454f1b564896bef50906e859c660",
+      "64e7861e6afc4b57b28063096533aac8",
+      "13fe0b8a8fd14a3684ae5d9beefb3f76",
+      "d1ec61e51d4c4b07b301959c4919f2a2",
+      "a45e9ed3d46645a18ca1f6b06f875ec9",
+      "a364770555cf40fdab5ff7bb85997127",
+      "12b3225aeb8c4f61b23b588738d48683",
+      "dca4952bae4c49ddb2fec2c36726a34d",
+      "163df8921f04425caed240465d8bd8b7",
+      "1a09718a80cd4bb5a9e985a3f599c614",
+      "71c719d57e4f4e23bd520f80e2e07e33",
+      "5e8c8eb7eba948fc8a39b601e9ac658e",
+      "db4fa2c97b7247c4826a1a9f69c1bed3",
+      "42a6f9c136584cc98fc2be973d9edaec",
+      "c1bc8cf2ed6542c49c1940673a662b1d",
+      "365b69634e2846a09b91de6b61d0719b",
+      "13eb69bc1c3c432db6c504856f3a0f7a",
+      "56444404d97549848ed729ee8bc14ec8",
+      "f0303454544d42a1ada2213a085a4ac0",
+      "c717969ed1b145a9af67d74482d49eab",
+      "9e9a826dfb264e44aa69c553d978729d",
+      "f2b4ff56a96c4d7e9f56668f6b7b5213",
+      "f71f0a3ccc654df288d7489abca0ffc0",
+      "5ab0574ed1db47e9b6f43e27acd6c2b2",
+      "426fae423dbb43ef9252e6fcfb099c6f",
+      "2e1c3ca06b2948f0bcf53a975dd67aec",
+      "3685a74a466a4ca0b5f05e7aee631d74",
+      "7bda5a4e803c4cbc8da67da8a565725b",
+      "5450fde9a54d450d90d14b009047b522",
+      "e827839bf4d34d2193776d1ee90d27ad",
+      "3d9854af016a4c3c8a582fc7f0f0b0bf",
+      "7045a11d5f0f4b2d8ff224bb76a9c943",
+      "32e568b25c2d447a8fa63055cb44c75c",
+      "ebd9d55db82542e5ae6bb9e715e36a6a",
+      "798a57883792465ab024dc19a58a54be",
+      "c9d1133770b44b22bda89f3d0eecd4f8",
+      "c040fa1bbd9f442884776fdf33efb4a2",
+      "c57e497d4fd546ff950eb2c898b94c88",
+      "5ae22935b7374219a16272cef31d6d9e",
+      "aae2686ee64740218d046ec37e50b584",
+      "87b4c953163a4cff8a88b76f40da9de8",
+      "30ee0e766fae44bfb570ae8adfba1a54",
+      "1c2db67dfc904e30a4013d9fe0253a4c",
+      "f6c5380bba0f40a4bea9b78d205eb726",
+      "0de9f765500b45428f828ad173dd279e",
+      "0663e5cfc20c496993b7c0054ce3d1a1",
+      "7ce5d369129b461681f424e52415e534",
+      "dfa90d76c670436a80f1a4fd0971b171",
+      "0694216654ac41909d567a8c4af247de",
+      "658048f25b4a4ad6a3ee66e97a542cc9",
+      "0edccfd243f940cfad9723b1d3f5a97c",
+      "32d473040a6744718b1b35543f2b3a0f",
+      "eadbfe846763427e98a40597560d8519",
+      "3cec8231bccb4bcf8d657ee8d2120f79",
+      "8bd43207fa8f4b309590f605ad81354f",
+      "8821912860f04105959ceb42e53de948",
+      "3666b044c757439f948f6942d7682c2f",
+      "d47e7c7504374fee82eef9f8cbe24eff",
+      "9c6d577f113f4f4baaa1f0e001549862",
+      "b0c88d34b0df46b7a3da8db42ff3274e",
+      "e4e4a2d0422b45c09c8691ce14ba9b9a",
+      "d9b1de1b37f14d70bc56a5f6cb468c9b",
+      "cb95b11368984236937fcec7cb689b04",
+      "69e70bfdafd4459491bad75651028626",
+      "a3b9f03c1f014691b5959fb9012c0bab",
+      "088da12bcff64297ad82dc7b2d01709e",
+      "8a69dc8aa84e49b1aabb58eddca1eee3",
+      "263e458b8a5f405bb1ee365fe561309d",
+      "aa3039e03447492da11f86185384470b",
+      "3c22264e11c0402fb07f56a0763dc055",
+      "db2c5746b8cc48d9a059bcef3b55217d",
+      "ad3ab2ab81f6469485a3072bd1ba6a4a",
+      "74ab1c79c43041c7ac314d62a6da04bf",
+      "ad1a3719b1814f6b88202e131ae923c7",
+      "d1cb72251682425fa6ca68341a084f95",
+      "895914fca4204593b1a4314e50b8e5a1",
+      "a8374dc19b294b6d8f5f92bee5196a1a",
+      "b7bef910950949fbac65fd996ad058e2",
+      "ce6b7aadbd904b3caa93d927ced6beb3",
+      "ba6a9e31ddf7419db317a5d27a1567bf",
+      "f271e9c78dcf4ab686caac37f18bd6f7",
+      "9ed57fe81783476986d6cb98d07e9aa1",
+      "8da75a35ab184675b0164682d8217406",
+      "f411c4485b844ceb9b3116f209a6fc86",
+      "60ac9cd6505141348323b39db7314554",
+      "59b2d494f11344879463a3471716bc3f",
+      "46abda4b52224874a93b729f5d4d195b",
+      "37bc81b97d48474aa0fd7e7739654d86",
+      "73da5101d99440abac30dc8c084439d4",
+      "ef790742325743fdb8f7cc6822388185",
+      "5eccfbe5715f4df9a96cffb2573f916f",
+      "3bf293367470430f84f341ef8711460a",
+      "317281ca2af54a148fa4cfd8f6e0f382",
+      "d655ef37643448aa95253143f8552f58",
+      "158e61376dee400e820f47c87d59bac5",
+      "d1fbbe8010e340119bf556c75284e1c2",
+      "eea1731926554e56a85867de15153f82",
+      "766fb34d23b941b2a9e0de153f4cb031",
+      "beb52b95db564105bbd8bc2b2d21c1ce",
+      "2effd1c45bee4278bd9172310f58fed4",
+      "91d6488876284748932b664953c02146",
+      "9157d82cca3f45c5b5a666a3d35d6abe"
+     ]
+    },
+    "id": "spOeRX2UlHlI",
+    "outputId": "093b74d1-9ece-4db5-d177-3aff6e2d6e0b"
+   },
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "a2db67e368d94f579c59b36c6ce7af33",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer_config.json:   0%|          | 0.00/47.0k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "269373e971704b9ea2e10e261b1c56d1",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer.model:   0%|          | 0.00/4.24M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "d1ec61e51d4c4b07b301959c4919f2a2",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer.json:   0%|          | 0.00/17.5M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "c1bc8cf2ed6542c49c1940673a662b1d",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "special_tokens_map.json:   0%|          | 0.00/636 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "2e1c3ca06b2948f0bcf53a975dd67aec",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "config.json:   0%|          | 0.00/838 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "c040fa1bbd9f442884776fdf33efb4a2",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "model.safetensors.index.json:   0%|          | 0.00/24.2k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "dfa90d76c670436a80f1a4fd0971b171",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Fetching 2 files:   0%|          | 0/2 [00:00<?, ?it/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "9c6d577f113f4f4baaa1f0e001549862",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "model-00001-of-00002.safetensors:   0%|          | 0.00/4.99G [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "3c22264e11c0402fb07f56a0763dc055",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "model-00002-of-00002.safetensors:   0%|          | 0.00/241M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "f271e9c78dcf4ab686caac37f18bd6f7",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Loading checkpoint shards:   0%|          | 0/2 [00:00<?, ?it/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "3bf293367470430f84f341ef8711460a",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "generation_config.json:   0%|          | 0.00/187 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from huggingface_hub import login\n",
+    "from transformers import AutoTokenizer, AutoModelForCausalLM, TrainingArguments, Trainer\n",
+    "from datasets import load_dataset\n",
+    "import torch\n",
+    "\n",
+    "login(\"Enter your token here\")\n",
+    "\n",
+    "model_id = \"google/gemma-2-2b-it\"\n",
+    "\n",
+    "tokenizer = AutoTokenizer.from_pretrained(model_id)\n",
+    "model = AutoModelForCausalLM.from_pretrained(\n",
+    "    model_id,\n",
+    "    device_map=\"auto\",              # Automatically selects GPU if available\n",
+    "    torch_dtype=torch.float16       # Optimized for performance\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "GaykKFKYspMd",
+   "metadata": {
+    "id": "GaykKFKYspMd"
+   },
+   "source": [
+    "# Yaml Prompt Configuration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "iLBZ7WPAlHlJ",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "iLBZ7WPAlHlJ",
+    "outputId": "a99fc3f2-68e0-4af8-cfbd-3c48a865538f"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "You are Qwen, a helpful assistant.\n",
+      "User: What is the capital of France?\n",
+      "Assistant: The capital of France is **Paris**. \n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "prompt = \"You are Qwen, a helpful assistant.\\nUser: What is the capital of France?\\nAssistant:\"\n",
+    "inputs = tokenizer(prompt, return_tensors=\"pt\").to(model.device)\n",
+    "outputs = model.generate(**inputs, max_new_tokens=100)\n",
+    "response = tokenizer.decode(outputs[0], skip_special_tokens=True)\n",
+    "print(response)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "XPqtCExSsvhn",
+   "metadata": {
+    "id": "XPqtCExSsvhn"
+   },
+   "source": [
+    "# Use a small sample dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "id": "ActfjFx0lHlK",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 49,
+     "referenced_widgets": [
+      "f1028b5dcab4460c81b09802ca7ec89c",
+      "ff33dcccaad945e9bf136d0f72e38d74",
+      "eec3a11b0605435d8d1e55092f5e5b85",
+      "d997b7bc993b4aa58cfafa7c59829ad3",
+      "62e2dc508746419ba3c0405a7199c6dc",
+      "2a7fc59019c749aa98d0e970a9b6b168",
+      "78067f66c8544020aa262c0012aa019b",
+      "f5e511b4279747c0a33b10f499a4f718",
+      "10e248a5730c4c09834b4065b6dd7843",
+      "bbd5a106c1de43e497987648899569e0",
+      "118faf3d1ed142038af4783fb3ba86cc"
+     ]
+    },
+    "id": "ActfjFx0lHlK",
+    "outputId": "f257e553-7baa-4f1e-b531-a6b7dc358665"
+   },
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "f1028b5dcab4460c81b09802ca7ec89c",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Map:   0%|          | 0/4 [00:00<?, ? examples/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from datasets import Dataset\n",
+    "\n",
+    "sample_data = {\n",
+    "    'text': [\n",
+    "        'The sun is a star at the center of our solar system.',\n",
+    "        'Photosynthesis is the process by which green plants make food.',\n",
+    "        'Water freezes at 0 degrees Celsius.',\n",
+    "        'The Earth revolves around the sun in 365 days.'\n",
+    "    ]\n",
+    "}\n",
+    "\n",
+    "dataset = Dataset.from_dict(sample_data)\n",
+    "\n",
+    "def tokenize_function(example):\n",
+    "    return tokenizer(example['text'], padding='max_length', truncation=True, max_length=64)\n",
+    "\n",
+    "tokenized_dataset = dataset.map(tokenize_function)\n",
+    "tokenized_dataset.set_format(type='torch', columns=['input_ids', 'attention_mask'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "x7icWpOnszjj",
+   "metadata": {
+    "id": "x7icWpOnszjj"
+   },
+   "source": [
+    "# Inference"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "id": "8mM4PAhRlHlL",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "8mM4PAhRlHlL",
+    "outputId": "1ba90639-b847-4cb1-df42-3fdd644e4cb8"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "user\n",
+      "Explain photosynthesis to a child.\n",
+      "model\n",
+      "Imagine plants are like tiny chefs, and they cook their own food! \n",
+      "\n",
+      "They use sunlight, air, and water to make yummy food called sugar.  \n",
+      "\n",
+      "Here's how it works:\n",
+      "\n",
+      "1. **Sunlight:** Plants have special green stuff called chlorophyll that acts like a solar panel, soaking up the sun's energy.\n",
+      "2. **Air:** Plants take in air through tiny holes in their leaves called stomata.  The air has a gas called carbon dioxide.\n",
+      "3\n"
+     ]
+    }
+   ],
+   "source": [
+    "input_text = \"Explain photosynthesis to a child.\"\n",
+    "chat = tokenizer.apply_chat_template(\n",
+    "    [{\"role\": \"user\", \"content\": input_text}],\n",
+    "    tokenize=False,\n",
+    "    add_generation_prompt=True\n",
+    ")\n",
+    "inputs = tokenizer(chat, return_tensors=\"pt\").to(model.device)\n",
+    "output = model.generate(**inputs, max_new_tokens=100)\n",
+    "print(tokenizer.decode(output[0], skip_special_tokens=True))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "Fhkfhbjns2oq",
+   "metadata": {
+    "id": "Fhkfhbjns2oq"
+   },
+   "source": [
+    "# Save Model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "OuJEt2-jlHlL",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "OuJEt2-jlHlL",
+    "outputId": "f076e950-cce7-4850-edd9-ff1d84a096d6"
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('gemma-finetuned-demo/tokenizer_config.json',\n",
+       " 'gemma-finetuned-demo/special_tokens_map.json',\n",
+       " 'gemma-finetuned-demo/chat_template.jinja',\n",
+       " 'gemma-finetuned-demo/tokenizer.model',\n",
+       " 'gemma-finetuned-demo/added_tokens.json',\n",
+       " 'gemma-finetuned-demo/tokenizer.json')"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model.save_pretrained(\"gemma-finetuned-demo\")\n",
+    "tokenizer.save_pretrained(\"gemma-finetuned-demo\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "uFK1sCzblHlM",
+   "metadata": {
+    "id": "uFK1sCzblHlM"
+   },
+   "source": [
+    "# Output\n",
+    "`Photosynthesis is how plants eat sunlight! 🌞 They use air, water, and sunlight to make food and grow.`"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/cookbooks/Groq_LPU_Powered_AI_Assistant.ipynb

@@ -0,0 +1,245 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "a9343007",
+      "metadata": {
+        "id": "a9343007"
+      },
+      "source": [
+        "# Groq Llama3-8b-8192 Agent\n",
+        "This agent uses Groq's `llama3-8b-8192` model to answer questions about Groq technology.\n",
+        "It demonstrates a structured approach with YAML configs, prompt templates, and result handling."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Groq_LPU_Powered_AI_Assistant.ipynb)\n"
+      ],
+      "metadata": {
+        "id": "mBWaooyypsyD"
+      },
+      "id": "mBWaooyypsyD"
+    },
+    {
+      "cell_type": "markdown",
+      "id": "b36ff766",
+      "metadata": {
+        "id": "b36ff766"
+      },
+      "source": [
+        "## Dependencies\n",
+        "We'll install the required Groq Python SDK.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "id": "518e7a6a",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "518e7a6a",
+        "outputId": "98149592-19d0-472a-c31b-aae763fc8b07"
+      },
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "\u001b[?25l   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/129.6 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K   \u001b[91m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m\u001b[91m╸\u001b[0m\u001b[90m━━\u001b[0m \u001b[32m122.9/129.6 kB\u001b[0m \u001b[31m5.3 MB/s\u001b[0m eta \u001b[36m0:00:01\u001b[0m\r\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m129.6/129.6 kB\u001b[0m \u001b[31m2.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+            "\u001b[?25h"
+          ]
+        }
+      ],
+      "source": [
+        "!pip install --quiet groq pyyaml"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "d8569a5f",
+      "metadata": {
+        "id": "d8569a5f"
+      },
+      "source": [
+        "## Tools Setup\n",
+        "Initialize Groq client and helper functions for prompt generation.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "id": "b59b0d09",
+      "metadata": {
+        "id": "b59b0d09"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "import yaml\n",
+        "from groq import Groq\n",
+        "\n",
+        "# Set API key (replace with your own or use environment variables)\n",
+        "os.environ['GROQ_API_KEY'] = 'enter your key'\n",
+        "\n",
+        "# Initialize Groq client\n",
+        "client = Groq()\n",
+        "\n",
+        "def run_groq_chat(prompt_messages, model='llama3-8b-8192'):\n",
+        "    response = client.chat.completions.create(\n",
+        "        model=model,\n",
+        "        messages=prompt_messages\n",
+        "    )\n",
+        "    return response.choices[0].message.content\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "9302e8e6",
+      "metadata": {
+        "id": "9302e8e6"
+      },
+      "source": [
+        "## YAML Configuration\n",
+        "Define model and prompt templates via YAML.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 3,
+      "id": "238b8f7f",
+      "metadata": {
+        "id": "238b8f7f"
+      },
+      "outputs": [],
+      "source": [
+        "yaml_config = '''\n",
+        "model: llama3-8b-8192\n",
+        "prompt_template: |\n",
+        "  You are an expert AI assistant knowledgeable about Groq's technology.\n",
+        "  Provide a detailed answer to the user's question.\n",
+        "  Then summarize the key points briefly.\n",
+        "\n",
+        "  User question: \"{user_question}\"\n",
+        "'''\n",
+        "\n",
+        "config = yaml.safe_load(yaml_config)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "6d2ff6b1",
+      "metadata": {
+        "id": "6d2ff6b1"
+      },
+      "source": [
+        "## Prompt Construction\n",
+        "Fill in the prompt template with user input.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "id": "2d42e686",
+      "metadata": {
+        "id": "2d42e686"
+      },
+      "outputs": [],
+      "source": [
+        "def build_prompt(user_question):\n",
+        "    prompt_text = config['prompt_template'].format(user_question=user_question)\n",
+        "    messages = [\n",
+        "        {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n",
+        "        {\"role\": \"user\", \"content\": prompt_text}\n",
+        "    ]\n",
+        "    return messages\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "3c9448d3",
+      "metadata": {
+        "id": "3c9448d3"
+      },
+      "source": [
+        "## Main Logic\n",
+        "Run the agent on an example question.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "id": "c59933e4",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "c59933e4",
+        "outputId": "bad10728-fd20-4e0d-fded-c29fd987a9b7"
+      },
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "Agent response:\n",
+            "Groq's Low-Precision Unified (LPU) technology is a proprietary architecture designed to accelerate artificial intelligence (AI) and machine learning (ML) workloads. LPU-powered models, also known as Groq Models, have several advantages over traditional Graphics Processing Units (GPUs) in specific applications:\n",
+            "\n",
+            "1. **Improved energy efficiency**: LPU is optimized for low power consumption, making it suitable for edge, mobile, and embedded devices where power constraints are common. This is particularly important for applications that require long-lived deployments, such as autonomous vehicles or IoT sensors.\n",
+            "2. **Enhanced accuracy**: LPU's customized precision and data type selection enable better representational precision for numeric computations, resulting in improved model accuracy. This is particularly beneficial for tasks that require high-fidelity calculations, such as medical imaging or natural language processing.\n",
+            "3. **Simplified software development**: LPU's unified architecture simplifies the development process for AI/ML developers. Groq Models provide a consistent programming model across different inference scenarios, allowing for easier model deployment and optimization.\n",
+            "4. **Increased throughput**: LPU's optimized arithmetic units and pipelined architecture enable higher Throughput per Watt (TPW) compared to traditional GPUs. This translates to faster processing times and higher compute density.\n",
+            "5. **Flexibility and scalability**: LPU-powered models can be deployed across various hardware platforms, from small, low-power devices to large data center clusters. This flexibility allows developers to choose the optimal deployment scenario for their specific use case.\n",
+            "6. **Customization and specialization**: LPU's architecture can be customized for specific workloads, allowing for optimized performance and power consumption. This customization potential enables developers to create highly specialized AI/ML hardware that matches their specific requirements.\n",
+            "\n",
+            "In summary, Groq's LPU-powered models offer significant advantages over traditional GPUs in terms of energy efficiency, accuracy, software development simplicity, throughput, flexibility, and customization.\n",
+            "\n",
+            "Key points:\n",
+            "\n",
+            "* Improved energy efficiency and suitability for edge, mobile, and embedded devices\n",
+            "* Enhanced accuracy for high-fidelity calculations\n",
+            "* Simplified software development with a unified programming model\n",
+            "* Increased throughput and compute density\n",
+            "* Flexibility and scalability across various hardware platforms\n",
+            "* Customization potential for specific workloads and applications\n"
+          ]
+        }
+      ],
+      "source": [
+        "user_question = \"What are the advantages of Groq's LPU-powered models compared to traditional GPUs?\"\n",
+        "prompt_messages = build_prompt(user_question)\n",
+        "agent_response = run_groq_chat(prompt_messages, model=config['model'])\n",
+        "print(\"Agent response:\")\n",
+        "print(agent_response)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "304a52dd",
+      "metadata": {
+        "id": "304a52dd"
+      },
+      "source": [
+        "## Output\n",
+        "The agent provides a detailed answer followed by a brief summary.\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": []
+    },
+    "language_info": {
+      "name": "python"
+    },
+    "kernelspec": {
+      "name": "python3",
+      "display_name": "Python 3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

examples/cookbooks/Hackathon_Agent_Notebook.ipynb

@@ -0,0 +1,436 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "dcpGQid2Jcud"
+      },
+      "source": [
+        "# 📘 Hackathon Project Video Evaluator using PraisonAIAgents"
+      ],
+      "id": "dcpGQid2Jcud"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Hackathon_Agent_Notebook.ipynb)\n"
+      ],
+      "metadata": {
+        "id": "9A8PW-_1NyK4"
+      },
+      "id": "9A8PW-_1NyK4"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Dependencies"
+      ],
+      "metadata": {
+        "id": "B-RlKMC3NWZL"
+      },
+      "id": "B-RlKMC3NWZL"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "ItoyCaVhJcug"
+      },
+      "outputs": [],
+      "source": [
+        "!pip install praisonaiagents opencv-python moviepy"
+      ],
+      "id": "ItoyCaVhJcug"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Set OpenAI API Key for Authentication"
+      ],
+      "metadata": {
+        "id": "x4dBCoN-Nf4h"
+      },
+      "id": "x4dBCoN-Nf4h"
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "import os\n",
+        "os.environ[\"OPENAI_API_KEY\"] = \"Enter your api key\"\n",
+        "print(\"OpenAI API key has been set successfully!\")"
+      ],
+      "metadata": {
+        "id": "wz9hEZf1Ncv2"
+      },
+      "id": "wz9hEZf1Ncv2",
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Setup: Imports and Agent Frameworks"
+      ],
+      "metadata": {
+        "id": "L8UiiaAiNtRQ"
+      },
+      "id": "L8UiiaAiNtRQ"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "eU6iiDynJcuh"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "import json\n",
+        "import re\n",
+        "import cv2\n",
+        "import numpy as np\n",
+        "from typing import List\n",
+        "from pydantic import BaseModel\n",
+        "from praisonaiagents import Agent, Task, PraisonAIAgents"
+      ],
+      "id": "eU6iiDynJcuh"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "jIBUGHAbJcui"
+      },
+      "source": [
+        "## 🛠️ Tools and Data Models"
+      ],
+      "id": "jIBUGHAbJcui"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "3wGOzkZcJcuj"
+      },
+      "outputs": [],
+      "source": [
+        "class ProjectEvaluation(BaseModel):\n",
+        "    innovation_score: int\n",
+        "    technical_complexity: int\n",
+        "    presentation_quality: int\n",
+        "    user_experience: int\n",
+        "    completeness: int\n",
+        "    overall_score: int\n",
+        "    key_strengths: List[str]\n",
+        "    areas_for_improvement: List[str]\n",
+        "    notable_features: List[str]\n",
+        "    technical_highlights: List[str]\n",
+        "    recommendations: List[str]\n",
+        "    market_potential: str\n",
+        "    scalability_assessment: str"
+      ],
+      "id": "3wGOzkZcJcuj"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "idRWbOQNJcuj"
+      },
+      "source": [
+        "## 🎞️ Video Frame Extraction"
+      ],
+      "id": "idRWbOQNJcuj"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "Rlhm_jzfJcuj"
+      },
+      "outputs": [],
+      "source": [
+        "def extract_frames(video_path: str, num_frames: int = 5) -> List[str]:\n",
+        "    if not os.path.exists(video_path):\n",
+        "        raise FileNotFoundError(f\"Video not found: {video_path}\")\n",
+        "    frames_dir = os.path.join(os.path.dirname(video_path), \"frames\")\n",
+        "    os.makedirs(frames_dir, exist_ok=True)\n",
+        "    cap = cv2.VideoCapture(video_path)\n",
+        "    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))\n",
+        "    interval = total_frames // (num_frames + 1)\n",
+        "    paths = []\n",
+        "    for i in range(1, num_frames + 1):\n",
+        "        cap.set(cv2.CAP_PROP_POS_FRAMES, i * interval)\n",
+        "        ret, frame = cap.read()\n",
+        "        if not ret: break\n",
+        "        path = os.path.join(frames_dir, f\"frame_{i}.jpg\")\n",
+        "        cv2.imwrite(path, frame)\n",
+        "        paths.append(path)\n",
+        "    cap.release()\n",
+        "    return paths"
+      ],
+      "id": "Rlhm_jzfJcuj"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "97Bap7zKJcuk"
+      },
+      "source": [
+        "## 🤖 Define the AI Agent"
+      ],
+      "id": "97Bap7zKJcuk"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "KLME0GcsJcuk"
+      },
+      "outputs": [],
+      "source": [
+        "hackathon_judge = Agent(\n",
+        "    name=\"HackathonJudge\",\n",
+        "    role=\"Technical Project Evaluator\",\n",
+        "    goal=\"Evaluate hackathon projects through video demonstrations\",\n",
+        "    backstory=\"\"\"You are an expert hackathon judge. You give fair scores and detailed feedback\n",
+        "    on technical complexity, innovation, presentation, and UX.\"\"\",\n",
+        "    llm=\"gpt-4o-mini\",\n",
+        "    self_reflect=False\n",
+        ")"
+      ],
+      "id": "KLME0GcsJcuk"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "HG5dmlzhJcul"
+      },
+      "source": [
+        "## 🚀 Main Evaluation Function"
+      ],
+      "id": "HG5dmlzhJcul"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "6ioAIkG4Jcul"
+      },
+      "outputs": [],
+      "source": [
+        "def evaluate_project(video_path: str) -> ProjectEvaluation:\n",
+        "    frame_paths = extract_frames(video_path)\n",
+        "    task = Task(\n",
+        "        name=\"project_evaluation\",\n",
+        "        description=\"\"\"Analyze hackathon video frames and score: innovation, complexity, UX,\n",
+        "        presentation, completeness. Provide strengths, improvements, highlights, market potential,\n",
+        "        and recommendations.\"\"\",\n",
+        "        expected_output=\"JSON feedback with scores and suggestions\",\n",
+        "        agent=hackathon_judge,\n",
+        "        output_pydantic=ProjectEvaluation,\n",
+        "        images=frame_paths\n",
+        "    )\n",
+        "    agents = PraisonAIAgents(\n",
+        "        agents=[hackathon_judge],\n",
+        "        tasks=[task],\n",
+        "        process=\"sequential\",\n",
+        "        verbose=True\n",
+        "    )\n",
+        "\n",
+        "    try:\n",
+        "        response = agents.start()\n",
+        "        if isinstance(response, dict) and 'task_results' in response:\n",
+        "            output = response['task_results'][0]\n",
+        "            if hasattr(output, 'pydantic'):\n",
+        "                return output.pydantic\n",
+        "            elif hasattr(output, 'raw'):\n",
+        "                raw = output.raw.strip()\n",
+        "                json_text = re.search(r'```(?:json)?\\s*([\\s\\S]+?)\\s*```', raw)\n",
+        "                raw = json_text.group(1).strip() if json_text else raw\n",
+        "                return ProjectEvaluation(**json.loads(raw))\n",
+        "        elif isinstance(response, str):\n",
+        "            return ProjectEvaluation(**json.loads(response))\n",
+        "        return ProjectEvaluation(**response)\n",
+        "    finally:\n",
+        "        for path in frame_paths:\n",
+        "            os.remove(path)\n",
+        "        try:\n",
+        "            os.rmdir(os.path.join(os.path.dirname(video_path), \"frames\"))\n",
+        "        except: pass"
+      ],
+      "id": "6ioAIkG4Jcul"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "VAwiZiJ1Jcum"
+      },
+      "source": [
+        "## ▶️ Run the Evaluation"
+      ],
+      "id": "VAwiZiJ1Jcum"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "Jf9_efNPJcum"
+      },
+      "outputs": [],
+      "source": [
+        "os.environ[\"OPENAI_API_KEY\"] = \"sk-proj-...YOUR_API_KEY...\"\n",
+        "\n",
+        "video_file = \"presentation.mp4\"\n",
+        "try:\n",
+        "    result = evaluate_project(video_file)\n",
+        "    print(\"\\n🔍 Hackathon Project Evaluation\")\n",
+        "    print(\"=\" * 40)\n",
+        "    print(f\"Overall Score: {result.overall_score}/100\")\n",
+        "    print(f\"Innovation: {result.innovation_score}/100\")\n",
+        "    print(f\"Technical Complexity: {result.technical_complexity}/100\")\n",
+        "    print(f\"Presentation Quality: {result.presentation_quality}/100\")\n",
+        "    print(f\"User Experience: {result.user_experience}/100\")\n",
+        "    print(f\"Completeness: {result.completeness}/100\")\n",
+        "    print(\"\\n✅ Key Strengths:\")\n",
+        "    for s in result.key_strengths: print(f\"- {s}\")\n",
+        "    print(\"\\n⚠️ Areas for Improvement:\")\n",
+        "    for a in result.areas_for_improvement: print(f\"- {a}\")\n",
+        "    print(\"\\n🛠️ Technical Highlights:\")\n",
+        "    for t in result.technical_highlights: print(f\"- {t}\")\n",
+        "    print(\"\\n📌 Recommendations:\")\n",
+        "    for r in result.recommendations: print(f\"- {r}\")\n",
+        "    print(f\"\\n📈 Market Potential: {result.market_potential}\")\n",
+        "    print(f\"\\n📊 Scalability Assessment: {result.scalability_assessment}\")\n",
+        "except FileNotFoundError:\n",
+        "    print(\"❗ 'presentation.mp4' not found. Please add it to the current directory.\")\n",
+        "except Exception as e:\n",
+        "    print(f\"❌ Evaluation Error: {e}\")"
+      ],
+      "id": "Jf9_efNPJcum"
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "output = \"\"\"\n",
+        "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+        "│                                                                                                                              │\n",
+        "│  👤 Agent: HackathonJudge                                                                                                    │\n",
+        "│  Role: Technical Project Evaluator                                                                                           │\n",
+        "│                                                                                                                              │\n",
+        "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+        "\n",
+        "╭───────────────────────────────────────────────────── Generating... 6.6s ─────────────────────────────────────────────────────╮\n",
+        "│                                                                                                                              │\n",
+        "│  {                                                                                                                           │\n",
+        "│    \"innovation_score\": 30,                                                                                                   │\n",
+        "│    \"technical_complexity\": 20,                                                                                               │\n",
+        "│    \"presentation_quality\": 25,                                                                                               │\n",
+        "│    \"user_experience\": 35,                                                                                                    │\n",
+        "│    \"completeness\": 20,                                                                                                       │\n",
+        "│    \"overall_score\": 24,                                                                                                      │\n",
+        "│    \"key_strengths\": [                                                                                                        │\n",
+        "│      \"Simple concept\",                                                                                                       │\n",
+        "│      \"Clear visual representation\"                                                                                           │\n",
+        "│    ],                                                                                                                        │\n",
+        "│    \"areas_for_improvement\": [                                                                                                │\n",
+        "│      \"Enhance technical features\",                                                                                           │\n",
+        "│      \"Improve presentation clarity\",                                                                                         │\n",
+        "│      \"Add user interaction elements\"                                                                                         │\n",
+        "│    ],                                                                                                                        │\n",
+        "│    \"notable_features\": [                                                                                                     │\n",
+        "│      \"Basic visual interface\"                                                                                                │\n",
+        "│    ],                                                                                                                        │\n",
+        "│    \"technical_highlights\": [                                                                                                 │\n",
+        "│      \"Use of basic graphics\"                                                                                                 │\n",
+        "│    ],                                                                                                                        │\n",
+        "│    \"recommendations\": [                                                                                                      │\n",
+        "│      \"Incorporate user feedback mechanisms\",                                                                                 │\n",
+        "│      \"Develop a more robust backend\",                                                                                        │\n",
+        "│      \"Enhance visual aesthetics\"                                                                                             │\n",
+        "│    ],                                                                                                                        │\n",
+        "│    \"market_potential\": \"Limited due to simplicity\",                                                                          │\n",
+        "│    \"scalability_assessment\": \"Low, requires significant development\"                                                         │\n",
+        "│  }                                                                                                                           │\n",
+        "│                                                                                                                              │\n",
+        "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+        "\"\"\"\n",
+        "print(output)\n"
+      ],
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "T-wYaKzkKGNK",
+        "outputId": "ebeaf7e3-6362-4d1c-f9d1-cc3504d733a2"
+      },
+      "id": "T-wYaKzkKGNK",
+      "execution_count": 2,
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "\n",
+            "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+            "│                                                                                                                              │\n",
+            "│  👤 Agent: HackathonJudge                                                                                                    │\n",
+            "│  Role: Technical Project Evaluator                                                                                           │\n",
+            "│                                                                                                                              │\n",
+            "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+            "\n",
+            "╭───────────────────────────────────────────────────── Generating... 6.6s ─────────────────────────────────────────────────────╮\n",
+            "│                                                                                                                              │\n",
+            "│  {                                                                                                                           │\n",
+            "│    \"innovation_score\": 30,                                                                                                   │\n",
+            "│    \"technical_complexity\": 20,                                                                                               │\n",
+            "│    \"presentation_quality\": 25,                                                                                               │\n",
+            "│    \"user_experience\": 35,                                                                                                    │\n",
+            "│    \"completeness\": 20,                                                                                                       │\n",
+            "│    \"overall_score\": 24,                                                                                                      │\n",
+            "│    \"key_strengths\": [                                                                                                        │\n",
+            "│      \"Simple concept\",                                                                                                       │\n",
+            "│      \"Clear visual representation\"                                                                                           │\n",
+            "│    ],                                                                                                                        │\n",
+            "│    \"areas_for_improvement\": [                                                                                                │\n",
+            "│      \"Enhance technical features\",                                                                                           │\n",
+            "│      \"Improve presentation clarity\",                                                                                         │\n",
+            "│      \"Add user interaction elements\"                                                                                         │\n",
+            "│    ],                                                                                                                        │\n",
+            "│    \"notable_features\": [                                                                                                     │\n",
+            "│      \"Basic visual interface\"                                                                                                │\n",
+            "│    ],                                                                                                                        │\n",
+            "│    \"technical_highlights\": [                                                                                                 │\n",
+            "│      \"Use of basic graphics\"                                                                                                 │\n",
+            "│    ],                                                                                                                        │\n",
+            "│    \"recommendations\": [                                                                                                      │\n",
+            "│      \"Incorporate user feedback mechanisms\",                                                                                 │\n",
+            "│      \"Develop a more robust backend\",                                                                                        │\n",
+            "│      \"Enhance visual aesthetics\"                                                                                             │\n",
+            "│    ],                                                                                                                        │\n",
+            "│    \"market_potential\": \"Limited due to simplicity\",                                                                          │\n",
+            "│    \"scalability_assessment\": \"Low, requires significant development\"                                                         │\n",
+            "│  }                                                                                                                           │\n",
+            "│                                                                                                                              │\n",
+            "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+            "\n"
+          ]
+        }
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.11"
+    },
+    "colab": {
+      "provenance": []
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

examples/cookbooks/Mistral_v0_3_Conversational_Demo.ipynb

@@ -0,0 +1,134 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "441900e0"
+      },
+      "source": [
+        "# 🧠 Mistral v0.3 (7B) Conversational Agent\n",
+        "A conceptual demo notebook to illustrate the workflow and output of the Mistral model, even if it doesn't run on Colab Free Tier."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "b4ba0b88"
+      },
+      "source": [
+        "## 📄 Description\n",
+        "This notebook showcases the typical flow of using Mistral v0.3 (7B) for conversational tasks. While the model is too large for Google Colab Free Tier, this version visually explains what the code would do.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Mistral_v0_3_Conversational_Demo.ipynb)\n"
+      ],
+      "metadata": {
+        "id": "yzXURvxIlIDD"
+      }
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# 📦 Dependencies"
+      ],
+      "metadata": {
+        "id": "IUQSTocQk7ml"
+      }
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "6f2afc57"
+      },
+      "outputs": [],
+      "source": [
+        "\n",
+        "!pip install transformers accelerate torch\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "9d5dad27"
+      },
+      "source": [
+        "## 🛠 Tools Used\n",
+        "- 🤗 Transformers: For loading the model and tokenizer.\n",
+        "- PyTorch: For model inference.\n",
+        "- Accelerate: To manage device placement (CPU/GPU).\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "cd936b40"
+      },
+      "source": [
+        "## 🧾 YAML Prompt Format (Conceptual)\n",
+        "```yaml\n",
+        "task: conversation\n",
+        "input: \"What's the capital of France?\"\n",
+        "history: []\n",
+        "temperature: 0.7\n",
+        "top_p: 0.9\n",
+        "```\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "8abaaa62"
+      },
+      "outputs": [],
+      "source": [
+        "# 🧠 Main Inference Logic (Illustrative)\n",
+        "from transformers import AutoModelForCausalLM, AutoTokenizer\n",
+        "import torch\n",
+        "\n",
+        "model_id = \"mistralai/Mistral-7B-Instruct-v0.3\"\n",
+        "tokenizer = AutoTokenizer.from_pretrained(model_id)\n",
+        "model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16, device_map=\"auto\")\n",
+        "\n",
+        "prompt = \"What's the capital of France?\"\n",
+        "inputs = tokenizer(prompt, return_tensors=\"pt\").to(model.device)\n",
+        "outputs = model.generate(**inputs, max_new_tokens=100)\n",
+        "response = tokenizer.decode(outputs[0], skip_special_tokens=True)\n",
+        "print(response)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "def486c6"
+      },
+      "source": [
+        "## 📤 Output (Example)\n",
+        "> \"The capital of France is Paris.\"\n",
+        "\n",
+        "![output](https://upload.wikimedia.org/wikipedia/commons/e/e6/Paris_Night.jpg)\n",
+        "\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "accelerator": "GPU",
+    "colab": {
+      "gpuType": "T4",
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

examples/cookbooks/Predictive_Maintenance_Multi_Agent_Workflow.ipynb

@@ -0,0 +1,401 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "l7oSysosTfJj"
+      },
+      "source": [
+        "# Predictive Maintenance Workflow using PraisonAIAgents\n",
+        "\n",
+        "This notebook demonstrates how to build a predictive maintenance workflow using multiple AI agents."
+      ],
+      "id": "l7oSysosTfJj"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Predictive_Maintenance_Multi-Agent_Workflow.ipynb)"
+      ],
+      "metadata": {
+        "id": "LH0_JjO7Y1G2"
+      },
+      "id": "LH0_JjO7Y1G2"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Dependencies"
+      ],
+      "metadata": {
+        "id": "ei-yNZSKXgtJ"
+      },
+      "id": "ei-yNZSKXgtJ"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "fnkuN8sTTfJq"
+      },
+      "outputs": [],
+      "source": [
+        "!pip install praisonaiagents"
+      ],
+      "id": "fnkuN8sTTfJq"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Set your OpenAI API key"
+      ],
+      "metadata": {
+        "id": "7PUSTQHwX5ia"
+      },
+      "id": "7PUSTQHwX5ia"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "metadata": {
+        "id": "33HivD-LTfJu"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "os.environ['OPENAI_API_KEY'] = 'enter your api key'"
+      ],
+      "id": "33HivD-LTfJu"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Import required modules"
+      ],
+      "metadata": {
+        "id": "D6we7t4nYESB"
+      },
+      "id": "D6we7t4nYESB"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "03z7Pi22TfJw"
+      },
+      "outputs": [],
+      "source": [
+        "from praisonaiagents import Agent, Task, PraisonAIAgents\n",
+        "import time\n",
+        "from typing import Dict, List\n",
+        "import asyncio"
+      ],
+      "id": "03z7Pi22TfJw"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Define helper functions"
+      ],
+      "metadata": {
+        "id": "TzZt0jbjYGgw"
+      },
+      "id": "TzZt0jbjYGgw"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "2oMzDsp3TfJw"
+      },
+      "outputs": [],
+      "source": [
+        "\n",
+        "def collect_sensor_data():\n",
+        "    return {\n",
+        "        \"temperature\": 75 + (int(time.time()) % 20),\n",
+        "        \"vibration\": 0.5 + (int(time.time()) % 10) / 10,\n",
+        "        \"pressure\": 100 + (int(time.time()) % 50),\n",
+        "        \"noise_level\": 60 + (int(time.time()) % 30)\n",
+        "    }\n",
+        "\n",
+        "def analyze_performance():\n",
+        "    return {\n",
+        "        \"efficiency\": 0.8 + (int(time.time()) % 20) / 100,\n",
+        "        \"uptime\": 0.95 + (int(time.time()) % 5) / 100,\n",
+        "        \"output_quality\": 0.9 + (int(time.time()) % 10) / 100\n",
+        "    }\n",
+        "\n",
+        "def detect_anomalies(sensor_data: Dict, performance: Dict):\n",
+        "    anomalies = []\n",
+        "    if sensor_data[\"temperature\"] > 90:\n",
+        "        anomalies.append({\"type\": \"temperature_high\", \"severity\": \"critical\"})\n",
+        "    if sensor_data[\"vibration\"] > 1.2:\n",
+        "        anomalies.append({\"type\": \"vibration_excess\", \"severity\": \"warning\"})\n",
+        "    if performance[\"efficiency\"] < 0.85:\n",
+        "        anomalies.append({\"type\": \"efficiency_low\", \"severity\": \"warning\"})\n",
+        "    return anomalies\n",
+        "\n",
+        "def predict_failures(anomalies: List[Dict]):\n",
+        "    predictions = []\n",
+        "    severity_scores = {\"critical\": 0.9, \"warning\": 0.6}\n",
+        "    for anomaly in anomalies:\n",
+        "        predictions.append({\n",
+        "            \"component\": anomaly[\"type\"].split(\"_\")[0],\n",
+        "            \"probability\": severity_scores[anomaly[\"severity\"]],\n",
+        "            \"timeframe\": \"24_hours\" if anomaly[\"severity\"] == \"critical\" else \"7_days\"\n",
+        "        })\n",
+        "    return predictions\n",
+        "\n",
+        "def schedule_maintenance(predictions: List[Dict]):\n",
+        "    schedule = []\n",
+        "    for pred in predictions:\n",
+        "        schedule.append({\n",
+        "            \"component\": pred[\"component\"],\n",
+        "            \"priority\": \"immediate\" if pred[\"timeframe\"] == \"24_hours\" else \"planned\",\n",
+        "            \"estimated_duration\": \"2_hours\",\n",
+        "            \"required_parts\": [\"replacement_\" + pred[\"component\"]]\n",
+        "        })\n",
+        "    return schedule"
+      ],
+      "id": "2oMzDsp3TfJw"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Define agents and tasks"
+      ],
+      "metadata": {
+        "id": "-7qMHyY5YIph"
+      },
+      "id": "-7qMHyY5YIph"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "4ZYbYzjNTfJy"
+      },
+      "outputs": [],
+      "source": [
+        "\n",
+        "sensor_monitor = Agent(\"Sensor Monitor\", \"Data Collection\", \"Collect sensor data\", \"Monitor and collect sensor readings\", [collect_sensor_data])\n",
+        "performance_analyzer = Agent(\"Performance Analyzer\", \"Performance Analysis\", \"Analyze equipment performance\", \"Analyze operational metrics\", [analyze_performance])\n",
+        "anomaly_detector = Agent(\"Anomaly Detector\", \"Anomaly Detection\", \"Detect operational anomalies\", \"Identify abnormal patterns\", [detect_anomalies])\n",
+        "failure_predictor = Agent(\"Failure Predictor\", \"Failure Prediction\", \"Predict potential failures\", \"Predict equipment failures\", [predict_failures])\n",
+        "maintenance_scheduler = Agent(\"Maintenance Scheduler\", \"Maintenance Planning\", \"Schedule maintenance activities\", \"Plan and schedule maintenance\", [schedule_maintenance])\n",
+        "\n",
+        "sensor_task = Task(\"collect_data\", \"Collect sensor data\", \"Sensor readings\", sensor_monitor, is_start=True, next_tasks=[\"analyze_performance\"], async_execution=True)\n",
+        "performance_task = Task(\"analyze_performance\", \"Analyze performance metrics\", \"Performance analysis\", performance_analyzer, next_tasks=[\"detect_anomalies\"], async_execution=True)\n",
+        "anomaly_task = Task(\"detect_anomalies\", \"Detect operational anomalies\", \"Detected anomalies\", anomaly_detector, next_tasks=[\"predict_failures\"], context=[sensor_task, performance_task])\n",
+        "prediction_task = Task(\"predict_failures\", \"Predict potential failures\", \"Failure predictions\", failure_predictor, next_tasks=[\"schedule_maintenance\"], task_type=\"decision\", condition={\"critical\": [\"schedule_maintenance\"], \"warning\": [\"schedule_maintenance\"], \"normal\": \"\"})\n",
+        "scheduling_task = Task(\"schedule_maintenance\", \"Schedule maintenance activities\", \"Maintenance schedule\", maintenance_scheduler, context=[prediction_task])"
+      ],
+      "id": "4ZYbYzjNTfJy"
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Create and run the workflow"
+      ],
+      "metadata": {
+        "id": "XOdIxJKiYKuD"
+      },
+      "id": "XOdIxJKiYKuD"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "KYu_YTVDTfJz"
+      },
+      "outputs": [],
+      "source": [
+        "\n",
+        "workflow = PraisonAIAgents(\n",
+        "    agents=[sensor_monitor, performance_analyzer, anomaly_detector, failure_predictor, maintenance_scheduler],\n",
+        "    tasks=[sensor_task, performance_task, anomaly_task, prediction_task, scheduling_task],\n",
+        "    process=\"workflow\",\n",
+        "    verbose=True\n",
+        ")\n",
+        "\n",
+        "async def main():\n",
+        "    print(\"\\nStarting Predictive Maintenance Workflow...\")\n",
+        "    print(\"=\" * 50)\n",
+        "    results = await workflow.astart()\n",
+        "    print(\"\\nMaintenance Planning Results:\")\n",
+        "    print(\"=\" * 50)\n",
+        "    for task_id, result in results[\"task_results\"].items():\n",
+        "        if result:\n",
+        "            print(f\"\\nTask: {task_id}\\nResult: {result.raw}\\n{'-'*50}\")\n",
+        "\n",
+        "await main()"
+      ],
+      "id": "KYu_YTVDTfJz"
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "print(\"\"\"\n",
+        "[Starting Predictive Maintenance Workflow...\n",
+        "==================================================\n",
+        "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+        "│                                                                                                                                              │\n",
+        "│  👤 Agent: Sensor Monitor                                                                                                                    │\n",
+        "│  Role: Data Collection                                                                                                                       │\n",
+        "│  Tools: collect_sensor_data                                                                                                                  │\n",
+        "│                                                                                                                                              │\n",
+        "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+        "\n",
+        "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+        "│                                                                                                                                              │\n",
+        "│  👤 Agent: Performance Analyzer                                                                                                              │\n",
+        "│  Role: Performance Analysis                                                                                                                  │\n",
+        "│  Tools: analyze_performance                                                                                                                  │\n",
+        "│                                                                                                                                              │\n",
+        "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+        "\n",
+        "[20:01:26] INFO     [20:01:26] process.py:429 INFO Task schedule_maintenance has no next tasks, ending workflow                   process.py:429\n",
+        "\n",
+        "Maintenance Planning Results:\n",
+        "==================================================\n",
+        "\n",
+        "Task: 0\n",
+        "Result: The sensor readings you have collected are as follows:\n",
+        "\n",
+        "- **Temperature**: 86°F\n",
+        "- **Vibration**: 0.6 (units not specified, but typically measured in g-forces or mm/s)\n",
+        "- **Pressure**: 101 (units not specified, but typically measured in kPa or psi)\n",
+        "- **Noise Level**: 81 dB\n",
+        "\n",
+        "Here's a brief analysis of these readings:\n",
+        "\n",
+        "1. **Temperature**: At 86°F, the temperature is relatively warm. Depending on the context (e.g., industrial equipment, environmental monitoring), this could be within normal operating conditions or might require cooling measures if it's above the optimal range.\n",
+        "\n",
+        "2. **Vibration**: A vibration level of 0.6 is generally low, but the significance depends on the type of equipment being monitored. For precision machinery, even small vibrations can be critical, whereas for more robust equipment, this might be negligible.\n",
+        "\n",
+        "3. **Pressure**: A pressure reading of 101 is often within normal ranges for many systems, but without specific units or context, it's hard to determine if this is optimal or requires adjustment.\n",
+        "\n",
+        "4. **Noise Level**: At 81 dB, the noise level is relatively high. Prolonged exposure to noise levels above 85 dB can be harmful to hearing, so if this is a workplace environment, it might be necessary to implement noise reduction measures or provide hearing protection.\n",
+        "\n",
+        "Overall, these readings should be compared against the specific operational thresholds and safety standards relevant to the equipment or environment being monitored. If any values are outside of acceptable ranges, further investigation or corrective actions may be needed.\n",
+        "--------------------------------------------------\n",
+        "\n",
+        "Task: 1\n",
+        "Result: Based on the provided operational metrics, here's an analysis of the equipment performance:\n",
+        "\n",
+        "1. **Efficiency (94%)**:\n",
+        "   - The equipment is operating at a high efficiency level, with 94% of the input being effectively converted into useful output. This suggests\n",
+        "that the equipment is well-maintained and optimized for performance. However, there is still a 6% margin for improvement, which could be addressed by identifying and minimizing any inefficiencies in the process.\n",
+        "\n",
+        "2. **Uptime (99%)**:\n",
+        "   - The equipment has an excellent uptime rate of 99%, indicating that it is available and operational almost all the time. This is a strong indicator of reliability and suggests that downtime due to maintenance or unexpected failures is minimal. Maintaining this level of uptime should\n",
+        "be a priority, as it directly impacts productivity and operational continuity.\n",
+        "\n",
+        "3. **Output Quality (94%)**:\n",
+        "   - The output quality is also at 94%, which is a positive sign that the equipment is producing high-quality products or results. However, similar to efficiency, there is room for improvement. Efforts could be made to identify any factors that might be affecting quality, such as calibration issues, material inconsistencies, or process deviations.\n",
+        "\n",
+        "**Overall Assessment**:\n",
+        "The equipment is performing well across all key metrics, with high efficiency, uptime, and output quality. To further enhance performance, focus should be placed on fine-tuning processes to close the small gaps in efficiency and quality. Regular maintenance, monitoring, and process optimization can help sustain and potentially improve these metrics.\n",
+        "--------------------------------------------------]\n",
+        "\"\"\")"
+      ],
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "4hrEJ5S6XpJ7",
+        "outputId": "899e677d-19d5-4e0a-d9ab-ebc945aeee1b"
+      },
+      "id": "4hrEJ5S6XpJ7",
+      "execution_count": 4,
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "\n",
+            "[Starting Predictive Maintenance Workflow...\n",
+            "==================================================\n",
+            "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+            "│                                                                                                                                              │\n",
+            "│  👤 Agent: Sensor Monitor                                                                                                                    │\n",
+            "│  Role: Data Collection                                                                                                                       │\n",
+            "│  Tools: collect_sensor_data                                                                                                                  │\n",
+            "│                                                                                                                                              │\n",
+            "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+            "\n",
+            "╭─ Agent Info ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
+            "│                                                                                                                                              │\n",
+            "│  👤 Agent: Performance Analyzer                                                                                                              │\n",
+            "│  Role: Performance Analysis                                                                                                                  │\n",
+            "│  Tools: analyze_performance                                                                                                                  │\n",
+            "│                                                                                                                                              │\n",
+            "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
+            "\n",
+            "[20:01:26] INFO     [20:01:26] process.py:429 INFO Task schedule_maintenance has no next tasks, ending workflow                   process.py:429\n",
+            "\n",
+            "Maintenance Planning Results:\n",
+            "==================================================\n",
+            "\n",
+            "Task: 0\n",
+            "Result: The sensor readings you have collected are as follows:\n",
+            "\n",
+            "- **Temperature**: 86°F\n",
+            "- **Vibration**: 0.6 (units not specified, but typically measured in g-forces or mm/s)\n",
+            "- **Pressure**: 101 (units not specified, but typically measured in kPa or psi)\n",
+            "- **Noise Level**: 81 dB\n",
+            "\n",
+            "Here's a brief analysis of these readings:\n",
+            "\n",
+            "1. **Temperature**: At 86°F, the temperature is relatively warm. Depending on the context (e.g., industrial equipment, environmental monitoring), this could be within normal operating conditions or might require cooling measures if it's above the optimal range.\n",
+            "\n",
+            "2. **Vibration**: A vibration level of 0.6 is generally low, but the significance depends on the type of equipment being monitored. For precision machinery, even small vibrations can be critical, whereas for more robust equipment, this might be negligible.\n",
+            "\n",
+            "3. **Pressure**: A pressure reading of 101 is often within normal ranges for many systems, but without specific units or context, it's hard to determine if this is optimal or requires adjustment.\n",
+            "\n",
+            "4. **Noise Level**: At 81 dB, the noise level is relatively high. Prolonged exposure to noise levels above 85 dB can be harmful to hearing, so if this is a workplace environment, it might be necessary to implement noise reduction measures or provide hearing protection.\n",
+            "\n",
+            "Overall, these readings should be compared against the specific operational thresholds and safety standards relevant to the equipment or environment being monitored. If any values are outside of acceptable ranges, further investigation or corrective actions may be needed.\n",
+            "--------------------------------------------------\n",
+            "\n",
+            "Task: 1\n",
+            "Result: Based on the provided operational metrics, here's an analysis of the equipment performance:\n",
+            "\n",
+            "1. **Efficiency (94%)**:\n",
+            "   - The equipment is operating at a high efficiency level, with 94% of the input being effectively converted into useful output. This suggests \n",
+            "that the equipment is well-maintained and optimized for performance. However, there is still a 6% margin for improvement, which could be addressed by identifying and minimizing any inefficiencies in the process.\n",
+            "\n",
+            "2. **Uptime (99%)**:\n",
+            "   - The equipment has an excellent uptime rate of 99%, indicating that it is available and operational almost all the time. This is a strong indicator of reliability and suggests that downtime due to maintenance or unexpected failures is minimal. Maintaining this level of uptime should \n",
+            "be a priority, as it directly impacts productivity and operational continuity.\n",
+            "\n",
+            "3. **Output Quality (94%)**:\n",
+            "   - The output quality is also at 94%, which is a positive sign that the equipment is producing high-quality products or results. However, similar to efficiency, there is room for improvement. Efforts could be made to identify any factors that might be affecting quality, such as calibration issues, material inconsistencies, or process deviations.\n",
+            "\n",
+            "**Overall Assessment**:\n",
+            "The equipment is performing well across all key metrics, with high efficiency, uptime, and output quality. To further enhance performance, focus should be placed on fine-tuning processes to close the small gaps in efficiency and quality. Regular maintenance, monitoring, and process optimization can help sustain and potentially improve these metrics.\n",
+            "--------------------------------------------------]\n",
+            "\n"
+          ]
+        }
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.9"
+    },
+    "colab": {
+      "provenance": []
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

examples/cookbooks/Qwen2_5_InstructionAgent.ipynb

@@ -0,0 +1,420 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "MLutIRWTYLqq",
+   "metadata": {
+    "id": "MLutIRWTYLqq"
+   },
+   "source": [
+    "# Simple Chat with Qwen2.5 (0.5B) using Hugging Face Transformers"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a2LoeTPnYQOW",
+   "metadata": {
+    "id": "a2LoeTPnYQOW"
+   },
+   "source": [
+    "This beginner-friendly notebook demonstrates how to use the Qwen2.5-0.5B-Instruct model for simple chat-based generation. It includes installing dependencies, setting up authentication via Hugging Face token, generating a response using a chat prompt, and displaying the output. The notebook is organized into 5 clean sections for easy understanding."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "WlfJBFucY9gi",
+   "metadata": {
+    "id": "WlfJBFucY9gi"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/Qwen2_5_InstructionAgent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "57059c85",
+   "metadata": {
+    "id": "57059c85"
+   },
+   "source": [
+    "# 🔧 Dependencies\n",
+    "Install necessary Python packages."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "1cdaae47",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "1cdaae47",
+    "outputId": "5b140b09-5c16-4849-f370-f8b5abcc127a"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m363.4/363.4 MB\u001b[0m \u001b[31m3.5 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m13.8/13.8 MB\u001b[0m \u001b[31m58.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m24.6/24.6 MB\u001b[0m \u001b[31m58.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m883.7/883.7 kB\u001b[0m \u001b[31m39.0 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m664.8/664.8 MB\u001b[0m \u001b[31m1.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m211.5/211.5 MB\u001b[0m \u001b[31m6.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m56.3/56.3 MB\u001b[0m \u001b[31m14.8 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m127.9/127.9 MB\u001b[0m \u001b[31m9.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m207.5/207.5 MB\u001b[0m \u001b[31m6.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m21.1/21.1 MB\u001b[0m \u001b[31m64.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[?25h"
+     ]
+    }
+   ],
+   "source": [
+    "!pip install transformers --quiet\n",
+    "!pip install accelerate --quiet\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9a65a2fa",
+   "metadata": {
+    "id": "9a65a2fa"
+   },
+   "source": [
+    "# 🛠️ Tools\n",
+    "Import required tools and libraries."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "a8a4bc30",
+   "metadata": {
+    "id": "a8a4bc30"
+   },
+   "outputs": [],
+   "source": [
+    "from transformers import AutoModelForCausalLM, AutoTokenizer\n",
+    "import torch\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1ad2bec4",
+   "metadata": {
+    "id": "1ad2bec4"
+   },
+   "source": [
+    "# ⚙️ YAML Prompt (Token Authentication)\n",
+    "Use Hugging Face token to access the model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "cd030b94",
+   "metadata": {
+    "id": "cd030b94"
+   },
+   "outputs": [],
+   "source": [
+    "from huggingface_hub import login\n",
+    "login(token=\"Enter your huggingface token\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b7b1a32d",
+   "metadata": {
+    "id": "b7b1a32d"
+   },
+   "source": [
+    "# 🚀 Main\n",
+    "Load model, prepare prompt and generate response."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "ef73b9ea",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 365,
+     "referenced_widgets": [
+      "a175e2b1fa8c4733afe1ddc78095be58",
+      "f5aaf63d7be04927a33e5cdd3655a003",
+      "7af74b8c184b4e72a2dba769b9caa40f",
+      "22b1c604d91648479cf01198db25a863",
+      "faaeb1c3ab914a6db9ff9b8ea06a440f",
+      "138860a12c6347fba11437eb098d31b5",
+      "d2f5fe459d544fa6adc92debab823ee6",
+      "468e8e7bee5c4198b121ac1aa677153d",
+      "068991c9ac44496bab06ccaa7d030722",
+      "44436151662f41ef81f6a4005add51de",
+      "c774c78c4fce4825872a76bb1e5fde33",
+      "4a7d0a84994c4b628974f631ecb95425",
+      "4adb654ea143456eb3b4244c3030b39f",
+      "d8dbdbc9327f4799a07767b59db59c47",
+      "669ea95c4cb642b580aa176ae2e89f9f",
+      "0bc8529b03364f83adf1110b5c1378ec",
+      "2eb8007145ef4c3caf7f5a9d1fd299e3",
+      "3fa4c368cea4474e8b97a215a20fd8d8",
+      "c750b36cfda24e24ae44a615e426de4b",
+      "e3001e1e3ba74c7ba28702fa5b2a6ed8",
+      "7ac0f7770ad341f68f194705f59ccb27",
+      "f9140e1979c6412993eee36c3f79c0d9",
+      "1ad8e2e2200c4277ba10dd8e9ac83b90",
+      "f193e4fb00b64e86b6f40f10f514739d",
+      "ae3aa36b649a43eb928ed843d2cfc239",
+      "c346fba7badb4c4596f6d6e8fa62224b",
+      "39dd29002d7b46848a29dfeb7405d9f9",
+      "166e17a0be5a4aa8831101eeb07a8645",
+      "60f9503b404945a3b99b5207190474f5",
+      "c480a676b82b48a0aae3dc438fa02ba8",
+      "d97b7d0765e84926b974b2c19156ae20",
+      "b22ca5c038f7419aa8e03f5f9a54accc",
+      "0387fba7ed044fbfb2a78c8d593c7b38",
+      "d6a31c3cf026450088596db5917c3e4a",
+      "4948c0014a95413b81848ae2b4a5fe7e",
+      "377cbca7363a495ea131a1e49a702168",
+      "a5eaad3284034beab09d212765d7ff78",
+      "7ed393b7c7564ab1897446eba875a4da",
+      "66d773bc8c7a40bc95dcba35052675cb",
+      "ad196b0deb2144b083cf8fddcbcfd147",
+      "09a99df922154a528f327bba0a47cb9a",
+      "bc9918e686244eb5b5db78932600a9d6",
+      "4fef54176f4b4a2d8d543a4bf04b416a",
+      "48551fb8dd5140cbb2d792e72b5fbb0d",
+      "955225e4206a4ee5a4284579935db920",
+      "e2faef80a0034c5384daf8ba66c1b75d",
+      "f27c3ec92bc74bacb3f86672b689370a",
+      "ec03dfb79a26474e812606b2664c931b",
+      "4705d2f502a74c3bb8eb8a06c3ba6889",
+      "7d8c99f622c34229894024c9772aed84",
+      "1e6e892b153c4c05b7de806ec674215f",
+      "85ac6a67bb0944b5bb8713fcf302da45",
+      "796771b887ce49119307725382f73bfd",
+      "c686586c431f4c22b0f0c698a9b213b6",
+      "239180fd12624e3a90188270b55ee218",
+      "e04653090c7e454d9c5e520e7f313588",
+      "992c7a4b44aa4feb8e13714fa922d705",
+      "a0a238c78d2842d680be448a2cb20157",
+      "6ab5ebed63674b5e87327a1623eba7f0",
+      "a49887aa0fcd4b91a0d5d978b29c1e0a",
+      "d9b2e4142dd14264b90829a5a4116613",
+      "154b27bb2ba44d10bde5c96929b65cc9",
+      "f0bf6206c31f49f2ad1ce97b99963011",
+      "1762735cfbcf4706b1c0686d3c2926a0",
+      "d5e3440785794f0f9ad4fd0650c2f682",
+      "08019bdd70364fabbc222dca66db0bb1",
+      "6f0b3a92d47c42dd815a670bb1c0f42c",
+      "54554545ad5a4f39b649f3acff6d5cba",
+      "bfd8f4ee8c414349a3695975e79c332e",
+      "332fc944eef14a9c82f71a68a3857dea",
+      "3b0b899fcfae451ba8ec3d8da176fcec",
+      "8383df3f07bd427287ad05726737cc67",
+      "67c267d7d1ec424593775bf8129e8ac9",
+      "85a50e2cb406403988639e6d6ecf9dc1",
+      "7251ed20382c4a60bae8549f68971043",
+      "44fbc377fd6a4c5a910c00dcceb143af",
+      "2d6d273941f04c13af598c53e067aae7"
+     ]
+    },
+    "id": "ef73b9ea",
+    "outputId": "34512fa7-527c-45cb-f3c7-b42d37e74980"
+   },
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/usr/local/lib/python3.11/dist-packages/huggingface_hub/utils/_auth.py:94: UserWarning: \n",
+      "The secret `HF_TOKEN` does not exist in your Colab secrets.\n",
+      "To authenticate with the Hugging Face Hub, create a token in your settings tab (https://huggingface.co/settings/tokens), set it as secret in your Google Colab and restart your session.\n",
+      "You will be able to reuse this secret in all of your notebooks.\n",
+      "Please note that authentication is recommended but still optional to access public models or datasets.\n",
+      "  warnings.warn(\n"
+     ]
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "a175e2b1fa8c4733afe1ddc78095be58",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer_config.json:   0%|          | 0.00/7.30k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "4a7d0a84994c4b628974f631ecb95425",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "vocab.json:   0%|          | 0.00/2.78M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "1ad8e2e2200c4277ba10dd8e9ac83b90",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "merges.txt:   0%|          | 0.00/1.67M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "d6a31c3cf026450088596db5917c3e4a",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer.json:   0%|          | 0.00/7.03M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "955225e4206a4ee5a4284579935db920",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "config.json:   0%|          | 0.00/659 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "e04653090c7e454d9c5e520e7f313588",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "model.safetensors:   0%|          | 0.00/988M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "6f0b3a92d47c42dd815a670bb1c0f42c",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "generation_config.json:   0%|          | 0.00/242 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "model_name = \"Qwen/Qwen2.5-0.5B-Instruct\"\n",
+    "\n",
+    "tokenizer = AutoTokenizer.from_pretrained(model_name)\n",
+    "model = AutoModelForCausalLM.from_pretrained(\n",
+    "    model_name,\n",
+    "    torch_dtype=\"auto\",\n",
+    "    device_map=\"auto\"\n",
+    ")\n",
+    "\n",
+    "messages = [\n",
+    "    {\"role\": \"system\", \"content\": \"You are Qwen, a helpful assistant.\"},\n",
+    "    {\"role\": \"user\", \"content\": \"Explain photosynthesis in simple words.\"}\n",
+    "]\n",
+    "\n",
+    "text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)\n",
+    "inputs = tokenizer(text, return_tensors=\"pt\").to(model.device)\n",
+    "\n",
+    "outputs = model.generate(**inputs, max_new_tokens=100)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bf70c765",
+   "metadata": {
+    "id": "bf70c765"
+   },
+   "source": [
+    "# 📤 Output\n",
+    "Print the model response."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "d8f70a7b",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "d8f70a7b",
+    "outputId": "559e9358-c2b7-4410-c1a6-1624640dfeae"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "system\n",
+      "You are Qwen, a helpful assistant.\n",
+      "user\n",
+      "Explain photosynthesis in simple words.\n",
+      "assistant\n",
+      "Photosynthesis is the process by which plants, algae, and some bacteria convert light energy from the sun into chemical energy stored in glucose molecules, using carbon dioxide and water as reactants. This process occurs in chloroplasts within plant cells and involves two main stages: the light-dependent reactions and the light-independent reactions (also known as the Calvin cycle).\n",
+      "\n",
+      "In the light-dependent reactions, light energy is captured by pigments like chlorophyll, causing electrons to be excited and transferred to oxygen through a series\n"
+     ]
+    }
+   ],
+   "source": [
+    "response = tokenizer.decode(outputs[0], skip_special_tokens=True)\n",
+    "print(response)\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/cookbooks/TinyLlama_1_1B_model_SimpleAIAgent.ipynb

@@ -0,0 +1,364 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "3622c575",
+   "metadata": {
+    "id": "3622c575"
+   },
+   "source": [
+    "# TinyLlama Agent Demo\n",
+    "\n",
+    "This notebook demonstrates how to create a simple AI agent using the TinyLlama (1.1B) model.\n",
+    "\n",
+    "**Requirements:**\n",
+    "- `transformers`\n",
+    "- `accelerate`\n",
+    "- `torch`\n",
+    "\n",
+    "We will load the model, prepare a basic conversational interface, and test it with a simple prompt."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qS0M9pRhTGpf",
+   "metadata": {
+    "id": "qS0M9pRhTGpf"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DhivyaBharathy-web/PraisonAI/blob/main/examples/cookbooks/TinyLlama_1_1B_model_SimpleAIAgent.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "tuw0IDpBS0ei",
+   "metadata": {
+    "id": "tuw0IDpBS0ei"
+   },
+   "source": [
+    "# Install necessary packages"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "0d06cae9",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "0d06cae9",
+    "outputId": "3e1d8fb7-19be-455b-dc35-d0ab19146669"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m363.4/363.4 MB\u001b[0m \u001b[31m3.4 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m13.8/13.8 MB\u001b[0m \u001b[31m29.8 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m24.6/24.6 MB\u001b[0m \u001b[31m29.0 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m883.7/883.7 kB\u001b[0m \u001b[31m20.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m664.8/664.8 MB\u001b[0m \u001b[31m2.8 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m211.5/211.5 MB\u001b[0m \u001b[31m5.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m56.3/56.3 MB\u001b[0m \u001b[31m12.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m127.9/127.9 MB\u001b[0m \u001b[31m7.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m207.5/207.5 MB\u001b[0m \u001b[31m6.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m21.1/21.1 MB\u001b[0m \u001b[31m45.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
+      "\u001b[?25h"
+     ]
+    }
+   ],
+   "source": [
+    "!pip install -q transformers accelerate torch"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "RFhYLkO1S5F9",
+   "metadata": {
+    "id": "RFhYLkO1S5F9"
+   },
+   "source": [
+    "# Load TinyLlama model and tokenizer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "415af398",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 241,
+     "referenced_widgets": [
+      "dae7d635257948149c74e65956f614e3",
+      "17ec6fcc9f624cdbb62fe2b8b55230d0",
+      "58474504488044138a0252bb75258d86",
+      "04fe4518fac04b9f8b29c62ed70f1dfd",
+      "c6a9d3ea25594170977243d2048d3408",
+      "730bebf00be142d3979c6d12b55d6757",
+      "03ad1674c0884e7b9c4a21af0a1e66c3",
+      "ebac47c887f04b79a60bd0918002bf0d",
+      "ece9bce5d2ca4dd7b019040175513118",
+      "458f11dbadb045f1aa8c72780e7aa2a0",
+      "ec28a20d0a14445489723684d2d69c0a",
+      "d347fa0c0fc849559b66c8f116c86317",
+      "117f649fa62b4f5d9add0160e6cd80a4",
+      "66f702418fa348eea27778282dc443aa",
+      "44413339df5b4ae688f8101faf9ed3b5",
+      "00cc576df95441c8916ce38a7c6decc2",
+      "22e9ea6d191841bf9a5a5072326aa6d8",
+      "bd94a291b3164113b5ea460b38b8c167",
+      "9d132a297f924a3d867605df81e70d8e",
+      "5345feddca204db784ea0452e739eda6",
+      "ace33e6e88d842c89efd180b3a83f674",
+      "61dd85a7edf544f196c60a259a91fa0d",
+      "7451ec9bd091441c852d075b47bd1ca5",
+      "05e3446e7c9243819a25d1ca8e8fa38e",
+      "73141c4c9218462da97999d3afa459bc",
+      "1cffc33252b94fbc861edb0953f13153",
+      "de917c0fc49040c8a9254333c34c884a",
+      "50962ececc0b42c28170eb0c23fd6171",
+      "856cc834a33a4f9fb59c77f748006b36",
+      "17fd1d476c1f4891b8cbeb8cacdeb866",
+      "c97dc50f42cb44b8a71aeff5272d5337",
+      "2e3a66f622d445c4be544a9306798cb6",
+      "92920b1d428a4ed68a9e0329e2034cad",
+      "7e282c1fcae842cc87c93ecfc1763654",
+      "f9ed70f887204e2fb336e38a35096eec",
+      "a4d99f9beca44e4a8fadff65b27aa78f",
+      "b4f77b96d00445eea77ac78baa8c1e99",
+      "695898e4a4c8476cb318446a6da592ba",
+      "d70bcacbe77c41f685a4f8020f767889",
+      "af49afc49ecf47fb9ebf2d299954eff2",
+      "1bd2a253348f4b45928c875940f72481",
+      "b6c5f55fc85b4331a2e749d27ce15f89",
+      "81a87638c71046d7aeb1c642558602f7",
+      "e750883103444391bd64872344c651d7",
+      "e78dca0cf1314d01a5d5126e448e9d87",
+      "d0c53dffc0c34d7090febf78231972b2",
+      "152a118177914c6692e7ee4987b92b9b",
+      "88fd71fd6dbf43ebb0a3b8471fd35f8d",
+      "ddb91266f8834e4eaaf136cc15f4a831",
+      "9f8179d135054eb292c9adc7fd66a91a",
+      "297d5bc8b3a04f26b80e2cc5ee3f7bbd",
+      "f49f72679cb944cd8fce5557bbd68b1b",
+      "2ee28c8ef4f74690b80a89050da4ebb5",
+      "c29924d6561a4feaa9238d1b34394941",
+      "03636146b7c14f5db80b8f105be55303",
+      "b391081de4444859ac3213aac99cc33a",
+      "2babb83499fc46dc8422473f7b98403c",
+      "a32f6cc2777941bca5b6250e36624ead",
+      "90cd9996184a452ab651f9b8cc590f47",
+      "dc04209c92764096ba9bd4aefa81c189",
+      "16e5b93c3c964a8a8ca460d9077d0638",
+      "794f22ded07d46c5a916325109618987",
+      "dce367f1a5a74ebf94aea37209aa0a40",
+      "5e355e3f340f4a7590e4a88d44b03383",
+      "4e725e19c877462aa3c10726a335bbde",
+      "d60ab6c255d244098a459459016a2089",
+      "f1b07183320d42af88f985bd1abf054f",
+      "d23103bb4b354e29a2c3e7dc93867b36",
+      "ea3e0ae0aef54e5da113c9686ebbbab9",
+      "4d3365c1bb7740dc8f36f4b419af135a",
+      "c06ccbc051264027bd2c6521fec69abe",
+      "597dbf5b28134cc0bf9d613443243455",
+      "faa4f285eb224bbcbed649bd479e571f",
+      "6e684d35885a4706b8add6834cd521ad",
+      "f9c55ada3386460183e02559defec8a4",
+      "9d64cbe1605f4f358923754c5f8b6424",
+      "6008ed7eca09485195eb37c36acfbe79"
+     ]
+    },
+    "id": "415af398",
+    "outputId": "28de1886-e83f-49bf-b05f-cd19439605c5"
+   },
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "dae7d635257948149c74e65956f614e3",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer_config.json:   0%|          | 0.00/1.29k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "d347fa0c0fc849559b66c8f116c86317",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer.model:   0%|          | 0.00/500k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "7451ec9bd091441c852d075b47bd1ca5",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "tokenizer.json:   0%|          | 0.00/1.84M [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "7e282c1fcae842cc87c93ecfc1763654",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "special_tokens_map.json:   0%|          | 0.00/551 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "e78dca0cf1314d01a5d5126e448e9d87",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "config.json:   0%|          | 0.00/608 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "b391081de4444859ac3213aac99cc33a",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "model.safetensors:   0%|          | 0.00/2.20G [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "f1b07183320d42af88f985bd1abf054f",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "generation_config.json:   0%|          | 0.00/124 [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from transformers import AutoTokenizer, AutoModelForCausalLM\n",
+    "import torch\n",
+    "\n",
+    "model_name = \"TinyLlama/TinyLlama-1.1B-Chat-v1.0\"\n",
+    "tokenizer = AutoTokenizer.from_pretrained(model_name)\n",
+    "model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.float16, device_map=\"auto\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "N0bRTd_DS8aL",
+   "metadata": {
+    "id": "N0bRTd_DS8aL"
+   },
+   "source": [
+    "# Define a function to generate responses from the agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "1b0483e1",
+   "metadata": {
+    "id": "1b0483e1"
+   },
+   "outputs": [],
+   "source": [
+    "def generate_response(prompt, max_length=256):\n",
+    "    inputs = tokenizer(prompt, return_tensors=\"pt\").to(model.device)\n",
+    "    outputs = model.generate(**inputs, max_new_tokens=max_length)\n",
+    "    return tokenizer.decode(outputs[0], skip_special_tokens=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "vbHKNxc-S_Bk",
+   "metadata": {
+    "id": "vbHKNxc-S_Bk"
+   },
+   "source": [
+    "# Example usage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "298c9811",
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "298c9811",
+    "outputId": "6e412608-735c-4604-8a5d-a66b98dd9df0"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "You are a helpful assistant. What is the capital of France?\n"
+     ]
+    }
+   ],
+   "source": [
+    "prompt = \"You are a helpful assistant. What is the capital of France?\"\n",
+    "response = generate_response(prompt)\n",
+    "print(response)"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/python/remote/README.md

@@ -0,0 +1,170 @@
+# Remote Agent Connectivity
+
+This directory contains examples demonstrating PraisonAI's remote agent connectivity feature, which allows you to connect to agents running on different servers, similar to Google ADK's agent connectivity pattern.
+
+## Overview
+
+The remote agent connectivity feature enables:
+- **Direct agent-to-agent connectivity** across networks
+- **Session-based communication** with remote agents  
+- **Google ADK-like API patterns** for familiar usage
+- **Automatic connection management** and error handling
+
+## Quick Start
+
+### 1. Start a Remote Agent Server
+
+```bash
+# Start a simple remote agent server
+python remote_agent_server.py
+
+# Or start multiple agents on one server
+python remote_agent_server.py --multiple
+```
+
+### 2. Connect from Client
+
+```python
+from praisonaiagents import Session
+
+# Connect to remote agent (similar to Google ADK)
+session = Session(agent_url="192.168.1.10:8000/agent")
+
+# Send messages to the remote agent
+response = session.chat("Hello from the client!")
+print(response)
+
+# Alternative method (Google ADK pattern)  
+response = session.send_message("What can you help me with?")
+print(response)
+```
+
+## Examples
+
+- **`remote_agent_server.py`** - Set up agents as remote servers
+- **`remote_agent_example.py`** - Connect to and communicate with remote agents
+
+## API Comparison
+
+### Google ADK Pattern
+```python
+from adk.agent import Agent
+from adk.session import Session
+
+session = Session(agent_url="192.168.1.10:8000")
+response = session.send_message("Hello!")
+```
+
+### PraisonAI Pattern  
+```python
+from praisonaiagents import Session
+
+session = Session(agent_url="192.168.1.10:8000/agent")
+response = session.chat("Hello!")
+# OR
+response = session.send_message("Hello!")  # Google ADK compatibility
+```
+
+## Key Features
+
+### ✅ **Seamless Connectivity**
+- Automatic protocol detection (http/https)
+- Connection testing and validation
+- Configurable timeouts
+
+### ✅ **Error Handling**
+- Clear error messages for connection issues
+- Graceful handling of network problems
+- Appropriate fallbacks for unavailable services
+
+### ✅ **Backward Compatibility**
+- Existing local agent functionality unchanged
+- Session API works for both local and remote scenarios
+- No breaking changes to current code
+
+### ✅ **Flexible Configuration**
+- Support for IP:port format (`192.168.1.10:8000`)
+- Full URL format (`http://server.com:8000/agent`)
+- Customizable endpoints and paths
+
+## Usage Patterns
+
+### Single Remote Agent
+```python
+# Connect to a specific remote agent
+session = Session(agent_url="192.168.1.10:8000/agent")
+response = session.chat("Hello from remote client!")
+```
+
+### Multiple Remote Agents
+```python
+# Connect to different specialized agents
+research_session = Session(agent_url="192.168.1.10:8000/research")
+coding_session = Session(agent_url="192.168.1.10:8000/coding")
+
+research_response = research_session.chat("Find info about AI trends")
+coding_response = coding_session.chat("Help me debug this Python code")
+```
+
+### Error Handling
+```python
+try:
+    session = Session(agent_url="192.168.1.10:8000/agent")
+    response = session.chat("Test message")
+    print(f"Response: {response}")
+except ConnectionError as e:
+    print(f"Failed to connect: {e}")
+```
+
+## Network Configuration
+
+### Server Setup
+```python
+# Create and launch agent server
+agent = Agent(name="RemoteAgent", role="Assistant")
+agent.launch(path="/agent", port=8000, host="0.0.0.0")
+```
+
+### Client Connection
+```python
+# Connect from any network location
+session = Session(agent_url="<server-ip>:8000/agent")
+```
+
+## Limitations for Remote Sessions
+
+When using remote agent sessions, certain local operations are not available:
+- **Memory operations** (`session.memory.*`)
+- **Knowledge operations** (`session.knowledge.*`) 
+- **Local agent creation** (`session.Agent(...)`)
+- **State management** (`session.save_state/restore_state`)
+
+This design keeps remote and local operations clearly separated.
+
+## Testing
+
+Run the examples to test the functionality:
+
+```bash
+# Terminal 1: Start server
+python remote_agent_server.py
+
+# Terminal 2: Test client (update IP as needed)
+python remote_agent_example.py
+```
+
+## Integration with Existing Code
+
+The remote connectivity feature integrates seamlessly with existing PraisonAI code:
+
+```python
+# Existing local code works unchanged
+local_session = Session(session_id="local_chat")
+local_agent = local_session.Agent(name="LocalAgent", role="Assistant")
+
+# New remote connectivity
+remote_session = Session(agent_url="remote-server:8000/agent")
+remote_response = remote_session.chat("Hello from remote!")
+```
+
+This provides a smooth migration path for applications that need to scale across multiple servers.

examples/python/remote/remote_agent_example.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+Remote Agent Connectivity Example
+
+This example demonstrates how to connect to agents running on remote servers,
+similar to Google ADK's agent connectivity pattern.
+
+Usage:
+1. First, start a remote agent server:
+   python remote_agent_server.py
+
+2. Then run this client to connect to it:
+   python remote_agent_example.py
+"""
+
+from praisonaiagents import Session
+import time
+
+def example_remote_agent_connection():
+    """
+    Example demonstrating remote agent connectivity similar to Google ADK.
+    """
+    print("🌐 Remote Agent Connectivity Example")
+    print("=" * 50)
+    
+    # Example 1: Connect to remote agent using IP:port format
+    try:
+        print("\n1. Connecting to remote agent at 192.168.1.10:8000...")
+        
+        # Create a session with remote agent URL (similar to Google ADK)
+        session = Session(agent_url="192.168.1.10:8000/agent")
+        
+        print(f"✅ Connected! Session: {session}")
+        
+        # Send a message to the remote agent
+        response = session.chat("Hello from the client!")
+        print(f"📨 Sent: 'Hello from the client!'")
+        print(f"📨 Received: {response}")
+        
+        # Send another message using the alias method (Google ADK pattern)
+        response = session.send_message("What can you help me with?")
+        print(f"📨 Sent: 'What can you help me with?'")
+        print(f"📨 Received: {response}")
+        
+    except ConnectionError as e:
+        print(f"❌ Connection failed: {e}")
+        print("💡 Make sure the remote agent server is running at 192.168.1.10:8000")
+    
+    # Example 2: Connect to localhost for testing
+    try:
+        print("\n2. Connecting to localhost for testing...")
+        
+        # Connect to local server (for testing)
+        session = Session(agent_url="localhost:8000/agent")
+        
+        print(f"✅ Connected! Session: {session}")
+        
+        # Test the connection
+        response = session.chat("Test message")
+        print(f"📨 Response: {response}")
+        
+    except ConnectionError as e:
+        print(f"❌ Connection failed: {e}")
+        print("💡 Start a local agent server first with: python remote_agent_server.py")
+
+def example_error_handling():
+    """
+    Example demonstrating error handling for remote sessions.
+    """
+    print("\n\n🚨 Error Handling Examples")
+    print("=" * 50)
+    
+    try:
+        # Create a remote session
+        session = Session(agent_url="localhost:8000/agent")
+        
+        # These operations are not available for remote sessions
+        print("\n❌ Attempting to access memory (should fail)...")
+        session.memory.store_short_term("test")
+        
+    except ConnectionError:
+        print("⚠️  Cannot connect to remote agent (expected if server not running)")
+    except ValueError as e:
+        print(f"✅ Correctly caught error: {e}")
+    
+    try:
+        session = Session(agent_url="localhost:8000/agent")
+        print("\n❌ Attempting to create local agent (should fail)...")
+        agent = session.Agent(name="Test", role="Assistant")
+        
+    except ConnectionError:
+        print("⚠️  Cannot connect to remote agent (expected if server not running)")
+    except ValueError as e:
+        print(f"✅ Correctly caught error: {e}")
+
+def comparison_with_google_adk():
+    """
+    Shows the comparison between Google ADK and PraisonAI patterns.
+    """
+    print("\n\n🔄 Comparison with Google ADK")
+    print("=" * 50)
+    
+    print("\n📋 Google ADK Pattern:")
+    print("""
+    from adk.agent import Agent
+    from adk.session import Session
+
+    # Connect to remote agent
+    session = Session(agent_url="192.168.1.10:8000")
+    response = session.send_message("Hello from client!")
+    """)
+    
+    print("📋 PraisonAI Pattern:")
+    print("""
+    from praisonaiagents import Session
+
+    # Connect to remote agent
+    session = Session(agent_url="192.168.1.10:8000/agent")
+    response = session.chat("Hello from client!")
+    # OR
+    response = session.send_message("Hello from client!")
+    """)
+    
+    print("✨ Key similarities:")
+    print("• Direct agent URL connectivity")
+    print("• Simple session-based API")
+    print("• Similar message sending patterns")
+    print("• Error handling for connection issues")
+
+if __name__ == "__main__":
+    example_remote_agent_connection()
+    example_error_handling()
+    comparison_with_google_adk()
+    
+    print("\n\n🎯 Summary")
+    print("=" * 50)
+    print("✅ Remote agent connectivity implemented")
+    print("✅ Google ADK-like API pattern supported")  
+    print("✅ Backward compatibility maintained")
+    print("✅ Proper error handling for remote sessions")
+    print("\n💡 To test with a real server, run remote_agent_server.py first!")

examples/python/remote/remote_agent_server.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Remote Agent Server Example
+
+This example demonstrates how to set up an agent as a remote server
+that can be accessed by other clients using the Session(agent_url=...) pattern.
+
+Usage:
+    python remote_agent_server.py
+
+Then connect from another machine/process:
+    python remote_agent_example.py
+"""
+
+from praisonaiagents import Agent
+import time
+
+def setup_remote_agent_server():
+    """
+    Set up an agent as a remote server accessible via HTTP API.
+    """
+    print("🚀 Setting up Remote Agent Server")
+    print("=" * 50)
+    
+    # Create an agent that will serve as the remote agent
+    agent = Agent(
+        name="RemoteAssistant",
+        role="Helpful Remote AI Assistant", 
+        goal="Assist users with their queries via remote connections",
+        backstory="I am an AI assistant running on a remote server, ready to help clients connect and interact with me.",
+        llm="gpt-4o-mini",  # or any other supported model
+        verbose=True
+    )
+    
+    print(f"📝 Created agent: {agent}")
+    print(f"🔧 Agent details:")
+    print(f"   • Name: {agent.name}")
+    print(f"   • Role: {agent.role}")
+    print(f"   • Goal: {agent.goal}")
+    
+    # Launch the agent as an HTTP API server
+    print(f"\n🌐 Launching agent server...")
+    print(f"📡 Server will be accessible at:")
+    print(f"   • Local: http://localhost:8000/agent")
+    print(f"   • Network: http://<your-ip>:8000/agent")
+    print(f"\n🔗 Clients can connect using:")
+    print(f"   session = Session(agent_url='<server-ip>:8000/agent')")
+    print(f"\n⏹️  Press Ctrl+C to stop the server")
+    print("=" * 50)
+    
+    # This will start the HTTP server and block until interrupted
+    try:
+        agent.launch(path="/agent", port=8000, host="0.0.0.0")
+    except KeyboardInterrupt:
+        print("\n\n🛑 Server stopped by user")
+    except Exception as e:
+        print(f"\n❌ Server error: {e}")
+
+def setup_multiple_agents():
+    """
+    Example of setting up multiple agents on the same server.
+    """
+    print("🚀 Setting up Multiple Remote Agents")
+    print("=" * 50)
+    
+    # Create different specialized agents
+    research_agent = Agent(
+        name="ResearchAgent",
+        role="Research Specialist",
+        instructions="You are a research specialist who helps with finding and analyzing information."
+    )
+    
+    coding_agent = Agent(
+        name="CodingAgent", 
+        role="Programming Assistant",
+        instructions="You are a programming assistant who helps with coding questions and debugging."
+    )
+    
+    # Launch them on different endpoints
+    print("🌐 Launching multiple agents:")
+    print("📡 Research Agent: http://localhost:8000/research")
+    print("📡 Coding Agent: http://localhost:8000/coding")
+    print("\n🔗 Connect using:")
+    print("   research_session = Session(agent_url='localhost:8000/research')")
+    print("   coding_session = Session(agent_url='localhost:8000/coding')")
+    
+    try:
+        # Launch both agents (this will start the server)
+        research_agent.launch(path="/research", port=8000, host="0.0.0.0")
+        coding_agent.launch(path="/coding", port=8000, host="0.0.0.0")
+    except KeyboardInterrupt:
+        print("\n\n🛑 Server stopped by user")
+
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) > 1 and sys.argv[1] == "--multiple":
+        setup_multiple_agents()
+    else:
+        setup_remote_agent_server()
+        
+    print("\n\n✅ Remote agent server example completed!")
+    print("💡 Tip: Use --multiple flag to run multiple agents example")

src/praisonai-agents/.cursorrules

@@ -5,146 +5,4 @@
 5. Make it minimal change as possible
 6. Firstly try not to make any modification to the existing code as possible
 7. Only modify the existing code if its highly required, without that if it cant be done, then add new code section. 
-8. If you are adding new code, make sure to add it in a way that it can be easily integrated with the existing codebase. 
-
-
-Below is a **detailed technical overview** of the issues that have been coming up in the workflow execution (specifically around loops, resetting tasks, and continuing on to subsequent tasks). It includes:
-
-1. **How the workflow currently flows**  
-2. **What logic marks a task as “completed”**  
-3. **What issues arose in `loop` tasks**  
-4. **Why the workflow can end up “stuck” or “looping indefinitely”**  
-
----
-
-## 1. Overall Workflow Flow
-
-### a. Building relationships among tasks
-
-- At startup, the code iterates through all `tasks`.  
-- For each `task`:
-  - It looks at `task.next_tasks`, and for each `next_task_name`:
-    - Finds the corresponding `Task` object
-    - Appends the current task’s name to the found `next_task`'s `previous_tasks` list.  
-- This means if Task A has `next_tasks=["B"]`, then Task B’s `previous_tasks` will include `"A"`.
-
-### b. Finding and starting with a “start task”
-
-- The workflow code tries to locate a task with `is_start=True`.  
-- If no such task is found, it uses the first item in the tasks dictionary instead.  
-- That “start task” is what the workflow tries to run first.
-
-### c. Execution loop in the method (e.g., `workflow()` or `aworkflow()`)
-
-- There is a `while current_task:` loop that processes tasks in sequence, or conditionally, based on `task.condition`.
-- Each time a task runs (if non-loop), it yields the `task_id` or triggers an agent to run. Once the agent finishes (with or without a final result), the workflow picks up again to see what to do next:
-  - If the `task` is a `loop` type, the code tries to create or manage sub-tasks for each row/line in an “input_file.”
-  - If the `task` is a normal (“decision” or “task” or “some-other-type”), it just executes once, sets `status="completed"`, and the code moves on.
-
-### d. Condition-based branching
-
-- If a task has a result that includes a “decision” (like `{"decision":"more"}` or `"done"`), the code checks `task.condition`. For example:
-  ```python
-  condition = {
-    "more": "generate_task",
-    "done": "evaluate_total_questions"
-  }
-  ```
-- If the result’s decision is `"done"`, it jumps to the task named `"evaluate_total_questions"`.  
-- If the result’s decision is `"more"`, it jumps right back to `"generate_task"`.  
-- If no condition matches, it can fallback to the first item in `task.next_tasks`.
-
-### e. Marking tasks as “completed”
-
-- After a task’s execution (like a typical “non-loop” task), the code sets `task.status = "completed"`.
-- Then the code has a snippet that says:
-  ```python
-  if self.tasks[task_id].status == "completed":
-      # Possibly reset to "not started" so we can re-run if needed
-  ```
-- By default, the system tries to “reset” tasks to `"not started"`, **unless** it is a loop task or a subtask of a loop.  
-
----
-
-## 2. How a “completed” task is marked
-
-Generally, tasks are marked `status="completed"` in two primary ways:
-
-1. **Non-Loop Execution**  
-   A normal task (like a “decision” or “task”) is executed once the code calls the agent, the agent returns a final result, and the system sets `task.status = "completed"`.
-2. **Loop Execution**  
-   A loop-type task is *programmatically* set to `status="completed"` when all of its sub-tasks have finished. That is:
-   - The code checks: “Have all child tasks of this loop finished?”  
-   - If `True`, the loop task is set to `completed`.
-
----
-
-## 3. Issues Specifically in `loop` Tasks
-
-### a. Re-Entering the Loop
-
-- Before, the same snippet that “resets completed tasks to ‘not started’ so they can re-run if needed” **also** tried to reset loop tasks or their subtasks.  
-- If a loop task got reset to `"not started"`, the code would eventually pick it back up again, leading to repeated creation of sub-tasks (or repeated attempts to re-run them).
-- This caused an **infinite loop** or repeating the same steps in the workflow, never truly exiting the loop stage.
-
-### b. Subtasks Not Marked or Overwritten
-
-- Another tricky scenario: If sub-tasks themselves got reset, the parent loop would see them as “not started” again, and might wait for them to “complete,” or might re-run them. That can lead to indefinite re-running of sub-tasks.
-
-### c. Not Proceeding to Next (e.g., “upload_to_huggingface”)
-
-- If the loop kept “restarting,” the workflow never ended up hitting the next tasks. For example, if your workflow is:
-  1. `generate_task`  
-  2. `evaluate_total_questions`  
-  3. `generate_cot` (loop)  
-  4. `upload_to_huggingface`
-- The system might get stuck in step #3 indefinitely (the sub-tasks keep getting reset, so it never actually transitions to step #4).
-
-### d. Condition Logic vs. Next Tasks
-
-- Another subtlety: If the loop tasks had a `condition` that pointed them back to a prior step, it might cause unintentional re-entry. Typically, you only want loop tasks to proceed once, **unless** you explicitly want to re-visit. But if it’s a data ingestion process, you usually want to do it once, then move on to the next step.
-
----
-
-## 4. Why the System Can End Up Stuck or “Looping Indefinitely”
-
-1. **Reset Mechanism**  
-   - The code tries to “reset tasks to ‘not started’ once they complete,” so they can be re-run in some dynamic multi-run scenario.  
-   - But that same logic can cause loop tasks to revert back to “not started” the moment they end. The system sees “Oh, a task is ‘not started’? Let’s run it!” and you’re in a cycle.
-
-2. **No Condition for Exit**  
-   - If the loop has a condition that leads back to a prior step (like `"more" -> generate_cot`), it can keep re-running.
-
-3. **Subtasks Not Marked**  
-   - If the subtask or the loop tries to “reactivate” each other, it never exits.
-
----
-
-## Summary of the “Core Problem”
-
-1. We want to keep the resetting mechanism for **non-loop tasks** – because in some advanced workflows, we like re-running them from a different path or after some condition.  
-2. But we want **loop tasks** to remain `"completed"` once all sub-tasks are done, so the code can seamlessly proceed to the next major step.  
-3. Before the fix, loop tasks or their sub-tasks got reset. This triggered the system to re-enter the loop, re-run the sub-tasks, etc., causing an infinite loop and preventing the workflow from reaching tasks like “upload_to_huggingface.”
-
----
-
-## Technical Highlights to Pass On
-
-- **In the reset snippet**:  
-  ```python
-  if self.tasks[task_id].status == "completed":
-      # never reset if loop or subtask-of-loop
-      # else reset to "not started"
-  ```
-  This is crucial to skipping re-runs on loop tasks.  
-- **Ensure** that once a loop’s sub-tasks are all “completed,” the loop’s status is set to “completed,” and it transitions to the next major tasks (like `upload_to_huggingface`).  
-- **Check** if the loop’s condition is correct. If you want a single pass, do not implement a condition that leads back to the same loop.  
-- Also, you can check you do not have “overlapping conditions” that cause re-entry.
-
----
-
-### Conclusion
-
-**Hence,** the main challenge is that the reset logic (meant to let normal tasks be re-run) conflicts with a loop task’s one-pass usage. Once you avoid resetting the loop tasks or sub-tasks, you can finish them once, mark them “completed,” and properly proceed to the next stage.
-
-Dont remove any logging or debug statements, as it will help you to understand the flow of the code.
+8. If you are adding new code, make sure to add it in a way that it can be easily integrated with the existing codebase. 

src/praisonai-agents/CLAUDE.md

@@ -0,0 +1,237 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PraisonAI Agents is a hierarchical AI agent framework for completing complex tasks with self-reflection capabilities. It supports multi-agent collaboration, tool integration, and various execution patterns (sequential, hierarchical, parallel).
+
+## Development Commands
+
+### Installation and Setup
+```bash
+# Install core package
+pip install -e .
+
+# Install with specific features
+pip install -e .[all]          # All features
+pip install -e .[memory]       # Memory capabilities
+pip install -e .[knowledge]    # Document processing
+pip install -e .[mcp]          # MCP server support
+pip install -e .[llm]          # Extended LLM support
+pip install -e .[api]          # API server capabilities
+```
+
+### Testing
+```bash
+# Run individual test examples (no formal test runner configured)
+python tests/basic-agents.py
+python tests/async_example.py
+python tests/knowledge-agents.py
+
+# Test specific features
+python tests/mcp-agents.py           # MCP integration
+python tests/memory_example.py      # Memory functionality
+python tests/tools_example.py       # Tool system
+```
+
+### Running Examples
+```bash
+# Basic agent usage
+python tests/single-agent.py
+
+# Multi-agent workflows
+python tests/multi-agents-api.py
+
+# Async operations
+python tests/async_example_full.py
+
+# MCP server examples
+python tests/mcp-sse-direct-server.py  # Start MCP server
+python tests/mcp-sse-direct-client.py  # Connect to server
+```
+
+## Core Architecture
+
+### Agent System (`praisonaiagents/agent/`)
+- **Agent**: Core agent class with LLM integration, tool calling, and self-reflection
+- **ImageAgent**: Specialized multimodal agent for image processing
+- Self-reflection with configurable min/max iterations (default: 1-3)
+- Delegation support for hierarchical agent structures
+
+### Multi-Agent Orchestration (`praisonaiagents/agents/`)
+- **PraisonAIAgents**: Main orchestrator for managing multiple agents and tasks
+- **AutoAgents**: Automatic agent creation and management
+- Process types: `sequential`, `hierarchical`, `parallel`
+- Context passing between agents and task dependency management
+
+### Task System (`praisonaiagents/task/`)
+- **Task**: Core task definition with context, callbacks, and output specifications
+- Supports file output, JSON/Pydantic structured output, async execution
+- Conditional logic with `condition` parameter for task flow control
+- Context passing via `context` parameter for task dependencies
+- **Guardrails**: Built-in validation and safety mechanisms for task outputs
+  - Function-based guardrails for custom validation logic
+  - LLM-based guardrails using natural language descriptions
+  - Automatic retry with configurable `max_retries` parameter
+  - Compatible with CrewAI guardrail patterns
+
+### LLM Integration (`praisonaiagents/llm/`)
+- Unified wrapper for multiple LLM providers via LiteLLM
+- Supports OpenAI, Anthropic, Gemini, DeepSeek, local models (Ollama)
+- Context length management and tool calling capabilities
+- Set via `llm` parameter on agents or global `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`
+
+### Tool System (`praisonaiagents/tools/`)
+Two implementation patterns:
+1. **Function-based**: Simple tools using `@tool` decorator
+2. **Class-based**: Complex tools inheriting from `BaseTool`
+
+Built-in tools include: DuckDuckGo search, file operations, calculator, Wikipedia, arXiv, data analysis tools, shell execution.
+
+### Memory & Knowledge Systems
+- **Memory** (`praisonaiagents/memory/`): Multi-layered memory with RAG support
+  - Types: short-term, long-term, entity, user memory
+  - Providers: ChromaDB, Mem0, custom implementations
+- **Knowledge** (`praisonaiagents/knowledge/`): Document processing with chunking
+  - Chunking strategies via `chonkie` library
+  - Embedding and retrieval capabilities
+
+### MCP (Model Context Protocol) Integration
+- **MCP Server**: Server-side tool protocol for distributed execution
+- **SSE Support**: Server-sent events for real-time communication
+- Tool discovery and dynamic registration
+
+## Development Patterns
+
+### Agent Creation
+```python
+agent = Agent(
+    name="Agent Name",
+    role="Agent Role",
+    goal="Agent Goal",
+    backstory="Agent Background",
+    llm="gpt-4o-mini",  # or other LLM
+    self_reflect=True,  # Enable self-reflection
+    min_reflect=1,      # Minimum reflection iterations
+    max_reflect=3,      # Maximum reflection iterations
+    tools=[tool1, tool2],  # Optional tools
+    guardrail=validate_function,  # Agent-level guardrail (function or string)
+    max_guardrail_retries=3  # Retry limit for guardrail failures
+)
+```
+
+### Task Definition
+```python
+task = Task(
+    name="task_name",
+    description="Task description",
+    expected_output="Expected output format",
+    agent=agent,
+    context=[previous_task],  # Task dependencies
+    output_pydantic=ResponseModel,  # Structured output
+    condition="condition_function"  # Conditional execution
+)
+```
+
+### Guardrails Usage
+
+#### Task-Level Guardrails
+```python
+from typing import Tuple, Any
+
+# Function-based guardrail
+def validate_output(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """Custom validation function."""
+    if "error" in task_output.raw.lower():
+        return False, "Output contains errors"
+    if len(task_output.raw) < 10:
+        return False, "Output is too short"
+    return True, task_output
+
+task = Task(
+    description="Write a professional email",
+    expected_output="A well-formatted email",
+    agent=agent,
+    guardrail=validate_output,  # Function-based guardrail
+    max_retries=3  # Retry up to 3 times if guardrail fails
+)
+
+# LLM-based guardrail
+task = Task(
+    description="Generate marketing copy",
+    expected_output="Professional marketing content",
+    agent=agent,
+    guardrail="Ensure the content is professional, engaging, and free of errors",  # String description
+    max_retries=2
+)
+```
+
+#### Agent-Level Guardrails
+```python
+# Agent guardrails apply to ALL outputs from that agent
+def validate_professional_tone(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """Ensure professional tone in all agent responses."""
+    content = task_output.raw.lower()
+    casual_words = ['yo', 'dude', 'awesome', 'cool']
+    for word in casual_words:
+        if word in content:
+            return False, f"Unprofessional language detected: {word}"
+    return True, task_output
+
+# Agent with function-based guardrail
+agent = Agent(
+    name="BusinessWriter",
+    instructions="You are a professional business writer",
+    guardrail=validate_professional_tone,  # Function guardrail
+    max_guardrail_retries=3
+)
+
+# Agent with LLM-based guardrail
+agent = Agent(
+    name="ContentWriter", 
+    instructions="You are a content writer",
+    guardrail="Ensure all responses are professional, accurate, and appropriate for business use",  # String guardrail
+    max_guardrail_retries=2
+)
+```
+
+### Multi-Agent Workflow
+```python
+workflow = PraisonAIAgents(
+    agents=[agent1, agent2],
+    tasks=[task1, task2],
+    process="sequential",  # or "hierarchical", "parallel"
+    verbose=True,
+    manager_agent=manager_agent  # For hierarchical process
+)
+result = workflow.start()
+```
+
+### Async Support
+All major components support async execution:
+```python
+result = await workflow.astart()
+result = await agent.aexecute(task)
+```
+
+## Key Dependencies
+
+- **Core**: `pydantic`, `rich`, `openai`, `mcp`
+- **Memory**: `chromadb`, `mem0ai`
+- **Knowledge**: `markitdown`, `chonkie`
+- **LLM**: `litellm` for unified provider access
+- **API**: `fastapi`, `uvicorn` for server capabilities
+
+## Error Handling
+
+- Global error logging via `error_logs` list
+- Callback system for real-time error reporting
+- Context length exception handling with automatic retry
+- Graceful degradation for optional dependencies
+
+## Testing Strategy
+
+The project uses example-driven testing with 100+ test files in `tests/` directory. Each test file demonstrates specific usage patterns and serves as both test and documentation. Run individual examples to test functionality rather than using a formal test runner.
+
+Use conda activate praisonai-agents to activate the environment.

src/praisonai-agents/TELEMETRY_SUMMARY.md

@@ -0,0 +1,33 @@
+# Telemetry Implementation Summary
+
+## What Was Fixed
+
+1. **PostHog initialization error** - Removed invalid `events_to_ignore` parameter
+2. **Missing imports** - Added `MinimalTelemetry` and `TelemetryCollector` imports to telemetry `__init__.py`
+3. **Wrong method instrumentation** - Changed from `agent.execute()` to `agent.chat()`
+4. **Task tracking** - Added instrumentation for `workflow.execute_task()`
+5. **Automatic setup** - Added `auto_instrument_all()` in main `__init__.py`
+6. **Automatic flush** - Added `atexit` handler to send data on program exit
+
+## Current Status
+
+✅ **Telemetry is now working automatically!**
+
+- Enabled by default (opt-out via environment variables)
+- Tracks agent executions and task completions
+- Sends anonymous data to PostHog on program exit
+- No manual setup required
+
+## Metrics Example
+```
+Telemetry metrics collected:
+- Agent executions: 4
+- Task completions: 2
+- Errors: 0
+- Session ID: 33873e62396d8b4c
+```
+
+## To Disable
+Set any of these environment variables:
+- `PRAISONAI_TELEMETRY_DISABLED=true`
+- `DO_NOT_TRACK=true`

src/praisonai-agents/agent_guardrails_example.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Agent-level guardrails example.
+
+This example demonstrates how to use guardrails at the Agent level,
+which will apply to all tasks executed by that agent.
+"""
+
+from typing import Tuple, Any
+from praisonaiagents import Agent, TaskOutput
+
+def validate_content_length(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """
+    Validate that task output content meets minimum length requirement.
+    
+    Args:
+        task_output: The task output to validate
+        
+    Returns:
+        Tuple of (success, result_or_error_message)
+    """
+    if len(task_output.raw) < 50:
+        return False, "Content too short - must be at least 50 characters"
+    return True, task_output
+
+def validate_professional_tone(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """
+    Validate that the content has a professional tone.
+    
+    Args:
+        task_output: The task output to validate
+        
+    Returns:
+        Tuple of (success, result_or_error_message)
+    """
+    content = task_output.raw.lower()
+    unprofessional_words = ['yo', 'dude', 'awesome', 'cool', 'lol']
+    
+    for word in unprofessional_words:
+        if word in content:
+            return False, f"Content contains unprofessional word: '{word}'"
+    
+    return True, task_output
+
+def main():
+    """Demonstrate Agent-level guardrails with function-based and LLM-based validation."""
+    
+    print("=== Agent Guardrail Examples ===\n")
+    
+    # Example 1: Function-based guardrail
+    print("1. Function-based guardrail (content length validation):")
+    agent1 = Agent(
+        name="ContentWriter",
+        instructions="You are a professional content writer who creates detailed responses",
+        guardrail=validate_content_length,
+        max_guardrail_retries=2
+    )
+    
+    try:
+        result1 = agent1.start("Write a brief welcome message")
+        print(f"Result: {result1}\n")
+    except Exception as e:
+        print(f"Error: {e}\n")
+    
+    # Example 2: LLM-based guardrail (string description)
+    print("2. LLM-based guardrail (professional tone validation):")
+    agent2 = Agent(
+        name="BusinessWriter", 
+        instructions="You are a business communication expert",
+        guardrail="Ensure the content is professional, formal, and suitable for business communication. No casual language or slang.",
+        max_guardrail_retries=3
+    )
+    
+    try:
+        result2 = agent2.start("Write a welcome message for new employees")
+        print(f"Result: {result2}\n")
+    except Exception as e:
+        print(f"Error: {e}\n")
+    
+    # Example 3: Multiple agents with different guardrails
+    print("3. Professional tone function-based guardrail:")
+    agent3 = Agent(
+        name="ProfessionalWriter",
+        instructions="Write professional business content",
+        guardrail=validate_professional_tone,
+        max_guardrail_retries=2
+    )
+    
+    try:
+        result3 = agent3.start("Write a casual greeting message")
+        print(f"Result: {result3}\n")
+    except Exception as e:
+        print(f"Error: {e}\n")
+    
+    print("=== Agent Guardrails Demonstration Complete ===")
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/debug_auto_instrument.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+Debug auto-instrumentation.
+"""
+
+print("1. Import telemetry module...")
+import praisonaiagents.telemetry
+print("   Telemetry module imported")
+
+print("\n2. Check if auto_instrument_all was called...")
+print(f"   _initialized: {praisonaiagents.telemetry._initialized}")
+
+print("\n3. Import Agent and PraisonAIAgents...")
+from praisonaiagents import Agent, PraisonAIAgents
+print("   Classes imported")
+
+print("\n4. Check if classes are instrumented...")
+agent = Agent(name="Test", role="Test", goal="Test", instructions="Test")
+print(f"   Agent.__init__ name: {Agent.__init__.__name__}")
+print(f"   agent.execute exists: {hasattr(agent, 'execute')}")
+
+print("\n5. Manually call auto_instrument_all...")
+from praisonaiagents.telemetry.integration import auto_instrument_all
+auto_instrument_all()
+print("   auto_instrument_all() called")
+
+print("\n6. Create new agent after instrumentation...")
+agent2 = Agent(name="Test2", role="Test2", goal="Test2", instructions="Test2")
+print(f"   Agent.__init__ name after: {Agent.__init__.__name__}")
+print(f"   agent2.execute exists: {hasattr(agent2, 'execute')}")
+
+print("\n7. Check if execute is wrapped...")
+if hasattr(agent2, 'execute'):
+    print(f"   agent2.execute name: {agent2.execute.__name__}")
+    print(f"   agent2.execute wrapped: {hasattr(agent2.execute, '__wrapped__')}")
+
+print("\n8. Import telemetry and check if it's working...")
+from praisonaiagents.telemetry import get_telemetry
+telemetry = get_telemetry()
+print(f"   Telemetry enabled: {telemetry.enabled}")
+print(f"   PostHog available: {telemetry._posthog is not None}")
+
+# The key insight: auto_instrument_all needs to be called AFTER
+# the Agent and PraisonAIAgents classes are imported!

src/praisonai-agents/debug_comparison.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+
+import sys
+import traceback
+from praisonaiagents import Agent, MCP
+
+def test_agent_direct():
+    """Test gpt-4o-mini (agent.py path)"""
+    print("=" * 50)
+    print("TESTING: gpt-4o-mini (agent.py direct calls)")
+    print("=" * 50)
+    
+    try:
+        agent = Agent(
+            instructions="""You are a helpful assistant that can break down complex problems.
+            Use the available tools when relevant to perform step-by-step analysis.""",
+            llm="gpt-4o-mini",
+            tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+        )
+        
+        print("✅ Agent created successfully")
+        print(f"✅ Agent LLM: {getattr(agent, 'llm', 'Not set')}")
+        print(f"✅ Agent using custom LLM: {getattr(agent, '_using_custom_llm', False)}")
+        
+        result = agent.start("What are 3 steps to make coffee?")
+        print("✅ Agent execution completed successfully")
+        return True, result
+        
+    except Exception as e:
+        print(f"❌ Error in agent direct: {e}")
+        traceback.print_exc()
+        return False, str(e)
+
+def test_llm_class():
+    """Test openai/gpt-4o-mini (llm.py path)"""
+    print("\n" + "=" * 50)
+    print("TESTING: openai/gpt-4o-mini (llm.py LiteLLM)")
+    print("=" * 50)
+    
+    try:
+        agent = Agent(
+            instructions="""You are a helpful assistant that can break down complex problems.
+            Use the available tools when relevant to perform step-by-step analysis.""",
+            llm="openai/gpt-4o-mini",
+            tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+        )
+        
+        print("✅ Agent created successfully")
+        print(f"✅ Agent LLM instance: {getattr(agent, 'llm_instance', 'Not set')}")
+        print(f"✅ Agent using custom LLM: {getattr(agent, '_using_custom_llm', False)}")
+        
+        result = agent.start("What are 3 steps to make coffee?")
+        print("✅ Agent execution completed successfully")
+        return True, result
+        
+    except Exception as e:
+        print(f"❌ Error in llm class: {e}")
+        traceback.print_exc()
+        return False, str(e)
+
+if __name__ == "__main__":
+    print("🔍 DEBUGGING: Comparing both LLM approaches\n")
+    
+    # Test agent direct
+    success1, result1 = test_agent_direct()
+    
+    # Test LLM class
+    success2, result2 = test_llm_class()
+    
+    print("\n" + "=" * 50)
+    print("FINAL RESULTS")
+    print("=" * 50)
+    
+    if success1:
+        print("✅ gpt-4o-mini (agent.py) - SUCCESS")
+    else:
+        print("❌ gpt-4o-mini (agent.py) - FAILED")
+        print(f"   Error: {result1}")
+    
+    if success2:
+        print("✅ openai/gpt-4o-mini (llm.py) - SUCCESS")
+    else:
+        print("❌ openai/gpt-4o-mini (llm.py) - FAILED")
+        print(f"   Error: {result2}")
+    
+    if success1 and success2:
+        print("\n🎉 BOTH FORMATS WORK CORRECTLY!")
+        print("📝 The issue mentioned might be resolved or was a different problem.")
+    elif success1 and not success2:
+        print("\n⚠️  CONFIRMED: LLM class path has issues")
+        print("📝 Need to debug the LLM class implementation")
+    elif success2 and not success1:
+        print("\n⚠️  CONFIRMED: Agent direct path has issues")
+        print("📝 Need to debug the agent direct implementation")
+    else:
+        print("\n💥 BOTH PATHS FAILED - Something is fundamentally wrong")

src/praisonai-agents/debug_telemetry.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Debug telemetry instrumentation to see what's happening.
+"""
+
+import os
+# Make sure telemetry is enabled
+if 'PRAISONAI_TELEMETRY_DISABLED' in os.environ:
+    del os.environ['PRAISONAI_TELEMETRY_DISABLED']
+
+print("1. Importing modules...")
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.telemetry import get_telemetry
+
+print("\n2. Checking telemetry status...")
+telemetry = get_telemetry()
+print(f"Telemetry enabled: {telemetry.enabled}")
+print(f"PostHog available: {telemetry._posthog is not None}")
+
+print("\n3. Creating agent...")
+agent = Agent(
+    name="TestAgent",
+    role="Test Role",
+    goal="Test Goal",
+    instructions="Test instructions"
+)
+
+# Check if agent.execute is instrumented
+print(f"\n4. Checking agent instrumentation...")
+print(f"Agent has execute method: {hasattr(agent, 'execute')}")
+if hasattr(agent, 'execute'):
+    print(f"Execute method type: {type(agent.execute)}")
+    print(f"Execute method name: {agent.execute.__name__ if hasattr(agent.execute, '__name__') else 'No name'}")
+    print(f"Is wrapped: {'instrumented' in str(agent.execute.__name__) if hasattr(agent.execute, '__name__') else 'Unknown'}")
+
+print("\n5. Creating task...")
+task = Task(
+    description="Test task",
+    expected_output="Test output",
+    agent=agent
+)
+
+print("\n6. Creating workflow...")
+workflow = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    process="sequential"
+)
+
+# Check if workflow.start is instrumented
+print(f"\n7. Checking workflow instrumentation...")
+print(f"Workflow has start method: {hasattr(workflow, 'start')}")
+if hasattr(workflow, 'start'):
+    print(f"Start method type: {type(workflow.start)}")
+    print(f"Start method name: {workflow.start.__name__ if hasattr(workflow.start, '__name__') else 'No name'}")
+    print(f"Is wrapped: {'instrumented' in str(workflow.start.__name__) if hasattr(workflow.start, '__name__') else 'Unknown'}")
+
+print("\n8. Running workflow...")
+result = workflow.start()
+
+print("\n9. Checking metrics...")
+metrics = telemetry.get_metrics()
+print(f"Metrics: {metrics}")
+
+print("\n10. Manually tracking to verify telemetry works...")
+telemetry.track_agent_execution("ManualTest", success=True)
+telemetry.track_task_completion("ManualTask", success=True)
+manual_metrics = telemetry.get_metrics()
+print(f"After manual tracking: {manual_metrics['metrics']}")

src/praisonai-agents/debug_telemetry_double.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Debug double-counting in telemetry.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.telemetry import get_telemetry
+
+# Get telemetry instance
+telemetry = get_telemetry()
+
+# Clear any existing metrics by flushing
+telemetry.flush()
+
+print("Starting fresh telemetry tracking...\n")
+
+# Create ONE agent
+print("Creating 1 agent...")
+agent = Agent(
+    name="SingleAgent",
+    role="Test Role",
+    goal="Test Goal",
+    instructions="Test instructions"
+)
+
+# Create ONE task
+print("Creating 1 task...")
+task = Task(
+    description="Single test task",
+    expected_output="Test output",
+    agent=agent
+)
+
+# Create workflow with ONE agent and ONE task
+print("Creating workflow with 1 agent and 1 task...")
+workflow = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    process="sequential"
+)
+
+# Check metrics before running
+metrics_before = telemetry.get_metrics()
+print(f"\nMetrics BEFORE running workflow:")
+print(f"  Agent executions: {metrics_before['metrics']['agent_executions']}")
+print(f"  Task completions: {metrics_before['metrics']['task_completions']}")
+
+# Run the workflow
+print("\nRunning workflow...")
+result = workflow.start()
+
+# Check metrics after running
+metrics_after = telemetry.get_metrics()
+print(f"\nMetrics AFTER running workflow:")
+print(f"  Agent executions: {metrics_after['metrics']['agent_executions']} (expected: 1)")
+print(f"  Task completions: {metrics_after['metrics']['task_completions']} (expected: 1)")
+
+if metrics_after['metrics']['agent_executions'] > 1:
+    print("\n❌ ISSUE: Agent executions are being double-counted!")
+    print("   Possible causes:")
+    print("   - Agent method is being called multiple times")
+    print("   - Instrumentation is being applied twice")
+    print("   - Multiple tracking calls for same execution")
+
+if metrics_after['metrics']['task_completions'] > 1:
+    print("\n❌ ISSUE: Task completions are being double-counted!")
+    print("   Possible causes:")
+    print("   - Task completion is tracked in multiple places")
+    print("   - Instrumentation is being applied twice")

src/praisonai-agents/guardrail_agent_example.py

@@ -0,0 +1,14 @@
+from praisonaiagents import Agent
+
+def validate_content(data):
+    if len(str(data)) < 50:
+        return False, "Content too short"
+    return True, data
+
+agent = Agent(
+    instructions="You are a writer",
+    guardrail=validate_content,
+    max_guardrail_retries=1
+)
+
+agent.start("Write a welcome message with 5 words")

src/praisonai-agents/guardrail_agents_example.py

@@ -0,0 +1,21 @@
+from praisonaiagents import Agent, Task, TaskOutput, PraisonAIAgents
+from typing import Tuple, Any
+
+def validate_content(task_output: TaskOutput) -> Tuple[bool, Any]:
+    if len(task_output.raw) < 50:
+        return False, "Content too short"
+    return True, task_output
+
+agent = Agent(
+    instructions="You are a writer",
+)
+
+task = Task(
+    description="Write a welcome message",
+    guardrail=validate_content,
+    agent=agent
+)
+
+praison_agents = PraisonAIAgents(agents=[agent], tasks=[task])
+
+praison_agents.start()

src/praisonai-agents/guardrails_example.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating guardrails functionality in PraisonAI Agents.
+
+This example shows both function-based and LLM-based guardrails
+for validating task outputs.
+"""
+
+import sys
+import os
+from typing import Tuple, Any
+
+from praisonaiagents import Agent, Task, TaskOutput
+
+
+def email_validator(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """
+    Function-based guardrail to validate email content.
+    
+    Args:
+        task_output: The task output to validate
+        
+    Returns:
+        Tuple of (success, result_or_error)
+    """
+    content = task_output.raw.lower()
+    
+    # Check for required email components
+    if "subject:" not in content:
+        return False, "Email must include a subject line"
+    
+    if "dear" not in content and "hello" not in content:
+        return False, "Email must include a proper greeting"
+    
+    if len(content) < 50:
+        return False, "Email content is too short"
+        
+    if "error" in content or "problem" in content:
+        return False, "Email should not mention errors or problems"
+        
+    return True, task_output
+
+
+def main():
+    """Run the guardrails example."""
+    print("PraisonAI Agents - Guardrails Example")
+    print("=====================================\n")
+    
+    # Create an agent
+    agent = Agent(
+        name="Email Assistant",
+        role="Professional Email Writer",
+        goal="Write clear, professional emails",
+        backstory="I am an AI assistant specialized in writing professional emails"
+    )
+    
+    print("1. Testing Function-based Guardrail")
+    print("------------------------------------")
+    
+    # Create task with function-based guardrail
+    task_with_function_guardrail = Task(
+        description="Write a professional email to a client about project completion",
+        expected_output="A well-formatted professional email",
+        agent=agent,
+        guardrail=email_validator,  # Function-based guardrail
+        max_retries=2
+    )
+    
+    print(f"Task created with function guardrail: {email_validator.__name__}")
+    print(f"Max retries: {task_with_function_guardrail.max_retries}")
+    
+    # Simulate a task output that should pass
+    good_output = TaskOutput(
+        description="Email task",
+        raw="""Subject: Project Completion Update
+
+Dear Client,
+
+I am pleased to inform you that your project has been completed successfully. 
+All deliverables have been reviewed and are ready for your review. 
+Please let me know if you have any questions.
+
+Best regards,
+Project Team""",
+        agent="Email Assistant"
+    )
+    
+    result = task_with_function_guardrail._process_guardrail(good_output)
+    print(f"Good email result: {'PASSED' if result.success else 'FAILED'}")
+    if not result.success:
+        print(f"Error: {result.error}")
+    
+    # Simulate a task output that should fail
+    bad_output = TaskOutput(
+        description="Email task",
+        raw="Hi there, there was an error with your project.",
+        agent="Email Assistant"
+    )
+    
+    result = task_with_function_guardrail._process_guardrail(bad_output)
+    print(f"Bad email result: {'PASSED' if result.success else 'FAILED'}")
+    if not result.success:
+        print(f"Error: {result.error}")
+    
+    print("\n2. Testing String-based LLM Guardrail")
+    print("-------------------------------------")
+    
+    # Create task with string-based guardrail
+    task_with_llm_guardrail = Task(
+        description="Write a marketing email for a new product launch",
+        expected_output="Engaging marketing content",
+        agent=agent,
+        guardrail="Ensure the content is professional, engaging, includes a clear call-to-action, and is free of errors",
+        max_retries=3
+    )
+    
+    print("Task created with LLM-based guardrail")
+    print("Guardrail description: 'Ensure the content is professional, engaging, includes a clear call-to-action, and is free of errors'")
+    print(f"Max retries: {task_with_llm_guardrail.max_retries}")
+    
+    print("\n3. Backward Compatibility")
+    print("-------------------------")
+    
+    # Create task without guardrail (backward compatible)
+    task_without_guardrail = Task(
+        description="Write a simple thank you note",
+        expected_output="A brief thank you message",
+        agent=agent
+    )
+    
+    print("Task created without guardrail (backward compatible)")
+    print(f"Guardrail function: {task_without_guardrail._guardrail_fn}")
+    
+    # Test that it doesn't break existing functionality
+    simple_output = TaskOutput(
+        description="Thank you task",
+        raw="Thank you for your business!",
+        agent="Email Assistant"
+    )
+    
+    result = task_without_guardrail._process_guardrail(simple_output)
+    print(f"No guardrail result: {'PASSED' if result.success else 'FAILED'}")
+    
+    print("\n✅ Guardrails example completed successfully!")
+    print("\nKey Features Demonstrated:")
+    print("- Function-based guardrails with custom validation logic")
+    print("- String-based LLM guardrails using natural language")
+    print("- Configurable retry mechanism")
+    print("- Backward compatibility with existing tasks")
+    print("- Integration with TaskOutput validation")
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/praisonaiagents/__init__.py

@@ -12,6 +12,8 @@ from .knowledge.knowledge import Knowledge
 from .knowledge.chunking import Chunking
 from .mcp.mcp import MCP
 from .session import Session
+from .memory.memory import Memory
+from .guardrails import GuardrailResult, LLMGuardrail
 from .main import (
     TaskOutput,
     ReflectionOutput,
@@ -28,9 +30,50 @@ from .main import (
     async_display_callbacks,
 )
 
+# Telemetry support (lazy loaded)
+try:
+    from .telemetry import (
+        get_telemetry,
+        enable_telemetry,
+        disable_telemetry,
+        MinimalTelemetry,
+        TelemetryCollector
+    )
+    _telemetry_available = True
+except ImportError:
+    # Telemetry not available - provide stub functions
+    _telemetry_available = False
+    def get_telemetry():
+        return None
+    
+    def enable_telemetry(*args, **kwargs):
+        import logging
+        logging.warning(
+            "Telemetry not available. Install with: pip install praisonaiagents[telemetry]"
+        )
+        return None
+    
+    def disable_telemetry():
+        pass
+    
+    MinimalTelemetry = None
+    TelemetryCollector = None
+
 # Add Agents as an alias for PraisonAIAgents
 Agents = PraisonAIAgents
 
+# Apply telemetry auto-instrumentation after all imports
+if _telemetry_available:
+    try:
+        # Only instrument if telemetry is enabled
+        _telemetry = get_telemetry()
+        if _telemetry and _telemetry.enabled:
+            from .telemetry.integration import auto_instrument_all
+            auto_instrument_all(_telemetry)
+    except Exception:
+        # Silently fail if there are any issues
+        pass
+
 __all__ = [
     'Agent',
     'ImageAgent',
@@ -42,6 +85,7 @@ __all__ = [
     'ReflectionOutput',
     'AutoAgents',
     'Session',
+    'Memory',
     'display_interaction',
     'display_self_reflection',
     'display_instruction',
@@ -55,5 +99,12 @@ __all__ = [
     'async_display_callbacks',
     'Knowledge',
     'Chunking',
-    'MCP'
+    'MCP',
+    'GuardrailResult',
+    'LLMGuardrail',
+    'get_telemetry',
+    'enable_telemetry',
+    'disable_telemetry',
+    'MinimalTelemetry',
+    'TelemetryCollector'
 ] 

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

@@ -3,7 +3,7 @@ import time
 import json
 import logging
 import asyncio
-from typing import List, Optional, Any, Dict, Union, Literal, TYPE_CHECKING
+from typing import List, Optional, Any, Dict, Union, Literal, TYPE_CHECKING, Callable, Tuple
 from rich.console import Console
 from rich.live import Live
 from openai import AsyncOpenAI
@@ -32,6 +32,7 @@ _shared_apps = {}  # Dict of port -> FastAPI app
 
 if TYPE_CHECKING:
     from ..task.task import Task
+    from ..main import TaskOutput
 
 @dataclass
 class ChatCompletionMessage:
@@ -367,9 +368,97 @@ class Agent:
         max_reflect: int = 3,
         min_reflect: int = 1,
         reflect_llm: Optional[str] = None,
+        reflect_prompt: Optional[str] = None,
         user_id: Optional[str] = None,
-        reasoning_steps: bool = False
+        reasoning_steps: bool = False,
+        guardrail: Optional[Union[Callable[['TaskOutput'], Tuple[bool, Any]], str]] = None,
+        max_guardrail_retries: int = 3
     ):
+        """Initialize an Agent instance.
+
+        Args:
+            name (Optional[str], optional): Name of the agent used for identification and logging.
+                If None, defaults to "Agent". Defaults to None.
+            role (Optional[str], optional): Role or job title that defines the agent's expertise
+                and behavior patterns. Examples: "Data Analyst", "Content Writer". Defaults to None.
+            goal (Optional[str], optional): Primary objective or goal the agent aims to achieve.
+                Defines the agent's purpose and success criteria. Defaults to None.
+            backstory (Optional[str], optional): Background story or context that shapes the agent's
+                personality and decision-making approach. Defaults to None.
+            instructions (Optional[str], optional): Direct instructions that override role, goal,
+                and backstory when provided. Used for simple, task-specific agents. Defaults to None.
+            llm (Optional[Union[str, Any]], optional): Language model configuration. Can be a model
+                name string (e.g., "gpt-4o", "anthropic/claude-3-sonnet") or a configured LLM object.
+                Defaults to environment variable OPENAI_MODEL_NAME or "gpt-4o".
+            tools (Optional[List[Any]], optional): List of tools, functions, or capabilities
+                available to the agent for task execution. Can include callables, tool objects,
+                or MCP instances. Defaults to None.
+            function_calling_llm (Optional[Any], optional): Dedicated language model for function
+                calling operations. If None, uses the main llm parameter. Defaults to None.
+            max_iter (int, optional): Maximum number of iterations the agent can perform during
+                task execution to prevent infinite loops. Defaults to 20.
+            max_rpm (Optional[int], optional): Maximum requests per minute to rate limit API calls
+                and prevent quota exhaustion. If None, no rate limiting is applied. Defaults to None.
+            max_execution_time (Optional[int], optional): Maximum execution time in seconds for
+                agent operations before timeout. If None, no time limit is enforced. Defaults to None.
+            memory (Optional[Any], optional): Memory system for storing and retrieving information
+                across conversations. Requires memory dependencies to be installed. Defaults to None.
+            verbose (bool, optional): Enable detailed logging and status updates during agent
+                execution for debugging and monitoring. Defaults to True.
+            allow_delegation (bool, optional): Allow the agent to delegate tasks to other agents
+                or sub-processes when appropriate. Defaults to False.
+            step_callback (Optional[Any], optional): Callback function called after each step
+                of agent execution for custom monitoring or intervention. Defaults to None.
+            cache (bool, optional): Enable caching of responses and computations to improve
+                performance and reduce API costs. Defaults to True.
+            system_template (Optional[str], optional): Custom template for system prompts that
+                overrides the default system prompt generation. Defaults to None.
+            prompt_template (Optional[str], optional): Template for formatting user prompts
+                before sending to the language model. Defaults to None.
+            response_template (Optional[str], optional): Template for formatting agent responses
+                before returning to the user. Defaults to None.
+            allow_code_execution (Optional[bool], optional): Enable the agent to execute code
+                snippets during task completion. Use with caution for security. Defaults to False.
+            max_retry_limit (int, optional): Maximum number of retry attempts for failed operations
+                before giving up. Helps handle transient errors. Defaults to 2.
+            respect_context_window (bool, optional): Automatically manage context window size
+                to prevent token limit errors with large conversations. Defaults to True.
+            code_execution_mode (Literal["safe", "unsafe"], optional): Safety mode for code execution.
+                "safe" restricts dangerous operations, "unsafe" allows full code execution. Defaults to "safe".
+            embedder_config (Optional[Dict[str, Any]], optional): Configuration dictionary for
+                text embedding models used in knowledge retrieval and similarity search. Defaults to None.
+            knowledge (Optional[List[str]], optional): List of knowledge sources (file paths, URLs,
+                or text content) to be processed and made available to the agent. Defaults to None.
+            knowledge_config (Optional[Dict[str, Any]], optional): Configuration for knowledge
+                processing and retrieval system including chunking and indexing parameters. Defaults to None.
+            use_system_prompt (Optional[bool], optional): Whether to include system prompts in
+                conversations to establish agent behavior and context. Defaults to True.
+            markdown (bool, optional): Enable markdown formatting in agent responses for better
+                readability and structure. Defaults to True.
+            self_reflect (bool, optional): Enable self-reflection capabilities where the agent
+                evaluates and improves its own responses. Defaults to False.
+            max_reflect (int, optional): Maximum number of self-reflection iterations to prevent
+                excessive reflection loops. Defaults to 3.
+            min_reflect (int, optional): Minimum number of self-reflection iterations required
+                before accepting a response as satisfactory. Defaults to 1.
+            reflect_llm (Optional[str], optional): Dedicated language model for self-reflection
+                operations. If None, uses the main llm parameter. Defaults to None.
+            reflect_prompt (Optional[str], optional): Custom prompt template for self-reflection
+                that guides the agent's self-evaluation process. Defaults to None.
+            user_id (Optional[str], optional): Unique identifier for the user or session to
+                enable personalized responses and memory isolation. Defaults to "praison".
+            reasoning_steps (bool, optional): Enable step-by-step reasoning output to show the
+                agent's thought process during problem solving. Defaults to False.
+            guardrail (Optional[Union[Callable[['TaskOutput'], Tuple[bool, Any]], str]], optional):
+                Safety mechanism to validate agent outputs. Can be a validation function or
+                description string for LLM-based validation. Defaults to None.
+            max_guardrail_retries (int, optional): Maximum number of retry attempts when guardrail
+                validation fails before giving up. Defaults to 3.
+
+        Raises:
+            ValueError: If all of name, role, goal, backstory, and instructions are None.
+            ImportError: If memory or LLM features are requested but dependencies are not installed.
+        """
         # Add check at start if memory is requested
         if memory is not None:
             try:
@@ -467,6 +556,7 @@ class Agent:
         self.markdown = markdown
         self.max_reflect = max_reflect
         self.min_reflect = min_reflect
+        self.reflect_prompt = reflect_prompt
         # Use the same model selection logic for reflect_llm
         self.reflect_llm = reflect_llm or os.getenv('OPENAI_MODEL_NAME', 'gpt-4o')
         self.console = Console()  # Create a single console instance for the agent
@@ -483,6 +573,12 @@ Your Goal: {self.goal}
         # Store user_id
         self.user_id = user_id or "praison"
         self.reasoning_steps = reasoning_steps
+        
+        # Initialize guardrail settings
+        self.guardrail = guardrail
+        self.max_guardrail_retries = max_guardrail_retries
+        self._guardrail_fn = None
+        self._setup_guardrail()
 
         # Check if knowledge parameter has any values
         if not knowledge:
@@ -512,6 +608,149 @@ Your Goal: {self.goal}
         except Exception as e:
             logging.error(f"Error processing knowledge item: {knowledge_item}, error: {e}")
 
+    def _setup_guardrail(self):
+        """Setup the guardrail function based on the provided guardrail parameter."""
+        if self.guardrail is None:
+            self._guardrail_fn = None
+            return
+            
+        if callable(self.guardrail):
+            # Validate function signature
+            sig = inspect.signature(self.guardrail)
+            positional_args = [
+                param for param in sig.parameters.values()
+                if param.default is inspect.Parameter.empty
+            ]
+            if len(positional_args) != 1:
+                raise ValueError("Agent guardrail function must accept exactly one parameter (TaskOutput)")
+            
+            # Check return annotation if present
+            from typing import get_args, get_origin
+            return_annotation = sig.return_annotation
+            if return_annotation != inspect.Signature.empty:
+                return_annotation_args = get_args(return_annotation)
+                if not (
+                    get_origin(return_annotation) is tuple
+                    and len(return_annotation_args) == 2
+                    and return_annotation_args[0] is bool
+                    and (
+                        return_annotation_args[1] is Any
+                        or return_annotation_args[1] is str
+                        or str(return_annotation_args[1]).endswith('TaskOutput')
+                        or str(return_annotation_args[1]).startswith('typing.Union')
+                    )
+                ):
+                    raise ValueError(
+                        "If return type is annotated, it must be Tuple[bool, Any] or Tuple[bool, Union[str, TaskOutput]]"
+                    )
+            
+            self._guardrail_fn = self.guardrail
+        elif isinstance(self.guardrail, str):
+            # Create LLM-based guardrail
+            from ..guardrails import LLMGuardrail
+            llm = getattr(self, 'llm', None) or getattr(self, 'llm_instance', None)
+            self._guardrail_fn = LLMGuardrail(description=self.guardrail, llm=llm)
+        else:
+            raise ValueError("Agent guardrail must be either a callable or a string description")
+
+    def _process_guardrail(self, task_output):
+        """Process the guardrail validation for a task output.
+        
+        Args:
+            task_output: The task output to validate
+            
+        Returns:
+            GuardrailResult: The result of the guardrail validation
+        """
+        from ..guardrails import GuardrailResult
+        
+        if not self._guardrail_fn:
+            return GuardrailResult(success=True, result=task_output)
+        
+        try:
+            # Call the guardrail function
+            result = self._guardrail_fn(task_output)
+            
+            # Convert the result to a GuardrailResult
+            return GuardrailResult.from_tuple(result)
+            
+        except Exception as e:
+            logging.error(f"Agent {self.name}: Error in guardrail validation: {e}")
+            # On error, return failure
+            return GuardrailResult(
+                success=False,
+                result=None,
+                error=f"Agent guardrail validation error: {str(e)}"
+            )
+
+    def _apply_guardrail_with_retry(self, response_text, prompt, temperature=0.2, tools=None):
+        """Apply guardrail validation with retry logic.
+        
+        Args:
+            response_text: The response to validate
+            prompt: Original prompt for regeneration if needed
+            temperature: Temperature for regeneration
+            tools: Tools for regeneration
+            
+        Returns:
+            str: The validated response text or None if validation fails after retries
+        """
+        if not self._guardrail_fn:
+            return response_text
+            
+        from ..main import TaskOutput
+        
+        retry_count = 0
+        current_response = response_text
+        
+        while retry_count <= self.max_guardrail_retries:
+            # Create TaskOutput object
+            task_output = TaskOutput(
+                description="Agent response output",
+                raw=current_response,
+                agent=self.name
+            )
+            
+            # Process guardrail
+            guardrail_result = self._process_guardrail(task_output)
+            
+            if guardrail_result.success:
+                logging.info(f"Agent {self.name}: Guardrail validation passed")
+                # Return the potentially modified result
+                if guardrail_result.result and hasattr(guardrail_result.result, 'raw'):
+                    return guardrail_result.result.raw
+                elif guardrail_result.result:
+                    return str(guardrail_result.result)
+                else:
+                    return current_response
+            
+            # Guardrail failed
+            if retry_count >= self.max_guardrail_retries:
+                raise Exception(
+                    f"Agent {self.name} response failed guardrail validation after {self.max_guardrail_retries} retries. "
+                    f"Last error: {guardrail_result.error}"
+                )
+            
+            retry_count += 1
+            logging.warning(f"Agent {self.name}: Guardrail validation failed (retry {retry_count}/{self.max_guardrail_retries}): {guardrail_result.error}")
+            
+            # Regenerate response for retry
+            try:
+                retry_prompt = f"{prompt}\n\nNote: Previous response failed validation due to: {guardrail_result.error}. Please provide an improved response."
+                response = self._chat_completion([{"role": "user", "content": retry_prompt}], temperature, tools)
+                if response and response.choices:
+                    current_response = response.choices[0].message.content.strip()
+                else:
+                    raise Exception("Failed to generate retry response")
+            except Exception as e:
+                logging.error(f"Agent {self.name}: Error during guardrail retry: {e}")
+                # If we can't regenerate, fail the guardrail
+                raise Exception(
+                    f"Agent {self.name} guardrail retry failed: {e}"
+                )
+        
+        return current_response
+
     def generate_task(self) -> 'Task':
         """Generate a Task object from the agent's instructions"""
         from ..task.task import Task
@@ -788,69 +1027,92 @@ Your Goal: {self.goal}
                     )
             else:
                 # Use the standard OpenAI client approach
-                if stream:
-                    # Process as streaming response with formatted tools
-                    final_response = self._process_stream_response(
-                        messages, 
-                        temperature, 
-                        start_time, 
-                        formatted_tools=formatted_tools if formatted_tools else None,
-                        reasoning_steps=reasoning_steps
-                    )
-                else:
-                    # Process as regular non-streaming response
-                    final_response = client.chat.completions.create(
-                        model=self.llm,
-                        messages=messages,
-                        temperature=temperature,
-                        tools=formatted_tools if formatted_tools else None,
-                        stream=False
-                    )
+                # Continue tool execution loop until no more tool calls are needed
+                max_iterations = 10  # Prevent infinite loops
+                iteration_count = 0
+                
+                while iteration_count < max_iterations:
+                    if stream:
+                        # Process as streaming response with formatted tools
+                        final_response = self._process_stream_response(
+                            messages, 
+                            temperature, 
+                            start_time, 
+                            formatted_tools=formatted_tools if formatted_tools else None,
+                            reasoning_steps=reasoning_steps
+                        )
+                    else:
+                        # Process as regular non-streaming response
+                        final_response = client.chat.completions.create(
+                            model=self.llm,
+                            messages=messages,
+                            temperature=temperature,
+                            tools=formatted_tools if formatted_tools else None,
+                            stream=False
+                        )
 
-            tool_calls = getattr(final_response.choices[0].message, 'tool_calls', None)
+                    tool_calls = getattr(final_response.choices[0].message, 'tool_calls', None)
 
-            if tool_calls:
-                messages.append({
-                    "role": "assistant", 
-                    "content": final_response.choices[0].message.content,
-                    "tool_calls": tool_calls
-                })
+                    if tool_calls:
+                        messages.append({
+                            "role": "assistant", 
+                            "content": final_response.choices[0].message.content,
+                            "tool_calls": tool_calls
+                        })
 
-                for tool_call in tool_calls:
-                    function_name = tool_call.function.name
-                    arguments = json.loads(tool_call.function.arguments)
+                        for tool_call in tool_calls:
+                            function_name = tool_call.function.name
+                            arguments = json.loads(tool_call.function.arguments)
 
-                    if self.verbose:
-                        display_tool_call(f"Agent {self.name} is calling function '{function_name}' with arguments: {arguments}")
+                            if self.verbose:
+                                display_tool_call(f"Agent {self.name} is calling function '{function_name}' with arguments: {arguments}")
 
-                    tool_result = self.execute_tool(function_name, arguments)
-                    results_str = json.dumps(tool_result) if tool_result else "Function returned an empty output"
+                            tool_result = self.execute_tool(function_name, arguments)
+                            results_str = json.dumps(tool_result) if tool_result else "Function returned an empty output"
 
-                    if self.verbose:
-                        display_tool_call(f"Function '{function_name}' returned: {results_str}")
+                            if self.verbose:
+                                display_tool_call(f"Function '{function_name}' returned: {results_str}")
 
-                    messages.append({
-                        "role": "tool",
-                        "tool_call_id": tool_call.id,
-                        "content": results_str
-                    })
+                            messages.append({
+                                "role": "tool",
+                                "tool_call_id": tool_call.id,
+                                "content": results_str
+                            })
 
-                # Get final response after tool calls
-                if stream:
-                    final_response = self._process_stream_response(
-                        messages, 
-                        temperature, 
-                        start_time,
-                        formatted_tools=formatted_tools if formatted_tools else None,
-                        reasoning_steps=reasoning_steps
-                    )
-                else:
-                    final_response = client.chat.completions.create(
-                        model=self.llm,
-                        messages=messages,
-                        temperature=temperature,
-                        stream=False
-                    )
+                        # Check if we should continue (for tools like sequential thinking)
+                        should_continue = False
+                        for tool_call in tool_calls:
+                            function_name = tool_call.function.name
+                            arguments = json.loads(tool_call.function.arguments)
+                            
+                            # For sequential thinking tool, check if nextThoughtNeeded is True
+                            if function_name == "sequentialthinking" and arguments.get("nextThoughtNeeded", False):
+                                should_continue = True
+                                break
+
+                        if not should_continue:
+                            # Get final response after tool calls
+                            if stream:
+                                final_response = self._process_stream_response(
+                                    messages, 
+                                    temperature, 
+                                    start_time,
+                                    formatted_tools=formatted_tools if formatted_tools else None,
+                                    reasoning_steps=reasoning_steps
+                                )
+                            else:
+                                final_response = client.chat.completions.create(
+                                    model=self.llm,
+                                    messages=messages,
+                                    temperature=temperature,
+                                    stream=False
+                                )
+                            break
+                        
+                        iteration_count += 1
+                    else:
+                        # No tool calls, we're done
+                        break
 
             return final_response
 
@@ -944,7 +1206,13 @@ Your Goal: {self.goal}
                     total_time = time.time() - start_time
                     logging.debug(f"Agent.chat completed in {total_time:.2f} seconds")
 
-                return response_text
+                # Apply guardrail validation for custom LLM response
+                try:
+                    validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                    return validated_response
+                except Exception as e:
+                    logging.error(f"Agent {self.name}: Guardrail validation failed for custom LLM: {e}")
+                    return None
             except Exception as e:
                 display_error(f"Error in LLM chat: {e}")
                 return None
@@ -1032,12 +1300,24 @@ Your Goal: {self.goal}
                         display_interaction(original_prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
                         # Return only reasoning content if reasoning_steps is True
                         if reasoning_steps and hasattr(response.choices[0].message, 'reasoning_content'):
-                            return response.choices[0].message.reasoning_content
-                        return response_text
+                            # Apply guardrail to reasoning content
+                            try:
+                                validated_reasoning = self._apply_guardrail_with_retry(response.choices[0].message.reasoning_content, original_prompt, temperature, tools)
+                                return validated_reasoning
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed for reasoning content: {e}")
+                                return None
+                        # Apply guardrail to regular response
+                        try:
+                            validated_response = self._apply_guardrail_with_retry(response_text, original_prompt, temperature, tools)
+                            return validated_response
+                        except Exception as e:
+                            logging.error(f"Agent {self.name}: Guardrail validation failed: {e}")
+                            return None
 
                     reflection_prompt = f"""
 Reflect on your previous response: '{response_text}'.
-Identify any flaws, improvements, or actions.
+{self.reflect_prompt if self.reflect_prompt else "Identify any flaws, improvements, or actions."}
 Provide a "satisfactory" status ('yes' or 'no').
 Output MUST be JSON with 'reflection' and 'satisfactory'.
                     """
@@ -1066,7 +1346,13 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                             self.chat_history.append({"role": "user", "content": prompt})
                             self.chat_history.append({"role": "assistant", "content": response_text})
                             display_interaction(prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
-                            return response_text
+                            # Apply guardrail validation after satisfactory reflection
+                            try:
+                                validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                                return validated_response
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed after reflection: {e}")
+                                return None
 
                         # Check if we've hit max reflections
                         if reflection_count >= self.max_reflect - 1:
@@ -1075,7 +1361,13 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                             self.chat_history.append({"role": "user", "content": prompt})
                             self.chat_history.append({"role": "assistant", "content": response_text})
                             display_interaction(prompt, response_text, markdown=self.markdown, generation_time=time.time() - start_time, console=self.console)
-                            return response_text
+                            # Apply guardrail validation after max reflections
+                            try:
+                                validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+                                return validated_response
+                            except Exception as e:
+                                logging.error(f"Agent {self.name}: Guardrail validation failed after max reflections: {e}")
+                                return None
 
                         logging.debug(f"{self.name} reflection count {reflection_count + 1}, continuing reflection process")
                         messages.append({"role": "user", "content": "Now regenerate your response using the reflection you made"})
@@ -1099,8 +1391,16 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
         if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
             total_time = time.time() - start_time
             logging.debug(f"Agent.chat completed in {total_time:.2f} seconds")
-            
-        return response_text
+        
+        # Apply guardrail validation before returning    
+        try:
+            validated_response = self._apply_guardrail_with_retry(response_text, prompt, temperature, tools)
+            return validated_response
+        except Exception as e:
+            logging.error(f"Agent {self.name}: Guardrail validation failed: {e}")
+            if self.verbose:
+                display_error(f"Guardrail validation failed: {e}", console=self.console)
+            return None
 
     def clean_json_output(self, output: str) -> str:
         """Clean and extract JSON from response text."""
@@ -1115,7 +1415,7 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
         return cleaned  
 
     async def achat(self, prompt: str, temperature=0.2, tools=None, output_json=None, output_pydantic=None, reasoning_steps=False):
-        """Async version of chat method. TODO: Requires Syncing with chat method.""" 
+        """Async version of chat method with self-reflection support.""" 
         # Log all parameter values when in debug mode
         if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
             param_info = {
@@ -1288,10 +1588,79 @@ Your Goal: {self.goal}
                             messages=messages,
                             temperature=temperature
                         )
+                        
+                        response_text = response.choices[0].message.content
+                        
+                        # Handle self-reflection if enabled
+                        if self.self_reflect:
+                            reflection_count = 0
+                            
+                            while True:
+                                reflection_prompt = f"""
+Reflect on your previous response: '{response_text}'.
+{self.reflect_prompt if self.reflect_prompt else "Identify any flaws, improvements, or actions."}
+Provide a "satisfactory" status ('yes' or 'no').
+Output MUST be JSON with 'reflection' and 'satisfactory'.
+                                """
+                                
+                                # Add reflection prompt to messages
+                                reflection_messages = messages + [
+                                    {"role": "assistant", "content": response_text},
+                                    {"role": "user", "content": reflection_prompt}
+                                ]
+                                
+                                try:
+                                    reflection_response = await async_client.beta.chat.completions.parse(
+                                        model=self.reflect_llm if self.reflect_llm else self.llm,
+                                        messages=reflection_messages,
+                                        temperature=temperature,
+                                        response_format=ReflectionOutput
+                                    )
+                                    
+                                    reflection_output = reflection_response.choices[0].message.parsed
+                                    
+                                    if self.verbose:
+                                        display_self_reflection(f"Agent {self.name} self reflection (using {self.reflect_llm if self.reflect_llm else self.llm}): reflection='{reflection_output.reflection}' satisfactory='{reflection_output.satisfactory}'", console=self.console)
+                                    
+                                    # Only consider satisfactory after minimum reflections
+                                    if reflection_output.satisfactory == "yes" and reflection_count >= self.min_reflect - 1:
+                                        if self.verbose:
+                                            display_self_reflection("Agent marked the response as satisfactory after meeting minimum reflections", console=self.console)
+                                        break
+                                    
+                                    # Check if we've hit max reflections
+                                    if reflection_count >= self.max_reflect - 1:
+                                        if self.verbose:
+                                            display_self_reflection("Maximum reflection count reached, returning current response", console=self.console)
+                                        break
+                                    
+                                    # Regenerate response based on reflection
+                                    regenerate_messages = reflection_messages + [
+                                        {"role": "assistant", "content": f"Self Reflection: {reflection_output.reflection} Satisfactory?: {reflection_output.satisfactory}"},
+                                        {"role": "user", "content": "Now regenerate your response using the reflection you made"}
+                                    ]
+                                    
+                                    new_response = await async_client.chat.completions.create(
+                                        model=self.llm,
+                                        messages=regenerate_messages,
+                                        temperature=temperature
+                                    )
+                                    response_text = new_response.choices[0].message.content
+                                    reflection_count += 1
+                                    
+                                except Exception as e:
+                                    if self.verbose:
+                                        display_error(f"Error in parsing self-reflection json {e}. Retrying", console=self.console)
+                                    logging.error("Reflection parsing failed.", exc_info=True)
+                                    reflection_count += 1
+                                    if reflection_count >= self.max_reflect:
+                                        break
+                                    continue
+                        
                         if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
                             total_time = time.time() - start_time
                             logging.debug(f"Agent.achat completed in {total_time:.2f} seconds")
-                        return response.choices[0].message.content
+                        return response_text
                 except Exception as e:
                     display_error(f"Error in chat completion: {e}")
                     if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
@@ -1670,6 +2039,7 @@ Your Goal: {self.goal}
                 import threading
                 import time
                 import inspect
+                import asyncio  # Import asyncio in the MCP scope
                 # logging is already imported at the module level
                 
             except ImportError as e:

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

@@ -0,0 +1,11 @@
+"""
+Guardrails module for PraisonAI Agents.
+
+This module provides validation and safety mechanisms for task outputs,
+including both function-based and LLM-based guardrails.
+"""
+
+from .guardrail_result import GuardrailResult
+from .llm_guardrail import LLMGuardrail
+
+__all__ = ["GuardrailResult", "LLMGuardrail"]

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

@@ -0,0 +1,43 @@
+"""
+Guardrail result classes for PraisonAI Agents.
+
+This module provides the result types for guardrail validation,
+following the same pattern as CrewAI for consistency.
+"""
+
+from typing import Any, Tuple, Union
+from pydantic import BaseModel, Field
+from ..main import TaskOutput
+
+
+class GuardrailResult(BaseModel):
+    """Result of a guardrail validation."""
+    
+    success: bool = Field(description="Whether the guardrail check passed")
+    result: Union[str, TaskOutput, None] = Field(description="The result if modified, or None if unchanged")
+    error: str = Field(default="", description="Error message if validation failed")
+    
+    @classmethod
+    def from_tuple(cls, result: Tuple[bool, Any]) -> "GuardrailResult":
+        """Create a GuardrailResult from a tuple returned by a guardrail function.
+        
+        Args:
+            result: Tuple of (success, result_or_error)
+            
+        Returns:
+            GuardrailResult: The structured result
+        """
+        success, data = result
+        
+        if success:
+            return cls(
+                success=True,
+                result=data,
+                error=""
+            )
+        else:
+            return cls(
+                success=False,
+                result=None,
+                error=str(data) if data else "Guardrail validation failed"
+            )

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

@@ -0,0 +1,88 @@
+"""
+LLM-based guardrail implementation for PraisonAI Agents.
+
+This module provides LLM-powered guardrails that can validate task outputs
+using natural language descriptions, similar to CrewAI's implementation.
+"""
+
+import logging
+from typing import Any, Tuple, Union, Optional
+from pydantic import BaseModel
+from ..main import TaskOutput
+
+
+class LLMGuardrail:
+    """An LLM-powered guardrail that validates task outputs using natural language."""
+    
+    def __init__(self, description: str, llm: Any = None):
+        """Initialize the LLM guardrail.
+        
+        Args:
+            description: Natural language description of what to validate
+            llm: The LLM instance to use for validation
+        """
+        self.description = description
+        self.llm = llm
+        self.logger = logging.getLogger(__name__)
+    
+    def __call__(self, task_output: TaskOutput) -> Tuple[bool, Union[str, TaskOutput]]:
+        """Validate the task output using the LLM.
+        
+        Args:
+            task_output: The task output to validate
+            
+        Returns:
+            Tuple of (success, result) where result is the output or error message
+        """
+        try:
+            if not self.llm:
+                self.logger.warning("No LLM provided for guardrail validation")
+                return True, task_output
+            
+            # Create validation prompt
+            validation_prompt = f"""
+You are a quality assurance validator. Your task is to evaluate the following output against specific criteria.
+
+Validation Criteria: {self.description}
+
+Output to Validate:
+{task_output.raw}
+
+Please evaluate if this output meets the criteria. Respond with:
+1. "PASS" if the output meets all criteria
+2. "FAIL: [specific reason]" if the output does not meet criteria
+
+Your response:"""
+
+            # Get LLM response
+            if hasattr(self.llm, 'chat'):
+                # For Agent's LLM interface
+                response = self.llm.chat(validation_prompt, temperature=0.1)
+            elif hasattr(self.llm, 'get_response'):
+                # For custom LLM instances
+                response = self.llm.get_response(validation_prompt, temperature=0.1)
+            elif callable(self.llm):
+                # For simple callable LLMs
+                response = self.llm(validation_prompt)
+            else:
+                self.logger.error(f"Unsupported LLM type: {type(self.llm)}")
+                return True, task_output
+            
+            # Parse response
+            response = str(response).strip()
+            
+            if response.upper().startswith("PASS"):
+                return True, task_output
+            elif response.upper().startswith("FAIL"):
+                # Extract the reason
+                reason = response[5:].strip(": ")
+                return False, f"Guardrail validation failed: {reason}"
+            else:
+                # Unclear response, log and pass through
+                self.logger.warning(f"Unclear guardrail response: {response}")
+                return True, task_output
+                
+        except Exception as e:
+            self.logger.error(f"Error in LLM guardrail validation: {str(e)}")
+            # On error, pass through the original output
+            return True, task_output

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

@@ -1,5 +1,9 @@
 import logging
 import warnings
+import os
+
+# Disable litellm telemetry before any imports
+os.environ["LITELLM_TELEMETRY"] = "False"
 
 # Suppress all relevant logs at module level
 logging.getLogger("litellm").setLevel(logging.ERROR)
@@ -17,4 +21,11 @@ logging.basicConfig(level=logging.WARNING)
 # Import after suppressing warnings
 from .llm import LLM, LLMContextLengthExceededException
 
+# Ensure telemetry is disabled after import as well
+try:
+    import litellm
+    litellm.telemetry = False
+except ImportError:
+    pass
+
 __all__ = ["LLM", "LLMContextLengthExceededException"]

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

@@ -17,6 +17,9 @@ from ..main import (
 from rich.console import Console
 from rich.live import Live
 
+# Disable litellm telemetry before any imports
+os.environ["LITELLM_TELEMETRY"] = "False"
+
 # TODO: Include in-build tool calling in LLM class
 # TODO: Restructure so that duplicate calls are not made (Sync with agent.py)
 class LLMContextLengthExceededException(Exception):
@@ -108,6 +111,9 @@ class LLM:
     ):
         try:
             import litellm
+            # Disable telemetry
+            litellm.telemetry = False
+            
             # Set litellm options globally
             litellm.set_verbose = False
             litellm.success_callback = []
@@ -413,24 +419,30 @@ class LLM:
             start_time = time.time()
             reflection_count = 0
 
-            while True:
-                try:
-                    if verbose:
-                        display_text = prompt
-                        if isinstance(prompt, list):
-                            display_text = next((item["text"] for item in prompt if item["type"] == "text"), "")
-                        
-                        if display_text and str(display_text).strip():
-                            display_instruction(
-                                f"Agent {agent_name} is processing prompt: {display_text}",
-                                console=console,
-                                agent_name=agent_name,
-                                agent_role=agent_role,
-                                agent_tools=agent_tools
-                            )
+            # Display initial instruction once
+            if verbose:
+                display_text = prompt
+                if isinstance(prompt, list):
+                    display_text = next((item["text"] for item in prompt if item["type"] == "text"), "")
+                
+                if display_text and str(display_text).strip():
+                    display_instruction(
+                        f"Agent {agent_name} is processing prompt: {display_text}",
+                        console=console,
+                        agent_name=agent_name,
+                        agent_role=agent_role,
+                        agent_tools=agent_tools
+                    )
 
+            # Sequential tool calling loop - similar to agent.py
+            max_iterations = 10  # Prevent infinite loops
+            iteration_count = 0
+            final_response_text = ""
+
+            while iteration_count < max_iterations:
+                try:
                     # Get response from LiteLLM
-                    start_time = time.time()
+                    current_time = time.time()
 
                     # If reasoning_steps is True, do a single non-streaming call
                     if reasoning_steps:
@@ -445,6 +457,7 @@ class LLM:
                         )
                         reasoning_content = resp["choices"][0]["message"].get("provider_specific_fields", {}).get("reasoning_content")
                         response_text = resp["choices"][0]["message"]["content"]
+                        final_response = resp
                         
                         # Optionally display reasoning if present
                         if verbose and reasoning_content:
@@ -452,7 +465,7 @@ class LLM:
                                 original_prompt,
                                 f"Reasoning:\n{reasoning_content}\n\nAnswer:\n{response_text}",
                                 markdown=markdown,
-                                generation_time=time.time() - start_time,
+                                generation_time=time.time() - current_time,
                                 console=console
                             )
                         else:
@@ -460,14 +473,14 @@ class LLM:
                                 original_prompt,
                                 response_text,
                                 markdown=markdown,
-                                generation_time=time.time() - start_time,
+                                generation_time=time.time() - current_time,
                                 console=console
                             )
                     
                     # Otherwise do the existing streaming approach
                     else:
                         if verbose:
-                            with Live(display_generating("", start_time), console=console, refresh_per_second=4) as live:
+                            with Live(display_generating("", current_time), console=console, refresh_per_second=4) as live:
                                 response_text = ""
                                 for chunk in litellm.completion(
                                     **self._build_completion_params(
@@ -481,7 +494,7 @@ class LLM:
                                     if chunk and chunk.choices and chunk.choices[0].delta.content:
                                         content = chunk.choices[0].delta.content
                                         response_text += content
-                                        live.update(display_generating(response_text, start_time))
+                                        live.update(display_generating(response_text, current_time))
                         else:
                             # Non-verbose mode, just collect the response
                             response_text = ""
@@ -499,20 +512,20 @@ class LLM:
 
                         response_text = response_text.strip()
 
-                    # Get final completion to check for tool calls
-                    final_response = litellm.completion(
-                        **self._build_completion_params(
-                            messages=messages,
-                            tools=formatted_tools,
-                            temperature=temperature,
-                            stream=False,  # No streaming for tool call check
-                            **kwargs
+                        # Get final completion to check for tool calls
+                        final_response = litellm.completion(
+                            **self._build_completion_params(
+                                messages=messages,
+                                tools=formatted_tools,
+                                temperature=temperature,
+                                stream=False,  # No streaming for tool call check
+                                **kwargs
+                            )
                         )
-                    )
                     
                     tool_calls = final_response["choices"][0]["message"].get("tool_calls")
                     
-                    # Handle tool calls
+                    # Handle tool calls - Sequential tool calling logic
                     if tool_calls and execute_tool_fn:
                         # Convert tool_calls to a serializable format for all providers
                         serializable_tool_calls = []
@@ -535,6 +548,7 @@ class LLM:
                             "tool_calls": serializable_tool_calls
                         })
                         
+                        should_continue = False
                         for tool_call in tool_calls:
                             # Handle both object and dict access patterns
                             if isinstance(tool_call, dict):
@@ -574,6 +588,18 @@ class LLM:
                                 "content": json.dumps(tool_result) if tool_result is not None else "Function returned an empty output"
                             })
 
+                            # Check if we should continue (for tools like sequential thinking)
+                            # This mimics the logic from agent.py lines 1004-1007
+                            if function_name == "sequentialthinking" and arguments.get("nextThoughtNeeded", False):
+                                should_continue = True
+                        
+                        # If we should continue, increment iteration and continue loop
+                        if should_continue:
+                            iteration_count += 1
+                            continue
+
+                        # If we reach here, no more tool calls needed - get final response
+                        # Make one more call to get the final summary response
                         # Special handling for Ollama models that don't automatically process tool results
                         if self.model and self.model.startswith("ollama/") and tool_result:
                             # For Ollama models, we need to explicitly ask the model to process the tool results
@@ -666,115 +692,141 @@ class LLM:
                         else:
                             # Get response after tool calls with streaming
                             if verbose:
-                                with Live(display_generating("", start_time), console=console, refresh_per_second=4) as live:
-                                    response_text = ""
+                                with Live(display_generating("", current_time), console=console, refresh_per_second=4) as live:
+                                    final_response_text = ""
                                     for chunk in litellm.completion(
                                         **self._build_completion_params(
                                             messages=messages,
+                                            tools=formatted_tools,
                                             temperature=temperature,
-                                            stream=True
+                                            stream=True,
+                                            **kwargs
                                         )
                                     ):
                                         if chunk and chunk.choices and chunk.choices[0].delta.content:
                                             content = chunk.choices[0].delta.content
-                                            response_text += content
-                                            live.update(display_generating(response_text, start_time))
+                                            final_response_text += content
+                                            live.update(display_generating(final_response_text, current_time))
                             else:
-                                response_text = ""
+                                final_response_text = ""
                                 for chunk in litellm.completion(
                                     **self._build_completion_params(
                                         messages=messages,
+                                        tools=formatted_tools,
                                         temperature=temperature,
-                                        stream=True
+                                        stream=True,
+                                        **kwargs
                                     )
                                 ):
                                     if chunk and chunk.choices and chunk.choices[0].delta.content:
-                                        response_text += chunk.choices[0].delta.content
-
-                            response_text = response_text.strip()
-
-                    # Handle output formatting
-                    if output_json or output_pydantic:
-                        self.chat_history.append({"role": "user", "content": original_prompt})
-                        self.chat_history.append({"role": "assistant", "content": response_text})
+                                        final_response_text += chunk.choices[0].delta.content
+                            
+                            final_response_text = final_response_text.strip()
+                        
+                        # Display final response
                         if verbose:
-                            display_interaction(original_prompt, response_text, markdown=markdown,
-                                             generation_time=time.time() - start_time, console=console)
-                        return response_text
+                            display_interaction(
+                                original_prompt,
+                                final_response_text,
+                                markdown=markdown,
+                                generation_time=time.time() - start_time,
+                                console=console
+                            )
+                        
+                        return final_response_text
+                    else:
+                        # No tool calls, we're done with this iteration
+                        break
+                        
+                except Exception as e:
+                    logging.error(f"Error in LLM iteration {iteration_count}: {e}")
+                    break
+                    
+            # End of while loop - return final response
+            if final_response_text:
+                return final_response_text
+            
+            # No tool calls were made in this iteration, return the response
+            if verbose:
+                display_interaction(
+                    original_prompt,
+                    response_text,
+                    markdown=markdown,
+                    generation_time=time.time() - start_time,
+                    console=console
+                )
+            
+            response_text = response_text.strip()
+            
+            # Handle output formatting
+            if output_json or output_pydantic:
+                self.chat_history.append({"role": "user", "content": original_prompt})
+                self.chat_history.append({"role": "assistant", "content": response_text})
+                if verbose:
+                    display_interaction(original_prompt, response_text, markdown=markdown,
+                                     generation_time=time.time() - start_time, console=console)
+                return response_text
 
-                    if not self_reflect:
-                        if verbose:
-                            display_interaction(original_prompt, response_text, markdown=markdown,
-                                             generation_time=time.time() - start_time, console=console)
-                        # Return reasoning content if reasoning_steps is True
-                        if reasoning_steps and reasoning_content:
-                            return reasoning_content
-                        return response_text
+            if not self_reflect:
+                if verbose:
+                    display_interaction(original_prompt, response_text, markdown=markdown,
+                                     generation_time=time.time() - start_time, console=console)
+                # Return reasoning content if reasoning_steps is True
+                if reasoning_steps and reasoning_content:
+                    return reasoning_content
+                return response_text
 
-                    # Handle self-reflection
-                    reflection_prompt = f"""
+            # Handle self-reflection loop
+            while reflection_count < max_reflect:
+                # Handle self-reflection
+                reflection_prompt = f"""
 Reflect on your previous response: '{response_text}'.
 Identify any flaws, improvements, or actions.
 Provide a "satisfactory" status ('yes' or 'no').
 Output MUST be JSON with 'reflection' and 'satisfactory'.
-                    """
-                    
-                    reflection_messages = messages + [
-                        {"role": "assistant", "content": response_text},
-                        {"role": "user", "content": reflection_prompt}
-                    ]
+                """
+                
+                reflection_messages = messages + [
+                    {"role": "assistant", "content": response_text},
+                    {"role": "user", "content": reflection_prompt}
+                ]
 
-                    # If reasoning_steps is True, do a single non-streaming call to capture reasoning
-                    if reasoning_steps:
-                        reflection_resp = litellm.completion(
-                            **self._build_completion_params(
-                                messages=reflection_messages,
-                                temperature=temperature,
-                                stream=False,  # Force non-streaming
-                                response_format={"type": "json_object"},
-                                **{k:v for k,v in kwargs.items() if k != 'reasoning_steps'}
-                            )
+                # If reasoning_steps is True, do a single non-streaming call to capture reasoning
+                if reasoning_steps:
+                    reflection_resp = litellm.completion(
+                        **self._build_completion_params(
+                            messages=reflection_messages,
+                            temperature=temperature,
+                            stream=False,  # Force non-streaming
+                            response_format={"type": "json_object"},
+                            **{k:v for k,v in kwargs.items() if k != 'reasoning_steps'}
                         )
-                        # Grab reflection text and optional reasoning
-                        reasoning_content = reflection_resp["choices"][0]["message"].get("provider_specific_fields", {}).get("reasoning_content")
-                        reflection_text = reflection_resp["choices"][0]["message"]["content"]
+                    )
+                    # Grab reflection text and optional reasoning
+                    reasoning_content = reflection_resp["choices"][0]["message"].get("provider_specific_fields", {}).get("reasoning_content")
+                    reflection_text = reflection_resp["choices"][0]["message"]["content"]
 
-                        # Optionally display reasoning if present
-                        if verbose and reasoning_content:
-                            display_interaction(
-                                "Reflection reasoning:",
-                                f"{reasoning_content}\n\nReflection result:\n{reflection_text}",
-                                markdown=markdown,
-                                generation_time=time.time() - start_time,
-                                console=console
-                            )
-                        elif verbose:
-                            display_interaction(
-                                "Self-reflection (non-streaming):",
-                                reflection_text,
-                                markdown=markdown,
-                                generation_time=time.time() - start_time,
-                                console=console
-                            )
-                    else:
-                        # Existing streaming approach
-                        if verbose:
-                            with Live(display_generating("", start_time), console=console, refresh_per_second=4) as live:
-                                reflection_text = ""
-                                for chunk in litellm.completion(
-                                    **self._build_completion_params(
-                                        messages=reflection_messages,
-                                        temperature=temperature,
-                                        stream=True,
-                                        response_format={"type": "json_object"},
-                                        **{k:v for k,v in kwargs.items() if k != 'reasoning_steps'}
-                                    )
-                                ):
-                                    if chunk and chunk.choices and chunk.choices[0].delta.content:
-                                        content = chunk.choices[0].delta.content
-                                        reflection_text += content
-                                        live.update(display_generating(reflection_text, start_time))
-                        else:
+                    # Optionally display reasoning if present
+                    if verbose and reasoning_content:
+                        display_interaction(
+                            "Reflection reasoning:",
+                            f"{reasoning_content}\n\nReflection result:\n{reflection_text}",
+                            markdown=markdown,
+                            generation_time=time.time() - start_time,
+                            console=console
+                        )
+                    elif verbose:
+                        display_interaction(
+                            "Self-reflection (non-streaming):",
+                            reflection_text,
+                            markdown=markdown,
+                            generation_time=time.time() - start_time,
+                            console=console
+                        )
+                else:
+                    # Existing streaming approach
+                    if verbose:
+                        with Live(display_generating("", start_time), console=console, refresh_per_second=4) as live:
                             reflection_text = ""
                             for chunk in litellm.completion(
                                 **self._build_completion_params(
@@ -786,48 +838,102 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                                 )
                             ):
                                 if chunk and chunk.choices and chunk.choices[0].delta.content:
-                                    reflection_text += chunk.choices[0].delta.content
-
-                    try:
-                        reflection_data = json.loads(reflection_text)
-                        satisfactory = reflection_data.get("satisfactory", "no").lower() == "yes"
-
-                        if verbose:
-                            display_self_reflection(
-                                f"Agent {agent_name} self reflection: reflection='{reflection_data['reflection']}' satisfactory='{reflection_data['satisfactory']}'",
-                                console=console
+                                    content = chunk.choices[0].delta.content
+                                    reflection_text += content
+                                    live.update(display_generating(reflection_text, start_time))
+                    else:
+                        reflection_text = ""
+                        for chunk in litellm.completion(
+                            **self._build_completion_params(
+                                messages=reflection_messages,
+                                temperature=temperature,
+                                stream=True,
+                                response_format={"type": "json_object"},
+                                **{k:v for k,v in kwargs.items() if k != 'reasoning_steps'}
                             )
+                        ):
+                            if chunk and chunk.choices and chunk.choices[0].delta.content:
+                                reflection_text += chunk.choices[0].delta.content
 
-                        if satisfactory and reflection_count >= min_reflect - 1:
-                            if verbose:
-                                display_interaction(prompt, response_text, markdown=markdown,
-                                                 generation_time=time.time() - start_time, console=console)
-                            return response_text
+                try:
+                    reflection_data = json.loads(reflection_text)
+                    satisfactory = reflection_data.get("satisfactory", "no").lower() == "yes"
 
-                        if reflection_count >= max_reflect - 1:
-                            if verbose:
-                                display_interaction(prompt, response_text, markdown=markdown,
-                                                 generation_time=time.time() - start_time, console=console)
-                            return response_text
+                    if verbose:
+                        display_self_reflection(
+                            f"Agent {agent_name} self reflection: reflection='{reflection_data['reflection']}' satisfactory='{reflection_data['satisfactory']}'",
+                            console=console
+                        )
 
-                        reflection_count += 1
-                        messages.extend([
-                            {"role": "assistant", "content": response_text},
-                            {"role": "user", "content": reflection_prompt},
-                            {"role": "assistant", "content": reflection_text},
-                            {"role": "user", "content": "Now regenerate your response using the reflection you made"}
-                        ])
-                        continue
+                    if satisfactory and reflection_count >= min_reflect - 1:
+                        if verbose:
+                            display_interaction(prompt, response_text, markdown=markdown,
+                                             generation_time=time.time() - start_time, console=console)
+                        return response_text
 
-                    except json.JSONDecodeError:
-                        reflection_count += 1
-                        if reflection_count >= max_reflect:
-                            return response_text
-                        continue
+                    if reflection_count >= max_reflect - 1:
+                        if verbose:
+                            display_interaction(prompt, response_text, markdown=markdown,
+                                             generation_time=time.time() - start_time, console=console)
+                        return response_text
 
+                    reflection_count += 1
+                    messages.extend([
+                        {"role": "assistant", "content": response_text},
+                        {"role": "user", "content": reflection_prompt},
+                        {"role": "assistant", "content": reflection_text},
+                        {"role": "user", "content": "Now regenerate your response using the reflection you made"}
+                    ])
+                    
+                    # Get new response after reflection
+                    if verbose:
+                        with Live(display_generating("", time.time()), console=console, refresh_per_second=4) as live:
+                            response_text = ""
+                            for chunk in litellm.completion(
+                                **self._build_completion_params(
+                                    messages=messages,
+                                    temperature=temperature,
+                                    stream=True,
+                                    **kwargs
+                                )
+                            ):
+                                if chunk and chunk.choices and chunk.choices[0].delta.content:
+                                    content = chunk.choices[0].delta.content
+                                    response_text += content
+                                    live.update(display_generating(response_text, time.time()))
+                    else:
+                        response_text = ""
+                        for chunk in litellm.completion(
+                            **self._build_completion_params(
+                                messages=messages,
+                                temperature=temperature,
+                                stream=True,
+                                **kwargs
+                            )
+                        ):
+                            if chunk and chunk.choices and chunk.choices[0].delta.content:
+                                response_text += chunk.choices[0].delta.content
+                    
+                    response_text = response_text.strip()
+                    continue
+
+                except json.JSONDecodeError:
+                    reflection_count += 1
+                    if reflection_count >= max_reflect:
+                        if verbose:
+                            display_interaction(prompt, response_text, markdown=markdown,
+                                             generation_time=time.time() - start_time, console=console)
+                        return response_text
+                    continue
                 except Exception as e:
                     display_error(f"Error in LLM response: {str(e)}")
                     return None
+            
+            # If we've exhausted reflection attempts
+            if verbose:
+                display_interaction(prompt, response_text, markdown=markdown,
+                                 generation_time=time.time() - start_time, console=console)
+            return response_text
 
         except Exception as error:
             display_error(f"Error in get_response: {str(error)}")

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

@@ -6,6 +6,9 @@ import shutil
 from typing import Any, Dict, List, Optional, Union, Literal
 import logging
 
+# Disable litellm telemetry before any imports
+os.environ["LITELLM_TELEMETRY"] = "False"
+
 # Set up logger
 logger = logging.getLogger(__name__)
 
@@ -29,6 +32,13 @@ try:
 except ImportError:
     OPENAI_AVAILABLE = False
 
+try:
+    import litellm
+    litellm.telemetry = False  # Disable telemetry
+    LITELLM_AVAILABLE = True
+except ImportError:
+    LITELLM_AVAILABLE = False
+
 
 
 
@@ -340,14 +350,28 @@ class Memory:
             
         elif self.use_rag and hasattr(self, "chroma_col"):
             try:
-                from openai import OpenAI
-                client = OpenAI()
-                
-                response = client.embeddings.create(
-                    input=query,
-                    model="text-embedding-3-small"
-                )
-                query_embedding = response.data[0].embedding
+                if LITELLM_AVAILABLE:
+                    # Use LiteLLM for consistency with the rest of the codebase
+                    import litellm
+                    
+                    response = litellm.embedding(
+                        model="text-embedding-3-small",
+                        input=query
+                    )
+                    query_embedding = response.data[0]["embedding"]
+                elif OPENAI_AVAILABLE:
+                    # Fallback to OpenAI client
+                    from openai import OpenAI
+                    client = OpenAI()
+                    
+                    response = client.embeddings.create(
+                        input=query,
+                        model="text-embedding-3-small"
+                    )
+                    query_embedding = response.data[0].embedding
+                else:
+                    self._log_verbose("Neither litellm nor openai available for embeddings", logging.WARNING)
+                    return []
                 
                 resp = self.chroma_col.query(
                     query_embeddings=[query_embedding],
@@ -464,19 +488,39 @@ class Memory:
         # Store in vector database if enabled
         if self.use_rag and hasattr(self, "chroma_col"):
             try:
-                from openai import OpenAI
-                client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))  # Ensure API key is correctly set
-                
-                logger.info("Getting embeddings from OpenAI...")
-                logger.debug(f"Embedding input text: {text}")  # Log the input text
-                
-                response = client.embeddings.create(
-                    input=text,
-                    model="text-embedding-3-small"
-                )
-                embedding = response.data[0].embedding
-                logger.info("Successfully got embeddings")
-                logger.debug(f"Received embedding of length: {len(embedding)}")  # Log embedding details
+                if LITELLM_AVAILABLE:
+                    # Use LiteLLM for consistency with the rest of the codebase
+                    import litellm
+                    
+                    logger.info("Getting embeddings from LiteLLM...")
+                    logger.debug(f"Embedding input text: {text}")
+                    
+                    response = litellm.embedding(
+                        model="text-embedding-3-small",
+                        input=text
+                    )
+                    embedding = response.data[0]["embedding"]
+                    logger.info("Successfully got embeddings from LiteLLM")
+                    logger.debug(f"Received embedding of length: {len(embedding)}")
+                    
+                elif OPENAI_AVAILABLE:
+                    # Fallback to OpenAI client
+                    from openai import OpenAI
+                    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+                    
+                    logger.info("Getting embeddings from OpenAI...")
+                    logger.debug(f"Embedding input text: {text}")
+                    
+                    response = client.embeddings.create(
+                        input=text,
+                        model="text-embedding-3-small"
+                    )
+                    embedding = response.data[0].embedding
+                    logger.info("Successfully got embeddings from OpenAI")
+                    logger.debug(f"Received embedding of length: {len(embedding)}")
+                else:
+                    logger.warning("Neither litellm nor openai available for embeddings")
+                    return
                 
                 # Sanitize metadata for ChromaDB
                 sanitized_metadata = self._sanitize_metadata(metadata)
@@ -527,15 +571,28 @@ class Memory:
 
         elif self.use_rag and hasattr(self, "chroma_col"):
             try:
-                from openai import OpenAI
-                client = OpenAI()
-                
-                # Get query embedding
-                response = client.embeddings.create(
-                    input=query,
-                    model="text-embedding-3-small"  # Using consistent model
-                )
-                query_embedding = response.data[0].embedding
+                if LITELLM_AVAILABLE:
+                    # Use LiteLLM for consistency with the rest of the codebase
+                    import litellm
+                    
+                    response = litellm.embedding(
+                        model="text-embedding-3-small",
+                        input=query
+                    )
+                    query_embedding = response.data[0]["embedding"]
+                elif OPENAI_AVAILABLE:
+                    # Fallback to OpenAI client
+                    from openai import OpenAI
+                    client = OpenAI()
+                    
+                    response = client.embeddings.create(
+                        input=query,
+                        model="text-embedding-3-small"
+                    )
+                    query_embedding = response.data[0].embedding
+                else:
+                    self._log_verbose("Neither litellm nor openai available for embeddings", logging.WARNING)
+                    return []
                 
                 # Search ChromaDB with embedding
                 resp = self.chroma_col.query(
@@ -910,18 +967,44 @@ class Memory:
         """
 
         try:
-            # Use OpenAI client from main.py
-            from ..main import client
-            
-            response = client.chat.completions.create(
-                model=llm or "gpt-4o",
-                messages=[{
-                    "role": "user", 
-                    "content": custom_prompt or default_prompt
-                }],
-                response_format={"type": "json_object"},
-                temperature=0.3
-            )
+            if LITELLM_AVAILABLE:
+                # Use LiteLLM for consistency with the rest of the codebase
+                import litellm
+                
+                # Convert model name if it's in litellm format
+                model_name = llm or "gpt-4o-mini"
+                
+                response = litellm.completion(
+                    model=model_name,
+                    messages=[{
+                        "role": "user", 
+                        "content": custom_prompt or default_prompt
+                    }],
+                    response_format={"type": "json_object"},
+                    temperature=0.3
+                )
+            elif OPENAI_AVAILABLE:
+                # Fallback to OpenAI client
+                from openai import OpenAI
+                client = OpenAI()
+                
+                response = client.chat.completions.create(
+                    model=llm or "gpt-4o-mini",
+                    messages=[{
+                        "role": "user", 
+                        "content": custom_prompt or default_prompt
+                    }],
+                    response_format={"type": "json_object"},
+                    temperature=0.3
+                )
+            else:
+                logger.error("Neither litellm nor openai available for quality calculation")
+                return {
+                    "completeness": 0.0,
+                    "relevance": 0.0,
+                    "clarity": 0.0,
+                    "accuracy": 0.0
+                }
             
             metrics = json.loads(response.choices[0].message.content)
             

src/praisonai-agents/praisonaiagents/session.py

@@ -7,6 +7,9 @@ session API for developers building stateful agent applications.
 
 import os
 import uuid
+import requests
+import json
+import time
 from typing import Any, Dict, List, Optional
 from .agent import Agent
 from .memory import Memory
@@ -22,68 +25,90 @@ class Session:
     - Memory operations (short-term, long-term, user-specific)
     - Knowledge base operations
     - Agent state management
+    - Remote agent connectivity
     
-    Example:
+    Examples:
+        # Local session with agent
         session = Session(session_id="chat_123", user_id="user_456")
+        agent = session.Agent(name="Assistant", role="Helpful AI")
         
-        # Create stateful agent
-        agent = session.Agent(
-            name="Assistant", 
-            role="Helpful AI",
-            memory=True
-        )
+        # Remote agent session (similar to Google ADK)
+        session = Session(agent_url="192.168.1.10:8000/agent")
+        response = session.chat("Hello from remote client!")
         
         # Save session state
         session.save_state({"conversation_topic": "AI research"})
-        
-        # Restore state later
-        session.restore_state()
     """
 
     def __init__(
         self, 
         session_id: Optional[str] = None,
         user_id: Optional[str] = None,
+        agent_url: Optional[str] = None,
         memory_config: Optional[Dict[str, Any]] = None,
-        knowledge_config: Optional[Dict[str, Any]] = None
+        knowledge_config: Optional[Dict[str, Any]] = None,
+        timeout: int = 30
     ):
         """
-        Initialize a new session with optional persistence.
+        Initialize a new session with optional persistence or remote agent connectivity.
         
         Args:
             session_id: Unique session identifier. Auto-generated if None.
             user_id: User identifier for user-specific memory operations.
+            agent_url: URL of remote agent for direct connectivity (e.g., "192.168.1.10:8000/agent")
             memory_config: Configuration for memory system (defaults to RAG)
-            knowledge_config: Configuration for knowledge base system
+            knowledge_config: Configuration for knowledge base system  
+            timeout: HTTP timeout for remote agent calls (default: 30 seconds)
         """
         self.session_id = session_id or str(uuid.uuid4())[:8]
         self.user_id = user_id or "default_user"
+        self.agent_url = agent_url
+        self.timeout = timeout
+        self.is_remote = agent_url is not None
 
-        # Initialize memory with sensible defaults
-        default_memory_config = {
-            "provider": "rag",
-            "use_embedding": True,
-            "rag_db_path": f".praison/sessions/{self.session_id}/chroma_db"
-        }
-        if memory_config:
-            default_memory_config.update(memory_config)
-        self.memory_config = default_memory_config
+        # Validate agent_url format
+        if self.is_remote:
+            if not self.agent_url.startswith(('http://', 'https://')):
+                # Assume http if no protocol specified
+                self.agent_url = f"http://{self.agent_url}"
+            # Test connectivity to remote agent
+            self._test_remote_connection()
 
-        # Initialize knowledge with session-specific config
-        default_knowledge_config = knowledge_config or {}
-        self.knowledge_config = default_knowledge_config
+        # Initialize memory with sensible defaults (only for local sessions)
+        if not self.is_remote:
+            default_memory_config = {
+                "provider": "rag",
+                "use_embedding": True,
+                "rag_db_path": f".praison/sessions/{self.session_id}/chroma_db"
+            }
+            if memory_config:
+                default_memory_config.update(memory_config)
+            self.memory_config = default_memory_config
 
-        # Create session directory
-        os.makedirs(f".praison/sessions/{self.session_id}", exist_ok=True)
+            # Initialize knowledge with session-specific config
+            default_knowledge_config = knowledge_config or {}
+            self.knowledge_config = default_knowledge_config
 
-        # Initialize components lazily
-        self._memory = None
-        self._knowledge = None
-        self._agents_instance = None
+            # Create session directory
+            os.makedirs(f".praison/sessions/{self.session_id}", exist_ok=True)
+
+            # Initialize components lazily
+            self._memory = None
+            self._knowledge = None
+            self._agents_instance = None
+        else:
+            # For remote sessions, disable local memory/knowledge
+            self.memory_config = {}
+            self.knowledge_config = {}
+            self._memory = None
+            self._knowledge = None
+            self._agents_instance = None
 
     @property
     def memory(self) -> Memory:
         """Lazy-loaded memory instance"""
+        if self.is_remote:
+            raise ValueError("Memory operations are not available for remote agent sessions")
         if self._memory is None:
             self._memory = Memory(config=self.memory_config)
         return self._memory
@@ -91,6 +116,8 @@ class Session:
     @property
     def knowledge(self) -> Knowledge:
         """Lazy-loaded knowledge instance"""
+        if self.is_remote:
+            raise ValueError("Knowledge operations are not available for remote agent sessions")
         if self._knowledge is None:
             self._knowledge = Knowledge(config=self.knowledge_config)
         return self._knowledge
@@ -119,7 +146,13 @@ class Session:
         
         Returns:
             Configured Agent instance
+            
+        Raises:
+            ValueError: If this is a remote session (use chat() instead)
         """
+        if self.is_remote:
+            raise ValueError("Cannot create local agents in remote sessions. Use chat() to communicate with the remote agent.")
+
         agent_kwargs = {
             "name": name,
             "role": role,
@@ -150,7 +183,12 @@ class Session:
         
         Args:
             state_data: Dictionary of state data to save
+            
+        Raises:
+            ValueError: If this is a remote session
         """
+        if self.is_remote:
+            raise ValueError("State operations are not available for remote agent sessions")
         state_text = f"Session state: {state_data}"
         self.memory.store_short_term(
             text=state_text,
@@ -168,7 +206,12 @@ class Session:
         
         Returns:
             Dictionary of restored state data
+            
+        Raises:
+            ValueError: If this is a remote session
         """
+        if self.is_remote:
+            raise ValueError("State operations are not available for remote agent sessions")
         # Use metadata-based search for better SQLite compatibility
         results = self.memory.search_short_term(
             query=f"type:session_state",
@@ -284,7 +327,105 @@ class Session:
             max_items=max_items
         )
 
+    def _test_remote_connection(self) -> None:
+        """
+        Test connectivity to the remote agent.
+        
+        Raises:
+            ConnectionError: If unable to connect to the remote agent
+        """
+        try:
+            # Try a simple GET request to check if the server is responding
+            test_url = self.agent_url.rstrip('/') + '/health' if '/health' not in self.agent_url else self.agent_url
+            response = requests.get(test_url, timeout=self.timeout)
+            if response.status_code != 200:
+                # If health endpoint fails, try the main endpoint
+                response = requests.head(self.agent_url, timeout=self.timeout)
+                if response.status_code not in [200, 405]:  # 405 = Method Not Allowed is OK
+                    raise ConnectionError(f"Remote agent returned status code: {response.status_code}")
+            print(f"✅ Successfully connected to remote agent at {self.agent_url}")
+        except requests.exceptions.Timeout:
+            raise ConnectionError(f"Timeout connecting to remote agent at {self.agent_url}")
+        except requests.exceptions.ConnectionError:
+            raise ConnectionError(f"Failed to connect to remote agent at {self.agent_url}")
+        except Exception as e:
+            raise ConnectionError(f"Error connecting to remote agent: {str(e)}")
+
+    def chat(self, message: str, **kwargs) -> str:
+        """
+        Send a message to the remote agent or handle local session.
+        
+        Args:
+            message: The message to send to the agent
+            **kwargs: Additional parameters for the request
+            
+        Returns:
+            The agent's response
+            
+        Raises:
+            ValueError: If this is not a remote session
+            ConnectionError: If unable to communicate with remote agent
+        """
+        if not self.is_remote:
+            raise ValueError("chat() method is only available for remote agent sessions. Use Agent.chat() for local agents.")
+        
+        try:
+            # Prepare the request payload
+            payload = {
+                "query": message,
+                "session_id": self.session_id,
+                "user_id": self.user_id,
+                **kwargs
+            }
+            
+            # Send POST request to the remote agent
+            response = requests.post(
+                self.agent_url,
+                json=payload,
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout
+            )
+            
+            # Check if request was successful
+            response.raise_for_status()
+            
+            # Parse the response
+            result = response.json()
+            
+            # Extract the agent's response
+            if isinstance(result, dict):
+                return result.get("response", str(result))
+            else:
+                return str(result)
+                
+        except requests.exceptions.Timeout:
+            raise ConnectionError(f"Timeout communicating with remote agent at {self.agent_url}")
+        except requests.exceptions.ConnectionError:
+            raise ConnectionError(f"Failed to communicate with remote agent at {self.agent_url}")
+        except requests.exceptions.HTTPError as e:
+            raise ConnectionError(f"HTTP error from remote agent: {e}")
+        except json.JSONDecodeError:
+            # If response is not JSON, return the raw text
+            return response.text
+        except Exception as e:
+            raise ConnectionError(f"Error communicating with remote agent: {str(e)}")
+
+    def send_message(self, message: str, **kwargs) -> str:
+        """
+        Alias for chat() method to match Google ADK pattern.
+        
+        Args:
+            message: The message to send to the agent
+            **kwargs: Additional parameters for the request
+            
+        Returns:
+            The agent's response
+        """
+        return self.chat(message, **kwargs)
+
     def __str__(self) -> str:
+        if self.is_remote:
+            return f"Session(id='{self.session_id}', user='{self.user_id}', remote_agent='{self.agent_url}')"
         return f"Session(id='{self.session_id}', user='{self.user_id}')"
 
     def __repr__(self) -> str:

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

@@ -1,6 +1,7 @@
 import logging
 import asyncio
-from typing import List, Optional, Dict, Any, Type, Callable, Union, Coroutine, Literal
+import inspect
+from typing import List, Optional, Dict, Any, Type, Callable, Union, Coroutine, Literal, Tuple, get_args, get_origin
 from pydantic import BaseModel
 from ..main import TaskOutput
 from ..agent.agent import Agent
@@ -40,7 +41,10 @@ class Task:
         quality_check=True,
         input_file: Optional[str] = None,
         rerun: bool = False, # Renamed from can_rerun and logic inverted, default True for backward compatibility
-        retain_full_context: bool = False # By default, only use previous task output, not all previous tasks
+        retain_full_context: bool = False, # By default, only use previous task output, not all previous tasks
+        guardrail: Optional[Union[Callable[[TaskOutput], Tuple[bool, Any]], str]] = None,
+        max_retries: int = 3,
+        retry_count: int = 0
     ):
         # Add check if memory config is provided
         if memory is not None or (config and config.get('memory_config')):
@@ -80,6 +84,10 @@ class Task:
         self.quality_check = quality_check
         self.rerun = rerun # Assigning the rerun parameter
         self.retain_full_context = retain_full_context
+        self.guardrail = guardrail
+        self.max_retries = max_retries
+        self.retry_count = retry_count
+        self._guardrail_fn = None
 
         # Set logger level based on config verbose level
         verbose = self.config.get("verbose", 0)
@@ -141,6 +149,55 @@ class Task:
 
             self.output_pydantic = LoopModel
 
+        # Initialize guardrail
+        self._setup_guardrail()
+
+    def _setup_guardrail(self):
+        """Setup the guardrail function based on the provided guardrail parameter."""
+        if self.guardrail is None:
+            self._guardrail_fn = None
+            return
+            
+        if callable(self.guardrail):
+            # Validate function signature
+            sig = inspect.signature(self.guardrail)
+            positional_args = [
+                param for param in sig.parameters.values()
+                if param.default is inspect.Parameter.empty
+            ]
+            if len(positional_args) != 1:
+                raise ValueError("Guardrail function must accept exactly one parameter (TaskOutput)")
+            
+            # Check return annotation if present
+            return_annotation = sig.return_annotation
+            if return_annotation != inspect.Signature.empty:
+                return_annotation_args = get_args(return_annotation)
+                if not (
+                    get_origin(return_annotation) is tuple
+                    and len(return_annotation_args) == 2
+                    and return_annotation_args[0] is bool
+                    and (
+                        return_annotation_args[1] is Any
+                        or return_annotation_args[1] is str
+                        or return_annotation_args[1] is TaskOutput
+                        or return_annotation_args[1] == Union[str, TaskOutput]
+                    )
+                ):
+                    raise ValueError(
+                        "If return type is annotated, it must be Tuple[bool, Any]"
+                    )
+            
+            self._guardrail_fn = self.guardrail
+        elif isinstance(self.guardrail, str):
+            # Create LLM-based guardrail
+            from ..guardrails import LLMGuardrail
+            if not self.agent:
+                raise ValueError("Agent is required for string-based guardrails")
+            llm = getattr(self.agent, 'llm', None) or getattr(self.agent, 'llm_instance', None)
+            self._guardrail_fn = LLMGuardrail(description=self.guardrail, llm=llm)
+        else:
+            raise ValueError("Guardrail must be either a callable or a string description")
+
     def __str__(self):
         return f"Task(name='{self.name if self.name else 'None'}', description='{self.description}', agent='{self.agent.name if self.agent else 'None'}', status='{self.status}')"
 
@@ -187,6 +244,37 @@ class Task:
         logger.info(f"Task {self.id}: execute_callback called")
         logger.info(f"Quality check enabled: {self.quality_check}")
 
+        # Process guardrail if configured
+        if self._guardrail_fn:
+            try:
+                guardrail_result = self._process_guardrail(task_output)
+                if not guardrail_result.success:
+                    if self.retry_count >= self.max_retries:
+                        raise Exception(
+                            f"Task failed guardrail validation after {self.max_retries} retries. "
+                            f"Last error: {guardrail_result.error}"
+                        )
+                    
+                    self.retry_count += 1
+                    logger.warning(f"Task {self.id}: Guardrail validation failed (retry {self.retry_count}/{self.max_retries}): {guardrail_result.error}")
+                    # Note: In a real execution, this would trigger a retry, but since this is a callback
+                    # the retry logic would need to be handled at the agent/execution level
+                    return
+                
+                # If guardrail passed and returned a modified result
+                if guardrail_result.result is not None:
+                    if isinstance(guardrail_result.result, str):
+                        # Update the task output with the modified result
+                        task_output.raw = guardrail_result.result
+                    elif isinstance(guardrail_result.result, TaskOutput):
+                        # Replace with the new task output
+                        task_output = guardrail_result.result
+                
+                logger.info(f"Task {self.id}: Guardrail validation passed")
+            except Exception as e:
+                logger.error(f"Task {self.id}: Error in guardrail processing: {e}")
+                # Continue execution even if guardrail fails to avoid breaking the task
+
         # Initialize memory if not already initialized
         if not self.memory:
             self.memory = self.initialize_memory()
@@ -220,7 +308,11 @@ class Task:
                 if self.agent:
                     if getattr(self.agent, '_using_custom_llm', False) and hasattr(self.agent, 'llm_instance'):
                         # For custom LLM instances (like Ollama)
-                        llm_model = self.agent.llm_instance
+                        # Extract the model name from the LLM instance
+                        if hasattr(self.agent.llm_instance, 'model'):
+                            llm_model = self.agent.llm_instance.model
+                        else:
+                            llm_model = "gpt-4o-mini"  # Default fallback
                     elif hasattr(self.agent, 'llm') and self.agent.llm:
                         # For standard model strings
                         llm_model = self.agent.llm
@@ -334,4 +426,34 @@ Context:
                 loop.run_until_complete(self.execute_callback(task_output))
         except RuntimeError:
             # If no loop is running in this context
-            asyncio.run(self.execute_callback(task_output))
+            asyncio.run(self.execute_callback(task_output))
+
+    def _process_guardrail(self, task_output: TaskOutput):
+        """Process the guardrail validation for a task output.
+        
+        Args:
+            task_output: The task output to validate
+            
+        Returns:
+            GuardrailResult: The result of the guardrail validation
+        """
+        from ..guardrails import GuardrailResult
+        
+        if not self._guardrail_fn:
+            return GuardrailResult(success=True, result=task_output)
+        
+        try:
+            # Call the guardrail function
+            result = self._guardrail_fn(task_output)
+            
+            # Convert the result to a GuardrailResult
+            return GuardrailResult.from_tuple(result)
+            
+        except Exception as e:
+            logger.error(f"Task {self.id}: Error in guardrail validation: {e}")
+            # On error, return failure
+            return GuardrailResult(
+                success=False,
+                result=None,
+                error=f"Guardrail validation error: {str(e)}"
+            )

src/praisonai-agents/praisonaiagents/telemetry/README.md

@@ -0,0 +1,108 @@
+# PraisonAI Agents Telemetry
+
+This module provides minimal, privacy-focused telemetry for PraisonAI Agents.
+
+## Privacy Guarantees
+
+- **No personal data is collected** - No prompts, responses, or user content
+- **Anonymous metrics only** - Usage counts and feature adoption
+- **Opt-out by default** - Respects standard privacy preferences
+- **Transparent collection** - See exactly what's tracked below
+
+## What We Collect
+
+We collect only anonymous usage metrics:
+- Number of agent executions
+- Number of task completions  
+- Tool usage (names only, no arguments)
+- Error types (no error messages)
+- Framework version and OS type
+- Anonymous session ID (regenerated each run)
+
+## Disabling Telemetry
+
+Telemetry can be disabled in three ways:
+
+### 1. Environment Variables (Recommended)
+
+Set any of these environment variables:
+```bash
+export PRAISONAI_TELEMETRY_DISABLED=true
+export PRAISONAI_DISABLE_TELEMETRY=true
+export DO_NOT_TRACK=true  # Universal standard
+```
+
+### 2. Programmatically
+
+```python
+from praisonaiagents.telemetry import disable_telemetry
+disable_telemetry()
+```
+
+### 3. At Runtime
+
+```python
+from praisonaiagents.telemetry import get_telemetry
+telemetry = get_telemetry()
+telemetry.enabled = False
+```
+
+## Usage
+
+The telemetry module integrates automatically with PraisonAI Agents:
+
+```python
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Telemetry is automatically enabled (unless disabled by environment)
+agent = Agent(name="MyAgent", role="Assistant")
+task = Task(description="Help user", agent=agent)
+
+workflow = PraisonAIAgents(agents=[agent], tasks=[task])
+result = workflow.start()
+
+# Check telemetry metrics
+from praisonaiagents.telemetry import get_telemetry
+telemetry = get_telemetry()
+print(telemetry.get_metrics())
+```
+
+## Implementation Details
+
+The telemetry implementation is minimal and lightweight:
+- No external dependencies required
+- No network calls in current implementation
+- Metrics stored in memory only
+- Future versions may send to PostHog or similar privacy-focused services
+
+## Backward Compatibility
+
+The module maintains compatibility with the previous telemetry interface:
+
+```python
+from praisonaiagents.telemetry import TelemetryCollector
+
+collector = TelemetryCollector()
+collector.start()
+
+with collector.trace_agent_execution("MyAgent"):
+    # Agent execution code
+    pass
+
+collector.stop()
+```
+
+## Contributing
+
+When contributing to telemetry:
+1. Never collect personal data or user content
+2. Always make new metrics opt-out
+3. Document what's collected
+4. Keep the implementation minimal
+
+## Future Plans
+
+- Integration with PostHog for anonymous analytics
+- Aggregate usage statistics dashboard
+- Opt-in detailed performance metrics
+- Self-hosted telemetry endpoint option

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

@@ -0,0 +1,102 @@
+"""
+PraisonAI Agents Minimal Telemetry Module
+
+This module provides anonymous usage tracking with privacy-first design.
+Telemetry is opt-out and can be disabled via environment variables:
+- PRAISONAI_TELEMETRY_DISABLED=true
+- PRAISONAI_DISABLE_TELEMETRY=true  
+- DO_NOT_TRACK=true
+
+No personal data, prompts, or responses are collected.
+"""
+
+import os
+import atexit
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .telemetry import MinimalTelemetry, TelemetryCollector
+
+# Import the classes for real (not just type checking)
+from .telemetry import MinimalTelemetry, TelemetryCollector
+
+__all__ = [
+    'get_telemetry',
+    'enable_telemetry',
+    'disable_telemetry',
+    'MinimalTelemetry',
+    'TelemetryCollector',  # For backward compatibility
+]
+
+
+def get_telemetry() -> 'MinimalTelemetry':
+    """Get the global telemetry instance."""
+    from .telemetry import get_telemetry as _get_telemetry
+    return _get_telemetry()
+
+
+def enable_telemetry():
+    """Enable telemetry (if not disabled by environment)."""
+    from .telemetry import enable_telemetry as _enable_telemetry
+    _enable_telemetry()
+
+
+def disable_telemetry():
+    """Disable telemetry."""
+    from .telemetry import disable_telemetry as _disable_telemetry
+    _disable_telemetry()
+
+
+# Auto-instrumentation and cleanup setup
+_initialized = False
+_atexit_registered = False
+
+def _ensure_atexit():
+    """Ensure atexit handler is registered."""
+    global _atexit_registered
+    if _atexit_registered:
+        return
+    
+    # Check if telemetry should be disabled
+    telemetry_disabled = any([
+        os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
+    ])
+    
+    if not telemetry_disabled:
+        # Register atexit handler to flush telemetry on exit
+        atexit.register(lambda: get_telemetry().flush())
+        _atexit_registered = True
+
+def _initialize_telemetry():
+    """Initialize telemetry with auto-instrumentation and cleanup."""
+    global _initialized
+    if _initialized:
+        return
+    
+    # Ensure atexit is registered
+    _ensure_atexit()
+    
+    # Check if telemetry should be disabled
+    telemetry_disabled = any([
+        os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
+        os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
+    ])
+    
+    if not telemetry_disabled:
+        try:
+            # Defer the actual instrumentation to avoid circular imports
+            # This will be called when get_telemetry() is first accessed
+            _initialized = True
+        except Exception:
+            # Silently fail if there are any issues
+            pass
+
+
+# No need for lazy auto-instrumentation here since main __init__.py handles it
+
+
+# Initialize atexit handler early
+_ensure_atexit()

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

@@ -0,0 +1,242 @@
+"""
+Simplified integration module for adding telemetry to core PraisonAI components.
+"""
+
+from typing import Any, Optional, TYPE_CHECKING
+from functools import wraps
+import time
+
+if TYPE_CHECKING:
+    from .telemetry import MinimalTelemetry
+    from ..agent.agent import Agent
+    from ..task.task import Task
+    from ..agents.agents import PraisonAIAgents
+
+
+def instrument_agent(agent: 'Agent', telemetry: Optional['MinimalTelemetry'] = None):
+    """
+    Instrument an Agent instance with minimal telemetry.
+    
+    Args:
+        agent: The Agent instance to instrument
+        telemetry: Optional telemetry instance (uses global if not provided)
+    """
+    if not telemetry:
+        from .telemetry import get_telemetry
+        telemetry = get_telemetry()
+    
+    if not telemetry.enabled:
+        return agent
+    
+    # Check if agent is already instrumented to avoid double-counting
+    if hasattr(agent, '_telemetry_instrumented'):
+        return agent
+    
+    # Store original methods
+    original_chat = agent.chat if hasattr(agent, 'chat') else None
+    original_start = agent.start if hasattr(agent, 'start') else None
+    original_run = agent.run if hasattr(agent, 'run') else None
+    original_execute_tool = agent.execute_tool if hasattr(agent, 'execute_tool') else None
+    
+    # Wrap chat method if it exists (this is the main method called by workflow)
+    if original_chat:
+        @wraps(original_chat)
+        def instrumented_chat(*args, **kwargs):
+            try:
+                result = original_chat(*args, **kwargs)
+                telemetry.track_agent_execution(agent.name, success=True)
+                return result
+            except Exception as e:
+                telemetry.track_agent_execution(agent.name, success=False)
+                telemetry.track_error(type(e).__name__)
+                raise
+        
+        agent.chat = instrumented_chat
+    
+    # Wrap start method if it exists
+    if original_start:
+        @wraps(original_start)
+        def instrumented_start(*args, **kwargs):
+            try:
+                result = original_start(*args, **kwargs)
+                telemetry.track_agent_execution(agent.name, success=True)
+                return result
+            except Exception as e:
+                telemetry.track_agent_execution(agent.name, success=False)
+                telemetry.track_error(type(e).__name__)
+                raise
+        
+        agent.start = instrumented_start
+    
+    # Wrap run method if it exists
+    if original_run:
+        @wraps(original_run)
+        def instrumented_run(*args, **kwargs):
+            try:
+                result = original_run(*args, **kwargs)
+                telemetry.track_agent_execution(agent.name, success=True)
+                return result
+            except Exception as e:
+                telemetry.track_agent_execution(agent.name, success=False)
+                telemetry.track_error(type(e).__name__)
+                raise
+        
+        agent.run = instrumented_run
+    
+    # Wrap execute_tool method
+    if original_execute_tool:
+        @wraps(original_execute_tool)
+        def instrumented_execute_tool(tool_name: str, *args, **kwargs):
+            try:
+                result = original_execute_tool(tool_name, *args, **kwargs)
+                telemetry.track_tool_usage(tool_name, success=True)
+                return result
+            except Exception as e:
+                telemetry.track_tool_usage(tool_name, success=False)
+                telemetry.track_error(type(e).__name__)
+                raise
+        
+        agent.execute_tool = instrumented_execute_tool
+    
+    # Mark agent as instrumented to avoid double instrumentation
+    agent._telemetry_instrumented = True
+    
+    return agent
+
+
+def instrument_workflow(workflow: 'PraisonAIAgents', telemetry: Optional['MinimalTelemetry'] = None):
+    """
+    Instrument a PraisonAIAgents workflow with minimal telemetry.
+    
+    Args:
+        workflow: The PraisonAIAgents instance to instrument
+        telemetry: Optional telemetry instance (uses global if not provided)
+    """
+    if not telemetry:
+        from .telemetry import get_telemetry
+        telemetry = get_telemetry()
+    
+    if not telemetry.enabled:
+        return workflow
+    
+    # Check if workflow is already instrumented to avoid double-counting
+    if hasattr(workflow, '_telemetry_instrumented'):
+        return workflow
+    
+    # Track feature usage
+    telemetry.track_feature_usage(f"workflow_{workflow.process}" if hasattr(workflow, 'process') else "workflow")
+    
+    # Instrument all agents in the workflow
+    if hasattr(workflow, 'agents') and workflow.agents:
+        for agent in workflow.agents:
+            instrument_agent(agent, telemetry)
+    
+    # Wrap the execute_task method to track task completions
+    if hasattr(workflow, 'execute_task'):
+        original_execute_task = workflow.execute_task
+        
+        @wraps(original_execute_task)
+        def instrumented_execute_task(task_id, *args, **kwargs):
+            task = None
+            try:
+                # Get task info
+                if hasattr(workflow, 'tasks') and task_id < len(workflow.tasks):
+                    task = workflow.tasks[task_id]
+                
+                result = original_execute_task(task_id, *args, **kwargs)
+                
+                # Track task completion
+                task_name = task.name if task and hasattr(task, 'name') else f"task_{task_id}"
+                telemetry.track_task_completion(task_name, success=True)
+                
+                return result
+            except Exception as e:
+                telemetry.track_error(type(e).__name__)
+                if task:
+                    task_name = task.name if hasattr(task, 'name') else f"task_{task_id}"
+                    telemetry.track_task_completion(task_name, success=False)
+                raise
+        
+        workflow.execute_task = instrumented_execute_task
+    
+    # Wrap the start method
+    original_start = workflow.start
+    
+    @wraps(original_start)
+    def instrumented_start(*args, **kwargs):
+        try:
+            result = original_start(*args, **kwargs)
+            # Don't double-track here since agent.chat already tracks execution
+            return result
+        except Exception as e:
+            telemetry.track_error(type(e).__name__)
+            raise
+    
+    workflow.start = instrumented_start
+    
+    # Also wrap astart if it exists (async version)
+    if hasattr(workflow, 'astart'):
+        original_astart = workflow.astart
+        
+        @wraps(original_astart)
+        async def instrumented_astart(*args, **kwargs):
+            try:
+                result = await original_astart(*args, **kwargs)
+                # Don't double-track here since agent.chat already tracks execution
+                return result
+            except Exception as e:
+                telemetry.track_error(type(e).__name__)
+                raise
+        
+        workflow.astart = instrumented_astart
+    
+    # Mark workflow as instrumented to avoid double instrumentation
+    workflow._telemetry_instrumented = True
+    
+    return workflow
+
+
+# Auto-instrumentation helper
+def auto_instrument_all(telemetry: Optional['MinimalTelemetry'] = None):
+    """
+    Automatically instrument all new instances of Agent and PraisonAIAgents.
+    This should be called after enabling telemetry.
+    
+    Args:
+        telemetry: Optional telemetry instance (uses global if not provided)
+    """
+    if not telemetry:
+        from .telemetry import get_telemetry
+        telemetry = get_telemetry()
+    
+    if not telemetry.enabled:
+        return
+    
+    try:
+        # Import the classes
+        from ..agent.agent import Agent
+        from ..agents.agents import PraisonAIAgents
+        
+        # Store original __init__ methods
+        original_agent_init = Agent.__init__
+        original_workflow_init = PraisonAIAgents.__init__
+        
+        # Wrap Agent.__init__
+        @wraps(original_agent_init)
+        def agent_init_wrapper(self, *args, **kwargs):
+            original_agent_init(self, *args, **kwargs)
+            instrument_agent(self, telemetry)
+        
+        # Wrap PraisonAIAgents.__init__
+        @wraps(original_workflow_init)
+        def workflow_init_wrapper(self, *args, **kwargs):
+            original_workflow_init(self, *args, **kwargs)
+            instrument_workflow(self, telemetry)
+        
+        # Apply wrapped constructors
+        Agent.__init__ = agent_init_wrapper
+        PraisonAIAgents.__init__ = workflow_init_wrapper
+        
+    except ImportError:
+        # Classes not available, skip auto-instrumentation
+        pass

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

@@ -0,0 +1,372 @@
+"""
+Minimal telemetry implementation for PraisonAI Agents.
+
+This module provides anonymous usage tracking with privacy-first design.
+All telemetry is opt-out via environment variables.
+"""
+
+import os
+import time
+import platform
+import hashlib
+from typing import Dict, Any, Optional
+from datetime import datetime
+import logging
+
+# Try to import PostHog
+try:
+    from posthog import Posthog
+    POSTHOG_AVAILABLE = True
+except ImportError:
+    POSTHOG_AVAILABLE = False
+
+# Check for opt-out environment variables
+_TELEMETRY_DISABLED = any([
+    os.environ.get('PRAISONAI_TELEMETRY_DISABLED', '').lower() in ('true', '1', 'yes'),
+    os.environ.get('PRAISONAI_DISABLE_TELEMETRY', '').lower() in ('true', '1', 'yes'),
+    os.environ.get('DO_NOT_TRACK', '').lower() in ('true', '1', 'yes'),
+])
+
+
+class MinimalTelemetry:
+    """
+    Minimal telemetry collector for anonymous usage tracking.
+    
+    Privacy guarantees:
+    - No personal data is collected
+    - No prompts, responses, or user content is tracked
+    - Only anonymous metrics about feature usage
+    - Respects DO_NOT_TRACK standard
+    - Can be disabled via environment variables
+    """
+    
+    def __init__(self, enabled: bool = None):
+        """
+        Initialize the minimal telemetry collector.
+        
+        Args:
+            enabled: Override the environment-based enable/disable setting
+        """
+        # Respect explicit enabled parameter, otherwise check environment
+        if enabled is not None:
+            self.enabled = enabled
+        else:
+            self.enabled = not _TELEMETRY_DISABLED
+            
+        self.logger = logging.getLogger(__name__)
+        
+        if not self.enabled:
+            self.logger.debug("Telemetry is disabled")
+            return
+            
+        # Generate anonymous session ID (not user ID)
+        session_data = f"{datetime.now().isoformat()}-{os.getpid()}-{time.time()}"
+        self.session_id = hashlib.sha256(session_data.encode()).hexdigest()[:16]
+        
+        # Basic metrics storage
+        self._metrics = {
+            "agent_executions": 0,
+            "task_completions": 0,
+            "tool_calls": 0,
+            "errors": 0,
+        }
+        
+        # Collect basic environment info (anonymous)
+        self._environment = {
+            "python_version": platform.python_version(),
+            "os_type": platform.system(),
+            "framework_version": self._get_framework_version(),
+        }
+        
+        self.logger.debug(f"Telemetry enabled with session {self.session_id}")
+        
+        # Initialize PostHog if available
+        if POSTHOG_AVAILABLE:
+            try:
+                self._posthog = Posthog(
+                    project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+                    host='https://eu.i.posthog.com',
+                    disable_geoip=True,
+                    on_error=lambda e: self.logger.debug(f"PostHog error: {e}"),
+                    sync_mode=False  # Use async mode to prevent blocking
+                )
+            except:
+                self._posthog = None
+        else:
+            self._posthog = None
+    
+    def _get_framework_version(self) -> str:
+        """Get the PraisonAI Agents version."""
+        try:
+            from .. import __version__
+            return __version__
+        except ImportError:
+            return "unknown"
+    
+    def track_agent_execution(self, agent_name: str = None, success: bool = True):
+        """
+        Track an agent execution event.
+        
+        Args:
+            agent_name: Name of the agent (not logged, just for counting)
+            success: Whether the execution was successful
+        """
+        if not self.enabled:
+            return
+            
+        self._metrics["agent_executions"] += 1
+        
+        # In a real implementation, this would send to a backend
+        # For now, just log at debug level
+        self.logger.debug(f"Agent execution tracked: success={success}")
+    
+    def track_task_completion(self, task_name: str = None, success: bool = True):
+        """
+        Track a task completion event.
+        
+        Args:
+            task_name: Name of the task (not logged, just for counting)
+            success: Whether the task completed successfully
+        """
+        if not self.enabled:
+            return
+            
+        self._metrics["task_completions"] += 1
+        
+        self.logger.debug(f"Task completion tracked: success={success}")
+    
+    def track_tool_usage(self, tool_name: str, success: bool = True):
+        """
+        Track tool usage event.
+        
+        Args:
+            tool_name: Name of the tool being used
+            success: Whether the tool call was successful
+        """
+        if not self.enabled:
+            return
+            
+        self._metrics["tool_calls"] += 1
+        
+        # Only track tool name, not arguments or results
+        self.logger.debug(f"Tool usage tracked: {tool_name}, success={success}")
+    
+    def track_error(self, error_type: str = None):
+        """
+        Track an error event.
+        
+        Args:
+            error_type: Type of error (not the full message)
+        """
+        if not self.enabled:
+            return
+            
+        self._metrics["errors"] += 1
+        
+        # Only track error type, not full error messages
+        self.logger.debug(f"Error tracked: type={error_type or 'unknown'}")
+    
+    def track_feature_usage(self, feature_name: str):
+        """
+        Track usage of a specific feature.
+        
+        Args:
+            feature_name: Name of the feature being used
+        """
+        if not self.enabled:
+            return
+            
+        # Track which features are being used
+        self.logger.debug(f"Feature usage tracked: {feature_name}")
+    
+    def get_metrics(self) -> Dict[str, Any]:
+        """
+        Get current metrics summary.
+        
+        Returns:
+            Dictionary of current metrics
+        """
+        if not self.enabled:
+            return {"enabled": False}
+            
+        return {
+            "enabled": True,
+            "session_id": self.session_id,
+            "metrics": self._metrics.copy(),
+            "environment": self._environment.copy(),
+        }
+    
+    def flush(self):
+        """
+        Flush any pending telemetry data.
+        
+        In a real implementation, this would send data to a backend.
+        """
+        if not self.enabled:
+            return
+            
+        metrics = self.get_metrics()
+        self.logger.debug(f"Telemetry flush: {metrics}")
+        
+        # Send to PostHog if available
+        if hasattr(self, '_posthog') and self._posthog:
+            
+            try:
+                self._posthog.capture(
+                    distinct_id='anonymous',
+                    event='sdk_used',
+                    properties={
+                        'version': self._environment['framework_version'],
+                        'os': platform.system(),
+                        '$process_person_profile': False,
+                        '$geoip_disable': True
+                    }
+                )
+                # Don't flush here - let PostHog handle it asynchronously
+            except:
+                pass
+        
+        # Reset counters
+        for key in self._metrics:
+            if isinstance(self._metrics[key], int):
+                self._metrics[key] = 0
+    
+    def shutdown(self):
+        """
+        Shutdown telemetry and ensure all events are sent.
+        """
+        if not self.enabled:
+            return
+            
+        # Final flush
+        self.flush()
+        
+        # Shutdown PostHog if available
+        if hasattr(self, '_posthog') and self._posthog:
+            try:
+                # Force a synchronous flush before shutdown
+                self._posthog.flush()
+                self._posthog.shutdown()
+            except:
+                pass
+
+
+# Global telemetry instance
+_telemetry_instance = None
+
+
+def get_telemetry() -> MinimalTelemetry:
+    """
+    Get the global telemetry instance.
+    
+    Returns:
+        The global MinimalTelemetry instance
+    """
+    global _telemetry_instance
+    if _telemetry_instance is None:
+        _telemetry_instance = MinimalTelemetry()
+    return _telemetry_instance
+
+
+def disable_telemetry():
+    """Programmatically disable telemetry."""
+    global _telemetry_instance
+    if _telemetry_instance:
+        _telemetry_instance.enabled = False
+    else:
+        _telemetry_instance = MinimalTelemetry(enabled=False)
+
+
+def enable_telemetry():
+    """Programmatically enable telemetry (if not disabled by environment)."""
+    global _telemetry_instance
+    if not _TELEMETRY_DISABLED:
+        if _telemetry_instance:
+            _telemetry_instance.enabled = True
+        else:
+            _telemetry_instance = MinimalTelemetry(enabled=True)
+
+
+# For backward compatibility with existing code
+class TelemetryCollector:
+    """Backward compatibility wrapper for the old TelemetryCollector interface."""
+    
+    def __init__(self, backend: str = "minimal", service_name: str = "praisonai-agents", **kwargs):
+        self.telemetry = get_telemetry()
+        
+    def start(self):
+        """Start telemetry collection."""
+        # No-op for minimal implementation
+        pass
+        
+    def stop(self):
+        """Stop telemetry collection and flush data."""
+        self.telemetry.flush()
+    
+    def trace_agent_execution(self, agent_name: str, **attributes):
+        """Compatibility method for agent execution tracking."""
+        from contextlib import contextmanager
+        
+        @contextmanager
+        def _trace():
+            try:
+                yield None
+                self.telemetry.track_agent_execution(agent_name, success=True)
+            except Exception:
+                self.telemetry.track_agent_execution(agent_name, success=False)
+                raise
+                
+        return _trace()
+    
+    def trace_task_execution(self, task_name: str, agent_name: str = None, **attributes):
+        """Compatibility method for task execution tracking."""
+        from contextlib import contextmanager
+        
+        @contextmanager
+        def _trace():
+            try:
+                yield None
+                self.telemetry.track_task_completion(task_name, success=True)
+            except Exception:
+                self.telemetry.track_task_completion(task_name, success=False)
+                raise
+                
+        return _trace()
+    
+    def trace_tool_call(self, tool_name: str, **attributes):
+        """Compatibility method for tool call tracking."""
+        from contextlib import contextmanager
+        
+        @contextmanager
+        def _trace():
+            try:
+                yield None
+                self.telemetry.track_tool_usage(tool_name, success=True)
+            except Exception:
+                self.telemetry.track_tool_usage(tool_name, success=False)
+                raise
+                
+        return _trace()
+    
+    def trace_llm_call(self, model: str = None, **attributes):
+        """Compatibility method for LLM call tracking."""
+        from contextlib import contextmanager
+        
+        @contextmanager
+        def _trace():
+            # We don't track LLM calls in minimal telemetry
+            yield None
+            
+        return _trace()
+    
+    def record_tokens(self, prompt_tokens: int, completion_tokens: int, model: str = None):
+        """Compatibility method - we don't track token usage."""
+        pass
+        
+    def record_cost(self, cost: float, model: str = None):
+        """Compatibility method - we don't track costs."""
+        pass
+        
+    def get_metrics(self) -> Dict[str, Any]:
+        """Get current metrics."""
+        return self.telemetry.get_metrics()

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.0.97"
+version = "0.0.106"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 requires-python = ">=3.10"
 authors = [
@@ -14,7 +14,8 @@ dependencies = [
     "pydantic",
     "rich",
     "openai",
-    "mcp>=1.6.0"
+    "mcp>=1.6.0",
+    "posthog>=3.0.0"
 ]
 
 [project.optional-dependencies]
@@ -25,7 +26,8 @@ mcp = [
 ]
 
 memory = [
-    "chromadb>=1.0.0"
+    "chromadb>=1.0.0",
+    "litellm>=1.72.0",
 ]
 
 knowledge = [
@@ -43,7 +45,7 @@ graph = [
 
 # Add LLM dependencies
 llm = [
-    "litellm>=1.50.0",
+    "litellm>=1.72.0",
     "pydantic>=2.4.2"
 ]
 
@@ -53,6 +55,11 @@ api = [
     "uvicorn>=0.34.0"
 ]
 
+# Telemetry dependencies
+telemetry = [
+    "posthog>=3.0.0"
+]
+
 # Combined features
 all = [
     "praisonaiagents[memory]",
@@ -60,8 +67,10 @@ all = [
     "praisonaiagents[graph]",
     "praisonaiagents[llm]",
     "praisonaiagents[mcp]",
-    "praisonaiagents[api]"
+    "praisonaiagents[api]",
+    "praisonaiagents[telemetry]"
 ]
 
-[tool.setuptools]
-packages = ["praisonaiagents"]
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["praisonaiagents*"]

src/praisonai-agents/requirements.txt

@@ -2,6 +2,7 @@
 pydantic
 rich
 openai>=1.30.0
+posthog>=3.0.0
 
 # Memory dependencies
 chromadb>=0.5.23

src/praisonai-agents/sequence.py

@@ -0,0 +1,11 @@
+from praisonaiagents import Agent, MCP
+import os
+
+sequential_agent = Agent(
+    instructions="""You are a helpful assistant that can break down complex problems.
+    Use the available tools when relevant to perform step-by-step analysis.""",
+    llm="gpt-4o-mini",
+    tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+)
+
+sequential_agent.start("Break down the process of making a cup of tea")

src/praisonai-agents/sequence_llm.py

@@ -0,0 +1,11 @@
+from praisonaiagents import Agent, MCP
+import os
+
+sequential_agent = Agent(
+    instructions="""You are a helpful assistant that can break down complex problems.
+    Use the available tools when relevant to perform step-by-step analysis.""",
+    llm="openai/gpt-4o-mini",
+    tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+)
+
+sequential_agent.start("Break down the process of making a cup of tea")

src/praisonai-agents/simple_guardrail_test.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Simple test for guardrails functionality without full dependencies.
+"""
+
+import sys
+import os
+from typing import Tuple, Any
+
+# Import only what we need for testing
+from praisonaiagents.guardrails import GuardrailResult, LLMGuardrail
+from praisonaiagents.main import TaskOutput
+
+
+def test_guardrail_result():
+    """Test GuardrailResult helper methods."""
+    print("Testing GuardrailResult...")
+    
+    # Test success case
+    success_result = GuardrailResult.from_tuple((True, "Modified output"))
+    assert success_result.success
+    assert success_result.result == "Modified output"
+    assert success_result.error == ""
+    print("✓ Success result created correctly")
+    
+    # Test failure case
+    failure_result = GuardrailResult.from_tuple((False, "Validation failed"))
+    assert not failure_result.success
+    assert failure_result.result is None
+    assert failure_result.error == "Validation failed"
+    print("✓ Failure result created correctly")
+    
+    print("GuardrailResult test passed!\n")
+
+
+def test_function_guardrail():
+    """Test function-based guardrail logic."""
+    print("Testing function-based guardrail logic...")
+    
+    def validate_output(task_output: TaskOutput) -> Tuple[bool, Any]:
+        """Simple validation function."""
+        if "error" in task_output.raw.lower():
+            return False, "Output contains errors"
+        if len(task_output.raw) < 10:
+            return False, "Output is too short"
+        return True, task_output
+    
+    # Test with good output
+    good_output = TaskOutput(
+        description="Test task",
+        raw="Hello! This is a friendly greeting message from the agent.",
+        agent="Test Agent"
+    )
+    
+    result = validate_output(good_output)
+    guardrail_result = GuardrailResult.from_tuple(result)
+    assert guardrail_result.success, f"Good output should pass: {guardrail_result.error}"
+    print("✓ Good output passed function guardrail")
+    
+    # Test with bad output
+    bad_output = TaskOutput(
+        description="Test task", 
+        raw="Error occurred",
+        agent="Test Agent"
+    )
+    
+    result = validate_output(bad_output)
+    guardrail_result = GuardrailResult.from_tuple(result)
+    assert not guardrail_result.success, "Bad output should fail guardrail"
+    print("✓ Bad output failed function guardrail as expected")
+    
+    print("Function-based guardrail logic test passed!\n")
+
+
+def test_llm_guardrail():
+    """Test LLM guardrail logic."""
+    print("Testing LLM guardrail logic...")
+    
+    # Mock LLM for testing that correctly parses the validation prompt
+    class MockLLM:
+        def chat(self, prompt, **kwargs):
+            # Extract the actual output to validate from the prompt
+            # The LLMGuardrail sends a structured prompt with "Output to Validate:" section
+            if "Output to Validate:" in prompt:
+                # Split by "Output to Validate:" and get the content after it
+                parts = prompt.split("Output to Validate:")
+                if len(parts) > 1:
+                    output_content = parts[1].strip()
+                    # Check only the output content, not the validation criteria
+                    if "error" in output_content.lower():
+                        return "FAIL: The output contains error messages"
+                    return "PASS"
+            
+            # Fallback: if no "Output to Validate:" section, return pass
+            return "PASS"
+    
+    # Create LLM guardrail
+    mock_llm = MockLLM()
+    llm_guardrail = LLMGuardrail(
+        description="Check if the output is professional and does not contain errors",
+        llm=mock_llm
+    )
+    
+    # Test with good output
+    good_output = TaskOutput(
+        description="Test task",
+        raw="Hello! This is a professional greeting message.",
+        agent="Test Agent"
+    )
+    
+    result = llm_guardrail(good_output)
+    guardrail_result = GuardrailResult.from_tuple(result)
+    assert guardrail_result.success, f"Good output should pass: {guardrail_result.error}"
+    print("✓ Good output passed LLM guardrail")
+    
+    # Test with bad output  
+    bad_output = TaskOutput(
+        description="Test task",
+        raw="There was an error in the system",
+        agent="Test Agent"
+    )
+    
+    result = llm_guardrail(bad_output)
+    guardrail_result = GuardrailResult.from_tuple(result)
+    assert not guardrail_result.success, "Bad output should fail LLM guardrail"
+    print("✓ Bad output failed LLM guardrail as expected")
+    
+    print("LLM guardrail logic test passed!\n")
+
+
+def main():
+    """Run all tests."""
+    print("Running Simple Guardrails Tests...\n")
+    
+    try:
+        test_guardrail_result()
+        test_function_guardrail()
+        test_llm_guardrail()
+        
+        print("🎉 All simple guardrail tests passed!")
+        print("\nGuardrails core logic is working correctly!")
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+    
+    return True
+
+
+if __name__ == "__main__":
+    success = main()
+    sys.exit(0 if success else 1)

src/praisonai-agents/telemetry_analysis.md

@@ -0,0 +1,123 @@
+# Telemetry Analysis: Why PostHog Events Aren't Being Sent by Default
+
+## Executive Summary
+
+The telemetry system is implemented but **not actively integrated** into the PraisonAI Agents codebase. While PostHog is properly configured and functional, telemetry data is never sent because:
+
+1. **No automatic integration**: Agent and PraisonAIAgents classes don't use telemetry
+2. **No automatic flush**: Events are collected but never sent to PostHog
+3. **No lifecycle hooks**: No atexit handler or periodic flush mechanism
+
+## Current State
+
+### What's Working ✓
+- PostHog client is properly initialized with API key and host
+- Telemetry can be enabled/disabled via environment variables
+- Privacy-first design with anonymous tracking
+- Manual telemetry tracking and flushing works correctly
+
+### What's Not Working ✗
+- Agent class doesn't integrate telemetry
+- PraisonAIAgents class doesn't integrate telemetry
+- No automatic flush() calls anywhere in the codebase
+- Integration module (integration.py) is not used
+
+## Technical Analysis
+
+### 1. PostHog Configuration (telemetry.py)
+```python
+# Lines 84-93: PostHog is initialized correctly
+if POSTHOG_AVAILABLE:
+    try:
+        self._posthog = Posthog(
+            project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+            host='https://eu.i.posthog.com'
+        )
+    except:
+        self._posthog = None
+```
+
+### 2. Flush Implementation (telemetry.py)
+```python
+# Lines 208-224: flush() sends events but is never called automatically
+def flush(self):
+    if hasattr(self, '_posthog') and self._posthog:
+        try:
+            self._posthog.capture(
+                distinct_id='anonymous',
+                event='sdk_used',
+                properties={...}
+            )
+            self._posthog.capture('test-id', 'test-event')
+        except:
+            pass
+```
+
+### 3. Missing Integration Points
+
+#### Agent Class (agent/agent.py)
+- No telemetry imports
+- No telemetry initialization in __init__
+- No telemetry tracking in start(), run(), or execute_tool()
+
+#### PraisonAIAgents Class (agents/agents.py)
+- No telemetry imports
+- No telemetry initialization
+- No telemetry tracking in start() or workflow execution
+
+## Root Causes
+
+1. **Incomplete Implementation**: The telemetry system was built but never integrated into the main classes
+2. **No Automatic Lifecycle Management**: No atexit handler or periodic flush
+3. **Integration Module Not Used**: `integration.py` has the code but it's never imported/called
+
+## Recommendations
+
+### Immediate Fixes
+
+1. **Add automatic integration to Agent class**:
+```python
+# In agent/agent.py __init__
+from ..telemetry import get_telemetry
+self._telemetry = get_telemetry()
+
+# In start() method
+if self._telemetry and self._telemetry.enabled:
+    self._telemetry.track_agent_execution(self.name, success=True)
+```
+
+2. **Add atexit handler in telemetry.py**:
+```python
+import atexit
+
+def _flush_on_exit():
+    if _telemetry_instance:
+        _telemetry_instance.flush()
+
+atexit.register(_flush_on_exit)
+```
+
+3. **Add periodic flush**:
+```python
+# Flush after N events or T seconds
+if self._metrics["total_events"] >= 100:
+    self.flush()
+```
+
+### Long-term Improvements
+
+1. **Make telemetry opt-in by default** with clear documentation
+2. **Add telemetry configuration options** (flush interval, batch size)
+3. **Implement proper error handling** for network failures
+4. **Add telemetry dashboard** for users to see their usage
+
+## Testing
+
+Created test files demonstrate:
+- `test_posthog.py`: PostHog is working correctly
+- `test_posthog_detailed.py`: Events are sent when flush() is called
+- `test_telemetry_integration.py`: Integration is missing
+
+## Conclusion
+
+The telemetry infrastructure is well-designed but incomplete. The main issue is that telemetry code exists in isolation and is never called by the core Agent/PraisonAIAgents classes. Additionally, even if it were integrated, the lack of automatic flush mechanisms means data would never reach PostHog.

src/praisonai-agents/telemetry_example.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating the minimal telemetry implementation.
+"""
+
+import os
+from praisonaiagents.telemetry import get_telemetry, disable_telemetry, enable_telemetry
+
+# Example 1: Default telemetry (enabled unless disabled by environment)
+print("=== Example 1: Default Telemetry ===")
+telemetry = get_telemetry()
+print(f"Telemetry enabled: {telemetry.enabled}")
+
+# Track some events
+telemetry.track_agent_execution("TestAgent", success=True)
+telemetry.track_task_completion("TestTask", success=True)
+telemetry.track_tool_usage("calculator", success=True)
+telemetry.track_error("ValueError")
+telemetry.track_feature_usage("memory")
+
+# Get metrics
+metrics = telemetry.get_metrics()
+print(f"Current metrics: {metrics}")
+
+# Example 2: Programmatically disable telemetry
+print("\n=== Example 2: Disable Telemetry ===")
+disable_telemetry()
+telemetry = get_telemetry()
+print(f"Telemetry enabled: {telemetry.enabled}")
+
+# These won't be tracked
+telemetry.track_agent_execution("TestAgent2", success=True)
+metrics = telemetry.get_metrics()
+print(f"Metrics after disable: {metrics}")
+
+# Example 3: Re-enable telemetry
+print("\n=== Example 3: Re-enable Telemetry ===")
+enable_telemetry()
+telemetry = get_telemetry()
+print(f"Telemetry enabled: {telemetry.enabled}")
+
+# Example 4: Test with environment variable
+print("\n=== Example 4: Environment Variable Opt-out ===")
+# Simulate environment variable being set
+os.environ['PRAISONAI_TELEMETRY_DISABLED'] = 'true'
+
+# Need to create a new instance to pick up the environment change
+from importlib import reload
+import praisonaiagents.telemetry.telemetry as telemetry_module
+reload(telemetry_module)
+
+from praisonaiagents.telemetry import get_telemetry as get_new_telemetry
+new_telemetry = get_new_telemetry()
+print(f"Telemetry enabled with env var: {new_telemetry.enabled}")
+
+# Clean up
+del os.environ['PRAISONAI_TELEMETRY_DISABLED']
+
+# Example 5: Backward compatibility with TelemetryCollector
+print("\n=== Example 5: Backward Compatibility ===")
+from praisonaiagents.telemetry.telemetry import TelemetryCollector
+
+collector = TelemetryCollector()
+collector.start()
+
+# Use context managers (backward compatible interface)
+with collector.trace_agent_execution("CompatAgent"):
+    print("Executing agent...")
+    
+with collector.trace_tool_call("web_search"):
+    print("Calling tool...")
+
+# Get metrics through collector
+collector_metrics = collector.get_metrics()
+print(f"Collector metrics: {collector_metrics}")
+
+collector.stop()
+
+print("\n=== Telemetry Example Complete ===")
+print("\nPrivacy Notes:")
+print("- No personal data, prompts, or responses are collected")
+print("- Only anonymous usage metrics are tracked")
+print("- Telemetry can be disabled via environment variables:")
+print("  - PRAISONAI_TELEMETRY_DISABLED=true")
+print("  - PRAISONAI_DISABLE_TELEMETRY=true")
+print("  - DO_NOT_TRACK=true")

src/praisonai-agents/telemetry_minimal.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+Minimal example showing telemetry integration with agents.
+"""
+
+import os
+# Uncomment to disable telemetry
+# os.environ['PRAISONAI_TELEMETRY_DISABLED'] = 'true'
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.telemetry import get_telemetry
+
+# Create a simple agent
+agent = Agent(
+    name="Calculator",
+    role="Math Expert",
+    goal="Perform calculations",
+    instructions="You are a helpful math expert."
+)
+
+# Create a task
+task = Task(
+    description="Calculate 2 + 2",
+    expected_output="The sum",
+    agent=agent
+)
+
+# Create and run workflow
+workflow = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    process="sequential"
+)
+
+print("Running workflow with telemetry...")
+result = workflow.start()
+print(f"Result: {result}")
+
+# Check telemetry metrics
+telemetry = get_telemetry()
+if telemetry.enabled:
+    metrics = telemetry.get_metrics()
+    print(f"\nTelemetry metrics collected:")
+    print(f"- Agent executions: {metrics['metrics']['agent_executions']}")
+    print(f"- Task completions: {metrics['metrics']['task_completions']}")
+    print(f"- Errors: {metrics['metrics']['errors']}")
+    print(f"- Session ID: {metrics['session_id']}")
+else:
+    print("\nTelemetry is disabled")
+
+print("\nTo disable telemetry, set any of these environment variables:")
+print("- PRAISONAI_TELEMETRY_DISABLED=true")
+print("- DO_NOT_TRACK=true")

src/praisonai-agents/test.py

@@ -0,0 +1,33 @@
+from praisonaiagents import Agent, Task, PraisonAIAgents
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+llm_config = {
+    "model": "openai/gpt-4o-mini",
+    "api_key": os.getenv('OPENAI_API_KEY'),
+    "temperature": 0.7,
+    "max_tokens": 2000
+}
+
+blog_agent = Agent(
+    role="Blog Writer",
+    goal="Write a blog post about AI",
+    backstory="Expert at writing blog posts",
+    llm=llm_config,
+)
+
+blog_task = Task(
+    description="Write a blog post about AI trends in 1 paragraph",
+    expected_output="Well-written blog post about AI trends",
+    agent=blog_agent
+)
+
+agents = PraisonAIAgents(
+    agents=[blog_agent],
+    tasks=[blog_task],
+    memory=False
+)
+
+result = agents.start()

src/praisonai-agents/test_agent_guardrails.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+Simple test for Agent guardrail functionality.
+"""
+
+def test_agent_guardrails():
+    """Test basic Agent guardrail functionality."""
+    print("Testing Agent guardrail functionality...")
+    
+    try:
+        from praisonaiagents import Agent, TaskOutput
+        print("✓ Basic imports successful")
+        
+        # Test function-based guardrail
+        def test_guardrail(task_output: TaskOutput):
+            if len(task_output.raw) < 10:
+                return False, "Too short"
+            return True, task_output
+        
+        # Test Agent creation with function guardrail
+        agent1 = Agent(
+            name="TestAgent1",
+            instructions="You are a test agent",
+            guardrail=test_guardrail,
+            max_guardrail_retries=2
+        )
+        print("✓ Agent with function guardrail created successfully")
+        print(f"  - Agent name: {agent1.name}")
+        print(f"  - Has guardrail function: {agent1._guardrail_fn is not None}")
+        print(f"  - Max retries: {agent1.max_guardrail_retries}")
+        
+        # Test Agent creation with string guardrail
+        agent2 = Agent(
+            name="TestAgent2",
+            instructions="You are a test agent",
+            guardrail="Ensure the response is polite and professional",
+            max_guardrail_retries=3
+        )
+        print("✓ Agent with LLM guardrail created successfully")
+        print(f"  - Agent name: {agent2.name}")
+        print(f"  - Has guardrail function: {agent2._guardrail_fn is not None}")
+        print(f"  - Max retries: {agent2.max_guardrail_retries}")
+        
+        # Test Agent without guardrail
+        agent3 = Agent(
+            name="TestAgent3",
+            instructions="You are a test agent"
+        )
+        print("✓ Agent without guardrail created successfully")
+        print(f"  - Agent name: {agent3.name}")
+        print(f"  - Has guardrail function: {agent3._guardrail_fn is None}")
+        
+        print("\n🎉 All Agent guardrail tests passed!")
+        return True
+        
+    except Exception as e:
+        print(f"✗ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+if __name__ == "__main__":
+    test_agent_guardrails()

src/praisonai-agents/test_auto_telemetry_final.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+Final test of automatic telemetry.
+"""
+
+print("Step 1: Import praisonaiagents...")
+from praisonaiagents import Agent, Task, PraisonAIAgents, get_telemetry
+
+print("\nStep 2: Check if telemetry is initialized...")
+telemetry = get_telemetry()
+print(f"  Telemetry enabled: {telemetry.enabled}")
+print(f"  PostHog available: {telemetry._posthog is not None}")
+
+print("\nStep 3: Check if Agent class is instrumented...")
+print(f"  Agent.__init__.__name__: {Agent.__init__.__name__}")
+
+print("\nStep 4: Create an agent...")
+agent = Agent(name="Test", role="Test", goal="Test", instructions="Test")
+print(f"  agent.chat wrapped: {hasattr(agent.chat, '__wrapped__')}")
+
+print("\nStep 5: Create and run a simple workflow...")
+task = Task(description="Say hello", expected_output="A greeting", agent=agent)
+workflow = PraisonAIAgents(agents=[agent], tasks=[task], process="sequential")
+
+# Check workflow instrumentation
+print(f"  workflow.execute_task wrapped: {hasattr(workflow.execute_task, '__wrapped__')}")
+
+result = workflow.start()
+print(f"\nResult: {result}")
+
+print("\nStep 6: Check metrics...")
+metrics = telemetry.get_metrics()
+print(f"  Metrics: {metrics['metrics']}")
+
+if metrics['metrics']['agent_executions'] > 0:
+    print("\n✅ Automatic telemetry is working!")
+else:
+    print("\n❌ Automatic telemetry is NOT working")
+    print("\nPossible reason: The auto_instrument_all() in __init__.py might be")
+    print("running before the telemetry module's lazy initialization completes.")

src/praisonai-agents/test_both_formats.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+
+from praisonaiagents import Agent, MCP
+import os
+
+def test_agent_direct():
+    """Test using gpt-4o-mini directly (agent.py path)"""
+    print("="*50)
+    print("Testing gpt-4o-mini (agent.py path)")
+    print("="*50)
+    
+    agent = Agent(
+        instructions="You are a helpful assistant that can break down complex problems.",
+        llm="gpt-4o-mini",
+        tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+    )
+    
+    result = agent.start("What are 5 steps to make coffee?")
+    print("✅ Agent direct path completed successfully")
+    return result
+
+def test_llm_class():
+    """Test using openai/gpt-4o-mini (llm.py path)"""
+    print("\n" + "="*50)
+    print("Testing openai/gpt-4o-mini (llm.py path)")
+    print("="*50)
+    
+    agent = Agent(
+        instructions="You are a helpful assistant that can break down complex problems.",
+        llm="openai/gpt-4o-mini",
+        tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+    )
+    
+    result = agent.start("What are 5 steps to make coffee?")
+    print("✅ LLM class path completed successfully")
+    return result
+
+if __name__ == "__main__":
+    try:
+        # Test both approaches
+        result1 = test_agent_direct()
+        result2 = test_llm_class()
+        
+        print("\n" + "="*50)
+        print("SUMMARY")
+        print("="*50)
+        print("✅ Both formats work correctly!")
+        print("✅ gpt-4o-mini uses agent.py direct OpenAI calls")
+        print("✅ openai/gpt-4o-mini uses llm.py LiteLLM wrapper")
+        print("✅ Both support tool calling and MCP integration")
+        
+    except Exception as e:
+        print(f"❌ Error occurred: {e}")
+        import traceback
+        traceback.print_exc()

src/praisonai-agents/test_guardrails.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+Test script for guardrails functionality in PraisonAI Agents.
+"""
+
+import os
+import sys
+import logging
+
+from praisonaiagents import Agent, Task, TaskOutput
+from praisonaiagents.guardrails import GuardrailResult, LLMGuardrail
+from typing import Tuple, Any
+
+
+def test_function_guardrail():
+    """Test function-based guardrail."""
+    print("Testing function-based guardrail...")
+    
+    def validate_output(task_output: TaskOutput) -> Tuple[bool, Any]:
+        """Simple validation function."""
+        if "error" in task_output.raw.lower():
+            return False, "Output contains errors"
+        if len(task_output.raw) < 10:
+            return False, "Output is too short"
+        return True, task_output
+    
+    # Create agent and task with guardrail
+    agent = Agent(
+        name="Test Agent",
+        role="Tester", 
+        goal="Test guardrails",
+        backstory="I am testing the guardrail functionality"
+    )
+    
+    task = Task(
+        description="Write a simple hello message",
+        expected_output="A friendly greeting message",
+        agent=agent,
+        guardrail=validate_output,
+        max_retries=2
+    )
+    
+    # Test with good output
+    good_output = TaskOutput(
+        description="Test task",
+        raw="Hello! This is a friendly greeting message from the agent.",
+        agent="Test Agent"
+    )
+    
+    result = task._process_guardrail(good_output)
+    assert result.success, f"Good output should pass: {result.error}"
+    print("✓ Good output passed guardrail")
+    
+    # Test with bad output
+    bad_output = TaskOutput(
+        description="Test task", 
+        raw="Error occurred",
+        agent="Test Agent"
+    )
+    
+    result = task._process_guardrail(bad_output)
+    assert not result.success, "Bad output should fail guardrail"
+    print("✓ Bad output failed guardrail as expected")
+    
+    print("Function-based guardrail test passed!\n")
+
+
+def test_string_guardrail():
+    """Test string-based LLM guardrail."""
+    print("Testing string-based LLM guardrail...")
+    
+    # Mock LLM for testing
+    class MockLLM:
+        def chat(self, prompt, **kwargs):
+            # Extract the actual output to validate from the prompt
+            # The LLMGuardrail sends a structured prompt with "Output to Validate:" section
+            if "Output to Validate:" in prompt:
+                # Split by "Output to Validate:" and get the content after it
+                parts = prompt.split("Output to Validate:")
+                if len(parts) > 1:
+                    output_content = parts[1].strip()
+                    # Check only the output content, not the validation criteria
+                    if "error" in output_content.lower():
+                        return "FAIL: The output contains error messages"
+                    return "PASS"
+            
+            # Fallback: if no "Output to Validate:" section, check the prompt directly
+            # This should rarely happen with proper LLMGuardrail usage
+            if "error" in prompt.lower() and "check if" not in prompt.lower():
+                return "FAIL: The output contains error messages"
+            return "PASS"
+    
+    # Create agent with mock LLM
+    agent = Agent(
+        name="Test Agent",
+        role="Tester",
+        goal="Test guardrails", 
+        backstory="I am testing the guardrail functionality"
+    )
+    agent.llm = MockLLM()
+    
+    task = Task(
+        description="Write a simple hello message",
+        expected_output="A friendly greeting message",
+        agent=agent,
+        guardrail="Check if the output is professional and does not contain errors",
+        max_retries=2
+    )
+    
+    # Test with good output
+    good_output = TaskOutput(
+        description="Test task",
+        raw="Hello! This is a professional greeting message.",
+        agent="Test Agent"
+    )
+    
+    result = task._process_guardrail(good_output)
+    assert result.success, f"Good output should pass: {result.error}"
+    print("✓ Good output passed LLM guardrail")
+    
+    # Test with bad output  
+    bad_output = TaskOutput(
+        description="Test task",
+        raw="There was an error in the system",
+        agent="Test Agent"
+    )
+    
+    result = task._process_guardrail(bad_output)
+    assert not result.success, "Bad output should fail LLM guardrail"
+    print("✓ Bad output failed LLM guardrail as expected")
+    
+    print("String-based LLM guardrail test passed!\n")
+
+
+def test_guardrail_result():
+    """Test GuardrailResult helper methods."""
+    print("Testing GuardrailResult...")
+    
+    # Test success case
+    success_result = GuardrailResult.from_tuple((True, "Modified output"))
+    assert success_result.success
+    assert success_result.result == "Modified output"
+    assert success_result.error == ""
+    print("✓ Success result created correctly")
+    
+    # Test failure case
+    failure_result = GuardrailResult.from_tuple((False, "Validation failed"))
+    assert not failure_result.success
+    assert failure_result.result is None
+    assert failure_result.error == "Validation failed"
+    print("✓ Failure result created correctly")
+    
+    print("GuardrailResult test passed!\n")
+
+
+def main():
+    """Run all tests."""
+    print("Running PraisonAI Agents Guardrails Tests...\n")
+    
+    try:
+        test_guardrail_result()
+        test_function_guardrail()
+        test_string_guardrail()
+        
+        print("🎉 All guardrail tests passed!")
+        print("\nGuardrails implementation is working correctly!")
+        
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+    
+    return True
+
+
+if __name__ == "__main__":
+    # Set up basic logging
+    logging.basicConfig(level=logging.WARNING)
+    
+    success = main()
+    sys.exit(0 if success else 1)

src/praisonai-agents/test_import_order.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+Test import order to debug telemetry availability.
+"""
+
+import sys
+
+print("1. Importing telemetry module directly...")
+try:
+    import praisonaiagents.telemetry
+    print("   ✅ Telemetry module imported successfully")
+except Exception as e:
+    print(f"   ❌ Failed: {type(e).__name__}: {e}")
+
+print("\n2. Importing main praisonaiagents...")
+try:
+    import praisonaiagents
+    print("   ✅ Main module imported successfully")
+    print(f"   _telemetry_available: {praisonaiagents._telemetry_available}")
+except Exception as e:
+    print(f"   ❌ Failed: {type(e).__name__}: {e}")
+
+print("\n3. Checking what prevented telemetry import...")
+# The main __init__.py tries to import from .telemetry
+# Let's see if we can import the functions directly
+try:
+    from praisonaiagents.telemetry import (
+        get_telemetry,
+        enable_telemetry,
+        disable_telemetry,
+        MinimalTelemetry,
+        TelemetryCollector
+    )
+    print("   ✅ All telemetry functions imported successfully")
+except Exception as e:
+    print(f"   ❌ Failed to import telemetry functions: {type(e).__name__}: {e}")
+    import traceback
+    traceback.print_exc()

src/praisonai-agents/test_litellm_telemetry.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Test script to identify litellm telemetry behavior"""
+
+import os
+import sys
+
+# Disable litellm telemetry before importing
+os.environ["LITELLM_TELEMETRY"] = "False"
+os.environ["LITELLM_LOG"] = "ERROR"
+
+print("Environment variables set:")
+print(f"LITELLM_TELEMETRY: {os.environ.get('LITELLM_TELEMETRY')}")
+print(f"LITELLM_LOG: {os.environ.get('LITELLM_LOG')}")
+
+print("\nImporting litellm...")
+import litellm
+
+print(f"\nChecking litellm telemetry status:")
+print(f"Has telemetry attribute: {hasattr(litellm, 'telemetry')}")
+if hasattr(litellm, 'telemetry'):
+    print(f"Telemetry value: {litellm.telemetry}")
+
+# Try to disable telemetry programmatically
+if hasattr(litellm, 'telemetry'):
+    litellm.telemetry = False
+    print(f"\nTelemetry disabled programmatically")
+
+# Check callbacks
+print(f"\nCallbacks: {litellm.callbacks}")
+print(f"Success callbacks: {litellm.success_callback}")
+print(f"Async success callbacks: {litellm._async_success_callback}")
+
+# Test a simple completion
+print("\n\nTesting completion (this might trigger telemetry)...")
+try:
+    response = litellm.completion(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": "Say hi"}],
+        mock_response="Hi there!"
+    )
+    print("Completion successful")
+except Exception as e:
+    print(f"Error: {e}")
+
+print("\nDone. Check if any network requests were made to BerriAI/litellm")

src/praisonai-agents/test_manual_instrumentation.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Test manual instrumentation to verify it works.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.telemetry import get_telemetry
+from praisonaiagents.telemetry.integration import auto_instrument_all
+
+# Manually call auto_instrument_all AFTER importing classes
+print("1. Calling auto_instrument_all()...")
+auto_instrument_all()
+
+print("\n2. Creating agent and task...")
+agent = Agent(
+    name="Calculator",
+    role="Math Expert",
+    goal="Perform calculations",
+    instructions="You are a helpful math expert."
+)
+
+task = Task(
+    description="Calculate 3 + 3",
+    expected_output="The sum",
+    agent=agent
+)
+
+print("\n3. Creating workflow...")
+workflow = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    process="sequential"
+)
+
+print("\n4. Running workflow...")
+result = workflow.start()
+print(f"Result: {result}")
+
+print("\n5. Checking telemetry metrics...")
+telemetry = get_telemetry()
+metrics = telemetry.get_metrics()
+print(f"Telemetry metrics: {metrics['metrics']}")
+print(f"PostHog available: {telemetry._posthog is not None}")
+
+if metrics['metrics']['agent_executions'] > 0:
+    print("\n✅ SUCCESS! Telemetry is working correctly.")
+    print("   Data will be sent to PostHog on program exit.")
+else:
+    print("\n❌ FAILED! Telemetry metrics are still 0.")
+    
+    # Additional debugging
+    print("\nDebugging info:")
+    print(f"  agent.chat wrapped: {hasattr(agent.chat, '__wrapped__')}")
+    print(f"  workflow.execute_task wrapped: {hasattr(workflow.execute_task, '__wrapped__')}")

src/praisonai-agents/test_posthog.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""
+Test PostHog integration in telemetry.
+"""
+
+import os
+import sys
+
+# Ensure telemetry is enabled
+if 'PRAISONAI_TELEMETRY_DISABLED' in os.environ:
+    del os.environ['PRAISONAI_TELEMETRY_DISABLED']
+if 'PRAISONAI_DISABLE_TELEMETRY' in os.environ:
+    del os.environ['PRAISONAI_DISABLE_TELEMETRY']
+if 'DO_NOT_TRACK' in os.environ:
+    del os.environ['DO_NOT_TRACK']
+
+# Test PostHog availability
+print("=== Testing PostHog Integration ===")
+print("\n1. Checking PostHog import:")
+try:
+    from posthog import Posthog
+    print("✓ PostHog is available")
+except ImportError as e:
+    print("✗ PostHog is NOT available")
+    print(f"  Error: {e}")
+    print("\n  To fix: pip install posthog")
+    sys.exit(1)
+
+# Test telemetry initialization
+print("\n2. Testing telemetry initialization:")
+from praisonaiagents.telemetry import get_telemetry
+
+telemetry = get_telemetry()
+print(f"✓ Telemetry enabled: {telemetry.enabled}")
+print(f"✓ Session ID: {telemetry.session_id}")
+
+# Check PostHog client
+print("\n3. Checking PostHog client:")
+if hasattr(telemetry, '_posthog') and telemetry._posthog:
+    print("✓ PostHog client is initialized")
+    print(f"  API Key: {telemetry._posthog.api_key[:10]}...")
+    print(f"  Host: {telemetry._posthog.host}")
+else:
+    print("✗ PostHog client is NOT initialized")
+
+# Test tracking
+print("\n4. Testing event tracking:")
+telemetry.track_agent_execution("TestAgent", success=True)
+telemetry.track_task_completion("TestTask", success=True)
+telemetry.track_tool_usage("test_tool", success=True)
+print("✓ Events tracked locally")
+
+# Test flush (which should send to PostHog)
+print("\n5. Testing flush (should send to PostHog):")
+telemetry.flush()
+print("✓ Flush completed")
+
+# Check metrics
+print("\n6. Current metrics:")
+metrics = telemetry.get_metrics()
+for key, value in metrics.items():
+    print(f"  {key}: {value}")
+
+print("\n=== PostHog Test Complete ===")

src/praisonai-agents/test_posthog_detailed.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Detailed test of PostHog integration showing why events might not be sent.
+"""
+
+import os
+import sys
+import time
+
+# Ensure telemetry is enabled
+for var in ['PRAISONAI_TELEMETRY_DISABLED', 'PRAISONAI_DISABLE_TELEMETRY', 'DO_NOT_TRACK']:
+    if var in os.environ:
+        del os.environ[var]
+
+print("=== Detailed PostHog Test ===")
+
+# Test PostHog directly
+print("\n1. Testing PostHog directly:")
+try:
+    from posthog import Posthog
+    
+    # Create a PostHog client directly
+    posthog_client = Posthog(
+        project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+        host='https://eu.i.posthog.com'
+    )
+    
+    # Send a test event
+    print("  Sending test event...")
+    posthog_client.capture(
+        distinct_id='test-user-123',
+        event='direct_test_event',
+        properties={
+            'test': True,
+            'timestamp': time.time()
+        }
+    )
+    
+    # Flush to ensure event is sent
+    print("  Flushing...")
+    posthog_client.flush()
+    
+    print("✓ Direct PostHog test completed")
+    
+except Exception as e:
+    print(f"✗ Direct PostHog test failed: {e}")
+    import traceback
+    traceback.print_exc()
+
+# Test telemetry integration
+print("\n2. Testing telemetry integration:")
+from praisonaiagents.telemetry.telemetry import MinimalTelemetry
+
+# Create a new telemetry instance with debug output
+class DebugTelemetry(MinimalTelemetry):
+    def flush(self):
+        """Override flush to add debug output."""
+        if not self.enabled:
+            print("  [DEBUG] Telemetry disabled, skipping flush")
+            return
+            
+        metrics = self.get_metrics()
+        print(f"  [DEBUG] Flushing metrics: {metrics}")
+        
+        # Check PostHog client
+        if hasattr(self, '_posthog') and self._posthog:
+            print("  [DEBUG] PostHog client exists")
+            print(f"  [DEBUG] PostHog API key: {self._posthog.api_key[:20]}...")
+            print(f"  [DEBUG] PostHog host: {self._posthog.host}")
+            
+            try:
+                # Send events
+                print("  [DEBUG] Sending sdk_used event...")
+                self._posthog.capture(
+                    distinct_id='anonymous',
+                    event='sdk_used',
+                    properties={
+                        'version': self._environment['framework_version'],
+                        'os': self._environment['os_type'],
+                        'python_version': self._environment['python_version'],
+                        'session_id': self.session_id,
+                        'metrics': self._metrics,
+                        '$process_person_profile': False
+                    }
+                )
+                
+                print("  [DEBUG] Sending test event...")
+                self._posthog.capture('test-id', 'test-event')
+                
+                # Explicitly flush PostHog
+                print("  [DEBUG] Flushing PostHog client...")
+                self._posthog.flush()
+                
+                print("  [DEBUG] PostHog flush completed")
+            except Exception as e:
+                print(f"  [DEBUG] PostHog error: {e}")
+                import traceback
+                traceback.print_exc()
+        else:
+            print("  [DEBUG] No PostHog client available")
+        
+        # Reset counters
+        for key in self._metrics:
+            if isinstance(self._metrics[key], int):
+                self._metrics[key] = 0
+
+# Create debug telemetry instance
+telemetry = DebugTelemetry(enabled=True)
+
+# Track some events
+print("\n3. Tracking events:")
+telemetry.track_agent_execution("TestAgent", success=True)
+telemetry.track_task_completion("TestTask", success=True)
+telemetry.track_tool_usage("calculator", success=True)
+print("✓ Events tracked")
+
+# Flush with debug output
+print("\n4. Flushing telemetry:")
+telemetry.flush()
+
+# Wait a moment for async operations
+print("\n5. Waiting for async operations...")
+time.sleep(2)
+
+print("\n=== Test Complete ===")
+
+# Additional debug info
+print("\n6. Debug information:")
+print(f"  POSTHOG_AVAILABLE: {telemetry.logger.parent.manager.loggerDict.get('posthog', 'Not found')}")
+print(f"  Telemetry module location: {MinimalTelemetry.__module__}")
+
+# Check if PostHog is properly installed
+print("\n7. PostHog installation check:")
+try:
+    import posthog
+    print(f"  PostHog version: {posthog.VERSION}")
+    print(f"  PostHog location: {posthog.__file__}")
+except Exception as e:
+    print(f"  PostHog check failed: {e}")

src/praisonai-agents/test_posthog_direct.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""
+Test PostHog integration directly to verify it's working.
+"""
+
+import os
+from praisonaiagents.telemetry import get_telemetry
+from praisonaiagents.telemetry.integration import auto_instrument_all
+
+# Enable automatic telemetry instrumentation
+auto_instrument_all()
+
+telemetry = get_telemetry()
+print(f"Telemetry enabled: {telemetry.enabled}")
+print(f"PostHog available: {telemetry._posthog is not None}")
+
+if telemetry.enabled and telemetry._posthog:
+    # Manually track some events
+    telemetry.track_agent_execution("TestAgent", success=True)
+    telemetry.track_task_completion("TestTask", success=True)
+    telemetry.track_tool_usage("TestTool")
+    
+    # Get metrics before flush
+    metrics = telemetry.get_metrics()
+    print(f"\nMetrics before flush:")
+    print(f"- Agent executions: {metrics['metrics']['agent_executions']}")
+    print(f"- Task completions: {metrics['metrics']['task_completions']}")
+    print(f"- Tool calls: {metrics['metrics']['tool_calls']}")
+    
+    # Manually flush to send to PostHog
+    print("\nFlushing telemetry to PostHog...")
+    telemetry.flush()
+    
+    # Get metrics after flush (should be reset)
+    metrics = telemetry.get_metrics()
+    print(f"\nMetrics after flush (should be reset):")
+    print(f"- Agent executions: {metrics['metrics']['agent_executions']}")
+    print(f"- Task completions: {metrics['metrics']['task_completions']}")
+    print(f"- Tool calls: {metrics['metrics']['tool_calls']}")
+    
+    print("\n✅ If no errors above, PostHog integration is working!")
+else:
+    print("\n❌ Telemetry or PostHog is not available")

src/praisonai-agents/test_posthog_error.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""
+Test PostHog initialization error.
+"""
+
+from posthog import Posthog
+
+print("Testing PostHog initialization with telemetry parameters...")
+try:
+    posthog_client = Posthog(
+        project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+        host='https://eu.i.posthog.com',
+        disable_geoip=True,
+        events_to_ignore=['test-event']
+    )
+    print(f"✅ PostHog client created: {posthog_client}")
+except Exception as e:
+    print(f"❌ PostHog initialization failed: {type(e).__name__}: {e}")
+    import traceback
+    traceback.print_exc()

src/praisonai-agents/test_posthog_import.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+Test PostHog import and initialization.
+"""
+
+print("1. Testing PostHog import...")
+try:
+    from posthog import Posthog
+    print("✅ PostHog imported successfully")
+except ImportError as e:
+    print(f"❌ PostHog import failed: {e}")
+    exit(1)
+
+print("\n2. Testing PostHog initialization...")
+try:
+    posthog_client = Posthog(
+        project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+        host='https://eu.i.posthog.com'
+    )
+    print("✅ PostHog client created successfully")
+except Exception as e:
+    print(f"❌ PostHog initialization failed: {e}")
+    exit(1)
+
+print("\n3. Testing PostHog capture...")
+try:
+    posthog_client.capture(
+        distinct_id='test-user',
+        event='test-event',
+        properties={'test': True}
+    )
+    print("✅ PostHog capture successful")
+except Exception as e:
+    print(f"❌ PostHog capture failed: {e}")
+
+print("\n4. Testing telemetry module...")
+from praisonaiagents.telemetry.telemetry import MinimalTelemetry, POSTHOG_AVAILABLE
+print(f"POSTHOG_AVAILABLE in telemetry module: {POSTHOG_AVAILABLE}")
+
+print("\n5. Creating MinimalTelemetry instance...")
+telemetry = MinimalTelemetry(enabled=True)
+print(f"Telemetry enabled: {telemetry.enabled}")
+print(f"Telemetry _posthog: {telemetry._posthog}")
+
+print("\n6. Checking get_telemetry()...")
+from praisonaiagents.telemetry import get_telemetry
+global_telemetry = get_telemetry()
+print(f"Global telemetry enabled: {global_telemetry.enabled}")
+print(f"Global telemetry _posthog: {global_telemetry._posthog}")
+print(f"Global telemetry session_id: {global_telemetry.session_id}")

src/praisonai-agents/test_self_reflection.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Test self-reflection functionality in both Agent and LLM classes"""
+
+from praisonaiagents import Agent
+from praisonaiagents.llm import LLM
+
+def test_agent_self_reflection():
+    """Test self-reflection in Agent class"""
+    print("=== Testing Agent Self-Reflection ===")
+    agent = Agent(
+        name="ReflectiveAgent",
+        instructions="You are a helpful assistant.",
+        llm="gpt-4o-mini",
+        self_reflect=True,
+        min_reflect=1,
+        max_reflect=3
+    )
+    
+    response = agent.start("What is 2+2? Be brief.")
+    print(f"Agent Response: {response}")
+    print()
+
+def test_llm_self_reflection():
+    """Test self-reflection in LLM class directly"""
+    print("=== Testing LLM Self-Reflection ===")
+    llm = LLM(model="gpt-4o-mini")
+    
+    response = llm.get_response(
+        prompt="What is 2+2? Be brief.",
+        system_prompt="You are a helpful assistant.",
+        self_reflect=True,
+        min_reflect=1,
+        max_reflect=3,
+        verbose=True
+    )
+    print(f"LLM Response: {response}")
+    print()
+
+def test_llm_no_reflection():
+    """Test LLM without self-reflection for comparison"""
+    print("=== Testing LLM Without Self-Reflection ===")
+    llm = LLM(model="gpt-4o-mini")
+    
+    response = llm.get_response(
+        prompt="What is 2+2? Be brief.",
+        system_prompt="You are a helpful assistant.",
+        self_reflect=False,
+        verbose=True
+    )
+    print(f"LLM Response: {response}")
+    print()
+
+if __name__ == "__main__":
+    # Test without reflection first
+    test_llm_no_reflection()
+    
+    # Test with reflection
+    test_llm_self_reflection()
+    
+    # Test agent reflection
+    test_agent_self_reflection()

src/praisonai-agents/test_sequential_fix.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+
+from praisonaiagents import Agent, MCP
+import os
+
+def test_agent_direct():
+    """Test using gpt-4o-mini directly (agent.py path)"""
+    print("=" * 50)
+    print("Testing gpt-4o-mini (agent.py path)")
+    print("=" * 50)
+    
+    agent = Agent(
+        instructions="You are a helpful assistant that can break down complex problems.",
+        llm="gpt-4o-mini",
+        tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+    )
+    
+    result = agent.start("What are 3 steps to make coffee?")
+    print("✅ Agent direct path completed successfully")
+    return result
+
+def test_llm_class():
+    """Test using openai/gpt-4o-mini (llm.py path)"""
+    print("\n" + "=" * 50)
+    print("Testing openai/gpt-4o-mini (llm.py path)")
+    print("=" * 50)
+    
+    agent = Agent(
+        instructions="You are a helpful assistant that can break down complex problems.",
+        llm="openai/gpt-4o-mini",
+        tools=MCP("npx -y @modelcontextprotocol/server-sequential-thinking")
+    )
+    
+    result = agent.start("What are 3 steps to make coffee?")
+    print("✅ LLM class path completed successfully")
+    return result
+
+if __name__ == "__main__":
+    try:
+        # Test both approaches
+        result1 = test_agent_direct()
+        result2 = test_llm_class()
+        
+        print("\n" + "=" * 50)
+        print("SUMMARY")
+        print("=" * 50)
+        print("✅ Both formats work correctly!")
+        print("✅ gpt-4o-mini uses agent.py direct OpenAI calls")
+        print("✅ openai/gpt-4o-mini uses llm.py LiteLLM wrapper")
+        print("✅ Both support sequential tool calling and MCP integration")
+        print("✅ Sequential thinking tool works properly in both modes")
+        
+    except Exception as e:
+        print(f"❌ Error occurred: {e}")
+        import traceback
+        traceback.print_exc()

src/praisonai-agents/test_telemetry_automatic.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Test that telemetry works automatically without manual instrumentation.
+"""
+
+# NO manual telemetry setup - it should work automatically!
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Create a simple agent
+agent = Agent(
+    name="AutoTelemetryTest",
+    role="Math Expert",
+    goal="Perform calculations",
+    instructions="You are a helpful math expert."
+)
+
+# Create a task
+task = Task(
+    description="Calculate 5 + 5",
+    expected_output="The sum",
+    agent=agent
+)
+
+# Create and run workflow
+workflow = PraisonAIAgents(
+    agents=[agent],
+    tasks=[task],
+    process="sequential"
+)
+
+print("Running workflow (telemetry should be automatic)...")
+result = workflow.start()
+print(f"Result: {result}")
+
+# Check if telemetry was collected
+from praisonaiagents.telemetry import get_telemetry
+telemetry = get_telemetry()
+
+if telemetry.enabled:
+    metrics = telemetry.get_metrics()
+    print(f"\n✅ Telemetry is working automatically!")
+    print(f"- Agent executions: {metrics['metrics']['agent_executions']}")
+    print(f"- Task completions: {metrics['metrics']['task_completions']}")
+    print(f"- Session ID: {metrics['session_id']}")
+    print("\nTelemetry data will be sent to PostHog on program exit.")
+else:
+    print("\n❌ Telemetry is disabled")

src/praisonai-agents/test_telemetry_disabled.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Test to verify litellm telemetry is properly disabled"""
+
+import sys
+import os
+
+print("Testing litellm telemetry is disabled...")
+
+# Test 1: Check environment variable is set
+print(f"\n1. Environment variable LITELLM_TELEMETRY: {os.environ.get('LITELLM_TELEMETRY', 'NOT SET')}")
+
+# Test 2: Import praisonaiagents and check if telemetry is disabled
+try:
+    from praisonaiagents.llm import LLM
+    print("2. Successfully imported LLM from praisonaiagents")
+    
+    # Check if litellm was imported and telemetry is disabled
+    import litellm
+    print(f"3. litellm.telemetry = {litellm.telemetry}")
+    
+    # Test 3: Create an LLM instance
+    llm = LLM(model="gpt-3.5-turbo")
+    print("4. Successfully created LLM instance")
+    
+    # Check telemetry again after instance creation
+    print(f"5. After LLM creation, litellm.telemetry = {litellm.telemetry}")
+    
+    # Test 4: Try a mock completion
+    print("\n6. Testing mock completion...")
+    response = litellm.completion(
+        model="gpt-3.5-turbo",
+        messages=[{"role": "user", "content": "test"}],
+        mock_response="test response"
+    )
+    print("   Mock completion successful")
+    
+    # Final check
+    print(f"\n7. Final check: litellm.telemetry = {litellm.telemetry}")
+    
+    if litellm.telemetry == False:
+        print("\n✅ SUCCESS: Telemetry is properly disabled!")
+    else:
+        print("\n❌ FAILURE: Telemetry is still enabled!")
+        sys.exit(1)
+        
+except Exception as e:
+    print(f"\n❌ ERROR: {e}")
+    import traceback
+    traceback.print_exc()
+    sys.exit(1)
+
+print("\nAll tests passed! Telemetry should be disabled.")

src/praisonai-agents/test_telemetry_integration.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Test to demonstrate why telemetry isn't being sent by default.
+"""
+
+import os
+
+# Ensure telemetry is enabled
+for var in ['PRAISONAI_TELEMETRY_DISABLED', 'PRAISONAI_DISABLE_TELEMETRY', 'DO_NOT_TRACK']:
+    if var in os.environ:
+        del os.environ[var]
+
+print("=== Testing Telemetry Integration ===")
+
+# Test 1: Default behavior (no telemetry)
+print("\n1. Testing default Agent behavior:")
+from praisonaiagents import Agent, Task
+
+agent = Agent(
+    name="TestAgent",
+    role="Tester",
+    goal="Test telemetry",
+    backstory="I test things",
+    llm="gpt-4o-mini"
+)
+
+task = Task(
+    description="Say hello",
+    expected_output="A greeting",
+    agent=agent
+)
+
+# Check if agent has telemetry
+print(f"  Agent has telemetry: {hasattr(agent, '_telemetry')}")
+print(f"  Agent methods: {[m for m in dir(agent) if 'telemetry' in m.lower()]}")
+
+# Test 2: Manual telemetry integration
+print("\n2. Testing manual telemetry integration:")
+from praisonaiagents.telemetry import get_telemetry
+from praisonaiagents.telemetry.integration import instrument_agent
+
+telemetry = get_telemetry()
+print(f"  Telemetry enabled: {telemetry.enabled}")
+
+# Manually instrument the agent
+instrument_agent(agent, telemetry)
+print("  Agent instrumented manually")
+
+# Test 3: Auto-instrumentation
+print("\n3. Testing auto-instrumentation:")
+from praisonaiagents.telemetry.integration import auto_instrument_all
+
+# Enable auto-instrumentation
+auto_instrument_all(telemetry)
+print("  Auto-instrumentation enabled")
+
+# Create a new agent to test auto-instrumentation
+new_agent = Agent(
+    name="AutoInstrumentedAgent",
+    role="Tester",
+    goal="Test auto telemetry",
+    backstory="I test auto-instrumentation",
+    llm="gpt-4o-mini"
+)
+
+print(f"  New agent instrumented: {hasattr(new_agent.execute, '__wrapped__')}")
+
+# Test 4: Check if telemetry data is collected
+print("\n4. Checking telemetry metrics:")
+initial_metrics = telemetry.get_metrics()
+print(f"  Initial metrics: {initial_metrics['metrics']}")
+
+# The problem: telemetry is never flushed automatically!
+print("\n5. The Issue:")
+print("  ✗ Telemetry is implemented but NOT automatically integrated")
+print("  ✗ Even if integrated, flush() is never called automatically")
+print("  ✗ PostHog events are only sent when flush() is explicitly called")
+
+# Test 5: Solution - manual flush
+print("\n6. Solution - Manual flush:")
+telemetry.flush()
+print("  ✓ Manual flush called - events sent to PostHog")
+
+# Test 6: Workflow integration
+print("\n7. Testing workflow integration:")
+from praisonaiagents import PraisonAIAgents
+
+agents = [
+    Agent(name="Agent1", role="First", goal="Do first task", backstory="I'm first"),
+    Agent(name="Agent2", role="Second", goal="Do second task", backstory="I'm second")
+]
+
+tasks = [
+    Task(description="Task 1", expected_output="Output 1", agent=agents[0]),
+    Task(description="Task 2", expected_output="Output 2", agent=agents[1])
+]
+
+workflow = PraisonAIAgents(
+    agents=agents,
+    tasks=tasks,
+    process="sequential"
+)
+
+print(f"  Workflow has telemetry integration: {hasattr(workflow.start, '__wrapped__')}")
+
+print("\n=== Summary of Issues ===")
+print("\n1. No automatic integration:")
+print("   - Agent and PraisonAIAgents classes don't automatically use telemetry")
+print("   - Need to manually call instrument_agent() or auto_instrument_all()")
+
+print("\n2. No automatic flush:")
+print("   - Even when integrated, telemetry data is only collected locally")
+print("   - flush() must be called explicitly to send data to PostHog")
+print("   - No automatic flush on program exit or periodic flush")
+
+print("\n3. Missing integration points:")
+print("   - Agent.__init__ doesn't initialize telemetry")
+print("   - Agent.execute() doesn't track execution")
+print("   - PraisonAIAgents doesn't track workflow execution")
+print("   - No atexit handler to flush on program termination")
+
+print("\n=== Recommendations ===")
+print("\n1. Add automatic integration in Agent.__init__ and PraisonAIAgents.__init__")
+print("2. Add atexit handler to flush telemetry on program exit")
+print("3. Add periodic flush (e.g., every 100 events or 60 seconds)")
+print("4. Document telemetry behavior clearly for users")

src/praisonai-agents/test_telemetry_simple.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""
+Simple test to check telemetry.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.telemetry import get_telemetry
+
+# Create workflow
+agent = Agent(name="Test", role="Tester", goal="Test", instructions="Test")
+task = Task(description="Test", expected_output="Test", agent=agent)
+workflow = PraisonAIAgents(agents=[agent], tasks=[task], process="sequential")
+
+# Run workflow
+print("Running workflow...")
+result = workflow.start()
+
+# Check telemetry
+telemetry = get_telemetry()
+metrics = telemetry.get_metrics()
+print(f"\nTelemetry metrics: {metrics['metrics']}")
+print(f"Session ID: {metrics['session_id']}")
+
+# Check if telemetry will be sent
+print(f"\nTelemetry enabled: {telemetry.enabled}")
+print(f"PostHog client available: {telemetry._posthog is not None}")
+
+if telemetry._posthog:
+    print("\n✅ Telemetry will be sent to PostHog on program exit")

src/praisonai-agents/tests/guardrails_example.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating guardrails functionality in PraisonAI Agents.
+
+This example shows both function-based and LLM-based guardrails
+for validating task outputs.
+"""
+
+import sys
+import os
+from typing import Tuple, Any
+
+# Add project to path
+sys.path.insert(0, os.path.abspath('..'))
+
+from praisonaiagents import Agent, Task, TaskOutput
+
+
+def email_validator(task_output: TaskOutput) -> Tuple[bool, Any]:
+    """
+    Function-based guardrail to validate email content.
+    
+    Args:
+        task_output: The task output to validate
+        
+    Returns:
+        Tuple of (success, result_or_error)
+    """
+    content = task_output.raw.lower()
+    
+    # Check for required email components
+    if "subject:" not in content:
+        return False, "Email must include a subject line"
+    
+    if "dear" not in content and "hello" not in content:
+        return False, "Email must include a proper greeting"
+    
+    if len(content) < 50:
+        return False, "Email content is too short"
+        
+    if "error" in content or "problem" in content:
+        return False, "Email should not mention errors or problems"
+        
+    return True, task_output
+
+
+def main():
+    """Run the guardrails example."""
+    print("PraisonAI Agents - Guardrails Example")
+    print("=====================================\n")
+    
+    # Create an agent
+    agent = Agent(
+        name="Email Assistant",
+        role="Professional Email Writer",
+        goal="Write clear, professional emails",
+        backstory="I am an AI assistant specialized in writing professional emails"
+    )
+    
+    print("1. Testing Function-based Guardrail")
+    print("------------------------------------")
+    
+    # Create task with function-based guardrail
+    task_with_function_guardrail = Task(
+        description="Write a professional email to a client about project completion",
+        expected_output="A well-formatted professional email",
+        agent=agent,
+        guardrail=email_validator,  # Function-based guardrail
+        max_retries=2
+    )
+    
+    print(f"Task created with function guardrail: {email_validator.__name__}")
+    print(f"Max retries: {task_with_function_guardrail.max_retries}")
+    
+    # Simulate a task output that should pass
+    good_output = TaskOutput(
+        description="Email task",
+        raw="""Subject: Project Completion Update
+
+Dear Client,
+
+I am pleased to inform you that your project has been completed successfully. 
+All deliverables have been reviewed and are ready for your review. 
+Please let me know if you have any questions.
+
+Best regards,
+Project Team""",
+        agent="Email Assistant"
+    )
+    
+    result = task_with_function_guardrail._process_guardrail(good_output)
+    print(f"Good email result: {'PASSED' if result.success else 'FAILED'}")
+    if not result.success:
+        print(f"Error: {result.error}")
+    
+    # Simulate a task output that should fail
+    bad_output = TaskOutput(
+        description="Email task",
+        raw="Hi there, there was an error with your project.",
+        agent="Email Assistant"
+    )
+    
+    result = task_with_function_guardrail._process_guardrail(bad_output)
+    print(f"Bad email result: {'PASSED' if result.success else 'FAILED'}")
+    if not result.success:
+        print(f"Error: {result.error}")
+    
+    print("\n2. Testing String-based LLM Guardrail")
+    print("-------------------------------------")
+    
+    # Create task with string-based guardrail
+    task_with_llm_guardrail = Task(
+        description="Write a marketing email for a new product launch",
+        expected_output="Engaging marketing content",
+        agent=agent,
+        guardrail="Ensure the content is professional, engaging, includes a clear call-to-action, and is free of errors",
+        max_retries=3
+    )
+    
+    print("Task created with LLM-based guardrail")
+    print("Guardrail description: 'Ensure the content is professional, engaging, includes a clear call-to-action, and is free of errors'")
+    print(f"Max retries: {task_with_llm_guardrail.max_retries}")
+    
+    print("\n3. Backward Compatibility")
+    print("-------------------------")
+    
+    # Create task without guardrail (backward compatible)
+    task_without_guardrail = Task(
+        description="Write a simple thank you note",
+        expected_output="A brief thank you message",
+        agent=agent
+    )
+    
+    print("Task created without guardrail (backward compatible)")
+    print(f"Guardrail function: {task_without_guardrail._guardrail_fn}")
+    
+    # Test that it doesn't break existing functionality
+    simple_output = TaskOutput(
+        description="Thank you task",
+        raw="Thank you for your business!",
+        agent="Email Assistant"
+    )
+    
+    result = task_without_guardrail._process_guardrail(simple_output)
+    print(f"No guardrail result: {'PASSED' if result.success else 'FAILED'}")
+    
+    print("\n✅ Guardrails example completed successfully!")
+    print("\nKey Features Demonstrated:")
+    print("- Function-based guardrails with custom validation logic")
+    print("- String-based LLM guardrails using natural language")
+    print("- Configurable retry mechanism")
+    print("- Backward compatibility with existing tasks")
+    print("- Integration with TaskOutput validation")
+
+
+if __name__ == "__main__":
+    main()

src/praisonai-agents/tests/state_based_workflow_example.py

@@ -0,0 +1,294 @@
+"""
+State-Based Workflow Control Example
+===================================
+
+This example shows how to use state for:
+1. Conditional task execution based on state
+2. Loop control using state
+3. Dynamic workflow modification
+4. State-based error handling and recovery
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from typing import Dict, Any, List
+import random
+import json
+
+# Tool functions that use state for control flow
+def analyze_data_quality() -> Dict[str, Any]:
+    """Analyze data and set quality state"""
+    # Simulate data quality check
+    quality_score = random.uniform(0.5, 1.0)
+    has_errors = random.choice([True, False])
+    
+    # Set state based on analysis
+    workflow.set_state("quality_score", quality_score)
+    workflow.set_state("has_errors", has_errors)
+    workflow.set_state("data_status", "analyzed")
+    
+    if quality_score < 0.7:
+        workflow.set_state("quality_level", "poor")
+    elif quality_score < 0.85:
+        workflow.set_state("quality_level", "moderate")
+    else:
+        workflow.set_state("quality_level", "good")
+    
+    return {
+        "quality_score": quality_score,
+        "has_errors": has_errors,
+        "quality_level": workflow.get_state("quality_level"),
+        "recommendation": "clean_data" if has_errors or quality_score < 0.8 else "proceed"
+    }
+
+def clean_data_based_on_state() -> Dict[str, Any]:
+    """Clean data based on current state"""
+    quality_score = workflow.get_state("quality_score", 0)
+    has_errors = workflow.get_state("has_errors", False)
+    cleaning_attempts = workflow.get_state("cleaning_attempts", 0)
+    
+    # Increment cleaning attempts
+    workflow.set_state("cleaning_attempts", cleaning_attempts + 1)
+    
+    # Simulate cleaning improvement
+    improvement = random.uniform(0.1, 0.2)
+    new_quality = min(quality_score + improvement, 0.95)
+    
+    workflow.set_state("quality_score", new_quality)
+    workflow.set_state("has_errors", False)
+    workflow.set_state("last_cleaning_improvement", improvement)
+    
+    # Determine if more cleaning needed
+    if new_quality < 0.8 and cleaning_attempts < 3:
+        status = "needs_more_cleaning"
+    else:
+        status = "cleaning_complete"
+        workflow.set_state("data_status", "cleaned")
+    
+    return {
+        "previous_score": quality_score,
+        "new_score": new_quality,
+        "improvement": improvement,
+        "attempts": cleaning_attempts + 1,
+        "status": status
+    }
+
+def process_batch_with_state() -> Dict[str, Any]:
+    """Process data in batches using state to track progress"""
+    # Initialize batch processing state
+    if not workflow.has_state("batch_total"):
+        batch_total = random.randint(5, 10)
+        workflow.set_state("batch_total", batch_total)
+        workflow.set_state("batch_current", 0)
+        workflow.set_state("batch_results", [])
+    
+    # Get current state
+    batch_total = workflow.get_state("batch_total")
+    batch_current = workflow.get_state("batch_current")
+    batch_results = workflow.get_state("batch_results", [])
+    
+    # Process current batch
+    batch_current += 1
+    result = {
+        "batch_number": batch_current,
+        "records_processed": random.randint(100, 500),
+        "errors": random.randint(0, 5)
+    }
+    batch_results.append(result)
+    
+    # Update state
+    workflow.set_state("batch_current", batch_current)
+    workflow.set_state("batch_results", batch_results)
+    
+    # Determine if more batches
+    if batch_current < batch_total:
+        status = "more_batches"
+        workflow.set_state("batch_status", "in_progress")
+    else:
+        status = "all_batches_complete"
+        workflow.set_state("batch_status", "completed")
+        workflow.set_state("total_records", sum(r["records_processed"] for r in batch_results))
+        workflow.set_state("total_errors", sum(r["errors"] for r in batch_results))
+    
+    return {
+        "batch": result,
+        "progress": f"{batch_current}/{batch_total}",
+        "status": status,
+        "remaining": batch_total - batch_current
+    }
+
+def generate_report_from_state() -> Dict[str, Any]:
+    """Generate comprehensive report from accumulated state"""
+    # Gather all relevant state
+    report = {
+        "data_quality": {
+            "initial_score": workflow.get_state("quality_score", 0),
+            "quality_level": workflow.get_state("quality_level", "unknown"),
+            "cleaning_attempts": workflow.get_state("cleaning_attempts", 0),
+            "final_status": workflow.get_state("data_status", "unknown")
+        },
+        "batch_processing": {
+            "total_batches": workflow.get_state("batch_total", 0),
+            "completed_batches": workflow.get_state("batch_current", 0),
+            "total_records": workflow.get_state("total_records", 0),
+            "total_errors": workflow.get_state("total_errors", 0),
+            "status": workflow.get_state("batch_status", "not_started")
+        },
+        "workflow_metadata": {
+            "has_errors": workflow.get_state("has_errors", False),
+            "state_keys": list(workflow.get_all_state().keys()),
+            "state_size": len(workflow.get_all_state())
+        }
+    }
+    
+    # Calculate summary metrics
+    if workflow.has_state("batch_results"):
+        batch_results = workflow.get_state("batch_results")
+        report["batch_processing"]["average_records_per_batch"] = (
+            sum(r["records_processed"] for r in batch_results) / len(batch_results)
+            if batch_results else 0
+        )
+    
+    # Set final state
+    workflow.set_state("final_report_generated", True)
+    workflow.set_state("workflow_complete", True)
+    
+    return report
+
+def check_state_conditions() -> str:
+    """Check various state conditions for decision making"""
+    quality_level = workflow.get_state("quality_level", "unknown")
+    cleaning_attempts = workflow.get_state("cleaning_attempts", 0)
+    has_errors = workflow.get_state("has_errors", False)
+    
+    if quality_level == "poor" and cleaning_attempts == 0:
+        return "needs_cleaning"
+    elif quality_level == "moderate" and not has_errors:
+        return "can_proceed"
+    elif quality_level == "good":
+        return "ready_for_processing"
+    elif cleaning_attempts >= 3:
+        return "max_cleaning_reached"
+    else:
+        return "needs_analysis"
+
+# Create agents
+data_analyst = Agent(
+    name="DataAnalyst",
+    role="Data quality analysis",
+    goal="Analyze data quality and set appropriate state",
+    backstory="Expert in data quality assessment",
+    tools=[analyze_data_quality, check_state_conditions],
+    llm="gpt-4o-mini"
+)
+
+data_engineer = Agent(
+    name="DataEngineer", 
+    role="Data cleaning and processing",
+    goal="Clean data based on state and process in batches",
+    backstory="Specialist in data transformation and batch processing",
+    tools=[clean_data_based_on_state, process_batch_with_state],
+    llm="gpt-4o-mini"
+)
+
+report_generator = Agent(
+    name="ReportGenerator",
+    role="Report generation",
+    goal="Generate comprehensive reports from workflow state",
+    backstory="Expert in creating detailed analytical reports",
+    tools=[generate_report_from_state],
+    llm="gpt-4o-mini"
+)
+
+# Create tasks with state-based conditions
+analyze_task = Task(
+    name="analyze_quality",
+    description="Analyze the data quality and set initial state values",
+    expected_output="Data quality analysis with recommendations",
+    agent=data_analyst,
+    tools=[analyze_data_quality]
+)
+
+decision_task = Task(
+    name="quality_decision",
+    description="Check data quality state and decide next action using check_state_conditions tool",
+    expected_output="Decision on whether to clean data or proceed",
+    agent=data_analyst,
+    tools=[check_state_conditions],
+    task_type="decision",
+    condition={
+        "needs_cleaning": ["clean_data"],
+        "can_proceed": ["process_batches"],
+        "ready_for_processing": ["process_batches"],
+        "max_cleaning_reached": ["process_batches"],
+        "needs_analysis": ["analyze_quality"]
+    },
+    context=[analyze_task]
+)
+
+clean_task = Task(
+    name="clean_data",
+    description="Clean the data to improve quality score. Check if more cleaning is needed.",
+    expected_output="Cleaning results with status",
+    agent=data_engineer,
+    tools=[clean_data_based_on_state],
+    task_type="decision",
+    condition={
+        "needs_more_cleaning": ["clean_data"],
+        "cleaning_complete": ["process_batches"]
+    }
+)
+
+process_task = Task(
+    name="process_batches",
+    description="Process data in batches. Continue until all batches are complete.",
+    expected_output="Batch processing results",
+    agent=data_engineer,
+    tools=[process_batch_with_state],
+    task_type="loop",
+    condition={
+        "more_batches": ["process_batches"],
+        "all_batches_complete": ["generate_report"]
+    }
+)
+
+report_task = Task(
+    name="generate_report",
+    description="Generate final report from all accumulated state data",
+    expected_output="Comprehensive workflow report",
+    agent=report_generator,
+    tools=[generate_report_from_state]
+)
+
+# Create workflow
+workflow = PraisonAIAgents(
+    agents=[data_analyst, data_engineer, report_generator],
+    tasks=[analyze_task, decision_task, clean_task, process_task, report_task],
+    verbose=1,
+    process="workflow"
+)
+
+# Demonstrate state before workflow
+print("\n=== State-Based Workflow Control Demo ===")
+print("\n1. Initial state (empty):", workflow.get_all_state())
+
+# Run the workflow
+print("\n2. Running workflow with state-based decisions...")
+result = workflow.start()
+
+# Show final state
+print("\n3. Final workflow state:")
+final_state = workflow.get_all_state()
+print(f"   Total state entries: {len(final_state)}")
+print(f"   Quality level: {final_state.get('quality_level')}")
+print(f"   Cleaning attempts: {final_state.get('cleaning_attempts', 0)}")
+print(f"   Batches processed: {final_state.get('batch_current', 0)}/{final_state.get('batch_total', 0)}")
+print(f"   Total records: {final_state.get('total_records', 0)}")
+print(f"   Workflow complete: {final_state.get('workflow_complete', False)}")
+
+# Display task execution path
+print("\n4. Task Execution Path:")
+for task_name, task in workflow.tasks.items():
+    if hasattr(task, 'status'):
+        print(f"   {task_name}: {task.status}")
+
+print("\n=== Demo Complete ===")

src/praisonai-agents/tests/state_management_example.py

@@ -0,0 +1,259 @@
+"""
+State Management Example for PraisonAI Agents
+============================================
+
+This example demonstrates various state management features:
+1. Workflow-level state management
+2. Session-level state persistence
+3. State sharing between agents
+4. State-based decision making
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents, Session
+from typing import Dict, Any
+import json
+import time
+
+# Create a session for persistent state
+session = Session(session_id="state_demo_session", user_id="demo_user")
+
+# Tool functions that interact with state
+def initialize_project_state() -> Dict[str, Any]:
+    """Initialize project state with default values"""
+    # Access workflow state from global workflow variable
+    workflow.set_state("project_name", "AI Assistant Project")
+    workflow.set_state("stage", "planning")
+    workflow.set_state("features", [])
+    workflow.set_state("completed_features", [])
+    workflow.set_state("budget", 100000)
+    workflow.set_state("spent", 0)
+    
+    # Also save to session for persistence
+    session.set_state("last_project", "AI Assistant Project")
+    session.set_state("total_projects", session.get_state("total_projects", 0) + 1)
+    
+    return {
+        "status": "initialized",
+        "project_name": workflow.get_state("project_name"),
+        "budget": workflow.get_state("budget"),
+        "session_projects": session.get_state("total_projects")
+    }
+
+def add_feature_to_project(feature_name: str, estimated_cost: int) -> Dict[str, Any]:
+    """Add a feature to the project and update state"""
+    features = workflow.get_state("features", [])
+    budget = workflow.get_state("budget", 0)
+    spent = workflow.get_state("spent", 0)
+    
+    if spent + estimated_cost > budget:
+        return {
+            "status": "rejected",
+            "reason": "over_budget",
+            "available_budget": budget - spent
+        }
+    
+    feature = {
+        "name": feature_name,
+        "cost": estimated_cost,
+        "status": "planned"
+    }
+    
+    features.append(feature)
+    workflow.set_state("features", features)
+    workflow.set_state("spent", spent + estimated_cost)
+    
+    return {
+        "status": "added",
+        "feature": feature,
+        "total_features": len(features),
+        "remaining_budget": budget - (spent + estimated_cost)
+    }
+
+def implement_next_feature() -> Dict[str, Any]:
+    """Implement the next planned feature"""
+    features = workflow.get_state("features", [])
+    completed = workflow.get_state("completed_features", [])
+    
+    # Find next planned feature
+    next_feature = None
+    for i, feature in enumerate(features):
+        if feature["status"] == "planned":
+            next_feature = feature
+            next_feature["status"] = "completed"
+            features[i] = next_feature
+            break
+    
+    if not next_feature:
+        workflow.set_state("stage", "completed")
+        return {
+            "status": "no_more_features",
+            "completed_count": len(completed),
+            "stage": "completed"
+        }
+    
+    completed.append(next_feature["name"])
+    workflow.set_state("features", features)
+    workflow.set_state("completed_features", completed)
+    workflow.set_state("stage", "implementing")
+    
+    # Update session state
+    session.set_state("last_implemented_feature", next_feature["name"])
+    
+    return {
+        "status": "implemented",
+        "feature": next_feature,
+        "completed_count": len(completed),
+        "remaining_count": sum(1 for f in features if f["status"] == "planned")
+    }
+
+def check_project_status() -> Dict[str, Any]:
+    """Check the current project status from state"""
+    return {
+        "project_name": workflow.get_state("project_name"),
+        "stage": workflow.get_state("stage"),
+        "total_features": len(workflow.get_state("features", [])),
+        "completed_features": len(workflow.get_state("completed_features", [])),
+        "budget": workflow.get_state("budget"),
+        "spent": workflow.get_state("spent"),
+        "remaining": workflow.get_state("budget", 0) - workflow.get_state("spent", 0),
+        "has_more_features": workflow.has_state("features") and any(
+            f["status"] == "planned" for f in workflow.get_state("features", [])
+        ),
+        "all_state": workflow.get_all_state()
+    }
+
+def retrieve_session_history() -> Dict[str, Any]:
+    """Retrieve historical data from session state"""
+    session_state = session.restore_state()
+    return {
+        "total_projects": session.get_state("total_projects", 0),
+        "last_project": session.get_state("last_project"),
+        "last_implemented_feature": session.get_state("last_implemented_feature"),
+        "session_id": session.session_id,
+        "full_session_state": session_state
+    }
+
+# Create agents with state-aware tools
+project_manager = Agent(
+    name="ProjectManager",
+    role="Project planning and management",
+    goal="Initialize and manage project state effectively",
+    backstory="Experienced project manager who tracks all project details",
+    tools=[initialize_project_state, add_feature_to_project, check_project_status],
+    llm="gpt-4o-mini"
+)
+
+developer = Agent(
+    name="Developer",
+    role="Feature implementation",
+    goal="Implement features based on project state",
+    backstory="Senior developer who implements features systematically",
+    tools=[implement_next_feature, check_project_status],
+    llm="gpt-4o-mini"
+)
+
+analyst = Agent(
+    name="Analyst",
+    role="Project analysis and reporting",
+    goal="Analyze project state and provide insights",
+    backstory="Data analyst who provides comprehensive project reports",
+    tools=[check_project_status, retrieve_session_history],
+    llm="gpt-4o-mini"
+)
+
+# Create tasks that utilize state
+init_task = Task(
+    name="initialize_project",
+    description="Initialize the project state with default values",
+    expected_output="Project initialization status with budget and name",
+    agent=project_manager,
+    tools=[initialize_project_state]
+)
+
+plan_features_task = Task(
+    name="plan_features",
+    description="""Add the following features to the project:
+    1. User Authentication (cost: 15000)
+    2. Data Analytics Dashboard (cost: 25000)
+    3. API Integration (cost: 20000)
+    4. Mobile App Support (cost: 30000)
+    5. Advanced Reporting (cost: 20000)
+    
+    Use the add_feature_to_project tool for each feature.""",
+    expected_output="List of features added with budget status",
+    agent=project_manager,
+    tools=[add_feature_to_project],
+    context=[init_task]
+)
+
+implement_features_task = Task(
+    name="implement_features",
+    description="""Implement all planned features one by one.
+    Use implement_next_feature tool repeatedly until all features are completed.
+    Check project status after each implementation.""",
+    expected_output="Implementation progress and final status",
+    agent=developer,
+    tools=[implement_next_feature, check_project_status],
+    context=[plan_features_task]
+)
+
+analyze_project_task = Task(
+    name="analyze_project",
+    description="""Provide a comprehensive analysis of the project including:
+    1. Current project state and completion status
+    2. Budget utilization
+    3. Historical session data
+    4. Summary of all state information""",
+    expected_output="Detailed project analysis report",
+    agent=analyst,
+    tools=[check_project_status, retrieve_session_history],
+    context=[implement_features_task]
+)
+
+# Create workflow with state management
+workflow = PraisonAIAgents(
+    agents=[project_manager, developer, analyst],
+    tasks=[init_task, plan_features_task, implement_features_task, analyze_project_task],
+    verbose=1,
+    process="sequential"
+)
+
+# Demonstrate state operations before starting
+print("\n=== State Management Demo ===")
+print("\n1. Initial State Check:")
+print(f"   Has 'project_name' state: {workflow.has_state('project_name')}")
+print(f"   All state: {workflow.get_all_state()}")
+
+# Run the workflow
+print("\n2. Running Workflow...")
+result = workflow.start()
+
+# Demonstrate state after workflow
+print("\n3. Final State Check:")
+print(f"   Project Name: {workflow.get_state('project_name')}")
+print(f"   Stage: {workflow.get_state('stage')}")
+print(f"   Features: {len(workflow.get_state('features', []))}")
+print(f"   Completed: {workflow.get_state('completed_features', [])}")
+print(f"   Budget Spent: ${workflow.get_state('spent')}/{workflow.get_state('budget')}")
+
+# Test state persistence
+print("\n4. Session State Persistence:")
+print(f"   Total Projects (this session): {session.get_state('total_projects')}")
+print(f"   Last Project: {session.get_state('last_project')}")
+
+# Save session state
+session.save_state({"workflow_completed": True, "timestamp": time.time()})
+
+# Demonstrate state update and deletion
+print("\n5. State Manipulation:")
+workflow.update_state({"additional_notes": "Project completed successfully"})
+print(f"   After update: {workflow.get_state('additional_notes')}")
+
+workflow.delete_state("additional_notes")
+print(f"   After delete, has 'additional_notes': {workflow.has_state('additional_notes')}")
+
+# Clear all workflow state (optional)
+# workflow.clear_state()
+# print(f"   After clear: {workflow.get_all_state()}")
+
+print("\n=== State Management Demo Complete ===")

src/praisonai-agents/tests/state_with_memory_example.py

@@ -0,0 +1,397 @@
+"""
+State with Memory Integration Example
+====================================
+
+This example demonstrates:
+1. Using shared memory for state persistence
+2. State sharing between agents via memory
+3. Combining workflow state with memory storage
+4. Historical state tracking
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+from praisonaiagents.memory import Memory
+from typing import Dict, Any, List
+import json
+import time
+from datetime import datetime
+
+# Initialize shared memory
+memory_config = {
+    "config": {
+        "collection_name": "state_memory_demo",
+        "path": "./state_memory_db"
+    }
+}
+
+shared_memory = Memory(**memory_config)
+
+# Tool functions that use both state and memory
+def initialize_conversation_state(user_name: str, topic: str) -> Dict[str, Any]:
+    """Initialize conversation state and store in memory"""
+    # Set workflow state
+    workflow.set_state("user_name", user_name)
+    workflow.set_state("topic", topic)
+    workflow.set_state("start_time", time.time())
+    workflow.set_state("turn_count", 0)
+    workflow.set_state("conversation_history", [])
+    
+    # Store in memory for persistence
+    context = f"Starting conversation with {user_name} about {topic}"
+    shared_memory.add(
+        text=context,
+        metadata={
+            "type": "conversation_start",
+            "user": user_name,
+            "topic": topic,
+            "timestamp": datetime.now().isoformat()
+        }
+    )
+    
+    return {
+        "status": "initialized",
+        "user": user_name,
+        "topic": topic,
+        "memory_stored": True
+    }
+
+def add_conversation_turn(speaker: str, message: str) -> Dict[str, Any]:
+    """Add a conversation turn to state and memory"""
+    # Get current state
+    history = workflow.get_state("conversation_history", [])
+    turn_count = workflow.get_state("turn_count", 0)
+    
+    # Create turn entry
+    turn = {
+        "turn": turn_count + 1,
+        "speaker": speaker,
+        "message": message,
+        "timestamp": time.time()
+    }
+    
+    # Update state
+    history.append(turn)
+    workflow.set_state("conversation_history", history)
+    workflow.set_state("turn_count", turn_count + 1)
+    workflow.set_state(f"last_{speaker}_message", message)
+    
+    # Store in memory
+    shared_memory.add(
+        text=f"{speaker}: {message}",
+        metadata={
+            "type": "conversation_turn",
+            "speaker": speaker,
+            "turn": turn_count + 1,
+            "topic": workflow.get_state("topic"),
+            "user": workflow.get_state("user_name")
+        }
+    )
+    
+    return {
+        "turn_added": turn,
+        "total_turns": turn_count + 1,
+        "history_length": len(history)
+    }
+
+def search_conversation_memory(query: str, speaker: str = None) -> Dict[str, Any]:
+    """Search through conversation memory"""
+    # Build metadata filter
+    metadata_filter = {"type": "conversation_turn"}
+    if speaker:
+        metadata_filter["speaker"] = speaker
+    
+    # Search memory
+    results = shared_memory.search(
+        query=query,
+        n=5,
+        metadata_filter=metadata_filter
+    )
+    
+    # Update state with search results
+    workflow.set_state("last_search_query", query)
+    workflow.set_state("last_search_results", len(results))
+    
+    return {
+        "query": query,
+        "results_count": len(results),
+        "results": [
+            {
+                "text": r["text"],
+                "speaker": r["metadata"].get("speaker"),
+                "turn": r["metadata"].get("turn"),
+                "relevance": r.get("score", 0)
+            }
+            for r in results
+        ]
+    }
+
+def analyze_conversation_patterns() -> Dict[str, Any]:
+    """Analyze patterns in conversation using state and memory"""
+    # Get state data
+    history = workflow.get_state("conversation_history", [])
+    user_name = workflow.get_state("user_name", "Unknown")
+    topic = workflow.get_state("topic", "Unknown")
+    
+    # Calculate metrics from state
+    total_turns = len(history)
+    speakers = {}
+    
+    for turn in history:
+        speaker = turn["speaker"]
+        speakers[speaker] = speakers.get(speaker, 0) + 1
+    
+    # Search memory for related conversations
+    related_convos = shared_memory.search(
+        query=topic,
+        n=10,
+        metadata_filter={"type": "conversation_turn"}
+    )
+    
+    # Analyze patterns
+    patterns = {
+        "current_conversation": {
+            "user": user_name,
+            "topic": topic,
+            "total_turns": total_turns,
+            "speaker_distribution": speakers,
+            "duration_seconds": time.time() - workflow.get_state("start_time", time.time())
+        },
+        "memory_insights": {
+            "related_conversations": len(related_convos),
+            "common_speakers": list(set(r["metadata"].get("speaker") for r in related_convos)),
+            "topics_discussed": list(set(r["metadata"].get("topic") for r in related_convos))
+        }
+    }
+    
+    # Store analysis in state
+    workflow.set_state("conversation_analysis", patterns)
+    
+    return patterns
+
+def retrieve_user_history(user_name: str) -> Dict[str, Any]:
+    """Retrieve all historical data for a user from memory"""
+    # Search memory for user's conversations
+    user_history = shared_memory.search(
+        query=user_name,
+        n=20,
+        metadata_filter={"user": user_name}
+    )
+    
+    # Organize by conversation topics
+    topics = {}
+    for item in user_history:
+        topic = item["metadata"].get("topic", "Unknown")
+        if topic not in topics:
+            topics[topic] = []
+        topics[topic].append({
+            "text": item["text"],
+            "type": item["metadata"].get("type"),
+            "timestamp": item["metadata"].get("timestamp")
+        })
+    
+    # Update state with user history
+    workflow.set_state("user_history_retrieved", True)
+    workflow.set_state("user_topics", list(topics.keys()))
+    
+    return {
+        "user": user_name,
+        "total_interactions": len(user_history),
+        "topics_discussed": list(topics.keys()),
+        "conversation_count": len(topics),
+        "history_by_topic": topics
+    }
+
+def summarize_and_save_state() -> Dict[str, Any]:
+    """Create a summary of the conversation and save final state"""
+    # Get all conversation data
+    history = workflow.get_state("conversation_history", [])
+    analysis = workflow.get_state("conversation_analysis", {})
+    user_name = workflow.get_state("user_name")
+    topic = workflow.get_state("topic")
+    
+    # Create summary
+    summary = {
+        "conversation_id": f"{user_name}_{topic}_{int(time.time())}",
+        "user": user_name,
+        "topic": topic,
+        "total_turns": len(history),
+        "duration": time.time() - workflow.get_state("start_time", 0),
+        "participants": list(set(turn["speaker"] for turn in history)),
+        "key_points": [turn["message"][:50] + "..." for turn in history[-3:]],  # Last 3 messages
+        "analysis": analysis
+    }
+    
+    # Save summary to memory
+    shared_memory.add(
+        text=json.dumps(summary, indent=2),
+        metadata={
+            "type": "conversation_summary",
+            "user": user_name,
+            "topic": topic,
+            "timestamp": datetime.now().isoformat(),
+            "conversation_id": summary["conversation_id"]
+        }
+    )
+    
+    # Clear workflow state but keep summary
+    workflow.set_state("final_summary", summary)
+    workflow.set_state("state_saved_to_memory", True)
+    
+    return summary
+
+# Create agents with memory-aware tools
+conversation_manager = Agent(
+    name="ConversationManager",
+    role="Manage conversation state and memory",
+    goal="Initialize and track conversation state effectively",
+    backstory="Expert in conversation management and state tracking",
+    tools=[initialize_conversation_state, add_conversation_turn, summarize_and_save_state],
+    memory=shared_memory,
+    llm="gpt-4o-mini"
+)
+
+memory_analyst = Agent(
+    name="MemoryAnalyst",
+    role="Analyze conversation patterns from memory",
+    goal="Extract insights from conversation history",
+    backstory="Specialist in pattern recognition and memory analysis",
+    tools=[search_conversation_memory, analyze_conversation_patterns, retrieve_user_history],
+    memory=shared_memory,
+    llm="gpt-4o-mini"
+)
+
+# Create tasks
+init_conversation_task = Task(
+    name="init_conversation",
+    description="Initialize a conversation with user 'Alice' about 'AI and Future of Work'",
+    expected_output="Initialization status",
+    agent=conversation_manager,
+    tools=[initialize_conversation_state]
+)
+
+simulate_conversation_task = Task(
+    name="simulate_conversation",
+    description="""Simulate a conversation by adding these turns:
+    1. Alice: "What are the main impacts of AI on employment?"
+    2. Assistant: "AI is transforming employment through automation and augmentation."
+    3. Alice: "Which industries are most affected?"
+    4. Assistant: "Manufacturing, customer service, and data analysis see significant changes."
+    5. Alice: "How can workers prepare for these changes?"
+    
+    Use add_conversation_turn for each message.""",
+    expected_output="Conversation simulation results",
+    agent=conversation_manager,
+    tools=[add_conversation_turn],
+    context=[init_conversation_task]
+)
+
+search_memory_task = Task(
+    name="search_memory",
+    description="""Search conversation memory for:
+    1. Messages about 'automation'
+    2. All messages from 'Alice'
+    3. Messages about 'employment'""",
+    expected_output="Search results from memory",
+    agent=memory_analyst,
+    tools=[search_conversation_memory],
+    context=[simulate_conversation_task]
+)
+
+analyze_patterns_task = Task(
+    name="analyze_patterns",
+    description="Analyze conversation patterns and extract insights",
+    expected_output="Pattern analysis results",
+    agent=memory_analyst,
+    tools=[analyze_conversation_patterns],
+    context=[search_memory_task]
+)
+
+retrieve_history_task = Task(
+    name="retrieve_history",
+    description="Retrieve all historical data for user 'Alice'",
+    expected_output="User history summary",
+    agent=memory_analyst,
+    tools=[retrieve_user_history],
+    context=[analyze_patterns_task]
+)
+
+save_state_task = Task(
+    name="save_state",
+    description="Create final summary and save conversation state to memory",
+    expected_output="Final conversation summary",
+    agent=conversation_manager,
+    tools=[summarize_and_save_state],
+    context=[retrieve_history_task]
+)
+
+# Create workflow with shared memory
+workflow = PraisonAIAgents(
+    agents=[conversation_manager, memory_analyst],
+    tasks=[
+        init_conversation_task,
+        simulate_conversation_task,
+        search_memory_task,
+        analyze_patterns_task,
+        retrieve_history_task,
+        save_state_task
+    ],
+    memory=memory_config,  # This creates shared memory for all agents
+    verbose=1,
+    process="sequential"
+)
+
+# Run workflow
+print("\n=== State with Memory Integration Demo ===")
+print("\n1. Starting workflow with memory-based state management...")
+result = workflow.start()
+
+# Display results
+print("\n2. Final State Summary:")
+final_summary = workflow.get_state("final_summary", {})
+if final_summary:
+    print(f"   Conversation ID: {final_summary.get('conversation_id')}")
+    print(f"   Total Turns: {final_summary.get('total_turns')}")
+    print(f"   Duration: {final_summary.get('duration', 0):.2f} seconds")
+    print(f"   Participants: {final_summary.get('participants')}")
+
+print("\n3. Memory Storage Status:")
+print(f"   State saved to memory: {workflow.get_state('state_saved_to_memory', False)}")
+print(f"   User history retrieved: {workflow.get_state('user_history_retrieved', False)}")
+print(f"   Topics in memory: {workflow.get_state('user_topics', [])}")
+
+# Test memory persistence by creating new workflow instance
+print("\n4. Testing Memory Persistence:")
+print("   Creating new workflow instance to test memory retrieval...")
+
+# Create a simple test agent to verify memory persistence
+test_agent = Agent(
+    name="MemoryTester",
+    role="Test memory persistence",
+    goal="Verify stored conversation data",
+    backstory="Memory system tester",
+    tools=[search_conversation_memory],
+    memory=shared_memory,
+    llm="gpt-4o-mini"
+)
+
+test_task = Task(
+    name="test_memory",
+    description="Search memory for 'Alice' to verify persistence",
+    expected_output="Memory search results",
+    agent=test_agent,
+    tools=[search_conversation_memory]
+)
+
+test_workflow = PraisonAIAgents(
+    agents=[test_agent],
+    tasks=[test_task],
+    memory=memory_config,
+    verbose=0
+)
+
+# This will use the same memory collection and find previously stored data
+test_result = test_workflow.start()
+
+print("\n=== Demo Complete ===")
+print("\nNote: The conversation data has been persisted in memory and can be")
+print("retrieved in future sessions using the same memory configuration.")

src/praisonai-agents/tests/telemetry_example.py

@@ -0,0 +1,258 @@
+"""
+Example demonstrating telemetry usage in PraisonAI Agents.
+
+This example shows how to:
+1. Enable telemetry with OpenTelemetry backend
+2. Use automatic instrumentation
+3. Use manual instrumentation
+4. Export telemetry data
+"""
+
+import os
+from praisonaiagents import (
+    Agent, Task, PraisonAIAgents,
+    enable_telemetry, disable_telemetry, get_telemetry_collector
+)
+from praisonaiagents.tools import DuckDuckGoSearchTool
+
+# Set current path to package root directory
+import os
+import sys
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+def basic_telemetry_example():
+    """Basic example with automatic telemetry."""
+    print("\n=== Basic Telemetry Example ===\n")
+    
+    # Enable telemetry - it will automatically instrument all agents and tasks
+    telemetry = enable_telemetry(
+        backend="opentelemetry",
+        service_name="praisonai-demo",
+        exporter="console"  # Use console exporter for demo
+    )
+    
+    if not telemetry:
+        print("Telemetry dependencies not installed. Install with:")
+        print("pip install praisonaiagents[telemetry]")
+        return
+    
+    # Create agents - telemetry will be automatically added
+    researcher = Agent(
+        name="Researcher",
+        role="Information gatherer",
+        goal="Find accurate information about topics",
+        backstory="You are an expert researcher with attention to detail",
+        tools=[DuckDuckGoSearchTool()],
+        llm="gpt-4o-mini"
+    )
+    
+    writer = Agent(
+        name="Writer",
+        role="Content creator",
+        goal="Create engaging content based on research",
+        backstory="You are a skilled writer who creates clear, engaging content",
+        llm="gpt-4o-mini"
+    )
+    
+    # Create tasks
+    research_task = Task(
+        name="research_task",
+        description="Research the latest developments in quantum computing",
+        expected_output="A summary of recent quantum computing breakthroughs",
+        agent=researcher
+    )
+    
+    writing_task = Task(
+        name="writing_task",
+        description="Write a blog post about quantum computing developments",
+        expected_output="A 300-word blog post suitable for a general audience",
+        agent=writer,
+        context=[research_task]  # Depends on research task
+    )
+    
+    # Create workflow
+    workflow = PraisonAIAgents(
+        agents=[researcher, writer],
+        tasks=[research_task, writing_task],
+        process="sequential",
+        verbose=True
+    )
+    
+    # Run workflow - all telemetry will be collected automatically
+    print("Running workflow with telemetry enabled...\n")
+    result = workflow.start()
+    
+    # Get telemetry metrics
+    metrics = telemetry.get_metrics()
+    print("\n=== Telemetry Metrics ===")
+    print(f"Agent executions: {metrics['agent_executions']}")
+    print(f"Task completions: {metrics['task_completions']}")
+    print(f"Tool calls: {metrics['tool_calls']}")
+    print(f"LLM calls: {metrics['llm_calls']}")
+    print(f"Total tokens: {metrics['total_tokens']}")
+    print(f"Errors: {metrics['errors']}")
+    
+    # Disable telemetry
+    disable_telemetry()
+    
+    return result
+
+
+def manual_telemetry_example():
+    """Example with manual telemetry instrumentation."""
+    print("\n=== Manual Telemetry Example ===\n")
+    
+    # Enable telemetry
+    telemetry = enable_telemetry(backend="custom")  # Use logging backend
+    
+    if not telemetry:
+        return
+    
+    # Create agent without automatic instrumentation
+    agent = Agent(
+        name="Assistant",
+        role="General assistant",
+        goal="Help with various tasks",
+        backstory="You are a helpful AI assistant",
+        llm="gpt-4o-mini"
+    )
+    
+    # Manual telemetry - trace custom operations
+    with telemetry.trace_agent_execution("Assistant", custom_field="demo"):
+        response = agent.chat("What is the capital of France?")
+        print(f"Response: {response}")
+    
+    # Use telemetry decorator for functions
+    @telemetry.trace(span_type="custom_operation")
+    def process_data(data):
+        """Process some data with telemetry."""
+        # Simulate processing
+        import time
+        time.sleep(0.1)
+        
+        # Record custom metrics
+        telemetry.record_metric("data.processed", len(data), {"type": "text"})
+        
+        return data.upper()
+    
+    # Call traced function
+    result = process_data("hello world")
+    print(f"Processed: {result}")
+    
+    # Manual event recording
+    telemetry._backend.record_event("custom_event", {
+        "user_action": "manual_example",
+        "success": True
+    })
+    
+    disable_telemetry()
+
+
+def advanced_telemetry_example():
+    """Advanced example with custom telemetry backend and OTLP export."""
+    print("\n=== Advanced Telemetry Example ===\n")
+    
+    # For OTLP export, you would typically have an OTLP collector running
+    # For this example, we'll use console export
+    
+    # Enable telemetry with OTLP configuration
+    telemetry = enable_telemetry(
+        backend="opentelemetry",
+        service_name="praisonai-production",
+        service_version="1.0.0",
+        exporter="otlp",  # Would export to OTLP collector
+        otlp_endpoint="localhost:4317",  # OTLP collector endpoint
+        metric_export_interval=10000  # Export metrics every 10 seconds
+    )
+    
+    if not telemetry:
+        print("Telemetry not available. Using fallback.")
+        # Even without telemetry, the code still works
+        agent = Agent(
+            name="Analyst",
+            role="Data analyst",
+            goal="Analyze data and provide insights",
+            backstory="You are an experienced data analyst",
+            llm="gpt-4o-mini"
+        )
+        
+        result = agent.chat("Analyze the trend: [10, 15, 13, 18, 22, 20, 25]")
+        print(f"Analysis: {result}")
+        return
+    
+    # Create instrumented agent
+    agent = Agent(
+        name="Analyst",
+        role="Data analyst", 
+        goal="Analyze data and provide insights",
+        backstory="You are an experienced data analyst",
+        llm="gpt-4o-mini"
+    )
+    
+    # Use context manager for grouped operations
+    with telemetry.trace("analysis_workflow", workflow_type="data_analysis"):
+        # Multiple operations within the same trace context
+        response1 = agent.chat("What is the mean of: [10, 15, 13, 18, 22, 20, 25]")
+        response2 = agent.chat("What is the trend in this data?")
+        response3 = agent.chat("Predict the next 3 values")
+        
+        # Record custom metrics
+        telemetry.record_metric("analysis.steps", 3)
+        telemetry.record_cost(0.001, model="gpt-4o-mini")  # Track costs
+    
+    print("\nAnalysis complete. Telemetry data exported to OTLP collector.")
+    
+    disable_telemetry()
+
+
+def telemetry_with_errors_example():
+    """Example showing how telemetry handles errors."""
+    print("\n=== Telemetry with Error Handling ===\n")
+    
+    telemetry = enable_telemetry()
+    
+    if not telemetry:
+        return
+    
+    agent = Agent(
+        name="ErrorProneAgent",
+        role="Test agent",
+        goal="Test error handling",
+        backstory="An agent for testing",
+        llm="gpt-4o-mini"
+    )
+    
+    # This will be traced and errors will be recorded
+    try:
+        with telemetry.trace_agent_execution("ErrorProneAgent"):
+            # Simulate an error by using an invalid tool
+            agent.execute_tool("non_existent_tool", "test")
+    except Exception as e:
+        print(f"Caught error: {e}")
+        print("Error was recorded in telemetry")
+    
+    # Check error metrics
+    metrics = telemetry.get_metrics()
+    print(f"\nError count in telemetry: {metrics['errors']}")
+    
+    disable_telemetry()
+
+
+if __name__ == "__main__":
+    print("PraisonAI Agents Telemetry Examples")
+    print("===================================")
+    
+    # Run basic example
+    basic_telemetry_example()
+    
+    # Run manual instrumentation example
+    manual_telemetry_example()
+    
+    # Run advanced example (commented out as it requires OTLP collector)
+    # advanced_telemetry_example()
+    
+    # Run error handling example
+    telemetry_with_errors_example()
+    
+    print("\n✅ All telemetry examples completed!")

src/praisonai-agents/tests/test_posthog_fixed.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Test PostHog integration after fix.
+"""
+
+import os
+import time
+
+# Ensure telemetry is enabled
+for var in ['PRAISONAI_TELEMETRY_DISABLED', 'PRAISONAI_DISABLE_TELEMETRY', 'DO_NOT_TRACK']:
+    if var in os.environ:
+        del os.environ[var]
+
+print("=== Testing PostHog Fix ===\n")
+
+# Test PostHog directly first
+print("1. Testing PostHog directly:")
+try:
+    from posthog import Posthog
+    
+    # Create PostHog client
+    ph = Posthog(
+        project_api_key='phc_skZpl3eFLQJ4iYjsERNMbCO6jfeSJi2vyZlPahKgxZ7',
+        host='https://eu.i.posthog.com'
+    )
+    
+    # Send test event
+    ph.capture('test-user', 'direct_test', {'timestamp': time.time()})
+    
+    # Flush and shutdown properly
+    ph.flush()
+    ph.shutdown()
+    
+    print("✓ Direct PostHog test successful\n")
+except Exception as e:
+    print(f"✗ Direct PostHog test failed: {e}\n")
+
+# Test telemetry module
+print("2. Testing telemetry module:")
+from praisonaiagents.telemetry.telemetry import MinimalTelemetry
+
+# Create telemetry instance
+telemetry = MinimalTelemetry(enabled=True)
+
+# Track events
+telemetry.track_agent_execution("TestAgent", success=True)
+telemetry.track_task_completion("TestTask", success=True)
+telemetry.track_tool_usage("TestTool", success=True)
+
+print(f"✓ Events tracked")
+print(f"✓ PostHog client available: {telemetry._posthog is not None}")
+
+# Flush
+print("\n3. Flushing telemetry...")
+telemetry.flush()
+print("✓ Flush completed")
+
+# Shutdown
+print("\n4. Shutting down telemetry...")
+telemetry.shutdown()
+print("✓ Shutdown completed")
+
+print("\n=== Test Complete ===")
+print("\nPostHog should now be receiving data properly!")
+print("The fix adds:")
+print("1. posthog.flush() call in the flush() method")
+print("2. shutdown() method that properly closes the connection")

src/praisonai-agents/uv.lock

@@ -585,19 +585,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cc/9d/37e5da7519de7b0b070a3fedd4230fe76d50d2a21403e0f2153d70ac4163/cryptography-44.0.0-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:62901fb618f74d7d81bf408c8719e9ec14d863086efe4185afd07c352aee1d2c", size = 3128774 },
 ]
 
-[[package]]
-name = "dataclasses-json"
-version = "0.6.7"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "marshmallow" },
-    { name = "typing-inspect" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/64/a4/f71d9cf3a5ac257c993b5ca3f93df5f7fb395c725e7f1e6479d2514173c3/dataclasses_json-0.6.7.tar.gz", hash = "sha256:b6b3e528266ea45b9535223bc53ca645f5208833c29229e847b3f26a1cc55fc0", size = 32227 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/c3/be/d0d44e092656fe7a06b55e6103cbce807cdbdee17884a5367c68c9860853/dataclasses_json-0.6.7-py3-none-any.whl", hash = "sha256:0dbf33f26c8d5305befd61b39d2b3414e8a407bedc2834dea9b8d642666fb40a", size = 28686 },
-]
-
 [[package]]
 name = "defusedxml"
 version = "0.7.1"
@@ -1197,6 +1184,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/91/61/c80ef80ed8a0a21158e289ef70dac01e351d929a1c30cb0f49be60772547/jiter-0.8.2-cp313-cp313t-win_amd64.whl", hash = "sha256:3ac9f578c46f22405ff7f8b1f5848fb753cc4b8377fbec8470a7dc3997ca7566", size = 202374 },
 ]
 
+[[package]]
+name = "json-repair"
+version = "0.39.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/60/6d1599bc01070d9fe3840d245ae80fd24b981c732d962842825ce7a9fde6/json_repair-0.39.1.tar.gz", hash = "sha256:e90a489f247e1a8fc86612a5c719872a3dbf9cbaffd6d55f238ec571a77740fa", size = 30040 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ff/b9/2e445481555422b907dab468b53574bc1e995099ca1a1201d0d876ca05e9/json_repair-0.39.1-py3-none-any.whl", hash = "sha256:3001409a2f319249f13e13d6c622117a5b70ea7e0c6f43864a0233cdffc3a599", size = 20686 },
+]
+
 [[package]]
 name = "jsonpatch"
 version = "1.33"
@@ -1286,29 +1282,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ed/5c/5c0be747261e1f8129b875fa3bfea736bc5fe17652f9d5e15ca118571b6f/langchain-0.3.25-py3-none-any.whl", hash = "sha256:931f7d2d1eaf182f9f41c5e3272859cfe7f94fc1f7cef6b3e5a46024b4884c21", size = 1011008 },
 ]
 
-[[package]]
-name = "langchain-community"
-version = "0.3.24"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "aiohttp" },
-    { name = "dataclasses-json" },
-    { name = "httpx-sse" },
-    { name = "langchain" },
-    { name = "langchain-core" },
-    { name = "langsmith" },
-    { name = "numpy" },
-    { name = "pydantic-settings" },
-    { name = "pyyaml" },
-    { name = "requests" },
-    { name = "sqlalchemy" },
-    { name = "tenacity" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/01/f6/4892d1f1cf6d3e89da6ee6cfb0eb82b908c706c58bde7df28367ee76a93f/langchain_community-0.3.24.tar.gz", hash = "sha256:62d9e8cf9aadf35182ec3925f9ec1c8e5e84fb4f199f67a01aee496d289dc264", size = 33233643 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d5/cb/582f22d74d69f4dbd41e98d361ee36922b79a245a9411383327bd4b63747/langchain_community-0.3.24-py3-none-any.whl", hash = "sha256:b6cdb376bf1c2f4d2503aca20f8f35f2d5b3d879c52848277f20ce1950e7afaf", size = 2528335 },
-]
-
 [[package]]
 name = "langchain-core"
 version = "0.3.63"
@@ -1327,6 +1300,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/5c/71/a748861e6a69ab6ef50ab8e65120422a1f36245c71a0dd0f02de49c208e1/langchain_core-0.3.63-py3-none-any.whl", hash = "sha256:f91db8221b1bc6808f70b2e72fded1a94d50ee3f1dff1636fb5a5a514c64b7f5", size = 438468 },
 ]
 
+[[package]]
+name = "langchain-neo4j"
+version = "0.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "langchain" },
+    { name = "langchain-core" },
+    { name = "neo4j" },
+    { name = "neo4j-graphrag" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f9/29/b1c485eaf5adffc59d97d2a47e9b5f3fcfc58becb0e92ded197b98c03138/langchain_neo4j-0.4.0.tar.gz", hash = "sha256:3f059a66411cec1062a2b8c44953a70d0fff9e123e9fb1d6b3f17a0bef6d6114", size = 27061 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/70/7e/d782a77ed3f561a466410aa384f93f59e33930e3d64686d0e1dac4d598c5/langchain_neo4j-0.4.0-py3-none-any.whl", hash = "sha256:2760b5757e7a402884cf3419830217651df97fe4f44b3fec6c96b14b6d7fd18e", size = 31349 },
+]
+
 [[package]]
 name = "langchain-text-splitters"
 version = "0.3.8"
@@ -1359,7 +1347,7 @@ wheels = [
 
 [[package]]
 name = "litellm"
-version = "1.59.1"
+version = "1.72.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -1374,9 +1362,9 @@ dependencies = [
     { name = "tiktoken" },
     { name = "tokenizers" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/92/98/80766e2820e140b4b03a4b3e997d25e522bc2ce1d3c79c98a7b856a84e1f/litellm-1.59.1.tar.gz", hash = "sha256:ca4fd7789cc493daa63fe0dd69e3351237708c48a9305ccbc685a1bcf9eecf98", size = 6374267 }
+sdist = { url = "https://files.pythonhosted.org/packages/d0/a7/67da5f515c3847bd121b5fde54ac48ee3e7d55d75c49d2b51a2f9b20ab7a/litellm-1.72.1.tar.gz", hash = "sha256:d5d822988d62db8fe434aca7584e1cf8f5a03c033e957e3b5c1ca24366840951", size = 8095871 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ff/3c/d2edad7c3cc85d83a4a6929c80ee258ae8875e2366366b9ab93eaf817cb3/litellm-1.59.1-py3-none-any.whl", hash = "sha256:69adf83f6942b9b62d3398cd8c1dc2e53b02e9b97bc5c45c427ed917629048e7", size = 6661803 },
+    { url = "https://files.pythonhosted.org/packages/10/2d/48dee9e0cc782a74d7361a3a1acf70d9ac8a9278a4fa8d2dcf2ac7359ed8/litellm-1.72.1-py3-none-any.whl", hash = "sha256:858b4458f199dd8d3acd46436cf5fb1de19404e5dcf92ff59ec417c224b52481", size = 7994774 },
 ]
 
 [[package]]
@@ -1608,18 +1596,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4f/65/6079a46068dfceaeabb5dcad6d674f5f5c61a6fa5673746f42a9f4c233b3/MarkupSafe-3.0.2-cp313-cp313t-win_amd64.whl", hash = "sha256:e444a31f8db13eb18ada366ab3cf45fd4b31e4db1236a4448f68778c1d1a5a2f", size = 15739 },
 ]
 
-[[package]]
-name = "marshmallow"
-version = "3.26.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "packaging" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/ab/5e/5e53d26b42ab75491cda89b871dab9e97c840bf12c63ec58a1919710cd06/marshmallow-3.26.1.tar.gz", hash = "sha256:e6d8affb6cb61d39d26402096dc0aee12d5a26d490a121f118d2e81dc0719dc6", size = 221825 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/34/75/51952c7b2d3873b44a0028b1bd26a25078c18f92f256608e8d1dc61b39fd/marshmallow-3.26.1-py3-none-any.whl", hash = "sha256:3350409f20a70a7e4e11a27661187b77cdcaeb20abca41c1454fe33636bea09c", size = 50878 },
-]
-
 [[package]]
 name = "mcp"
 version = "1.6.0"
@@ -1650,7 +1626,7 @@ wheels = [
 
 [[package]]
 name = "mem0ai"
-version = "0.1.44"
+version = "0.1.104"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "openai" },
@@ -1660,14 +1636,14 @@ dependencies = [
     { name = "qdrant-client" },
     { name = "sqlalchemy" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/81/e3/46e695de8b7d1dc3f922425b01797c1bd3ee63bde449f22d0f1f10bd9df9/mem0ai-0.1.44.tar.gz", hash = "sha256:93214272915d94f673d370bb8fe7a8bfc21806267e65700b471bec454dcdfa5c", size = 63273 }
+sdist = { url = "https://files.pythonhosted.org/packages/49/d3/d2bbab0e505be71794bb5d53a67c740cf0ed8187d3965d68e317d7f3b208/mem0ai-0.1.104.tar.gz", hash = "sha256:4193bc2a2d5e9e299f3efb5ad80a9f3296e343b20e24cf2326c1ac7efdcfc773", size = 100245 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/8b/37/96382bf64375237d1fed98813d19aba725e8089e1044b7a0873ddf74576b/mem0ai-0.1.44-py3-none-any.whl", hash = "sha256:32260a2cd935035a1b16ce04ad2e4510a5bd97618709466e2d06303e0eb8d9d4", size = 89595 },
+    { url = "https://files.pythonhosted.org/packages/da/03/818b01ad786aeb719ca73408c9ceae9e8193bc1a6aaba86c11c8fdd002b8/mem0ai-0.1.104-py3-none-any.whl", hash = "sha256:7c1f7dd11dcfa8ce827a2911a9dceee98ec8e149a5454e3f8673504832a9186d", size = 156132 },
 ]
 
 [package.optional-dependencies]
 graph = [
-    { name = "langchain-community" },
+    { name = "langchain-neo4j" },
     { name = "neo4j" },
     { name = "rank-bm25" },
 ]
@@ -1744,15 +1720,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9d/d3/f7e6d7d062b8d7072c3989a528d9d47486ee5d5ae75250f6e26b4976d098/mmh3-5.0.1-cp313-cp313-win_arm64.whl", hash = "sha256:122fa9ec148383f9124292962bda745f192b47bfd470b2af5fe7bb3982b17896", size = 36539 },
 ]
 
-[[package]]
-name = "monotonic"
-version = "1.6"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ea/ca/8e91948b782ddfbd194f323e7e7d9ba12e5877addf04fb2bf8fca38e86ac/monotonic-1.6.tar.gz", hash = "sha256:3a55207bcfed53ddd5c5bae174524062935efed17792e9de2ad0205ce9ad63f7", size = 7615 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/67/7e8406a29b6c45be7af7740456f7f37025f0506ae2e05fb9009a53946860/monotonic-1.6-py2.py3-none-any.whl", hash = "sha256:68687e19a14f11f26d140dd5c86f3dba4bf5df58003000ed467e0e2a69bca96c", size = 8154 },
-]
-
 [[package]]
 name = "mpmath"
 version = "1.3.0"
@@ -1860,15 +1827,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/99/b7/b9e70fde2c0f0c9af4cc5277782a89b66d35948ea3369ec9f598358c3ac5/multidict-6.1.0-py3-none-any.whl", hash = "sha256:48e171e52d1c4d33888e529b999e5900356b9ae588c2f09a52dcefb158b27506", size = 10051 },
 ]
 
-[[package]]
-name = "mypy-extensions"
-version = "1.1.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a2/6e/371856a3fb9d31ca8dac321cda606860fa4548858c0cc45d9d1d4ca2628b/mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558", size = 6343 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963 },
-]
-
 [[package]]
 name = "neo4j"
 version = "5.28.1"
@@ -1881,6 +1839,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/6a/57/94225fe5e9dabdc0ff60c88cbfcedf11277f4b34e7ab1373d3e62dbdd207/neo4j-5.28.1-py3-none-any.whl", hash = "sha256:6755ef9e5f4e14b403aef1138fb6315b120631a0075c138b5ddb2a06b87b09fd", size = 312258 },
 ]
 
+[[package]]
+name = "neo4j-graphrag"
+version = "1.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "fsspec" },
+    { name = "json-repair" },
+    { name = "neo4j" },
+    { name = "pydantic" },
+    { name = "pypdf" },
+    { name = "pyyaml" },
+    { name = "types-pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7c/5a/b9309d488b7cfe63326b6502b12dfae16558d64ead4d007b5e6392dd36ac/neo4j_graphrag-1.7.0.tar.gz", hash = "sha256:c6c1f730e680d8af3ff3e1ee6086c465c15dd3245157e6c40606ac3ddae7d4f0", size = 104306 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/2a/b9e29d7a1068302f94dc05d682f1068795947f6c0a99d8274e7f1ca29d23/neo4j_graphrag-1.7.0-py3-none-any.whl", hash = "sha256:29a854f2f1e268f043446cdd387c72ee954b87726329ef6479c59ed7b9cf0751", size = 180365 },
+]
+
 [[package]]
 name = "numpy"
 version = "2.2.1"
@@ -1999,7 +1975,7 @@ wheels = [
 
 [[package]]
 name = "openai"
-version = "1.58.1"
+version = "1.84.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -2011,9 +1987,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/27/3c/b1ecce430ed56fa3ac1b0676966d3250aab9c70a408232b71e419ea62148/openai-1.58.1.tar.gz", hash = "sha256:f5a035fd01e141fc743f4b0e02c41ca49be8fab0866d3b67f5f29b4f4d3c0973", size = 343411 }
+sdist = { url = "https://files.pythonhosted.org/packages/91/a3/128caf24e116f48fad3e4d5122cdf84db06c5127911849d51663c66158c8/openai-1.84.0.tar.gz", hash = "sha256:4caa43bdab262cc75680ce1a2322cfc01626204074f7e8d9939ab372acf61698", size = 467066 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/8e/5a/d22cd07f1a99b9e8b3c92ee0c1959188db4318828a3d88c9daac120bdd69/openai-1.58.1-py3-none-any.whl", hash = "sha256:e2910b1170a6b7f88ef491ac3a42c387f08bd3db533411f7ee391d166571d63c", size = 454279 },
+    { url = "https://files.pythonhosted.org/packages/2a/10/f245db006a860dbc1f2e2c8382e0a1762c7753e7971ba43a1dc3f3ec1404/openai-1.84.0-py3-none-any.whl", hash = "sha256:7ec4436c3c933d68dc0f5a0cef0cb3dbc0864a54d62bddaf2ed5f3d521844711", size = 725512 },
 ]
 
 [[package]]
@@ -2382,27 +2358,28 @@ wheels = [
 
 [[package]]
 name = "posthog"
-version = "3.7.5"
+version = "4.3.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "backoff" },
-    { name = "monotonic" },
+    { name = "distro" },
     { name = "python-dateutil" },
     { name = "requests" },
     { name = "six" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/58/e9/1cd7492bb58dd255129467e1221e2d6f51aa0c6f3c781ac9ac29cc8a2859/posthog-3.7.5.tar.gz", hash = "sha256:8ba40ab623da35db72715fc87fe7dccb7fc272ced92581fe31db2d4dbe7ad761", size = 50269 }
+sdist = { url = "https://files.pythonhosted.org/packages/89/df/cb1b1837a38dfde0eca9b7947037ef0abf9e7732a7c29b8eab6cd4af1a0b/posthog-4.3.2.tar.gz", hash = "sha256:1dc422ccef560ee0949b00e340e8135160fd71a4eb03f06ec382c4672ab0fe4c", size = 85399 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/76/bd/2d550ac79443cdbb6a5a4193c37820f04df0499e1ecbe8e41c5462cf0c2d/posthog-3.7.5-py2.py3-none-any.whl", hash = "sha256:022132c17069dde03c5c5904e2ae1b9bd68d5059cbc5a8dffc5c1537a1b71cb5", size = 54882 },
+    { url = "https://files.pythonhosted.org/packages/2e/e7/2983efeec4356cbae0fcd775effc76576377ae86330d25c150a5bbf8fa4c/posthog-4.3.2-py2.py3-none-any.whl", hash = "sha256:e53d0e20cc8d4ec9cb62f0cbf6034e8f93e7f5b3fc502dfcc8813feb12a06bb7", size = 102036 },
 ]
 
 [[package]]
 name = "praisonaiagents"
-version = "0.0.97"
+version = "0.0.106"
 source = { editable = "." }
 dependencies = [
     { name = "mcp" },
     { name = "openai" },
+    { name = "posthog" },
     { name = "pydantic" },
     { name = "rich" },
 ]
@@ -2416,6 +2393,7 @@ all = [
     { name = "markitdown", extra = ["all"] },
     { name = "mcp" },
     { name = "mem0ai", extra = ["graph"] },
+    { name = "posthog" },
     { name = "pydantic" },
     { name = "uvicorn" },
 ]
@@ -2444,6 +2422,10 @@ mcp = [
 ]
 memory = [
     { name = "chromadb" },
+    { name = "litellm" },
+]
+telemetry = [
+    { name = "posthog" },
 ]
 
 [package.metadata]
@@ -2454,19 +2436,23 @@ requires-dist = [
     { name = "chromadb", marker = "extra == 'memory'", specifier = ">=1.0.0" },
     { name = "fastapi", marker = "extra == 'api'", specifier = ">=0.115.0" },
     { name = "fastapi", marker = "extra == 'mcp'", specifier = ">=0.115.0" },
-    { name = "litellm", marker = "extra == 'llm'", specifier = ">=1.50.0" },
+    { name = "litellm", marker = "extra == 'llm'", specifier = ">=1.72.0" },
+    { name = "litellm", marker = "extra == 'memory'", specifier = ">=1.72.0" },
     { name = "markitdown", extras = ["all"], marker = "extra == 'knowledge'", specifier = ">=0.1.0" },
     { name = "mcp", specifier = ">=1.6.0" },
     { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.6.0" },
     { name = "mem0ai", marker = "extra == 'knowledge'", specifier = ">=0.1.0" },
     { name = "mem0ai", extras = ["graph"], marker = "extra == 'graph'", specifier = ">=0.1.0" },
     { name = "openai" },
+    { name = "posthog", specifier = ">=3.0.0" },
+    { name = "posthog", marker = "extra == 'telemetry'", specifier = ">=3.0.0" },
     { name = "praisonaiagents", extras = ["api"], marker = "extra == 'all'" },
     { name = "praisonaiagents", extras = ["graph"], marker = "extra == 'all'" },
     { name = "praisonaiagents", extras = ["knowledge"], marker = "extra == 'all'" },
     { name = "praisonaiagents", extras = ["llm"], marker = "extra == 'all'" },
     { name = "praisonaiagents", extras = ["mcp"], marker = "extra == 'all'" },
     { name = "praisonaiagents", extras = ["memory"], marker = "extra == 'all'" },
+    { name = "praisonaiagents", extras = ["telemetry"], marker = "extra == 'all'" },
     { name = "pydantic" },
     { name = "pydantic", marker = "extra == 'llm'", specifier = ">=2.4.2" },
     { name = "rich" },
@@ -2725,6 +2711,18 @@ crypto = [
     { name = "cryptography" },
 ]
 
+[[package]]
+name = "pypdf"
+version = "5.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/46/67de1d7a65412aa1c896e6b280829b70b57d203fadae6859b690006b8e0a/pypdf-5.6.0.tar.gz", hash = "sha256:a4b6538b77fc796622000db7127e4e58039ec5e6afd292f8e9bf42e2e985a749", size = 5023749 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/8b/dc3a72d98c22be7a4cbd664ad14c5a3e6295c2dbdf572865ed61e24b5e38/pypdf-5.6.0-py3-none-any.whl", hash = "sha256:ca6bf446bfb0a2d8d71d6d6bb860798d864c36a29b3d9ae8d7fc7958c59f88e7", size = 304208 },
+]
+
 [[package]]
 name = "pypika"
 version = "0.48.9"
@@ -3461,6 +3459,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d0/cc/0a838ba5ca64dc832aa43f727bd586309846b0ffb2ce52422543e6075e8a/typer-0.15.1-py3-none-any.whl", hash = "sha256:7994fb7b8155b64d3402518560648446072864beefd44aa2dc36972a5972e847", size = 44908 },
 ]
 
+[[package]]
+name = "types-pyyaml"
+version = "6.0.12.20250516"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4e/22/59e2aeb48ceeee1f7cd4537db9568df80d62bdb44a7f9e743502ea8aab9c/types_pyyaml-6.0.12.20250516.tar.gz", hash = "sha256:9f21a70216fc0fa1b216a8176db5f9e0af6eb35d2f2932acb87689d03a5bf6ba", size = 17378 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/99/5f/e0af6f7f6a260d9af67e1db4f54d732abad514252a7a378a6c4d17dd1036/types_pyyaml-6.0.12.20250516-py3-none-any.whl", hash = "sha256:8478208feaeb53a34cb5d970c56a7cd76b72659442e733e268a94dc72b2d0530", size = 20312 },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.12.2"
@@ -3470,19 +3477,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/26/9f/ad63fc0248c5379346306f8668cda6e2e2e9c95e01216d2b8ffd9ff037d0/typing_extensions-4.12.2-py3-none-any.whl", hash = "sha256:04e5ca0351e0f3f85c6853954072df659d0d13fac324d0072316b67d7794700d", size = 37438 },
 ]
 
-[[package]]
-name = "typing-inspect"
-version = "0.9.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "mypy-extensions" },
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/dc/74/1789779d91f1961fa9438e9a8710cdae6bd138c80d7303996933d117264a/typing_inspect-0.9.0.tar.gz", hash = "sha256:b23fc42ff6f6ef6954e4852c1fb512cdd18dbea03134f91f856a95ccc9461f78", size = 13825 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/65/f3/107a22063bf27bdccf2024833d3445f4eea42b2e598abfbd46f6a63b6cb0/typing_inspect-0.9.0-py3-none-any.whl", hash = "sha256:9ee6fc59062311ef8547596ab6b955e1b8aa46242d854bfc78f4f6b0eff35f9f", size = 8827 },
-]
-
 [[package]]
 name = "tzdata"
 version = "2024.2"

src/praisonai-ts/examples/README-tool-examples.md

@@ -191,3 +191,17 @@ const agent = new Agent({
 // Start the agent with a prompt that will trigger tool usage
 agent.start("What's the weather in Paris, the time in Tokyo, and what is 25 * 4?");
 ```
+
+## MCP SSE Tool Integration
+
+PraisonAI can use remote tools exposed via the Model Context Protocol over Server-Sent Events.
+
+1. Start the Python SSE server in another terminal:
+```bash
+python ../../praisonai-agents/tests/mcp-sse-direct-server.py --host 127.0.0.1 --port 8080
+```
+
+2. Run the TypeScript example which connects to this server:
+```bash
+npx ts-node examples/tools/mcp-sse.ts
+```

src/praisonai-ts/examples/tools/mcp-sse.ts

@@ -0,0 +1,70 @@
+import { Agent } from '../../src/agent';
+import { MCP } from '../../src/tools/mcpSse';
+
+async function main() {
+  // Connect to the running SSE server
+  const mcp = new MCP('http://127.0.0.1:8080/sse');
+  try {
+    await mcp.initialize();
+  } catch (error) {
+    console.error('Failed to connect to MCP SSE server:', error);
+    console.error('Please ensure the server is running at http://127.0.0.1:8080/sse');
+    process.exit(1);
+  }
+
+  // Create tool functions that call the remote MCP tools
+  const toolFunctions: Record<string, (...args: any[]) => Promise<any>> = {};
+  
+  if (mcp.tools.length === 0) {
+    console.warn('Warning: No MCP tools available. Make sure the MCP server is running.');
+  }
+  
+  for (const tool of mcp) {
+    if (!tool || typeof tool.name !== 'string') {
+      console.warn('Skipping invalid tool:', tool);
+      continue;
+    }
+    
+    const paramNames = Object.keys(tool.schemaProperties || {});
+    toolFunctions[tool.name] = async (...args: any[]) => {
+      const params: Record<string, any> = {};
+      
+      if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null) {
+        // If single object argument, use it directly as params
+        Object.assign(params, args[0]);
+      } else {
+        // Map positional arguments with validation
+        if (args.length > paramNames.length) {
+          console.warn(
+            `Tool ${tool.name}: Too many arguments provided. Expected ${paramNames.length}, got ${args.length}`
+          );
+        }
+        for (let i = 0; i < Math.min(args.length, paramNames.length); i++) {
+          params[paramNames[i]] = args[i];
+        }
+      }
+      return tool.execute(params);
+    };
+  }
+
+  const agent = new Agent({
+    instructions: 'Use the tools to greet people and report the weather.',
+    name: 'MCPAgent',
+    tools: mcp.toOpenAITools(),
+    toolFunctions
+  });
+
+  try {
+    const result = await agent.start('Say hello to John and tell the weather in London.');
+    console.log('\nFinal Result:', result);
+  } catch (error) {
+    console.error('Agent execution failed:', error);
+  } finally {
+    // Clean up MCP connection
+    await mcp.close();
+  }
+}
+
+if (require.main === module) {
+  main();
+}

src/praisonai-ts/package.json

@@ -62,7 +62,8 @@
     "fast-xml-parser": "^4.5.1",
     "node-fetch": "^2.6.9",
     "openai": "^4.81.0",
-    "praisonai": "^1.0.19"
+    "praisonai": "^1.0.19",
+    "@modelcontextprotocol/sdk": "^1.12.1"
   },
   "optionalDependencies": {
     "boxen": "^7.1.1",

src/praisonai-ts/src/tools/index.ts

@@ -20,4 +20,5 @@ export class BaseTool implements Tool {
 }
 
 // Export all tool modules
-export * from './arxivTools';
+export * from './arxivTools';
+export * from './mcpSse';

src/praisonai-ts/src/tools/mcpSse.ts

@@ -0,0 +1,116 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { BaseTool } from './index';
+
+export interface MCPToolInfo {
+  name: string;
+  description?: string;
+  inputSchema?: any;
+}
+
+export class MCPTool extends BaseTool {
+  private client: Client;
+  private inputSchema: any;
+
+  constructor(info: MCPToolInfo, client: Client) {
+    super(info.name, info.description || `Call the ${info.name} tool`);
+    this.client = client;
+    this.inputSchema = info.inputSchema || { type: 'object', properties: {}, required: [] };
+  }
+
+  get schemaProperties(): Record<string, any> | undefined {
+    return this.inputSchema?.properties;
+  }
+
+  async execute(args: any = {}): Promise<any> {
+    try {
+      const result: any = await this.client.callTool({ name: this.name, arguments: args });
+      if (result.structuredContent) {
+        return result.structuredContent;
+      }
+      if (Array.isArray(result.content) && result.content.length > 0) {
+        const item = result.content[0];
+        if (typeof item.text === 'string') return item.text;
+      }
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to execute tool ${this.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  toOpenAITool() {
+    return {
+      type: 'function',
+      function: {
+        name: this.name,
+        description: this.description,
+        parameters: this.inputSchema
+      }
+    };
+  }
+}
+
+export class MCP implements Iterable<MCPTool> {
+  tools: MCPTool[] = [];
+  private client: Client | null = null;
+
+  constructor(private url: string, private debug = false) {
+    if (debug) {
+      console.log(`MCP client initialized for URL: ${url}`);
+    }
+  }
+
+  async initialize(): Promise<void> {
+    if (this.client) {
+      if (this.debug) console.log('MCP client already initialized');
+      return;
+    }
+    
+    try {
+      this.client = new Client({ name: 'praisonai-ts-mcp', version: '1.0.0' });
+      const transport = new SSEClientTransport(new URL(this.url));
+      await this.client.connect(transport);
+      const { tools } = await this.client.listTools();
+      this.tools = tools.map((t: any) => new MCPTool({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema
+      }, this.client as Client));
+      
+      if (this.debug) console.log(`Initialized MCP with ${this.tools.length} tools`);
+    } catch (error) {
+      if (this.client) {
+        await this.client.close().catch(() => {});
+        this.client = null;
+      }
+      throw new Error(`Failed to initialize MCP client: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  [Symbol.iterator](): Iterator<MCPTool> {
+    return this.tools[Symbol.iterator]();
+  }
+
+  toOpenAITools() {
+    return this.tools.map(t => t.toOpenAITool());
+  }
+
+  async close(): Promise<void> {
+    if (this.client) {
+      try {
+        await this.client.close();
+      } catch (error) {
+        if (this.debug) {
+          console.warn('Error closing MCP client:', error);
+        }
+      } finally {
+        this.client = null;
+        this.tools = [];
+      }
+    }
+  }
+
+  get isConnected(): boolean {
+    return this.client !== null;
+  }
+}

src/praisonai/.env.example

@@ -1,6 +1,16 @@
-OPENAI_MODEL_NAME="gpt-4o"
+# OpenAI / compatible API
 OPENAI_API_KEY="Enter your API key"
+OPENAI_MODEL_NAME="gpt-4o"
 OPENAI_API_BASE="https://api.openai.com/v1"
+
+# AG2 framework (uses same OPENAI_* vars above, or override below)
+# MODEL_NAME=gpt-4o-mini
+
+# AWS Bedrock (for ag2_bedrock.yaml example)
+# AWS_DEFAULT_REGION=us-east-1
+# AWS_ACCESS_KEY_ID=your-access-key
+# AWS_SECRET_ACCESS_KEY=your-secret-key
+
+# Chainlit (optional)
 CHAINLIT_USERNAME=admin
-CHAINLIT_USERNAME=admin
-CHAINLIT_AUTH_SECRET="chainlit create-secret to create"
+CHAINLIT_AUTH_SECRET="chainlit create-secret to create"