rerankgate 0.2.0__tar.gz

rerankgate-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: rerankgate
+Version: 0.2.0
+Summary: Agentic RAG quality gate: hybrid retrieval with a sufficiency gate, query-rewrite retries, and per-stage metrics. Local-first.
+Author: Calas Automations Inc.
+License: MIT
+Project-URL: Homepage, https://calasautomations.com
+Keywords: rag,retrieval,rerank,bm25,quality-gate,agentic
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: local
+Requires-Dist: numpy>=1.24; extra == "local"
+Requires-Dist: sentence-transformers>=2.2; extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+
+# rerankgate
+
+**Agentic RAG quality gate.** A drop-in retrieval pipeline with a decision point
+between retrieval and generation:
+
+```
+query → hybrid retrieval (BM25 + vectors, RRF fusion)
+      → rerank
+      → sufficiency gate ── PASS ─→ evidence (+ optional generation & faithfulness check)
+                           FAIL ─→ rewrite query (RM3, no LLM) → retry (≤2, early-stop)
+                           exhausted → ABSTAIN with evidence + reasons
+```
+
+**The rule:** if the retrieval wasn't good enough, the answer never gets generated.
+Local-first — the sufficiency gate works with zero LLM calls by default.
+
+## Install
+
+```bash
+pip install rerankgate            # zero hard dependencies (BM25-only mode)
+pip install "rerankgate[local]"   # + sentence-transformers, numpy (hybrid vectors)
+```
+
+## Quickstart
+
+```python
+from rerankgate import RAGPipeline, Document
+
+pipe = RAGPipeline()  # degrades to BM25-only if embeddings aren't installed
+pipe.ingest([
+    Document(id="rag", text="Retrieval-augmented generation pairs a retriever..."),
+    Document(id="bm25", text="BM25 is a classic probabilistic ranking function..."),
+])
+
+result = pipe.ask("What is retrieval-augmented generation?")
+print(result.verdict)          # "answerable" | "insufficient" | "needs_review"
+print(result.gate.reasons)     # e.g. ["PASS"] or ["LOW_COVERAGE", ...]
+print(result.gate.explanation) # human-readable why
+
+# Suspected false negative? Override it — the override is recorded in the trace.
+result = pipe.ask("...", gate_override=True)
+
+# Optional: run your own generator through the faithfulness check.
+result = pipe.ask("...", generator=lambda q, ev: my_llm(q, [c.chunk.text for c in ev]))
+# verdict flips to "needs_review" if the answer isn't grounded in the evidence.
+```
+
+Every `ask()` returns a full `trace`: per-stage timings, retrieval modes,
+retry count, gate features, and whether the run was degraded.
+
+## CLI
+
+```bash
+# JSONL corpus: {"id": ..., "text": ..., ...metadata}
+rerankgate ingest --input corpus.jsonl --store ./store
+
+rerankgate query --store ./store "What is RAG?"
+rerankgate query --store ./store --gate-preset lenient --json "..."
+
+# Evaluate retrieval + gate on labeled data, then tune the threshold.
+# qrels JSONL: {"query": ..., "relevant_ids": [...], "answerable": true/false}
+rerankgate eval --store ./store --qrels eval.jsonl
+rerankgate eval --store ./store --qrels eval.jsonl --summary  # aggregates only
+```
+
+`rerankgate eval` reports recall@k, MRR (over answerable items), the gate
+confusion matrix (precision/recall of PASS vs your labels), and the abstention
+rate — use it to pick a threshold/preset instead of trusting the defaults.
+
+## How the gate works
+
+The sufficiency gate is a fixed weighted heuristic over interpretable features —
+top rerank score, query-term coverage, ranking margin, and cross-chunk support —
+plus hard floors on coverage and top score. Every decision carries stable
+machine-readable reason codes (`PASS`, `LOW_TOP_SCORE`, `LOW_COVERAGE`,
+`NO_MARGIN`, `NO_CONSENSUS`, `NO_EVIDENCE`) and a human explanation. Nothing is
+learned, so there's nothing to overfit; tune it with the eval CLI.
+
+Presets: `strict` (0.70) · `balanced` (0.55, default) · `lenient` (0.40).
+
+## Design notes
+
+- **Fusion:** Reciprocal Rank Fusion (k=60) — rank-based, no cross-system score
+  normalization hacks. Per-system weights available in `PipelineConfig`.
+- **Retries:** RM3-style pseudo-relevance feedback expands the query from the
+  failed attempt's top docs — no LLM needed. Hard cap of 2 retries plus
+  diminishing-returns early stop: the loop always terminates.
+- **Abstention > hallucination:** on `insufficient` the pipeline returns
+  best-effort evidence with gate reasons so the caller can decide — it never
+  silently hands weak context to an LLM.
+- **Pluggable:** `EmbeddingBackend`, `Reranker`, and `Judge` are protocols.
+  Bring your own embeddings (OpenAI, Cohere…), a cross-encoder, or an
+  LLM-as-judge without touching the pipeline.
+
+## Limitations (honest)
+
+- The heuristic gate is tuned for English keyword overlap. Synonym-heavy,
+  cross-lingual, or highly abstract queries can under-score — use hybrid vectors
+  and/or the `lenient` preset, and calibrate with `rerankgate eval`.
+- The default faithfulness judge is token-overlap based: free and instant, but
+  gameable by extractive copying. For adversarial settings, plug in `LLMJudge`.
+- Default chunking is a sentence-aware character window, not semantic chunking;
+  tables and structured text chunk naively.
+- `pip install rerankgate[local]` pulls PyTorch (~2GB) via sentence-transformers —
+  the price of local dense retrieval. BM25-only mode needs nothing.
+- The gate threshold defaults are starting points, not tuned constants — they
+  were sanity-checked on a toy corpus, not a benchmark. Calibrate on your data.
+- Not thread-safe; one pipeline per thread. At 500K+ vectors, prefer the numpy
+  path (installed with `[local]`) over the pure-Python fallback.
+
+## License
+
+MIT — Calas Automations Inc.

