fastembed-haystack 2.0.0__tar.gz → 2.2.0__tar.gz

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [integrations/fastembed-v2.1.0] - 2026-02-13
+
+### 📚 Documentation
+
+- *(fastembed)* Remove explicit warm_up from examples (#2830)
+
+### 🌀 Miscellaneous
+
+- Automatically call warm_up() if model is not loaded in FastembedRanker
+- Remove explicit call to warm_up() in ranker_example.py
+- Add unit tests
+- Fix typing issue
+- Fix tying
+- Update docstrings
+- Remove explicit warm_up calls from integration tests
+
+## [integrations/fastembed-v2.0.0] - 2026-01-12
+
+### 🧹 Chores
+
+- [**breaking**] Fastembed - drop Python 3.9 and use X|Y typing (#2698)
+
+
 ## [integrations/fastembed-v1.6.0] - 2026-01-09
 
 ### 🚀 Features

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastembed-haystack
-Version: 2.0.0
+Version: 2.2.0
 Summary: Haystack 2.x component to embed strings and Documents using fastembed embedding model
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/fastembed/README.md
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.10
 Requires-Dist: fastembed>=0.4.2
-Requires-Dist: haystack-ai>=2.22.0
+Requires-Dist: haystack-ai>=2.24.1
 Description-Content-Type: text/markdown
 
 # fastembed-haystack

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/examples/example.py

@@ -14,7 +14,6 @@ documents = [
 ]
 
 document_embedder = FastembedDocumentEmbedder()
-document_embedder.warm_up()
 documents_with_embeddings = document_embedder.run(documents)["documents"]
 document_store.write_documents(documents_with_embeddings)
 

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/examples/ranker_example.py

@@ -11,7 +11,6 @@ documents = [
 ]
 
 ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2")
-ranker.warm_up()
 reranked_documents = ranker.run(query=query, documents=documents)["documents"]
 
 

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/examples/sparse_example.py

@@ -25,7 +25,6 @@ document_list = [
 ]
 
 document_embedder = FastembedSparseDocumentEmbedder()
-document_embedder.warm_up()
 documents_with_embeddings = document_embedder.run(document_list)["documents"]
 
 for doc in documents_with_embeddings:

fastembed_haystack-2.2.0/pydoc/config_docusaurus.yml

@@ -0,0 +1,18 @@
+loaders:
+  - modules:
+      - haystack_integrations.components.embedders.fastembed.fastembed_document_embedder
+      - haystack_integrations.components.embedders.fastembed.fastembed_text_embedder
+      - haystack_integrations.components.embedders.fastembed.fastembed_sparse_document_embedder
+      - haystack_integrations.components.embedders.fastembed.fastembed_sparse_text_embedder
+      - haystack_integrations.components.rankers.fastembed.ranker
+      - haystack_integrations.components.rankers.fastembed.late_interaction_ranker
+    search_path: [../src]
+processors:
+  - type: filter
+    documented_only: true
+    skip_empty_modules: true
+renderer:
+  description: FastEmbed integration for Haystack
+  id: fastembed-embedders
+  filename: fastembed.md
+  title: FastEmbed

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = ["haystack-ai>=2.22.0", "fastembed>=0.4.2"]
+dependencies = ["haystack-ai>=2.24.1", "fastembed>=0.4.2"]
 
 [project.urls]
 Source = "https://github.com/deepset-ai/haystack-core-integrations"
@@ -44,7 +44,7 @@ git_describe_command = 'git describe --tags --match="integrations/fastembed-v[0-
 installer = "uv"
 dependencies = ["haystack-pydoc-tools", "ruff"]
 [tool.hatch.envs.default.scripts]
-docs = ["pydoc-markdown pydoc/config_docusaurus.yml"]
+docs = ["haystack-pydoc pydoc/config_docusaurus.yml"]
 fmt = "ruff check --fix {args}; ruff format {args}"
 fmt-check = "ruff check {args} && ruff format --check {args}"
 
@@ -63,7 +63,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.embedders.fastembed \
 -p haystack_integrations.components.rankers.fastembed {args}"""
 
@@ -79,9 +80,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",
@@ -115,6 +124,8 @@ ignore = [
   "S105",
   "S106",
   "S107",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
   # Ignore complexity
   "C901",
   "PLR0911",
@@ -131,13 +142,14 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252"]
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
 # examples can contain "print" commands
 "examples/**/*" = ["T201", "E501"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]
 branch = true
+relative_files = true
 parallel = false
 
 [tool.coverage.report]

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/embedders/fastembed/embedding_backend/fastembed_backend.py

@@ -44,7 +44,7 @@ class _FastembedEmbeddingBackend:
         cache_dir: str | None = None,
         threads: int | None = None,
         local_files_only: bool = False,
-    ):
+    ) -> None:
         self.model = TextEmbedding(
             model_name=model_name, cache_dir=cache_dir, threads=threads, local_files_only=local_files_only
         )
@@ -103,7 +103,7 @@ class _FastembedSparseEmbeddingBackend:
         threads: int | None = None,
         local_files_only: bool = False,
         model_kwargs: dict[str, Any] | None = None,
-    ):
+    ) -> None:
         model_kwargs = model_kwargs or {}
 
         self.model = SparseTextEmbedding(

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_document_embedder.py

@@ -14,6 +14,7 @@ from .embedding_backend.fastembed_backend import _FastembedEmbeddingBackend, _Fa
 class FastembedDocumentEmbedder:
     """
     FastembedDocumentEmbedder computes Document embeddings using Fastembed embedding models.
+
     The embedding of each Document is stored in the `embedding` field of the Document.
 
     Usage example:
@@ -29,8 +30,6 @@ class FastembedDocumentEmbedder:
         batch_size=256,
     )
 
-    doc_embedder.warm_up()
-
     # Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
     document_list = [
         Document(
@@ -112,6 +111,7 @@ class FastembedDocumentEmbedder:
     def to_dict(self) -> dict[str, Any]:
         """
         Serializes the component to a dictionary.
+
         :returns:
             Dictionary with serialized data.
         """

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_sparse_document_embedder.py

@@ -28,8 +28,6 @@ class FastembedSparseDocumentEmbedder:
         batch_size=32,
     )
 
-    sparse_doc_embedder.warm_up()
-
     # Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa)
     document_list = [
         Document(
@@ -108,6 +106,7 @@ class FastembedSparseDocumentEmbedder:
     def to_dict(self) -> dict[str, Any]:
         """
         Serializes the component to a dictionary.
+
         :returns:
             Dictionary with serialized data.
         """

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_sparse_text_embedder.py

@@ -28,7 +28,6 @@ class FastembedSparseTextEmbedder:
     sparse_text_embedder = FastembedSparseTextEmbedder(
         model="prithivida/Splade_PP_en_v1"
     )
-    sparse_text_embedder.warm_up()
 
     sparse_embedding = sparse_text_embedder.run(text)["sparse_embedding"]
     ```

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_text_embedder.py

@@ -24,7 +24,6 @@ class FastembedTextEmbedder:
     text_embedder = FastembedTextEmbedder(
         model="BAAI/bge-small-en-v1.5"
     )
-    text_embedder.warm_up()
 
     embedding = text_embedder.run(text)["embedding"]
     ```

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/rankers/fastembed/__init__.py

@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .late_interaction_ranker import FastembedLateInteractionRanker
 from .ranker import FastembedRanker
 
-__all__ = ["FastembedRanker"]
+__all__ = ["FastembedLateInteractionRanker", "FastembedRanker"]

fastembed_haystack-2.2.0/src/haystack_integrations/components/rankers/fastembed/late_interaction_ranker.py

@@ -0,0 +1,230 @@
+# SPDX-FileCopyrightText: 2024-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from dataclasses import replace
+from typing import Any
+
+import numpy as np
+from haystack import Document, component, default_from_dict, default_to_dict, logging
+from haystack.utils.misc import _deduplicate_documents
+
+from fastembed import LateInteractionTextEmbedding
+
+logger = logging.getLogger(__name__)
+
+
+@component
+class FastembedLateInteractionRanker:
+    """
+    Ranks Documents based on their similarity to the query using ColBERT models via Fastembed.
+
+    Uses late interaction (MaxSim) scoring to compute token-level similarity between
+    query and document embeddings, then ranks documents accordingly.
+
+    See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
+
+    Usage example:
+    ```python
+    from haystack import Document
+    from haystack_integrations.components.rankers.fastembed import FastembedLateInteractionRanker
+
+    ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=2)
+
+    docs = [Document(content="Paris"), Document(content="Berlin")]
+    query = "What is the capital of germany?"
+    output = ranker.run(query=query, documents=docs)
+    print(output["documents"][0].content)
+
+    # Berlin
+    ```
+    """
+
+    def __init__(
+        self,
+        model_name: str = "colbert-ir/colbertv2.0",
+        top_k: int = 10,
+        cache_dir: str | None = None,
+        threads: int | None = None,
+        batch_size: int = 64,
+        parallel: int | None = None,
+        local_files_only: bool = False,
+        meta_fields_to_embed: list[str] | None = None,
+        meta_data_separator: str = "\n",
+        score_threshold: float | None = None,
+    ) -> None:
+        """
+        Creates an instance of the 'FastembedLateInteractionRanker'.
+
+        :param model_name: Fastembed ColBERT model name. Check the list of supported models in the
+            [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+        :param top_k: The maximum number of documents to return.
+        :param cache_dir: The path to the cache directory.
+                Can be set using the `FASTEMBED_CACHE_PATH` env variable.
+                Defaults to `fastembed_cache` in the system's temp directory.
+        :param threads: The number of threads single onnxruntime session can use. Defaults to None.
+        :param batch_size: Number of strings to encode at once.
+        :param parallel:
+                If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets.
+                If 0, use all available cores.
+                If None, don't use data-parallel processing, use default onnxruntime threading instead.
+        :param local_files_only: If `True`, only use the model files in the `cache_dir`.
+        :param meta_fields_to_embed: List of meta fields that should be concatenated
+            with the document content for reranking.
+        :param meta_data_separator: Separator used to concatenate the meta fields
+            to the Document content.
+        :param score_threshold: If provided, only documents with a score above the threshold are returned.
+            Note that ColBERT scores are unnormalized sums and typically range from 3 to 25.
+        """
+        if top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
+
+        self.model_name = model_name
+        self.top_k = top_k
+        self.cache_dir = cache_dir
+        self.threads = threads
+        self.batch_size = batch_size
+        self.parallel = parallel
+        self.local_files_only = local_files_only
+        self.meta_fields_to_embed = meta_fields_to_embed or []
+        self.meta_data_separator = meta_data_separator
+        self.score_threshold = score_threshold
+        self._model: LateInteractionTextEmbedding | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            model_name=self.model_name,
+            top_k=self.top_k,
+            cache_dir=self.cache_dir,
+            threads=self.threads,
+            batch_size=self.batch_size,
+            parallel=self.parallel,
+            local_files_only=self.local_files_only,
+            meta_fields_to_embed=self.meta_fields_to_embed,
+            meta_data_separator=self.meta_data_separator,
+            score_threshold=self.score_threshold,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "FastembedLateInteractionRanker":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            The dictionary to deserialize from.
+        :returns:
+            The deserialized component.
+        """
+        return default_from_dict(cls, data)
+
+    def warm_up(self) -> None:
+        """
+        Initializes the component.
+        """
+        if self._model is None:
+            self._model = LateInteractionTextEmbedding(
+                model_name=self.model_name,
+                cache_dir=self.cache_dir,
+                threads=self.threads,
+                local_files_only=self.local_files_only,
+            )
+
+    def _prepare_fastembed_input_docs(self, documents: list[Document]) -> list[str]:
+        """
+        Prepare the input by concatenating the document text with the metadata fields specified.
+
+        :param documents: The list of Document objects.
+
+        :return: A list of strings to be given as input to Fastembed model.
+        """
+        concatenated_input_list = []
+        for doc in documents:
+            meta_values_to_embed = [
+                str(doc.meta[key]) for key in self.meta_fields_to_embed if key in doc.meta and doc.meta.get(key)
+            ]
+            concatenated_input = self.meta_data_separator.join([*meta_values_to_embed, doc.content or ""])
+            concatenated_input_list.append(concatenated_input)
+
+        return concatenated_input_list
+
+    def _get_telemetry_data(self) -> dict[str, Any]:
+        """
+        Data that is sent to Posthog for usage analytics.
+        """
+        return {"model": self.model_name}
+
+    @component.output_types(documents=list[Document])
+    def run(self, query: str, documents: list[Document], top_k: int | None = None) -> dict[str, list[Document]]:
+        """
+        Returns a list of documents ranked by their similarity to the given query using ColBERT MaxSim scoring.
+
+        :param query:
+            The input query to compare the documents to.
+        :param documents:
+            A list of documents to be ranked.
+        :param top_k:
+            The maximum number of documents to return.
+
+        :returns:
+            A dictionary with the following keys:
+            - `documents`: A list of documents closest to the query, sorted from most similar to least similar.
+
+        :raises ValueError: If `top_k` is not > 0.
+        """
+        if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
+            msg = "FastembedLateInteractionRanker expects a list of Documents as input. "
+            raise TypeError(msg)
+        if query == "":
+            msg = "No query provided"
+            raise ValueError(msg)
+
+        if not documents:
+            return {"documents": []}
+
+        top_k = top_k or self.top_k
+        if top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
+
+        if self._model is None:
+            self.warm_up()
+
+        documents = _deduplicate_documents(documents)
+        fastembed_input_docs = self._prepare_fastembed_input_docs(documents)
+
+        assert self._model is not None  # noqa: S101
+        query_embedding = next(iter(self._model.query_embed(query)))
+        document_embeddings = list(
+            self._model.embed(
+                fastembed_input_docs,
+                batch_size=self.batch_size,
+                parallel=self.parallel,
+            )
+        )
+
+        query_emb = np.array(query_embedding)
+        scores = []
+        for raw_doc_emb in document_embeddings:
+            doc_emb = np.array(raw_doc_emb)
+            sim = np.matmul(query_emb, doc_emb.T)
+            max_sim = np.max(sim, axis=1)
+            scores.append(float(np.sum(max_sim)))
+
+        doc_scores = list(zip(documents, scores, strict=True))
+        sorted_doc_scores = sorted(doc_scores, key=lambda x: x[1], reverse=True)
+
+        top_k_documents = [replace(doc, score=score) for doc, score in sorted_doc_scores[:top_k]]
+
+        score_threshold = self.score_threshold
+        if score_threshold is not None:
+            top_k_documents = [doc for doc in top_k_documents if doc.score is not None and doc.score >= score_threshold]
+
+        return {"documents": top_k_documents}

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/src/haystack_integrations/components/rankers/fastembed/ranker.py

@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from dataclasses import replace
 from typing import Any
 
 from haystack import Document, component, default_from_dict, default_to_dict, logging
@@ -14,8 +15,9 @@ logger = logging.getLogger(__name__)
 @component
 class FastembedRanker:
     """
-    Ranks Documents based on their similarity to the query using
-    [Fastembed models](https://qdrant.github.io/fastembed/examples/Supported_Models/).
+    Ranks Documents based on their similarity to the query using Fastembed models.
+
+    See https://qdrant.github.io/fastembed/examples/Supported_Models/ for supported models.
 
     Documents are indexed from most to least semantically relevant to the query.
 
@@ -46,7 +48,7 @@ class FastembedRanker:
         local_files_only: bool = False,
         meta_fields_to_embed: list[str] | None = None,
         meta_data_separator: str = "\n",
-    ):
+    ) -> None:
         """
         Creates an instance of the 'FastembedRanker'.
 
@@ -114,7 +116,7 @@ class FastembedRanker:
         """
         return default_from_dict(cls, data)
 
-    def warm_up(self):
+    def warm_up(self) -> None:
         """
         Initializes the component.
         """
@@ -129,6 +131,7 @@ class FastembedRanker:
     def _prepare_fastembed_input_docs(self, documents: list[Document]) -> list[str]:
         """
         Prepare the input by concatenating the document text with the metadata fields specified.
+
         :param documents: The list of Document objects.
 
         :return: A list of strings to be given as input to Fastembed model.
@@ -177,13 +180,12 @@ class FastembedRanker:
             raise ValueError(msg)
 
         if self._model is None:
-            msg = "The ranker model has not been loaded. Please call warm_up() before running."
-            raise RuntimeError(msg)
+            self.warm_up()
 
         fastembed_input_docs = self._prepare_fastembed_input_docs(documents)
 
         scores = list(
-            self._model.rerank(
+            self._model.rerank(  # type: ignore[union-attr]
                 query=query,
                 documents=fastembed_input_docs,
                 batch_size=self.batch_size,
@@ -197,10 +199,6 @@ class FastembedRanker:
         # Sort the list of tuples by the score in descending order
         sorted_doc_scores = sorted(doc_scores, key=lambda x: x[1], reverse=True)
 
-        # Get the top_k documents
-        top_k_documents = []
-        for doc, score in sorted_doc_scores[:top_k]:
-            doc.score = score
-            top_k_documents.append(doc)
+        top_k_documents = [replace(doc, score=score) for doc, score in sorted_doc_scores[:top_k]]
 
         return {"documents": top_k_documents}

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/tests/test_fastembed_document_embedder.py

@@ -281,12 +281,25 @@ class TestFastembedDocumentEmbedder:
             parallel=None,
         )
 
+    def test_run_calls_warm_up(self):
+        embedder = FastembedDocumentEmbedder()
+        assert embedder.embedding_backend is None
+
+        mock_backend = MagicMock()
+        mock_backend.embed.return_value = [[0.1, 0.2, 0.3]]
+
+        with patch.object(
+            embedder, "warm_up", side_effect=lambda: setattr(embedder, "embedding_backend", mock_backend)
+        ) as mock_warm_up:
+            embedder.run(documents=[Document(content="test document")])
+
+        mock_warm_up.assert_called_once()
+
     @pytest.mark.integration
     def test_run(self):
         embedder = FastembedDocumentEmbedder(
             model="BAAI/bge-small-en-v1.5",
         )
-        embedder.warm_up()
 
         doc = Document(content="Parton energy loss in QCD matter")
 

fastembed_haystack-2.2.0/tests/test_fastembed_late_interaction_ranker.py

@@ -0,0 +1,350 @@
+# SPDX-FileCopyrightText: 2024-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+from haystack import Document, default_from_dict
+
+from haystack_integrations.components.rankers.fastembed.late_interaction_ranker import (
+    FastembedLateInteractionRanker,
+)
+
+
+class TestFastembedLateInteractionRanker:
+    def test_init_default(self):
+        """
+        Test default initialization parameters for FastembedLateInteractionRanker.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0")
+        assert ranker.model_name == "colbert-ir/colbertv2.0"
+        assert ranker.top_k == 10
+        assert ranker.cache_dir is None
+        assert ranker.threads is None
+        assert ranker.batch_size == 64
+        assert ranker.parallel is None
+        assert not ranker.local_files_only
+        assert ranker.meta_fields_to_embed == []
+        assert ranker.meta_data_separator == "\n"
+
+    def test_init_with_parameters(self):
+        """
+        Test custom initialization parameters for FastembedLateInteractionRanker.
+        """
+        ranker = FastembedLateInteractionRanker(
+            model_name="colbert-ir/colbertv2.0",
+            top_k=64,
+            cache_dir="fake_dir",
+            threads=2,
+            batch_size=50,
+            parallel=1,
+            local_files_only=True,
+            meta_fields_to_embed=["test_field"],
+            meta_data_separator=" | ",
+        )
+        assert ranker.model_name == "colbert-ir/colbertv2.0"
+        assert ranker.top_k == 64
+        assert ranker.cache_dir == "fake_dir"
+        assert ranker.threads == 2
+        assert ranker.batch_size == 50
+        assert ranker.parallel == 1
+        assert ranker.local_files_only
+        assert ranker.meta_fields_to_embed == ["test_field"]
+        assert ranker.meta_data_separator == " | "
+
+    def test_init_with_incorrect_input(self):
+        """
+        Test for checking incorrect input format on init.
+        """
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got 0",
+        ):
+            FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=0)
+
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got -3",
+        ):
+            FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=-3)
+
+    def test_to_dict(self):
+        """
+        Test serialization of FastembedLateInteractionRanker to a dictionary, using default initialization parameters.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0")
+        ranker_dict = ranker.to_dict()
+        assert ranker_dict == {
+            "type": "haystack_integrations.components.rankers.fastembed"
+            ".late_interaction_ranker.FastembedLateInteractionRanker",
+            "init_parameters": {
+                "model_name": "colbert-ir/colbertv2.0",
+                "top_k": 10,
+                "cache_dir": None,
+                "threads": None,
+                "batch_size": 64,
+                "parallel": None,
+                "local_files_only": False,
+                "meta_fields_to_embed": [],
+                "meta_data_separator": "\n",
+                "score_threshold": None,
+            },
+        }
+
+    def test_to_dict_with_custom_init_parameters(self):
+        """
+        Test serialization of FastembedLateInteractionRanker to a dictionary, using custom initialization parameters.
+        """
+        ranker = FastembedLateInteractionRanker(
+            model_name="colbert-ir/colbertv2.0",
+            cache_dir="fake_dir",
+            threads=2,
+            top_k=5,
+            batch_size=50,
+            parallel=1,
+            local_files_only=True,
+            meta_fields_to_embed=["test_field"],
+            meta_data_separator=" | ",
+        )
+        ranker_dict = ranker.to_dict()
+        assert ranker_dict == {
+            "type": "haystack_integrations.components.rankers.fastembed"
+            ".late_interaction_ranker.FastembedLateInteractionRanker",
+            "init_parameters": {
+                "model_name": "colbert-ir/colbertv2.0",
+                "cache_dir": "fake_dir",
+                "threads": 2,
+                "top_k": 5,
+                "batch_size": 50,
+                "parallel": 1,
+                "local_files_only": True,
+                "meta_fields_to_embed": ["test_field"],
+                "meta_data_separator": " | ",
+                "score_threshold": None,
+            },
+        }
+
+    def test_from_dict(self):
+        """
+        Test deserialization of FastembedLateInteractionRanker from a dictionary, using default init parameters.
+        """
+        ranker_dict = {
+            "type": "haystack_integrations.components.rankers.fastembed"
+            ".late_interaction_ranker.FastembedLateInteractionRanker",
+            "init_parameters": {
+                "model_name": "colbert-ir/colbertv2.0",
+                "cache_dir": None,
+                "threads": None,
+                "top_k": 5,
+                "batch_size": 50,
+                "parallel": None,
+                "local_files_only": False,
+                "meta_fields_to_embed": [],
+                "meta_data_separator": "\n",
+            },
+        }
+        ranker = default_from_dict(FastembedLateInteractionRanker, ranker_dict)
+        assert ranker.model_name == "colbert-ir/colbertv2.0"
+        assert ranker.cache_dir is None
+        assert ranker.threads is None
+        assert ranker.top_k == 5
+        assert ranker.batch_size == 50
+        assert ranker.parallel is None
+        assert not ranker.local_files_only
+        assert ranker.meta_fields_to_embed == []
+        assert ranker.meta_data_separator == "\n"
+
+    def test_from_dict_with_custom_init_parameters(self):
+        """
+        Test deserialization of FastembedLateInteractionRanker from a dictionary, using custom init parameters.
+        """
+        ranker_dict = {
+            "type": "haystack_integrations.components.rankers.fastembed"
+            ".late_interaction_ranker.FastembedLateInteractionRanker",
+            "init_parameters": {
+                "model_name": "colbert-ir/colbertv2.0",
+                "cache_dir": "fake_dir",
+                "threads": 2,
+                "top_k": 5,
+                "batch_size": 50,
+                "parallel": 1,
+                "local_files_only": True,
+                "meta_fields_to_embed": ["test_field"],
+                "meta_data_separator": " | ",
+            },
+        }
+        ranker = default_from_dict(FastembedLateInteractionRanker, ranker_dict)
+        assert ranker.model_name == "colbert-ir/colbertv2.0"
+        assert ranker.cache_dir == "fake_dir"
+        assert ranker.threads == 2
+        assert ranker.top_k == 5
+        assert ranker.batch_size == 50
+        assert ranker.parallel == 1
+        assert ranker.local_files_only
+        assert ranker.meta_fields_to_embed == ["test_field"]
+        assert ranker.meta_data_separator == " | "
+
+    def test_run_incorrect_input_format(self):
+        """
+        Test for checking incorrect input format.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0")
+        ranker._model = "mock_model"
+
+        query = "query"
+        string_input = "text"
+        list_integers_input = [1, 2, 3]
+        list_document = [Document("Document 1")]
+
+        with pytest.raises(
+            TypeError,
+            match=r"FastembedLateInteractionRanker expects a list of Documents as input\.",
+        ):
+            ranker.run(query=query, documents=string_input)
+
+        with pytest.raises(
+            TypeError,
+            match=r"FastembedLateInteractionRanker expects a list of Documents as input\.",
+        ):
+            ranker.run(query=query, documents=list_integers_input)
+
+        with pytest.raises(
+            ValueError,
+            match="No query provided",
+        ):
+            ranker.run(query="", documents=list_document)
+
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got -3",
+        ):
+            ranker.run(query=query, documents=list_document, top_k=-3)
+
+    def test_run_empty_document_list(self):
+        """
+        Test for no error when sending no documents.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0")
+        ranker._model = "mock_model"
+
+        query = "query"
+        list_document = []
+
+        result = ranker.run(query=query, documents=list_document)
+        assert len(result["documents"]) == 0
+
+    def test_embed_metadata(self):
+        """
+        Tests the embedding of metadata fields in document content for ranking.
+        """
+        ranker = FastembedLateInteractionRanker(
+            model_name="colbert-ir/colbertv2.0",
+            meta_fields_to_embed=["meta_field"],
+        )
+        mock_model = MagicMock()
+        # query_embed returns one embedding with shape (num_query_tokens, embedding_dim)
+        mock_model.query_embed.return_value = iter([np.random.rand(32, 128)])
+        # embed returns one embedding per document with shape (num_doc_tokens, embedding_dim)
+        mock_model.embed.return_value = iter([np.random.rand(64, 128) for _ in range(5)])
+        ranker._model = mock_model
+
+        documents = [Document(content=f"document-number {i}", meta={"meta_field": f"meta_value {i}"}) for i in range(5)]
+        query = "test"
+        ranker.run(query=query, documents=documents)
+
+        mock_model.embed.assert_called_once_with(
+            [
+                "meta_value 0\ndocument-number 0",
+                "meta_value 1\ndocument-number 1",
+                "meta_value 2\ndocument-number 2",
+                "meta_value 3\ndocument-number 3",
+                "meta_value 4\ndocument-number 4",
+            ],
+            batch_size=64,
+            parallel=None,
+        )
+
+    def test_warm_up_called_once(self):
+        """
+        Test that calling warm_up() twice only initializes the model once.
+        """
+        ranker = FastembedLateInteractionRanker()
+        with patch(
+            "haystack_integrations.components.rankers.fastembed.late_interaction_ranker.LateInteractionTextEmbedding"
+        ) as mock_cls:
+            ranker.warm_up()
+            ranker.warm_up()
+            mock_cls.assert_called_once()
+
+    def test_run_calls_warm_up(self):
+        """
+        Unit test to check that warm_up is called when run is called for the first time.
+        """
+        ranker = FastembedLateInteractionRanker()
+
+        mock_model = MagicMock()
+        mock_model.query_embed.return_value = iter([np.random.rand(32, 128)])
+        mock_model.embed.return_value = iter([np.random.rand(64, 128)])
+
+        with patch.object(ranker, "warm_up", side_effect=lambda: setattr(ranker, "_model", mock_model)) as mock_warm_up:
+            ranker.run(query="test query", documents=[Document(content="test document")])
+
+        mock_warm_up.assert_called_once()
+
+    def test_run_with_mock(self):
+        """
+        Test that MaxSim scoring produces correct ranking order.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=2)
+
+        mock_model = MagicMock()
+        # Query embedding: 2 tokens, 4 dims
+        mock_model.query_embed.return_value = iter([np.array([[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0]])])
+        # Doc embeddings: 2 docs, each with 3 tokens, 4 dims
+        # Doc 0: low similarity to query
+        # Doc 1: high similarity to query
+        mock_model.embed.return_value = iter(
+            [
+                np.array([[0.1, 0.1, 0.9, 0.0], [0.1, 0.0, 0.0, 0.9], [0.0, 0.1, 0.9, 0.0]]),
+                np.array([[0.9, 0.0, 0.0, 0.1], [0.0, 0.9, 0.1, 0.0], [0.1, 0.1, 0.8, 0.0]]),
+            ]
+        )
+        ranker._model = mock_model
+
+        documents = [
+            Document(content="low similarity doc"),
+            Document(content="high similarity doc"),
+        ]
+
+        result = ranker.run(query="test", documents=documents)
+
+        assert len(result["documents"]) == 2
+        assert result["documents"][0].content == "high similarity doc"
+        assert result["documents"][0].score > result["documents"][1].score
+
+    @pytest.mark.integration
+    def test_run(self):
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=2)
+
+        query = "Who is maintaining Qdrant?"
+        documents = [
+            Document(
+                content="This is built to be faster and lighter than other embedding "
+                "libraries e.g. Transformers, Sentence-Transformers, etc."
+            ),
+            Document(content="This is some random input"),
+            Document(content="fastembed is supported by and maintained by Qdrant."),
+        ]
+
+        result = ranker.run(query=query, documents=documents)
+
+        assert len(result["documents"]) == 2
+        first_document = result["documents"][0]
+        second_document = result["documents"][1]
+
+        assert isinstance(first_document, Document)
+        assert isinstance(second_document, Document)
+        assert first_document.content == "fastembed is supported by and maintained by Qdrant."
+        assert first_document.score > second_document.score

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/tests/test_fastembed_ranker.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 import numpy as np
 import pytest
