Skip to main content

production-rag

PyPI version Tests Python 3.11+ License: MIT

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
  • .txt file ingestion alongside PDF
  • PEP 561 py.typed marker
  • 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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for prod-rag 0.1.2
File Size Uploaded Provenance Actions
prod_rag-0.1.2.tar.gz 32.4 kB Without provenance Details for prod_rag-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for prod-rag 0.1.2
File Interpreter ABI Platform Actions
prod_rag-0.1.2-py3-none-any.whl Python 3 none any Details for prod_rag-0.1.2-py3-none-any.whl

Total release size: 76.1 kB

Release files / prod_rag-0.1.2.tar.gz

Download URL prod_rag-0.1.2.tar.gz
Size 32.4 kB
Tags Source
SHA-256 checksum
How to use checksums
72cbe0888f2391a75c80f1d80b4f7916828defe5686f25b6469044b9d5038c4a
BLAKE2b-256 checksum
How to use checksums
6d5126ee28fd4c86f31cd7459eb41fe825b0d80b77473cb3b05c5224263c6f64
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.2-py3-none-any.whl

Download URL prod_rag-0.1.2-py3-none-any.whl
Size 43.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
64c4df057087f65d15bf211e8eff9222120aa8db10509e946d581a7a4254201c
BLAKE2b-256 checksum
How to use checksums
213296b4ab767b33964af7a21237977607b393a0e305b9d3b5fc7b9d05cc4b84
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.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page