cadrumo.entrypoints.tui.ledger.models module

Immutable presentation records for the host-neutral Ledger workspace.

declared_ledger_destination_ids()

Read the internal closed destination set from its defining type alias.

Defined beside the alias it reads rather than beside a consumer, so the set and its declaration cannot drift apart.

Return type:

frozenset[str]

LEDGER_DESTINATION_BY_AREA: Final[dict[LedgerWorkspaceArea, LedgerDestinationIdV1]]

The one pairing of workspace area to internal destination.

Declared here rather than beside either consumer because both need it and the route catalogue imports the controller, so neither module can own it.

It used to be written twice: once in the route catalogue, whose totality gate checked it, and once in the controller behind a cast to this alias. A cast asserts rather than validates, so the controller copy was checked by nothing at all – not by the type checker, which believed the assertion, and not by the route gate, which never read it. A destination misspelled there stayed invisible until an operator selected that area and the route lookup raised KeyError; a destination swapped between two areas surfaced as a disagreement refusal at the same moment. Both are import-time facts about a closed set, so they are settled at import now.

class LedgerRouteTargetV1(**data)

Bases: BaseModel

One internal destination selected by its stable area identity.

Parameters:

data (Any)

destination: LedgerDestinationIdV1

area: LedgerWorkspaceArea

class LedgerRouteRefusalV1(**data)

Bases: BaseModel

A route that cannot be opened, preserving the authority that refused it.

Parameters:

data (Any)

target: LedgerRouteTargetV1

availability: LedgerWorkspaceAvailability

reason_key: str

class LedgerEntryRowV1(**data)

Bases: BaseModel

Safe entry row containing no description, amount, counterparty, or evidence.

Parameters:

data (Any)

transaction_id: TransactionId

review_status: str

source: LedgerWorkspaceEntryRefV1

class LedgerReviewRowV1(**data)

Bases: BaseModel

A reviewable transaction plus the canonical read action naming its door.

Parameters:

data (Any)

transaction_id: TransactionId

review_status: str

action: ActionReference

source: LedgerWorkspaceEntryRefV1

class LedgerFlowState(*values)

Bases: StrEnum

Explicit state of a command-backed Ledger interaction.

EDITING

CONFIRMING

SUBMITTING

SUCCEEDED

FAILED

CANCELLED

class LedgerClassificationSubmissionV1(**data)

Bases: BaseModel

Catalogue-authorized canonical classification patch submission.

Parameters:

data (Any)

action: ActionReference

transaction_id: TransactionId

patch: ManualLedgerTransactionPatch

class LedgerClassificationSubmitterV1(*args, **kwargs)

Bases: Protocol

Injected application door for a classification mutation.

class LedgerExclusionSubmissionV1(**data)

Bases: BaseModel

Catalogue-authorized request to exclude one reviewed entry from filing.

Parameters:

data (Any)

action: ActionReference

transaction_id: TransactionId

class LedgerExclusionSubmitterV1(*args, **kwargs)

Bases: Protocol

Injected application door that marks one entry reviewed and excluded.

class LedgerImportSourceKind(*values)

Bases: StrEnum

What an operator-chosen file holds, which decides the door that reads it.

BANK_STATEMENT

INVOICES_RECEIVED

INVOICES_ISSUED

class LedgerImportRequestV1(**data)

Bases: BaseModel

One operator-chosen file or folder and how to read it.

provider applies to a bank statement and country to an invoice book; each is ignored by the other kind rather than guessed for it.

Parameters:

data (Any)

path: Path

source_kind: LedgerImportSourceKind

provider: LedgerProviderID

country: str | None

class LedgerImportFileRefusalV1(**data)

Bases: BaseModel

One file of a folder that could not be read, with the reason it gave.

Parameters:

data (Any)

file_name: str

reason: str

class LedgerImportRowRefusalV1(**data)

Bases: BaseModel

One invoice-book row the importer refused, by its spreadsheet row number.

Parameters:

data (Any)

row_number: int

field: str

reason: str

class LedgerImportOutcomeV1(**data)

Bases: BaseModel

What a preview or an applied import reports, in the operator’s terms.

imported and skipped are None when the preview cannot measure them: an invoice book is only resolved against the catalogue as it is written, so its preview counts rows and columns and says nothing more.

Parameters:

data (Any)

source_kind: LedgerImportSourceKind

dry_run: bool

files: int

rows: int

imported: int | None

skipped: int | None

likely_duplicates: int

diagnostics: tuple[str, ...]

refused_files: tuple[LedgerImportFileRefusalV1, ...]

refused_rows: tuple[LedgerImportRowRefusalV1, ...]

unmapped_columns: tuple[str, ...]

class LedgerImportDoorV1(*args, **kwargs)

Bases: Protocol

Injected application door that previews and then applies one import.

async preview(request)

Read the source and report what applying it would do, writing nothing.

Return type:

LedgerImportOutcomeV1

Parameters:

request (LedgerImportRequestV1)

async apply(request)

Write the source into the operator’s ledger or invoice catalogue.

Return type:

LedgerImportOutcomeV1

Parameters:

request (LedgerImportRequestV1)

class LedgerInvoiceClassChoice(*values)

Bases: StrEnum

The invoice classes an operator may state; the registry resolves each token.

ORDINARIA

SIMPLIFICADA

RECTIFICATIVA

class LedgerInvoiceEntryV1(**data)

Bases: BaseModel

One invoice as the operator typed it, already parsed into typed values.

Legal checks – the NIF format, the IVA slot for the date, the retention consistency – are the application writer’s, so nothing here pre-judges them; this only carries what was entered.

Parameters:

data (Any)

kind: InvoiceKind

counterparty_name: str

counterparty_nif: str | None

country_code: str

invoice_number: str

invoice_date: date

taxable_base: Decimal

iva_rate: Decimal | None

currency: str

retention_rate: Decimal | None

retention_amount: Decimal | None

invoice_class: LedgerInvoiceClassChoice

series: str | None

notes: str

class LedgerInvoiceAddResultV1(**data)

Bases: BaseModel

Identity and totals of the invoice the writer recorded.

Parameters:

data (Any)

invoice_id: InvoiceId

invoice_number: str

base_total: Decimal

iva_total: Decimal

grand_total: Decimal

currency: str

class LedgerInvoiceAddDoorV1(*args, **kwargs)

Bases: Protocol

Injected application door that records one catalogue invoice.

class LedgerEvidenceRecordStatus(*values)

Bases: StrEnum

Where one registered document stands; unmeasured is not the same as awaiting.

AWAITING

CONFIRMED

DECLINED

UNMEASURED

class LedgerEvidenceRecordRowV1(**data)

Bases: BaseModel

One locally registered purchase-invoice document and where it stands.

Parameters:

data (Any)

evidence_id: str

media_kind: str

file_name: str

supplier: str | None

invoice_number: str | None

created_at: str

status: LedgerEvidenceRecordStatus

class LedgerReaderReadinessV1(**data)

Bases: BaseModel

Whether documents can be read on this machine, as the reader reports it.

Parameters:

data (Any)

extraction_ready: bool

failed_condition_id: str | None

class LedgerEvidenceDraftV1(**data)

Bases: BaseModel

What the on-host reader found in one document, as display text.

None is a field the reader could not ground in the document; it is shown as unread, never as zero.

Parameters:

data (Any)

evidence_id: str

supplier_name: str | None

supplier_tax_id: str | None

invoice_number: str | None

invoice_date: str | None

taxable_base: str | None

iva_rate: str | None

iva_amount: str | None

grand_total: str | None

currency: str | None

suggested_kind: InvoiceKind | None

discrepancies: int

class LedgerEvidenceConfirmationV1(**data)

Bases: BaseModel

The operator’s answers that confirm one read document as an invoice.

Parameters:

data (Any)

evidence_id: str

kind: InvoiceKind

country_code: CountryCodeAlpha2

counterparty_name: str | None

class LedgerEvidenceConfirmedV1(**data)

Bases: BaseModel

The invoice a confirmation recorded, or found already recorded.

Parameters:

data (Any)

invoice_id: InvoiceId

invoice_number: str

grand_total: Decimal

currency: str

created: bool

printed_total_disagrees: bool

class LedgerEvidenceDoorV1(*args, **kwargs)

Bases: Protocol

Injected application door over the operator’s local invoice evidence.

list_records()

Read every registered document with its confirmation state.

Return type:

tuple[LedgerEvidenceRecordRowV1, ...]

async add(source_path)

Register one PDF or image file as evidence, storing its bytes securely.

The path travels as typed: the service resolves it for byte access and records the operator’s own spelling as provenance.

Return type:

LedgerEvidenceRecordRowV1

Parameters:

source_path (str)

reader_readiness()

Measure the local document reader without starting or loading anything.

Return type:

LedgerReaderReadinessV1

async extract(evidence_id)

Read one stored document on this machine; nothing is recorded.

Return type:

LedgerEvidenceDraftV1

Parameters:

evidence_id (str)

async confirm(confirmation)

Re-read the document and record it as an invoice through the sole writer.

Return type:

LedgerEvidenceConfirmedV1

Parameters:

confirmation (LedgerEvidenceConfirmationV1)

class LedgerEvidenceRowV1(**data)

Bases: BaseModel

Safe application evidence-review metadata with its declared read action.

Parameters:

data (Any)

attachment_id: str

mime_type: str

bytes_size: int

captured_at: str

pending_review: bool

action: ActionReference

source: AttachmentReviewItem

class LedgerLinkSubmissionV1(**data)

Bases: BaseModel

Catalogue-authorized local invoice/transaction link request.

Parameters:

data (Any)

action: ActionReference

transaction_id: TransactionId

invoice_id: InvoiceId

class LedgerLinkResultV1(**data)

Bases: BaseModel

Safe identity-only acknowledgement returned by an injected link door.

Parameters:

data (Any)

transaction_id: TransactionId

invoice_id: InvoiceId

class LedgerLinkSubmitterV1(*args, **kwargs)

Bases: Protocol

Injected application door for one admitted local Ledger link.