feat(retrieval): wire the cross-encoder reranker into kb.context

[nickmopen]

What changed

Wires the existing cross-encoder reranker (embeddings/rerank.py, already used by vouch search --rerank) into the kb.context / kb.search hybrid retrieval path in context._retrieve, behind a new retrieval.rerank config block.

Why

vouch already fuses lexical + semantic hits by reciprocal-rank fusion (embeddings/fusion.py:rrf_fuse, wired into context._retrieve) and already ships a finished cross-encoder reranker, but the reranker was only reachable from one place — vouch search --rerank in cli.py. The context-pack path that actually feeds agents (build_context_pack → _retrieve → kb.context) never reranked, and there was no config to turn it on. Fixes #429.

What might break

• On-disk layout: none.
• Behaviour change (intentional): none by default — retrieval.rerank.enabled defaults to false, so kb.context / kb.search ordering is byte-identical to today until a kb opts in. When enabled, only the ordering of hybrid-backend hits changes (never membership — archived/superseded claims stay excluded as before); if the optional reranker extra (sentence-transformers) isn't installed, it silently degrades to the unreranked fused order rather than raising.

VEP

Not a surface change — no new kb.* method, no object-model or on-disk-layout change, no audit-log-shape change. kb.context / kb.search gain an internal, opt-in reordering stage.

Tests

• make check (lint + mypy + pytest) — clean on the touched files. Full local suite: 1012/1020 passed (excluding tests/embeddings); the 8 pre-existing failures and 2 excluded modules (test_http_server.py, test_http_server_mcp.py, which bind real sockets) are Windows-local environment artifacts unrelated to this change — identical failure set before and after this diff.
• New tests in tests/test_retrieval_backend.py, following that file's existing monkeypatch pattern so they run under the base CI install without the sentence-transformers extra: test_rerank_disabled_by_default_ordering_unchanged (asserts the reranker is never even constructed when off), test_rerank_enabled_reorders_by_cross_encoder_score (on/off parity plus reordering via a stub reranker), test_rerank_missing_extra_degrades_to_fused_order (ImportError degrades cleanly).
• CHANGELOG.md updated under ## [Unreleased].

Fixes #429

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 25f88261-550a-4e84-aa71-f05b1c28ee41

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}