rerankgate 0.2.0__py3-none-any.whl

rerankgate/judge.py

@@ -0,0 +1,88 @@
+"""Faithfulness judges: heuristic default, LLM-backed opt-in."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from rerankgate.retrieval import ScoredChunk
+from rerankgate.tokenize import content_tokens
+
+_SENT = re.compile(r"(?<=[.!?])\s+")
+
+
+@dataclass
+class FaithfulnessReport:
+    score: float  # mean per-sentence grounding, [0,1]
+    unsupported: list[str] = field(default_factory=list)  # sentences below the floor
+    per_sentence: list[dict] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "score": round(self.score, 4),
+            "unsupported": self.unsupported,
+            "per_sentence": self.per_sentence,
+        }
+
+
+class Judge(Protocol):
+    name: str
+
+    def check(self, answer: str, evidence: list[ScoredChunk]) -> FaithfulnessReport: ...
+
+
+class HeuristicJudge:
+    """Ground every answer sentence in the evidence via token-overlap F1.
+
+    A sentence is 'supported' if some evidence chunk shares enough content
+    tokens (F1 >= 0.35 by default). Heuristic — documented as such — but
+    free, instant, and dependency-free.
+    """
+
+    name = "heuristic"
+
+    def __init__(self, support_floor: float = 0.35) -> None:
+        self.support_floor = support_floor
+
+    def check(self, answer: str, evidence: list[ScoredChunk]) -> FaithfulnessReport:
+        sentences = [s.strip() for s in _SENT.split(answer.strip()) if s.strip()]
+        ev_sets = [set(content_tokens(c.chunk.text)) for c in evidence]
+        per_sentence: list[dict] = []
+        unsupported: list[str] = []
+        for s in sentences:
+            s_toks = set(content_tokens(s))
+            best = 0.0
+            for ev in ev_sets:
+                if not s_toks or not ev:
+                    continue
+                inter = s_toks & ev
+                prec = len(inter) / len(s_toks)
+                rec = len(inter) / len(ev)
+                f1 = 2 * prec * rec / (prec + rec) if (prec + rec) else 0.0
+                best = max(best, f1)
+            per_sentence.append({"sentence": s, "grounding": round(best, 4)})
+            if best < self.support_floor:
+                unsupported.append(s)
+        if per_sentence:
+            score = sum(p["grounding"] for p in per_sentence) / len(per_sentence)
+        else:
+            score = 0.0
+        return FaithfulnessReport(
+            score=round(score, 4), unsupported=unsupported, per_sentence=per_sentence
+        )
+
+
+class LLMJudge:
+    """Wrap any callable as a model-based judge: fn(answer, evidence_texts) -> float in [0,1]."""
+
+    name = "llm"
+
+    def __init__(self, fn: Callable[[str, list[str]], float]) -> None:
+        self._fn = fn
+
+    def check(self, answer: str, evidence: list[ScoredChunk]) -> FaithfulnessReport:
+        score = float(self._fn(answer, [c.chunk.text for c in evidence]))
+        score = max(0.0, min(1.0, score))
+        return FaithfulnessReport(score=round(score, 4))

rerankgate/metrics.py

@@ -0,0 +1,106 @@
+"""Evaluation aggregates: retrieval metrics + gate confusion matrix."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class EvalItem:
+    query: str
+    relevant_ids: list[str]  # chunk or doc ids considered relevant
+    answerable: bool = True
+
+
+def _match(ids: list[str], relevant: set[str]) -> bool:
+    # A retrieved chunk matches if its id or its doc id is in the relevant set.
+    for i in ids:
+        if i in relevant or i.split("#c")[0] in relevant:
+            return True
+    return False
+
+
+@dataclass
+class EvalReport:
+    n: int = 0
+    recall_at_k: dict[int, float] = field(default_factory=dict)
+    mrr: float = 0.0
+    gate_precision: float = 0.0  # of gate-PASS, fraction actually answerable
+    gate_recall: float = 0.0  # of answerable, fraction gate passed
+    abstention_rate: float = 0.0  # fraction verdict == insufficient
+    answerable_rate: float = 0.0  # fraction verdict == answerable
+    per_query: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "n": self.n,
+            "recall_at_k": {str(k): round(v, 4) for k, v in self.recall_at_k.items()},
+            "mrr": round(self.mrr, 4),
+            "gate_precision": round(self.gate_precision, 4),
+            "gate_recall": round(self.gate_recall, 4),
+            "abstention_rate": round(self.abstention_rate, 4),
+            "answerable_rate": round(self.answerable_rate, 4),
+            "per_query": self.per_query,
+        }
+
+
+def aggregate(
+    items: list[EvalItem],
+    results: list[dict],
+    ks: tuple[int, ...] = (1, 3, 5, 10),
+) -> EvalReport:
+    """Aggregate per-query pipeline results into retrieval + gate metrics.
+
+    Each result dict must have: `retrieved_ids` (ranked chunk ids),
+    `verdict` ("answerable"|"insufficient"|"needs_review").
+    """
+    rep = EvalReport(n=len(items))
+    if not items:
+        return rep
+    # Retrieval metrics are computed over answerable items only (those with
+    # labeled relevant ids); the gate confusion matrix covers all items.
+    retrievable = [(it, rs) for it, rs in zip(items, results, strict=True) if it.relevant_ids]
+    hits = dict.fromkeys(ks, 0)
+    rr_sum = 0.0
+    tp = fp = fn = 0  # gate PASS vs labeled answerable
+    abstentions = 0
+    answerable_out = 0
+    for item, res in zip(items, results, strict=True):
+        verdict = res.get("verdict")
+        passed = verdict == "answerable"
+        if verdict == "insufficient":
+            abstentions += 1
+        if passed:
+            answerable_out += 1
+        if passed and item.answerable:
+            tp += 1
+        elif passed and not item.answerable:
+            fp += 1
+        elif not passed and item.answerable:
+            fn += 1
+        rep.per_query.append(
+            {
+                "query": item.query,
+                "verdict": verdict,
+                "expected_answerable": item.answerable,
+                "retrieved_ids": res.get("retrieved_ids", [])[: max(ks)],
+            }
+        )
+    for item, res in retrievable:
+        rel = set(item.relevant_ids)
+        ranked = res.get("retrieved_ids", [])
+        for k in ks:
+            if _match(ranked[:k], rel):
+                hits[k] += 1
+        for rank, cid in enumerate(ranked, start=1):
+            if cid in rel or cid.split("#c")[0] in rel:
+                rr_sum += 1.0 / rank
+                break
+    denom = len(retrievable) or 1
+    rep.recall_at_k = {k: hits[k] / denom for k in ks}
+    rep.mrr = rr_sum / denom
+    rep.gate_precision = tp / (tp + fp) if (tp + fp) else 0.0
+    rep.gate_recall = tp / (tp + fn) if (tp + fn) else 0.0
+    rep.abstention_rate = abstentions / len(items)
+    rep.answerable_rate = answerable_out / len(items)
+    return rep

