Struct SemanticCacheManager 

pub struct SemanticCacheManager { /* private fields */ }

A semantic-aware cache backed by cosine similarity search.

Entries are stored in a Vec<Slot> for simplicity and full linear-scan semantic search. For workloads requiring sub-linear semantic lookup, wrap this with an HNSW layer on top.

Implementations

impl SemanticCacheManager

pub fn new(config: ScmCacheConfig) -> Self

Create a new SemanticCacheManager with the given configuration.

pub fn insert( &mut self, key: ScmCacheKey, result: Vec<u8>, ttl_us: Option<u64>, ) -> Result<u64, ScmCacheError>

Insert an entry into the cache.

Assigns a monotonically increasing entry_id and stores the entry. If the cache is over capacity after insertion, entries are evicted according to the configured ScmEvictionStrategy.

Errors

• ScmCacheError::EntryTooLarge if the entry alone exceeds max_bytes.
• ScmCacheError::DimensionMismatch if the embedding dimension is wrong.
• ScmCacheError::CacheAtCapacity if eviction fails to free space.

pub fn insert_at( &mut self, key: ScmCacheKey, result: Vec<u8>, ttl_us: Option<u64>, inserted_at: u64, ) -> Result<u64, ScmCacheError>

Insert with an explicit insertion timestamp (used in tests and production where you track time yourself).

pub fn lookup( &mut self, query_text: &str, embedding: &[f64], current_ts: u64, ) -> Result<ScmCacheHit, ScmCacheError>

Look up a query in the cache.

1. Scan all live entries; lazily expire any TTL-expired entries found.
2. Check for an exact-text match (same FNV-1a hash and identical text).
3. If no exact match, find the highest-similarity entry above the threshold.

Updates access_count and last_accessed on the winning entry.

Errors

Returns ScmCacheError::DimensionMismatch when the provided embedding dimension differs from the inferred dimension.

pub fn get_entry(&self, entry_id: u64) -> Result<&ScmCacheEntry, ScmCacheError>

Retrieve a reference to an entry by its ID.

Errors

Returns ScmCacheError::EntryNotFound if no such ID exists.

pub fn invalidate(&mut self, entry_id: u64) -> Result<(), ScmCacheError>

Remove the entry with the given ID.

Errors

Returns ScmCacheError::EntryNotFound if no such ID exists.

pub fn invalidate_similar( &mut self, embedding: &[f64], threshold: f64, ) -> Vec<u64>

Remove all entries whose embedding has cosine similarity > threshold with the given embedding. Returns the IDs of removed entries.

pub fn expire_ttl(&mut self, current_ts: u64) -> Vec<u64>

Remove all TTL-expired entries as of current_ts. Returns the IDs removed.

pub fn evict_to_fit(&mut self, needed_bytes: usize) -> Vec<u64>

Evict entries (per the configured strategy) until at least needed_bytes of space is available. Returns the IDs of evicted entries.

Errors

Returns ScmCacheError::CacheAtCapacity if it is impossible to free enough space (e.g., all entries are locked or the budget is zero).

pub fn semantic_neighbors( &self, embedding: &[f64], top_k: usize, ) -> Vec<(u64, f64)>

Return the top-k entries ranked by cosine similarity to embedding, without any threshold filtering.

pub fn cluster_stats(&self) -> Vec<(f64, usize)>

Compute greedy cluster statistics.

Groups embeddings into clusters where every member is within config.cluster_radius (in cosine distance = 1 − similarity) of the cluster centroid. Returns a Vec of (centroid_similarity, cluster_size).

The “centroid” here is represented as the embedding of the first entry assigned to each cluster (greedy seeding). The returned f64 is the average pairwise cosine similarity within the cluster.

pub fn stats(&self) -> ScmCacheStats

Return a snapshot of current cache statistics.

Trait Implementations

impl Debug for SemanticCacheManager

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

Formats the value using the given formatter.