Metadata-Version: 2.4
Name: mzero-rag
Version: 0.1.1
Summary: Zero-Configuration RAG Framework and Embeddable SDK for Python
Author-email: MZero Team <info@mzero.ai>
License: MIT
Project-URL: Homepage, https://github.com/bala-2305/advanced_rag_pipeline
Project-URL: Documentation, https://github.com/bala-2305/advanced_rag_pipeline#readme
Project-URL: Repository, https://github.com/bala-2305/advanced_rag_pipeline.git
Project-URL: Issues, https://github.com/bala-2305/advanced_rag_pipeline/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sentence-transformers>=2.2.2
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: chromadb>=0.4.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.22.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pypdf>=3.9.0
Requires-Dist: python-docx>=0.8.11
Requires-Dist: python-pptx>=0.6.21
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: streamlit>=1.25.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.25.0; extra == "streamlit"
Requires-Dist: watchdog>=3.0.0; extra == "streamlit"
Provides-Extra: full
Requires-Dist: qdrant-client>=1.6.0; extra == "full"
Requires-Dist: pymilvus>=2.3.0; extra == "full"
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: youtube-transcript-api>=0.6.0; extra == "full"
Requires-Dist: langchain-core>=0.1.0; extra == "full"
Requires-Dist: llama-index-core>=0.10.0; extra == "full"
Requires-Dist: flask>=2.3.0; extra == "full"
Requires-Dist: streamlit>=1.25.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# mzero: Zero-Configuration RAG Framework

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.25+-FF4B4B.svg?logo=streamlit&logoColor=white)](https://streamlit.io/)

**mzero** is a zero-configuration Retrieval-Augmented Generation (RAG) framework and embeddable Python SDK. It abstracts document ingestion, domain-aware chunking, dynamic vector store routing, hybrid dense/sparse search, cross-encoder reranking, conversation state management, and hallucination verification behind a minimal single-line interface.

```python
from mzero import RAG

rag = RAG("./docs")
print(rag.ask("Explain the refund policy"))
```

---

## Architecture Flow

```mermaid
graph TD
    A[Document Corpus] --> B[Router Parser]
    B -->|PDF / DOCX / MD / Code / Web| C[Adaptive Chunker]
    C --> D[Embedding Selector]
    D --> E[Vector DB Store Router]
    E -->|FAISS / Chroma / Qdrant / Milvus| F[Hybrid Retriever]
    
    UserQuery[User Query] --> G[Semantic Cache]
    G -->|Cache Hit| ReturnCache[Return Cached Response]
    G -->|Cache Miss| F
    
    F -->|Reciprocal Rank Fusion| H[Cross-Encoder Reranker]
    H --> I[LLM Query Engine]
    I --> J[Hallucination Verifier]
    J -->|Verified| Output[Response & Citations]
    J -->|Unverified Grounding| WebFallback[Web Search Fallback]
```

---

## Core Specifications & Features

- **Zero Configuration Setup**: Automatic runtime initialization of storage, indexes, and model pipelines based on directory inspection.
- **Smart Multi-Format Parsing**: Built-in support for PDF, DOCX, TXT, MD, HTML, CSV, JSON, XML, PPTX, Source Code ASTs, Web Pages, OCR Images, and YouTube transcripts.
- **Adaptive Chunking**: Domain-aware context splitting for structured manuals, AST-based source code parsing, legal contracts, research papers, and FAQ structures.
- **Content-Aware Embedding Selector**: Automatic model selection (BGE, BGE-M3, Code-specialized, Bio-medical, or Cloud API models) matching input context language and domain.
- **Dynamic Vector DB Routing**: Automatic tier assignment:
  - FAISS CPU for lightweight local datasets (<50MB)
  - ChromaDB for medium local stores (<1GB)
  - Qdrant or Milvus for large-scale distributed deployments (>1GB)
- **Hybrid Dense & Sparse Search**: Reciprocal Rank Fusion (RRF) combining dense vector search and BM25 sparse keyword matching, followed by Cross-Encoder reranking.
- **Incremental Indexing Engine**: Incremental document delta tracking using SHA-256 signatures to update modified files without full re-indexing.
- **Hallucination Verification & Web Fallback**: Grounding verification scoring model calculating source token overlap, triggering optional web search fallback when verification drops below threshold.
- **Embeddable Framework Adapters**: Native integration adapters for FastAPI, Streamlit, LangChain, LlamaIndex, and Flask applications.

---

## Installation & Setup

```bash
pip install mzero-rag
```

To include framework optional dependencies (e.g. Streamlit, vector storage backends):

```bash
# Install with Streamlit support
pip install mzero-rag[streamlit]

# Install full enterprise bundle
pip install mzero-rag[full]
```

### Google Colab Guide

For step-by-step instructions on running `mzero` inside Google Colab (including Google Drive mounting, token streaming, and exposing Streamlit via localtunnel), see [COLAB_README.md](file:///d:/Github%20repo/advanced_rag_pipeline/COLAB_README.md).

---

## API Reference & SDK Usage

### Synchronous SDK Usage

```python
from mzero import RAG

# Initialize pipeline pointing to knowledge base directory
rag = RAG(docs_path="./docs")

# Single question retrieval and generation
response = rag.ask("What is the warranty coverage period?")

print("Answer:", response.answer)
print("Confidence Score:", response.confidence)
print("Citations:", response.citations)

# Streaming token response
for token in rag.stream("Summarize section 4 of the documentation"):
    print(token, end="", flush=True)
```

### Custom Provider & API Key Configuration

You can easily instantiate `RAG` with any document folder and API key from any LLM provider (OpenAI, Gemini, NVIDIA, Anthropic, Groq, OpenRouter, etc.), passed directly or resolved automatically from environment variables:

```python
from mzero import RAG

# 1. Direct Initialization with explicit API Key
rag = RAG(
    docs_path="./my_documents",
    llm_provider="openai",        # "openai", "nvidia", "gemini", "anthropic", "groq", "openrouter"
    llm_model="gpt-4o-mini",
    api_key="sk-..."
)

# 2. NVIDIA NIM Example
rag_nvidia = RAG(
    docs_path="./my_documents",
    llm_provider="nvidia",
    llm_model="meta/llama-3.1-70b-instruct",
    api_key="nvapi-..."
)

# 3. Provider specified, API key automatically pulled from environment variable (e.g. GEMINI_API_KEY)
rag_gemini = RAG(
    docs_path="./my_documents",
    llm_provider="gemini"
)

# 4. Zero-config auto-detection (Detects provider & key automatically from environment)
# Scans environment for OPENAI_API_KEY, GEMINI_API_KEY, NVIDIA_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, etc.
rag_auto = RAG(docs_path="./my_documents")
```

### Asynchronous SDK Usage

```python
import asyncio
from mzero import AsyncRAG

async def run_query():
    rag = AsyncRAG(docs_path="./docs")
    response = await rag.aask("How do I initiate a return?")
    print("Answer:", response.answer)

asyncio.run(run_query())
```

---

## Framework Integration Adapters

### Streamlit Integration

Embed an interactive chat UI into any existing Streamlit application.

```python
import streamlit as st
from mzero.adapters.streamlit import render_mzero_chat

st.set_page_config(page_title="mzero Knowledge Base", layout="wide")

# Mount interactive chat component bound to local documents
render_mzero_chat(docs_path="./docs")
```

Run the Streamlit application:

```bash
streamlit run app.py
```

### FastAPI Integration

Mount `mzero` endpoints directly onto a FastAPI app instance:

```python
from fastapi import FastAPI
from mzero.adapters.fastapi import mount_mzero

app = FastAPI(title="Knowledge Base Service")

# Mount /ask, /stream, and /stats endpoints
mount_mzero(app, docs_path="./docs")
```

---

## CLI & Telemetry Dashboard

### Start API Server & Telemetry Dashboard

```bash
mzero serve --port 8000
```

Access the built-in live telemetry dashboard at:
`http://localhost:8000/dashboard`

### CLI Direct Query

```bash
mzero ask "What are the API rate limits?" --docs ./docs
```

---

## Documentation & AI Context

- **Module Architecture Reference**: For a technical breakdown of every package module, parser, chunker, vector DB router, and retriever, see [MODULES.md](file:///d:/Github%20repo/advanced_rag_pipeline/MODULES.md).
- **AI Agent Context & SDK Reference Guide**: For feeding AI assistants (ChatGPT, Claude, Gemini, Cursor, Antigravity) with precise SDK specs, schemas, and rules, see [AI_README.md](file:///d:/Github%20repo/advanced_rag_pipeline/AI_README.md) and [AGENTS.md](file:///d:/Github%20repo/advanced_rag_pipeline/AGENTS.md).

---

## License

MIT License.