rerankgate-0.2.0/README.md

@@ -0,0 +1,113 @@
+# rerankgate
+
+**Agentic RAG quality gate.** A drop-in retrieval pipeline with a decision point
+between retrieval and generation:
+
+```
+query → hybrid retrieval (BM25 + vectors, RRF fusion)
+      → rerank
+      → sufficiency gate ── PASS ─→ evidence (+ optional generation & faithfulness check)
+                           FAIL ─→ rewrite query (RM3, no LLM) → retry (≤2, early-stop)
+                           exhausted → ABSTAIN with evidence + reasons
+```
+
+**The rule:** if the retrieval wasn't good enough, the answer never gets generated.
+Local-first — the sufficiency gate works with zero LLM calls by default.
+
+## Install
+
+```bash
+pip install rerankgate            # zero hard dependencies (BM25-only mode)
+pip install "rerankgate[local]"   # + sentence-transformers, numpy (hybrid vectors)
+```
+
+## Quickstart
+
+```python
+from rerankgate import RAGPipeline, Document
+
+pipe = RAGPipeline()  # degrades to BM25-only if embeddings aren't installed
+pipe.ingest([
+    Document(id="rag", text="Retrieval-augmented generation pairs a retriever..."),
+    Document(id="bm25", text="BM25 is a classic probabilistic ranking function..."),
+])
+
+result = pipe.ask("What is retrieval-augmented generation?")
+print(result.verdict)          # "answerable" | "insufficient" | "needs_review"
+print(result.gate.reasons)     # e.g. ["PASS"] or ["LOW_COVERAGE", ...]
+print(result.gate.explanation) # human-readable why
+
+# Suspected false negative? Override it — the override is recorded in the trace.
+result = pipe.ask("...", gate_override=True)
+
+# Optional: run your own generator through the faithfulness check.
+result = pipe.ask("...", generator=lambda q, ev: my_llm(q, [c.chunk.text for c in ev]))
+# verdict flips to "needs_review" if the answer isn't grounded in the evidence.
+```
+
+Every `ask()` returns a full `trace`: per-stage timings, retrieval modes,
+retry count, gate features, and whether the run was degraded.
+
+## CLI
+
+```bash
+# JSONL corpus: {"id": ..., "text": ..., ...metadata}
+rerankgate ingest --input corpus.jsonl --store ./store
+
+rerankgate query --store ./store "What is RAG?"
+rerankgate query --store ./store --gate-preset lenient --json "..."
+
+# Evaluate retrieval + gate on labeled data, then tune the threshold.
+# qrels JSONL: {"query": ..., "relevant_ids": [...], "answerable": true/false}
+rerankgate eval --store ./store --qrels eval.jsonl
+rerankgate eval --store ./store --qrels eval.jsonl --summary  # aggregates only
+```
+
+`rerankgate eval` reports recall@k, MRR (over answerable items), the gate
+confusion matrix (precision/recall of PASS vs your labels), and the abstention
+rate — use it to pick a threshold/preset instead of trusting the defaults.
+
+## How the gate works
+
+The sufficiency gate is a fixed weighted heuristic over interpretable features —
+top rerank score, query-term coverage, ranking margin, and cross-chunk support —
+plus hard floors on coverage and top score. Every decision carries stable
+machine-readable reason codes (`PASS`, `LOW_TOP_SCORE`, `LOW_COVERAGE`,
+`NO_MARGIN`, `NO_CONSENSUS`, `NO_EVIDENCE`) and a human explanation. Nothing is
+learned, so there's nothing to overfit; tune it with the eval CLI.
+
+Presets: `strict` (0.70) · `balanced` (0.55, default) · `lenient` (0.40).
+
+## Design notes
+
+- **Fusion:** Reciprocal Rank Fusion (k=60) — rank-based, no cross-system score
+  normalization hacks. Per-system weights available in `PipelineConfig`.
+- **Retries:** RM3-style pseudo-relevance feedback expands the query from the
+  failed attempt's top docs — no LLM needed. Hard cap of 2 retries plus
+  diminishing-returns early stop: the loop always terminates.
+- **Abstention > hallucination:** on `insufficient` the pipeline returns
+  best-effort evidence with gate reasons so the caller can decide — it never
+  silently hands weak context to an LLM.
+- **Pluggable:** `EmbeddingBackend`, `Reranker`, and `Judge` are protocols.
+  Bring your own embeddings (OpenAI, Cohere…), a cross-encoder, or an
+  LLM-as-judge without touching the pipeline.
+
+## Limitations (honest)
+
+- The heuristic gate is tuned for English keyword overlap. Synonym-heavy,
+  cross-lingual, or highly abstract queries can under-score — use hybrid vectors
+  and/or the `lenient` preset, and calibrate with `rerankgate eval`.
+- The default faithfulness judge is token-overlap based: free and instant, but
+  gameable by extractive copying. For adversarial settings, plug in `LLMJudge`.
+- Default chunking is a sentence-aware character window, not semantic chunking;
+  tables and structured text chunk naively.
+- `pip install rerankgate[local]` pulls PyTorch (~2GB) via sentence-transformers —
+  the price of local dense retrieval. BM25-only mode needs nothing.
+- The gate threshold defaults are starting points, not tuned constants — they
+  were sanity-checked on a toy corpus, not a benchmark. Calibrate on your data.
+- Not thread-safe; one pipeline per thread. At 500K+ vectors, prefer the numpy
+  path (installed with `[local]`) over the pure-Python fallback.
+
+## License
+
+MIT — Calas Automations Inc.

rerankgate-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rerankgate"
+version = "0.2.0"
+description = "Agentic RAG quality gate: hybrid retrieval with a sufficiency gate, query-rewrite retries, and per-stage metrics. Local-first."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Calas Automations Inc." }]
+keywords = ["rag", "retrieval", "rerank", "bm25", "quality-gate", "agentic"]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.optional-dependencies]
+local = ["numpy>=1.24", "sentence-transformers>=2.2"]
+dev = ["pytest>=7", "ruff>=0.1"]
+
+[project.scripts]
+rerankgate = "rerankgate.cli:main"
+
+[project.urls]
+Homepage = "https://calasautomations.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "C4", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rerankgate-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rerankgate-0.2.0/src/rerankgate/__init__.py

@@ -0,0 +1,30 @@
+"""rerankgate — agentic RAG quality gate.
+
+Drop-in retrieval pipeline with built-in quality gates:
+hybrid search (BM25 + vector) -> rerank -> sufficiency gate ->
+query-rewrite retry or abstain. Local-first; the sufficiency gate
+works without any LLM call by default.
+"""
+
+from rerankgate.config import GateConfig, PipelineConfig, RetryConfig
+from rerankgate.documents import Document, chunk_text
+from rerankgate.gate import GateDecision, SufficiencyGate
+from rerankgate.pipeline import AnswerResult, RAGPipeline, Verdict
+from rerankgate.retrieval import HybridRetriever, ScoredChunk
+
+__all__ = [
+    "AnswerResult",
+    "Document",
+    "GateConfig",
+    "GateDecision",
+    "HybridRetriever",
+    "PipelineConfig",
+    "RAGPipeline",
+    "RetryConfig",
+    "ScoredChunk",
+    "SufficiencyGate",
+    "Verdict",
+    "chunk_text",
+]
+
+__version__ = "0.2.0"

