v0.5.0 — retrieval-capabilities release

The retrieval-capabilities release. A full opt-in retrieval ladder lands on top of the keyword default — static hybrid, configurable abstention, and a heavyweight transformer tier — each measured against an unseen-corpus benchmark and shipped without changing any default.

Upgrading from 0.2.0: zero breaking changes. The base install and the keyword retriever behave exactly as before. Everything new is opt-in via extras.

Added

• Static hybrid retrieval (pip install attune-rag[embeddings], torch-free) — EmbeddingRetriever + HybridRetriever (weighted RRF, keyword-favoring default, graceful keyword-only fallback). +9pts recall@3 on an unseen corpus; tuned-corpus default path unchanged.
• Configurable abstention — KeywordRetriever(min_score=) returns nothing when every candidate is weak, instead of surfacing a likely-wrong match. New attune-rag-benchmark --calibrate-abstention recommends a per-corpus threshold. Measured: bundled false-answer rate 92% → 8% for a 2pt legit-recall cost. Default unchanged (opt-in).
• Transformer retrieval (pip install attune-rag[transformers], heavyweight opt-in) — TransformerRetriever (default BAAI/bge-small-en-v1.5) with an asymmetric query_prefix hook. For arbitrary, paraphrase-heavy corpora: hard-tier paraphrase precision@1 ≈0.50 → 0.85–0.90, recall@3 → 1.00 on two unseen corpora — the one goal no torch-free retriever reaches. sentence_transformers is lazily imported; base install unaffected.
• Generalization benchmark track — --corpus / --corpus-queries measure retrieval against an unseen second corpus (reported as generalization, advisory).

Changed

• CI enforces uv.lock matches pyproject.toml (new lockfile workflow) — closes a silent dependency-drift gap.
• Corpus-quality guide §6.4 ("Wiring into CI") hardened into a standing-guard recipe gating on both P@1 and R@3 watermarks. Docs-only.

Quality (gated in CI)

Bundled corpus P@1 100% / R@3 100%; generalization P@1 72.7% (gate 70%). Full test suite green; sdist + wheel twine check clean.

Install

pip install attune-rag            # keyword default, dependency-light
pip install attune-rag[embeddings]   # + torch-free static hybrid
pip install attune-rag[transformers] # + heavyweight transformer tier

Docs & guides: https://attune-rag.dev