Metadata-Version: 2.4
Name: rostaingchain
Version: 2.0.4
Summary: The Enterprise-Grade Agentic Hybrid RAG & Multi-Agent Orchestration Framework.
Home-page: https://github.com/Rostaing/rostaingchain
Author: Davila Rostaing ENGANDZI
Author-email: rostaingdavila@gmail.com
License: MIT
Keywords: AI,Artificial Intelligence,Agentic AI,Agentic RAG,Hybrid RAG,RAG,Retrieval Augmented Generation,AI Agents,Autonomous AI Agents,Multi Agent Systems,Multi-Agent Orchestration,Generative AI,LLM,Large Language Models,Enterprise AI,Machine Learning,Deep Learning,Data Science,Data Analytics,AI Engineers,AI Developers,Data Scientists,Data Analysts,Python AI,LangChain,MCP,Vector Database,Embedding,pgvector,ChromaDB,FAISS,Qdrant,Ollama,OpenAI,Anthropic,Mistral,Google,Automation,Workflow Automation,Docker,Open Source AI
Platform: Windows
Platform: Linux
Platform: macOS
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain
Requires-Dist: langchain-community
Requires-Dist: langchain-core
Requires-Dist: langchain-text-splitters
Requires-Dist: python-dotenv
Requires-Dist: watchdog
Requires-Dist: markdown
Requires-Dist: tabulate
Requires-Dist: schedule
Requires-Dist: requests
Requires-Dist: langchain-ollama
Requires-Dist: langchain-openai
Requires-Dist: langchain-anthropic
Requires-Dist: langchain-google-genai
Requires-Dist: langchain-groq
Requires-Dist: langchain-mistralai
Requires-Dist: langchain-huggingface
Requires-Dist: huggingface-hub
Requires-Dist: chromadb
Requires-Dist: langchain-chroma
Requires-Dist: faiss-cpu
Requires-Dist: qdrant-client
Requires-Dist: fastembed
Requires-Dist: sentence-transformers
Requires-Dist: hf-xet
Requires-Dist: hf-transfer
Requires-Dist: langchain-qdrant
Requires-Dist: langchain-postgres
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: polars
Requires-Dist: fastexcel
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: sqlalchemy
Requires-Dist: pyodbc
Requires-Dist: pymssql
Requires-Dist: psycopg2-binary
Requires-Dist: psycopg
Requires-Dist: pymysql
Requires-Dist: pymongo
Requires-Dist: neo4j
Requires-Dist: rostaing-ocr
Requires-Dist: pdf2image
Requires-Dist: pytesseract
Requires-Dist: Pillow
Requires-Dist: pypdf
Requires-Dist: python-docx
Requires-Dist: openpyxl
Requires-Dist: python-pptx
Requires-Dist: unstructured
Requires-Dist: beautifulsoup4
Requires-Dist: html2text
Requires-Dist: rapidocr
Requires-Dist: onnxruntime
Requires-Dist: SpeechRecognition
Requires-Dist: gTTS
Requires-Dist: pygame
Requires-Dist: langdetect
Requires-Dist: sounddevice
Requires-Dist: mcp
Provides-Extra: all
Requires-Dist: langchain; extra == "all"
Requires-Dist: langchain-community; extra == "all"
Requires-Dist: langchain-core; extra == "all"
Requires-Dist: langchain-text-splitters; extra == "all"
Requires-Dist: python-dotenv; extra == "all"
Requires-Dist: watchdog; extra == "all"
Requires-Dist: markdown; extra == "all"
Requires-Dist: tabulate; extra == "all"
Requires-Dist: schedule; extra == "all"
Requires-Dist: requests; extra == "all"
Requires-Dist: langchain-ollama; extra == "all"
Requires-Dist: langchain-openai; extra == "all"
Requires-Dist: langchain-anthropic; extra == "all"
Requires-Dist: langchain-google-genai; extra == "all"
Requires-Dist: langchain-groq; extra == "all"
Requires-Dist: langchain-mistralai; extra == "all"
Requires-Dist: langchain-huggingface; extra == "all"
Requires-Dist: huggingface-hub; extra == "all"
Requires-Dist: chromadb; extra == "all"
Requires-Dist: langchain-chroma; extra == "all"
Requires-Dist: faiss-cpu; extra == "all"
Requires-Dist: qdrant-client; extra == "all"
Requires-Dist: fastembed; extra == "all"
Requires-Dist: sentence-transformers; extra == "all"
Requires-Dist: hf-xet; extra == "all"
Requires-Dist: hf-transfer; extra == "all"
Requires-Dist: langchain-qdrant; extra == "all"
Requires-Dist: langchain-postgres; extra == "all"
Requires-Dist: pandas; extra == "all"
Requires-Dist: numpy; extra == "all"
Requires-Dist: scipy; extra == "all"
Requires-Dist: polars; extra == "all"
Requires-Dist: fastexcel; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: seaborn; extra == "all"
Requires-Dist: sqlalchemy; extra == "all"
Requires-Dist: pyodbc; extra == "all"
Requires-Dist: pymssql; extra == "all"
Requires-Dist: psycopg2-binary; extra == "all"
Requires-Dist: psycopg; extra == "all"
Requires-Dist: pymysql; extra == "all"
Requires-Dist: pymongo; extra == "all"
Requires-Dist: neo4j; extra == "all"
Requires-Dist: rostaing-ocr; extra == "all"
Requires-Dist: pdf2image; extra == "all"
Requires-Dist: pytesseract; extra == "all"
Requires-Dist: Pillow; extra == "all"
Requires-Dist: pypdf; extra == "all"
Requires-Dist: python-docx; extra == "all"
Requires-Dist: openpyxl; extra == "all"
Requires-Dist: python-pptx; extra == "all"
Requires-Dist: unstructured; extra == "all"
Requires-Dist: beautifulsoup4; extra == "all"
Requires-Dist: html2text; extra == "all"
Requires-Dist: rapidocr; extra == "all"
Requires-Dist: onnxruntime; extra == "all"
Requires-Dist: SpeechRecognition; extra == "all"
Requires-Dist: gTTS; extra == "all"
Requires-Dist: pygame; extra == "all"
Requires-Dist: langdetect; extra == "all"
Requires-Dist: sounddevice; extra == "all"
Requires-Dist: mcp; extra == "all"
Provides-Extra: oracle
Requires-Dist: cx-oracle; extra == "oracle"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


<p align="center">
  <a href="https://pypi.org/project/rostaingchain/"><img src="https://img.shields.io/pypi/v/rostaingchain?color=blue&label=PyPI%20version" alt="PyPI version"></a>
  <a href="https://pypi.org/project/rostaingchain/"><img src="https://img.shields.io/pypi/pyversions/rostaingchain.svg" alt="Python versions"></a>
  <a href="https://github.com/Rostaing/rostaingchain/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/rostaingchain.svg" alt="License"></a>
  <a href="https://pepy.tech/project/rostaingchain"><img src="https://static.pepy.tech/badge/rostaingchain" alt="Downloads"></a>
</p>


<p align="center">
  <img src="https://raw.githubusercontent.com/Rostaing/rostaingchain-assets/main/logo.png" alt="RostaingChain Logo" width="450">
</p>


# 🧠 RostaingChain v2.0.4

**Enterprise-grade Agentic Hybrid RAG framework for building autonomous AI agents, multi-agent systems, enterprise search, workflow automation and production LLM applications.**  

`Autonomous Agents` | `Multi-Agent Teams` | `Real-Time Sound Device VAD` | `SLA Monitoring` | `DLP & PII Masking` | `Model Context Protocol (MCP)` | `NoSQL-like SQL Bootstrapping`


## 📋 Overview

**RostaingChain v2.0.4** is an industry-ready, high-performance, and resilient Python framework designed to build secure, autonomous, and hybrid Retrieval-Augmented Generation (RAG) systems. It seamlessly bridges the gap between private local compute (Ollama, local vector stores) and cloud-scale engines (OpenAI, Claude, Gemini, Groq, Mistral, Zilliz, Weaviate), featuring a robust real-time file watcher, advanced database connector pollers, and a unified multi-agent team control plane.


## 🚀 Key Architectural Pillars

### 1. Unified Multi-Agent Teams (`RostaingTeam`)
Orchestrate multiple specialized agents working collaboratively in three distinct coordination modes:
*   **Route Mode**: A history-aware master router analyzes the query, resolves conversational pronouns, and delegates the task to the best-suited expert agent.
*   **Coordinate Mode**: Simultaneously queries all workers in parallel using multi-threaded execution, then synthesizes their findings into a single, cohesive, and cross-referenced executive summary.
*   **Sequential Mode**: Pipeline tasks sequentially through agents, building upon the outputs of previous steps.

### 2. Autonomous Data Analyst & SQL Auto-Bootstrapping
When connected to structured data sources (CSV, Excel, Parquet, SQL, NoSQL), the agent executes local, sandboxed Python code to calculate exact statistics, perform advanced math (correlations, hypothesis testing), and save visualization charts directly to `public/graph/`.
*   **Zero-Config SQL Bootstrapping**: Like MongoDB, if you connect to a non-existent database in MySQL, PostgreSQL, or MS SQL Server, the framework automatically logs into the system master, programmatically builds the database container on the fly, and instantiates the schemas with no manual DBA intervention required.

### 3. Enterprise DLP Security (RGPD & SOC2 Compliant)
Protects sensitive personal identifiable information (PII) from leaking to external LLM APIs:
*   **Inbound Tokenization**: Replaces raw PII (emails, SSNs, credit cards, salaries, etc.) with reversible cryptographic tokens (e.g., `[ANON_EMAIL_1]`) before sending them to the cloud.
*   **Outbound Redaction / De-anonymization**: 
    *   *Redact Mode (Censorship)*: Replaces tokens in the final output with clean, permanent placeholders (e.g., `[Email Redacted]`).
    *   *De-anonymization Mode (Restore)*: Safely restores original values only for authorized local users.

### 4. Advanced SLA Monitoring & LLM-as-a-Judge Evaluation
Tracks system performance and data alignment automatically.
*   **Observability**: Logs response latency, conversation turns, and exact data sources used.
*   **LLM-as-a-Judge**: Programs parallel evaluators to grade **Retrieval** (Precision@K, Recall@K, MRR) and **Generation** (Groundedness, Faithfulness, Relevance) metrics.
*   **Independent Column Persistence**: Saves these metrics directly as flat, queryable columns inside your SQL (SQLite, PostgreSQL, MySQL, MSSQL) or NoSQL (MongoDB) databases, fully decoupled from local files.

### 5. High-Throughput Performance Engine
*   **Semantic Cache**: Employs local vector databases to instantly serve identical or semantically similar queries (0 ms API latency).
*   **Auto-Context Scaling**: Bypasses chunking entirely for small documents (CVs, invoices, short reports under 15,000 characters) to ensure 100% information retrieval, while using an advanced, non-fragmenting `SemanticChunker` for massive datasets.
*   **Just-In-Time (JIT) Lazy Loading**: Heavy scientific or multimedia libraries (like PyGame, PyTorch, Matplotlib, Seaborn, or Unstructured) are loaded *only on demand*, achieving sub-0.1s startup times.

### 6. Conversational Voice AI with Interruption Handling
*   **Real-time VAD**: Grabs mic streams and transcribes them using local Whisper.
*   **Sustained Speech Debouncer**: During TTS playback, a background thread monitors the microphone. If it hears continuous human speech (exceeding a calibrated threshold for 0.3s), it instantly stops the speaker, handles the interruption, and listens to the user.

### 7. Big Data Management
Implemented intelligent chunking (adaptive chunking), streaming ingestion, pagination/batching, and native DataFrame support (Pandas, Polars) to eliminate data truncation and optimize vectorization for large volumes. Includes memory management and disk/streaming fallback.

### 8. SKILLS System (Claude Code-like)
A robust modular skill architecture where each capability includes `SKILL.md` instructions, executable scripts, references, and assets. Features integrated, non-blocking file system hot-reloading: creating, modifying, or deleting skills on disk is automatically detected and dynamically injected into the active agent's system prompt on-the-fly, requiring zero server restarts. Fully compatible with dynamic tool execution and multi-agent orchestration.

### 9. Automation (n8n-like) & CLI Control 
`RostaingAgent` can now plan tasks, execute autonomous workflows, act as an orchestrator, and control the PC via a secure shell (with placeholders for full integration).


### 10. Enterprise Cross-Platform & Headless Compatibility (Windows, macOS, Linux)
RostaingChain is engineered to run consistently across all major operating systems (Windows, macOS, Linux) and headless cloud architectures (Docker, Kubernetes). The framework employs unified path abstractions to resolve directory separator differences automatically, and features graceful degradation guardrails—such as falling back to silent text logging when audio hardware or local OCR engines are absent on remote servers. This ensures your agentic workflows deploy reliably on local workstations or enterprise cloud nodes with zero configuration friction.



## 🛠 Environment Setup

To ensure stability and avoid dependency conflicts, we strongly recommend using a virtual environment. **RostaingChain** requires **Python 3.9 or higher**.

### Option 1: Using Python `venv` (Standard)

This is the built-in method. Choose the commands based on your Operating System:

#### **On Windows:**
```bash
# 1. Create the environment
python -m venv venv

# 2. Activate it
venv\Scripts\activate
```

#### **On macOS / Linux:**
```bash
# 1. Create the environment
python3 -m venv venv

# 2. Activate it
source venv/bin/activate
```

### Option 2: Using Conda (Recommended for Data Science)

Conda is often more robust for managing complex dependencies like `pyodbc` or `chromadb`.

```bash
# 1. Create the environment with a specific Python version
conda create -n rostaing_env python=3.12 -y

# 2. Activate the environment
conda activate rostaing_env
```


## 📦 Installation & System Dependencies
Once your environment is activated, you can install the framework.

Install the core framework:
```bash
pip install rostaingchain
```

To run high-concurrency relational databases or local vector stores, install their respective packages:
```bash
# For Milvus Cloud
pip install "pymilvus[milvus_lite]" "langchain-milvus"

# For Weaviate Cloud (WCS)
pip install "weaviate-client" "langchain-weaviate"
```


## 🔑 Environment Configuration (`.env`)

Create a `.env` file at your project root to manage your API keys, databases, and alerting SMTP servers securely:

1.  **Create a file named `.env`** in your project root.
2.  **Add your API keys** following this format:

To use remote LLMs (like OpenAI, Groq, Claude, Gemini, Grok, Mistral, DeepSeek) without hardcoding your credentials in the code, RostaingChain supports environment variables.

```env
# --- LLM API KEYS ---

# Standard Providers
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_API_KEY=...

# Fast Inference Providers
GROQ_API_KEY=...
MISTRAL_API_KEY=...

# OpenAI-Compatible Providers
DEEPSEEK_API_KEY=...
XAI_API_KEY=...

HF_TOKEN=...

# --- SLA & BDD METRICS RECORDING (SQL & NoSQL) ---
# SQL Database (Supports SQLite, PostgreSQL, MySQL, MSSQL, Oracle)
# The framework automatically bootstraps (creates) the database on the server if it does not exist.

# 1. MySQL (using pymysql driver)
EVAL_SQL_CONNECTION=mysql+pymysql://root:password@localhost:3306/eval_database

# 2. PostgreSQL (using psycopg driver)
# EVAL_SQL_CONNECTION=postgresql+psycopg://postgres:password@localhost:5432/eval_database

# 3. Microsoft SQL Server (using pymssql driver)
# EVAL_SQL_CONNECTION=mssql+pymssql://sa:password@localhost:1433/eval_database

# 4. Oracle Database (using cx_oracle driver)
# EVAL_SQL_CONNECTION=oracle+cx_oracle://system:password@localhost:1521/?service_name=eval_database

# 5. SQLite (using native sqlite driver with automatic WAL mode enabled)
# Dynamically configures Write-Ahead Logging (WAL) to allow simultaneous reads and writes.
# EVAL_SQL_CONNECTION=sqlite:///C:/Users/username/Desktop/rostaingchain/memory_cache/eval_database.db

# --- NoSQL DATABASE RECORDING (MongoDB) ---
# Automatically persists evaluation runs natively into your local or cloud MongoDB instances.

# 1. Local MongoDB Connection
EVAL_NOSQL_CONNECTION=mongodb://127.0.0.1:27017/

# 2. Cloud MongoDB Atlas Connection (Secure TLS)
# EVAL_NOSQL_CONNECTION=mongodb+srv://username:password@cluster-name.mongodb.net/


# --- ENTERPRISE SMTP EMAIL ALERTING ---
# Servers (Optional — uses the default value if not specified)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

SENDER_EMAIL=alerts-sender@gmail.com
SENDER_PASSWORD=...  # Google App Password
ALERT_RECIPIENT_EMAIL=admin-audit@yourcompany.com # Alert recipient
```

3.  **Load the keys** at the start of your script using `python-dotenv`:

```bash
pip install python-dotenv
```

## ⚡ Quick Start

### 1. The "Chat with Anything" Mode

Simply point `data_source` to a file, a folder, a database, or a URL.

```python
from rostaingchain import RostaingAgent

# Initialize the Agent
agent = RostaingAgent(
    llm_model="llama3.2", # Use local Ollama and ensure you ran 'ollama pull llama3.2' in your terminal
    data_source="/path/to/data", # Watches this folder
    auto_update=True             # Real-time ingestion
)

# Chat
response = agent.chat("What are the main topics in these documents?")
print(response)
```

### 2. 🚀 Quick Start: Interactive Console Agent

```python
import os
from dotenv import load_dotenv
from rostaingchain import RostaingAgent

# 1. Load environment variables (Make sure your .env file is set up)
load_dotenv()

def main():
    # 2. Initialize the Agent
    # RostaingAgent automatically handles data profiling, vector indexing, and memory.
    agent = RostaingAgent(
        llm_model="gpt-4o",
        llm_provider="openai",
        llm_api_key=os.getenv("OPENAI_API_KEY"),
        data_source="data/products.xlsx",  # Path to your CSV/SQL/Excel/Image/...
        vector_db="faiss",                 # High-performance vector storage
        reset_db=False,                    # Set to True to re-index the data
        memory=True,                       # Keep track of the conversation context
        stream=True
    )

    print("\n" + "="*40)
    print("🤖 RotaingChain AGENT: CONSOLE MODE")
    print("Type your question below or 'q' to exit.")
    print("="*40 + "\n")

    try:
        while True:
            # 3. Capture User Input
            user_input = input("👤 You: ").strip()

            # Exit condition
            if user_input.lower() in ["q", "quit", "exit"]:
                print("\nShutting down... Goodbye! 👋")
                break

            if not user_input:
                continue

            # 4. Generate & Display Response
            print("🤖 Agent:", end=" ", flush=True)
            
            try:
                response = agent.chat(user_input)
                print(response)
            except Exception as e:
                print(f"\n❌ Error: {str(e)}")

    except KeyboardInterrupt:
        print("\n\n[System] Session interrupted by user. Closing... 👋")
    finally:
        print("Program closed.")

if __name__ == "__main__":
    main()
```


## 🛠️ Advanced Usage

### 1. YouTube Video Analysis

Extract transcripts and metadata automatically.

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

agent = RostaingAgent(
    llm_model="openai/gpt-oss-120b",
    llm_provider="groq",
    data_source="https://www.youtube.com/watch?v=3mTK0vYYXA4",
    vector_db="faiss",
    stream=True
)

# Streaming response for better UX
generator = agent.chat("Summarize this video in 3 bullet points.")

for token in generator:
    print(token, end="", flush=True)
```


### 2. Data Security (DLP)

Protect sensitive information from being displayed.

```python
from rostaingchain import RostaingAgent

agent = RostaingAgent(
    llm_model="llama3.2",
    data_source="bank_statements.pdf",
    # Enable Security
    security_filters=["IBAN", "BIC", "PHONE", "EMAIL", "MONEY", "CREDIT_CARD"] # Optional: DLP Security. Set to True for ALL filters, False to disable, or a list to select specific fields.
)

response = agent.chat("Give me the IBAN of the supplier.")
print(response)
# Output: "The IBAN is [Protected IBAN bank details]."
```


### 3. Working with DataFrames (Pandas)

```python
import pandas as pd
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

