Local RAG you can trust. Zero hallucination by design: every claim is cited ([file:L1-L2]) or the answer is refused with Insufficient evidence. Stdlib-only, offline-first.
One command reproduces every number below from the bundled golden set — run it, don't trust this table:
pip install cited-rag
cited-rag index ./docs --db ./index.db
cited-rag eval --golden eval/golden.jsonl
examples/docs/) — BM25/RFF tuning notes, chunking, CLI, fidelity, refusal, eval-metrics, LLM adapter, security, offline-portfolio.eval/golden.jsonl, n = 52 questions — 40 in-corpus (should_refuse: false, each mapped to an expected_doc) + 12 out-of-corpus (should_refuse: true: sport, cuisine, médecine, histoire…).dependencies = []), pure offline (no socket/urllib outside the opt-in adapter).[file:Lstart-Lend] offsets; refusal trigger max_score < --min-score (default 0.35) or fidelity < 0.5; refused answers carry zero citations, exit 0.| Metric | Gate (C4) | Measured | Verdict |
|---|---|---|---|
| Recall@5 | ≥ 0.80 | 1.00 | PASS |
| MRR | ≥ 0.60 | 0.93 | PASS |
| Correct-refusal (off-topic) | ≥ 0.90 | 1.00 (12/12) | PASS |
| n (golden) | ≥ 50 Q/A | 52 (40 + 12) | PASS |
| pytest | green | 70 passed (v0.1.1; 59 at QA baseline) | PASS |
| Index perf | < 60 s / 50 docs | 12 docs in ~0.4 s * | PASS * |
| Gate | Requirement | Evidence | Verdict |
|---|---|---|---|
| C1 offline stdlib-only | index + ask, no external dep | dependencies = []; index+ask OK offline | PASS |
| C2 exact citations | 100% claims cited, exact offsets | 3/3 phrases verbatim [01-bm25-ranking.md:L1-L20], fidelity 1.00 | PASS |
| C3 refusal | Insufficient evidence, exit 0, no invented citations | 12/12 off-topic → refusal | PASS |
| C4 eval | Recall@5 ≥ 0.80, MRR ≥ 0.60, refusal ≥ 0.90, ≥ 50 Q/A | 1.00 / 0.93 / 1.00, n = 52 | PASS |
| C5 LLM OFF by default | opt-in --llm only, citation format unchanged | store_true, default=False; no network outside adapter | PASS |
| C6 tests + perf + docs | pytest green, index < 60 s, 3-command quickstart | 59 passed (QA) / 70 on v0.1.1 / 0.4 s / README quickstart | PASS * |
--llm) is opt-in and unevaluated against the gates above.AKIA…, ghp_…) but does not redact — scrub corpora before indexing.PyPI · cited-rag v0.1.1 (70 tests)pip install cited-rag
GitHub · shenn667/cited-rag
CI badge, MIT, Trusted Publishing (no stored token).
git clone https://github.com/shenn667/cited-rag.git
cd cited-rag
pip install cited-rag # or: pip install -e .
cited-rag index examples/docs
cited-rag ask "What are the default BM25 parameters?" --k 5
cited-rag ask "What is the best sourdough recipe?" --k 5 # -> Insufficient evidence
cited-rag eval --golden eval/golden.jsonl
# expected: Recall@5=1.00 MRR=0.93 correct-refusal=1.00 (12/12) n=52