🧠 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:

# 1. Create the environment
python -m venv venv

# 2. Activate it
venv\Scripts\activate

On macOS / Linux:

# 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.

# 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:

pip install rostaingchain

To run high-concurrency relational databases or local vector stores, install their respective packages:

# 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.

# --- 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:

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.

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

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.

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.

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)

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)

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)

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

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)

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.

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.

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.

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.

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:

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

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

MySQL

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

# 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

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

Microsoft SQL Server

# 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

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)

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

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.

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.

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.

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)

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)

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)

agent = RostaingAgent(
    llm_model="openai/gpt-oss-120b",
    llm_provider="groq" # Force the provider to ensure it
)

C. Use Claude Sonnet (Best for coding)

agent = RostaingAgent(
    llm_model="claude-4.5-sonnet",
    llm_provider="anthropic" # Force the provider to ensure it
)

D. Use Gemini 3 Pro (Google)

agent = RostaingAgent(
    llm_model="gemini-3-pro-preview",
    llm_provider="google" # Force the provider to ensure it
)

E. Use Mistral (via Groq for Speed)

agent = RostaingAgent(
    llm_model="mistral-large-2512",
    llm_provider="mistral" # Force the provider for ultra-fast inference
)

F. Use Grok (xAI)

agent = RostaingAgent(
     llm_model="grok-4.1",
    llm_provider="grok" # Automatically configures the xAI API base_url
)

G. Use OpenAI (GPT-4o)

agent = RostaingAgent(
    llm_model="gpt-4o",
    llm_provider="openai" # Automatically uses OPENAI_API_KEY from your .env file
)

H. Use Local LLMs (Ollama)

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).

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.

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).

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.

👥 RostaingTeam Configuration Parameters

📊 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:

🛡️ 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:

💡 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
• YouTube Channel: RostaingAI
• PyPI Project: RostaingChain on PyPI