aeat.application.corpus_search._terminology module

Product-side reader and search over the bundled Terminology Handbook.

The Handbook concept fragments under _data/terminology/concepts/*.toml are authored/compiled by the dev.docs.terminology_handbook dev tooling, which is NOT shipped in the wheel. This module is the shipped, product-side consumer: a lean strict loader that projects each concept for a requested locale and a simple in-memory search over the small concept set.

Per the glossary-concepts-are-taxpayer-facing rule the shipped search surfaces only approved-lifecycle concepts — the ratified taxpayer/operator vocabulary — excluding draft (unreviewed) and deprecated (internal machinery) concepts, which the taxpayer glossary also excludes.

See also

search_terminology()

Public facade for approved-concept terminology search.

lookup_terminology()

Public facade for exact concept-id lookup.

terminology_payload_from_hits()

MCP transport mapper for ranked terminology hits.

class TerminologyConcept(**data)[source]

Bases: BaseModel

One Handbook concept projected for a single locale.

Parameters:

  • concept_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)])

  • domain (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)])

  • lifecycle (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)])

  • locale (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)])

  • preferred_label (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)])

  • terms (tuple[str, ...])

  • short_description (str)

  • definition (str)

  • scope_note (str | None)

  • legal_refs (tuple[str, ...])

concept_id: _Text
domain: _Text
lifecycle: _Text
locale: _Text
preferred_label: _Text
terms: tuple[str, ...]
short_description: str
definition: str
scope_note: str | None
legal_refs: tuple[str, ...]
class TerminologyHit(**data)[source]

Bases: BaseModel

One ranked terminology search result.

Parameters:

  • concept_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)])

  • preferred_label (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)])

  • short_description (str)

  • score (int)

  • matched_on (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)])

concept_id: _Text
preferred_label: _Text
short_description: str
score: int
matched_on: _Text
load_terminology_concepts(locale='es')[source]

Load every Handbook concept projected for locale (fallback es).

Return type:

tuple[TerminologyConcept, ...]

Returns:

A TerminologyConcept.

Parameters:

locale (str)

search_terminology(query, *, locale='es', limit=8, lifecycles=('approved',))[source]

Search the Handbook for query, returning ranked hits.

Only concepts whose lifecycle is in lifecycles (approved by default, the taxpayer-facing set) are considered.

Raises:

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

Return type:

tuple[TerminologyHit, ...]

Returns:

A TerminologyHit.

Parameters:
lookup_terminology(concept_id, *, locale='es')[source]

Return one concept by id.

Raises:

CorpusSearchInputError – If concept_id is unknown.

Return type:

TerminologyConcept

Returns:

A TerminologyConcept.

Parameters:

  • concept_id (str)

  • locale (str)