aeat.application.corpus_search._runtime module¶

Runtime corpus-search service: provision the index and run hybrid search.

The MCP console tools and resources consume grounding through one service entry, search_corpus(), so the protocol layer never re-derives the retrieval wiring. On first use the lexical index is built once from the bundled corpus into an app-controlled cache under the Settings storage root and reused thereafter (the corpus is static, so a present index is current).

Precomputed corpus vectors are loaded when they have been shipped/materialised into the same cache directory; absent them (or the search extra) the service runs in lexical-only + citation mode, the shippable degraded default.

See also

hybrid_search(): Retrieval primitive this runtime service provisions and calls.
ensure_corpus_embeddings(): Build-once semantic-vector cache behind the aeat-cli[search] extra.
QueryEmbedder: Live-query embedder used only when semantic vectors are available.

corpus_search_dir(settings=None)[source]¶

Return the app-controlled corpus-search cache directory.

Return type:: Path
Parameters:: settings (Settings | None)

corpus_index_path(settings=None)[source]¶

Return the lexical index path (whether or not it has been built).

Return type:: Path
Parameters:: settings (Settings | None)

ensure_corpus_index(settings=None)[source]¶

Return the lexical index path, building it from the bundled corpus if absent.

The first build stems the whole bundled corpus and is the one slow call (seconds to tens of seconds); every later call finds the cached index and returns immediately. A present index is current because the bundled corpus is static.

Return type:: Path
Parameters:: settings (Settings | None)

load_corpus_embeddings(settings=None)[source]¶

Load precomputed corpus vectors from the cache, or None if not present.

Return type:: tuple[ndarray, tuple[str, ...]] | None
Parameters:: settings (Settings | None)

ensure_corpus_embeddings(settings=None, *, semantic_available=None, corpus_chunks=None)[source]¶

Return the corpus vectors, building them once behind the search extra.

This is the runtime build step for the semantic half (the decision recorded for the S79/S87 question): corpus vectors are BUILT behind the aeat-cli[search] extra on first use, never shipped in the wheel (shipped-search-licence-clean keeps the wheel free of the ~0.5 GB model weights and the derived matrix). It mirrors ensure_corpus_index(): the first call is the one slow build (it downloads/loads the potion model and encodes every bundled chunk into an app-controlled cache); every later call finds the cached matrix and returns immediately, and a present matrix is current because the bundled corpus is static.

Returns None — the shippable lexical-only default — whenever the extra is absent, so a bare-core install never triggers a model download.

Return type:

tuple[ndarray, tuple[str, ...]] | None

Parameters:

settings (Settings | None)
semantic_available (bool | None)
corpus_chunks (Iterable[CorpusChunk] | None)

search_corpus(query, *, limit=8, settings=None)[source]¶

Run grounding retrieval for query over the bundled corpus.

Provisions the lexical index (build-once cache), loads precomputed vectors when present, and fuses lexical, semantic, and exact-citation retrieval — degrading to lexical-only when the semantic stack is unavailable.

Parameters:

query (str) – The free-text query or an exact citation id.
limit (int) – Maximum number of hits.
settings (Settings | None) – Optional settings override (test isolation).

Return type:

RetrievalResponse

Returns:

A RetrievalResponse.