brainiac-cli 0.16.0__py3-none-any.whl

brain/overlay.py

@@ -0,0 +1,183 @@
+"""Per-user personalization overlay (PER-01 / PER-02).
+
+The substrate (`vault/brain/`, `vault/raw/`) is generic — it carries NO
+hard-coded owner identity. Brand/voice/keyword/people content that used to be
+wired straight into the kernel is a **data-driven slot** any new owner fills
+with their own: the overlay.
+
+Layout (the generic, owner-agnostic shape):
+
+    overlay/
+    ├── voice/      *.md  — durable writing voice (tone, register, sign-offs)
+    ├── brand/      *.md  — naming/anonymisation/title conventions
+    ├── keywords/   *.md  — glossary / acronym / codename decoder ring
+    └── people/     *.md  — the always-on people this owner's notes reference
+
+Each file carries a small frontmatter block (`overlay_type: <category>`) so a
+validator can check shape without guessing from folder name alone. See
+`overlay/README.md` for the full schema + starter scaffold.
+
+This module is intentionally **filesystem-only** — it never constructs a
+`BrainCore` or opens the index. `brain init --validate-overlay` has to work on
+a brand-new install before any index exists, so overlay validation must not
+depend on one.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from . import frontmatter
+
+CATEGORIES: tuple[str, ...] = ("voice", "brand", "keywords", "people")
+
+# AUT-01/AUT-03 (ADR-0003 Ruling c/e): the HTML brief/digest renderers are
+# pure-render — all overlay I/O happens here, once, before the render call.
+# Two OPTIONAL frontmatter keys on a brand/*.md file (alongside the existing
+# overlay_type/title/updated) let an owner brand the generated HTML without
+# any new overlay category or schema ceremony. Absent -> neutral fallback
+# (zero hard-coded owner content is the kernel/overlay contract).
+_DEFAULT_BRAND_TITLE = "Brain Brief"
+_DEFAULT_ACCENT = "#2563eb"
+_HEX_COLOR_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
+def overlay_dir(
+    vault: str | os.PathLike[str] | None = None,
+    explicit: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Resolve the active overlay directory.
+
+    Precedence: ``explicit`` arg (``--overlay-dir``) > ``$BRAIN_OVERLAY_DIR`` >
+    ``<vault>/overlay`` (the overlay travels with the user's vault, alongside
+    ``raw/`` and ``brain/`` — see AGENTS.md §1).
+    """
+    if explicit:
+        return Path(explicit).expanduser().resolve()
+    env = os.environ.get("BRAIN_OVERLAY_DIR")
+    if env:
+        return Path(env).expanduser().resolve()
+    from . import config
+
+    return config.vault_root(vault) / "overlay"
+
+
+def _validate_category_file(path: Path, category: str) -> list[str]:
+    """Return a list of human-readable issues for one overlay file (empty = OK)."""
+    issues: list[str] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as exc:  # pragma: no cover - unreadable file is rare
+        return [f"{path.name}: unreadable ({type(exc).__name__}: {exc})"]
+
+    meta, body = frontmatter.parse_text(text)
+    if not meta:
+        issues.append(f"{path.name}: missing or unparseable frontmatter")
+        return issues
+
+    declared = meta.get("overlay_type")
+    if declared != category:
+        issues.append(
+            f"{path.name}: overlay_type={declared!r} does not match its "
+            f"directory ({category!r})"
+        )
+    if not body.strip():
+        issues.append(f"{path.name}: frontmatter present but body is empty")
+    return issues
+
+
+def validate_overlay(path: Path) -> dict[str, Any]:
+    """Validate an overlay directory's shape. Pure filesystem check.
+
+    Required shape: ``path`` exists and contains, for EACH of ``CATEGORIES``,
+    a subdirectory with at least one ``*.md`` file whose frontmatter declares
+    ``overlay_type: <category>``. Returns a report dict (never raises on a
+    malformed/missing overlay — that is what ``valid: false`` is for).
+    """
+    if not path.exists():
+        return {
+            "overlay_dir": str(path),
+            "exists": False,
+            "valid": False,
+            "categories": {
+                c: {"present": False, "file_count": 0, "issues": [f"{c}/ missing (overlay dir does not exist)"]}
+                for c in CATEGORIES
+            },
+            "errors": [f"overlay dir does not exist: {path}"],
+        }
+
+    categories: dict[str, Any] = {}
+    errors: list[str] = []
+
+    for cat in CATEGORIES:
+        cat_dir = path / cat
+        issues: list[str] = []
+        file_count = 0
+        present = cat_dir.is_dir()
+        if not present:
+            issues.append(f"missing category directory: {cat}/")
+        else:
+            md_files = sorted(cat_dir.glob("*.md"))
+            file_count = len(md_files)
+            if file_count == 0:
+                issues.append(f"{cat}/ exists but has no .md files")
+            for f in md_files:
+                issues.extend(_validate_category_file(f, cat))
+        categories[cat] = {"present": present, "file_count": file_count, "issues": issues}
+        errors.extend(f"{cat}: {issue}" for issue in issues)
+
+    return {
+        "overlay_dir": str(path),
+        "exists": True,
+        "valid": len(errors) == 0,
+        "categories": categories,
+        "errors": errors,
+    }
+
+
+def resolve_brand(
+    vault: str | os.PathLike[str] | None = None,
+    explicit: str | os.PathLike[str] | None = None,
+) -> dict[str, Any]:
+    """Resolve brand data for the HTML brief/digest renderers (AUT-01/AUT-03).
+
+    Reads the FIRST ``overlay/brand/*.md`` file (sorted, deterministic) if
+    present and takes its ``title`` plus two optional keys — ``owner_name``,
+    ``accent_color`` (a ``#rgb``/``#rrggbb`` hex string; anything else is
+    ignored, never trusted into CSS unvalidated). Never raises; a missing
+    overlay, empty ``brand/`` category, or unreadable file all fall back to
+    the NEUTRAL default below — the renderer must never depend on an owner
+    overlay existing.
+    """
+    result: dict[str, Any] = {
+        "present": False,
+        "title": _DEFAULT_BRAND_TITLE,
+        "owner_name": None,
+        "accent_color": _DEFAULT_ACCENT,
+    }
+    brand_dir = overlay_dir(vault, explicit) / "brand"
+    brand_files = sorted(brand_dir.glob("*.md")) if brand_dir.is_dir() else []
+    if not brand_files:
+        return result
+    try:
+        text = brand_files[0].read_text(encoding="utf-8")
+    except Exception:
+        return result
+
+    meta, _body = frontmatter.parse_text(text)
+    if not meta:
+        return result
+
+    title = meta.get("title")
+    owner_name = meta.get("owner_name")
+    accent = meta.get("accent_color")
+    if isinstance(title, str) and title.strip():
+        result["title"] = title.strip()
+    if isinstance(owner_name, str) and owner_name.strip():
+        result["owner_name"] = owner_name.strip()
+    if isinstance(accent, str) and _HEX_COLOR_RE.match(accent.strip()):
+        result["accent_color"] = accent.strip()
+    result["present"] = True
+    return result

