Struct SemanticCacheLayer 

pub struct SemanticCacheLayer {
    pub config: CacheConfig,
    pub entries: Vec<CacheEntry>,
    pub next_id: usize,
    pub total_hits: u64,
    pub total_misses: u64,
    pub total_insertions: u64,
}

A vector-similarity-based cache.

See the module-level documentation for a usage example.

Fields

config: CacheConfig

Runtime configuration.

entries: Vec<CacheEntry>

The stored entries.

next_id: usize

Monotonically increasing counter used to assign stable entry IDs.

total_hits: u64

Total cache hits since creation.

total_misses: u64

Total cache misses since creation.

total_insertions: u64

Total entries ever inserted.

Implementations

impl SemanticCacheLayer

pub fn new(config: CacheConfig) -> Self

Create a new cache with the given configuration.

pub fn cosine_similarity(a: &[f64], b: &[f64]) -> f64

Compute the cosine similarity between two f64 slices.

Returns 0.0 if the vectors have different lengths, if either vector is all-zeros, or if the denominator underflows to zero.

pub fn lookup(&mut self, query_embedding: &[f64], now: u64) -> CacheLookupResult

Look up the cache for a semantically similar previous query.

Scans all non-expired entries and finds the one with the highest cosine similarity to query_embedding. If that similarity is ≥ config.similarity_threshold the entry’s hit_count and last_accessed fields are updated and a CacheLookupResult::Hit is returned; otherwise CacheLookupResult::Miss is returned.

The global total_hits / total_misses counters are always updated.

Arguments

• query_embedding — embedding vector for the incoming query.
• now — current timestamp in milliseconds (caller-supplied for testability).

pub fn insert(&mut self, key: CacheKey, result: String, now: u64)

Insert a new entry into the cache.

If the cache has reached config.max_entries, one entry is evicted first according to config.eviction_policy. The config.ttl_ms value is applied to the new entry’s ttl_ms field.

Arguments

• key — the query key (text + embedding).
• result — the result to cache.
• now — current timestamp in milliseconds.

pub fn evict_one(&mut self, now: u64)

Evict a single entry according to the configured CacheEvictionPolicy.

• LRU — remove the entry with the smallest last_accessed timestamp.
• LFU — remove the entry with the smallest hit_count.
• TTLFirst — among entries that have a ttl_ms, remove the one that will expire soonest (inserted_at + ttl_ms is smallest); if no entry has a TTL, fall back to LRU.

Does nothing if the cache is empty.

pub fn evict_expired(&mut self, now: u64) -> usize

Remove all expired entries from the cache.

Returns the number of entries that were removed.

pub fn invalidate_by_text(&mut self, text: &str) -> usize

Remove all entries whose key.query_text exactly matches text.

Returns the number of entries removed.

pub fn clear(&mut self)

Remove all entries from the cache (statistics are preserved).

pub fn entry_count(&self) -> usize

Return the current number of entries in the cache.

pub fn stats(&self) -> ScCacheStats

Return aggregate statistics for this cache instance.

Trait Implementations

impl Debug for SemanticCacheLayer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.