cadrumo.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 terminology-handbook authoring 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 aeat-documentation 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. The lifecycle axis itself is the core-owned ConceptLifecycle closed set, the one home reachable from both this shipped reader and the unshipped authoring tooling; a stored token that names no member is refused here rather than silently filtered out of every result.

See also

search_terminology()

Approved-concept terminology search defined here.

Notes

External adapters may project ranked terminology hits into their own transport payloads without changing this product-side authority.

CONCEPT_ID_PATTERN

Canonical kebab-case shape for a Terminology Handbook concept_id: an immutable Spanish stem, lowercase, hyphen-separated. Shared with the unshipped authoring schema (the authoring tooling’s schema module, which imports these three constants from this package) so a malformed id is refused identically on both sides of the shipping boundary rather than passing this lean product reader while failing strict authoring validation.

class TerminologyConcept(**data)[source]

Bases: BaseModel

One Handbook concept projected for a single locale.

Parameters:

data (Any)

concept_id: _Text
domain: _Text
lifecycle: ConceptLifecycle
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:

data (Any)

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=(ConceptLifecycle.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: