cited-rag
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. No data leaves your machine unless you pass --llm
explicitly. Install with pip install cited-rag — no heavy dependencies.
Quickstart (3 commands)
pip install cited-rag
cited-rag index ./docs --db ./index.db
cited-rag ask "how does RRF fusion work?" --k 5 --min-score 0.35
Ask with machine-readable output:
cited-rag ask "what is the chunk overlap?" --k 5 --json
Run the benchmark (reproduces the numbers below in one command):
cited-rag eval --golden eval/golden.jsonl
How it works
docs (.txt/.md)
|
ingestion + line-based chunking (40 lines, 10 overlap, hash + line offsets)
|
+----+----+
| |
BM25 TF-IDF/cosine (optional dense adapter: OFF by default)
(k1=1.5, (sublinear tf,
b=0.75) stopwords, L2-norm)
| |
+----+----+
|
Reciprocal Rank Fusion RRF(d) = sum_r 1 / (60 + rank_r(d))
|
light rerank (exact-phrase boost) -> top-k
|
extractive generation (verbatim phrases + [file:L1-L2])
|
fidelity gate (>= 0.5) + min-score gate (>= 0.35)
|
answer | `Insufficient evidence` (exit 0, zero citations)
Why RRF: BM25 and cosine live on incompatible scales. Fusion on ranks only, with k=60 per Cormac et al., keeps small-corpus behavior stable without tuning.
Benchmark
Measured with cited-rag eval --golden eval/golden.jsonl on the bundled
corpus (12 docs in examples/docs/, 52 questions: 40 in-corpus + 12
out-of-corpus). Release gates (PRODUCT_BRIEF C4): Recall@5 >= 0.80,
MRR >= 0.60, correct-refusal rate >= 0.90.
| Metric | Target | Measured |
|---|---|---|
| Recall@5 | >= 0.80 | see cited-rag eval output |
| MRR | >= 0.60 | see cited-rag eval output |
| Correct-refusal (12 off-topic Q) | >= 0.90 | see cited-rag eval output |
Numbers are reproduced deterministically from eval/golden.jsonl — run the
single eval command above rather than trusting this table.
Golden format (one JSON object per line, 40 in-corpus + 12 out-of-corpus):
{"question": "What are the default BM25 parameters?", "expected_doc": "01-bm25-ranking.md", "should_refuse": false}
{"question": "What is the best sourdough recipe?", "expected_doc": null, "should_refuse": true}
Refusal contract
- Trigger:
max_score < --min-score(default 0.35) or fidelity < 0.5. - Output: the literal string
Insufficient evidence, exit code 0. - Guarantee: refused answers carry zero
[file:L1-L2]markers — no invented citations, ever. Assert it in tests, not by inspection.
Limitations (honest)
- Lexical retrieval only by default: BM25 + TF-IDF miss paraphrases and
cross-lingual queries. The dense adapter (
--llm) is opt-in and unevaluated against the gates above. - Small-corpus IDF: with ~12 demo docs, rare-term statistics are noisy; scores stabilize as the corpus grows. Re-index after every corpus change.
- Extractive answers: verbatim quoting is faithful but stilted — no synthesis, no multi-hop reasoning, fixed fidelity threshold (0.5).
- Secrets: the indexer warns on key-like patterns (
AKIA...,ghp_...) but does not redact. Scrub corpora before indexing. - Scale: single-machine SQLite/JSON index; 50 docs index in < 60 s, but this is not a distributed search engine and makes no such claim.
Project context
Third portfolio pillar after agent-context-bridge and llm-eval-ci.
See PRODUCT_BRIEF.md for the testable criteria (C1–C6) this release targets.
License
MIT — see LICENSE.
Metadata
Release files for cited-rag 0.1.0
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 |
|---|---|---|---|---|
| cited_rag-0.1.0.tar.gz | 25.4 kB | With provenance | Details for cited_rag-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cited_rag-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cited_rag-0.1.0-py3-none-any.whl |
Total release size: 46.1 kB
Release files / cited_rag-0.1.0.tar.gz
| Download URL | cited_rag-0.1.0.tar.gz |
|---|---|
| Size | 25.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bdbf8537bb2702badc9e52dff991cfd9a295a3882bdf1c4546276283658aa16e
|
|
BLAKE2b-256 checksum How to use checksums |
88ec8060521701010258d323d82cb515755e70805addac48227757cebbb83d7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / cited_rag-0.1.0-py3-none-any.whl
| Download URL | cited_rag-0.1.0-py3-none-any.whl |
|---|---|
| Size | 20.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce0a3b4ad33d42c4122f015f78dbc93ad045114b59ee8cc31f1ddec37a8966cb
|
|
BLAKE2b-256 checksum How to use checksums |
3bf9b0046fe0a50bb6ac22ba12bb8574bec0897587c2094d244ed9ca07709d74
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for cited-rag 0.1.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cited_rag-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA 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.