aeat.application.ledger._evidence_draft module¶

On-host invoice-PDF field extraction into a typed draft.

Given an EvidenceInput already resolved from secure storage (see _evidence_input), extract_invoice_fields() runs the in-tree on-host text-layer extractor (extract_evidence_text()) and applies grounded heuristics – the shared Spanish tax-id validator (validate_spanish_tax_id()), the shared day-first date parser (parse_date()), and the shared European decimal separator normaliser (normalize_decimal_separators()) – to recover a supplier NIF/NIE/CIF, invoice number, invoice date, taxable base, IVA rate, IVA amount, and grand total.

This is the extraction PRIMITIVE only: it returns an InvoiceDraft the operator reviews and confirms. It never persists an Invoice and never guesses a value it cannot ground in the extracted text – every field it cannot recover is left None rather than fabricated (no-silent-under-declaration in spirit: an unconfident field is absent, not invented).

Everything here runs on-host and in-memory only. The evidence bytes and the extracted text never touch disk and are never sent to a cloud provider or an LLM (sensitive-financial-data-secure-storage-only, 2026-06-10-llm-evidence-classification-adr). This module makes no network call and performs no filesystem write.

A scan-only PDF (no embedded text layer) or an image attachment has nothing for extract_invoice_fields() to read, so extract_invoice_draft_from_evidence() falls back to the on-host LOCAL vision reader (_evidence_draft_vision) – the same rasterise-then-read-with-Ollama transport LocalVisionLLMClassifier already uses for classification, gated by LLM_VISION and never a cloud call. When on-host vision reading is disabled for the profile, or the local Ollama runtime is unreachable, the caller gets a typed, instructive refusal – never a silent empty draft.

extract_invoice_draft_from_evidence() is the CLI-facing wiring layer: it resolves an already-stored purchase_invoice_evidence record or a linked attachment_id to its in-memory bytes (through the private evidence-input resolvers resolve_purchase_invoice_evidence_input() and resolve_attachment_evidence_input()) and runs extract_invoice_fields() over them, falling back to the on-host vision reader for scan-only PDFs and images, so aeat app ledger evidence extract needs only a bucket id plus one of the two reference ids.

confirm_invoice_draft_from_evidence() is the non-interactive CONFIRM step that closes the review loop: it re-runs the on-host extraction, applies any operator-supplied field overrides (extraction is best-effort – every field may be corrected), and delegates the actual write to create_catalogue_invoice() – the sole sanctioned Invoice writer (composition-service-no-parallel-write-path). A confirm keyed on the same evidence/attachment reference and the same resolved fields is a guarded no-op that returns the existing invoice rather than raising or duplicating (single-subject-mutation-is-idempotent-guarded); a same-reference confirm whose resolved fields genuinely differ from the already-stored invoice mints a second, distinct invoice record (a different content-derived invoice_id) rather than silently overwriting one filer’s data with another’s.

Confirming also auto-links the source evidence to the resulting invoice: link_attachment_invoice() appends the invoice’s id to the backing Attachment’s linked_invoice_ids, closing the provenance loop in both directions (the invoice is discoverable from the evidence, and the evidence is the invoice’s traceable source). The link is re-asserted on a guarded no-op confirm too, so a re-confirm never regresses a provenance link that was never wired for older evidence, and the append itself is idempotent (dedup on the linked-ids tuple).