brain/projection.py

@@ -0,0 +1,79 @@
+"""Workspace projection — the REAL containment control (consensus hardening).
+
+The classification filter (brain.classification) only governs what the
+cooperative `brain` CLI *prints*. It is NOT containment: any file-capable
+harness can read the Markdown in ``vault/`` directly and see every tier. The
+plan's consensus hardening requires a real control. We choose option (a):
+
+    Project a workspace that physically EXCLUDES Restricted/MNPI (and anything
+    above the cap, and all unlabelled/default-deny notes) for untrusted harnesses.
+
+An untrusted harness (e.g. a Cowork VM leg) is given access ONLY to the
+projected directory, never the full vault. Because the sensitive files are not
+present in the projection, a direct file read on that surface cannot surface
+them — proven by tests/test_direct_file_read.py.
+
+This composes with the host/VM trust split (substrate-spec §4): the host owns
+the full vault and the writer role; the VM sees only a projection.
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import classification as cls
+from .notes import scan_vault
+
+
+@dataclass
+class ProjectionResult:
+    dest: Path
+    max_tier: str
+    copied: int
+    excluded: int
+    excluded_unlabelled: int
+
+    def to_dict(self) -> dict:
+        return {
+            "dest": str(self.dest),
+            "max_tier": self.max_tier,
+            "copied": self.copied,
+            "excluded": self.excluded,
+            "excluded_unlabelled": self.excluded_unlabelled,
+        }
+
+
+def project_workspace(vault: Path, dest: Path, max_tier: str = cls.DEFAULT_MAX_TIER) -> ProjectionResult:
+    """Materialise a filtered copy of ``vault`` into ``dest``.
+
+    Only notes whose effective classification rank <= ``max_tier`` are copied.
+    Unlabelled/unrecognised notes are default-denied (treated as MNPI) and
+    excluded unless ``max_tier == "MNPI"``. ``dest`` is recreated from scratch
+    each call so it can never retain a previously-projected sensitive file.
+    """
+    vault = Path(vault)
+    dest = Path(dest)
+    flt = cls.ClassificationFilter(max_tier=max_tier)
+
+    if dest.exists():
+        shutil.rmtree(dest)
+    dest.mkdir(parents=True)
+
+    copied = excluded = excluded_unlabelled = 0
+    for note in scan_vault(vault):
+        if flt.allows(note.classification):
+            rel = note.path.relative_to(vault)
+            out = dest / rel
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(note.path.read_text(encoding="utf-8"), encoding="utf-8")
+            copied += 1
+        else:
+            excluded += 1
+            if cls.is_default_denied(note.classification):
+                excluded_unlabelled += 1
+
+    return ProjectionResult(
+        dest=dest, max_tier=max_tier, copied=copied,
+        excluded=excluded, excluded_unlabelled=excluded_unlabelled,
+    )

brain/rerank.py

@@ -0,0 +1,425 @@
+"""Reranker ADAPTER INTERFACE + a real cross-encoder + an identity fallback (RET-02).
+
+A reranker is an OPTIONAL precision booster: after the fused hybrid_search
+(``brain.index.BrainIndex.hybrid_search``) produces a coarse top-N, a
+cross-encoder re-scores each (query, passage) pair jointly and re-orders only
+the top 10-20 candidates. It is strictly skippable — every retrieval path runs
+correctly with reranking switched OFF, and degrades to the identity reranker
+(order preserved) whenever the model runtime is unavailable.
+
+Design of record: **Alibaba-NLP/gte-multilingual-reranker-base** (Apache-2.0,
+multilingual, ~int8/ONNX). Like the Arctic embedder it is run locally over ONNX
+(no PyTorch) via fastembed's ``TextCrossEncoder``; the model is loaded lazily on
+first ``rerank`` so merely constructing the reranker is cheap and offline.
+
+Two implementations satisfy the ``Reranker`` protocol:
+
+  * ``GteReranker``  — the real cross-encoder via fastembed/ONNX. Raises
+                       ``RerankerUnavailable`` if the runtime/model is absent.
+  * ``NoopReranker`` — identity: returns candidates in their incoming order with
+                       monotonically-decreasing synthetic scores. Always
+                       available, network-free; the guaranteed fallback and the
+                       "rerank skipped" path.
+
+Because rerank is bounded to the top 10-20 (``RERANK_TOP_DEFAULT``), its latency
+is comparable to today's single rerank step regardless of corpus size.
+"""
+from __future__ import annotations
+
+import os
+from typing import Protocol, Sequence, runtime_checkable
+
+
+def _ort_threads() -> int | None:
+    """Intra-op thread count for the reranker ONNX session (S11 speed fix).
+
+    Default: all physical cores. The reranker cross-encodes the top-N
+    (query, passage) pairs in ONE batched forward pass, so saturating the
+    batch dimension across cores is what keeps query p95 interactive.
+    Override via ``$BRAIN_RERANK_THREADS``."""
+    raw = os.environ.get("BRAIN_RERANK_THREADS")
+    if raw and raw.strip().isdigit():
+        return int(raw)
+    try:
+        return os.cpu_count() or None
+    except Exception:
+        return None
+
+
+def _ort_providers() -> list[str]:
+    """Execution providers for the reranker (S11 speed fix). Default CPU
+    (the path the eval gate ran on); opt into Apple CoreML (ANE/GPU) via
+    ``$BRAIN_RERANK_PROVIDERS=CoreMLExecutionProvider``. Comma-separate for
+    a fallback chain."""
+    raw = os.environ.get("BRAIN_RERANK_PROVIDERS")
+    if raw and raw.strip():
+        return [p.strip() for p in raw.split(",") if p.strip()]
+    return ["CPUExecutionProvider"]
+
+# Bound the rerank window: only the coarse top-N is re-scored, never the whole
+# candidate set. Clamped to [RERANK_TOP_MIN, RERANK_TOP_MAX] at call sites.
+#
+# RERANK_TOP_MAX is the latency-vs-recall lever. The original [10,20] band
+# assumed the bi-encoder already had the right doc near the top — TRUE for
+# same-language queries, FALSE for CROSS-LINGUAL ones, where a relevant
+# EN-content note can sit at fused rank 40+ (buried under same-language
+# transcript chunks) and never enter a top-20 rerank window. A wide-candidate
+# cross-encoder pass (top 100–200) is the standard agentic "retrieve broad →
+# rerank" recovery for exactly that case, so the ceiling is env-overridable via
+# BRAIN_RERANK_MAX (default 20 keeps the conservative latency default). The
+# cross-encoder re-scores the full note body, giving brain a whole-note signal
+# at rerank time — the incumbent's structural advantage, recovered post-hoc.
+RERANK_TOP_DEFAULT = 15
+RERANK_TOP_MIN = 10
+RERANK_TOP_MAX = 20
+
+# The model of record. The original design named gte-multilingual-reranker-base,
+# but that model is NOT in fastembed's TextCrossEncoder catalog (verified
+# 2026-06-28 — TextCrossEncoder.list_supported_models()), so it cannot run in the
+# chosen ONNX/no-PyTorch runtime. The of-record multilingual cross-encoder is now
+# jina-reranker-v2-base-multilingual (in the fastembed catalog, ~1.1 GB int8/ONNX,
+# CC-BY-NC for the weights — gate at deploy if commercial use is required). It
+# scores cross-lingual (PT-query ↔ EN-passage) pairs correctly with a wide margin
+# where the e5-small bi-encoder cannot. Override via BRAIN_RERANKER_MODEL.
+GTE_RERANKER_MODEL_ID = "jinaai/jina-reranker-v2-base-multilingual"
+
+
+def _resolve_reranker_model() -> str:
+    """The reranker model id, env-overridable via ``BRAIN_RERANKER_MODEL``."""
+    return os.environ.get("BRAIN_RERANKER_MODEL") or GTE_RERANKER_MODEL_ID
+
+
+@runtime_checkable
+class Reranker(Protocol):
+    model_id: str
+
+    def rerank(self, query: str, passages: Sequence[str]) -> list[float]:
+        """Return one relevance score per passage (higher = more relevant),
+        aligned by index with ``passages``."""
+
+
+class RerankerUnavailable(RuntimeError):
+    """Raised when the requested reranker backend is not importable/usable."""
+
+
+class NoopReranker:
+    """Identity reranker: preserves the incoming order.
+
+    Emits descending synthetic scores so a stable sort by score is a no-op on the
+    incoming order. This is the value returned whenever reranking is skipped or
+    the real model runtime is unavailable — callers never special-case it.
+    """
+
+    model_id = "noop"
+
+    def rerank(self, query: str, passages: Sequence[str]) -> list[float]:
+        n = len(passages)
+        # Descending, position-preserving scores: n, n-1, ... 1.
+        return [float(n - i) for i in range(n)]
+
+
+class GteReranker:
+    """gte-multilingual-reranker-base via fastembed/ONNX — NO PyTorch.
+
+    Lazy: the ONNX cross-encoder is created on first ``rerank`` so constructing
+    the reranker (to read ``model_id``) is cheap and offline. Raises
+    ``RerankerUnavailable`` if fastembed's cross-encoder support or the model is
+    not importable/available.
+    """
+
+    def __init__(
+        self,
+        model_id: str | None = None,
+        *,
+        cache_dir: str | None = None,
+    ) -> None:
+        self.model_id = model_id or _resolve_reranker_model()
+        self._cache_dir = cache_dir or os.environ.get("BRAIN_FASTEMBED_CACHE")
+        self._model = None  # lazily created TextCrossEncoder
+
+    @staticmethod
+    def available() -> bool:
+        try:
+            from fastembed.rerank.cross_encoder import TextCrossEncoder  # noqa: F401
+
+            return True
+        except Exception:
+            return False
+
+    def _ensure_model(self):
+        if self._model is None:
+            try:
+                from fastembed.rerank.cross_encoder import TextCrossEncoder
+            except Exception as exc:  # pragma: no cover - exercised when absent
+                raise RerankerUnavailable(
+                    "fastembed cross-encoder support not importable; install the "
+                    "'embed' extra or bundle the reranker model"
+                ) from exc
+            try:
+                self._model = TextCrossEncoder(
+                    model_name=self.model_id, cache_dir=self._cache_dir,
+                    threads=_ort_threads(), providers=_ort_providers(),
+                )
+            except Exception as exc:  # pragma: no cover - model unavailable offline
+                raise RerankerUnavailable(
+                    f"reranker model {self.model_id!r} unavailable: {exc}"
+                ) from exc
+        return self._model
+
+    def rerank(self, query: str, passages: Sequence[str]) -> list[float]:
+        if not passages:
+            return []
+        model = self._ensure_model()
+        return [float(s) for s in model.rerank(query, list(passages))]
+
+
+class QwenReranker:
+    """Qwen3-Reranker-0.6B via the ``qwen3-embed`` lib (ONNX INT8, Apache-2.0).
+
+    The 2025-2026 best-in-class small multilingual reranker (MMTEB-R 66.36).
+    Shipped in S11 (UPG-03) as the upgrade over ``jina-reranker-v2`` — BOTH a
+    quality gain (largest on long multilingual docs, +27 on MLDR per the tech
+    report) AND a licence fix (jina-reranker-v2 is CC-BY-NC-4.0, a corporate-
+    deployment blocker; Qwen3 is Apache-2.0). ~573 MB INT8 ONNX.
+
+    Loaded via the same ``qwen3-embed`` lib as the embedder (it exposes a
+    ``TextCrossEncoder`` with a fastembed-compatible ``rerank(query, docs)``
+    API). Lazy: the ONNX session is created on first ``rerank``.
+    """
+
+    def __init__(
+        self,
+        model_id: str | None = None,
+        *,
+        cache_dir: str | None = None,
+    ) -> None:
+        self.model_id = model_id or _resolve_reranker_model()
+        self._cache_dir = cache_dir or os.environ.get("BRAIN_FASTEMBED_CACHE")
+        self._model = None
+
+    @staticmethod
+    def available() -> bool:
+        try:
+            import qwen3_embed  # noqa: F401
+            import onnxruntime  # noqa: F401
+
+            return True
+        except Exception:
+            return False
+
+    def _ensure_model(self):
+        if self._model is None:
+            try:
+                from qwen3_embed import TextCrossEncoder
+            except Exception as exc:  # pragma: no cover
+                raise RerankerUnavailable(
+                    "qwen3-embed not importable; pip install qwen3-embed"
+                ) from exc
+            try:
+                self._model = TextCrossEncoder(
+                    model_name=self.model_id, cache_dir=self._cache_dir,
+                    threads=_ort_threads(), providers=_ort_providers(),
+                )
+            except Exception as exc:  # pragma: no cover - model unavailable offline
+                raise RerankerUnavailable(
+                    f"reranker model {self.model_id!r} unavailable: {exc}"
+                ) from exc
+        return self._model
+
+    def rerank(self, query: str, passages: Sequence[str]) -> list[float]:
+        if not passages:
+            return []
+        model = self._ensure_model()
+        return [float(s) for s in model.rerank(query, list(passages))]
+
+
+def _is_qwen_reranker(model_id: str) -> bool:
+    low = (model_id or "").lower()
+    return "qwen3-reranker" in low or "qwen-rerank" in low
+
+
+# --- Fully-open reranker of record (replaces the CC-BY-NC jina-reranker-v2) ---
+# gte-multilingual-reranker-base is Apache-2.0, an XLM-R ENCODER cross-encoder
+# (~306M). It is the best QUALITY among the latency-affordable fully-open
+# multilingual rerankers: an encoder is far faster per pair than the decoder
+# rerankers (Qwen3-Reranker, mxbai-rerank-v2) that fail the HP latency gate, and
+# it is licence-clean (jina-reranker-v2 — the prior model of record — is CC-BY-NC,
+# barred for commercial use in your organization). Loaded DIRECTLY via ONNX Runtime + tokenizers
+# (bge-reranker-v2-m3 / gte are NOT in fastembed's catalogue). Latency ~1.65 s /
+# top-15 query on an M4 ⇒ ~4 s projected on a corporate HP, so reranking stays
+# OPT-IN (the default at the call site remains NoopReranker).
+OPEN_DEFAULT_RERANKER_REPO = "onnx-community/gte-multilingual-reranker-base"
+OPEN_DEFAULT_RERANKER_ONNX = "onnx/model.onnx"
+OPEN_DEFAULT_RERANKER_MODEL_ID = "Alibaba-NLP/gte-multilingual-reranker-base"
+
+
+class OnnxReranker:
+    """Any HuggingFace ONNX cross-encoder reranker loaded DIRECTLY via ONNX
+    Runtime — no fastembed-catalog dependency, no PyTorch at runtime.
+
+    Default-of-record: ``gte-multilingual-reranker-base`` (Apache-2.0). Can also
+    load a local exported reranker via ``local_dir`` / ``$BRAIN_RERANKER_ONNX_DIR``
+    (e.g. an exported bge-reranker-v2-m3). ENCODER cross-encoders only — do not
+    point this at a decoder reranker (Qwen3-Reranker / mxbai-rerank-v2); those
+    fail the latency gate on corporate-HP CPU.
+    """
+
+    def __init__(
+        self,
+        *,
+        hf_repo: str | None = None,
+        onnx_file: str | None = None,
+        local_dir: str | None = None,
+        model_id: str | None = None,
+    ) -> None:
+        self.model_id = model_id or OPEN_DEFAULT_RERANKER_MODEL_ID
+        self._hf_repo = hf_repo or OPEN_DEFAULT_RERANKER_REPO
+        self._onnx_file = onnx_file or OPEN_DEFAULT_RERANKER_ONNX
+        self._local_dir = local_dir or os.environ.get("BRAIN_RERANKER_ONNX_DIR")
+        self._sess = None
+        self._tok = None
+        self._in_names: list[str] | None = None
+
+    @staticmethod
+    def available() -> bool:
+        try:
+            import onnxruntime  # noqa: F401
+            import tokenizers  # noqa: F401
+
+            return True
+        except Exception:
+            return False
+
+    def _ensure(self):
+        if self._sess is None:
+            try:
+                import onnxruntime as ort
+                from tokenizers import Tokenizer
+            except Exception as exc:  # pragma: no cover
+                raise RerankerUnavailable(
+                    "onnxruntime/tokenizers not importable for OnnxReranker"
+                ) from exc
+            try:
+                if self._local_dir:
+                    base = self._local_dir
+                    onnx_path = os.path.join(base, "model_quantized.onnx")
+                    if not os.path.exists(onnx_path):
+                        onnx_path = os.path.join(base, "model.onnx")
+                else:
+                    from huggingface_hub import snapshot_download
+
+                    base = snapshot_download(
+                        self._hf_repo,
+                        allow_patterns=[
+                            self._onnx_file,
+                            self._onnx_file + "_data",
+                            "tokenizer*",
+                            "*.json",
+                        ],
+                    )
+                    onnx_path = os.path.join(base, self._onnx_file)
+                so = ort.SessionOptions()
+                so.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+                t = _ort_threads()
+                if t:
+                    so.intra_op_num_threads = t
+                self._sess = ort.InferenceSession(
+                    onnx_path, sess_options=so, providers=_ort_providers()
+                )
+                self._in_names = [i.name for i in self._sess.get_inputs()]
+                self._tok = Tokenizer.from_file(os.path.join(base, "tokenizer.json"))
+                # Clamp (query, passage) pairs to the cross-encoder's context
+                # window before run(): an over-long pair makes the position-
+                # embedding broadcast fail (same crash class as the embedder's
+                # "512 by 620"). Passages are already char-capped upstream
+                # (_apply_rerank -> [:2000]), so at the default 1024 this
+                # truncation effectively never fires for gte/jina and does NOT
+                # change the S11-frozen rerank numbers — it is pure crash
+                # insurance. Override via $BRAIN_RERANK_MAX_TOKENS.
+                _rmax = 1024
+                try:
+                    _rt = os.environ.get("BRAIN_RERANK_MAX_TOKENS")
+                    if _rt and _rt.strip().isdigit():
+                        _rmax = int(_rt)
+                except Exception:
+                    pass
+                self._tok.enable_truncation(max_length=_rmax)
+            except RerankerUnavailable:
+                raise
+            except Exception as exc:  # pragma: no cover - model unavailable offline
+                raise RerankerUnavailable(
+                    f"ONNX reranker {self.model_id!r} unavailable: {exc}"
+                ) from exc
+        return self._sess
+
+    def rerank(self, query: str, passages: Sequence[str]) -> list[float]:
+        if not passages:
+            return []
+        self._ensure()
+        import numpy as np
+
+        enc = self._tok.encode_batch([(query, p) for p in passages])
+        ii = np.array([e.ids for e in enc], dtype=np.int64)
+        am = np.array([e.attention_mask for e in enc], dtype=np.int64)
+        feed = {}
+        for nm in self._in_names:
+            low = nm.lower()
+            if "input_id" in low:
+                feed[nm] = ii
+            elif "attention" in low:
+                feed[nm] = am
+            elif "token_type" in low:
+                feed[nm] = np.zeros_like(ii)
+        logits = self._sess.run(None, feed)[0]
+        return [float(x[0]) if hasattr(x, "__len__") else float(x) for x in logits]
+
+
+def get_reranker(prefer: str = "noop") -> Reranker:
+    """Adapter selection.
+
+    ``noop`` forces the identity fallback (the DEFAULT — reranking is OPT-IN at
+    the call site, because even the open reranker is ~4 s/query on a corporate
+    HP). ``onnx`` selects ``OnnxReranker`` — the fully-open model of record
+    (gte-multilingual-reranker-base, Apache-2.0; the CC-BY-NC jina-reranker-v2
+    replacement). ``gte`` selects the legacy fastembed ``GteReranker`` (the
+    CC-BY-NC jina-v2 catalogue path — AVOID for commercial use).
+    ``qwen`` selects ``QwenReranker`` (decoder; fails the HP latency gate —
+    legacy only). ``auto`` prefers a Qwen reranker when ``$BRAIN_RERANKER_MODEL``
+    names one, else the open OnnxReranker (gte), else the legacy fastembed path,
+    else noop.
+    """
+    env = os.environ.get("BRAIN_RERANKER_PREFER", "").strip().lower()
+    if env in {"noop", "gte", "qwen", "onnx"}:
+        prefer = env  # eval/AB-test override: force a specific reranker
+    if prefer == "noop":
+        return NoopReranker()
+    if prefer == "qwen":
+        return QwenReranker()
+    if prefer == "gte":
+        return GteReranker()
+    if prefer == "onnx":
+        return OnnxReranker()
+    # auto
+    rid = _resolve_reranker_model()
+    if _is_qwen_reranker(rid) and QwenReranker.available():
+        return QwenReranker()
+    # OPEN DEFAULT: gte-multilingual-reranker-base via OnnxReranker (Apache-2.0;
+    # replaces the CC-BY-NC jina-reranker-v2). Preferred over the fastembed path.
+    if OnnxReranker.available():
+        return OnnxReranker()
+    if GteReranker.available():
+        return GteReranker()
+    return NoopReranker()
+
+
+def clamp_rerank_top(n: int) -> int:
+    """Clamp the rerank window to [RERANK_TOP_MIN, ceiling], where the ceiling is
+    RERANK_TOP_MAX (20) by default but raisable via ``BRAIN_RERANK_MAX`` for the
+    wide-candidate cross-encoder pass that recovers cross-lingually buried docs.
+    A bad/zero env value falls back to the conservative default."""
+    try:
+        hi = int(os.environ.get("BRAIN_RERANK_MAX", "") or RERANK_TOP_MAX)
+    except ValueError:
+        hi = RERANK_TOP_MAX
+    hi = max(RERANK_TOP_MAX, hi)  # never below the design floor of 20
+    return max(RERANK_TOP_MIN, min(hi, n))