rerankgate/pipeline.py

@@ -0,0 +1,301 @@
+"""RAGPipeline: retrieve -> rerank -> gate -> rewrite/retry -> verdict."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from time import perf_counter
+from typing import Literal
+
+from rerankgate.bm25 import BM25Index
+from rerankgate.config import PipelineConfig
+from rerankgate.documents import Chunk, Document, chunk_text
+from rerankgate.embeddings import EmbeddingBackend, SentenceTransformerBackend
+from rerankgate.gate import GateDecision, SufficiencyGate
+from rerankgate.judge import FaithfulnessReport, HeuristicJudge, Judge
+from rerankgate.metrics import EvalItem, aggregate
+from rerankgate.rerank import FeatureReranker, Reranker
+from rerankgate.retrieval import HybridRetriever, RetrievalResult, ScoredChunk
+from rerankgate.rewrite import RM3Rewriter
+from rerankgate.store import DocumentStore
+from rerankgate.vectorstore import VectorStore
+
+ANSWERABLE = "answerable"
+INSUFFICIENT = "insufficient"
+NEEDS_REVIEW = "needs_review"
+
+Verdict = Literal[ANSWERABLE, INSUFFICIENT, NEEDS_REVIEW]  # type: ignore[valid-type]
+
+
+@dataclass
+class AttemptRecord:
+    query: str
+    retrieval_metrics: dict
+    gate: dict
+    evidence_ids: list[str]
+    rewrite: str | None = None
+
+
+@dataclass
+class AnswerResult:
+    verdict: Verdict
+    query: str
+    evidence: list[ScoredChunk]
+    gate: GateDecision
+    attempts: list[AttemptRecord] = field(default_factory=list)
+    answer: str | None = None
+    faithfulness: FaithfulnessReport | None = None
+    trace: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "verdict": self.verdict,
+            "query": self.query,
+            "evidence": [
+                {
+                    "chunk_id": c.chunk.id,
+                    "doc_id": c.chunk.doc_id,
+                    "score": round(c.score, 4),
+                    "text": c.chunk.text,
+                    "sources": c.sources,
+                }
+                for c in self.evidence
+            ],
+            "gate": self.gate.to_dict(),
+            "attempts": [
+                {
+                    "query": a.query,
+                    "retrieval_metrics": a.retrieval_metrics,
+                    "gate": a.gate,
+                    "evidence_ids": a.evidence_ids,
+                    "rewrite": a.rewrite,
+                }
+                for a in self.attempts
+            ],
+            "answer": self.answer,
+            "faithfulness": self.faithfulness.to_dict() if self.faithfulness else None,
+            "trace": self.trace,
+        }
+
+
+class RAGPipeline:
+    """Drop-in retrieval pipeline with a sufficiency gate.
+
+    If the retrieval wasn't good enough, the answer never gets generated:
+    `ask()` returns verdict="insufficient" and abstains instead of
+    handing weak evidence to an LLM.
+    """
+
+    def __init__(
+        self,
+        config: PipelineConfig | None = None,
+        embeddings: EmbeddingBackend | None = None,
+        reranker: Reranker | None = None,
+        judge: Judge | None = None,
+    ) -> None:
+        self.config = config or PipelineConfig()
+        self.bm25 = BM25Index()
+        self.chunks: list[Chunk] = []
+        self.reranker: Reranker = reranker or FeatureReranker()
+        self.judge: Judge = judge or HeuristicJudge()
+        self.gate = SufficiencyGate(self.config.effective_gate())
+        self.rewriter = RM3Rewriter(expansion_terms=self.config.retry.expansion_terms)
+        self.faithfulness_floor = 0.35
+
+        self.embeddings: EmbeddingBackend | None = None
+        self.vector_store: VectorStore | None = None
+        self.degraded_reason: str | None = None
+        if self.config.use_vectors:
+            if embeddings is not None:
+                self._enable_vectors(embeddings)
+            else:
+                try:
+                    self._enable_vectors(SentenceTransformerBackend())
+                except RuntimeError as exc:
+                    self.degraded_reason = str(exc)
+                    warnings.warn(
+                        "rerankgate: embeddings unavailable, running BM25-only. "
+                        "Install with `pip install rerankgate[local]` for hybrid mode.",
+                        stacklevel=2,
+                    )
+
+    def _enable_vectors(self, backend: EmbeddingBackend) -> None:
+        self.embeddings = backend
+        self.vector_store = VectorStore(dim=backend.dim)
+
+    # -- ingestion -----------------------------------------------------
+    def ingest(self, documents: list[Document]) -> int:
+        """Chunk, index, and embed documents. Returns chunk count added."""
+        new_chunks: list[Chunk] = []
+        for doc in documents:
+            new_chunks.extend(
+                chunk_text(
+                    doc.text,
+                    doc_id=doc.id,
+                    size=self.config.chunk_size,
+                    overlap=self.config.chunk_overlap,
+                    metadata=doc.metadata,
+                )
+            )
+        self.chunks.extend(new_chunks)
+        self.bm25.add(new_chunks)
+        if self.embeddings is not None and self.vector_store is not None:
+            vecs = self.embeddings.embed([c.text for c in new_chunks])
+            self.vector_store.add(new_chunks, vecs)
+        return len(new_chunks)
+
+    def save(self, path: str) -> None:
+        vectors: list[list[float]] | None = None
+        if self.vector_store is not None:
+            vectors = self.vector_store.vectors
+        DocumentStore(path).save(
+            self.chunks,
+            vectors,
+            meta={"embedding": self.embeddings.name if self.embeddings else None},
+        )
+
+    @classmethod
+    def load(
+        cls,
+        path: str,
+        config: PipelineConfig | None = None,
+        embeddings: EmbeddingBackend | None = None,
+    ) -> RAGPipeline:
+        """Load a persisted store and rebuild indexes."""
+        store = DocumentStore(path)
+        chunks, vectors, meta = store.load()
+        pipe = cls(config=config, embeddings=embeddings)
+        # If the store has vectors but this process has no embedding backend
+        # (e.g. sentence-transformers missing), stay BM25-only: retrieval
+        # still works, quality just degrades gracefully.
+        if vectors and pipe.vector_store is not None and pipe.embeddings is not None:
+            if len(vectors) == len(chunks) and len(vectors[0]) == pipe.embeddings.dim:
+                pipe.vector_store.add(chunks, vectors)
+            # else: dim mismatch (different model) -> fall back to re-embed
+            # lazily on next ingest; existing vectors are not trusted.
+        pipe.chunks = chunks
+        pipe.bm25.add(chunks)
+        if vectors and (pipe.vector_store is None or len(pipe.vector_store) == 0):
+            # Re-embed with the current backend if dims allow.
+            if pipe.embeddings is not None:
+                pipe.vector_store = VectorStore(dim=pipe.embeddings.dim)
+                pipe.vector_store.add(chunks, pipe.embeddings.embed([c.text for c in chunks]))
+        return pipe
+
+    # -- querying ------------------------------------------------------
+    def _retriever(self) -> HybridRetriever:
+        retr = HybridRetriever(
+            self.bm25,
+            vector_store=self.vector_store,
+            embeddings=self.embeddings,
+            rrf_k=self.config.rrf_k,
+            bm25_weight=self.config.bm25_weight,
+            vector_weight=self.config.vector_weight,
+        )
+        retr.degraded = self.degraded_reason
+        return retr
+
+    def retrieve(self, query: str, k: int | None = None) -> RetrievalResult:
+        return self._retriever().retrieve(query, k=k or self.config.retrieve_k)
+
+    def ask(
+        self,
+        query: str,
+        generator: Callable[[str, list[ScoredChunk]], str] | None = None,
+        gate_override: bool = False,
+    ) -> AnswerResult:
+        """Run retrieve -> rerank -> gate, with rewrite retries, then verdict.
+
+        If `generator` is given and the gate passes, the generated answer is
+        faithfulness-checked; a failing check flips the verdict to needs_review.
+
+        `gate_override=True` is the escape hatch for suspected gate false
+        negatives: the best evidence is returned as answerable regardless of
+        the gate, and the override is recorded in the trace.
+        """
+        t0 = perf_counter()
+        cfg = self.config
+        attempts: list[AttemptRecord] = []
+        best: tuple[float, list[ScoredChunk], GateDecision, str] | None = None
+        current_query = query
+
+        for attempt in range(cfg.retry.max_retries + 1):
+            retrieval = self._retriever().retrieve(current_query, k=cfg.retrieve_k)
+            reranked = self.reranker.rerank(current_query, retrieval.chunks, k=cfg.rerank_k)
+            decision = self.gate.evaluate(current_query, reranked)
+            attempts.append(
+                AttemptRecord(
+                    query=current_query,
+                    retrieval_metrics=retrieval.metrics,
+                    gate=decision.to_dict(),
+                    evidence_ids=[c.chunk.id for c in reranked],
+                )
+            )
+            prev_best = best[0] if best is not None else -1.0
+            if best is None or decision.score > best[0]:
+                best = (decision.score, reranked, decision, current_query)
+            if decision.passed:
+                break
+            # Diminishing-returns early stop: don't burn retries going nowhere.
+            improved = decision.score > prev_best + cfg.retry.min_improvement
+            if len(attempts) >= 2 and not improved:
+                break
+            if attempt < cfg.retry.max_retries:
+                rewritten = self.rewriter.rewrite(current_query, reranked)
+                if rewritten == current_query:
+                    break  # rewriter found nothing new; further retries are pointless
+                attempts[-1].rewrite = rewritten
+                current_query = rewritten
+
+        assert best is not None
+        _, evidence, decision, _ = best
+        verdict: Verdict = ANSWERABLE if decision.passed else INSUFFICIENT
+        overridden = False
+        if gate_override and verdict == INSUFFICIENT:
+            verdict = ANSWERABLE
+            overridden = True
+
+        answer: str | None = None
+        faithfulness: FaithfulnessReport | None = None
+        if verdict == ANSWERABLE and generator is not None:
+            answer = generator(query, evidence)
+            faithfulness = self.judge.check(answer, evidence)
+            if faithfulness.score < self.faithfulness_floor:
+                verdict = NEEDS_REVIEW
+
+        total_ms = round((perf_counter() - t0) * 1000, 2)
+        trace = {
+            "modes": self._retriever().modes,
+            "degraded": self.degraded_reason,
+            "attempts": len(attempts),
+            "retries_used": len(attempts) - 1,
+            "reranker": self.reranker.name,
+            "judge": self.judge.name,
+            "gate_overridden": overridden,
+            "total_ms": total_ms,
+            "chunk_count": len(self.chunks),
+        }
+        return AnswerResult(
+            verdict=verdict,
+            query=query,
+            evidence=evidence,
+            gate=decision,
+            attempts=attempts,
+            answer=answer,
+            faithfulness=faithfulness,
+            trace=trace,
+        )
+
+    def evaluate(self, items: list[EvalItem]) -> dict:
+        """Run the eval harness: retrieval metrics + gate confusion matrix."""
+        results = []
+        for item in items:
+            res = self.ask(item.query)
+            results.append(
+                {
+                    "retrieved_ids": [c.chunk.id for c in res.evidence],
+                    "verdict": res.verdict,
+                }
+            )
+        return aggregate(items, results).to_dict()

rerankgate/rerank.py

@@ -0,0 +1,94 @@
+"""Rerankers: zero-dependency feature reranker (default) + cross-encoder (opt-in)."""
+
+from __future__ import annotations
+
+from time import perf_counter
+from typing import Protocol
+
+from rerankgate.retrieval import ScoredChunk
+from rerankgate.tokenize import content_tokens, tokenize
+
+
+class Reranker(Protocol):
+    name: str
+
+    def rerank(self, query: str, candidates: list[ScoredChunk], k: int) -> list[ScoredChunk]: ...
+
+
+class FeatureReranker:
+    """Deterministic, explainable reranker. No model required.
+
+    score = 0.5 * norm(fusion) + 0.3 * term_coverage + 0.2 * phrase_bonus
+    """
+
+    name = "feature"
+
+    def rerank(self, query: str, candidates: list[ScoredChunk], k: int) -> list[ScoredChunk]:
+        t0 = perf_counter()
+        q_terms = set(content_tokens(query))
+        q_phrases = _phrases(query)
+        max_fused = max((c.score for c in candidates), default=1.0) or 1.0
+
+        rescored: list[ScoredChunk] = []
+        for c in candidates:
+            toks = set(tokenize(c.chunk.text))
+            coverage = len(q_terms & toks) / len(q_terms) if q_terms else 0.0
+            text_l = c.chunk.text.lower()
+            phrase_bonus = 1.0 if q_phrases and any(p in text_l for p in q_phrases) else 0.0
+            norm_fused = c.score / max_fused
+            score = 0.5 * norm_fused + 0.3 * coverage + 0.2 * phrase_bonus
+            rescored.append(
+                ScoredChunk(
+                    chunk=c.chunk,
+                    score=score,
+                    sources={
+                        **c.sources,
+                        "rerank": round(score, 4),
+                        "coverage": round(coverage, 4),
+                        "phrase": phrase_bonus,
+                    },
+                )
+            )
+        rescored.sort(key=lambda c: c.score, reverse=True)
+        self.last_ms = round((perf_counter() - t0) * 1000, 2)
+        return rescored[:k]
+
+
+def _phrases(query: str) -> list[str]:
+    toks = content_tokens(query)
+    return [" ".join(toks[i : i + 2]) for i in range(len(toks) - 1)]
+
+
+class CrossEncoderReranker:
+    """Cross-encoder reranker (ms-marco MiniLM). Requires `rerankgate[local]`."""
+
+    name = "cross-encoder"
+
+    def __init__(self, model_name: str = "cross-encoder/ms-marco-MiniLM-L-6-v2") -> None:
+        try:
+            from sentence_transformers import CrossEncoder  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError(
+                "sentence-transformers is not installed. "
+                "Install it with `pip install rerankgate[local]`."
+            ) from exc
+        self._model = CrossEncoder(model_name)
+        self.last_ms = 0.0
+
+    def rerank(self, query: str, candidates: list[ScoredChunk], k: int) -> list[ScoredChunk]:
+        import math
+
+        if not candidates:
+            return []
+        t0 = perf_counter()
+        pairs = [(query, c.chunk.text) for c in candidates]
+        logits = self._model.predict(pairs)
+        rescored = []
+        for c, logit in zip(candidates, logits, strict=True):
+            score = 1 / (1 + math.exp(-float(logit)))  # sigmoid to [0,1]
+            rescored.append(
+                ScoredChunk(chunk=c.chunk, score=score, sources={**c.sources, "rerank": score})
+            )
+        rescored.sort(key=lambda c: c.score, reverse=True)
+        self.last_ms = round((perf_counter() - t0) * 1000, 2)
+        return rescored[:k]

rerankgate/retrieval.py

@@ -0,0 +1,99 @@
+"""Hybrid retrieval: BM25 + vector search fused with Reciprocal Rank Fusion."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from time import perf_counter
+from typing import Any
+
+from rerankgate.bm25 import BM25Index
+from rerankgate.documents import Chunk
+from rerankgate.embeddings import EmbeddingBackend
+from rerankgate.tokenize import tokenize
+from rerankgate.vectorstore import VectorStore
+
+
+@dataclass
+class ScoredChunk:
+    chunk: Chunk
+    score: float
+    sources: dict[str, float] = field(default_factory=dict)  # per-system raw scores
+
+
+@dataclass
+class RetrievalResult:
+    chunks: list[ScoredChunk]
+    metrics: dict[str, Any]
+
+
+class HybridRetriever:
+    """Fuses BM25 and vector rankings with RRF (rank-based, no score normalization)."""
+
+    def __init__(
+        self,
+        bm25: BM25Index,
+        vector_store: VectorStore | None = None,
+        embeddings: EmbeddingBackend | None = None,
+        rrf_k: int = 60,
+        bm25_weight: float = 1.0,
+        vector_weight: float = 1.0,
+    ) -> None:
+        self.bm25 = bm25
+        self.vector_store = vector_store
+        self.embeddings = embeddings
+        self.rrf_k = rrf_k
+        self.bm25_weight = bm25_weight
+        self.vector_weight = vector_weight
+        self.degraded: str | None = None  # reason if running BM25-only
+
+    @property
+    def modes(self) -> list[str]:
+        modes = ["bm25"]
+        if self.vector_store is not None and self.embeddings is not None:
+            modes.append("vector")
+        return modes
+
+    def retrieve(self, query: str, k: int = 100) -> RetrievalResult:
+        t0 = perf_counter()
+        rankings: list[tuple[str, list[tuple[Chunk, float]], float]] = []
+
+        t_bm25 = perf_counter()
+        bm25_hits = self.bm25.search(query, k=k)
+        bm25_ms = (perf_counter() - t_bm25) * 1000
+        rankings.append(("bm25", bm25_hits, self.bm25_weight))
+
+        vector_ms = 0.0
+        if self.vector_store is not None and self.embeddings is not None:
+            t_vec = perf_counter()
+            qvec = self.embeddings.embed([query])[0]
+            vec_hits = self.vector_store.search(qvec, k=k)
+            vector_ms = (perf_counter() - t_vec) * 1000
+            rankings.append(("vector", vec_hits, self.vector_weight))
+
+        # Reciprocal Rank Fusion over ranks (1-based).
+        fused: dict[str, float] = {}
+        by_id: dict[str, Chunk] = {}
+        sources: dict[str, dict[str, float]] = {}
+        for name, hits, weight in rankings:
+            for rank, (ch, raw) in enumerate(hits, start=1):
+                fused[ch.id] = fused.get(ch.id, 0.0) + weight / (self.rrf_k + rank)
+                by_id[ch.id] = ch
+                sources.setdefault(ch.id, {})[name] = raw
+
+        ordered = sorted(fused.items(), key=lambda kv: kv[1], reverse=True)[:k]
+        chunks = [
+            ScoredChunk(chunk=by_id[cid], score=s, sources=dict(sources[cid])) for cid, s in ordered
+        ]
+        total_ms = (perf_counter() - t0) * 1000
+        metrics = {
+            "modes": self.modes,
+            "degraded": self.degraded,
+            "k": k,
+            "bm25_hits": len(bm25_hits),
+            "bm25_ms": round(bm25_ms, 2),
+            "vector_ms": round(vector_ms, 2),
+            "total_ms": round(total_ms, 2),
+            "fused_count": len(chunks),
+            "query_terms": len(tokenize(query)),
+        }
+        return RetrievalResult(chunks=chunks, metrics=metrics)