cadrumo.application.ledger.document_transcription module

The faithful text representation a document ingestion produces at stage S1.

The acquisition stage of the ingestion pipeline turns a document’s bytes into one typed record: reading-order text with the document’s own printed forms preserved, the page count, the content address of the bytes it was read from, and the identity of whatever transcribed it. Everything downstream – semantic extraction, anchor grounding, classification – reads this record rather than the bytes, so it is the seam the whole pipeline is anchored to.

One record, not a union. A text-layer read and a vision read differ in their TranscriberIdentity, never in their type. A tagged union would push a branch into every consumer for a distinction only provenance cares about, and would let a consumer forget the branch that matters.

Printed forms are preserved literally. 2.420,00 stays 2.420,00; it is never normalised to 2420.00 on the way in. The grounding stage verifies a candidate value by finding its verbatim anchor in this text, so normalising here would delete the evidence the anchor check runs against – and the corpus scores against printed form. Nothing in this module transforms :attr:` DocumentTranscription.text`.

CRITICAL (sensitive-financial-data-secure-storage-only): the transcription of an invoice is the invoice, in a shape a grep can read. This record holds it in process memory ONLY and carries the same serialization tripwires as EvidenceInput – model_dump, model_dump_json, iteration and pickling all raise, so a stray persistence call fails loudly rather than writing taxpayer financial data out in the clear.

ACQUISITION_ORIGINS

The origins stage S1 can actually produce.

Derived from the closed core taxonomy rather than restated as strings, so a new FieldOrigin member cannot silently become an acquisition origin. EXACT_STRUCTURED values come from a machine-readable record that needs no transcription at all, TABULAR_MAPPED from a column-role mapping, and OPERATOR from a human at the confirm boundary – none of the three transcribes a document, so none may stamp a transcription.

class TranscriberIdentity(**data)[source]

Bases: BaseModel

Who produced a transcription, at what revision.

Every axis is required for both origins, and none has a default. A provenance stamp that can be constructed without naming its producer is a stamp that will eventually be constructed wrong: a hardcoded default would let a transcription claim a reader it did not come from, which is exactly the class of lie a provenance record exists to make impossible. The transport is required for the same reason and it is the sharper case – a defaulted transport would let an off-host read claim it never left the machine, and that claim is the one a consent withdrawal rests on.

The revision is load-bearing rather than decorative. A transcription produced by one model under one prompt revision is not interchangeable with one produced by the same model under another.

Variables:

  • origin – Which acquisition path read the document – TEXT_LAYER for the deterministic extraction, VISION for a local vision model in transcription role. Constrained to ACQUISITION_ORIGINS.

  • name – The concrete reader, e.g. a deterministic extractor’s name or a vision model’s identifier. Never a coarse label like local: the point is to know which reader’s output is being trusted.

  • transport –

    Where the read ran, as the one canonical transport token (provenance_transport_label()). A transcription is a durable artefact derived from the document, so one produced off-host is an artefact a consent withdrawal must enumerate – and a model identifier reveals its vendor only to a reader who already knows the catalogue.

    Its own axis rather than folded into name, which is where it started: name is contracted to say WHICH reader produced the text and explicitly not to carry a coarse label, so smuggling the transport through it broke that contract and created a third provenance grammar nothing could parse. Recorded as data, nothing has to parse it at all.

  • revision – The reader’s version – an extractor release, or a model’s weights-plus-prompt revision.

Parameters:

data (Any)

origin: FieldOrigin
name: str
transport: str
revision: str
class DocumentTranscription(**data)[source]

Bases: BaseModel

A document’s faithful reading-order text plus the provenance to cite it.

In-memory only; see the module docstring for the custody contract.

Variables:

  • text – The document’s reading-order text with printed forms preserved verbatim. FINANCIAL: this is the document’s contents in readable form, so it is excluded from repr.

  • page_count – How many pages were read. At least one – a transcription of no pages is a failed read, not an empty success.

  • source_content_sha256 – 64-character lowercase hex SHA-256 content address of the source bytes. Identical bytes reached through different evidence records or attachments resolve to one transcription.

  • transcriber – Which reader produced this text, at which revision.

Parameters:

data (Any)

text: str
page_count: int
source_content_sha256: ContentDigest
transcriber: TranscriberIdentity