cadrumo.adapters.persistence.llm.usage module

Encrypted usage recorder for LLM calls.

Persists llm.UsageRecord payloads under adapters.persistence.storage.secure_object_namespaces.LLM_USAGE_NAMESPACE in the encrypted SQL secure-object backend and exposes load and aggregate helpers. Records are routed through core.redaction.rules.redact_structured() at core.classification.policies.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 llm.UsageRecord through adapters.persistence.storage.runtime_repository.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 llm.UsageRecord from a response.

Parameters:

• response (LLMResponse) – Public 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.rules.redact_structured() at core.classification.policies.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:

• 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 llm.UsageRecord entries in file-iteration order.

prune(*, retention_days=None, max_records=None)

Delete usage records older than the retention window or beyond the count cap.

Applies the same two-stage bound as prune(): first every record older than retention_days (measured against the current time) is removed, then – if more than max_records remain – the oldest excess records beyond the cap are removed too. Both bounds default to the centralized cadrumo_llm_usage_retention_days and cadrumo_llm_usage_max_records settings.

Like every usage-record read path, prune hard-refuses (raises LLMCacheError) when a record lacks its object_key_uuid. Every current writer emits that field, so absence is storage corruption.

Return type:

int

Parameters:

• retention_days (int | None)

• max_records (int | None)

summarize(since=None, until=None)

Aggregate usage records into a 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.