Skip to main content

cited-rag

CI Python 3.12+ License: MIT offline

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)

Source distribution for cited-rag 0.1.0
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)

Table of built distributions (wheels) for cited-rag 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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