cadrumo.adapters.persistence.llm.cache module

Encrypted content-addressed cache for LLM responses.

Each CachedEntry is stored under LLM_CACHE_NAMESPACE as an encrypted secure object with SensitivityClass DIAGNOSTIC classification so operator-identifying inputs are redacted before persistence.

class LLMCache(root_dir=None)[source]

Bases: object

Persist LLM responses through encrypted secure objects.

The cache derives CacheKey values from LLMRequest content and persists LLMResponse payloads through secure_object_repository_for_active_bucket().

Parameters:

root_dir (Path | None) – Optional logical cache partition override.

build_key(request, provider, model)[source]

Derive a CacheKey from the request.

Parameters:
Return type:

CacheKey

Returns:

Deterministic CacheKey components.

read(request, provider, model)[source]

Read a cached response, if present.

Parameters:
Return type:

LLMResponse | None

The decoded entry is bound back to the key that was asked for before it is returned. The object key is derived from the request, but until that check existed nothing tied the DECRYPTED payload’s own provider / model / prompt hash / args hash to it: a valid entry re-encrypted under another entry’s row was returned verbatim, so a caller asking one provider-and-model could be answered by another’s text with cache_hit set. Successful decryption proves custody of the bucket key, never that the row holds what was requested.

An entry whose response carries a redaction placeholder is evicted and reported as a miss: it predates the write-side refusal to store a redacted response, and replaying it would substitute a hash for the value the model returned.

Return type:

LLMResponse | None

Returns:

Cached LLMResponse when present, otherwise None.

Raises:

  • LLMCacheError – When the cached

  • payload is present but cannot be parsed, or when it decodes to –

  • an entry belonging to a different cache key. –

Parameters:
write(request, response)[source]

Write a response to the cache and return the stored entry.

The serialised payload is routed through the substrate’s redact_structured() helper at SensitivityClass DIAGNOSTIC class before persistence (the CACHE-class default policy has an empty rule set because most caches are public reference data; the LLM cache carries identity-bearing inputs and therefore adopts the DIAGNOSTIC rule set, mirroring the run-trace sink’s discipline). The redacted payload is stored as an encrypted SQL secure object rather than a materialized JSON file.

A response the redaction altered is not stored at all. A cache hit stands in for the response, and a redacted one is a different response: an invoice read whose tax identifier came back as its hash fails validation on replay, so a re-read of the same document refused what the first read accepted.

Parameters:
Return type:

CachedEntry

Returns:

Persisted CachedEntry model.

Raises:

  • LLMCacheError – When redaction

  • produces a non-dict result or the storage write fails with an –

  • OS-level error. –

stats()[source]

Return encrypted cache counts as a CacheStats.

Return type:

CacheStats

Returns:

CacheStats with aggregate entry count and total decrypted JSON byte size for this logical cache partition.

prune(*, retention_days=None, max_records=None)[source]

Delete cached entries older than the retention window or beyond the count cap.

Two-stage bound mirroring prune(): entries older than retention_days (measured against the current time) are removed, then – if more than max_records remain – the oldest excess entries beyond the cap are removed too. Both bounds default to the centralized cadrumo_llm_cache_retention_days / cadrumo_llm_cache_max_records settings, giving the response cache a declared retention lifecycle instead of unbounded growth.

Return type:

int

Returns:

Number of removed cache objects.

Raises:

  • LLMCacheError – When a cache

  • entry cannot be parsed during iteration. –

Parameters:

  • retention_days (int | None)

  • max_records (int | None)