aeat.application.verification._schema module

Strict pydantic v2 records for declaración verification verdicts.

Defines the closed schema returned by aeat.application.verification.verify_declaracion(): DiscrepancyCause, VerificationStatus, ClassifiedDiscrepancy, and the top-level VerificationVerdict. Every model is frozen, strict, and rejects extra keys so that the operator’s UI and any persisted verdict survive an end-to-end JSON round trip without drift.

The VerificationVerdict.period field is typed as the canonical Period value object (filing_year + code), serialising to {"filing_year": YYYY, "code": "1T"} in JSON.

See also

VerificationVerdict, ClassifiedDiscrepancy, DiscrepancyCause, and VerificationStatus.

class DiscrepancyCause(*values)[source]

Bases: StrEnum

Cause classification for a printed-vs-computed value mismatch.

The categories mirror the local verification classifier in aeat.application.verification.verify_declaracion(); they are not remote AEAT status values.

Variables:

  • EXTRACTION_UNRELIABLE – The extractor warned about this casilla (bbox fallback, ambiguous label, unparseable value, missing casilla). The operator should re-check the source PDF.

  • ROUNDING – Small delta within 10 * tolerance on a computed casilla. Non-blocking.

  • UNMODELLED_RULE – The registry snapshot does not model this casilla. Verification cannot be marked complete until the gap is reviewed.

  • CORRECTNESS_DIVERGENCE – Material disagreement — likely an extractor bug or a formula bug. Requires operator review.

EXTRACTION_UNRELIABLE
ROUNDING
UNMODELLED_RULE
CORRECTNESS_DIVERGENCE
class VerificationStatus(*values)[source]

Bases: StrEnum

Operator-facing single-word verdict.

Variables:
VERIFIED
NEEDS_REVIEW
class ClassifiedDiscrepancy(**data)[source]

Bases: BaseModel

One discrepancy with its cause classification and operator-facing rationale.

Variables:

  • casilla_id – CasillaId of the casilla that diverged.

  • expected – The value the formula engine derived.

  • actual – The value extracted from the printed PDF.

  • delta – actual - expected (signed).

  • cause – The DiscrepancyCause category the operator uses to route the next action.

  • cause_rationale – Multilingual human-readable explanation surfaced in the UI.

Parameters:
casilla_id: CasillaId
expected: Decimal
actual: Decimal
delta: Decimal
cause: DiscrepancyCause
cause_rationale: str
class VerificationVerdict(**data)[source]

Bases: BaseModel

Persisted calc-verification verdict for one imported filing.

Variables:

  • modelo – AEAT modelo identifier.

  • period – The filing Period (year + registry code).

  • registry_snapshot_id – Identifier of the RegistrySnapshot used for the audit.

  • verification_expectation_ids – Registry expectation ids that governed the verdict.

  • status – The VerificationStatus summarising the verdict.

  • discrepancies – Every ClassifiedDiscrepancy produced by the engine audit.

  • coverage – Fraction of the registry casillas the extraction supplied, in the inclusive 0.0..1.0 range.

  • externally_grounded_casilla_ids – The reconciled casillas (from computed_casilla_ids or reconcile_when_present_casilla_ids) whose reconciliation is backed by an AEAT-authoritative independent oracle expected value, rather than only the app’s own engine. Registry-declared data; see externally_grounded_casilla_ids.

  • independently_grounded_fraction – Fraction of the reconciled casilla set that is externally grounded, in the inclusive 0.0..1.0 range. A grounding-depth signal, not a correctness score: a low value means most reconciliation was engine-only, not that the filing is wrong.

  • narrative – Multilingual user-facing summary string.

  • verified_at – UTC timestamp of when the verdict was produced.

Parameters:
modelo: str
period: Period
registry_snapshot_id: str
verification_expectation_ids: tuple[str, ...]
status: VerificationStatus
discrepancies: tuple[ClassifiedDiscrepancy, ...]
coverage: float
externally_grounded_casilla_ids: tuple[CasillaId, ...]
independently_grounded_fraction: float
narrative: str
verified_at: datetime