aeat.adapters.outbound.llm._usage module

Encrypted usage recorder for LLM calls.

Persists adapters.outbound.llm.UsageRecord payloads under adapters.persistence.storage.LLM_USAGE_NAMESPACE in the encrypted SQL secure-object backend and exposes load and aggregate helpers. Records are routed through core.redaction.redact_structured() at core.classification.SensitivityClass DIAGNOSTIC before they are encrypted, so NIFs and bearer-shaped tokens are redacted before persistence.

class UsageRecorder(root_dir=None)

Bases: object

Append LLM usage records to encrypted secure objects.

Each call to record() stores one redacted adapters.outbound.llm.UsageRecord through adapters.persistence.storage.secure_object_repository_for_active_bucket() under the recorder’s logical root.

Variables:

root_dir – Logical partition used for usage records.

Parameters:

root_dir (Path | None)

build_record(response, prompt_id, caller)

Build a adapters.outbound.llm.UsageRecord from a response.

Parameters:

• response (LLMResponse) – Public adapters.outbound.llm.LLMResponse model.

• prompt_id (str) – Stable prompt identifier (e.g. "translation_v1").

• caller (str) – Stable caller identifier used for cost attribution.

Return type:

UsageRecord

Returns:

Persistable usage record carrying the response text and accounting metadata.

record(record)

Append a redacted record to encrypted secure-object storage.

The record is routed through core.redaction.redact_structured() at core.classification.SensitivityClass DIAGNOSTIC class before encoding so NIFs are SHA-256 prefixed, URLs are reduced to host-only, and bearer-shaped tokens are fingerprinted.

Parameters:

record (UsageRecord) – Usage record to append.

Return type:

Path

Returns:

Logical daily usage path for operator display only.

Raises:

• adapters.outbound.llm.LLMCacheError – When the storage

• write fails. –

load_records(since=None, until=None)

Load usage records, optionally filtered by an inclusive date range.

Parameters:

• since (date | None) – Inclusive lower date bound, or None for no lower bound.

• until (date | None) – Inclusive upper date bound, or None for no upper bound.

Return type:

tuple[UsageRecord, ...]

Returns:

Loaded adapters.outbound.llm.UsageRecord entries in file-iteration order.

summarize(since=None, until=None)

Aggregate usage records into a adapters.outbound.llm.UsageSummary.

Parameters:

• since (date | None) – Inclusive lower date bound, or None for no lower bound.

• until (date | None) – Inclusive upper date bound, or None for no upper bound.

Return type:

UsageSummary

Returns:

Aggregate usage summary covering entries, total tokens, and estimated cost.