@@ -257,10 +257,23 @@ class TestFastembedRanker:
             parallel=None,
         )
 
+    def test_run_calls_warm_up(self):
+        """
+        Unit test to check that warm_up is called when run is called for the first time.
+        """
+        ranker = FastembedRanker()
+
+        mock_model = MagicMock()
+        mock_model.rerank.return_value = [0.5]
+
+        with patch.object(ranker, "warm_up", side_effect=lambda: setattr(ranker, "_model", mock_model)) as mock_warm_up:
+            ranker.run(query="test query", documents=[Document(content="test document")])
+
+        mock_warm_up.assert_called_once()
+
     @pytest.mark.integration
     def test_run(self):
         ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2", top_k=2)
-        ranker.warm_up()
 
         query = "Who is maintaining Qdrant?"
         documents = [

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/tests/test_fastembed_sparse_document_embedder.py

@@ -304,6 +304,19 @@ class TestFastembedSparseDocumentEmbedderDoc:
 
         assert embedder.model_kwargs == bm25_config
 
+    def test_run_calls_warm_up(self):
+        embedder = FastembedSparseDocumentEmbedder()
+
+        mock_backend = MagicMock()
+        mock_backend.embed.return_value = [{"indices": [0], "values": [0.5]}]
+
+        with patch.object(
+            embedder, "warm_up", side_effect=lambda: setattr(embedder, "embedding_backend", mock_backend)
+        ) as mock_warm_up:
+            embedder.run(documents=[Document(content="test document")])
+
+        mock_warm_up.assert_called_once()
+
     @pytest.mark.integration
     def test_run_with_model_kwargs(self):
         """
@@ -317,7 +330,6 @@ class TestFastembedSparseDocumentEmbedderDoc:
             model="Qdrant/bm42-all-minilm-l6-v2-attentions",
             model_kwargs=bm42_config,
         )
-        embedder.warm_up()
 
         doc = Document(content="Example content using BM42")
 
@@ -336,7 +348,6 @@ class TestFastembedSparseDocumentEmbedderDoc:
         embedder = FastembedSparseDocumentEmbedder(
             model="prithivida/Splade_PP_en_v1",
         )
-        embedder.warm_up()
 
         doc = Document(content="Parton energy loss in QCD matter")
 

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/tests/test_fastembed_sparse_text_embedder.py

@@ -224,6 +224,20 @@ class TestFastembedSparseTextEmbedder:
 
         assert embedder.model_kwargs == bm25_config
 
+    def test_run_calls_warm_up(self):
+        embedder = FastembedSparseTextEmbedder()
+        assert embedder.embedding_backend is None
+
+        mock_backend = MagicMock()
+        mock_backend.embed.return_value = [[0.1, 0.2, 0.3]]
+
+        with patch.object(
+            embedder, "warm_up", side_effect=lambda: setattr(embedder, "embedding_backend", mock_backend)
+        ) as mock_warm_up:
+            embedder.run(text="test text")
+
+        mock_warm_up.assert_called_once()
+
     @pytest.mark.integration
     def test_run_with_model_kwargs(self):
         """
@@ -258,7 +272,6 @@ class TestFastembedSparseTextEmbedder:
         embedder = FastembedSparseTextEmbedder(
             model="prithivida/Splade_PP_en_v1",
         )
-        embedder.warm_up()
 
         text = "Parton energy loss in QCD matter"
 

{fastembed_haystack-2.0.0 → fastembed_haystack-2.2.0}/tests/test_fastembed_text_embedder.py

@@ -202,12 +202,25 @@ class TestFastembedTextEmbedder:
         with pytest.raises(TypeError, match="FastembedTextEmbedder expects a string as input"):
             embedder.run(text=list_integers_input)
 
+    def test_run_calls_warm_up(self):
+        embedder = FastembedTextEmbedder()
+        assert embedder.embedding_backend is None
+
+        mock_backend = MagicMock()
+        mock_backend.embed.return_value = [[0.1, 0.2, 0.3]]
+
+        with patch.object(
+            embedder, "warm_up", side_effect=lambda: setattr(embedder, "embedding_backend", mock_backend)
+        ) as mock_warm_up:
+            embedder.run(text="test text")
+
+        mock_warm_up.assert_called_once()
+
     @pytest.mark.integration
     def test_run(self):
         embedder = FastembedTextEmbedder(
             model="BAAI/bge-small-en-v1.5",
         )
-        embedder.warm_up()
 
         text = "Parton energy loss in QCD matter"
 

fastembed_haystack-2.0.0/pydoc/config_docusaurus.yml

@@ -1,32 +0,0 @@
-loaders:
-- ignore_when_discovered:
-  - __init__
-  modules:
-  - haystack_integrations.components.embedders.fastembed.fastembed_document_embedder
-  - haystack_integrations.components.embedders.fastembed.fastembed_text_embedder
-  - haystack_integrations.components.embedders.fastembed.fastembed_sparse_document_embedder
-  - haystack_integrations.components.embedders.fastembed.fastembed_sparse_text_embedder
-  - haystack_integrations.components.rankers.fastembed.ranker
-  search_path:
-  - ../src
-  type: haystack_pydoc_tools.loaders.CustomPythonLoader
-processors:
-- do_not_filter_modules: false
-  documented_only: true
-  expression: null
-  skip_empty_modules: true
-  type: filter
-- type: smart
-- type: crossref
-renderer:
-  description: FastEmbed integration for Haystack
-  id: fastembed-embedders
-  markdown:
-    add_member_class_prefix: false
-    add_method_class_prefix: true
-    classdef_code_block: false
-    descriptive_class_title: false
-    descriptive_module_title: true
-    filename: fastembed.md
-  title: FastEmbed
-  type: haystack_pydoc_tools.renderers.DocusaurusRenderer