df = pd.read_csv("titanic.csv") 

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="gpt-4o",
    data_source=df,
    vector_db="chroma" 
)

print(agent.chat("What is the average age of passengers?"))
```


### 4. Chat with a Website (Web RAG)

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source="https://en.wikipedia.org/wiki/Artificial_intelligence",
    vector_db="chroma",  # Options: 'faiss', 'qdrant' or 'chroma'
)

response = gent.chat("Give me a summary.")
print(response)
```


### 5. Chat with an image (RAG)

```python
from rostaingchain import RostaingAgent

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="llama3.2", # Ensure you ran 'ollama pull llama3.2' in your terminal
    llm_provider="ollama", # Runs 100% locally on your machine for privacy
    embedding_model="nomic-embed-text", # Ensure you ran 'ollama pull nomic-embed-text' in your terminal
    img4rag=True,
    data_source="invoice.jpg", # Supports: .png, .jpeg, .bmp, .tiff, .webp
    memory=True, # Enable conversation history
    vector_db="chroma",  # Options: 'faiss', 'qdrant'
)

response = gent.chat("Give me a summary.")
print(response)
```


### 6. Reporting Chatbot

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
import pandas as pd

# Load environment variables from .env file
load_dotenv()

df = pd.read_csv("C:/Users/Rostaing/Desktop/db/ds_salaries.csv")

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source=df,
    vector_db="chroma",  # Options: 'faiss', 'qdrant', 'chroma', etc.
    auto_update=True,
    skills_dir="./skills",
    max_memory_turns=5,

    # --- ULTRA-ADVANCED ENGINES ACTIVATION ---
    semantic_chunking=True,    # Intelligent Semantic Segmentation
    semantic_cache=True,       # Local Semantic Cache (0 ms latency for duplicate requests)
    reranking=True,            # Re-scoring local MMR + Cosine Similarity
    self_corrective_rag=True,  # Intelligent Prompt Rewriting for Failed Searches
    memory=True,
    canvas="word",
    alert_email=os.getenv("ALERT_RECIPIENT_EMAIL"),
    eval_pipeline=True,
    eval_sql_connection=os.getenv("EVAL_SQL_CONNECTION"),
    # security_filters= ["EMAIL", "PHONE", "MONEY", "DATE"],
    # redact_outbound=False,
    eval_nosql_connection=os.getenv("EVAL_NOSQL_CONNECTION"),
    stream=True
)

# Console-Based Interaction Loop
while True:
    try:
        # Retrieve user input
        user_input = input("\nYou : ")
        
        # Check if the user wants to quit (q or Q)
        if user_input.strip().lower() == 'q':
            print("\nClosing the console. Goodbye!")
            break
        
        # Ignore empty inputs
        if not user_input.strip():
            continue
        
        print("Agent : ", end="", flush=True)
        
        # Send the question to the agent
        response = agent.chat(user_input)
        
        # Stream the response
        for token in response:
            print(token, end="", flush=True)            
        
        # Line break at the end of the response
        print() 

    except KeyboardInterrupt:
        # Handle Ctrl+C shutdown
        print("\n\nInterruption detected (Ctrl+C). Goodbye!")
        sys.exit(0)
        
    except Exception as e:
        # Handle potential errors (API issues, etc.) to prevent the loop from crashing
        print(f"\nAn error occurred: {e}")
```


### 7. Chat with a file (Streaming RAG)

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source="your_file.txt", # Supports: .pdf, .docx, .doc, .xlsx, .xls, .pptx, .ppt, .html, .htm, .xml, .epub, .md, .json, .log, .py, .js, .sql, .yaml, .ini, etc.
    vector_db="chroma",  # Options: 'faiss' or 'chroma'
    stream=True
)

response = gent.chat("Give me a summary.")

# Real-time display loop
for token in response:
    # Prints every token as soon as it arrives (ChatGPT-like effect)
    print(token, end="", flush=True)
```


### 8. Connecting to Databases (SQL / NoSQL)

RostaingAgent uses a **Polling Watcher** to monitor database changes.

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

# PostgreSQL Configuration
db_config = {
    "type": "sql",
    "connection_string": "postgresql+psycopg2://your_username:your_password@localhost:5432/your_database",
    "query": "SELECT * FROM sales" # Your query
}

agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source=db_config,
    poll_interval=30, # Check for DB changes every 30 seconds
    reset_db=False,     # Start with a fresh index
    vector_db="faiss"
)

print(agent.chat("What is the total revenue for Q1?"))
# Thanks to Deep Profiling, the AI will know the exact sum/mean/max.
```


## ⚡ Advanced Code Examples

### 1. Zero-Config Collaborative Multi-Agent Team with Shared Memory & Cache

This example demonstrates how to orchestrate a team of three agents sharing a single, unified database and memory. We enable **Parallel Execution** to query the workers concurrently, **Semantic Cache** to avoid redundant API costs, and **Auto-Context Scaling** for data ingestion.

```python
import os
from dotenv import load_dotenv
from rostaingchain import RostaingAgent, RostaingTeam

load_dotenv()

# Shared corporate data source
data_file = "C:/Users/Rostaing/Desktop/db/data.pdf"

# Initialize Agent 1: Financial Expert
agent_finance = RostaingAgent(
    name="Financial_Expert",
    role="Senior Auditor. You analyze and extract budgets, financial forecasts, and costs.",
    data_source=data_file,
    shared_team_db=True,      # Shares the vector store with the team
    semantic_chunking=True,   # Segment data by semantic boundaries
    reset_db=True,            # Build the initial database once
    memory=True,
    semantic_cache=True,
    eval_pipeline=True
)

# Initialize Agent 2: Legal Expert
agent_legal = RostaingAgent(
    name="Legal_Expert",
    role="Corporate Attorney. You analyze contractual clauses, liabilities, and legal timelines.",
    data_source=data_file,
    shared_team_db=True,      # Uses the exact same database as Agent 1 (No re-indexing!)
    semantic_chunking=True,
    reset_db=False,           # Reuse the existing database
    memory=True,
    semantic_cache=True,
    eval_pipeline=True
)

# Initialize the RostaingTeam
team = RostaingTeam(
    agents=[agent_finance, agent_legal],
    mode="coordinate",        # Coordinate mode: query workers, then synthesize
    parallel=True             # EXTREME SPEED: Query both workers in parallel!
)

print("\n🚀 RostaingTeam is online. Asking team for consolidated analysis...")
query = "Evaluate this Business Plan: summarize the project, list the financial costs, and extract any legal liabilities."
response = team.chat(query)

print(f"\nFinal Consolidated Response:\n{response}")
```


### 2. Conversational Voice AI with Real-Time Interruption & SLA Logging

This script initializes a conversational loop. When the user speaks, it performs a RAG query on their local data, generates the response, reads it aloud, and **listens for voice interruptions**.

```python
import os
import sys
import time
from dotenv import load_dotenv
from rostaingchain import RostaingAgent

load_dotenv()

# Initialize the RAG Agent with voice input, output, and evaluation pipeline
agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source="C:/Users/Rostaing/Desktop/db/sleep_health_dataset.csv",
    
    # --- VOICE CAPABILITIES ---
    input_voice=True,         # STT active (Whisper)
    output_voice=True,        # TTS active (gTTS)
    voice_language="fr",      # Constrains Whisper to French (No background noise language confusion)
    
    # --- MONITORING & EVALUATION ---
    eval_pipeline=True,       # Auto-saves flat metrics to SQL / NoSQL defined in .env
    self_corrective_rag=True, # Auto-corrects pronunciations or typos
    memory=True
)

print("\n" + "="*50)
print("🎙️ Real-time Conversational Voice AI Agent Active!")
print("Speak freely. You can interrupt the agent's voice at any time.")
print("Press Ctrl+C to terminate.")
print("="*50 + "\n")

# Start the infinite background listening loop
agent.voice_agent.start_full_duplex()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    agent.voice_agent.stop()
    print("\nSession closed. Goodbye!")
```


### 3. Desktop Canvas Automation (RAG to justified Word Report / Excel Sheet)

This example shows how to direct the agent's output into a **fully styled Word Document** with justified text paragraphs and embedded tables, and open it natively on the user's desktop.

```python
import os
from dotenv import load_dotenv
from rostaingchain import RostaingAgent

load_dotenv()

agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai",
    data_source="C:/Users/Rostaing/Desktop/db/sleep_health_dataset.csv",
    save_graph=True,          # Automatically save generated charts to public/graph/
    
    # --- CANVAS ENGINE ---
    # Options: "word" (justified report), "excel" (native spreadsheet), "powerpoint" (slides), "text" (plain log)
    canvas="word",
)

# This query will make the agent run python code, plot a chart, 
# write a beautifully justified Word Report, insert the chart natively,
# close any existing Word lock, save it to the Desktop, and open it!
query = "Plot the distribution of Sleep Duration across professions and summarize the statistics."
response = agent.chat(query)
print("Task Completed.")
```


### 4. Zero-Config Model Context Protocol (MCP) filesystem integration

Connect your agent to a secure local filesystem server using the open-source MCP standard in one line of configuration:

```python
import os
from dotenv import load_dotenv
from rostaingchain import RostaingAgent

load_dotenv()

agent = RostaingAgent(
    llm_model="gpt-4o",
    data_source="C:/Users/Rostaing/Desktop/db/doc.docx",
    
    # --- REGISTER MCP SYSTEM TOOLS ---
    # Automatically boots up the Node server and registers: read_file, write_file, list_directory
    mcp_tools=[
        {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Rostaing/Desktop"]
        }
    ]
)

# The agent can now use the filesystem tools to write its findings to a new file!
query = "Read the main points of doc.docx and write a short summary inside a new file on my Desktop named RAG_Summary.txt"
agent.chat(query)
```


### 🗄️ Database Configuration Examples

To connect **RostaingAgent** to a database, create a dictionary `db_config` and pass it to the `data_source` parameter.

### SQL Databases (via SQLAlchemy)

**PostgreSQL**
```python
pg_config = {
"type": "sql",
"connection_string": "postgresql+psycopg2://your_username:your_password@localhost:5432/your_database",
"query": "SELECT * FROM sales" # Your query
}
```

**MySQL**
```python
mysql_config = {
    "type": "sql",
    "connection_string": "mysql+pymysql://my_username:your_password@localhost:3306/your_database",
    "query": "SELECT * FROM orders WHERE status = 'shipped'" # Your query
}
```

**Oracle**
```python
# Requires Oracle Instant Client installed
# Ensure you ran 'pip install cx-oracle' in your terminal
oracle_config = {
    "type": "sql",
    "connection_string": "oracle+cx_oracle://your_username:your_password@localhost:1521/?service_name=ORCL",
    "query": "SELECT * FROM employees" # Your query
}
```

**SQLite**
```python
sqlite_config = {
    "type": "sql",
    "connection_string": "sqlite:///C:/path/to/your_data.db",
    "query": "SELECT * FROM invoices" # Your query
}
```

**Microsoft SQL Server**
```python
# Option 1

mssql_config = {
    "type": "sql",
    "connection_string": "mssql+pymssql://your_username:your_password@localhost:1433/your_database",
    "query": "SELECT top 100 * FROM customers" # Your query
}

# Option 2 (Recommended)
# We build a valid SQLAlchemy URL.
# We use quote_plus to handle special characters like \ in the server name.

host = r"your_host" # Example: DESKTOP-9K6BSF8\SQLEXPRESS
db_name = "your_database"
username = "your_username"
password = "your_password"

connection_string = f"mssql+pyodbc://{username}:{password}@{host}/{db_name}?driver=ODBC+Driver+17+for+SQL+Server&TrustServerCertificate=yes"
mssql_config = {
    "type": "sql",
    "connection_string": connection_string,
    "query": "SELECT * FROM customers" # Your query
}
```


### NoSQL Databases

**MongoDB**
```python
mongo_config = {
    "type": "mongodb",
    "uri": "mongodb://localhost:27017/",
    "db": "ecommerce_db",
    "collection": "products",
    "limit": 50 # Optional: Limit the number of documents to ingest
}
```

**Neo4j (Graph)**
```python
neo4j_config = {
    "type": "neo4j",
    "uri": "bolt://localhost:7687",
    "user": "neo4j",
    "password": "your_password",
    "query": "MATCH (p:Person)-[:WROTE]->(a:Article) RETURN p.name, a.title LIMIT 20" # Your query
}
```


### Usage Example

```python
agent = RostaingAgent(
    llm_model="gpt-4o",
    data_source=mysql_config, # Pass the dictionary here.
    poll_interval=3600,         # Watch for changes every minute
    reset_db=False
)
```


### ☁️ Cloud Vector Databases (Qdrant, Milvus & Weaviate)

In production enterprise deployments, local embedded vector databases are discouraged due to memory and platform-locking constraints. RostaingChain supports connecting natively to enterprise-grade managed cloud vectors.

#### 1. Milvus (Zilliz Cloud)

To connect your agent to **Zilliz Cloud** (the managed service for Milvus), set `vector_db="milvus"`, and pass your Zilliz Endpoint as the `db_connection_string` and your Zilliz Token as the `llm_api_key`.

```python
from rostaingchain import RostaingAgent

agent = RostaingAgent(
    vector_db="milvus",
    # Pass your managed Zilliz Cloud endpoint URI
    db_connection_string="https://in03-xxxxxxxxxxx.zillizcloud.com:443", 
    # Pass your Zilliz Cloud API cluster token
    llm_api_key="your-zilliz-cloud-token",                             
    data_source="C:/path/to/corporate_document.pdf"
)
```

#### 2. Weaviate (Weaviate Cloud Services - WCS)

To connect your agent to **Weaviate Cloud Services (WCS)**, set `vector_db="weaviate"`, and pass your WCS Cluster URL as the `db_connection_string` and your WCS API Key as the `llm_api_key`.

```python
from rostaingchain import RostaingAgent

