Metadata-Version: 2.4
Name: ezrag-engine
Version: 0.1.0
Summary: A 3-line, zero-boilerplate, cloud-ready RAG pipeline for Python and Hugging Face Spaces.
Author-email: Oguru Vinay Reddy <Vinayreddy.ace@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://huggingface.co/
Project-URL: Repository, https://github.com/<your-github-username>/ezrag
Project-URL: Documentation, https://github.com/<your-github-username>/ezrag#readme
Keywords: rag,llm,retrieval-augmented-generation,huggingface,embeddings,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: huggingface_hub>=0.23.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: requests>=2.31.0
Requires-Dist: litellm>=1.40.0

<div align="center">

# **ezrag** — 3-Line, Zero-Boilerplate, Cloud-Ready RAG

**A production-grade Retrieval-Augmented Generation framework for Python and Hugging Face Spaces.**

![PyPI](https://img.shields.io/pypi/v/ezrag.svg)
![Python](https://img.shields.io/pypi/pyversions/ezrag.svg)
![PyPI - License](https://img.shields.io/pypi/l/ezrag.svg)

</div>

---

## Why ezrag?

Most RAG stacks take hours to wire up: embedding models, vector stores, chunkers,
prompts, and LLM clients. ezrag hides all of that behind one class, so you go from
an empty folder to a **grounded, citation-aware answer** in exactly three lines of
code.

**What you get out of the box:**

- **Chunking** — sentence-aware splitting with a sliding overlap, zero configuration
- **Embeddings** — a lightweight `sentence-transformers` model, loaded lazily
- **Vector DB** — a self-contained in-memory store with fast NumPy cosine search
- **Context bundling** — evidence is ranked, tagged `[1] [2] [3] ...` and injected into the prompt
- **LLM execution** — unified calls through the Hugging Face Serverless API or LiteLLM
- **Weak-evidence guard** — answers truthfully when the documents do not cover the question

## Installation

```bash
pip install ezrag
```

## Quick Start

That is the entire experience — import, load, ask:

```python
from ezrag import EZRAG                     # 1. import

rag = EZRAG().load(SOURCE)                  # 2. initialise + load your source
print(rag.ask("Your question here"))        # 3. ask — grounded, cited answer
```

No environment variables to set up, no vector database to spin up, no prompting
prompts to craft. One object call chain produces a grounded, cited answer.

## Configuration

| Parameter | Default | Purpose |
| --- | --- | --- |
| `llm` | `mistralai/Mistral-7B-Instruct-v0.2` | LLM identifier or endpoint |
| `embedding_model` | `all-MiniLM-L6-v2` | sentence-transformers model |
| `provider` | `"hf"` | `"hf"` (HF Serverless) or `"litellm"` |
| `hf_token` | env `HF_TOKEN` | token for protected / gated models |
| `top_k` | `4` | number of evidence chunks retrieved |
| `min_score` | `0.10` | retrieval similarity floor |
| `chunk_size` | `900` | target chunk length (characters) |
| `chunk_overlap` | `120` | sliding context overlap |

## Providers

- **Hugging Face Serverless** (default) — no custom API wiring. Set the `HF_TOKEN`
  environment variable only when the model is gated.
- **LiteLLM** — point `llm` at any OpenAI-compatible endpoint, for example
  `openai/gpt-4o` or `azure/gpt-4o`.

## How It Works

```
  source ──▶ chunk ──▶ embed ──▶ in-memory index
                                       │
  question ──▶ embed ──▶ top-k search ──┘
                                       │
                      context bundle ──▶ LLM ──▶ cited answer
```

## Hugging Face Spaces

ezrag runs out of the box in a Hugging Face Space — pip pulls in every runtime
dependency automatically. Store a `HF_TOKEN` Space secret if your chosen model is
gated.

## License

MIT © Oguru Vinay Reddy
