Module semantic_cache 

Semantic cache for retrieval results (0.21.0 S4.2).

A semantic cache answers repeated (or paraphrased) queries from cached retrieval results instead of re-running embedding + retrieval:

• lexical hit: the query text is byte-identical to a cached query — always preferred (product codes, IDs: lexical is more reliable);
• semantic hit: the query embedding’s cosine similarity against a cached query’s embedding reaches the threshold.

The cache is a RetrieverTrait decorator (CachedRetriever); it is off-by-default (wrap your retriever explicitly) and eviction/TTL keep the footprint bounded. k is part of the cached result set: a hit requires the same k (a different k recomputes rather than slicing padded results).

The inner bookkeeping (SemanticCacheCore) is a pure, embedder-free unit so the threshold/FIFO/TTL/exact-priority semantics are testable with synthetic vectors.

Structs

CachedRetriever

A RetrieverTrait decorator backed by a SemanticCacheCore.

SemanticCacheConfig

Semantic cache configuration.

SemanticCacheCore

Pure cache bookkeeping (no embedder, no retriever — fully unit-testable).

Enums

CacheHitKind

Hit kind returned by SemanticCacheCore::lookup.