agent = RostaingAgent(
    vector_db="weaviate",
    # Pass your Weaviate Cloud Services cluster URL
    db_connection_string="https://your-cluster-name.weaviate.network", 
    # Pass your Weaviate WCS API cluster Key
    llm_api_key="your-wcs-api-key",                                  
    data_source="C:/path/to/corporate_document.pdf"
)
```

#### 3. Qdrant Cloud

To connect your agent to **Qdrant Cloud**, set `vector_db="qdrant"`, and pass your Qdrant Cloud Cluster URL as the `db_connection_string` and your Qdrant Cloud API Key as the `llm_api_key`.

```python
from rostaingchain import RostaingAgent

agent = RostaingAgent(
    vector_db="qdrant",
    # Pass your Qdrant Cloud cluster URL (usually listening on port 6333)
    db_connection_string="https://your-cluster-id.aws.qdrant.io:6333", 
    # Pass your Qdrant Cloud API access Key
    llm_api_key="your-qdrant-cloud-api-key",                                  
    data_source="C:/path/to/corporate_document.pdf"
)
```

> 💡 **Auto-Fallback Note**: If you initialize your agent with `vector_db="milvus"` or `vector_db="weaviate"` but do NOT provide a valid cloud `db_connection_string`, RostaingChain's internal factory will automatically fallback to **Chroma** locally to ensure zero-crash operations.


### Use a custom LLM (e.g., vLLM on another server)

```python
from rostaingchain import RostaingAgent
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()

# Direct Memory Ingestion
agent = RostaingAgent(
    llm_model="my-finetuned-model",
    llm_provider="custom",
    llm_base_url="http://192.168.1.50:8000/v1", # Your vLLM server
    llm_api_key="token-if-needed",
    memory=True,
    vector_db="chroma",  # Options: 'faiss', 'chroma' or 'qdrant'
    data_source="/path/to/your_file.pdf", # Supports: .txt, .docx, .doc, .xlsx, .xls, .pptx, .ppt, .html, .htm, .xml, .epub, .md, .json, .log, .py, .js, .sql, .yaml, .ini, .jpg, .png, .jpeg, .bmp, .tiff, .webp, SQL/NoSQL Databases, Web(link), etc.
    reset_db=True, # Start with a fresh index
    temperature=0,
    top_k=0.1,
    top_p=1,
    max_tokens=1500,
    stream=True
)

response = gent.chat("Give me a summary.")

# Real-time display loop
for token in response:
    # Prints every token as soon as it arrives (ChatGPT-like effect)
    print(token, end="", flush=True)
```


### Universal Intelligence: Switching LLM Providers

**A. Use DeepSeek (the cheaper GPT-4 alternative)**
```python
agent = RostaingAgent(
    llm_model="deepseek-chat", # Auto-detection
    provider="deepseek",
    # If the key is not in the .env:
    llm_api_key="sk-your-deepseek-key" 
)
```

**B. Use Groq (Lightning speed – 500 tokens/s)**
```python
agent = RostaingAgent(
    llm_model="openai/gpt-oss-120b",
    llm_provider="groq" # Force the provider to ensure it
)
```

**C. Use Claude Sonnet (Best for coding)**
```python
agent = RostaingAgent(
    llm_model="claude-4.5-sonnet",
    llm_provider="anthropic" # Force the provider to ensure it
)
```

**D. Use Gemini 3 Pro (Google)**
```python
agent = RostaingAgent(
    llm_model="gemini-3-pro-preview",
    llm_provider="google" # Force the provider to ensure it
)
```

**E. Use Mistral (via Groq for Speed)**
```python
agent = RostaingAgent(
    llm_model="mistral-large-2512",
    llm_provider="mistral" # Force the provider for ultra-fast inference
)
```

**F. Use Grok (xAI)**
```python
agent = RostaingAgent(
     llm_model="grok-4.1",
    llm_provider="grok" # Automatically configures the xAI API base_url
)
```

**G. Use OpenAI (GPT-4o)**
```python
agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai" # Automatically uses OPENAI_API_KEY from your .env file
)
```

**H. Use Local LLMs (Ollama)**
```python
agent = RostaingAgent(
    llm_model="llama3.2",  # Ensure you ran 'ollama pull llama3.2' in your terminal
    llm_provider="ollama", # Runs 100% locally on your machine for privacy
    # llm_base_url="http://localhost:11434" # Optional: Default URL
)
```

**I. Using LM Studio (Local & Private)**
Ensure LM Studio is running and the Local Server is turned on (default port 1234).
```python
agent = RostaingAgent(
    llm_provider="lmstudio",
    llm_model="local-model", # The name doesn't matter much for LM Studio
    # You don't even need to provide base_url or api_key, it automatically knows to use http://localhost:1234/v1 !
    data_source="C:/Users/rostaing/Desktop/db/doc.docx"
)
```

**J. Using vLLM (High-Performance Local)**
Ensure your vLLM server is running on port 8000.
```python
agent = RostaingAgent(
    llm_provider="vllm",
    llm_model="meta-llama/Llama-3-8b-Instruct", # The specific model loaded in vLLM
    # Automatically defaults to http://localhost:8000/v1
    data_source="C:/Users/rostaing/Desktop/db/doc.docx"
)
```

**K. Using Hugging Face (Cloud Inference API)**
(Note: Some large models on Hugging Face require a Pro subscription for their API, but thousands of smaller models are free).
```python
import os

agent = RostaingAgent(
    llm_provider="huggingface",
    llm_model="mistralai/Mistral-7B-Instruct-v0.3", # Any compatible Hugging Face Hub model ID
    llm_api_key=os.getenv("HF_TOKEN"), # Your Hugging Face Access Token
    data_source="C:/Users/rostaing/Desktop/db/doc.docx"
)
```


#### 📝 Key Parameters Explained

*   **`stream=True`**:
    This is essential for User Experience (UX). Instead of waiting for the entire response to be generated (which can take time for long summaries), the method returns a Python **Generator**. You must iterate over it (using a `for` loop) to display tokens in real-time, exactly like ChatGPT.

*   **`output_format`**:
    This parameter enforces the structure or style of the LLM's response. It accepts three values:
    *   `"text"` (Default): A standard, conversational plain text response.
    *   `"json"`: Forces the LLM to output a valid JSON object. Extremely useful if you are building an API or need to parse the result programmatically.
    *   `"cartoon"`: Makes the LLM generate responses in a playful, cartoon-style tone with simplified language and expressive descriptions. Useful for educational content, storytelling, or kid-friendly interfaces.

*   **`vector_db`**:
    Defines the local vector storage engine. RostaingChain currently supports two robust, file-based options:
    *   `"chroma"`: Uses Chroma vector database (lightweight, developer-friendly, optimized for local-first embedding storage and retrieval).
    *   `"faiss"`: Uses Facebook AI Similarity Search (highly efficient for CPU).
    *   `"qdrant\"`: Uses Qdrant vector database (open-source, written in Rust, optimized for fast similarity search with payload filtering and horizontal scaling).


