cadrumo.application.ledger.llm_diagnostics_ports module

Application-owned read capabilities for ledger LLM diagnostics.

The diagnostics projection aggregates two existing stores, but it does not own either store’s persistence details. The application boundary therefore names only the accounting facts it needs and lets an executable composition root translate concrete records and failures before they cross inward.

class LlmUsageDiagnosticRecord(provider, input_tokens, output_tokens, cost_estimate_usd, cache_hit)[source]

Bases: object

Accounting-only usage fact supplied by an outer reader.

Response text, request identifiers, and other transport/storage fields are intentionally absent: the diagnostics use case has no reason to receive them, and the DTO keeps that boundary explicit.

Parameters:

  • provider (str)

  • input_tokens (int)

  • output_tokens (int)

  • cost_estimate_usd (Decimal | None)

  • cache_hit (bool)

provider: str
input_tokens: int
output_tokens: int
cost_estimate_usd: Decimal | None
cache_hit: bool
class LlmUsageDiagnosticsReader(*args, **kwargs)[source]

Bases: Protocol

Read usage accounting facts within an inclusive date window.

load_records(*, since, until)[source]

Return translated usage facts for the requested window.

Return type:

Sequence[LlmUsageDiagnosticRecord]

Parameters:

  • since (date | None)

  • until (date | None)

class LlmTransactionDiagnosticsReader(*args, **kwargs)[source]

Bases: Protocol

Read the domain transaction facts used for confidence diagnostics.

load_transactions()[source]

Return all transactions in the explicitly composed bucket.

Return type:

Sequence[Transaction]

exception LlmDiagnosticsReadError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

A usage or transaction diagnostics read failed at the outer boundary.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class LlmDiagnosticsPorts(usage_reader, transaction_reader)[source]

Bases: object

Required read capabilities for one ledger LLM diagnostics report.

Parameters:
usage_reader: LlmUsageDiagnosticsReader
transaction_reader: LlmTransactionDiagnosticsReader