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

gllm_datastore/core/filters/schema.pyi

@@ -0,0 +1,149 @@
+from enum import StrEnum
+from pydantic import BaseModel
+from typing import Any, Sequence
+
+class FilterOperator(StrEnum):
+    """Operators for comparing field values."""
+    EQ: str
+    NE: str
+    GT: str
+    LT: str
+    GTE: str
+    LTE: str
+    IN: str
+    NIN: str
+    ANY: str
+    ALL: str
+    ARRAY_CONTAINS: str
+    TEXT_CONTAINS: str
+
+class FilterCondition(StrEnum):
+    """Logical conditions for combining filters."""
+    AND: str
+    OR: str
+    NOT: str
+
+class FilterClause(BaseModel):
+    '''Single filter criterion with operator support.
+
+    Examples:
+        ```python
+        FilterClause(key="metadata.age", value=25, operator=FilterOperator.GT)
+        FilterClause(key="metadata.status", value=["active", "pending"], operator=FilterOperator.IN)
+        ```
+
+    Attributes:
+        key (str): The field path to filter on (supports dot notation for nested fields).
+        value (int | float | str | bool | list[str] | list[float] | list[int] | list[bool] | None):
+            The value to compare against.
+        operator (FilterOperator): The comparison operator.
+    '''
+    key: str
+    value: bool | int | float | str | list[str] | list[float] | list[int] | list[bool] | None
+    operator: FilterOperator
+    def to_query_filter(self) -> QueryFilter:
+        '''Convert FilterClause to QueryFilter.
+
+        This method enables automatic conversion of FilterClause to QueryFilter.
+
+        Example:
+            ```python
+            clause = FilterClause(key="metadata.status", value="active", operator=FilterOperator.EQ)
+            query_filter = clause.to_query_filter()
+            # Results in: QueryFilter(filters=[clause], condition=FilterCondition.AND)
+            ```
+
+        Returns:
+            QueryFilter: A QueryFilter wrapping this FilterClause with AND condition.
+        '''
+
+class QueryFilter(BaseModel):
+    '''Composite filter supporting multiple conditions and logical operators.
+
+    Attributes:
+        filters (list[FilterClause | QueryFilter]): List of filters to combine.
+            Can include nested QueryFilter for complex logic.
+        condition (FilterCondition): Logical operator to combine filters. Defaults to AND.
+
+    Examples:
+        1. Simple AND: age > 25 AND status == "active"
+            ```python
+            QueryFilter(
+                filters=[
+                    FilterClause(key="metadata.age", value=25, operator=FilterOperator.GT),
+                    FilterClause(key="metadata.status", value="active", operator=FilterOperator.EQ)
+                ],
+                condition=FilterCondition.AND
+            )
+            ```
+
+        2. Complex OR: (status == "active" OR status == "pending") AND age >= 18
+            ```python
+            QueryFilter(
+                filters=[
+                    QueryFilter(
+                        filters=[
+                            FilterClause(key="metadata.status", value="active"),
+                            FilterClause(key="metadata.status", value="pending")
+                        ],
+                        condition=FilterCondition.OR
+                    ),
+                    FilterClause(key="metadata.age", value=18, operator=FilterOperator.GTE)
+                ],
+                condition=FilterCondition.AND
+            )
+            ```
+
+        3. NOT: NOT (status == "deleted")
+            ```python
+            QueryFilter(
+                filters=[
+                    FilterClause(key="metadata.status", value="deleted")
+                ],
+                condition=FilterCondition.NOT
+            )
+            ```
+    '''
+    filters: list[FilterClause | QueryFilter]
+    condition: FilterCondition
+    @classmethod
+    def from_dicts(cls, filter_dicts: list[dict[str, Any]], condition: FilterCondition = ...) -> QueryFilter:
+        '''Create QueryFilter from list of filter dictionaries.
+
+        Example:
+            ```python
+            QueryFilter.from_dicts(
+                [
+                    {"key": "metadata.age", "value": 25, "operator": ">"},
+                    {"key": "metadata.status", "value": "active"}
+                ],
+                condition=FilterCondition.AND
+            )
+            ```
+
+        Args:
+            filter_dicts (list[dict[str, Any]]): List of filter dictionaries. Contains the key, value, and operator.
+            condition (FilterCondition, optional): Logical operator to combine filters. Defaults to AND.
+
+        Returns:
+            QueryFilter: Composite filter instance.
+        '''
+
+class QueryOptions(BaseModel):
+    '''Model for query options.
+
+    Attributes:
+        include_fields (Sequence[str] | None): The fields to include in the query result. Defaults to None.
+        order_by (str | None): The column to order the query result by. Defaults to None.
+        order_desc (bool): Whether to order the query result in descending order. Defaults to False.
+        limit (int | None): The maximum number of rows to return. Must be >= 0. Defaults to None.
+
+    Example:
+        ```python
+        QueryOptions(include_fields=["field1", "field2"], order_by="column1", order_desc=True, limit=10)
+        ```
+    '''
+    include_fields: Sequence[str] | None
+    order_by: str | None
+    order_desc: bool
+    limit: int | None

gllm_datastore/data_store/__init__.pyi

@@ -0,0 +1,8 @@
+from gllm_datastore.data_store.chroma import ChromaDataStore as ChromaDataStore
+from gllm_datastore.data_store.elasticsearch import ElasticsearchDataStore as ElasticsearchDataStore
+from gllm_datastore.data_store.exceptions import NotRegisteredException as NotRegisteredException, NotSupportedException as NotSupportedException
+from gllm_datastore.data_store.in_memory import InMemoryDataStore as InMemoryDataStore
+from gllm_datastore.data_store.opensearch import OpenSearchDataStore as OpenSearchDataStore
+from gllm_datastore.data_store.redis import RedisDataStore as RedisDataStore
+
+__all__ = ['ChromaDataStore', 'ElasticsearchDataStore', 'InMemoryDataStore', 'NotRegisteredException', 'NotSupportedException', 'OpenSearchDataStore', 'RedisDataStore']

gllm_datastore/data_store/_elastic_core/client_factory.pyi

@@ -0,0 +1,66 @@
+from elasticsearch import AsyncElasticsearch
+from enum import StrEnum
+from gllm_datastore.constants import DEFAULT_REQUEST_TIMEOUT as DEFAULT_REQUEST_TIMEOUT
+from opensearchpy import AsyncOpenSearch
+from typing import Any
+
+ElasticLikeClient = AsyncElasticsearch | AsyncOpenSearch
+
+class EngineType(StrEnum):
+    """Engine type for Elasticsearch-like clients."""
+    ELASTICSEARCH: str
+    OPENSEARCH: str
+
+def create_client(engine: EngineType, client: ElasticLikeClient | None = None, url: str | None = None, cloud_id: str | None = None, api_key: str | None = None, username: str | None = None, password: str | None = None, request_timeout: int = ..., connection_params: dict[str, Any] | None = None) -> ElasticLikeClient:
+    '''Create Elasticsearch or OpenSearch client (internal use only).
+
+    This function is used internally by ElasticsearchDataStore and OpenSearchDataStore.
+    It is not part of the public API.
+
+    Args:
+        engine: Engine type ("elasticsearch" or "opensearch").
+            Determines which client library to use for connection.
+        client: Pre-configured client instance.
+            If provided, will be validated and returned as-is without creating a new client.
+            Must match the engine type (AsyncElasticsearch for "elasticsearch",
+            AsyncOpenSearch for "opensearch"). Defaults to None.
+        url (str | None, optional): The URL of the Elasticsearch or OpenSearch server.
+            For example, "http://localhost:9200" or "https://localhost:9200".
+            If URL starts with "https://", SSL/TLS will be automatically enabled with
+            certificate verification enabled by default. To use self-signed certificates,
+            set verify_certs=False in connection_params.
+            Defaults to None. Either url or cloud_id must be provided if client is None.
+        cloud_id (str | None, optional): The cloud ID of the Elasticsearch cluster.
+            Used for Elastic Cloud connections. Defaults to None.
+            Either url or cloud_id must be provided if client is None.
+            NOTE: Not supported for OpenSearch engine. Will raise ValueError if provided with engine="opensearch".
+        api_key (str | None, optional): The API key for authentication.
+            If provided, will be used for authentication. Mutually exclusive with username/password.
+            Defaults to None.
+            NOTE: Not supported for OpenSearch engine. Will raise ValueError if provided with engine="opensearch".
+            For OpenSearch, use username/password with http_auth instead.
+        username (str | None, optional): The username for basic authentication.
+            Must be provided together with password. Mutually exclusive with api_key.
+            Defaults to None.
+        password (str | None, optional): The password for basic authentication.
+            Must be provided together with username. Mutually exclusive with api_key.
+            Defaults to None.
+        request_timeout (int, optional): The request timeout in seconds.
+            Defaults to DEFAULT_REQUEST_TIMEOUT.
+        connection_params (dict[str, Any] | None, optional): Additional connection parameters
+            to override defaults. These will be merged with automatically detected parameters
+            (authentication, SSL settings). User-provided params take precedence. Defaults to None.
+            Available parameters include use_ssl, verify_certs, ssl_show_warn, max_retries,
+            retry_on_timeout, client_cert, client_key, root_cert, etc.
+
+    Returns:
+        The configured client instance.
+            Returns AsyncElasticsearch if engine is "elasticsearch",
+            AsyncOpenSearch if engine is "opensearch".
+
+    Raises:
+        ValueError: If neither url nor cloud_id is provided when client is None.
+            If cloud_id is provided for OpenSearch engine (not supported).
+            If api_key is provided for OpenSearch engine (not supported).
+        TypeError: If client is provided but has wrong type for the specified engine.
+    '''

gllm_datastore/data_store/_elastic_core/constants.pyi

@@ -0,0 +1,27 @@
+class ELASTIC_RESPONSE_KEYS:
+    """Keys used in Elasticsearch/OpenSearch response dictionaries.
+
+    Attributes:
+        SUGGEST (str): Key for suggestions in the response.
+        AGGREGATIONS (str): Key for aggregations in the response.
+        HITS (str): Key for hits in the response.
+        HIGHLIGHT (str): Key for highlights in hit objects.
+        OPTIONS (str): Key for options in suggestion objects.
+        BUCKETS (str): Key for buckets in aggregation objects.
+        TEXT (str): Key for text in suggestion option objects.
+        SOURCE (str): Key for source document in hit objects.
+        ID (str): Key for document ID in hit objects.
+        COUNT (str): Key for count in count response.
+        INDEX (str): Key for index name in bulk operations.
+    """
+    SUGGEST: str
+    AGGREGATIONS: str
+    HITS: str
+    HIGHLIGHT: str
+    OPTIONS: str
+    BUCKETS: str
+    TEXT: str
+    SOURCE: str
+    ID: str
+    COUNT: str
+    INDEX: str

gllm_datastore/data_store/_elastic_core/elastic_like_core.pyi

@@ -0,0 +1,115 @@
+from _typeshed import Incomplete
+from elasticsearch import AsyncElasticsearch
+from elasticsearch.dsl import AttrDict as ESAttrDict
+from gllm_core.schema import Chunk
+from gllm_datastore.constants import METADATA_KEYS as METADATA_KEYS
+from gllm_datastore.data_store._elastic_core.constants import ELASTIC_RESPONSE_KEYS as ELASTIC_RESPONSE_KEYS
+from opensearchpy import AsyncOpenSearch
+from opensearchpy.helpers.utils import AttrDict as OSAttrDict
+from typing import Any
+
+AttrDict = ESAttrDict | OSAttrDict
+
+class ElasticLikeCore:
+    """Shared core implementation for Elasticsearch-like datastores.
+
+    This class contains the common logic shared between Elasticsearch and OpenSearch.
+    Product-specific datastores delegate to this core and override methods where needed.
+
+    Attributes:
+        index_name (str): The name of the index used for all operations.
+        client (AsyncElasticsearch | AsyncOpenSearch): The Elasticsearch or OpenSearch client.
+            Used for all index and document operations.
+        _logger (Logger): Logger instance for this core. Used for logging operations and errors.
+    """
+    index_name: Incomplete
+    client: Incomplete
+    def __init__(self, index_name: str, client: AsyncElasticsearch | AsyncOpenSearch) -> None:
+        """Initialize the shared core.
+
+        Args:
+            index_name (str): The name of the index to use for operations.
+                This index name will be used for all queries and operations.
+            client (AsyncElasticsearch | AsyncOpenSearch): The Elasticsearch or OpenSearch client.
+                Must be a properly configured async client instance.
+        """
+    async def check_index_exists(self) -> bool:
+        """Check if index exists.
+
+        Returns:
+            bool: True if the index exists, False otherwise.
+        """
+    async def get_index_count(self) -> int:
+        """Get document count for the index.
+
+        Returns:
+            int: The total number of documents in the index.
+        """
+    async def create_chunks(self, data: Chunk | list[Chunk], query_field: str = 'text', **kwargs: Any) -> None:
+        '''Create new records in the datastore using bulk API.
+
+        Args:
+            data (Chunk | list[Chunk]): Data to create (single item or collection).
+            query_field (str, optional): The field name to use for text content. Defaults to "text".
+            **kwargs: Backend-specific parameters forwarded to bulk API.
+
+        Raises:
+            ValueError: If data structure is invalid.
+        '''
+    def create_chunks_from_hits(self, hits: list[AttrDict], query_field: str = 'text') -> list[Chunk]:
+        '''Create Chunk objects from Elasticsearch/OpenSearch hits.
+
+        This method processes hits from Elasticsearch/OpenSearch DSL responses where hits are AttrDict
+        objects (from elasticsearch.dsl or opensearchpy.helpers.utils). The _source field is accessed via
+        attribute access and is always an AttrDict (nested dicts are automatically wrapped by _wrap function).
+
+        Args:
+            hits (list[AttrDict]): List of Elasticsearch/OpenSearch hits as AttrDict objects.
+            query_field (str, optional): The field name to use for text content. Defaults to "text".
+
+        Returns:
+            list[Chunk]: List of Chunk objects.
+        '''
+    @staticmethod
+    def extract_response_suggestions(response: dict[str, Any], suggestion_key: str) -> list[str]:
+        """Extract suggestions from Elasticsearch/OpenSearch autocomplete response.
+
+        Args:
+            response (dict[str, Any]): Elasticsearch/OpenSearch response.
+            suggestion_key (str): The suggestion key in the response.
+
+        Returns:
+            list[str]: List of suggestions.
+        """
+    @staticmethod
+    def extract_aggregation_buckets(response: dict[str, Any], aggregation_name: str) -> list[str]:
+        """Extract bucket keys from Elasticsearch/OpenSearch aggregation response.
+
+        Args:
+            response (dict[str, Any]): Elasticsearch/OpenSearch response.
+            aggregation_name (str): The aggregation name in the response.
+
+        Returns:
+            list[str]: List of bucket keys.
+        """
+    @staticmethod
+    def extract_highlighted_text(response: dict[str, Any], field: str) -> list[str]:
+        """Extract highlighted text from Elasticsearch/OpenSearch response.
+
+        Args:
+            response (dict[str, Any]): Elasticsearch/OpenSearch response.
+            field (str): The field name to extract highlights from.
+
+        Returns:
+            list[str]: List of unique highlighted text snippets.
+        """
+    def validate_bm25_parameters(self, k1: float | None, b: float | None) -> bool:
+        """Validate BM25 parameters.
+
+        Args:
+            k1 (float | None): BM25 parameter controlling term frequency saturation.
+            b (float | None): BM25 parameter controlling document length normalization.
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """

gllm_datastore/data_store/_elastic_core/index_manager.pyi

@@ -0,0 +1,37 @@
+from elasticsearch import AsyncElasticsearch
+from opensearchpy import AsyncOpenSearch
+from typing import Any
+
+async def create_index_if_not_exists(client: AsyncElasticsearch | AsyncOpenSearch, index_name: str, mapping: dict[str, Any] | None = None, settings: dict[str, Any] | None = None) -> None:
+    """Create index if it doesn't exist (shared implementation).
+
+    This function checks if the index exists, and if not, creates it with the provided
+    mapping and settings. If the index already exists, the function returns without error.
+
+    Args:
+        client (AsyncElasticsearch | AsyncOpenSearch): The Elasticsearch or OpenSearch client.
+            Used to check index existence and create the index.
+        index_name (str): The name of the index to create.
+            Must be a valid index name according to Elasticsearch/OpenSearch naming rules.
+        mapping (dict[str, Any] | None, optional): Optional index mapping dictionary.
+            Defines the schema for fields in the index. If None, no custom mapping is applied.
+            Defaults to None.
+        settings (dict[str, Any] | None, optional): Optional index settings dictionary.
+            Defines index-level settings like number of shards, replicas, etc.
+            If None, no custom settings are applied. Defaults to None.
+
+    Raises:
+        RuntimeError: If index creation fails after checking existence.
+    """
+async def delete_index_if_exists(client: AsyncElasticsearch | AsyncOpenSearch, index_name: str) -> None:
+    """Delete index if it exists (shared implementation).
+
+    This function checks if the index exists, and if it does, deletes it.
+    If the index does not exist, the function returns without error.
+
+    Args:
+        client (AsyncElasticsearch | AsyncOpenSearch): The Elasticsearch or OpenSearch client.
+            Used to check index existence and delete the index.
+        index_name (str): The name of the index to delete.
+            Must be a valid index name according to Elasticsearch/OpenSearch naming rules.
+    """

gllm_datastore/data_store/_elastic_core/query_translator.pyi

@@ -0,0 +1,89 @@
+from abc import ABC
+from elasticsearch.dsl import AsyncSearch as ESAsyncSearch
+from elasticsearch.dsl.query import Query as ESQuery
+from gllm_datastore.core.filters.schema import FilterClause as FilterClause, FilterCondition as FilterCondition, FilterOperator as FilterOperator, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from opensearchpy._async.helpers.search import AsyncSearch as OSAsyncSearch
+from opensearchpy.helpers.query import Query as OSQuery
+
+AsyncSearchType = ESAsyncSearch | OSAsyncSearch
+QueryType = ESQuery | OSQuery
+
+def convert_filter_clause(filters: FilterClause | QueryFilter | None) -> QueryFilter | None:
+    """Convert FilterClause to QueryFilter if needed.
+
+    Args:
+        filters (FilterClause | QueryFilter | None): The filter to convert.
+
+    Returns:
+        QueryFilter | None: The converted QueryFilter or None if input is None.
+    """
+
+class ElasticLikeQueryTranslator(ABC):
+    """Base class for Elasticsearch-like query translators.
+
+    This class provides shared translation logic for converting FilterClause and
+    QueryFilter objects to product-specific Query DSL objects. Subclasses must
+    implement abstract methods to create Query objects using their DSL API.
+
+    Attributes:
+        _logger: Logger instance for error messages.
+    """
+    def __init__(self) -> None:
+        """Initialize the query translator."""
+    def translate(self, filters: QueryFilter | None) -> QueryType | None:
+        """Translate a structured QueryFilter into a Query DSL object.
+
+        The translation supports comparison operators (EQ, NE, GT, LT, GTE, LTE),
+        array operators (IN, NIN, ARRAY_CONTAINS, ANY, ALL), text operators (TEXT_CONTAINS),
+        and logical conditions (AND, OR, NOT), including nested filters.
+
+        Args:
+            filters (QueryFilter | None): Structured QueryFilter containing filter clauses
+                and logical conditions. If None or empty, returns None.
+
+        Returns:
+            QueryType | None: Query DSL object representing the translated filters.
+                Returns None if no filters are provided or filters are empty.
+                The actual Query type depends on the product-specific implementation
+                (elasticsearch.dsl.query.Query or opensearchpy.helpers.query.Query).
+
+        Raises:
+            ValueError: When the filter structure is invalid or translation fails.
+        """
+    def apply_options(self, search: AsyncSearchType, options: QueryOptions | None) -> AsyncSearchType:
+        """Apply QueryOptions to an Elasticsearch/OpenSearch search object.
+
+        This method applies query options including limit, field inclusion, and sorting
+        to a search object. Both Elasticsearch and OpenSearch AsyncSearch objects
+        support the same API for these operations.
+
+        Args:
+            search (AsyncSearchType): Elasticsearch or OpenSearch search object to modify.
+                The search object will be modified in-place and returned.
+            options (QueryOptions | None): Query options including limit, sort, and fields.
+                If None, the search object is returned unchanged. Defaults to None.
+
+        Returns:
+            AsyncSearchType: Modified search object with options applied.
+                Returns the same search object instance with modifications.
+        """
+    def apply_filters_and_options(self, search: AsyncSearchType, filters: QueryFilter | None = None, options: QueryOptions | None = None) -> AsyncSearchType:
+        """Apply both filters and options to an Elasticsearch/OpenSearch search object.
+
+        This method applies filters first (if provided), then applies options.
+        Both operations modify the search object in-place.
+
+        Args:
+            search (AsyncSearchType): Elasticsearch or OpenSearch search object to modify.
+                The search object will be modified in-place and returned.
+            filters (QueryFilter | None, optional): QueryFilter with filters and logical condition.
+                If provided, filters will be translated and applied to the search query.
+                Defaults to None.
+            options (QueryOptions | None, optional): Query options including limit, sort, and fields.
+                If provided, options will be applied to the search object.
+                Defaults to None.
+
+        Returns:
+            AsyncSearchType: Modified search object with filters and options applied.
+                Returns the same search object instance with modifications.
+        """