## ⚙️ Configuration Parameters

For the full list of configuration parameters, place your cursor inside the `RostaingAgent` constructor in **VS Code** and press **`Ctrl` + `Space`** to trigger autocomplete/IntelliSense.

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| **RostaingAgent Core** | | | |
| `llm_model` | str | `"llama3.2"` | Name of the active LLM (e.g., `"gpt-4o"`, `"claude-3-5-sonnet"`, `"llama3"`). |
| `llm_provider` | str | `"auto"` | LLM provider: `"openai"`, `"anthropic"`, `"google"`, `"groq"`, `"mistral"`, `"deepseek"`, `"grok"`, `"vllm"`, `"lmstudio"`, `"huggingface"`, or `"ollama"`. |
| `llm_api_key` | str | `None` | Custom API Key (optional if configured in your `.env` file). |
| `llm_base_url` | str | `None` | Custom API endpoint URL (for local vLLM, LM Studio, or proxy endpoints). |
| `embedding_model` | str | `"BAAI/bge-small-en-v1.5"` | Model used for vectorizing documents into embeddings. |
| `embedding_source` | str | `"fastembed"` | Embeddings library provider: `"fastembed"`, `"openai"`, `"huggingface"`, or `"ollama"`. |
| `llm_prompt_cost` | float | `None` | Custom prompt/input token rate (in USD per 1,000,000 tokens) to dynamically override default model prices. |
| `llm_completion_cost` | float | `None` | Custom completion/output token rate (in USD per 1,000,000 tokens) to dynamically override default model prices. |
| `vector_db` | str | `"chroma"` | Vector Database engine: `"chroma"`, `"faiss"`, `"qdrant"`, `"milvus"`, `"weaviate"`, or `"supermemory"`. |
| `data_source` | str/dict/obj | `"./data"` | Unified source path: local files, folder directories, Pandas/Polars DataFrames, Web URLs, or SQL/NoSQL connection configurations. |
| **Automation & Watchers** | | | |
| `auto_update` | bool | `True` | Activates real-time, non-blocking background folder Watchers (using `watchdog`) or database Polling. |
| `poll_interval` | int | `60` | Interval in seconds between consecutive database or web polling runs. |
| `reset_db` | bool | `False` | Wipes and resets both the local vector store and the semantic cache on startup. |
| `memory` | bool | `False` | Enables persistent multi-turn conversational history (saves to `./memory_cache`). |
| `save_graph` | bool | `False` | Saves autonomously generated analyst charts directly to `public/graph/`. |
| `save_logs` | bool | `False` | Writes secure, timestamped JSON logs to `public/logs/`. |
| **Generation Settings** | | | |
| `temperature` | float | `0.1` | Creativity/determinism of the model (0.0 = analytical, 1.0 = creative). |
| `max_tokens` | int | `None` | Strict limit on the maximum generated response tokens. |
| `top_p` | float | `None` | Nucleus sampling probability threshold. |
| `top_k` | int | `None` | Top-K vocabulary filtering threshold. |
| `seed` | int | `None` | Integer seed to guarantee deterministic, reproducible outputs. |
| `stream` | bool | `False` | Enables token-by-token streaming generator output. |
| `cache` | bool | `True` | Enables fast in-memory compilation caching. |
| `output_format` | str | `"text"` | Enforces response styles: `"text"`, `"json"`, `"markdown"`, or `"cartoon"`. |
| **Agent Identity** | | | |
| `role` | str | `"Helpful Assistant"` | Defines the precise persona and authority profile of the agent. |
| `goal` | str | `"Assist the user..."` | The primary mission of the agent. |
| `instructions` | str | `"Answer concisely."` | Strict behavioral constraints or custom formatting rules. |
| `reflection` | bool | `False` | Enables "Step-by-step" chain-of-thought planning and internal critique before answering. |
| **Company Context** | | | |
| `company_name` | str | `None` | Organization name for custom context grounding. |
| `company_description`| str | `None` | Overview of the company's industry and baseline operations. |
| `company_url` | str | `None` | Reference URL for web-informed queries. |
| **Security & PII (DLP)** | | | |
| `security_filters` | list/bool | `None` | List of target PII data types to protect (e.g. `["EMAIL", "PHONE", "MONEY"]`) or `True` for all. |
| `redact_outbound` | bool | `True` | `True` to permanently censor sensitive data to `[Redacted]`. `False` to temporarily mask only API-bound data, safely restoring original values for the final output. |
| `user_profile` | str | `None` | Role-Based Access Control (RBAC) profile (e.g. `"Intern"`, `"Admin"`). Admins automatically bypass DLP redactions. |
| `user_id` | str | `None` | Unique ID for multi-tenant billing and auditing. |
| `session_id` | str | `None` | Unique ID to separate distinct user chat session logs. |
| `agent_id` | str | `None` | Unique ID to audit the specific agent instance performance. |
| `system_prompt` | str | `None` | Full, advanced override of the underlying system prompt. |
| **SLA Monitoring & Evaluation** | | | |
| `eval_pipeline` | bool | `False` | Enables parallel LLM-as-a-Judge evaluations on every run. Automatically auto-activates if connection keys are detected in your `.env`. |
| `eval_sql_connection` | str | `None` | Relational database URI to save metrics natively as flat columns (Supports SQLite, PostgreSQL, MySQL, MSSQL, Oracle). |
| `eval_nosql_connection`| str | `None` | MongoDB connection URI to save metrics natively as flat document fields. |
| **Advanced Agentic Features** | | | |
| `shared_team_db` | bool | `False` | Shares a single synchronized database and memory across all agents inside a `RostaingTeam`, preventing data duplication and context loss. |
| `semantic_chunking` | bool | `False` | Uses a dynamic, list-aware sentence similarity model to chunk data, keeping headings and lists strictly grouped. |
| `semantic_cache` | bool | `False` | Employs a local FAISS semantic cache to instantly serve recurring or highly similar queries with 0 ms API latency. |
| `reranking` | bool | `False` | Performs a local matrix Cosine Similarity re-scoring on retrieved context chunks, retaining only the top 4 highly relevant sources. |
| `self_corrective_rag` | bool | `False` | Invokes an automatic query-reformulation loop if initial retrieval is poor, correcting typos, phonetic transcriptions, and spelling mistakes. |
| **Conversational Voice AI** | | | |
| `input_voice` | bool | `False` | Enables microphone capturing and local, multilingual Whisper transcription. |
| `output_voice` | bool | `False` | Enables natural, multilingual speech synthesis (gTTS) with automatic language detection. |
| `voice_language` | str | `None` | Constrains both the voice input and output to a strict language code (e.g., `"fr"`, `"en"`) to prevent background noise translation glitches. |
| **Tools & Office Canvas** | | | |
| `mcp_tools` | list | `None` | List of Model Context Protocol server configurations (e.g. `{"command": "npx", "args": [...]}`) to dynamically mount external system tools. |
| `canvas` | str | `None` | Destination format for reporting: `"word"` (justified report), `"excel"` (spreadsheets), `"powerpoint"` (slides), or `"text"` (plain logs). Opens the application natively on Desktop on run. |


