chroma-haystack 4.2.0__tar.gz → 4.3.1__tar.gz

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [integrations/chroma-v4.3.0] - 2026-04-29
+
+### 🚀 Features
+
+- *(chroma)* Support DuplicatePolicy in write_documents and use async mixin tests (#3245)
+
+### 🚜 Refactor
+
+- Weaviate, chroma, elasticsearch, opensearch, azure_ai_search use `_normalize_metadata_field_name` from haystack.utils (#2953)
+
+### 🧪 Testing
+
+- `ChromaDocumentStore` use Mixin tests (#3026)
+- Track test coverage for all integrations (#3065)
+- Better categorize some Document Stores tests (#3085)
+- Chroma - add unit tests (#3175)
+
+### 🧹 Chores
+
+- Add missing -> None return type annotations to chroma __init__ methods (#2976)
+- Enforce ruff docstring rules (D102/D103/D205/D209/D213/D417/D419) in first 10 integrations (#3008)
+- Increase lower pins for 3.14 support in some integrations + test with 3.14 (#3033)
+
+
+## [integrations/chroma-v4.2.0] - 2026-03-11
+
+### 🚀 Features
+
+- Add support for metadata that contains lists of supported types (#2877)
+
+### 📚 Documentation
+
+- Simplify pydoc configs (#2855)
+
+### 🧪 Testing
+
+- Replacing each `DocumentStore` specific tests and used the generalised ones from `haystack.testing.document_store` (#2812)
+- Chroma - remove tests for invalid Settings (now ignored) (#2935)
+
+### 🧹 Chores
+
+- Remove unused allow-direct-references (#2866)
+- Standardize author mentions (#2897)
+
+
 ## [integrations/chroma-v4.1.1] - 2026-02-10
 
 ### 📚 Documentation

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chroma-haystack
-Version: 4.2.0
+Version: 4.3.1
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/chroma
@@ -14,11 +14,12 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.10
-Requires-Dist: chromadb>=1.5.0
-Requires-Dist: haystack-ai>=2.24.0
+Requires-Dist: chromadb>=1.5.4
+Requires-Dist: haystack-ai>=2.28.0
 Description-Content-Type: text/markdown
 
 # chroma-haystack

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/pyproject.toml

@@ -19,12 +19,13 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
 dependencies = [
-  "haystack-ai>=2.24.0",
-  "chromadb>=1.5.0"
+  "haystack-ai>=2.28.0",
+  "chromadb>=1.5.4"
 ]
 
 [project.urls]
@@ -66,7 +67,8 @@ dependencies = [
 unit = 'pytest -m "not integration" {args:tests}'
 integration = 'pytest -m "integration" {args:tests}'
 all = 'pytest {args:tests}'
-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x {args:tests}'
+unit-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x -m "not integration" {args:tests}'
+integration-cov-append-retry = 'pytest --cov=haystack_integrations --cov-append --reruns 3 --reruns-delay 30 -x -m "integration" {args:tests}'
 
 types = "mypy -p haystack_integrations.components.retrievers.chroma -p haystack_integrations.document_stores.chroma {args}"
 
@@ -83,9 +85,17 @@ line-length = 120
 [tool.ruff.lint]
 select = [
   "A",
+  "ANN",
   "ARG",
   "B",
   "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
   "DTZ",
   "E",
   "EM",
@@ -111,6 +121,8 @@ select = [
 ignore = [
   # Allow non-abstract empty methods in abstract base classes
   "B027",
+  # Allow `Any` - used legitimately for **kwargs and dynamic metadata values
+  "ANN401",
   # Allow boolean positional values in function calls, like `dict.get(... True)`
   "FBT003",
   # Ignore checks for possible passwords
@@ -138,12 +150,13 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["PLR2004", "S101", "TID252", "D", "ANN"]
 "example/**/*" = ["T201"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]
 branch = true
+relative_files = true
 parallel = false
 
 

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/src/haystack_integrations/components/retrievers/chroma/retriever.py

@@ -51,8 +51,10 @@ class ChromaQueryTextRetriever:
         filters: dict[str, Any] | None = None,
         top_k: int = 10,
         filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
-    ):
+    ) -> None:
         """
+        Initialize the ChromaQueryTextRetriever.
+
         :param document_store: an instance of `ChromaDocumentStore`.
         :param filters: filters to narrow down the search space.
         :param top_k: the maximum number of documents to retrieve.
@@ -164,8 +166,10 @@ class ChromaEmbeddingRetriever:
         filters: dict[str, Any] | None = None,
         top_k: int = 10,
         filter_policy: str | FilterPolicy = FilterPolicy.REPLACE,
-    ):
+    ) -> None:
         """
+        Initialize the ChromaEmbeddingRetriever.
+
         :param document_store: an instance of `ChromaDocumentStore`.
         :param filters: filters to narrow down the search space.
         :param top_k: the maximum number of documents to retrieve.

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/src/haystack_integrations/document_stores/chroma/document_store.py

@@ -11,8 +11,9 @@ from chromadb.api.types import GetResult, Metadata, OneOrMany, QueryResult
 from chromadb.config import Settings
 from haystack import default_from_dict, default_to_dict, logging
 from haystack.dataclasses import Document
-from haystack.document_stores.errors import DocumentStoreError
+from haystack.document_stores.errors import DocumentStoreError, DuplicateDocumentError
 from haystack.document_stores.types import DuplicatePolicy
+from haystack.utils.misc import _normalize_metadata_field_name
 
 from .filters import _convert_filters
 from .utils import get_embedding_function
@@ -45,9 +46,10 @@ class ChromaDocumentStore:
         metadata: dict | None = None,
         client_settings: dict[str, Any] | None = None,
         **embedding_function_params: Any,
-    ):
+    ) -> None:
         """
         Creates a new ChromaDocumentStore instance.
+
         It is meant to be connected to a Chroma collection.
 
         Note: for the component to be part of a serializable pipeline, the __init__
@@ -102,7 +104,7 @@ class ChromaDocumentStore:
         self._collection: chromadb.Collection | None = None
         self._async_collection: AsyncCollection | None = None
 
-    def _ensure_initialized(self):
+    def _ensure_initialized(self) -> None:
         if not self._collection:
             # Create the client instance
             if self._persist_path and (self._host or self._port is not None):
@@ -138,9 +140,10 @@ class ChromaDocumentStore:
 
             self._client = client  # store client for potential future use
 
-            self._metadata = self._metadata or {}
-            if "hnsw:space" not in self._metadata:
-                self._metadata["hnsw:space"] = self._distance_function
+            # Build the collection metadata locally so `self._metadata` stays exactly as the user passed it.
+            # This keeps `to_dict()` deterministic and avoids mutating a user-supplied dict in place.
+            collection_metadata = dict(self._metadata) if self._metadata else {}
+            collection_metadata.setdefault("hnsw:space", self._distance_function)
 
             existing_collection_names = [c.name for c in client.list_collections()]
             if self._collection_name in existing_collection_names:
@@ -149,18 +152,18 @@ class ChromaDocumentStore:
                     embedding_function=self._embedding_func,
                 )
 
-                if self._metadata != self._collection.metadata:
+                if collection_metadata != self._collection.metadata:
                     logger.warning(
                         "Collection already exists. The `distance_function` and `metadata` parameters will be ignored."
                     )
             else:
                 self._collection = client.create_collection(
                     name=self._collection_name,
-                    metadata=self._metadata,
+                    metadata=collection_metadata,
                     embedding_function=self._embedding_func,
                 )
 
-    async def _ensure_initialized_async(self):
+    async def _ensure_initialized_async(self) -> None:
         if not self._async_collection:
             if self._host is None or self._port is None:
                 error_message = (
@@ -186,9 +189,10 @@ class ChromaDocumentStore:
 
             self._async_client = client  # store client for potential future use
 
-            self._metadata = self._metadata or {}
-            if "hnsw:space" not in self._metadata:
-                self._metadata["hnsw:space"] = self._distance_function
+            # Build the collection metadata locally so `self._metadata` stays exactly as the user passed it.
+            # This keeps `to_dict()` deterministic and avoids mutating a user-supplied dict in place.
+            collection_metadata = dict(self._metadata) if self._metadata else {}
+            collection_metadata.setdefault("hnsw:space", self._distance_function)
 
             collection = await client.list_collections()
             existing_collection_names = [c.name for c in collection]
@@ -198,14 +202,14 @@ class ChromaDocumentStore:
                     embedding_function=self._embedding_func,
                 )
 
-                if self._metadata != self._async_collection.metadata:
+                if collection_metadata != self._async_collection.metadata:
                     logger.warning(
                         "Collection already exists. The `distance_function` and `metadata` parameters will be ignored."
                     )
             else:
                 self._async_collection = await client.create_collection(
                     name=self._collection_name,
-                    metadata=self._metadata,
+                    metadata=collection_metadata,
                     embedding_function=self._embedding_func,
                 )
 
@@ -242,16 +246,6 @@ class ChromaDocumentStore:
             "include": ["embeddings", "documents", "metadatas", "distances"],
         }
 
-    @staticmethod
-    def _normalize_metadata_field_name(metadata_field: str) -> str:
-        """
-        Normalizes a metadata field name by removing the "meta." prefix if present.
-
-        :param metadata_field: The metadata field name to normalize.
-        :returns: The normalized field name without "meta." prefix.
-        """
-        return metadata_field[5:] if metadata_field.startswith("meta.") else metadata_field
-
     @staticmethod
     def _infer_type_from_value(value: Any) -> str:
         """
@@ -341,7 +335,7 @@ class ChromaDocumentStore:
         for meta in metadatas:
             if meta and field_name in meta:
                 val = meta.get(field_name)
-                if isinstance(val, (str, int, float)):
+                if isinstance(val, str | int | float):
                     values.append(val)
 
         if not values:
@@ -581,62 +575,123 @@ class ChromaDocumentStore:
     def write_documents(
         self,
         documents: list[Document],
-        policy: DuplicatePolicy = DuplicatePolicy.FAIL,
+        policy: DuplicatePolicy = DuplicatePolicy.NONE,
     ) -> int:
         """
-        Writes (or overwrites) documents into the store.
+        Writes documents into the store.
 
         :param documents:
             A list of documents to write into the document store.
         :param policy:
-            Not supported at the moment.
+            How to handle documents whose `id` already exists in the store:
+            - `NONE` (default): treated as `FAIL`.
+            - `OVERWRITE`: replace the existing document.
+            - `SKIP`: keep the existing document and skip the new one.
+            - `FAIL`: raise `DuplicateDocumentError`.
 
         :raises ValueError:
             When input is not valid.
+        :raises DuplicateDocumentError:
+            When `policy` is `FAIL` (or `NONE`) and any document `id` already exists.
 
         :returns:
-            The number of documents written
+            The number of documents written.
         """
         self._ensure_initialized()
         assert self._collection is not None
 
-        for doc in documents:
-            data = ChromaDocumentStore._convert_document_to_chroma(doc)
-            if data is not None:
-                self._collection.add(**data)
+        if policy == DuplicatePolicy.NONE:
+            policy = DuplicatePolicy.FAIL
+
+        chroma_payloads: list[dict[str, Any]] = [
+            p for p in (ChromaDocumentStore._convert_document_to_chroma(doc) for doc in documents) if p is not None
+        ]
+        if not chroma_payloads:
+            return 0
+
+        if policy in (DuplicatePolicy.FAIL, DuplicatePolicy.SKIP):
+            existing_ids = set(self._collection.get(ids=[p["ids"][0] for p in chroma_payloads])["ids"])
+            payloads_to_write = self._apply_duplicate_policy(chroma_payloads, existing_ids, policy)
+        else:
+            payloads_to_write = chroma_payloads
+
+        for payload in payloads_to_write:
+            if policy == DuplicatePolicy.OVERWRITE:
+                self._collection.upsert(**payload)
+            else:
+                self._collection.add(**payload)
 
-        return len(documents)
+        return len(payloads_to_write)
 
     async def write_documents_async(
         self,
         documents: list[Document],
-        policy: DuplicatePolicy = DuplicatePolicy.FAIL,
+        policy: DuplicatePolicy = DuplicatePolicy.NONE,
     ) -> int:
         """
-        Asynchronously writes (or overwrites) documents into the store.
+        Asynchronously writes documents into the store.
 
         Asynchronous methods are only supported for HTTP connections.
 
         :param documents:
             A list of documents to write into the document store.
         :param policy:
-            Not supported at the moment.
+            How to handle documents whose `id` already exists in the store:
+            - `NONE` (default): treated as `FAIL`.
+            - `OVERWRITE`: replace the existing document.
+            - `SKIP`: keep the existing document and skip the new one.
+            - `FAIL`: raise `DuplicateDocumentError`.
 
         :raises ValueError:
             When input is not valid.
+        :raises DuplicateDocumentError:
+            When `policy` is `FAIL` (or `NONE`) and any document `id` already exists.
 
         :returns:
-            The number of documents written
+            The number of documents written.
         """
         await self._ensure_initialized_async()
         assert self._async_collection is not None
 
-        for doc in documents:
-            data = ChromaDocumentStore._convert_document_to_chroma(doc)
-            if data is not None:
-                await self._async_collection.add(**data)
+        if policy == DuplicatePolicy.NONE:
+            policy = DuplicatePolicy.FAIL
+
+        chroma_payloads: list[dict[str, Any]] = [
+            p for p in (ChromaDocumentStore._convert_document_to_chroma(doc) for doc in documents) if p is not None
+        ]
+        if not chroma_payloads:
+            return 0
+
+        if policy in (DuplicatePolicy.FAIL, DuplicatePolicy.SKIP):
+            existing = await self._async_collection.get(ids=[p["ids"][0] for p in chroma_payloads])
+            existing_ids = set(existing["ids"])
+            payloads_to_write = self._apply_duplicate_policy(chroma_payloads, existing_ids, policy)
+        else:
+            payloads_to_write = chroma_payloads
 
-        return len(documents)
+        for payload in payloads_to_write:
+            if policy == DuplicatePolicy.OVERWRITE:
+                await self._async_collection.upsert(**payload)
+            else:
+                await self._async_collection.add(**payload)
+
+        return len(payloads_to_write)
+
+    @staticmethod
+    def _apply_duplicate_policy(
+        payloads: list[dict[str, Any]],
+        existing_ids: set[str],
+        policy: DuplicatePolicy,
+    ) -> list[dict[str, Any]]:
+        if policy == DuplicatePolicy.FAIL:
+            duplicates = [p["ids"][0] for p in payloads if p["ids"][0] in existing_ids]
+            if duplicates:
+                msg = f"Documents with ids {duplicates} already exist in the document store."
+                raise DuplicateDocumentError(msg)
+            return payloads
+        if policy == DuplicatePolicy.SKIP:
+            return [p for p in payloads if p["ids"][0] not in existing_ids]
+        return payloads
 
     def delete_documents(self, document_ids: list[str]) -> None:
         """
@@ -1008,8 +1063,7 @@ class ChromaDocumentStore:
         filters: dict[str, Any] | None = None,
     ) -> list[list[Document]]:
         """
-        Asynchronously perform vector search on the stored document, pass the embeddings of the queries instead of
-        their text.
+        Asynchronously perform vector search using query embeddings instead of text.
 
         Asynchronous methods are only supported for HTTP connections.
 
@@ -1074,8 +1128,7 @@ class ChromaDocumentStore:
 
     def count_unique_metadata_by_filter(self, filters: dict[str, Any], metadata_fields: list[str]) -> dict[str, int]:
         """
-        Returns the number of unique values for each specified metadata field
-        of the documents that match the provided filters.
+        Return unique value counts for metadata fields of documents matching the provided filters.
 
         :param filters: The filters to apply to count documents.
             For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
@@ -1087,7 +1140,7 @@ class ChromaDocumentStore:
         self._ensure_initialized()
         assert self._collection is not None
 
-        normalized_fields = [self._normalize_metadata_field_name(field) for field in metadata_fields]
+        normalized_fields = [_normalize_metadata_field_name(field) for field in metadata_fields]
 
         kwargs = ChromaDocumentStore._prepare_get_kwargs(filters)
         kwargs["include"] = ["metadatas"]
@@ -1099,8 +1152,7 @@ class ChromaDocumentStore:
         self, filters: dict[str, Any], metadata_fields: list[str]
     ) -> dict[str, int]:
         """
-        Asynchronously returns the number of unique values for each specified metadata field
-        of the documents that match the provided filters.
+        Asynchronously return unique value counts for metadata fields of documents matching the provided filters.
 
         Asynchronous methods are only supported for HTTP connections.
 
@@ -1114,7 +1166,7 @@ class ChromaDocumentStore:
         await self._ensure_initialized_async()
         assert self._async_collection is not None
 
-        normalized_fields = [self._normalize_metadata_field_name(field) for field in metadata_fields]
+        normalized_fields = [_normalize_metadata_field_name(field) for field in metadata_fields]
 
         kwargs = ChromaDocumentStore._prepare_get_kwargs(filters)
         kwargs["include"] = ["metadatas"]
@@ -1205,7 +1257,7 @@ class ChromaDocumentStore:
         self._ensure_initialized()
         assert self._collection is not None
 
-        field_name = self._normalize_metadata_field_name(metadata_field)
+        field_name = _normalize_metadata_field_name(metadata_field)
 
         result = self._collection.get(include=["metadatas"])
         return self._compute_field_min_max(result.get("metadatas", []), field_name)
@@ -1229,7 +1281,7 @@ class ChromaDocumentStore:
         await self._ensure_initialized_async()
         assert self._async_collection is not None
 
-        field_name = self._normalize_metadata_field_name(metadata_field)
+        field_name = _normalize_metadata_field_name(metadata_field)
 
         result = await self._async_collection.get(include=["metadatas"])
         return self._compute_field_min_max(result.get("metadatas", []), field_name)
@@ -1242,8 +1294,7 @@ class ChromaDocumentStore:
         size: int = 10,
     ) -> tuple[list[str], int]:
         """
-        Returns unique values for a metadata field, optionally filtered by
-        a search term in the content field, with pagination support.
+        Return unique metadata field values, optionally filtered by a content search term, with pagination.
 
         :param metadata_field: The metadata field to get unique values for.
             Can include or omit the "meta." prefix.
@@ -1256,7 +1307,7 @@ class ChromaDocumentStore:
         self._ensure_initialized()
         assert self._collection is not None
 
-        field_name = self._normalize_metadata_field_name(metadata_field)
+        field_name = _normalize_metadata_field_name(metadata_field)
 
         kwargs: dict[str, Any] = {"include": ["metadatas"]}
         if search_term:
@@ -1273,8 +1324,7 @@ class ChromaDocumentStore:
         size: int = 10,
     ) -> tuple[list[str], int]:
         """
-        Asynchronously returns unique values for a metadata field, optionally filtered by
-        a search term in the content field, with pagination support.
+        Asynchronously return unique metadata field values, optionally filtered by content, with pagination.
 
         Asynchronous methods are only supported for HTTP connections.
 
@@ -1289,7 +1339,7 @@ class ChromaDocumentStore:
         await self._ensure_initialized_async()
         assert self._async_collection is not None
 
-        field_name = self._normalize_metadata_field_name(metadata_field)
+        field_name = _normalize_metadata_field_name(metadata_field)
 
         kwargs: dict[str, Any] = {"include": ["metadatas"]}
         if search_term:
@@ -1325,6 +1375,7 @@ class ChromaDocumentStore:
             host=self._host,
             port=self._port,
             distance_function=self._distance_function,
+            metadata=self._metadata,
             client_settings=self._client_settings,
             **self._embedding_function_params,
         )

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/src/haystack_integrations/document_stores/chroma/filters.py

@@ -44,8 +44,10 @@ class ChromaFilter:
 
 def _convert_filters(filters: dict[str, Any]) -> ChromaFilter:
     """
-    Converts Haystack filters into a format compatible with Chroma, separating them into ids, metadata filters,
-    and content filters to be passed to chroma as ids, where, and where_document clauses respectively.
+    Converts Haystack filters into a format compatible with Chroma.
+
+    Separates filters into ids, metadata filters, and content filters to be passed to chroma as ids, where,
+    and where_document clauses respectively.
     """
 
     ids = []
@@ -103,9 +105,7 @@ def _convert_filter_clause(filters: dict[str, Any]) -> dict[str, Any]:
 
 def _create_where_document_filter(field: str, value: dict[Any, Any]) -> dict[str, Any]:
     """
-    Method to check if given haystack filter is a document filter
-    and converts it to Chroma-compatible where_document filter.
-
+    Check if a given Haystack filter is a document filter and convert it to a Chroma-compatible where_document filter.
     """
     where_document: dict[str, list[Any]] = defaultdict(list)
 

{chroma_haystack-4.2.0 → chroma_haystack-4.3.1}/src/haystack_integrations/document_stores/chroma/utils.py

@@ -37,7 +37,8 @@ FUNCTION_REGISTRY = {
 
 
 def get_embedding_function(function_name: str, **kwargs: Any) -> EmbeddingFunction:
-    """Load an embedding function by name.
+    """
+    Load an embedding function by name.
 
     :param function_name: the name of the embedding function.
     :param kwargs: additional arguments to pass to the embedding function.