gllm-datastore-binary 0.5.45__cp311-cp311-macosx_13_0_arm64.whl

gllm_datastore/cache/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_datastore.cache.base import MatchingStrategy as MatchingStrategy
+from gllm_datastore.cache.cache import Cache as Cache
+
+__all__ = ['MatchingStrategy', 'Cache']

gllm_datastore/cache/base.pyi

@@ -0,0 +1,84 @@
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from typing import Any, Callable
+
+class MatchingStrategy(StrEnum):
+    """Defines how keys should be matched during retrieval."""
+    EXACT: str
+    FUZZY: str
+    SEMANTIC: str
+
+class BaseCache(ABC):
+    """Base class for cache using data store."""
+    @abstractmethod
+    def cache(self, key_func: Callable | None = None, name: str = '', matching_strategy: MatchingStrategy = ..., matching_config: dict[str, Any] | None = None, **kwargs) -> Callable:
+        """Decorator to cache the result of a function.
+
+        This method should be implemented by subclasses to provide the caching functionality.
+
+        Args:
+            key_func (Callable | None, optional): Function to generate the cache key. Defaults to None.
+            name (str, optional): Name of the cache. Defaults to an empty string.
+            matching_strategy (MatchingStrategy, optional): The strategy to use for matching keys.
+                This can be one of the values from the MatchingStrategy enum. Defaults to exact matching.
+            matching_config (dict[str, Any] | None, optional): Configuration parameters for matching strategies.
+                Defaults to None.
+            **kwargs: Additional parameters specific to the caching method.
+
+        Returns:
+            Callable: A decorator that can be applied to a function to cache its result.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def retrieve(self, key: str, **kwargs) -> Any | None:
+        """Retrieve the cached result.
+
+        This method should be implemented by subclasses to provide the retrieval functionality.
+
+        Args:
+            key (str): The cache key to retrieve.
+            **kwargs: Additional parameters specific to the retrieval method.
+
+        Returns:
+            Any | None: The cached result if found, otherwise None.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def store(self, key: str, value: Any, **kwargs) -> None:
+        """Store the cached result.
+
+        This method should be implemented by subclasses to provide the storage functionality.
+
+        Args:
+            key (str): The cache key to store.
+            value (Any): The value to store in the cache.
+            **kwargs: Additional parameters specific to the storage method.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def delete(self, key: str | list[str]) -> None:
+        """Delete the cached result.
+
+        This method should be implemented by subclasses to provide the deletion functionality.
+
+        Args:
+            key (str | list[str]): The cache key to delete.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear all cached results.
+
+        This method should be implemented by subclasses to provide the clearing functionality.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """

gllm_datastore/cache/cache.pyi

@@ -0,0 +1,137 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.base import BaseCache as BaseCache, MatchingStrategy as MatchingStrategy
+from gllm_datastore.cache.utils import generate_cache_id as generate_cache_id, generate_key_from_func as generate_key_from_func, serialize_pydantic as serialize_pydantic
+from gllm_datastore.cache.vector_cache.eviction_manager.eviction_manager import BaseEvictionManager as BaseEvictionManager
+from gllm_datastore.constants import METADATA_KEYS as METADATA_KEYS
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore, CapabilityType as CapabilityType
+from typing import Any, Callable, Literal, overload
+
+class Cache(BaseCache):
+    """Cache interface that uses a data store for storage and retrieval.
+
+    Attributes:
+        data_store (BaseDataStore): The data store to use for storage.
+        eviction_manager (BaseEvictionManager | None): The eviction manager to use for cache eviction.
+        matching_strategy (MatchingStrategy): The strategy to use for matching keys.
+        eviction_config (dict[str, Any] | None): Configuration parameters for eviction strategies.
+        max_locks (int): Maximum number of locks to keep in memory for race condition mitigation.
+    """
+    data_store: Incomplete
+    eviction_manager: Incomplete
+    eviction_strategy: Incomplete
+    matching_strategy: Incomplete
+    eviction_config: Incomplete
+    def __init__(self, data_store: BaseDataStore, eviction_manager: BaseEvictionManager | None = None, matching_strategy: MatchingStrategy = ..., eviction_config: dict[str, Any] | None = None, max_locks: int = 100) -> None:
+        """Initialize the data store cache.
+
+        Args:
+            data_store (BaseDataStore): The data store to use for storage.
+                Must have fulltext capability registered.
+                Vector capability required only for semantic matching.
+            eviction_manager (BaseEvictionManager | None, optional): The eviction manager to use for cache eviction.
+                Defaults to None. If None, no eviction will be performed.
+            matching_strategy (MatchingStrategy, optional): The strategy to use for matching keys.
+                Defaults to MatchingStrategy.EXACT.
+            eviction_config (dict[str, Any] | None, optional): Configuration parameters for eviction strategies.
+                Defaults to None, which means no specific configuration is provided.
+            max_locks (int, optional): Maximum number of locks to keep in memory. When exceeded,
+                least recently used locks are automatically evicted. Defaults to 100.
+
+        Raises:
+            ValueError: If data_store doesn't have fulltext capability.
+            ValueError: If semantic matching requested without vector capability.
+        """
+    def cache(self, key_func: Callable | None = None, name: str = '', matching_strategy: MatchingStrategy | None = None, eviction_config: dict[str, Any] | None = None) -> Callable:
+        '''Decorator for caching function results.
+
+        This decorator caches the results of the decorated function using this cache storage.
+        The cache key is generated using the provided key function or a default key generation
+        based on the function name and arguments.
+
+        Synchronous and asynchronous functions are supported.
+
+        Example:
+            1. Basic usage:
+            ```python
+            def get_user_cache_key(user_id: int) -> str:
+                return f"user:{user_id}"
+
+            @cache_store.cache(key_func=get_user_cache_key)
+            async def get_user(user_id: int) -> User:
+                return await db.get_user(user_id)
+
+            # will use/store cache with key "user:1"
+            user1 = await get_user(1)
+            ```
+
+            2. Using eviction config:
+            ```python
+            @cache_store.cache(eviction_config={"ttl": "1h"})
+            async def get_user(user_id: int) -> User:
+                return await db.get_user(user_id)
+            ```
+
+        Args:
+            key_func (Callable | None, optional): A function to generate the cache key.
+                Defaults to None, in which case the function name and arguments will be used to generate the cache key.
+            name (str, optional): The name of the cache. This can be used to identify the cache in logs or metrics.
+                Defaults to an empty string.
+            matching_strategy (MatchingStrategy | None, optional): The strategy to use for matching keys.
+                Defaults to None, in which case the class-level matching strategy will be used.
+            eviction_config (dict[str, Any] | None, optional): Configuration parameters for eviction strategies.
+                Defaults to None, in which case the class-level eviction config will be used.
+
+        Returns:
+            Callable: A decorator function.
+        '''
+    async def store(self, key: str, value: str, metadata: dict[str, Any] | None = None, **kwargs) -> None:
+        '''Store the cached result based on the key and matching strategy.
+
+        Example:
+            ```python
+            await cache.store("my_key", "my_value", metadata={"category": "ML", "subcategory": "AI"}, ttl="1h")
+            ```
+
+        Args:
+            key (str): The cache key to store.
+            value (str): The value to store in the cache.
+            metadata (dict[str, Any] | None, optional): Metadata to store with the cache.
+                Defaults to None.
+            **kwargs: Additional keyword arguments to pass to the eviction strategy (e.g. ttl).
+        '''
+    @overload
+    async def retrieve(self, key: str, matching_strategy: Literal[MatchingStrategy.EXACT], filters: FilterClause | QueryFilter | None = None) -> Any | None: ...
+    @overload
+    async def retrieve(self, key: str, matching_strategy: Literal[MatchingStrategy.FUZZY], max_distance: int = 2, filters: FilterClause | QueryFilter | None = None) -> Any | None: ...
+    @overload
+    async def retrieve(self, key: str, matching_strategy: Literal[MatchingStrategy.SEMANTIC], min_similarity: float = 0.8, filters: FilterClause | QueryFilter | None = None) -> Any | None: ...
+    async def delete(self, key: str | list[str], filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Delete the cached result based on the key and matching strategy.
+
+        Example:
+            ```python
+            # Using QueryFilter for multiple conditions
+            await cache.delete(
+                "my_key",
+                filters=F.and_(F.eq("metadata.category", "ML"), F.eq("metadata.subcategory", "AI"))
+            )
+
+            # Using FilterClause directly
+            await cache.delete("my_key", filters=F.eq("metadata.category", "ML"))
+            ```
+
+        Args:
+            key (str | list[str]): The cache key to delete.
+            filters (FilterClause | QueryFilter | None, optional): Optional filters to apply to the search.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+        '''
+    async def clear(self) -> None:
+        """Clear all cached results based on the matching strategy.
+
+        Example:
+            ```python
+            await cache.clear()
+            ```
+        """

gllm_datastore/cache/hybrid_cache/__init__.pyi

@@ -0,0 +1,5 @@
+from gllm_datastore.cache.hybrid_cache.file_system_hybrid_cache import FileSystemHybridCache as FileSystemHybridCache
+from gllm_datastore.cache.hybrid_cache.in_memory_hybrid_cache import InMemoryHybridCache as InMemoryHybridCache
+from gllm_datastore.cache.hybrid_cache.redis_hybrid_cache import RedisHybridCache as RedisHybridCache
+
+__all__ = ['FileSystemHybridCache', 'InMemoryHybridCache', 'RedisHybridCache']

gllm_datastore/cache/hybrid_cache/file_system_hybrid_cache.pyi

@@ -0,0 +1,50 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.hybrid_cache.hybrid_cache import BaseHybridCache as BaseHybridCache
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+
+class FileSystemHybridCache(BaseHybridCache):
+    '''A cache that stores data in the file system.
+
+    The `FileSystemHybridCache` class utilizes the file system to store cache data.
+
+    Attributes:
+        cache_dir (str): The directory to store the cache data.
+        cache_version (str): The version of the cache data.
+        current_version_dir (str): The directory to store the cache data for the current version.
+        metadata_dir (str): The directory to store the metadata for the cache data.
+        serialization_format (str): The serialization format to use for storing the cache data.
+            The supported serialization formats are "json" and "pickle".
+        compression_extension (str): The extension to use for the compression of the cache data. The supported
+            compression extensions are "json.gz" and "pkl.gz".
+        logger (Logger): The logger to use for logging.
+        key_matcher (BaseKeyMatcher): The key matcher to use that defines the cache key matching strategy.
+    '''
+    logger: Incomplete
+    cache_dir: Incomplete
+    cache_version: Incomplete
+    current_version_dir: Incomplete
+    metadata_dir: Incomplete
+    serialization_format: Incomplete
+    compression_extension: Incomplete
+    def __init__(self, cache_dir: str, cache_version: str = '1.0.0', serialization_format: str = 'json', key_matcher: BaseKeyMatcher | None = None) -> None:
+        '''Initializes a new instance of the FileSystemHybridCache class.
+
+        Args:
+            cache_dir (str): The directory to store the cache data.
+            cache_version (str, optional): The version of the cache data. Defaults to "1.0.0".
+            serialization_format (str, optional): The serialization format to use for storing the cache data.
+                The supported serialization formats are "json" and "pickle". Defaults to "json".
+            key_matcher (BaseKeyMatcher | None, optional): The key matcher to use that defines the cache key
+                matching strategy. Defaults to None, in which case the `ExactKeyMatcher` will be used.
+
+        Raises:
+            ValueError: If the serialization format is not supported.
+        '''
+    async def retrieve_all_keys(self) -> set[str]:
+        """Retrieves all keys from the file system cache.
+
+        This method filters out and deletes any expired keys before returning the set.
+
+        Returns:
+            set[str]: A set of all keys in the file system cache.
+        """

gllm_datastore/cache/hybrid_cache/hybrid_cache.pyi

@@ -0,0 +1,115 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from gllm_datastore.cache.cache import BaseCache as BaseCache
+from gllm_datastore.cache.hybrid_cache.key_matcher import ExactKeyMatcher as ExactKeyMatcher
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+from gllm_datastore.cache.hybrid_cache.utils import generate_key_from_func as generate_key_from_func
+from gllm_datastore.utils import convert_ttl_to_seconds as convert_ttl_to_seconds
+from typing import Any, Callable, ParamSpec, TypeVar
+
+P = ParamSpec('P')
+T = TypeVar('T')
+
+class BaseHybridCache(BaseCache, ABC):
+    """A base class for hybrid cache used in Gen AI applications.
+
+    The `BaseHybridCache` class provides a framework for storing and retrieving cache data.
+
+    Attributes:
+        key_matcher (BaseKeyMatcher): The key matcher that defines the cache key matching strategy.
+    """
+    key_matcher: Incomplete
+    def __init__(self, key_matcher: BaseKeyMatcher | None = None) -> None:
+        """Initialize a new instance of the `BaseHybridCache` class.
+
+        Args:
+            key_matcher (BaseKeyMatcher | None, optional): The key matcher that defines the cache key matching
+                strategy. Defaults to None, in which case the `ExactKeyMatcher` will be used.
+        """
+    def cache(self, key_func: Callable[P, str] | None = None, name: str = '', ttl: int | str | None = None) -> Callable[[Callable[P, T]], Callable[P, T]]:
+        '''Decorator for caching function results.
+
+        This decorator caches the results of the decorated function using this cache storage.
+        The cache key is generated using the provided key function or a default key generation
+        based on the function name and arguments.
+
+        Synchronous and asynchronous functions are supported.
+
+        Args:
+            key_func (Callable[P, str] | None, optional): Function to generate cache keys.
+                Must accept the same parameters as the decorated function.
+            name (str, optional): Name to use in the default key generation if key_func is None.
+            ttl (int | str | None, optional): The time-to-live for the cached data. Can be an integer
+                in seconds or a string (e.g. "1h", "1d", "1w", "1y"). If None, the cache data will not expire.
+                Defaults to None. In this case, the cache will not expire.
+            matching_strategy (MatchingStrategy, optional): The strategy to use for matching keys.
+                This can be one of the values from the MatchingStrategy enum. Defaults to exact matching.
+            matching_config (dict[str, Any], optional): Configuration parameters for matching strategies.
+                Defaults to None.
+
+        Example:
+            ```python
+            def get_user_cache_key(user_id: int) -> str:
+                return f"user:{user_id}"
+
+            @cache_store.cache(key_func=get_user_cache_key, ttl="1h")
+            async def get_user(user_id: int) -> User:
+                return await db.get_user(user_id)
+
+            # will use/store cache with key "user:1", expiring after 1 hour
+            user1 = await get_user(1)
+            ```
+
+        Returns:
+            Callable: A decorator function.
+        '''
+    async def store(self, key: str, value: Any, ttl: int | str | None = None) -> None:
+        '''Stores cache data in the storage.
+
+        This method preprocesses the TTL (time-to-live) value to seconds if provided, and then calls both
+        the `key_matcher.store` and `_store` methods to store the cache data in the storage.
+
+        Args:
+            key (str): The key to store the cache data.
+            value (Any): The cache data to store.
+            ttl (int | str | None): The time-to-live (TTL) for the cache data. Must either be an integer in seconds
+                or a string (e.g. "1h", "1d", "1w", "1y"). If None, the cache data will not expire.
+        '''
+    async def retrieve(self, key: str) -> Any:
+        """Retrieves cache data from the storage.
+
+        This method first retrieves the key using the strategy defined in the `key_matcher`. If a matching key is
+        found, the method will retrieve the cache data from the storage using the `_retrieve` method. Otherwise,
+        the method will return None.
+
+        Args:
+            key (str): The key to retrieve the cache data.
+
+        Returns:
+            Any: The retrieved cache data.
+        """
+    async def delete(self, key: str | list[str]) -> None:
+        """Deletes cache data from the storage.
+
+        This method deletes the key by calling both the `key_matcher.delete` and `_delete` methods.
+
+        Args:
+            key (str | list[str]): The key(s) to delete the cache data.
+        """
+    async def clear(self) -> None:
+        """Clears all cache data from the storage.
+
+        This method clears all cache data from the storage by calling both the `key_matcher.clear` and `_clear` methods.
+        """
+    @abstractmethod
+    async def retrieve_all_keys(self) -> set[str]:
+        """Retrieves all keys from the storage.
+
+        This method must be implemented by the subclasses to define the logic for retrieving all keys from the storage.
+
+        Returns:
+            set[str]: A set of all keys in the storage.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """

gllm_datastore/cache/hybrid_cache/in_memory_hybrid_cache.pyi

@@ -0,0 +1,29 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.hybrid_cache.hybrid_cache import BaseHybridCache as BaseHybridCache
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+
+class InMemoryHybridCache(BaseHybridCache):
+    """A hybrid cache that stores data in an in-memory dictionary.
+
+    The `InMemoryHybridCache` class utilizes an in-memory dictionary to store the cache data.
+
+    Attributes:
+        in_memory_cache (dict[str, Any]): An in-memory dictionary to store the cache data.
+        key_matcher (BaseKeyMatcher): The key matcher to use that defines the cache key matching strategy.
+    """
+    in_memory_cache: Incomplete
+    def __init__(self, key_matcher: BaseKeyMatcher | None = None) -> None:
+        """Initializes a new instance of the InMemoryHybridCache class.
+
+        Args:
+            key_matcher (BaseKeyMatcher | None, optional): The key matcher to use that defines the cache key
+                matching strategy. Defaults to None, in which case the `ExactKeyMatcher` will be used.
+        """
+    async def retrieve_all_keys(self) -> set[str]:
+        """Retrieves all keys from the storage.
+
+        This method filters out and deletes any expired keys before returning the set.
+
+        Returns:
+            set[str]: A set of all keys in the storage.
+        """

gllm_datastore/cache/hybrid_cache/key_matcher/__init__.pyi

@@ -0,0 +1,5 @@
+from gllm_datastore.cache.hybrid_cache.key_matcher.exact_key_matcher import ExactKeyMatcher as ExactKeyMatcher
+from gllm_datastore.cache.hybrid_cache.key_matcher.fuzzy_key_matcher import FuzzyKeyMatcher as FuzzyKeyMatcher
+from gllm_datastore.cache.hybrid_cache.key_matcher.semantic_key_matcher import SemanticKeyMatcher as SemanticKeyMatcher
+
+__all__ = ['ExactKeyMatcher', 'FuzzyKeyMatcher', 'SemanticKeyMatcher']

gllm_datastore/cache/hybrid_cache/key_matcher/exact_key_matcher.pyi

@@ -0,0 +1,44 @@
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+
+class ExactKeyMatcher(BaseKeyMatcher):
+    """A key matcher that performs exact matching strategy.
+
+    This implementation simply checks if the input key exists in the set of cached keys
+    and returns it if found, otherwise returns None. The store_key method is a no-op.
+    """
+    async def store(self, key: str) -> None:
+        """Store the key as additional information during the matching process.
+
+        This method does nothing as exact matching doesn't require storing additional information.
+
+        Args:
+            key (str): The key to be stored.
+        """
+    async def retrieve(self, key: str, cached_keys: set[str]) -> str | None:
+        """Retrieve the key with exact matching strategy.
+
+        This method performs exact matching as follows:
+        1. Check if the input key exists in the set of cached keys.
+        2. If it does, return the input key.
+        3. Otherwise, return None.
+
+        Args:
+            key (str): The input key to be matched.
+            cached_keys (set[str]): The set of cached keys to be matched.
+
+        Returns:
+            str | None: The key if it exists in cached_keys, otherwise None.
+        """
+    async def delete(self, key: str | list[str]) -> None:
+        """Delete the key stored as additional information during the matching process.
+
+        This method does nothing as exact matching doesn't require deleting additional information.
+
+        Args:
+            key (str | list[str]): The key(s) to be deleted.
+        """
+    async def clear(self) -> None:
+        """Clear all the keys that are stored as additional information during the matching process.
+
+        This method does nothing as exact matching doesn't require clearing additional information.
+        """

gllm_datastore/cache/hybrid_cache/key_matcher/fuzzy_key_matcher.pyi

@@ -0,0 +1,70 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+
+class FuzzyKeyMatcher(BaseKeyMatcher):
+    """A key matcher that performs fuzzy matching strategy.
+
+    This implementation uses fuzzy matching to find the closest match between the input key
+    and the cached keys. The distance is calculated using the Levenshtein distance.
+
+    Attributes:
+        max_distance_ratio (float): The ratio of key length to use as maximum Levenshtein distance
+            for a key to match with the cached keys (e.g., 0.05 means 5% of key length).
+
+    Note:
+        Since the fuzzy matching heavily depends on the syntactic similarity between the key and the cached
+        key, it should only be used when the key is a plain string. Fuzzy matching SHOULD NOT be used when the key
+        is a hash / encryption of the input data.
+    """
+    max_distance_ratio: Incomplete
+    def __init__(self, max_distance_ratio: float = 0.05) -> None:
+        """Initialize a new instance of the `FuzzyKeyMatcher` class.
+
+        Args:
+            max_distance_ratio (float, optional): The ratio of key length to use as maximum Levenshtein distance
+                for a key to match with the cached keys (e.g., 0.05 means 5% of key length). Must be between 0 and 1.
+                Defaults to 0.05.
+
+        Raises:
+            ValueError: If the fuzzy distance ratio is not between 0 and 1.
+        """
+    async def store(self, key: str) -> None:
+        """Store the key as additional information during the matching process.
+
+        This method does nothing as fuzzy matching doesn't require storing additional information.
+
+        Args:
+            key (str): The key to be stored.
+        """
+    async def retrieve(self, key: str, cached_keys: set[str]) -> str | None:
+        """Retrieve the key with fuzzy matching strategy.
+
+        This method performs fuzzy matching as follows:
+        1. Iterate through all cached keys and calculate the Levenshtein distance between the key and the cached key
+           to get the key with the smallest distance.
+        2. If a cached key with the distance of 0 is found, the cached value of that key is returned immediately.
+        3. If the smallest distance is less than the fuzzy distance ratio, the cached value of the key with the
+           smallest distance is returned.
+        4. Otherwise, None is returned.
+
+        Args:
+            key (str): The input key to be matched.
+            cached_keys (set[str]): The set of cached keys to be matched.
+
+        Returns:
+            str | None: The key with the smallest Levenshtein distance, if the distance is less than the fuzzy
+                distance ratio, otherwise None.
+        """
+    async def delete(self, key: str | list[str]) -> None:
+        """Delete the keys stored as additional information during the matching process.
+
+        This method does nothing as fuzzy matching doesn't require deleting additional information.
+
+        Args:
+            key (str | list[str]): The key(s) to be deleted.
+        """
+    async def clear(self) -> None:
+        """Clear all the keys that are stored as additional information during the matching process.
+
+        This method does nothing as fuzzy matching doesn't require clearing additional information.
+        """

gllm_datastore/cache/hybrid_cache/key_matcher/key_matcher.pyi

@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+
+class BaseKeyMatcher(ABC):
+    """A base class for key matcher classes used in hybrid caches.
+
+    The key matcher is a framework that can be used by hybrid caches to retrieve the key that matches
+    the input key using different strategies as defined in the subclasses.
+    """
+    @abstractmethod
+    async def store(self, key: str) -> None:
+        """Store the key as additional information during the matching process.
+
+        This method must be implemented by the subclasses to define the logic for storing the key as additional
+        information during the matching process.
+
+        Args:
+            key (str): The key to be stored as additional information during the matching process.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    async def retrieve(self, key: str, cached_keys: set[str]) -> str | None:
+        """Retrieve the key that matches the input key.
+
+        This method must be implemented by the subclasses to define the logic for retrieving the matched key.
+
+        Args:
+            key (str): The input key to be matched.
+            cached_keys (set[str]): The set of cached keys to be matched.
+
+        Returns:
+            str | None: The matched key, if found. Otherwise, None.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    async def delete(self, key: str | list[str]) -> None:
+        """Delete the key stored as additional information during the matching process.
+
+        This method must be implemented by the subclasses to define the logic for deleting the key stored as additional
+        information during the matching process.
+
+        Args:
+            key (str | list[str]): The key(s) to be deleted.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all the keys that are stored as additional information during the matching process.
+
+        This method must be implemented by the subclasses to define the logic for clearing all the keys that are
+        stored as additional information during the matching process.
+
+        Raises:
+            NotImplementedError: If the method is not implemented.
+        """