Eviction strategy

Eviction strategy base class and factory.

BaseEvictionStrategy

Bases: ABC

Base class for eviction strategies.

evict(vector_store) abstractmethod async

Evict entries based on the eviction policy.

This method should be implemented by subclasses to define how entries should be selected for eviction.

Parameters:

Name	Type	Description	Default
vector_store	CacheCompatibleMixin | BaseDataStore	The cache store to use for eviction.	required

Raises:

Type	Description
NotImplementedError	If the method is not implemented by the subclass.

prepare_metadata(**kwargs) abstractmethod async

Prepare metadata for a new cache entry.

This method should be implemented by subclasses to define how metadata should be prepared for a new cache entry.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary containing metadata for the new entry.
dict[str, Any]	**kwargs: Additional keyword arguments to pass to the eviction strategy.

Raises:

Type	Description
NotImplementedError	If the method is not implemented by the subclass.

CapacityBasedEvictionStrategy(max_entries)

Bases: BaseEvictionStrategy

Base class for eviction strategies that manage cache size via max_entries.

Subclasses define their eviction policy by implementing three hooks:

• primary_metadata_key: the metadata field used for primary ordering (e.g. last_used_at for LRU, access_count for LFU).
• primary_default: the fallback value when that field is missing.
• _sort_key(chunk): returns a tuple used to deterministically rank candidates after fetching (used to break ties consistently).

The shared evict() method uses these hooks to execute the full fetch-loop / sort / delete pipeline without duplication.

Initialize the capacity-based eviction strategy.

Parameters:

Name	Type	Description	Default
max_entries	int	Maximum number of entries allowed in the cache. Must be a positive integer.	required

Raises:

Type	Description
ValueError	If max_entries is not a positive integer.

primary_default abstractmethod property

The default value used when primary_metadata_key is absent from a chunk's metadata.

Returns:

Name	Type	Description
Any	Any	The fallback value (e.g. "" for timestamps, 0 for counts).

primary_metadata_key abstractmethod property

The metadata field used as the primary sort key for eviction candidates.

Returns:

Name	Type	Description
str	str	The metadata key name (e.g. "last_used_at" or "access_count").

evict(vector_store) async

Evict entries from the cache using the subclass-defined eviction policy.

This method: 1. Checks the current cache size; exits early if under the limit. 2. Fetches the num_to_evict + EVICTION_FETCH_BUFFER least-priority candidates ordered by primary_metadata_key (ascending). 3. Expands the fetch window if all fetched entries share the same primary value (a tie), ensuring a fair and deterministic cut. 4. Sorts the final candidate pool using _sort_key and deletes the correct number of entries.

Only BaseDataStore instances are supported. Passing any other type will emit a warning and return without evicting.

Parameters:

Name	Type	Description	Default
vector_store	BaseDataStore	The cache store to perform eviction on.	required

prepare_metadata(**kwargs) async

Prepare metadata for a new cache entry.

By default, capacity-based eviction strategies (like LRU/LFU) do not require additional metadata beyond what Cache already provides.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Empty dictionary — no extra metadata needed.