rag-pipeline

Local-first RAG pipeline with chunking, retrieval, evaluation, and reports.

Thesis: RAG is not a demo until retrieval quality is measurable. This repo keeps chunking, embeddings, vector storage, retrieval, and metrics separate so you can test each part.

Run It In 30 Seconds

python -m pip install -e ".[dev]" && python examples/local_rag_demo.py

No API key is required. The default hash embedder is deterministic and local so the pipeline can run in CI and examples.

Why Care?

• You want to teach or debug RAG without hiding behind hosted APIs.
• You want chunking and retrieval metrics in the same small project.
• You need a testable baseline before swapping in real embeddings.

Components

flowchart LR
    Documents --> Chunker
    Chunker --> Embedder
    Embedder --> VectorStore
    Query --> Embedder
    VectorStore --> Results
    Results --> Evaluation

Loading

Example

from rag_pipeline.pipeline import Pipeline

pipe = Pipeline()
pipe.ingest("safejson rejects duplicate JSON keys.", source="safejson.md")
result = pipe.query("Which project handles duplicate keys?", k=1)
print(result.context)

Correctness Notes

• The in-memory store normalizes vectors and uses cosine similarity.
• Retrieval metrics include precision@k, recall, MRR, and hit rate.
• The hash embedder is deliberately not semantic; it exists for deterministic local tests and demos.

Comparison

Need	Use this	Use a larger RAG stack
Learn the mechanics	Yes	Maybe too much machinery
CI-friendly retrieval tests	Yes	Often requires services
Production vector DB integrations	Not the goal	Yes

Development

python -m pip install -e ".[dev]"
pytest
python scripts/retrieval_report.py

See ARCHITECTURE.md, TECHNICAL_ARTICLE.md, and RELEASE.md.