aeat.application.corpus_search._models module

Typed records for the on-host corpus-search grounding surface.

Every record is a strict, frozen pydantic v2 model. The surface never exposes a bare dict for a chunk, a search hit, or a citation resolution: the console grounds an operator against verbatim legal text, so the provenance carried alongside each result (corpus_ref, source path, document id, permalink) is contract, not decoration.

See also

search_corpus()

Runtime service that returns RetrievalResponse.

corpus_search_payload_from_response()

MCP transport mapper that preserves the typed retrieval provenance.

class RetrievalMode(*values)[source]

Bases: StrEnum

How a retrieval response was produced.

CITATION — the query was an exact citation id, short-circuited to the structured lookup; HYBRID — lexical FTS5 fused with semantic cosine; LEXICAL_ONLY — the degraded no-model mode (search extra absent or no precomputed vectors supplied).

CITATION
HYBRID
LEXICAL_ONLY
class CorpusChunk(**data)[source]

Bases: BaseModel

One retrievable prose chunk extracted from the bundled corpus.

A chunk is a paragraph-bounded slice of a single extracted unit (an article or disposition). chunk_id is deterministic given the same corpus, so a rebuilt index re-mints byte-identical ids and the shipped embedding matrix stays row-aligned with the lexical index.

Parameters:

  • chunk_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • corpus_ref (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • source_path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • doc_title (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • section (str | None)

  • anchor (str | None)

  • ordinal (int)

  • text (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

chunk_id: _Text
corpus_ref: _Text
source_path: _Text
doc_title: _Text
section: str | None
anchor: str | None
ordinal: int
text: _Text
class CorpusDocument(**data)[source]

Bases: BaseModel

Metadata for one extracted corpus source file in the lexical index.

Parameters:

  • corpus_ref (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • source_path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • title (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • chunk_count (int)

corpus_ref: _Text
source_path: _Text
title: _Text
chunk_count: int
class LexicalSearchHit(**data)[source]

Bases: BaseModel

One ranked lexical-search result over the FTS5 index.

Parameters:

  • chunk_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • corpus_ref (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • doc_title (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • section (str | None)

  • anchor (str | None)

  • rank (int)

  • score (float)

  • text (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

chunk_id: _Text
corpus_ref: _Text
doc_title: _Text
section: str | None
anchor: str | None
rank: int
score: float
text: _Text
class CitationResolution(**data)[source]

Bases: BaseModel

A citation id resolved to catalogue metadata plus verbatim text.

The metadata is projected from the registry legal catalogue (the single citation authority); verbatim_text is read from the bundled extracted corpus the citation’s corpus_ref points at.

Parameters:

  • citation_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • document_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • kind (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • corpus_ref (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • permalink (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • article (str | None)

  • section (str | None)

  • anchor (str | None)

  • verbatim_text (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

citation_id: _Text
document_id: _Text
kind: _Text
corpus_ref: _Text
article: str | None
section: str | None
anchor: str | None
verbatim_text: _Text
class SimilarChunk(**data)[source]

Bases: BaseModel

One cosine-nearest chunk for the more-like-this primitive.

Parameters:

  • chunk_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • rank (int)

  • similarity (float)

chunk_id: _Text
rank: int
similarity: float
class CorpusIndexBuildResult(**data)[source]

Bases: BaseModel

Summary of one lexical-index build.

Parameters:

  • database_path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • document_count (int)

  • chunk_count (int)

database_path: _Text
document_count: int
chunk_count: int
class CorpusEmbeddingBuildResult(**data)[source]

Bases: BaseModel

Summary of one build-time embedding precompute.

Parameters:

  • matrix_path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • chunk_ids_path (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • chunk_count (int)

  • dimensions (int)

  • embedding_model_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • embedding_model_revision (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

matrix_path: _Text
chunk_ids_path: _Text
chunk_count: int
dimensions: int
embedding_model_id: _Text
embedding_model_revision: _Text
class RetrievalHit(**data)[source]

Bases: BaseModel

One fused hybrid-retrieval result over the corpus.

text is the verbatim chunk prose (the snippet source); corpus_ref grounds it in the bundled source (and is the aeat://corpus/{ref} key that resolves the full verbatim text). score is the fused RRF score; lexical_rank / semantic_rank record the per-side contribution (None when a side did not surface the chunk).

Parameters:

  • chunk_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • corpus_ref (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • doc_title (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • text (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None, ascii_only=None)])

  • score (float)

  • rank (int)

  • lexical_rank (int | None)

  • semantic_rank (int | None)

chunk_id: _Text
corpus_ref: _Text
doc_title: _Text
text: _Text
score: float
rank: int
lexical_rank: int | None
semantic_rank: int | None
class RetrievalResponse(**data)[source]

Bases: BaseModel

The typed result of one corpus retrieval.

mode records how the response was produced (citation short-circuit, hybrid, or lexical-only degraded). citation carries the resolved citation when mode is CITATION; otherwise hits carries the ranked results.

Parameters:
query: _Text
mode: RetrievalMode
hits: tuple[RetrievalHit, ...]
citation: CitationResolution | None