cadrumo.application.ledger.llm_review_workflow module

Typed vocabulary for the one ledger LLM review workflow.

The ledger LLM classify surface exposes several operator intents — suggest, apply, saturate-and-apply, reject, and evidence-driven split — whose durable writes are owned by the canonical ledger persistence primitives in llm_classification. Historically each primitive accepted a free-text source_command keyword defaulting to a CLI spelling ("aeat app ledger classify --llm --reject" and siblings) inside application code, so audit provenance could silently default to a command string the application layer should not know or own.

This module defines the typed spine that removes that default: a mandatory LlmReviewInvocationOrigin (the operator intent), the LlmReviewDecision terminals. The canonical CLI source_command spelling is derived from the origin (LlmReviewInvocationOrigin.source_command), never defaulted in an application function signature — so a caller must always name its origin and the audit label follows from it. classify --auto-split and split --llm share this vocabulary while retaining distinct origins.

The review workflow that consumes this vocabulary and delegates to the ledger persistence authorities is built on top of these types.

class LlmReviewInvocationOrigin(*values)[source]

Bases: StrEnum

Mandatory provenance for one ledger LLM review invocation.

Each member is a distinct operator intent routed into the shared review workflow. The member value is a stable, CLI-spelling-independent token; the human-facing source_command audit label is derived from the member via source_command, so application code never carries a defaulted CLI string. CLASSIFY_AUTO_SPLIT and SPLIT_LLM are deliberately distinct origins for the two CLI routes that share the split workflow.

CLASSIFY_LLM_APPLY
CLASSIFY_LLM_REJECT
CLASSIFY_LLM_SATURATE_APPLY
CLASSIFY_IVA_CATEGORY_SATURATE
CLASSIFY_AUTO_SPLIT
SPLIT_LLM
property source_command: str

Return the canonical operator-facing CLI source_command audit label.

The mapping is total over the enum: a new origin without a spelling raises KeyError at first use, so the audit label can never be silently blank.

class LlmReviewDecision(*values)[source]

Bases: StrEnum

The terminal decision an operator reaches on an LLM review subject.

APPLY approves and writes; REJECT records an audit-trailed decline that mutates nothing; SPLIT is the evidence-driven split verdict.

APPLY
REJECT
SPLIT
class ReviewedInvoiceDraft(**data)[source]

Bases: BaseModel

A read invoice draft awaiting the operator’s apply-or-decline.

Carries no confidence, and that is the point. Its three sibling suggestion models each require a Decimal confidence, and the ingestion decision forbids a numeric confidence anywhere in this chain: a model’s self-assessed certainty is not evidence, and a number beside a field invites an operator to treat one reading as more checked than another when nothing checked either. The prohibition is load-bearing rather than stylistic, so the subject type is confidence-free by construction instead of carrying the field and leaving it unset.

Keyed by the evidence it was read from rather than by a transaction. A draft exists before any ledger row does – that is what the operator is deciding about – so requiring a transaction id here would be requiring the answer to the question under review.

Variables:

  • evidence_reference – The evidence or attachment id the draft was read from, and the key its store is addressed by.

  • draft – The proposed fields, exactly as the reader produced them.

  • extractor – Which reader produced it.

  • read_transports – Every transport that carried the reading, so a withdrawal can classify what an apply persists.

  • provenance – The reader’s own stamp, carried for the audit trail.

Parameters:

data (Any)

evidence_reference: str
draft: InvoiceDraft
extractor: str
read_transports: tuple[str, ...]
provenance: str
class InvoiceDraftDeclineResult(**data)[source]

Bases: BaseModel

The durable trace of an operator declining a read draft.

Distinct from LLMSuggestionRejectionResult, which is keyed by the transaction its suggestion targeted. A declined draft has no transaction – that is what was not created – so reusing that shape would have required inventing one.

Variables:

  • bucket_id – The profile bucket the decision was taken in.

  • evidence_reference – Which read was declined.

  • bucket_event_id – The audit event this decline emitted.

  • provenance – The reader stamp of the declined draft.

  • operator_reason – What the operator said, when they said anything.

Parameters:

data (Any)

bucket_id: BucketId
evidence_reference: str
bucket_event_id: str
provenance: str
operator_reason: str
execute_reviewed_decision(suggestion, *, origin, decision, bucket_id, business_pct=None, reason='', actor='operator', ports=None, occurred_at=None, settings=None)[source]

Route one reviewed LLM suggestion to its canonical persistence authority.

This is the single persisting decision terminal of the review workflow. It introduces no write path: each branch delegates to the existing canonical ledger primitive (apply_llm_classification(), apply_saturated_llm_classification(), apply_evidence_split(), reject_llm_suggestion()), and the durable source_command audit label is derived from the mandatory origin rather than defaulted inside application code.

A decision/suggestion shape mismatch (e.g. SPLIT on a non-split suggestion) raises TransactionValidationError.

Return type:

TypeAliasType

Parameters: