gllm-datastore-binary 0.5.50__cp312-cp312-macosx_13_0_arm64.whl

gllm_datastore/cache/hybrid_cache/key_matcher/semantic_key_matcher.pyi

@@ -0,0 +1,93 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.hybrid_cache.key_matcher.key_matcher import BaseKeyMatcher as BaseKeyMatcher
+from gllm_datastore.vector_data_store import ElasticsearchVectorDataStore as ElasticsearchVectorDataStore
+from gllm_datastore.vector_data_store.vector_data_store import BaseVectorDataStore as BaseVectorDataStore
+
+class SemanticKeyMatcher(BaseKeyMatcher):
+    """A key matcher that performs semantic matching strategy.
+
+    This implementation uses semantic matching to find the closest match between the input key
+    and the cached keys. The similarity is calculated using a vector data store instance.
+
+    Attributes:
+        vector_data_store (BaseVectorDataStore): The vector data store to be used for semantic matching.
+        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 semantic matching heavily depends on the semantic similarity between the key and the cached
+        key, it should only be used when the key is a plain string. Semantic matching SHOULD NOT be used when the key
+        is a hash / encryption of the input data.
+
+        Additionally, the semantic matching is currently has the following tech debts:
+        1. The distance to be evaluated againts the threshold is calculated using the Levenshtein distance.
+           This will be updated to use semantic score once the vector data store supports retrieval with scores.
+        2. The vector data store currently only supports `ElasticsearchVectorDataStore`.
+           This should be updated once the vector data store supports a general interface to delete and clear all
+           chunks from the vector data store.
+    """
+    vector_data_store: Incomplete
+    max_distance_ratio: Incomplete
+    def __init__(self, vector_data_store: BaseVectorDataStore, max_distance_ratio: float = 0.05) -> None:
+        """Initialize a new instance of the `SemanticKeyMatcher` class.
+
+        Args:
+            vector_data_store (BaseVectorDataStore): The vector data store to be used for semantic matching.
+            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.
+            ValueError: If the vector data store is not an instance of `ElasticsearchVectorDataStore`.
+        """
+    async def store(self, key: str) -> None:
+        """Store the key as additional information during the matching process.
+
+        This method adds the key to the vector data store.
+
+        Args:
+            key (str): The key to be stored.
+        """
+    async def retrieve(self, key: str, cached_keys: set[str]) -> str | None:
+        """Retrieve the key with the semantic matching strategy.
+
+        This method performs semantic matching as follows:
+        1. Retrieve the most similar key from the vector data store.
+        2. Calculate the distance between the input key and the retrieved key.
+        3. Calculate the maximum distance as a ratio of the input key length.
+        4. If the distance is less than or equal to the maximum distance and the retrieved key exists in cached_keys,
+           return the retrieved key. Otherwise, return None.
+
+        Note:
+            As of now, the distance to be evaluated againts the threshold is calculated using the Levenshtein distance.
+            This will be updated to use semantic score once the vector data store supports retrieval with scores.
+
+        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 deletes the key from the vector data store.
+
+        Note:
+            As of now, this is only compatible with the `ElasticsearchVectorDataStore` implementation.
+            This should be updated once the vector data store supports deletion of chunks by query.
+
+        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.
+
+        Note:
+            As of now, this is only compatible with the `ElasticsearchVectorDataStore` implementation.
+            This should be updated once the vector data store supports deletion of chunks by query.
+
+        This method deletes all keys from the vector data store.
+        """

gllm_datastore/cache/hybrid_cache/redis_hybrid_cache.pyi

@@ -0,0 +1,34 @@
+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 RedisHybridCache(BaseHybridCache):
+    """A hybrid cache that stores data in Redis.
+
+    The `RedisHybridCache` class utilizes Redis to store the cache data.
+
+    Attributes:
+        client (StrictRedis): The Redis client.
+        key_matcher (BaseKeyMatcher): The key matcher that defines the cache key matching strategy.
+    """
+    client: Incomplete
+    def __init__(self, host: str, port: int, password: str, db: int = 0, ssl: bool = False, key_matcher: BaseKeyMatcher | None = None) -> None:
+        """Initializes a new instance of the RedisHybridCache class.
+
+        Args:
+            host (str): The host of the Redis server.
+            port (int): The port of the Redis server.
+            password (str): The password for the Redis server.
+            db (int, optional): The database number. Defaults to 0.
+            ssl (bool, optional): Whether to use SSL. Defaults to False.
+            key_matcher (BaseKeyMatcher, optional): The key matcher to use. 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/utils.pyi

@@ -0,0 +1,36 @@
+from _typeshed import Incomplete
+from typing import Any
+
+logger: Incomplete
+
+def generate_cache_key(input_: str, key_prefix: str = '') -> str:
+    '''Generate a cache key from the input string.
+
+    This function generates a cache key from the input string.
+    If the input is a valid file, the function will hash the file.
+    If the input is not a valid file, the function will hash the input string.
+
+    Args:
+        input_ (str): The input string to generate the cache key from.
+        key_prefix (str, optional): The prefix of the cache key. Defaults to "".
+
+    Returns:
+        str: The generated cache key.
+
+    Raises:
+        Exception: If the input file path exists but cannot be read.
+    '''
+def generate_key_from_func(func_name: str, *args: Any, **kwargs: Any) -> str:
+    """Generate a cache key based on function name and arguments.
+
+    The key is created by hashing the function name, positional arguments, and keyword arguments.
+    If the function name, positional arguments, or keyword arguments are modified, the cache key will change.
+
+    Args:
+        func_name (str): Name of the function being cached
+        *args (Any): Positional arguments passed to the function
+        **kwargs (Any): Keyword arguments passed to the function
+
+    Returns:
+        str: SHA-256 hash digest to be used as cache key
+    """

gllm_datastore/cache/utils.pyi

@@ -0,0 +1,34 @@
+from typing import Any
+
+def generate_key_from_func(func_name: str, *args, **kwargs) -> str:
+    """Generate a cache key based on function name and arguments.
+
+    Args:
+        func_name (str): The name of the function.
+        *args: Positional arguments passed to the function.
+        **kwargs: Keyword arguments passed to the function.
+
+    Returns:
+        str: A string key for caching.
+    """
+def generate_cache_id(key: str) -> str:
+    """Generate a cache entry ID from a key.
+
+    Args:
+        key (str): The cache key.
+
+    Returns:
+        str: A cache entry ID.
+    """
+def serialize_pydantic(obj: Any) -> dict[str, Any]:
+    """Custom JSON serializer for Pydantic models and other objects.
+
+    Args:
+        obj (Any): The object to serialize.
+
+    Returns:
+        dict[str, Any]: The serialized object.
+
+    Raises:
+        TypeError: If the object cannot be serialized.
+    """

gllm_datastore/cache/vector_cache/eviction_manager/asyncio_eviction_manager.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.vector_cache.eviction_manager.eviction_manager import BaseEvictionManager as BaseEvictionManager
+from gllm_datastore.cache.vector_cache.eviction_strategy.eviction_strategy import BaseEvictionStrategy as BaseEvictionStrategy
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore
+from gllm_datastore.vector_data_store.vector_data_store import BaseVectorDataStore as BaseVectorDataStore
+
+class AsyncIOEvictionManager(BaseEvictionManager):
+    """Eviction manager using asyncio for background tasks.
+
+    The `AsyncIOEvictionManager` is responsible for:
+    1. Starting and stopping the background task that performs the eviction check and eviction process.
+    2. Providing the eviction strategy to use for the eviction process.
+
+    This eviction manager should be used in the application that is using the cache, not in the database itself.
+    It is specifically designed to handle vector datastores that do not have its own eviction policies or specific
+    eviction strategy.
+
+    The `AsyncIOEvictionManager` could be used in the following scenarios:
+    1. When the `VectorCache` is initialized, it starts the background task.
+    2. When the `VectorCache` is shut down, it stops the background task.
+    """
+    vector_store: Incomplete
+    eviction_strategy: Incomplete
+    check_interval: Incomplete
+    task: Incomplete
+    running: bool
+    def __init__(self, vector_store: BaseVectorDataStore | BaseDataStore, eviction_strategy: BaseEvictionStrategy, check_interval: int = 60) -> None:
+        """Initialize the asyncio eviction manager.
+
+        Args:
+            vector_store (BaseVectorDataStore | BaseDataStore): The vector datastore to manage evictions for.
+            eviction_strategy (BaseEvictionStrategy): The eviction strategy to use.
+            check_interval (int): How often to check for entries to evict (in seconds).
+        """
+    def start(self) -> None:
+        """Start the background task for evicting entries.
+
+        This method starts the background task that periodically checks for entries to evict from the vector datastore
+        and evicts them if necessary using the specified eviction strategy.
+
+        If the task currently exists and is not done or cancelled, it will not start a new one.
+        """
+    def stop(self) -> None:
+        """Stop the background task for evicting entries.
+
+        This method stops the background task that periodically checks for entries to evict from the vector datastore
+        and evicts them if necessary using the specified eviction strategy.
+        """

gllm_datastore/cache/vector_cache/eviction_manager/eviction_manager.pyi

@@ -0,0 +1,38 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from gllm_datastore.cache.vector_cache.eviction_strategy.eviction_strategy import BaseEvictionStrategy as BaseEvictionStrategy
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore
+from gllm_datastore.vector_data_store.vector_data_store import BaseVectorDataStore as BaseVectorDataStore
+
+class BaseEvictionManager(ABC):
+    """Base class for eviction managers that handle the eviction process."""
+    vector_store: Incomplete
+    eviction_strategy: Incomplete
+    check_interval: Incomplete
+    def __init__(self, vector_store: BaseVectorDataStore | BaseDataStore, eviction_strategy: BaseEvictionStrategy, check_interval: int = 60) -> None:
+        """Initialize the eviction manager.
+
+        Args:
+            vector_store (BaseVectorDataStore | BaseDataStore): The datastore that will be managed by the
+                eviction manager.
+            eviction_strategy (BaseEvictionStrategy): The eviction strategy to use.
+            check_interval (int, optional): How often to check for entries to evict (seconds). Defaults to 60.
+        """
+    @abstractmethod
+    def start(self) -> None:
+        """Start the eviction checking process.
+
+        This method should be implemented by subclasses.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass
+        """
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop the eviction checking process.
+
+        This method should be implemented by subclasses.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass
+        """

gllm_datastore/cache/vector_cache/eviction_strategy/eviction_strategy.pyi

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore
+from gllm_datastore.vector_data_store.mixin.cache_compatible_mixin import CacheCompatibleMixin as CacheCompatibleMixin
+from typing import Any
+
+class BaseEvictionStrategy(ABC):
+    """Base class for eviction strategies."""
+    @abstractmethod
+    async def prepare_metadata(self, **kwargs) -> dict[str, Any]:
+        """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:
+            dict[str, Any]: A dictionary containing metadata for the new entry.
+            **kwargs: Additional keyword arguments to pass to the eviction strategy.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """
+    @abstractmethod
+    async def evict(self, vector_store: CacheCompatibleMixin | BaseDataStore) -> None:
+        """Evict entries based on the eviction policy.
+
+        This method should be implemented by subclasses to define how entries should be selected
+        for eviction.
+
+        Args:
+            vector_store (CacheCompatibleMixin | BaseDataStore): The cache store to use for eviction.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by the subclass.
+        """

gllm_datastore/cache/vector_cache/eviction_strategy/ttl_eviction_strategy.pyi

@@ -0,0 +1,34 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.vector_cache.eviction_strategy.eviction_strategy import BaseEvictionStrategy as BaseEvictionStrategy
+from gllm_datastore.constants import METADATA_KEYS as METADATA_KEYS
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore
+from gllm_datastore.utils import convert_ttl_to_seconds as convert_ttl_to_seconds
+from gllm_datastore.vector_data_store.mixin.cache_compatible_mixin import CacheCompatibleMixin as CacheCompatibleMixin
+from typing import Any
+
+class TTLEvictionStrategy(BaseEvictionStrategy):
+    """Eviction strategy based on time-to-live."""
+    ttl: Incomplete
+    def __init__(self, ttl: int | str) -> None:
+        '''Initialize the TTL eviction strategy.
+
+        Args:
+            ttl (int | str): The time-to-live for the cache. This can be an integer (in seconds)
+                or a string (e.g., "1h", "30m").
+        '''
+    async def prepare_metadata(self, ttl: int | str | None = None) -> dict[str, Any]:
+        """Prepare metadata with expiration time if TTL is provided.
+
+        Args:
+            ttl (int | None): The time-to-live for the cache, in seconds. If passed -1, the cache will not expire.
+                Defaults to None, in which case the class-defined TTL will be used.
+
+        Returns:
+            dict[str, Any]: Metadata dictionary containing creation time and expiration time.
+        """
+    async def evict(self, vector_store: CacheCompatibleMixin | BaseDataStore) -> None:
+        """Evict entries based on the eviction policy.
+
+        Args:
+            vector_store (CacheCompatibleMixin): The cache store to use for eviction.
+        """

gllm_datastore/cache/vector_cache/vector_cache.pyi

@@ -0,0 +1,99 @@
+from _typeshed import Incomplete
+from gllm_datastore.cache.cache import BaseCache as BaseCache, MatchingStrategy as MatchingStrategy
+from gllm_datastore.cache.utils import 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.vector_data_store.mixin.cache_compatible_mixin import CacheCompatibleMixin as CacheCompatibleMixin
+from typing import Any, Callable
+
+class VectorCache(BaseCache):
+    """Cache interface that uses a vector datastore for storage and retrieval."""
+    vector_store: Incomplete
+    eviction_manager: Incomplete
+    eviction_strategy: Incomplete
+    matching_strategy: Incomplete
+    matching_config: Incomplete
+    saving_config: Incomplete
+    def __init__(self, vector_store: CacheCompatibleMixin, eviction_manager: BaseEvictionManager | None = None, matching_strategy: MatchingStrategy = ..., matching_config: dict[str, Any] | None = None, saving_config: dict[str, Any] | None = None) -> None:
+        """Initialize the vector cache.
+
+        Args:
+            vector_store (CacheCompatibleMixin): The vector datastore to use for storage.
+                Must inherit both CacheCompatibleMixin and BaseVectorDataStore.
+            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.
+            matching_config (dict[str, Any] | None, optional): Configuration parameters for matching strategies.
+                Defaults to None, which means no specific configuration is provided.
+            saving_config (dict[str, Any] | None, optional): Configuration parameters for saving strategies.
+                Defaults to None, which means no specific configuration is provided.
+        """
+    def cache(self, key_func: Callable | None = None, name: str = '', matching_strategy: MatchingStrategy | None = None, matching_config: dict[str, Any] | None = None, saving_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.
+
+        Args:
+            key_func (Callable | None, optional): A function to generate the cache key.
+                If None, a default key generation will be used.
+            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.
+                This can be one of the values from the MatchingStrategy enum. Defaults to None. If None,
+                the class-level matching strategy will be used.
+            matching_config (dict[str, Any] | None, optional): Configuration parameters for matching strategies.
+                Defaults to None. If None, the class-level matching config will be used.
+            saving_config (dict[str, Any] | None, optional): Configuration parameters for saving strategies.
+                Defaults to None. If None, the class-level saving config will be used.
+
+        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 retrieve(self, key: str, matching_strategy: MatchingStrategy, matching_config: dict[str, Any] | None = None) -> Any | None:
+        """Retrieve the cached result based on the key and matching strategy.
+
+        Args:
+            key (str): The cache key to retrieve.
+            matching_strategy (MatchingStrategy): The strategy to use for matching keys.
+            matching_config (dict[str, Any]): Configuration parameters for the matching strategy.
+
+        Returns:
+            The cached result if found, otherwise None.
+        """
+    async def store(self, key: str, value: Any, metadata: dict[str, Any] | None = None, **kwargs) -> None:
+        """Store the cached result based on the key and matching strategy.
+
+        Args:
+            key (str): The cache key to store.
+            value (Any): 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.
+        """
+    async def delete(self, key: str | list[str], metadata: dict[str, Any] | None = None) -> None:
+        '''Delete the cached result based on the key and matching strategy.
+
+        Args:
+            key (str | list[str]): The cache key to delete.
+            metadata (dict[str, Any] | None, optional): Optional metadata filter to apply to the search.
+                For example, `{"key": "value"}`. Defaults to None.
+        '''
+    async def clear(self) -> None:
+        """Clear all cached results based on the matching strategy."""

gllm_datastore/constants.pyi

@@ -0,0 +1,66 @@
+from enum import Enum
+
+DEFAULT_TOP_K: int
+DEFAULT_FETCH_K: int
+DEFAULT_REQUEST_TIMEOUT: int
+SIMILARITY_SCORE: str
+DEFAULT_FUZZY_MATCH_MAX_DISTANCE: int
+DEFAULT_REDIS_QUERY_BATCH_SIZE: int
+REDIS_DEFAULT_HOST: str
+REDIS_DEFAULT_PORT: int
+REDIS_DEFAULT_DB: int
+FIELD_CONFIG_NAME: str
+FIELD_CONFIG_TYPE: str
+BOOL_TRUE_STR: str
+BOOL_FALSE_STR: str
+METADATA_PREFIX: str
+METADATA_SEPARATOR: str
+LIST_SEPARATOR: str
+
+class FieldType(str, Enum):
+    """Redis Search field types for filterable fields.
+
+    Attributes:
+        NUMERIC: Numeric field type for range queries.
+        TAG: Tag field type for exact matching and filtering.
+        TEXT: Text field type for full-text search.
+    """
+    NUMERIC: str
+    TAG: str
+    TEXT: str
+
+class CHUNK_KEYS:
+    """Dictionary-like keys used internally for in-memory chunk representation."""
+    ID: str
+    TEXT: str
+    CONTENT: str
+    METADATA: str
+    VECTOR: str
+    SCORE: str
+
+class METADATA_KEYS:
+    """Metadata keys used in the cache compatible vector data store.
+
+    Attributes:
+        EMBEDDINGS (str): Key for the embeddings in the cache.
+        DOCUMENTS (str): Key for the documents in the cache.
+        METADATA (str): Key for the metadata in the cache.
+        ORIGINAL_KEY (str): Key to store the original key value.
+        CACHE_VALUE (str): Key for the cached value.
+        CACHE_CREATED (str): Key for the timestamp when the cache was created.
+        TTL (str): Key for the time-to-live of the cache.
+        EXPIRE_AT (str): Key for the expiration time of the cache.
+        LAST_USED_AT (str): Key for the last used time of the cache.
+        ACCESS_COUNT (str): Key for the access count of the cache.
+    """
+    EMBEDDINGS: str
+    DOCUMENTS: str
+    METADATAS: str
+    METADATA: str
+    ORIGINAL_KEY: str
+    CACHE_VALUE: str
+    CACHE_CREATED: str
+    TTL: str
+    EXPIRE_AT: str
+    LAST_USED_AT: str
+    ACCESS_COUNT: str

gllm_datastore/core/__init__.pyi

@@ -0,0 +1,7 @@
+from gllm_datastore.core.capabilities.fulltext_capability import FulltextCapability as FulltextCapability
+from gllm_datastore.core.capabilities.graph_capability import GraphCapability as GraphCapability
+from gllm_datastore.core.capabilities.vector_capability import VectorCapability as VectorCapability
+from gllm_datastore.core.filters import FilterClause as FilterClause, FilterCondition as FilterCondition, FilterOperator as FilterOperator, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_datastore.core.filters.filter import all_ as all_, and_ as and_, any_ as any_, array_contains as array_contains, eq as eq, gt as gt, gte as gte, in_ as in_, lt as lt, lte as lte, ne as ne, nin as nin, not_ as not_, or_ as or_, text_contains as text_contains
+
+__all__ = ['FilterCondition', 'FilterOperator', 'FilterClause', 'QueryFilter', 'QueryOptions', 'FulltextCapability', 'GraphCapability', 'VectorCapability', 'all_', 'and_', 'any_', 'array_contains', 'eq', 'gt', 'gte', 'in_', 'lt', 'lte', 'ne', 'nin', 'not_', 'or_', 'text_contains']

gllm_datastore/core/capabilities/__init__.pyi

@@ -0,0 +1,7 @@
+from gllm_datastore.core.capabilities.encryption_capability import EncryptionCapability as EncryptionCapability
+from gllm_datastore.core.capabilities.fulltext_capability import FulltextCapability as FulltextCapability
+from gllm_datastore.core.capabilities.graph_capability import GraphCapability as GraphCapability
+from gllm_datastore.core.capabilities.hybrid_capability import HybridCapability as HybridCapability, HybridSearchType as HybridSearchType, SearchConfig as SearchConfig
+from gllm_datastore.core.capabilities.vector_capability import VectorCapability as VectorCapability
+
+__all__ = ['EncryptionCapability', 'FulltextCapability', 'GraphCapability', 'HybridCapability', 'SearchConfig', 'HybridSearchType', 'VectorCapability']

gllm_datastore/core/capabilities/encryption_capability.pyi

@@ -0,0 +1,21 @@
+from typing import Protocol
+
+class EncryptionCapability(Protocol):
+    """Protocol defining the encryption capability interface.
+
+    This protocol defines the contract that all encryption implementations must satisfy.
+    The EncryptionCapabilityMixin class provides a concrete implementation, but custom
+    implementations can also satisfy this protocol without inheriting from the mixin.
+
+    Note:
+        Encryption is an internal-only capability. Unlike fulltext and vector capabilities
+        which users access via properties, encryption works transparently in the background.
+        Users cannot access store.encryption - it's not exposed as a public property.
+    """
+    @property
+    def encryption_config(self) -> set[str] | None:
+        """Get the current encryption configuration.
+
+        Returns:
+            set[str] | None: Set of encrypted field names if encryption is enabled, None otherwise.
+        """

gllm_datastore/core/capabilities/fulltext_capability.pyi

@@ -0,0 +1,73 @@
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from typing import Any, Protocol
+
+class FulltextCapability(Protocol):
+    """Protocol for full-text search and document operations.
+
+    This protocol defines the interface for datastores that support CRUD operations
+    and flexible querying mechanisms for document data.
+    """
+    async def create(self, data: Chunk | list[Chunk], **kwargs) -> None:
+        """Create new records in the datastore.
+
+        Args:
+            data (Chunk | list[Chunk]): Data to create (single item or collection).
+            **kwargs: Datastore-specific parameters.
+        """
+    async def retrieve(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None, **kwargs) -> list[Chunk]:
+        """Read records from the datastore with optional filtering.
+
+        Args:
+            filters (FilterClause | QueryFilter | None, optional): Query filters to apply.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+            options (QueryOptions | None, optional): Query options like limit and sorting.
+                Defaults to None.
+            **kwargs: Datastore-specific parameters.
+
+        Returns:
+            list[Chunk]: Query results.
+        """
+    async def retrieve_fuzzy(self, query: str, max_distance: int = 2, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None, **kwargs) -> list[Chunk]:
+        """Find records that fuzzy match the query within distance threshold.
+
+        Args:
+            query (str): Text to fuzzy match against.
+            max_distance (int): Maximum edit distance for matches (Levenshtein distance). Defaults to 2.
+            filters (FilterClause | QueryFilter | None, optional): Optional metadata filters to apply.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+            options (QueryOptions | None, optional): Query options (limit, sorting, etc.). Defaults to None.
+            **kwargs: Datastore-specific parameters.
+
+        Returns:
+            list[Chunk]: Matched chunks ordered by relevance/distance.
+        """
+    async def update(self, update_values: dict[str, Any], filters: FilterClause | QueryFilter | None = None, **kwargs) -> None:
+        """Update existing records in the datastore.
+
+        Args:
+            update_values (dict[str, Any]): Values to update.
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to update.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+            **kwargs: Datastore-specific parameters.
+        """
+    async def delete(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None, **kwargs) -> None:
+        """Delete records from the datastore.
+
+        Args:
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to delete.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None, in which case no operation is performed (no-op).
+            options (QueryOptions | None, optional): Query options for sorting and limiting deletions.
+                Defaults to None.
+            **kwargs: Datastore-specific parameters.
+        """
+    async def clear(self, **kwargs) -> None:
+        """Clear all records from the datastore.
+
+        Args:
+            **kwargs: Datastore-specific parameters.
+        """