Release v2.5.1

Author: MervinPraison

README.md

@@ -204,6 +204,12 @@ npm install praisonai
 | ↳ Add Custom Knowledge | [Example](examples/python/concepts/knowledge-agents.py) | [📖](https://docs.praison.ai/features/knowledge) |
 | ↳ RAG Agents | [Example](examples/python/concepts/rag-agents.py) | [📖](https://docs.praison.ai/features/rag) |
 | ↳ Chat with PDF Agents | [Example](examples/python/concepts/chat-with-pdf.py) | [📖](https://docs.praison.ai/features/chat-with-pdf) |
+| ↳ Data Readers (PDF, DOCX, etc.) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-readers-api) |
+| ↳ Vector Store Selection | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-vector-store-api) |
+| ↳ Retrieval Strategies | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-retrieval-api) |
+| ↳ Rerankers | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-reranker-api) |
+| ↳ Index Types (Vector/Keyword/Hybrid) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-index-api) |
+| ↳ Query Engines (Sub-Question, etc.) | [CLI](#knowledge-cli) | [📖](https://docs.praison.ai/api/praisonai/knowledge-query-engine-api) |
 | **🔬 Research & Intelligence** | | |
 | ↳ Deep Research Agents | [Example](examples/python/agents/research-agent.py) | [📖](https://docs.praison.ai/agents/deep-research) |
 | ↳ Query Rewriter Agent | [Example](#5-query-rewriter-agent) | [📖](https://docs.praison.ai/agents/query-rewriter) |
@@ -2641,6 +2647,84 @@ PraisonAI provides zero-dependency persistent memory for agents. For detailed ex
 
 ---
 
+## 📚 Knowledge & Retrieval (RAG)
+
+PraisonAI provides a complete knowledge stack for building RAG applications with multiple vector stores, retrieval strategies, rerankers, and query modes.
+
+### Knowledge CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `praisonai knowledge add <file\|dir\|url>` | Add documents to knowledge base |
+| `praisonai knowledge query <question>` | Query knowledge base with RAG |
+| `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+### Knowledge CLI Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | Vector store backend |
+| `--retrieval` | `basic`, `fusion`, `recursive`, `auto_merge` | Retrieval strategy |
+| `--reranker` | `simple`, `llm`, `cross_encoder`, `cohere` | Reranking method |
+| `--index-type` | `vector`, `keyword`, `hybrid` | Index type |
+| `--query-mode` | `default`, `sub_question`, `summarize` | Query mode |
+
+### Knowledge CLI Examples
+
+```bash
+# Add documents
+praisonai knowledge add ./docs/
+praisonai knowledge add https://example.com/page.html
+praisonai knowledge add "*.pdf"
+
+# Query with advanced options
+praisonai knowledge query "How to authenticate?" --retrieval fusion --reranker llm
+
+# Full advanced query
+praisonai knowledge query "authentication flow" \
+  --vector-store chroma \
+  --retrieval fusion \
+  --reranker llm \
+  --index-type hybrid \
+  --query-mode sub_question
+```
+
+### Knowledge SDK Usage
+
+```python
+from praisonaiagents import Agent, Knowledge
+
+# Simple usage with Agent
+agent = Agent(
+    name="Research Assistant",
+    knowledge=["docs/manual.pdf", "data/faq.txt"],
+    knowledge_config={
+        "vector_store": {"provider": "chroma"}
+    }
+)
+response = agent.chat("How do I authenticate?")
+
+# Direct Knowledge usage
+knowledge = Knowledge()
+knowledge.add("document.pdf")
+results = knowledge.search("authentication", limit=5)
+```
+
+### Knowledge Stack Features Table
+
+| Feature | Description | SDK Docs | CLI Docs |
+|---------|-------------|----------|----------|
+| **Data Readers** | Load PDF, Markdown, Text, HTML, URLs | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Vector Stores** | ChromaDB, Pinecone, Qdrant, Weaviate, In-Memory | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Retrieval Strategies** | Basic, Fusion (RRF), Recursive, Auto-Merge | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Rerankers** | Simple, LLM, Cross-Encoder, Cohere | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Index Types** | Vector, Keyword (BM25), Hybrid | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+| **Query Engines** | Default, Sub-Question, Summarize | [SDK](/docs/sdk/praisonaiagents/knowledge/protocols) | [CLI](/docs/cli/knowledge) |
+
+---
+
 ## 🔬 Advanced Features
 
 ### Research & Intelligence
@@ -2755,6 +2839,44 @@ agent.chat("Hello!")  # Auto-persists messages, runs, traces
 | `praisonai persistence migrate` | Apply schema migrations |
 | `praisonai persistence status` | Show schema status |
 
+### Knowledge CLI Commands {#knowledge-cli}
+
+| Command | Description |
+|---------|-------------|
+| `praisonai knowledge add <source>` | Add file, directory, URL, or glob pattern |
+| `praisonai knowledge query "<question>"` | Query knowledge base with RAG |
+| `praisonai knowledge list` | List indexed documents |
+| `praisonai knowledge clear` | Clear knowledge base |
+| `praisonai knowledge stats` | Show knowledge base statistics |
+
+**Knowledge Query Flags:**
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--vector-store` | `memory`, `chroma`, `pinecone`, `qdrant`, `weaviate` | `chroma` |
+| `--retrieval-strategy` | `basic`, `fusion`, `recursive`, `auto_merge` | `basic` |
+| `--reranker` | `none`, `simple`, `llm`, `cross_encoder`, `cohere` | `none` |
+| `--index-type` | `vector`, `keyword`, `hybrid` | `vector` |
+| `--query-mode` | `default`, `sub_question`, `summarize` | `default` |
+| `--workspace` | Path to workspace directory | Current dir |
+| `--session` | Session ID for persistence | - |
+
+**Examples:**
+
+```bash
+# Add documents
+praisonai knowledge add document.pdf
+praisonai knowledge add ./docs/
+praisonai knowledge add "*.md"
+
+# Query with options
+praisonai knowledge query "How to authenticate?" \
+  --vector-store chroma \
+  --retrieval-strategy fusion \
+  --reranker simple \
+  --query-mode sub_question
+```
+
 ### Databases Table
 
 | Database | Store Type | Install | Example | Docs |

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

docker/Dockerfile.dev

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

docker/Dockerfile.ui

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

examples/async_runs/README.py

@@ -0,0 +1,35 @@
+"""
+Async Runs Examples
+===================
+
+This directory contains examples for the PraisonAI Async Jobs API.
+
+Examples:
+---------
+1. sdk_submit_poll_result.py - Python SDK example for submit/poll/result
+2. cli_submit_poll_result.sh - Bash/curl example for submit/poll/result
+3. idempotency.sh - Demonstrates idempotency key usage
+4. cancel.sh - Demonstrates job cancellation
+5. sse_stream.sh - Demonstrates SSE streaming
+
+Prerequisites:
+--------------
+1. Set OPENAI_API_KEY environment variable
+2. Start the jobs server:
+   
+   cd /path/to/praisonai-package/src/praisonai
+   python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory
+
+3. Run examples:
+   
+   python sdk_submit_poll_result.py
+   bash cli_submit_poll_result.sh
+   bash idempotency.sh
+   bash cancel.sh
+   bash sse_stream.sh
+
+Environment Variables:
+----------------------
+- OPENAI_API_KEY: Required for agent execution
+- PRAISONAI_BASE_URL: API server URL (default: http://127.0.0.1:8005)
+"""

examples/async_runs/cancel.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# CLI Example: Cancel a Running Job
+#
+# This example demonstrates how to cancel a running job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cancel.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Job Cancellation Example"
+echo "============================================================"
+
+# Submit a long-running job
+echo ""
+echo "1. Submitting a job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "Write a detailed essay about the history of computing."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# Wait briefly
+echo ""
+echo "2. Waiting 1 second..."
+sleep 1
+
+# Cancel the job
+echo ""
+echo "3. Cancelling job..."
+CANCEL_RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs/$JOB_ID/cancel")
+STATUS=$(echo "$CANCEL_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+echo "   Status after cancel: $STATUS"
+
+# Verify cancellation
+echo ""
+echo "4. Verification:"
+if [ "$STATUS" = "cancelled" ]; then
+    echo "   ✓ SUCCESS: Job was cancelled"
+else
+    echo "   ℹ Job status: $STATUS (may have completed before cancel)"
+fi
+
+echo ""
+echo "============================================================"
+echo "Cancellation example completed!"
+echo "============================================================"

examples/async_runs/cli_submit_poll_result.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# CLI Example: Submit, Poll, and Get Result for Async Jobs
+#
+# This example demonstrates how to use the PraisonAI CLI to:
+# 1. Submit an async job
+# 2. Check job status
+# 3. Get the result
+#
+# Requirements:
+# - OPENAI_API_KEY environment variable set
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash cli_submit_poll_result.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+
+echo "============================================================"
+echo "PraisonAI Async Jobs CLI Example"
+echo "============================================================"
+
+# Check if server is running
+echo ""
+echo "Checking server health..."
+if ! curl -s "$API_URL/health" > /dev/null 2>&1; then
+    echo "✗ Server not available at $API_URL"
+    echo "  Start the server with: python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory"
+    exit 1
+fi
+echo "✓ Server is healthy"
+
+# 1. Submit a job
+echo ""
+echo "1. Submitting job..."
+RESPONSE=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -d '{"prompt": "What is 2+2? Answer with just the number."}')
+
+JOB_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID"
+
+# 2. Poll for status
+echo ""
+echo "2. Polling for status..."
+while true; do
+    STATUS_RESPONSE=$(curl -s "$API_URL/api/v1/runs/$JOB_ID")
+    STATUS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
+    PROGRESS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['progress']['percentage'])")
+    
+    echo "   Status: $STATUS | Progress: ${PROGRESS}%"
+    
+    if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
+        break
+    fi
+    
+    sleep 2
+done
+
+# 3. Get result
+echo ""
+echo "3. Getting result..."
+if [ "$STATUS" = "succeeded" ]; then
+    RESULT=$(curl -s "$API_URL/api/v1/runs/$JOB_ID/result")
+    echo "   Result: $(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['result'])")"
+    echo "   Duration: $(echo "$RESULT" | python3 -c "import sys,json; print(f\"{json.load(sys.stdin)['duration_seconds']:.2f}s\")")"
+else
+    echo "   Job did not succeed: $STATUS"
+fi
+
+echo ""
+echo "============================================================"
+echo "Example completed!"
+echo "============================================================"

examples/async_runs/idempotency.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# CLI Example: Idempotency Key Usage
+#
+# This example demonstrates how idempotency keys prevent duplicate job submissions.
+# Submitting the same request with the same idempotency key returns the existing job.
+#
+# Requirements:
+# - Jobs server running on http://127.0.0.1:8005
+#
+# Usage:
+#     bash idempotency.sh
+
+set -e
+
+API_URL="${PRAISONAI_BASE_URL:-http://127.0.0.1:8005}"
+IDEM_KEY="example-idem-key-$(date +%s)"
+
+echo "============================================================"
+echo "PraisonAI Idempotency Key Example"
+echo "============================================================"
+
+# First submission
+echo ""
+echo "1. First submission with Idempotency-Key: $IDEM_KEY"
+RESPONSE1=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "What is 1+1?"}')
+
+JOB_ID1=$(echo "$RESPONSE1" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID1"
+
+# Second submission with same key
+echo ""
+echo "2. Second submission with SAME Idempotency-Key: $IDEM_KEY"
+RESPONSE2=$(curl -s -X POST "$API_URL/api/v1/runs" \
+    -H "Content-Type: application/json" \
+    -H "Idempotency-Key: $IDEM_KEY" \
+    -d '{"prompt": "Different prompt but same key"}')
+
+JOB_ID2=$(echo "$RESPONSE2" | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")
+echo "   Job ID: $JOB_ID2"
+
+# Verify same job ID
+echo ""
+echo "3. Verification:"
+if [ "$JOB_ID1" = "$JOB_ID2" ]; then
+    echo "   ✓ SUCCESS: Same job ID returned (no duplicate created)"
+else
+    echo "   ✗ FAILURE: Different job IDs returned"
+    exit 1
+fi
+
+echo ""
+echo "============================================================"
+echo "Idempotency example completed!"
+echo "============================================================"