Project description
attune-rag
Lightweight, LLM-agnostic RAG pipeline with pluggable
corpora. Works with Claude, Gemini, or any LLM.
🌐 Docs & guides: attune-rag.dev
Proven retrieval — the numbers
Every figure is reproducible with attune-rag-benchmark. The bundled-corpus
row is a hard CI gate — a PR that regresses it fails automatically.
इससे जुड़ी जानकारी
| Bundled corpus¹ | Unseen corpus, overall² | Unseen corpus, hard paraphrases³ | |
|---|---|---|---|
| precision@1 | 100% | 73% (lightweight, zero torch) | 25% lightweight → 90% transformer tier |
| recall@3 | 100% | 82% (lightweight, zero torch) | 25% lightweight → 100% transformer tier |
| faithfulness | 0.97 mean | — | — |
Plus: configurable abstention drops out-of-corpus false answers from
92% → 8% — so the retriever stays quiet instead of confidently wrong.
The headline: on a corpus attune-rag has never seen or been tuned on,
asking questions worded nothing like the docs, the transformer tier goes
from a keyword baseline of 1-in-4 to 9-in-10 top-1 correct, and
finds the right doc in the top 3 every single time (recall@3 100%).
¹ bundled attune-help corpus, gated in CI at P@1 ≥ 0.95 / R@3 = 1.00 / faithfulness ≥ 0.9686; actuals shown. ² lightweight keyword on an unseen
corpus (corpus_b), no embeddings. ³ pure-paraphrase stress test
(corpus_c, queries with almost no vocabulary overlap with the docs) —
measured in docs/specs/transformer-retriever/.
Two ways to run it
🪶 Lightweight (default). Keyword retrieval, optionally fused with
torch-free static embeddings (pip install attune-rag[embeddings]).
5 pure-Python deps, no LLM SDK, no torch, fully offline, ~1 ms/query —
the dependency-light path that holds 100% / 100% on a tuned corpus
and 73% precision@1 on an unseen one.🤖 Transformer tier (opt-in). Real sentence-transformers embeddings
(pip install attune-rag[transformers]) for paraphrase-heavy or arbitrary
corpora. On pure-paraphrase queries it lifts precision@1 25% → 90% and
recall@3 25% → 100% — the generalization no torch-free retriever
reaches. Heavyweight (pulls torch, ~GB); embedding-primary; never a default.No LLM SDK at install time; footprint scales with your setup.
The base install pulls 5 small pure-Python deps (structlog,
jinja2,pyyaml,rich,jsonschema) — no LLM SDK, no torch.
Retrieval tiers add only what they need:[embeddings]adds
torch-freemodel2vec;[transformers]adds the torch stack. You
pay for exactly the setup you choose.Pluggable corpus. Use attune-help (the default), any
markdown directory, or your ownCorpusProtocol.Returns a prompt string + citation records by default
—pipeline.run()never opens a network connection. You
call your own LLM however you like. Optional provider
adapters ship convenience wrappers.Opt-in retrieval ladder. Keyword retrieval by default;
add a torch-free static-embeddingHybridRetriever
([embeddings]) or aTransformerRetriever([transformers])
for paraphrase-heavy corpora, plus configurable abstention
(min_score=) to suppress confident out-of-corpus answers.
Every rung is opt-in and fail-safe; the keyword default is
unchanged.
Why attune-rag
Most RAG libraries ship features. attune-rag ships measured
quality numbers and gates merges against them. The CI badge
isn’t “tests pass” — it’s P@1 ≥ 0.95, R@3 = 1.00, mean faithfulness ≥ 0.9686 (locked at
docs/specs/release-quality-baseline/baseline-1.md)
plus per-axis CPU + wall-clock perf thresholds (locked at
docs/specs/downstream-validation/perf-baseline.md).
A PR that drops mean_faithfulness below 0.9686 fails CI
automatically. Same for any latency hot-path regressing past
mean + 2σ. That’s the differentiator.
vs LangChain / LlamaIndex
| attune-rag | LangChain | LlamaIndex | |
|---|---|---|---|
| Required runtime deps | 5 (pure-Python) | many (transitively, ~30+) | many (~25+) |
| LLM SDK at install | none | bundled | bundled |
| Published quality regression thresholds | yes (P@1, R@3, faithfulness) | no | no |
| Published perf thresholds (wall + CPU) | yes | no | no |
| Citation primitives built-in | yes | add-on | add-on |
| “Get a string back, call your own LLM” | default | possible w/ effort | possible w/ effort |
LangChain and LlamaIndex are fantastic frameworks if you want
batteries-included orchestration. attune-rag is the alternative
when you want a RAG component you can drop into an existing app
without buying into a framework — and want the quality bar
quantified, not implied.
Beyond drop-in retrieval, attune-rag is the grounding foundation
for the attune-* family’s content-quality discipline. The
attune-author polish/fact-check pipeline uses attune-rag’s
retrieval + faithfulness primitives to verify generated help
content is grounded in source material before it’s marked
authoritative — the same mean_faithfulness ≥ 0.9686 discipline
that gates this library’s own benchmarks, extended to the
authoring loop.
What attune-rag is not
Honest exclusions, so you can self-disqualify if you need any
of these:
- Not an agent framework. No multi-step chains, no tool-use
orchestration, no agent loops. - Not a document-parsing toolkit. Bring your markdown
already-parsed; useunstructured.ioor similar upstream. - Not a vector DB integration. Keyword retrieval is the
default; the optional[embeddings]/[transformers]tiers
embed in-process (model2vec / sentence-transformers). There is
no external vector-store integration — you wire your own if
you need one. - Not a one-line-install batteries-included framework. That’s
LangChain / LlamaIndex. attune-rag is for the case where that’s
too much.
Install
pip install attune-rag # core — keyword retrieval, 5 pure-Python deps, no LLM SDK
# Retrieval tiers (opt-in):
pip install 'attune-rag[embeddings]' # + torch-free static hybrid retrieval
pip install 'attune-rag[transformers]' # + transformer retrieval tier (pulls torch, ~GB)
# Corpus & LLM adapters (opt-in):
pip install 'attune-rag[attune-help]' # + bundled help corpus
pip install 'attune-rag[claude]' # + Claude adapter
pip install 'attune-rag[gemini]' # + Gemini adapter
# Convenience:
pip install 'attune-rag[all]' # every extra, incl. the transformer tier (pulls torch, ~GB)
Extras compose, e.g. <code…
Leave a Reply