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

gllm_datastore/data_store/in_memory/fulltext.pyi

@@ -0,0 +1,131 @@
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_datastore.data_store.in_memory.query import create_updated_chunk as create_updated_chunk, delete_chunks_by_filters as delete_chunks_by_filters, get_chunks_from_store as get_chunks_from_store
+from typing import Any
+
+class InMemoryFulltextCapability:
+    """In-memory implementation of FulltextCapability protocol.
+
+    This class provides document CRUD operations and flexible querying using pure
+    Python data structures optimized for development and testing.
+
+    Attributes:
+        store (dict[str, Chunk]): Dictionary storing Chunk objects with their IDs as keys.
+    """
+    store: dict[str, Chunk]
+    def __init__(self, store: dict[str, Any] | None = None) -> None:
+        """Initialize the in-memory fulltext capability.
+
+        Args:
+            store (dict[str, Any] | None, optional): Dictionary storing Chunk objects with their IDs as keys.
+                Defaults to None.
+        """
+    async def create(self, data: Chunk | list[Chunk]) -> None:
+        '''Create new records in the datastore.
+
+        Examples:
+            Create a new chunk.
+            ```python
+            await fulltext_capability.create(Chunk(content="Test chunk", metadata={"category": "test"}))
+            ```
+
+        Args:
+            data (Chunk | list[Chunk]): Data to create (single item or collection).
+
+        Raises:
+            ValueError: If data structure is invalid.
+        '''
+    async def retrieve(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+        '''Read records from the datastore with optional filtering.
+
+        Usage Example:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            results = await fulltext_capability.retrieve(filters=F.eq("metadata.category", "tech"))
+
+            # Multiple filters
+            results = await fulltext_capability.retrieve(
+                filters=F.and_(F.eq("metadata.category", "tech"), F.eq("metadata.status", "active"))
+            )
+            ```
+
+        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 for sorting and pagination. Defaults to None.
+
+        Returns:
+            list[Chunk]: List of matched chunks after applying filters and options.
+        '''
+    async def retrieve_fuzzy(self, query: str, max_distance: int = 2, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+        """Find records that fuzzy match the query within distance threshold.
+
+        Args:
+            query (str): Text to fuzzy match against.
+            max_distance (int, optional): Maximum edit distance for matches. 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, only limit is used here. Defaults to None.
+
+        Returns:
+            list[Chunk]: Matched chunks ordered by distance (ascending), limited by options.limit.
+        """
+    async def update(self, update_values: dict[str, Any], filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Update existing records in the datastore.
+
+        Examples:
+            Update certain metadata of a chunk with specific filters.
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            await fulltext_capability.update(
+                update_values={"metadata": {"status": "published"}},
+                filters=F.eq("metadata.category", "tech"),
+            )
+
+            # Multiple filters
+            await fulltext_capability.update(
+                update_values={"metadata": {"status": "published"}},
+                filters=F.and_(F.eq("metadata.status", "draft"), F.eq("metadata.category", "tech")),
+            )
+            ```
+
+        Args:
+            update_values (dict[str, Any]): Mapping of fields to new values to apply.
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to update.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+        '''
+    async def delete(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> None:
+        '''Delete records from the datastore.
+
+        Usage Example:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            await fulltext_capability.delete(filters=F.eq("metadata.category", "tech"))
+
+            # Multiple filters
+            await fulltext_capability.delete(
+                filters=F.and_(F.eq("metadata.category", "tech"), F.eq("metadata.status", "draft"))
+            )
+            ```
+
+        Args:
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to delete.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+            options (QueryOptions | None, optional): Query options for sorting and limiting deletions
+                (for eviction-like operations). Defaults to None.
+
+        Returns:
+            None: This method performs deletions in-place.
+        '''
+    async def clear(self) -> None:
+        """Clear all records from the datastore."""

gllm_datastore/data_store/in_memory/query.pyi

@@ -0,0 +1,175 @@
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.constants import CHUNK_KEYS as CHUNK_KEYS
+from gllm_datastore.core.filters import FilterClause as FilterClause, FilterCondition as FilterCondition, FilterOperator as FilterOperator, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_inference.schema import Vector
+from typing import Any
+
+def apply_filters(chunks: list[Chunk], filters: FilterClause | QueryFilter) -> list[Chunk]:
+    '''Apply filters to chunks.
+
+    Usage Example:
+        ```python
+        from gllm_datastore.core.filters import filter as F
+
+        chunks = [
+            Chunk(id="1", content="Chunk 1", metadata={"category": "test"}),
+            Chunk(id="2", content="Chunk 2", metadata={"category": "test"}),
+            Chunk(id="3", content="Chunk 3", metadata={"category": "test"}),
+        ]
+        # Direct FilterClause usage
+        filters = F.eq("metadata.category", "test")
+        filtered_chunks = apply_filters(chunks, filters)
+
+        # Multiple filters
+        filters = F.and_(F.eq("metadata.category", "test"), F.eq("metadata.status", "active"))
+        filtered_chunks = apply_filters(chunks, filters)
+        ```
+
+    Args:
+        chunks (list[Chunk]): List of chunks to filter.
+        filters (FilterClause | QueryFilter): Filter criteria to apply.
+            FilterClause objects are automatically converted to QueryFilter internally.
+
+    Returns:
+        list[Chunk]: Filtered list of chunks.
+    '''
+def apply_options(chunks: list[Chunk], options: QueryOptions) -> list[Chunk]:
+    """Apply query options (sorting, pagination).
+
+    Note: columns filtering is not applicable to Chunk objects since they have a fixed structure
+    and we can only filter on id, content, score, and metadata.
+
+    Args:
+        chunks (list[Chunk]): List of chunks to process.
+        options (QueryOptions): Query options to apply.
+
+    Returns:
+        list[Chunk]: Processed list of chunks.
+    """
+def get_nested_value(obj: dict[str, Any], key_path: str) -> Any:
+    '''Get a nested value from a dictionary using dot notation.
+
+    Args:
+        obj (dict[str, Any]): Dictionary to traverse.
+        key_path (str): Dot-separated path to the value (e.g., "user.profile.name").
+
+    Returns:
+        Any: The value at the specified path, or None if not found.
+    '''
+def get_sort_value(chunk: Chunk, order_by: str) -> Any:
+    """Get the value to sort by.
+
+    Args:
+        chunk (Chunk): Chunk to get the value from.
+        order_by (str): The field to sort by.
+
+    Returns:
+        Any: The value to sort by.
+    """
+def validate_cache_key(key: str) -> None:
+    """Validate cache key format and content.
+
+    Args:
+        key (str): Cache key to validate.
+
+    Raises:
+        TypeError: If key is not a string.
+        ValueError: If key is empty or whitespace-only.
+    """
+def get_chunks_from_store(store: dict[str, Chunk], filters: QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+    """Get chunks from a store as a list with optional filters and options.
+
+    Args:
+        store (dict[str, Chunk]): Store containing chunks.
+        filters (QueryFilter | None, optional): Filter criteria to apply. Defaults to None.
+        options (QueryOptions | None, optional): Query options to apply. Defaults to None.
+
+    Returns:
+        list[Chunk]: List of all chunks in the store.
+    """
+def apply_filters_and_options(chunks: list[Chunk], filters: QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+    """Apply filters and options to a list of chunks.
+
+    Args:
+        chunks (list[Chunk]): List of chunks to process.
+        filters (QueryFilter | None, optional): Filter criteria to apply. Defaults to None.
+        options (QueryOptions | None, optional): Query options to apply. Defaults to None.
+
+    Returns:
+        list[Chunk]: Processed list of chunks.
+    """
+def create_updated_chunk(existing_chunk: Chunk, update_values: dict[str, Any]) -> Chunk:
+    """Create an updated chunk with new values.
+
+    Args:
+        existing_chunk (Chunk): The existing chunk to update.
+        update_values (dict[str, Any]): Values to update.
+
+    Returns:
+        Chunk: Updated chunk with new values.
+    """
+def delete_chunks_by_filters(store: dict[str, Chunk], filters: QueryFilter | None = None) -> int:
+    """Delete chunks from store based on filters.
+
+    Args:
+        store (dict[str, Chunk]): Store containing chunks.
+        filters (QueryFilter | None, optional): Filters to select chunks to delete. Defaults to None.
+
+    Returns:
+        int: Number of chunks deleted.
+    """
+def find_matching_chunk_ids(store: dict[str, Chunk], filters: QueryFilter) -> list[str]:
+    """Find chunk IDs that match the given filters.
+
+    Args:
+        store (dict[str, Chunk]): Store containing chunks.
+        filters (QueryFilter): The filters to apply.
+
+    Returns:
+        list[str]: List of chunk IDs that match the filters.
+    """
+def similarity_search(query_vector: Vector, store: dict[str, Chunk], filters: QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+    """Retrieve chunks by vector similarity from a store.
+
+    This method will only return chunks that have a vector in their metadata.
+    It will also apply the filters and options to the chunks.
+
+    Args:
+        query_vector (Vector): Query embedding vector.
+        store (dict[str, Chunk]): Store containing chunks.
+        filters (QueryFilter | None): Query filters to apply.
+        options (QueryOptions | None, optional): Query options to apply.
+
+    Returns:
+        list[Chunk]: List of chunks ordered by similarity score.
+    """
+def evaluate_filter(chunk: Chunk, filters: QueryFilter) -> bool:
+    '''Evaluate if a chunk matches the given filters.
+
+    Examples:
+        ```python
+        from gllm_datastore.core.filters import filter as F
+
+        # Simple filter
+        filters = F.and_(F.eq("metadata.category", "tech"))
+        result = evaluate_filter(chunk, filters)
+
+        # Complex nested filter
+        filters = F.and_(
+            F.gte("metadata.price", 10),
+            F.lte("metadata.price", 100),
+            F.or_(
+                F.eq("metadata.status", "active"),
+                F.eq("metadata.status", "pending")
+            )
+        )
+        result = evaluate_filter(chunk, filters)
+        ```
+
+    Args:
+        chunk (Chunk): The chunk to evaluate.
+        filters (QueryFilter): The filters to apply.
+
+    Returns:
+        bool: True if the chunk matches all filters, False otherwise.
+    '''

gllm_datastore/data_store/in_memory/vector.pyi

@@ -0,0 +1,174 @@
+from gllm_core.schema.chunk import Chunk
+from gllm_datastore.constants import CHUNK_KEYS as CHUNK_KEYS
+from gllm_datastore.core.filters import FilterClause as FilterClause, QueryFilter as QueryFilter, QueryOptions as QueryOptions
+from gllm_datastore.data_store.in_memory.query import create_updated_chunk as create_updated_chunk, delete_chunks_by_filters as delete_chunks_by_filters, get_chunks_from_store as get_chunks_from_store, similarity_search as similarity_search
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from gllm_inference.schema import Vector
+from typing import Any
+
+class InMemoryVectorCapability:
+    """In-memory implementation of VectorCapability protocol.
+
+    This class provides vector similarity search operations using pure Python
+    data structures optimized for development and testing.
+
+    Attributes:
+        store (dict[str, Chunk]): Dictionary storing Chunk objects with their IDs as keys.
+        em_invoker (BaseEMInvoker): The embedding model to perform vectorization.
+    """
+    store: dict[str, Chunk]
+    def __init__(self, em_invoker: BaseEMInvoker, store: dict[str, Any] | None = None) -> None:
+        """Initialize the in-memory vector capability.
+
+        Args:
+            em_invoker (BaseEMInvoker): em_invoker model for text-to-vector conversion.
+            store (dict[str, Any] | None, optional): Dictionary storing Chunk objects with their IDs as keys.
+                Defaults to None.
+        """
+    @property
+    def em_invoker(self) -> BaseEMInvoker:
+        """Returns the EM Invoker instance.
+
+        Returns:
+            BaseEMInvoker: The EM Invoker instance.
+        """
+    async def ensure_index(self) -> None:
+        """Ensure in-memory vector store exists, initializing it if necessary.
+
+        This method is idempotent - if the store already exists, it will skip
+        initialization and return early.
+        """
+    async def create(self, data: Chunk | list[Chunk]) -> None:
+        """Add chunks to the vector store with automatic embedding generation.
+
+        Args:
+            data (Chunk | list[Chunk]): Single chunk or list of chunks to add.
+        """
+    async def create_from_vector(self, chunk_vectors: list[tuple[Chunk, Vector]]) -> None:
+        """Add pre-computed vectors directly.
+
+        Args:
+            chunk_vectors (list[tuple[Chunk, Vector]]): List of tuples containing chunks and their
+                corresponding vectors.
+        """
+    async def retrieve(self, query: str, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+        '''Read records from the datastore using text-based similarity search with optional filtering.
+
+        Usage Example:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            await vector_capability.retrieve(
+                query="What is the capital of France?",
+                filters=F.eq("metadata.category", "tech"),
+                options=QueryOptions(limit=2),
+            )
+
+            # Multiple filters
+            filters = F.and_(F.eq("metadata.source", "wikipedia"), F.eq("metadata.category", "tech"))
+            await vector_capability.retrieve(
+                query="What is the capital of France?",
+                filters=filters,
+                options=QueryOptions(limit=2),
+            )
+            ```
+            This will retrieve the top 2 chunks by similarity score from the vector store
+            that match the query and the filters. The chunks will be sorted by score in descending order.
+
+        Args:
+            query (str): Input text to embed and search with.
+            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, in which case, no sorting is applied and top 10 chunks are returned.
+
+        Returns:
+            list[Chunk]: Top ranked chunks by similarity score.
+        '''
+    async def retrieve_by_vector(self, vector: Vector, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> list[Chunk]:
+        """Direct vector similarity search.
+
+        Args:
+            vector (Vector): Query embedding vector.
+            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, in which case, no sorting is applied and top 10 chunks are returned.
+
+        Returns:
+            list[Chunk]: List of chunks ordered by similarity score.
+        """
+    async def update(self, update_values: dict[str, Any], filters: FilterClause | QueryFilter | None = None, **kwargs: Any) -> None:
+        '''Update existing records in the datastore.
+
+        Examples:
+            1. Update certain metadata of a chunk with specific filters.
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            await vector_capability.update(
+                update_values={"metadata": {"status": "published"}},
+                filters=F.eq("metadata.category", "tech"),
+            )
+
+            # Multiple filters
+            await vector_capability.update(
+                update_values={"metadata": {"status": "published"}},
+                filters=F.and_(F.eq("metadata.status", "draft"), F.eq("metadata.category", "tech")),
+            )
+            ```
+
+            2. Update certain content of a chunk with specific id.
+            This will also regenerate the vector of the chunk.
+            ```python
+            # Direct FilterClause usage
+            await vector_capability.update(
+                update_values={"content": "new_content"},
+                filters=F.eq("id", "unique_id"),
+            )
+
+            # Multiple filters
+            await vector_capability.update(
+                update_values={"content": "new_content"},
+                filters=F.and_(F.eq("id", "unique_id"), F.eq("metadata.category", "tech")),
+            )
+            ```
+
+        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, in which case no operation is performed (no-op).
+            **kwargs: Datastore-specific parameters.
+
+        Raises:
+            ValueError: If content is empty.
+        '''
+    async def delete(self, filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Delete records from the datastore.
+
+        Usage Example:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Direct FilterClause usage
+            await vector_capability.delete(filters=F.eq("metadata.category", "AI"))
+
+            # Multiple filters
+            await vector_capability.delete(
+                filters=F.and_(F.eq("metadata.category", "AI"), F.eq("metadata.status", "published")),
+            )
+            ```
+            This will delete all chunks from the vector store that match the filters.
+
+        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).
+        '''
+    async def clear(self) -> None:
+        """Clear all vectors from the store."""

gllm_datastore/data_store/redis/__init__.pyi

@@ -0,0 +1,5 @@
+from gllm_datastore.data_store.redis.data_store import RedisDataStore as RedisDataStore
+from gllm_datastore.data_store.redis.fulltext import RedisFulltextCapability as RedisFulltextCapability
+from gllm_datastore.data_store.redis.vector import RedisVectorCapability as RedisVectorCapability
+
+__all__ = ['RedisDataStore', 'RedisFulltextCapability', 'RedisVectorCapability']

gllm_datastore/data_store/redis/data_store.pyi

@@ -0,0 +1,154 @@
+from _typeshed import Incomplete
+from gllm_datastore.core.filters.schema import FilterClause as FilterClause, QueryFilter as QueryFilter
+from gllm_datastore.data_store.base import BaseDataStore as BaseDataStore, CapabilityType as CapabilityType
+from gllm_datastore.data_store.redis.fulltext import RedisFulltextCapability as RedisFulltextCapability
+from gllm_datastore.data_store.redis.query import get_filterable_fields_from_index as get_filterable_fields_from_index
+from gllm_datastore.data_store.redis.query_translator import RedisQueryTranslator as RedisQueryTranslator
+from gllm_datastore.data_store.redis.vector import RedisVectorCapability as RedisVectorCapability
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from redis.asyncio.client import Redis
+
+class RedisDataStore(BaseDataStore):
+    """Redis data store with fulltext capability support.
+
+    Attributes:
+        index_name (str): Name for the Redis index.
+        client (Redis): Redis client instance.
+    """
+    client: Incomplete
+    index_name: Incomplete
+    def __init__(self, index_name: str, url: str | None = None, client: Redis | None = None) -> None:
+        """Initialize the Redis data store.
+
+        Args:
+            index_name (str): Name of the Redis index to use.
+            url (str | None, optional): URL for Redis connection. Defaults to None.
+                Format: redis://[[username]:[password]]@host:port/database
+            client (Redis | None, optional): Redis client instance to use. Defaults to None.
+                in which case the url parameter will be used to create a new Redis client.
+
+        Raises:
+            ValueError: If neither `url` nor `client` is provided, or if URL is invalid.
+            TypeError: If `client` is not a Redis instance.
+            ConnectionError: If Redis connection fails.
+        """
+    @property
+    def supported_capabilities(self) -> list[CapabilityType]:
+        """Return list of currently supported capabilities.
+
+        Returns:
+            list[CapabilityType]: List of capability names that are supported.
+        """
+    @property
+    def fulltext(self) -> RedisFulltextCapability:
+        """Access fulltext capability if registered.
+
+        This method uses the logic of its parent class to return the fulltext capability handler.
+        This method overrides the parent class to return the RedisFulltextCapability handler for better
+        type hinting.
+
+        Returns:
+            RedisFulltextCapability: Fulltext capability handler.
+
+        Raises:
+            NotRegisteredException: If fulltext capability is not registered.
+        """
+    @property
+    def vector(self) -> RedisVectorCapability:
+        """Access vector capability if registered.
+
+        This method uses the logic of its parent class to return the vector capability handler.
+        This method overrides the parent class to return the RedisVectorCapability handler for better
+        type hinting.
+
+        Returns:
+            RedisVectorCapability: Vector capability handler.
+
+        Raises:
+            NotRegisteredException: If vector capability is not registered.
+        """
+    def with_fulltext(self, index_name: str | None = None) -> RedisDataStore:
+        """Configure fulltext capability and return datastore instance.
+
+        Schema will be automatically inferred from chunks when creating a new index,
+        or auto-detected from an existing index when performing operations.
+
+        Args:
+            index_name (str | None, optional): The name of the Redis index. Defaults to None,
+                in which case the default class attribute will be utilized.
+
+        Returns:
+            RedisDataStore: RedisDataStore instance for method chaining.
+        """
+    def with_vector(self, em_invoker: BaseEMInvoker, index_name: str | None = None) -> RedisDataStore:
+        """Configure vector capability and return datastore instance.
+
+        Schema will be automatically inferred from chunks when creating a new index,
+        or auto-detected from an existing index when performing operations.
+
+        Args:
+            em_invoker (BaseEMInvoker): The embedding model to perform vectorization.
+            index_name (str | None, optional): The name of the Redis index. Defaults to None,
+                in which case the default class attribute will be utilized.
+
+        Returns:
+            RedisDataStore: RedisDataStore instance for method chaining.
+
+        Raises:
+            ValueError: If em_invoker is not provided.
+        """
+    def translate_query_filter(self, query_filter: FilterClause | QueryFilter | None = None) -> str | None:
+        '''Translate QueryFilter or FilterClause to Redis native filter syntax.
+
+        This method delegates to the existing RedisQueryTranslator in the
+        redis.query_translator module and returns the result as a string.
+        It uses the instance\'s index_name and client to detect field types
+        for accurate Redis Search query syntax.
+
+        Examples:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            # Create datastore instance
+            datastore = RedisDataStore(index_name="my_index", url="redis://localhost:6379")
+
+            # Single FilterClause (field types detected from index schema)
+            clause = F.eq("metadata.status", "active")
+            result = datastore.translate_query_filter(clause)
+            # Returns: "@metadata_status:{active}" if status is a TAG field
+            # Returns: "@metadata_status:active" if status is a TEXT field
+
+            # QueryFilter with multiple clauses (AND condition)
+            filter_obj = F.and_(
+                F.eq("metadata.status", "active"),
+                F.gt("metadata.age", 25),
+            )
+            result = datastore.translate_query_filter(filter_obj)
+            # Returns: "@metadata_status:{active} @metadata_age:[(25 +inf]"
+
+            # QueryFilter with OR condition
+            filter_obj = F.or_(
+                F.eq("metadata.status", "active"),
+                F.eq("metadata.status", "pending"),
+            )
+            result = datastore.translate_query_filter(filter_obj)
+            # Returns: "@metadata_status:{active} | @metadata_status:{pending}"
+
+            # IN operator (produces parentheses syntax)
+            filter_obj = F.in_("metadata.category", ["tech", "science"])
+            result = datastore.translate_query_filter(filter_obj)
+            # Returns: "@metadata_category:(tech|science)"
+
+            # Empty filter returns None
+            result = datastore.translate_query_filter(None)
+            # Returns: None
+            ```
+
+        Args:
+            query_filter (FilterClause | QueryFilter | None, optional): The filter to translate.
+                Can be a single FilterClause, a QueryFilter with multiple clauses. Defaults to None.
+
+        Returns:
+            str | None: The translated filter as a Redis Search query string.
+                Returns None if no filter is provided.
+        '''