gllm_datastore/data_store/base.pyi

@@ -0,0 +1,176 @@
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from gllm_datastore.cache import Cache as Cache
+from gllm_datastore.core.capabilities import EncryptionCapability as EncryptionCapability, FulltextCapability as FulltextCapability, GraphCapability as GraphCapability, HybridCapability as HybridCapability, SearchConfig as SearchConfig, VectorCapability as VectorCapability
+from gllm_datastore.core.filters.schema import FilterClause as FilterClause, QueryFilter as QueryFilter
+from gllm_datastore.data_store.exceptions import NotRegisteredException as NotRegisteredException, NotSupportedException as NotSupportedException
+from gllm_datastore.encryptor.encryptor import BaseEncryptor as BaseEncryptor
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from typing import Any, Self
+
+class CapabilityType(StrEnum):
+    """Enumeration of supported capability types."""
+    FULLTEXT: str
+    GRAPH: str
+    HYBRID: str
+    VECTOR: str
+
+class BaseDataStore(ABC):
+    """Base class for datastores with multiple capabilities.
+
+    This class provides the infrastructure for capability composition and
+    delegation. Datastores inherit from this class and register capability
+    handlers based on their configuration.
+    """
+    def __init__(self) -> None:
+        """Initialize the datastore with specified capabilities."""
+    @property
+    @abstractmethod
+    def supported_capabilities(self) -> list[CapabilityType]:
+        """Return list of currently supported capabilities.
+
+        A data store might have more capabilities than the ones that are currently registered.
+        Each data store should implement this method to return the list of supported capabilities.
+
+        Returns:
+            list[str]: List of capability names that are supported.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by subclass.
+        """
+    @property
+    def registered_capabilities(self) -> list[CapabilityType]:
+        """Return list of currently registered capabilities.
+
+        Returns:
+            list[str]: List of capability names that are registered and available.
+        """
+    @property
+    def fulltext(self) -> FulltextCapability:
+        """Access fulltext capability if supported.
+
+        Returns:
+            FulltextCapability: Fulltext capability handler.
+
+        Raises:
+            NotSupportedException: If fulltext capability is not supported.
+        """
+    @property
+    def vector(self) -> VectorCapability:
+        """Access vector capability if supported.
+
+        Returns:
+            VectorCapability: Vector capability handler.
+
+        Raises:
+            NotSupportedException: If vector capability is not supported
+        """
+    @property
+    def graph(self) -> GraphCapability:
+        """Access graph capability if supported.
+
+        Returns:
+            GraphCapability: Graph capability handler.
+
+        Raises:
+            NotSupportedException: If graph capability is not supported.
+        """
+    @property
+    def hybrid(self) -> HybridCapability:
+        """Access hybrid capability if supported.
+
+        Returns:
+            HybridCapability: Hybrid capability handler.
+
+        Raises:
+            NotSupportedException: If hybrid capability is not supported.
+            NotRegisteredException: If hybrid capability is not registered.
+        """
+    def with_fulltext(self, **kwargs) -> Self:
+        """Configure fulltext capability and return datastore instance.
+
+        Args:
+            **kwargs: Fulltext capability configuration parameters.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    def with_vector(self, em_invoker: BaseEMInvoker, **kwargs) -> Self:
+        """Configure vector capability and return datastore instance.
+
+        Args:
+            em_invoker (BaseEMInvoker): Embedding model invoker (required).
+            **kwargs: Vector capability configuration parameters.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    def with_graph(self, **kwargs) -> Self:
+        """Configure graph capability and return datastore instance.
+
+        Args:
+            **kwargs: Graph capability configuration parameters.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    def with_encryption(self, encryptor: BaseEncryptor, fields: set[str] | list[str]) -> Self:
+        """Enable encryption for specified fields.
+
+        Encryption works transparently - users don't need to access it directly.
+        It's automatically used by fulltext and vector capabilities.
+
+        Args:
+            encryptor (BaseEncryptor): The encryptor instance to use. Must not be None.
+            fields (set[str] | list[str]): Set or list of field names to encrypt. Must not be empty.
+
+        Returns:
+            Self: Self for method chaining.
+
+        Raises:
+            ValueError: If encryptor is None or fields is empty.
+        """
+    def with_hybrid(self, config: list[SearchConfig], **kwargs) -> Self:
+        """Configure hybrid capability and return datastore instance.
+
+        Args:
+            config (list[SearchConfig]): List of search configurations for hybrid search.
+            **kwargs: Additional hybrid capability configuration parameters.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    def as_cache(self, eviction_manager: Any | None = None, matching_strategy: Any = None) -> Cache:
+        """Create a Cache instance from this datastore.
+
+        Args:
+            eviction_manager (Any | None, optional): Optional eviction manager for cache eviction.
+                Defaults to None.
+            matching_strategy (Any, optional): Default matching strategy for cache retrieval.
+                Defaults to None.
+
+        Returns:
+            Cache: Instance wrapping this datastore.
+
+        Raises:
+            ValueError: If required capabilities not registered.
+        """
+    @classmethod
+    def translate_query_filter(cls, query_filter: FilterClause | QueryFilter, **kwargs) -> Any:
+        """Translate QueryFilter or FilterClause to datastore's native filter syntax.
+
+        This method provides a public interface for converting the GLLM DataStore's
+        QueryFilter DSL into each datastore's native filter format. Subclasses must
+        implement this method to provide their specific translation logic.
+
+        Args:
+            query_filter (FilterClause | QueryFilter): The filter to translate.
+                Can be a single FilterClause or a QueryFilter with multiple clauses.
+            **kwargs: Additional keyword arguments for the datastore's native filter syntax.
+
+        Returns:
+            Any: The translated filter in the datastore's native format.
+
+        Raises:
+            NotImplementedError: If not implemented by subclass.
+        """