aeat.domain.manuals._schema module

Strict pydantic v2 records for the Manual práctico corpus.

The corpus consists of three primary records:

  • Manual: The root volume (id, year, part).

  • Chapter: Metadata and ordered section references.

  • Section: Prose paragraphs and extracted Rule objects.

Every record is strict, frozen, and prohibits unknown keys. Spanish is the authoritative language for the corpus text (prose, titles, summaries); the internationalization engine is used for the application’s user interface and error messages.

class ManualCasillaReference(**data)[source]

Bases: _ManualStrictFrozen

Structured manual cross-reference to a canonical registry casilla.

Parameters:

  • modelo_id (ModeloId)

  • casilla_id (CasillaId)

modelo_id: ModeloId
casilla_id: CasillaId
class SectionRef(**data)[source]

Bases: _ManualStrictFrozen

Link to a Section from a Chapter.

Parameters:

  • section_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • relative_path (str)

section_id: _StableId
relative_path: str
class LLMProvenance(**data)[source]

Bases: _ManualStrictFrozen

Metadata about the LLM extraction of a rule draft.

Variables:

  • provider – Provider key, e.g. 'anthropic'.

  • model – Concrete model name used for the draft.

  • prompt_id – Named prompt from the prompt registry.

  • cache_hit – Whether the draft was served from the LLM cache.

  • extracted_at – UTC timestamp the draft was produced.

Parameters:
provider: str
model: str
prompt_id: str
cache_hit: bool
extracted_at: datetime
class SectionSource(**data)[source]

Bases: _ManualStrictFrozen

Provenance pointer for a Section back to the source handbook.

Parameters:

  • manual_url (AnyHttpUrl)

  • page (int)

manual_url: AnyHttpUrl
page: int
class RuleSource(**data)[source]

Bases: _ManualStrictFrozen

Provenance pointer for a Rule back to the source handbook.

Parameters:

  • manual_url (AnyHttpUrl)

  • page (int)

  • paragraph (int | None)

manual_url: AnyHttpUrl
page: int
paragraph: int | None
class Paragraph(**data)[source]

Bases: _ManualStrictFrozen

A single source paragraph within a section.

Parameters:

  • paragraph_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • text (str)

  • page (int)

paragraph_id: _StableId
text: str
page: int
class Rule(**data)[source]

Bases: _ManualStrictFrozen

A single extracted rule from the Manual práctico.

Every persisted rule carries reviewer metadata populated by a real human; the verify CLI rejects rules missing those fields when AEAT_MANUALS_REVIEW_REQUIRED is true.

Variables:

  • rule_id – Stable kebab-case identifier produced by generate_rule_id().

  • manual_id – Owning handbook identifier.

  • year – Tax year the rule applies to.

  • part – Volume split within the year.

  • chapter_id – Stable identifier of the owning chapter.

  • section_id – Stable identifier of the owning section.

  • kind – Closed-catalogue rule category.

  • statement – Authoritative Spanish rule statement.

  • applies_when – Optional natural-language predicate describing the rule’s applicability (Spanish).

  • references_casillas – Cross-references to canonical registry casilla ids.

  • references_sections – Cross-references to sibling sections by stable id.

  • references_legal_acts – Cross-references to external legal acts (BOE orders, laws).

  • source – Provenance pointer back to the source PDF.

  • extracted_by – LLM provenance for the draft extraction.

  • definition_reviewed_by – Reviewer handle who signed off on the curated definition.

  • definition_reviewed_at – Date of the reviewer sign-off.

Parameters:

  • rule_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • manual_id (ManualId)

  • year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2100)])])

  • part (ManualPart)

  • chapter_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • section_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • kind (Literal['computation', 'applicability', 'valuation', 'deductibility', 'formal_obligation', 'procedural', 'other'])

  • statement (str)

  • applies_when (str | None)

  • references_casillas (tuple[ManualCasillaReference, ...])

  • references_sections (tuple[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)], ...])

  • references_legal_acts (tuple[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=256, pattern=^[A-Z0-9-][^|]*\|[^|]+$, ascii_only=None)], ...])

  • source (RuleSource)

  • extracted_by (LLMProvenance)

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

  • definition_reviewed_at (date)

rule_id: _StableId
manual_id: ManualId
year: _YearField
part: ManualPart
chapter_id: _StableId
section_id: _StableId
kind: RuleKind
statement: str
applies_when: str | None
references_casillas: tuple[ManualCasillaReference, ...]
references_sections: tuple[_StableId, ...]
source: RuleSource
extracted_by: LLMProvenance
definition_reviewed_by: _Reviewer
definition_reviewed_at: date
class Section(**data)[source]

Bases: _ManualStrictFrozen

A structured section of a handbook chapter.

Parameters:

  • section_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • chapter_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • title (str)

  • summary (str)

  • prose (tuple[Paragraph, ...])

  • rules (tuple[Rule, ...])

  • references_sections (tuple[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)], ...])

  • references_legal_acts (tuple[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=256, pattern=^[A-Z0-9-][^|]*\|[^|]+$, ascii_only=None)], ...])

  • source (SectionSource)

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

  • definition_reviewed_at (date)

section_id: _StableId
chapter_id: _StableId
title: str
summary: str
prose: tuple[Paragraph, ...]
rules: tuple[Rule, ...]
references_sections: tuple[_StableId, ...]
source: SectionSource
definition_reviewed_by: _Reviewer
definition_reviewed_at: date
class Chapter(**data)[source]

Bases: _ManualStrictFrozen

A handbook chapter: metadata plus ordered section references.

Parameters:

  • chapter_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=^[a-z0-9][a-z0-9-]*$, ascii_only=None)])

  • title (str)

  • summary (str)

  • sections (tuple[SectionRef, ...])

chapter_id: _StableId
title: str
summary: str
sections: tuple[SectionRef, ...]
class Manual(**data)[source]

Bases: _ManualStrictFrozen

Root record for a single (manual_id, year, part) volume.

Parameters:

  • manual_id (ManualId)

  • year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2100)])])

  • part (ManualPart)

  • title (str)

  • summary (str)

  • source_pdf_url (AnyHttpUrl)

  • source_html_url (AnyHttpUrl | None)

  • fetched_at (datetime)

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

  • definition_reviewed_at (date)

  • chapters (tuple[Chapter, ...])

manual_id: ManualId
year: _YearField
part: ManualPart
title: str
summary: str
source_pdf_url: AnyHttpUrl
source_html_url: AnyHttpUrl | None
fetched_at: datetime
definition_reviewed_by: _Reviewer
definition_reviewed_at: date
chapters: tuple[Chapter, ...]
class ManualCatalogue(**data)[source]

Bases: _ManualStrictFrozen

Aggregate view of all chapters and sections in a manual.

Parameters:

manuals (tuple[Manual, ...])

manuals: tuple[Manual, ...]
class FetchedManualPart(**data)[source]

Bases: _ManualStrictFrozen

Result of a successful manual fetch and validation.

Parameters:

  • manual_id (ManualId)

  • year (int)

  • part (ManualPart)

  • source_pdf_url (AnyHttpUrl)

  • relative_pdf_path (str)

  • sha256 (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[a-f0-9]{64}$, ascii_only=None)])

  • content_length (int)

  • fetched_at (datetime)

  • synthetic (bool)

manual_id: ManualId
year: int
part: ManualPart
source_pdf_url: AnyHttpUrl
relative_pdf_path: str
sha256: _Sha256
content_length: int
fetched_at: datetime
synthetic: bool