aeat.application.corpus_search._retrieval module

Hybrid corpus retrieval: FTS5 lexical + semantic cosine, RRF-fused (R3).

The R3 grounding search runs three cooperating retrievers and fuses them:

  • an exact-citation short-circuit — when the query IS a citation id (ley-58-2003:art-27.2), it resolves directly through the structured lookup, no ranking needed;

  • the FTS5 lexical index (_lexical_index) for exact and stemmed in-prose recall;

  • a brute-force numpy cosine over the build-time-precomputed corpus matrix, with the live query embedded by QueryEmbedder.

The lexical and semantic rankings are fused with Reciprocal Rank Fusion (RRF, k=60), each side capped at its top ~50, in plain Python — no ANN index earns its keep at this corpus scale. When the semantic side is unavailable (the search extra absent, or no precomputed vectors supplied) the retriever degrades cleanly to lexical-only, so a bare-core install still grounds an operator against the corpus.

RRF_K

RRF constant. The canonical k=60 dampens the contribution of low-ranked results so a strong hit on one side is not drowned by a long tail on the other.

PER_SIDE_CAP

Per-side result cap before fusion; a generous top-N keeps fusion cheap.

Run hybrid retrieval for query and return a typed response.

Parameters:

  • query (str) – The free-text query, or an exact citation id.

  • database_path (Path) – A lexical index built by build_lexical_index.

  • embeddings (tuple[ndarray, Sequence[str]] | None) – Optional (matrix, chunk_ids) precomputed corpus vectors; when omitted the semantic side is off (lexical-only).

  • query_embedder (QueryEmbedder | None) – Optional embedder for the live query; when omitted or unavailable, the semantic side is off.

  • citation_lookup (CitationLookup | None) – Optional catalogue lookup enabling the exact-citation short-circuit.

  • limit (int) – Maximum number of fused hits to return.

  • rrf_k (int) – The RRF damping constant.

  • per_side_cap (int) – Per-side result cap before fusion.

Return type:

RetrievalResponse

Returns:

A RetrievalResponse — a citation resolution, or ranked hits with the mode (hybrid or lexical-only) that produced them.

Raises:

CorpusSearchInputError – If query is blank or limit is not positive.