cadrumo.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.

Notes

External adapters may project this response while preserving its typed retrieval provenance.

class RetrievalMode(*values)

Bases: StrEnum

How a retrieval response was produced.

CITATION — the query was an exact citation id, short-circuited to the structured lookup; LEXICAL_ONLY — the ranked FTS5 lexical search over the bundled corpus. These are the only two shapes the product ships: the shipped retrieval surface loads no model and computes no vectors.

CITATION

LEXICAL_ONLY

class CorpusChunk(**data)

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 a chunk id held across a rebuild still resolves.

Parameters:

data (Any)

chunk_id: _Text

corpus_ref: _Text

source_path: _Text

doc_title: _Text

section: str | None

anchor: str | None

ordinal: NonNegativeInt

text: _Text

class CorpusDocument(**data)

Bases: BaseModel

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

Parameters:

data (Any)

corpus_ref: _Text

source_path: _Text

title: _Text

chunk_count: NonNegativeInt

class LexicalSearchHit(**data)

Bases: BaseModel

One ranked lexical-search result over the FTS5 index.

Parameters:

data (Any)

chunk_id: _Text

corpus_ref: _Text

doc_title: _Text

section: str | None

anchor: str | None

rank: NonNegativeInt

score: float

text: _Text

class CitationResolution(**data)

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:

data (Any)

citation_id: _Text

document_id: _Text

kind: _Text

corpus_ref: _Text

permalink: _Text

article: str | None

section: str | None

anchor: str | None

verbatim_text: _Text

class CorpusIndexBuildResult(**data)

Bases: BaseModel

Summary of one lexical-index build.

Parameters:

data (Any)

database_path: _Text

document_count: NonNegativeInt

chunk_count: NonNegativeInt

class RetrievalHit(**data)

Bases: BaseModel

One ranked lexical-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 cadrumo://corpus/{ref} key that resolves the full verbatim text). score is the FTS5 BM25 relevance, sign-flipped so a larger value is a better match; lexical_rank is the hit’s zero-based position in the lexical ranking.

Parameters:

data (Any)

chunk_id: _Text

corpus_ref: _Text

doc_title: _Text

text: _Text

score: float

rank: NonNegativeInt

lexical_rank: int | None

class RetrievalResponse(**data)

Bases: BaseModel

The typed result of one corpus retrieval.

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

Parameters:

data (Any)

query: _Text

mode: RetrievalMode

hits: tuple[RetrievalHit, ...]

citation: CitationResolution | None