rerankgate-0.2.0/src/rerankgate/bm25.py

@@ -0,0 +1,70 @@
+"""Pure-stdlib BM25 (Okapi) index over chunks."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+from rerankgate.documents import Chunk
+from rerankgate.tokenize import tokenize
+
+
+class BM25Index:
+    """In-memory BM25 index. Deterministic; rebuild from chunks."""
+
+    def __init__(self, k1: float = 1.5, b: float = 0.75) -> None:
+        self.k1 = k1
+        self.b = b
+        self._chunks: list[Chunk] = []
+        self._doc_freq: Counter[str] = Counter()
+        self._term_freqs: list[Counter[str]] = []
+        self._doc_lens: list[int] = []
+        self._avg_len: float = 0.0
+
+    def __len__(self) -> int:
+        return len(self._chunks)
+
+    def add(self, chunks: list[Chunk]) -> None:
+        for ch in chunks:
+            toks = tokenize(ch.text)
+            tf = Counter(toks)
+            self._chunks.append(ch)
+            self._term_freqs.append(tf)
+            self._doc_lens.append(len(toks))
+            for term in tf:
+                self._doc_freq[term] += 1
+        total = sum(self._doc_lens)
+        self._avg_len = total / len(self._doc_lens) if self._doc_lens else 0.0
+
+    def _idf(self, term: str) -> float:
+        n = len(self._chunks)
+        df = self._doc_freq.get(term, 0)
+        # Standard BM25 IDF with +1 smoothing floor; unseen terms get ~0.
+        return math.log(1 + (n - df + 0.5) / (df + 0.5)) if df else 0.0
+
+    def search(self, query: str, k: int = 100) -> list[tuple[Chunk, float]]:
+        """Return top-k (chunk, score) pairs, highest score first."""
+        q_terms = tokenize(query)
+        if not q_terms or not self._chunks:
+            return []
+        idfs = {t: self._idf(t) for t in set(q_terms)}
+        scored: list[tuple[Chunk, float]] = []
+        for i, ch in enumerate(self._chunks):
+            tf = self._term_freqs[i]
+            dl = self._doc_lens[i]
+            norm = 1 - self.b + self.b * (dl / self._avg_len) if self._avg_len else 1.0
+            score = 0.0
+            for t in q_terms:
+                f = tf.get(t, 0)
+                if f and idfs[t]:
+                    score += idfs[t] * (f * (self.k1 + 1)) / (f + self.k1 * norm)
+            if score > 0:
+                scored.append((ch, score))
+        scored.sort(key=lambda p: p[1], reverse=True)
+        return scored[:k]
+
+    def term_stats(self, chunk_idx: int) -> Counter[str]:
+        return self._term_freqs[chunk_idx]
+
+    def chunks(self) -> list[Chunk]:
+        return list(self._chunks)

rerankgate-0.2.0/src/rerankgate/cli.py

@@ -0,0 +1,142 @@
+"""rerankgate CLI: ingest | query | eval."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from rerankgate.config import PipelineConfig
+from rerankgate.documents import Document
+from rerankgate.metrics import EvalItem
+from rerankgate.pipeline import RAGPipeline
+
+
+def _pipeline_for(args: argparse.Namespace, *, for_ingest: bool = False) -> RAGPipeline:
+    cfg = PipelineConfig()
+    if args.gate_preset:
+        cfg.gate_preset = args.gate_preset
+    if args.max_retries is not None:
+        cfg.retry.max_retries = args.max_retries
+    if args.no_vectors:
+        cfg.use_vectors = False
+    if for_ingest:
+        return RAGPipeline(config=cfg)
+    return RAGPipeline.load(args.store, config=cfg)
+
+
+def cmd_ingest(args: argparse.Namespace) -> int:
+    docs: list[Document] = []
+    with open(args.input, encoding="utf-8") as f:
+        for i, line in enumerate(f):
+            line = line.strip()
+            if not line:
+                continue
+            obj = json.loads(line)
+            text = obj.get("text", "")
+            meta = {k: v for k, v in obj.items() if k not in ("id", "text")}
+            docs.append(Document(id=str(obj.get("id", f"doc-{i}")), text=text, metadata=meta))
+    pipe = _pipeline_for(args, for_ingest=True)
+    n_chunks = pipe.ingest(docs)
+    pipe.save(args.store)
+    print(f"ingested {len(docs)} documents -> {n_chunks} chunks -> {args.store}")
+    if pipe.degraded_reason:
+        print("note: BM25-only mode (no embeddings installed)")
+    return 0
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    pipe = _pipeline_for(args)
+    result = pipe.ask(args.query)
+    out = result.to_dict()
+    if args.json:
+        print(json.dumps(out, indent=2))
+        return 0
+    print(f"verdict:  {out['verdict']}")
+    print(
+        f"gate:     {'PASS' if out['gate']['passed'] else 'FAIL'} "
+        f"(score {out['gate']['score']} vs threshold {out['gate']['threshold']})"
+    )
+    print(f"reasons:  {', '.join(out['gate']['reasons'])}")
+    print(
+        f"attempts: {out['trace']['attempts']}  "
+        f"modes: {','.join(out['trace']['modes'])}  "
+        f"total: {out['trace']['total_ms']}ms"
+    )
+    if out["trace"]["degraded"]:
+        print("degraded: BM25-only (embeddings unavailable)")
+    print("evidence:")
+    for ev in out["evidence"][:10]:
+        snippet = ev["text"][:120].replace("\n", " ")
+        print(f"  [{ev['score']:.3f}] {ev['chunk_id']}: {snippet}...")
+    return 0
+
+
+def cmd_eval(args: argparse.Namespace) -> int:
+    pipe = _pipeline_for(args)
+    items: list[EvalItem] = []
+    with open(args.qrels, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            obj = json.loads(line)
+            items.append(
+                EvalItem(
+                    query=obj["query"],
+                    relevant_ids=list(obj.get("relevant_ids", [])),
+                    answerable=bool(obj.get("answerable", True)),
+                )
+            )
+    report = pipe.evaluate(items)
+    if args.summary:
+        report = {k: v for k, v in report.items() if k != "per_query"}
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    import rerankgate
+
+    p = argparse.ArgumentParser(prog="rerankgate", description="Agentic RAG quality gate")
+    p.add_argument("--version", action="version", version=f"%(prog)s {rerankgate.__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def _common(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("--gate-preset", choices=["strict", "balanced", "lenient"], default=None)
+        sp.add_argument("--max-retries", type=int, default=None)
+        sp.add_argument("--no-vectors", action="store_true", help="force BM25-only mode")
+
+    pi = sub.add_parser("ingest", help="ingest a JSONL corpus into a store")
+    pi.add_argument("--input", required=True, help="JSONL with {id, text, ...metadata}")
+    pi.add_argument("--store", required=True, help="output store directory")
+    _common(pi)
+    pi.set_defaults(func=cmd_ingest)
+
+    pq = sub.add_parser("query", help="ask a question against a store")
+    pq.add_argument("--store", required=True)
+    pq.add_argument("query")
+    pq.add_argument("--json", action="store_true")
+    _common(pq)
+    pq.set_defaults(func=cmd_query)
+
+    pe = sub.add_parser("eval", help="evaluate retrieval + gate on labeled qrels")
+    pe.add_argument("--store", required=True)
+    pe.add_argument("--qrels", required=True, help="JSONL with {query, relevant_ids, answerable}")
+    pe.add_argument(
+        "--summary",
+        action="store_true",
+        help="print aggregate metrics only, without the per-query detail",
+    )
+    _common(pe)
+    pe.set_defaults(func=cmd_eval)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rerankgate-0.2.0/src/rerankgate/config.py

@@ -0,0 +1,77 @@
+"""Configuration dataclasses for rerankgate."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RetryConfig:
+    """Bounds for the query-rewrite retry loop."""
+
+    max_retries: int = 2
+    # Stop early if the best gate score does not improve by at least this much.
+    min_improvement: float = 0.01
+    # How many expansion terms the RM3-style rewriter may add per retry.
+    expansion_terms: int = 5
+
+
+@dataclass
+class GateConfig:
+    """Tunable knobs for the heuristic sufficiency gate.
+
+    The gate score is a fixed weighted sum of interpretable features
+    (see gate.py). Nothing is learned, so there is nothing to overfit;
+    tune the threshold with `rerankgate eval` on your own labeled data.
+    """
+
+    threshold: float = 0.55
+    w_top_score: float = 0.35
+    w_coverage: float = 0.30
+    w_margin: float = 0.20
+    w_support: float = 0.15
+    # Minimum fraction of (non-stopword) query terms that must appear
+    # in the evidence before the gate can pass, regardless of score.
+    min_coverage: float = 0.25
+    # Minimum normalized top-1 rerank score before the gate can pass.
+    min_top_score: float = 0.10
+
+    def preset(self, name: str) -> GateConfig:
+        """Return a copy with a named strictness preset applied."""
+        presets = {
+            # (threshold, min_coverage): stricter gates demand more evidence.
+            "strict": (0.70, 0.35),
+            "balanced": (0.55, 0.25),
+            "lenient": (0.40, 0.15),
+        }
+        if name not in presets:
+            raise ValueError(f"unknown gate preset {name!r}; choose from {sorted(presets)}")
+        import dataclasses
+
+        threshold, min_coverage = presets[name]
+        return dataclasses.replace(self, threshold=threshold, min_coverage=min_coverage)
+
+
+@dataclass
+class PipelineConfig:
+    """Top-level pipeline configuration."""
+
+    # Retrieval
+    retrieve_k: int = 100  # candidates pulled from each retriever before fusion
+    rerank_k: int = 10  # evidence chunks returned after reranking
+    rrf_k: int = 60  # RRF rank constant
+    bm25_weight: float = 1.0  # per-system RRF multipliers
+    vector_weight: float = 1.0
+    use_vectors: bool = True  # degraded to BM25-only if embeddings unavailable
+
+    # Chunking
+    chunk_size: int = 500
+    chunk_overlap: int = 50
+
+    # Gate + retry
+    gate: GateConfig = field(default_factory=GateConfig)
+    retry: RetryConfig = field(default_factory=RetryConfig)
+    gate_preset: str = "balanced"
+
+    def effective_gate(self) -> GateConfig:
+        return self.gate.preset(self.gate_preset)