cadrumo.application.ledger.llm_classification_ports module

Application boundary for supervised ledger LLM classification.

class LLMClassificationSuggestion(**data)

Bases: BaseModel

A reviewable LLM classification that has not been persisted.

Parameters:

data (Any)

transaction_id: TransactionId

provenance: str

classification: BusinessClassification

category: SpendingCategory | None

confidence: Decimal

reason: str

evidence_id: str | None

multiple_components: bool | None

property recommends_split: bool

Return whether the suggestion contains multiple components.

class LLMSaturatedSuggestion(**data)

Bases: LLMClassificationSuggestion

A classification review with system-derived IVA substrate.

Parameters:

• transaction_id (TransactionId)

• provenance (Annotated[str, MinLen(min_length=1)])

• classification (BusinessClassification)

• category (SpendingCategory | None)

• confidence (Decimal)

• reason (Annotated[str, MinLen(min_length=1)])

• evidence_id (str | None)

• multiple_components (bool | None)

iva_category: IvaCategory | None

business_pct: Decimal | None

iva_rate: Decimal | None

taxable_base: Decimal | None

iva_amount: Decimal | None

rate_derivable: bool

derivation_note: str

evidence_advisory: str

class OperatorIvaDerivationResult(**data)

Bases: BaseModel

Outcome of an operator-selected IVA category derivation.

Parameters:

data (Any)

transaction_id: TransactionId

iva_category: IvaCategory

derivable: bool

iva_rate: Decimal | None

taxable_base: Decimal | None

iva_amount: Decimal | None

note: str

result: ManualLedgerTransactionResult | None

class LLMSplitChildSuggestion(**data)

Bases: BaseModel

One reviewable evidence-driven split child.

Parameters:

data (Any)

proportion: Decimal

amount: Decimal

description: str

category: SpendingCategory | None

iva_category: IvaCategory | None

iva_rate: Decimal | None

taxable_base: Decimal | None

iva_amount: Decimal | None

rate_derivable: bool

derivation_note: str

evidence_citation: str

class LLMSplitSuggestion(**data)

Bases: BaseModel

Reviewable evidence-driven split proposal.

Parameters:

data (Any)

transaction_id: TransactionId

provenance: str

reason: str

parent_amount: Decimal

children: tuple[LLMSplitChildSuggestion, ...]

evidence_id: str | None

property recommends_split: bool

Return whether this proposal contains more than one child.

class LLMSplitApplyResult(**data)

Bases: BaseModel

Result of persisting an evidence-driven transaction split.

Parameters:

data (Any)

bucket_id: BucketId

parent_transaction_id: TransactionId

split_group_id: str

child_transaction_ids: tuple[str, ...]

provenance: str

classified_child_count: int

class LLMSuggestionRejectionResult(**data)

Bases: BaseModel

Result of persisting an operator rejection of an LLM suggestion.

Parameters:

data (Any)

bucket_id: BucketId

transaction_id: TransactionId

bucket_event_id: str

suggestion_kind: str

provenance: str

operator_reason: str

class EvidenceImage(**data)

Bases: BaseModel

Transient evidence image prepared for an application-owned reader port.

Parameters:

data (Any)

content_sha256: ContentDigest

base64_data: str

media_type: ImageMediaType

classmethod from_base64(base64_data, media_type)

Build an evidence image while recording its content digest.

Return type:

EvidenceImage

Parameters:

• base64_data (str)

• media_type (ImageMediaType)

class ResolvedEvidenceInput(evidence_input, reference)

Bases: object

Document bytes and stable reference supplied by outer composition.

Parameters:

• evidence_input (EvidenceInput)

• reference (str)

evidence_input: EvidenceInput

reference: str

class VisionClassifier(*args, **kwargs)

Bases: Protocol

Read-only classifier port for evidence-backed vision suggestions.

property decided_by: str

Return the stable identity of the classifier implementation.

classify(transaction, *, evidence_images)

Classify one transaction using the supplied evidence images.

Return type:

LLMClassificationResponse

Parameters:

• transaction (Transaction)

• evidence_images (tuple[EvidenceImage, ...])

propose_split(transaction, *, evidence_images)

Propose evidence-driven children for one transaction.

Return type:

LLMSplitResponse

Parameters:

• transaction (Transaction)

• evidence_images (tuple[EvidenceImage, ...])

class LLMClassificationPorts(resolve_evidence_input, text_layer_ports, rasterise_pdf, make_text_classifier, make_vision_classifier, run_reader, record_classifier_run)

Bases: object

Outer-owned I/O required by the ledger LLM review use case.

Parameters:

• resolve_evidence_input (Callable[[str, str | None, tuple[str, ...]], ResolvedEvidenceInput])

• text_layer_ports (EvidenceTextLayerPorts)

• rasterise_pdf (Callable[[bytes], tuple[str, ...]])

• make_text_classifier (Callable[[PromptSpec], LLMClassifier])

• make_vision_classifier (Callable[[PromptSpec, str | None], VisionClassifier])

• run_reader (Callable[[ModelRole, Callable[[], object]], object])

• record_classifier_run (Callable[[Callable[[], object], str], object])

resolve_evidence_input: Callable[[str, str | None, tuple[str, ...]], ResolvedEvidenceInput]

text_layer_ports: EvidenceTextLayerPorts

rasterise_pdf: Callable[[bytes], tuple[str, ...]]

make_text_classifier: Callable[[PromptSpec], LLMClassifier]

make_vision_classifier: Callable[[PromptSpec, str | None], VisionClassifier]

run_reader: Callable[[ModelRole, Callable[[], object]], object]

record_classifier_run: Callable[[Callable[[], object], str], object]