production-rag
A production-ready Python library for Retrieval-Augmented Generation — not a demo. Index documents, ask questions, get answers cited to the exact page, or get an honest refusal when the evidence isn't there.
pip install prod-rag
Quick Start
from rag_core import RAGPipeline, RAGConfig
from rag_core.config import EmbeddingSettings, LLMSettings
config = RAGConfig(
embedding_settings=EmbeddingSettings(
api_key="your-jina-key", # jina.ai — 1M tokens/month free
provider="jina",
),
llm_settings=LLMSettings(
api_key="your-groq-key", # console.groq.com — 30 req/min free
base_url="https://api.groq.com/openai/v1",
model="openai/gpt-oss-20b",
),
)
pipeline = RAGPipeline(config)
# Index a PDF or .txt file
result = pipeline.index_document("paper.pdf")
print(f"Indexed {result.indexed_chunks} chunks")
# Ask a question
answer = pipeline.query("What are the key findings?")
if answer.refused:
print("Not enough evidence to answer.")
else:
print(answer.answer)
for src in answer.sources:
print(f" [{src['index']}] {src['filename']}, page {src['page_number']}")
Or load keys from a .env file and call RAGPipeline() with no arguments — it auto-loads.
Features
- Page-level citations — every
[n]marker resolves to a filename, page number, and similarity score - Honest refusals — below the confidence threshold the LLM is never called; "I don't know" is built in
- PDF and .txt ingestion — PyMuPDF page extraction with encrypted/corrupt file detection
- Content-hash deduplication — re-indexing the same file is a no-op; deleting is clean
- Provider flexibility — Jina embeddings; any OpenAI-compatible LLM (Groq, OpenRouter, OpenAI, Claude, Gemini)
- Embedded or server Qdrant — zero-infrastructure local mode; server mode via
VECTOR_STORE_URL - Standalone — no FastAPI, no web server; use in scripts, notebooks, CLI tools, or any Python app
- Fully typed — PEP 561 compliant (
py.typed), Pydantic validation throughout - Testable — 209 offline tests; fake providers for deterministic unit testing
Installation
# From PyPI
pip install prod-rag
# From source (editable)
pip install -e .
Requires Python 3.11+.
Configuration
All settings load from environment variables. Copy .env.example to .env and fill in your keys:
# Embeddings (required for indexing and querying)
EMBEDDING_API_KEY=your-jina-key
# LLM (required for answer generation)
LLM_API_KEY=your-llm-key
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_MODEL=openai/gpt-oss-20b
# Vector store (optional — defaults to local embedded mode)
# VECTOR_STORE_URL=http://localhost:6333 # uncomment for server mode
Or pass settings explicitly via RAGConfig as shown in the Quick Start.
Supported LLM providers
The LLM layer works with any OpenAI-compatible endpoint. Provider auto-detection is built in:
| Provider | base_url |
Example model |
|---|---|---|
| Groq | https://api.groq.com/openai/v1 |
openai/gpt-oss-20b |
| OpenRouter | https://openrouter.ai/api/v1 |
openai/gpt-4o-mini |
| OpenAI | https://api.openai.com/v1 |
gpt-4o |
| Anthropic Claude | https://api.anthropic.com/v1 |
claude-3-5-sonnet-20241022 |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta |
gemini-1.5-flash |
Project Structure
production-rag/
├── rag_core/ # The library
│ ├── pipeline.py # RAGPipeline — main public entry point
│ ├── config.py # Settings dataclasses (all env-loadable)
│ ├── exceptions.py # Typed domain exceptions
│ ├── ingestion/ # PDF + .txt parsing, dedup, page extraction
│ ├── chunking/ # Recursive splitter with char offsets + lineage
│ ├── embeddings/ # EmbeddingProvider ABC + Jina implementation
│ ├── llm/ # LLMProvider ABC + OpenAI-compat + Claude + Gemini
│ ├── vector_stores/ # Qdrant (embedded and server modes)
│ ├── retrieval/ # Query → top-k ScoredChunks
│ └── generation/ # Numbered-context prompting, citations, refusal
├── frontend/ # Static documentation site (Next.js → Vercel)
├── tests/
│ ├── library/ # Public API tests (RAGPipeline, RAGConfig)
│ └── unit/ # Component tests (chunking, embeddings, LLM, etc.)
├── examples/ # 5 runnable examples
├── docs/
│ ├── PYTHON_LIBRARY_GUIDE.md # Deep-dive architecture and usage guide
│ └── PUBLISHING.md # PyPI release process
└── pyproject.toml
Pipeline
file (PDF/.txt)
→ ingestion (SHA-256 hash, page extraction)
→ chunking (recursive split, char offsets, overlap)
→ embedding (Jina AI, batched with retries)
→ Qdrant (hash-derived point IDs — idempotent)
query
→ embed query
→ top-k vector search
→ score threshold check → refusal if below threshold
→ numbered-context LLM prompt
→ answer with [n] citations
Testing
209 offline tests — deterministic PDF fixtures, in-memory Qdrant, mocked HTTP transports. No test calls a paid API.
# Run all tests
python -m pytest -v
# Library API tests only
python -m pytest tests/library/ -v
# Unit tests only
python -m pytest tests/unit/ -v
# With coverage
python -m pytest --cov=rag_core --cov-report=term-missing
Examples
Five runnable examples in examples/:
| File | What it shows |
|---|---|
01_basic_usage.py |
Quickstart — index a PDF, ask questions |
02_advanced_configuration.py |
Provider customization and settings |
03_citations_and_sources.py |
Working with answer sources |
04_error_handling.py |
Robust error handling patterns |
05_standalone_application.py |
Building a CLI tool with the library |
Documentation
- Python Library Guide — full architecture walkthrough, execution flows, design decisions, extension patterns, debugging tips
- Examples README — guide to running the examples
Roadmap
- Hybrid search (dense + BM25) and reranking
- Retrieval evaluation harness
- Multi-modal support (images, tables in PDFs)
- Claude and Gemini provider support
-
.txtfile ingestion alongside PDF - PEP 561
py.typedmarker - Lazy embedding dimension probe (offline construction)
- 209 offline tests
Contributing
See CONTRIBUTING.md. Core principle: all RAG logic lives in rag_core/ with zero web framework dependencies. Run pytest -v before submitting.
License
MIT — see LICENSE.
Metadata
Release files for prod-rag 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| prod_rag-0.1.1.tar.gz | 32.1 kB | Without provenance | Details for prod_rag-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| prod_rag-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for prod_rag-0.1.1-py3-none-any.whl |
Total release size: 75.3 kB
Release files / prod_rag-0.1.1.tar.gz
| Download URL | prod_rag-0.1.1.tar.gz |
|---|---|
| Size | 32.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
61472de543a5f6f4a07d5652cc68c2f5d65f54765f6c4ff0405b7795aa5b7c5f
|
|
BLAKE2b-256 checksum How to use checksums |
29a9cdc4a590e9f36731cb0dd9f002947185cbd09800b173295d808b87c094cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / prod_rag-0.1.1-py3-none-any.whl
| Download URL | prod_rag-0.1.1-py3-none-any.whl |
|---|---|
| Size | 43.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2de9207f67cbe5a6a9f0adb9df51fcc99b3c9ecd9c9ffd3b14d2c5584a5bfbfe
|
|
BLAKE2b-256 checksum How to use checksums |
018748ce9dea5b2b4f61593646f46c6f8d511426020dddffbb1fac8b66b7d678
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for prod-rag 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.