aeat.application.ledger._llm_suggestions module

LLM ledger classification suggestion/result contracts.

These strict frozen DTOs carry the reviewable output of the governed ledger LLM workflow: stage-1 business classification suggestions, saturated IVA category suggestions with system-derived tax substrate, evidence-driven split proposals, provider availability rows, and explicit rejection receipts. They are application-layer contracts only; classifier engines and prompt parsing live in transactions, while persistence and audit events are handled by the application services that consume these records.

The contracts preserve the review loop required by the LLM ADRs: a suggestion is not persisted until the operator applies it, a rejection records an audit event without mutating the transaction, and regulated euro amounts / IVA rates are derived by the system rather than emitted by the model.

See also

_llm_classification

Application service that builds, applies, saturates, splits, and rejects these suggestions.

suggest_llm_classification()

Stage-1 suggestion path that persists nothing.

saturate_llm_classification()

Path that adds model-selected IVA category plus system-derived substrate.

suggest_evidence_split()

Evidence-driven split/no-split proposal builder.

reject_llm_suggestion()

Audit-trailed rejection terminal for any suggestion kind.

_ledger_llm_payloads

CLI JSON-envelope projections for suggest, saturate, and reject paths.

LLMClassificationResponse

Domain classifier response projected into LLMClassificationSuggestion.

LLMSplitResponse

Domain split response projected into LLMSplitSuggestion.

class LLMProvider(*values)[source]

Bases: StrEnum

Subprocess LLM provider names accepted by the classify surface.

CLAUDE
ANTIGRAVITY
CODEX
class LLMClassificationSuggestion(**data)[source]

Bases: BaseModel

One LLM classification suggestion for a transaction, not yet persisted.

Parameters:
transaction_id: str
provider: LLMProvider | None
provenance: str
classification: BusinessClassification
category: SpendingCategory | None
confidence: Decimal
reason: str
evidence_id: str | None
multiple_components: bool | None

True when the evidence read judged a split may be warranted.

property recommends_split: bool

True when the evidence read flagged the invoice as multi-component.

class LLMProviderAvailability(**data)[source]

Bases: BaseModel

Whether one subprocess LLM provider has a usable CLI on PATH.

Parameters:
provider: LLMProvider
cli_binary: str
available: bool
resolved_path: str | None
class LLMSaturatedSuggestion(**data)[source]

Bases: BaseModel

A saturated LLM suggestion: business decision plus grounded tax substrate.

Parameters:
transaction_id: str
provider: LLMProvider | None
provenance: str
classification: BusinessClassification
category: SpendingCategory | None
confidence: Decimal
reason: str
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_id: str | None
evidence_advisory: str
multiple_components: bool | None

True when the evidence read judged a split may be warranted.

property recommends_split: bool

True when the evidence read flagged the invoice as multi-component.

class OperatorIvaDerivationResult(**data)[source]

Bases: BaseModel

Result of an operator-initiated IVA derivation for one transaction.

Parameters:
transaction_id: str
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)[source]

Bases: BaseModel

One reviewed child of an evidence-driven split, with derived numbers.

Parameters:
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)[source]

Bases: BaseModel

An evidence-driven N-way split proposal with derived child amounts.

Parameters:
transaction_id: str
provider: LLMProvider | None
provenance: str
reason: str
parent_amount: Decimal
children: tuple[LLMSplitChildSuggestion, ...]
evidence_id: str | None
property recommends_split: bool

True when the model proposed more than one child.

class LLMSplitApplyResult(**data)[source]

Bases: BaseModel

Outcome of applying a reviewed evidence-driven split.

Parameters:

  • bucket_id (str)

  • parent_transaction_id (str)

  • split_group_id (str)

  • child_transaction_ids (tuple[str, ...])

  • provenance (str)

  • classified_child_count (int)

bucket_id: str
parent_transaction_id: str
split_group_id: str
child_transaction_ids: tuple[str, ...]
provenance: str
classified_child_count: int
class LLMSuggestionRejectionResult(**data)[source]

Bases: BaseModel

Outcome of explicitly rejecting an LLM suggestion.

Parameters:

  • bucket_id (str)

  • transaction_id (str)

  • bucket_event_id (str)

  • suggestion_kind (str)

  • provenance (str)

  • operator_reason (str)

bucket_id: str
transaction_id: str
bucket_event_id: str
suggestion_kind: str
provenance: str
operator_reason: str