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

gllm_datastore/data_store/chroma/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_datastore.data_store.chroma.data_store import ChromaDataStore as ChromaDataStore
+from gllm_datastore.data_store.chroma.fulltext import ChromaFulltextCapability as ChromaFulltextCapability
+
+__all__ = ['ChromaDataStore', 'ChromaFulltextCapability']

gllm_datastore/data_store/chroma/_chroma_import.pyi

@@ -0,0 +1,13 @@
+import chromadb
+
+def safe_import_chromadb() -> chromadb:
+    """Import and return the `chromadb` module with SQLite fallback.
+
+    This function centralizes the logic to import `chromadb`, applying the
+    `pysqlite3` fallback for environments where the built-in sqlite3 causes
+    issues. Other modules should use `safe_import_chromadb()` to
+    avoid duplication.
+
+    Returns:
+        ModuleType: The imported `chromadb` module.
+    """

gllm_datastore/data_store/chroma/data_store.pyi

@@ -0,0 +1,201 @@
+from _typeshed import Incomplete
+from enum import StrEnum
+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.chroma._chroma_import import safe_import_chromadb as safe_import_chromadb
+from gllm_datastore.data_store.chroma.fulltext import ChromaFulltextCapability as ChromaFulltextCapability
+from gllm_datastore.data_store.chroma.query import DEFAULT_NUM_CANDIDATES as DEFAULT_NUM_CANDIDATES
+from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator as ChromaQueryTranslator
+from gllm_datastore.data_store.chroma.vector import ChromaVectorCapability as ChromaVectorCapability
+from gllm_inference.em_invoker.em_invoker import BaseEMInvoker
+from typing import Any
+
+chromadb: Incomplete
+
+class ChromaClientType(StrEnum):
+    """Enum for different types of ChromaDB clients."""
+    MEMORY: str
+    PERSISTENT: str
+    HTTP: str
+
+class ChromaDataStore(BaseDataStore):
+    """ChromaDB data store with multiple capability support.
+
+    Attributes:
+        collection_name (str): The name of the ChromaDB collection.
+        client (chromadb.ClientAPI): The ChromaDB client instance.
+    """
+    collection_name: Incomplete
+    client: Incomplete
+    def __init__(self, collection_name: str, client_type: ChromaClientType = ..., persist_directory: str | None = None, host: str | None = None, port: int | None = None, headers: dict | None = None, client_settings: dict | None = None) -> None:
+        """Initialize the ChromaDB data store.
+
+        Args:
+            collection_name (str): The name of the ChromaDB collection.
+            client_type (ChromaClientType, optional): Type of ChromaDB client to use.
+                Defaults to ChromaClientType.MEMORY.
+            persist_directory (str | None, optional): Directory to persist vector store data.
+                Required for PERSISTENT client type. Defaults to None.
+            host (str | None, optional): Host address for ChromaDB server.
+                Required for HTTP client type. Defaults to None.
+            port (int | None, optional): Port for ChromaDB server.
+                Required for HTTP client type. Defaults to None.
+            headers (dict | None, optional): A dictionary of headers to send to the Chroma server.
+                Used for authentication with the Chroma server for HTTP client type. Defaults to None.
+            client_settings (dict | None, optional): A dictionary of additional settings for the Chroma client.
+                Defaults to None.
+        """
+    @property
+    def supported_capabilities(self) -> list[str]:
+        """Return list of currently supported capabilities.
+
+        Returns:
+            list[str]: List of capability names that are supported.
+        """
+    @property
+    def fulltext(self) -> ChromaFulltextCapability:
+        """Access fulltext capability if supported.
+
+        This method uses the logic of its parent class to return the fulltext capability handler.
+        This method overrides the parent class to return the ChromaFulltextCapability handler for better
+        type hinting.
+
+        Returns:
+            ChromaFulltextCapability: Fulltext capability handler.
+
+        Raises:
+            NotSupportedException: If fulltext capability is not supported.
+        """
+    @property
+    def vector(self) -> ChromaVectorCapability:
+        """Access vector capability if supported.
+
+        This method uses the logic of its parent class to return the vector capability handler.
+        This method overrides the parent class to return the ChromaVectorCapability handler for better
+        type hinting.
+
+        Returns:
+            ChromaVectorCapability: Vector capability handler.
+
+        Raises:
+            NotSupportedException: If vector capability is not supported.
+        """
+    def with_fulltext(self, collection_name: str | None = None, num_candidates: int = ...) -> ChromaDataStore:
+        """Configure fulltext capability and return datastore instance.
+
+        This method uses the logic of its parent class to configure the fulltext capability.
+        This method overrides the parent class for better type hinting.
+
+        Args:
+            collection_name (str | None, optional): Name of the collection to use in ChromaDB. Defaults to None,
+                in which case the default class attribute will be utilized.
+            num_candidates (int, optional): Maximum number of candidates to consider during search.
+                Defaults to DEFAULT_NUM_CANDIDATES.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    def with_vector(self, em_invoker: BaseEMInvoker, collection_name: str | None = None, num_candidates: int = ...) -> ChromaDataStore:
+        """Configure vector capability and return datastore instance.
+
+        This method uses the logic of its parent class to configure the vector capability.
+        This method overrides the parent class for better type hinting.
+
+        Args:
+            em_invoker (BaseEMInvoker): The embedding model to perform vectorization.
+            collection_name (str | None, optional): Name of the collection to use in ChromaDB. Defaults to None,
+                in which case the default class attribute will be utilized.
+            num_candidates (int, optional): Maximum number of candidates to consider during search.
+                Defaults to DEFAULT_NUM_CANDIDATES.
+
+        Returns:
+            Self: Self for method chaining.
+        """
+    @classmethod
+    def translate_query_filter(cls, query_filter: FilterClause | QueryFilter) -> dict[str, Any]:
+        '''Translate QueryFilter or FilterClause to ChromaDB native filter syntax.
+
+        This method uses ChromaQueryTranslator to translate filters and returns
+        the result as a dictionary.
+
+        Examples:
+            1. Translate a simple FilterClause:
+                ```python
+                from gllm_datastore.core.filters import filter as F
+
+                filter_clause = F.eq("metadata.status", "active")
+                result = ChromaDataStore.translate_query_filter(filter_clause)
+                # result -> {"where": {"status": "active"}}
+                ```
+
+            2. Translate QueryFilter with metadata filters:
+                ```python
+                from gllm_datastore.core.filters import filter as F
+
+                filters = F.and_(
+                    F.eq("metadata.category", "tech"),
+                    F.gte("metadata.price", 10),
+                )
+                result = ChromaDataStore.translate_query_filter(filters)
+                # result ->
+                # {
+                #   "where": {
+                #     "$and": [
+                #       {"category": "tech"},
+                #       {"price": {"$gte": 10}}
+                #     ]
+                #   }
+                # }
+                ```
+
+            3. Translate QueryFilter with content filters:
+                ```python
+                from gllm_datastore.core.filters import filter as F
+
+                filters = F.text_contains("content", "python")
+                result = ChromaDataStore.translate_query_filter(filters)
+                # result -> {"where_document": {"$contains": "python"}}
+                ```
+
+            4. Translate QueryFilter with id filters:
+                ```python
+                from gllm_datastore.core.filters import filter as F
+
+                filters = F.in_("id", ["chunk_1", "chunk_2"])
+                result = ChromaDataStore.translate_query_filter(filters)
+                # result -> {"ids": ["chunk_1", "chunk_2"]}
+                ```
+
+            5. Translate complex nested QueryFilter:
+                ```python
+                from gllm_datastore.core.filters import filter as F
+
+                filters = F.and_(
+                    F.or_(
+                        F.eq("metadata.status", "active"),
+                        F.eq("metadata.status", "pending"),
+                    ),
+                    F.text_contains("content", "machine learning"),
+                    F.in_("id", ["chunk_1", "chunk_2"]),
+                )
+                result = ChromaDataStore.translate_query_filter(filters)
+                # result ->
+                # {
+                #   "where": {
+                #     "$or": [
+                #       {"status": "active"},
+                #       {"status": "pending"}
+                #     ]
+                #   },
+                #   "where_document": {"$contains": "machine learning"},
+                #   "ids": ["chunk_1", "chunk_2"]
+                # }
+                ```
+
+        Args:
+            query_filter (FilterClause | QueryFilter): The filter to translate.
+                Can be a single FilterClause or a QueryFilter with multiple clauses.
+
+        Returns:
+            dict[str, Any] | None: The translated filter as a ChromaDB query dict.
+        '''

gllm_datastore/data_store/chroma/fulltext.pyi

@@ -0,0 +1,134 @@
+from _typeshed import Incomplete
+from chromadb import ClientAPI
+from gllm_core.schema import Chunk
+from gllm_datastore.constants import CHUNK_KEYS as CHUNK_KEYS, 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.chroma._chroma_import import safe_import_chromadb as safe_import_chromadb
+from gllm_datastore.data_store.chroma.query import ChromaCollectionKeys as ChromaCollectionKeys, DEFAULT_NUM_CANDIDATES as DEFAULT_NUM_CANDIDATES, build_chroma_delete_kwargs as build_chroma_delete_kwargs, build_chroma_get_kwargs as build_chroma_get_kwargs, sanitize_metadata as sanitize_metadata
+from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator as ChromaQueryTranslator
+from typing import Any
+
+chromadb: Incomplete
+
+class ChromaFulltextCapability:
+    """ChromaDB implementation of FulltextCapability protocol.
+
+    This class provides document CRUD operations and text search using ChromaDB.
+
+    Attributes:
+        collection_name (str): The name of the ChromaDB collection.
+        client (ClientAPI): ChromaDB client instance.
+        collection: ChromaDB collection instance.
+        num_candidates (int): Maximum number of candidates to consider during search.
+    """
+    collection_name: Incomplete
+    client: Incomplete
+    collection: Incomplete
+    num_candidates: Incomplete
+    def __init__(self, collection_name: str, client: ClientAPI, num_candidates: int = ...) -> None:
+        """Initialize the ChromaDB fulltext capability.
+
+        Args:
+            collection_name (str): The name of the ChromaDB collection.
+            client (ClientAPI): ChromaDB client instance.
+            num_candidates (int, optional): Maximum number of candidates to consider during search.
+                Defaults to DEFAULT_NUM_CANDIDATES.
+        """
+    def get_size(self) -> int:
+        """Returns the total number of documents in the collection.
+
+        Returns:
+            int: The total number of documents.
+        """
+    async def create(self, data: Chunk | list[Chunk], **kwargs: Any) -> None:
+        """Create new records in the datastore.
+
+        Args:
+            data (Chunk | list[Chunk]): Data to create (single item or collection).
+            **kwargs: Backend-specific parameters.
+
+        Raises:
+            ValueError: If data structure is invalid.
+        """
+    async def retrieve(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None, **kwargs: Any) -> 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 (sorting, pagination, etc.).
+                Defaults to None.
+            **kwargs: Backend-specific parameters.
+
+        Returns:
+            list[Chunk]: Query results.
+
+        Raises:
+            NotImplementedError: If unsupported operators are used for id or content filters.
+        '''
+    async def retrieve_fuzzy(self, query: str, max_distance: int = 2, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None, **kwargs: Any) -> 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. 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 (sorting, limit, etc.). Defaults to None.
+            **kwargs: Backend-specific parameters.
+
+        Returns:
+            list[Chunk]: Matched chunks ordered by distance (ascending) or by options.order_by if specified.
+        """
+    async def update(self, update_values: dict[str, Any], filters: FilterClause | QueryFilter | None = None) -> None:
+        '''Update existing records in the datastore.
+
+        Examples:
+            Update the content and metadata of the chunk with the id "unique_id" to "updated_content"
+            and "published" respectively.
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            await fulltext_capability.update(
+                update_values={"content": "updated_content", "metadata": {"status": "published"}},
+                filters=F.eq("id", "unique_id"),
+            )
+            ```
+
+        Args:
+            update_values (dict[str, Any]): Values to update. Supports "content" for updating document content
+                and "metadata" for updating metadata. Other keys are treated as direct metadata updates.
+            filters (FilterClause | QueryFilter | None, optional): Filters to select records to update.
+                FilterClause objects are automatically converted to QueryFilter internally.
+                Defaults to None.
+
+        Note:
+            ChromaDB doesn\'t support direct update operations. This method will
+            retrieve matching records, update them, and re-add them to the collection.
+        '''
+    async def delete(self, filters: FilterClause | QueryFilter | None = None, options: QueryOptions | None = None) -> 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.
+        """
+    async def clear(self) -> None:
+        """Clear all records from the datastore."""

gllm_datastore/data_store/chroma/query.pyi

@@ -0,0 +1,266 @@
+import logging
+from chromadb.types import Where, WhereDocument
+from dataclasses import dataclass
+from enum import StrEnum
+from gllm_datastore.core.filters.schema import FilterOperator as FilterOperator, QueryFilter as QueryFilter
+from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator as ChromaQueryTranslator
+from typing import Any
+
+DEFAULT_NUM_CANDIDATES: int
+
+class ChromaCollectionKeys:
+    """Constants for ChromaDB collection method keyword arguments.
+
+    This class provides constants for all string literals used in ChromaDB
+    collection method calls (get, delete, query, etc.) to avoid magic strings
+    and improve maintainability.
+
+    Attributes:
+        WHERE (str): Keyword for metadata filtering condition.
+        WHERE_DOCUMENT (str): Keyword for document content filtering condition.
+        IDS (str): Keyword for filtering by document IDs.
+        INCLUDE (str): Keyword for specifying fields to include in results.
+        LIMIT (str): Keyword for limiting the number of results.
+        METADATA_PREFIX (str): Prefix for metadata field keys.
+    """
+    WHERE: str
+    WHERE_DOCUMENT: str
+    IDS: str
+    INCLUDE: str
+    LIMIT: str
+    METADATA_PREFIX: str
+
+class ChromaOperators(StrEnum):
+    """Constants for ChromaDB query operators.
+
+    This class provides constants for all operator string literals used in
+    ChromaDB query expressions to avoid magic strings and improve maintainability.
+
+    Attributes:
+        AND (str): Logical AND operator for combining filters.
+        OR (str): Logical OR operator for combining filters.
+        NE (str): Not equal comparison operator.
+        GT (str): Greater than comparison operator.
+        LT (str): Less than comparison operator.
+        GTE (str): Greater than or equal comparison operator.
+        LTE (str): Less than or equal comparison operator.
+        IN (str): Array membership operator (value in list).
+        NIN (str): Array non-membership operator (value not in list).
+        TEXT_CONTAINS (str): Document content substring match operator.
+        NOT_CONTAINS (str): Document content substring exclusion operator.
+    """
+    AND: str
+    OR: str
+    NE: str
+    GT: str
+    LT: str
+    GTE: str
+    LTE: str
+    IN: str
+    NIN: str
+    TEXT_CONTAINS: str
+    NOT_CONTAINS: str
+
+class ChromaOperatorMapper:
+    """Maps FilterOperator to ChromaDB operators and provides inverse operator mappings.
+
+    This class encapsulates operator translation logic.
+
+    Attributes:
+        OPERATOR_TO_CHROMA (dict[FilterOperator, str]): Mapping from FilterOperator to ChromaDB operators.
+        OPERATOR_INVERSE (dict[FilterOperator, FilterOperator]): Mapping from FilterOperator to its inverse operator.
+    """
+    OPERATOR_TO_CHROMA: dict[FilterOperator, str]
+    OPERATOR_INVERSE: dict[FilterOperator, FilterOperator]
+    @classmethod
+    def get_inverse_operator(cls, operator: FilterOperator) -> FilterOperator | None:
+        """Get the inverse operator for a given FilterOperator.
+
+        Args:
+            operator (FilterOperator): The operator to get the inverse for.
+
+        Returns:
+            FilterOperator | None: The inverse operator, or None if no inverse exists.
+        """
+    @classmethod
+    def has_inverse(cls, operator: FilterOperator) -> bool:
+        """Check if an operator has an inverse mapping.
+
+        Args:
+            operator (FilterOperator): The operator to check.
+
+        Returns:
+            bool: True if the operator has an inverse, False otherwise.
+        """
+
+@dataclass
+class ChromaQueryComponents:
+    """ChromaDB query components extracted from a QueryFilter.
+
+    Attributes:
+        where_condition (Where | None): Where clause for metadata filters, or None.
+        where_document (WhereDocument | None): WhereDocument clause for content filters, or None.
+        id_values (list[str] | None): List of IDs for id filters, or None.
+    """
+    where_condition: Where | None
+    where_document: WhereDocument | None
+    id_values: list[str] | None
+    def to_dict(self) -> dict[str, Any] | None:
+        """Convert to ChromaDB kwargs dict, omitting None values.
+
+        Returns:
+            dict[str, Any] | None: Dictionary with non-None components,
+                or None if all components are None/empty.
+        """
+
+def sanitize_metadata(metadata: dict[str, Any] | None, logger: logging.Logger) -> dict[str, Any]:
+    '''Sanitize metadata by removing list values that ChromaDB doesn\'t support.
+
+    ChromaDB only supports str, int, float, or bool as metadata values.
+    This function filters out list values and logs warnings for each removed key.
+
+    Examples:
+        1. Remove list values:
+            ```python
+            logger = logging.getLogger(__name__)
+            input_meta = {"status": "active", "tags": ["a", "b"], "age": 30}
+            out = sanitize_metadata(input_meta, logger)
+            # out -> {"status": "active", "age": 30}
+            ```
+
+        2. Handle None input:
+            ```python
+            out = sanitize_metadata(None, logging.getLogger(__name__))
+            # out -> {}
+            ```
+
+    Args:
+        metadata (dict[str, Any] | None): Metadata dictionary to sanitize.
+        logger (logging.Logger): Logger instance for warning messages.
+
+    Returns:
+        dict[str, Any]: Sanitized metadata with list values removed.
+    '''
+def build_chroma_get_kwargs(filters: QueryFilter | None, query_translator: ChromaQueryTranslator, include: list[str] | None = None, limit: int | None = None, **additional_kwargs: Any) -> dict[str, Any]:
+    '''Build kwargs dictionary for ChromaDB collection.get() operations.
+
+    This function processes filters and builds a kwargs dictionary that includes
+    where, where_document, ids, include, and limit parameters as needed.
+
+    Examples:
+        1. Build kwargs with metadata and content filters:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+            from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator
+
+            translator = ChromaQueryTranslator()
+            filters = F.and_(
+                F.eq("metadata.status", "active"),
+                F.text_contains("content", "python"),
+            )
+
+            out = build_chroma_get_kwargs(filters, translator, include=["documents"], limit=10)
+            # out ->
+            # {
+            #   "where": {"status": "active"},
+            #   "where_document": {"$contains": "python"},
+            #   "include": ["documents"],
+            #   "limit": 10
+            # }
+            ```
+
+        2. Build kwargs using id filters:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+            from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator
+
+            translator = ChromaQueryTranslator()
+            filters = F.or_(F.eq("id", "123"), F.in_("id", ["a", "b"]))
+            out = build_chroma_get_kwargs(filters, translator)
+            # out -> {"ids": ["123", "a", "b"]}
+            ```
+
+    Args:
+        filters (QueryFilter | None): QueryFilter to process.
+        query_translator (ChromaQueryTranslator): Query translator instance to use.
+        include (list[str] | None, optional): List of fields to include in results.
+            Defaults to None.
+        limit (int | None, optional): Maximum number of results to return.
+            Defaults to None.
+        **additional_kwargs: Additional kwargs to include in the result.
+
+    Returns:
+        dict[str, Any]: Dictionary of kwargs ready for ChromaDB collection.get() call.
+    '''
+def build_chroma_delete_kwargs(filters: QueryFilter | None, query_translator: ChromaQueryTranslator, **additional_kwargs: Any) -> dict[str, Any]:
+    '''Build kwargs dictionary for ChromaDB collection.delete() operations.
+
+    This function processes filters and builds a kwargs dictionary that includes
+    where, where_document, and ids parameters as needed.
+
+    Examples:
+        1. Delete by ids or where:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+            from gllm_datastore.data_store.chroma.query_translator import ChromaQueryTranslator
+
+            translator = ChromaQueryTranslator()
+            filters = F.and_(
+                F.in_("id", ["x1", "x2"]),
+                F.eq("metadata.status", "inactive"),
+            )
+            out = build_chroma_delete_kwargs(filters, translator)
+            # out ->
+            # {
+            #   "ids": ["x1", "x2"],
+            #   "where": {"status": "inactive"}
+            # }
+            ```
+
+    Args:
+        filters (QueryFilter | None): QueryFilter to process.
+        query_translator (ChromaQueryTranslator): Query translator instance to use.
+        **additional_kwargs: Additional kwargs to include in the result.
+
+    Returns:
+        dict[str, Any]: Dictionary of kwargs ready for ChromaDB collection.delete() call.
+    '''
+def extract_chroma_query_components(filters: QueryFilter | None) -> ChromaQueryComponents:
+    '''Prepare all ChromaDB query parameters from a QueryFilter.
+
+    This function processes a QueryFilter and extracts:
+    1. Metadata filters -> Where clause
+    2. Content filters -> WhereDocument clause
+    3. id filters -> ids parameter
+
+    Only operators natively supported by ChromaDB are allowed:
+    1. id: EQ, IN (using ids parameter)
+    2. content: TEXT_CONTAINS (substring match in document content, maps to $contains)
+    3. metadata: EQ, NE, GT, LT, GTE, LTE, IN, NIN (using where clause)
+    4. metadata: ARRAY_CONTAINS (array membership, not supported by ChromaDB - raises NotImplementedError)
+
+    Examples:
+        1. Extract all components from a mixed filter:
+            ```python
+            from gllm_datastore.core.filters import filter as F
+
+            filters = F.and_(
+                F.eq("metadata.status", "active"),
+                F.text_contains("content", "python"),
+                F.in_("id", ["a", "b"]),
+            )
+            components = extract_chroma_query_components(filters)
+            # components.where_condition -> dict
+            # components.where_document -> dict
+            # components.id_values -> ["a", "b"]
+            ```
+
+    Args:
+        filters (QueryFilter | None): QueryFilter to process.
+
+    Returns:
+        ChromaQueryComponents: Dataclass containing where_condition, where_document, and id_values.
+
+    Raises:
+        NotImplementedError: If unsupported operators are used for id or content filters.
+    '''

gllm_datastore/data_store/chroma/query_translator.pyi

@@ -0,0 +1,41 @@
+from dataclasses import dataclass
+from gllm_datastore.constants import CHUNK_KEYS as CHUNK_KEYS
+from gllm_datastore.core.filters.schema import FilterClause as FilterClause, FilterCondition as FilterCondition, FilterOperator as FilterOperator, QueryFilter as QueryFilter
+from gllm_datastore.data_store.chroma.query import ChromaCollectionKeys as ChromaCollectionKeys, ChromaOperatorMapper as ChromaOperatorMapper, ChromaOperators as ChromaOperators, ChromaQueryComponents as ChromaQueryComponents
+
+@dataclass
+class FilterSeparationResult:
+    """Intermediate result from separating special filters (id, content) from metadata filters.
+
+    Attributes:
+        id_values (list[str] | None): Extracted ID values, or None if no ID filters found.
+        document_filters (list[FilterClause | QueryFilter]): List of content FilterClauses or
+            QueryFilters for where_document. QueryFilters are used to represent NOT conditions.
+        metadata_filters (list[FilterClause | QueryFilter]): Metadata filters for where clause.
+        condition (FilterCondition): The original FilterCondition from the QueryFilter.
+    """
+    id_values: list[str] | None
+    document_filters: list[FilterClause | QueryFilter]
+    metadata_filters: list[FilterClause | QueryFilter]
+    condition: FilterCondition
+
+class ChromaQueryTranslator:
+    """Translates QueryFilter and FilterClause objects to ChromaDB native filter syntax.
+
+    This class encapsulates all query translation logic for ChromaDB, converting
+    structured FilterClause and QueryFilter objects into ChromaDB's where, where_document,
+    and ids parameters.
+    """
+    def translate(self, filters: QueryFilter | None = None) -> ChromaQueryComponents:
+        """Translate QueryFilter to ChromaDB query components.
+
+        This is the main entry point for query translation. It handles None filters
+        and orchestrates filter separation and translation.
+
+        Args:
+            filters (QueryFilter | None, optional): Structured QueryFilter to translate. Defaults to None.
+
+        Returns:
+            ChromaQueryComponents: ChromaDB query components containing where,
+                where_document, and id_values, or None if no filters are provided.
+        """