## 👥 RostaingTeam Configuration Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `agents` | list | *Required* | List of fully instantiated `RostaingAgent` objects representing the specialized team members. |
| `mode` | str | `"route"` | Orchestration mode for the team: `"route"` (context-aware router), `"coordinate"` (collaborative synthesis), or `"sequential"` (linear pipeline). |
| `ask_other_team_members`| bool | `True` | Intercepts prompts to enable autonomous background inter-agent collaboration, peer-to-peer queries, and delegation. |
| `parallel` | bool | `False` | Enables high-performance parallel, multi-threaded execution (using `ThreadPoolExecutor`) of all worker agents in `coordinate` mode to cut latency. |


## 📊 SLA Evaluation & Audit Database Schema

When `eval_pipeline=True` is enabled and database connection strings are present in your `.env`, RostaingChain automatically and independently persists the following flat, indexed metrics into your SQL (SQLite, PostgreSQL, MySQL, MS SQL Server, Oracle) and NoSQL (MongoDB) databases:

| Database Field / Column | Type (SQL) | Type (NoSQL) | Description |
| :--- | :--- | :--- | :--- |
| `id` | `INTEGER (PK)` | `ObjectId` | Unique auto-incrementing identifier for the run. |
| `timestamp` | `VARCHAR(50)` | `String` | Exact date and time when the interaction took place. |
| `user_id` | `VARCHAR(100)`| `String` | Unique identifier of the user who initiated the request. |
| `sources_used` | `TEXT` | `String` | Comma-separated list of document source files read by the RAG. |
| `model_name` | `VARCHAR(100)`| `String` | Name of the active LLM model used for the run (e.g., gpt-5.5, claude-3-5-sonnet). |
| `query` | `VARCHAR(1000)`| `String` | The raw text or voice question submitted by the user. |
| `ai_response` | `TEXT` | `String` | The exact response generated by the AI (supports heavy Base64 charts). |
| `latency_seconds` | `FLOAT` | `Double` | End-to-end execution time in seconds. |
| `precision_at_k` | `FLOAT` | `Double` | Retrieval metric: Ratio of relevant retrieved documents in Top K. |
| `recall_at_k` | `FLOAT` | `Double` | Retrieval metric: Proportion of retrieved relevant items in Top K. |
| `mrr` | `FLOAT` | `Double` | Mean Reciprocal Rank: Positional quality of the first relevant document. |
| `groundedness` | `FLOAT` | `Double` | Judge score (0.00-1.00): Is the answer strictly based on the context? |
| `faithfulness` | `FLOAT` | `Double` | Judge score (0.00-1.00): Is the response 100% truthful (no hallucinations)? |
| `relevance` | `FLOAT` | `Double` | Judge score (0.00-1.00): Does the response fully and directly answer the query? |
| `resolution_rate` | `INTEGER` | `Int32` | Business metric: `1` for successfully resolved task, `0` for knowledge gap. |
| `time_saved_seconds` | `FLOAT` | `Double` | Business metric: Estimated human work seconds saved (300s baseline - latency). |
| "est_user_satisfaction"| `FLOAT` | `Double` | Estimated user satisfaction score based on generation quality. |
| `prompt_tokens` | `INTEGER` | `Int32` | Exact count of input tokens sent to the LLM. |
| `completion_tokens` | `INTEGER` | `Int_32` | Exact count of output tokens generated by the LLM. |
| `total_tokens` | `INTEGER` | `Int_32` | Total token volume (prompt + completion) consumed. |
| `cost_usd` | `FLOAT` | `Double` | Real-time billing cost calculated dynamically in USD based on model rates. |


## 🛡️ Security Filters & PII Masking

When `security_filters` is active, the framework tokenizes data *before* sending it to any local or cloud LLM, and processes it on exit according to `redact_outbound`:

| Data type | Redact Mode (`True`) | Reversible Mode (`False`) |
| :--- | :--- | :--- |
| **EMAIL** | `[Email Redacted]` | Restores original email (e.g. `user@email.com`) |
| **PHONE** | `[Phone Redacted]` | Restores original phone number |
| **ID_NUM** | `[Id Num Redacted]` | Restores original ID |
| **PASSPORT**| `[Passport Redacted]` | Restores original passport |
| **SSN** | `[Ssn Redacted]` | Restores original SSN |
| **ADDRESS** | `[Address Redacted]` | Restores original address |
| **POSTAL** | `[Postal Redacted]` | Restores original postal code |
| **BIC** | `[Bic Redacted]` | Restores original BIC |
| **IBAN** | `[Iban Redacted]` | Restores original IBAN |
| **VAT_ID** | `[Vat Id Redacted]` | Restores original VAT |
| **CREDIT_CARD**| `[Credit Card Redacted]`| Restores original card |
| **MONEY** | `[Money Redacted]` | Restores original money amount |
| **CRYPTO** | `[Crypto Redacted]` | Restores original crypto wallet |
| **IP_ADDR** | `[Ip Addr Redacted]` | Restores original IP |
| **MAC_ADDR**| `[Mac Addr Redacted]` | Restores original MAC |
| **API_KEY** | `[Api Key Redacted]` | Restores original API key |
| **DATE** | `[Date Redacted]` | Restores original date |
| **SALARY** | `[Salary Redacted]` | Restores original salary |
| **BIRTHDATE**| `[Birthdate Redacted]`| Restores original birthdate |
| **MEDICAL** | `[Medical Redacted]` | Restores original medical term |


## 💡 Pro Tip: VSCode Autocomplete

Don't memorize the parameters! If you are using **VSCode**, you can view the complete list of available options for `RostaingAgent` instantly.

Just place your cursor inside the parentheses and press:

**`Ctrl` + `Space`**

This will trigger IntelliSense and display all configuration arguments (like `memory`, `security_filters`, `temperature`, `cache`, etc.) with their descriptions.


## 🔗 Useful Links
*   **Author's LinkedIn**: [Davila Rostaing](https://www.linkedin.com/in/davila-rostaing/)
*   **YouTube Channel**: [RostaingAI](https://youtube.com/@RostaingAI?sub_confirmation=1)
*   **PyPI Project**: [RostaingChain on PyPI](https://pypi.org/project/rostaingchain/)
