huggingface-api-haystack 0.5.0__tar.gz → 0.6.0__tar.gz

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: huggingface-api-haystack
-Version: 0.5.0
+Version: 0.6.0
 Summary: Haystack integration for Hugging Face API
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.10
 Requires-Dist: haystack-ai>=2.30.0
+Requires-Dist: httpx>=0.27.0
 Requires-Dist: huggingface-hub[inference]>=0.35.0
 Description-Content-Type: text/markdown
 
@@ -37,4 +38,7 @@ Description-Content-Type: text/markdown
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
 
-To run integration tests locally, you need to export the `HF_TOKEN` environment variable.
+To run integration tests locally, you need a Docker container running a Text Embeddings Inference (TEI) server with
+a sparse embedding model. Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.
+
+The tests that call the Hugging Face Inference API are skipped unless `HF_TOKEN` is set as an evironment variable.

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-0.6.0}/README.md

@@ -12,4 +12,7 @@
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
 
-To run integration tests locally, you need to export the `HF_TOKEN` environment variable.
+To run integration tests locally, you need a Docker container running a Text Embeddings Inference (TEI) server with
+a sparse embedding model. Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.
+
+The tests that call the Hugging Face Inference API are skipped unless `HF_TOKEN` is set as an evironment variable.

huggingface_api_haystack-0.6.0/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  tei-sparse:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3
+    command: ["--model-id", "opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini", "--pooling", "splade"]
+    ports:
+      - "8080:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+    restart: no
+
+volumes:
+  tei-data:

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-0.6.0}/pydoc/config_docusaurus.yml

@@ -1,6 +1,8 @@
 loaders:
   - modules:
       - haystack_integrations.components.embedders.huggingface_api.document_embedder
+      - haystack_integrations.components.embedders.huggingface_api.sparse_document_embedder
+      - haystack_integrations.components.embedders.huggingface_api.sparse_text_embedder
       - haystack_integrations.components.embedders.huggingface_api.text_embedder
       - haystack_integrations.components.generators.huggingface_api.chat.chat_generator
       - haystack_integrations.components.rankers.huggingface_api.ranker

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-0.6.0}/pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = ["haystack-ai>=2.30.0", "huggingface_hub[inference]>=0.35.0"]
+dependencies = ["haystack-ai>=2.30.0", "httpx>=0.27.0", "huggingface_hub[inference]>=0.35.0"]
 
 [project.urls]
 Documentation = "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api#readme"

huggingface_api_haystack-0.6.0/src/haystack_integrations/components/embedders/huggingface_api/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+from .document_embedder import HuggingFaceAPIDocumentEmbedder
+from .sparse_document_embedder import HuggingFaceAPISparseDocumentEmbedder
+from .sparse_text_embedder import HuggingFaceAPISparseTextEmbedder
+from .text_embedder import HuggingFaceAPITextEmbedder
+
+__all__ = [
+    "HuggingFaceAPIDocumentEmbedder",
+    "HuggingFaceAPISparseDocumentEmbedder",
+    "HuggingFaceAPISparseTextEmbedder",
+    "HuggingFaceAPITextEmbedder",
+]

huggingface_api_haystack-0.6.0/src/haystack_integrations/components/embedders/huggingface_api/sparse_document_embedder.py

@@ -0,0 +1,199 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from asyncio import Semaphore, gather
+from dataclasses import replace
+from itertools import chain
+from typing import Any
+
+import httpx
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.dataclasses import SparseEmbedding
+from haystack.utils import Secret
+from haystack.utils.url_validation import is_valid_http_url
+from tqdm import tqdm
+
+from .sparse_embedding_utils import _build_client_kwargs, _embed_sparse, _embed_sparse_async
+
+
+@component
+class HuggingFaceAPISparseDocumentEmbedder:
+    """
+    Embeds Documents into sparse vectors using a Hugging Face Text Embeddings Inference (TEI) server.
+
+    The component batches requests and returns copies of the input Documents with `sparse_embedding` set.
+
+    ```python
+    from haystack import Document
+    from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseDocumentEmbedder
+
+    embedder = HuggingFaceAPISparseDocumentEmbedder(api_base_url="http://localhost:8080")
+    documents = embedder.run([Document(content="Sparse retrieval")])["documents"]
+    print(documents[0].sparse_embedding)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_base_url: str = "http://localhost:8080",
+        token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+        prefix: str = "",
+        suffix: str = "",
+        batch_size: int = 32,
+        progress_bar: bool = True,
+        meta_fields_to_embed: list[str] | None = None,
+        embedding_separator: str = "\n",
+        timeout: float | None = 30.0,
+        headers: dict[str, str] | None = None,
+        concurrency_limit: int = 4,
+    ) -> None:
+        """
+        Create a sparse Document embedder backed by TEI.
+
+        :param api_base_url: Base URL of the TEI server.
+        :param token: Token sent to TEI as HTTP bearer authorization, if set.
+        :param prefix: A string to add before each prepared Document text.
+        :param suffix: A string to add after each prepared Document text.
+        :param batch_size: Number of Documents sent in each request.
+        :param progress_bar: If `True`, show a progress bar while embedding.
+        :param meta_fields_to_embed: Metadata fields to embed before the Document content.
+        :param embedding_separator: Separator for metadata fields and Document content.
+        :param timeout: HTTP request timeout in seconds. Set to `None` to disable it.
+        :param headers: Additional HTTP headers to send with each request.
+        :param concurrency_limit: Maximum concurrent requests made by `run_async`.
+        :raises ValueError: If `api_base_url` is invalid or a numeric parameter is not positive.
+        """
+        if not is_valid_http_url(api_base_url):
+            msg = f"api_base_url must be a valid HTTP URL, but got {api_base_url}"
+            raise ValueError(msg)
+        if batch_size <= 0:
+            msg = f"batch_size must be > 0, but got {batch_size}"
+            raise ValueError(msg)
+        if concurrency_limit <= 0:
+            msg = f"concurrency_limit must be > 0, but got {concurrency_limit}"
+            raise ValueError(msg)
+
+        self.api_base_url = api_base_url
+        self.token = token
+        self.prefix = prefix
+        self.suffix = suffix
+        self.batch_size = batch_size
+        self.progress_bar = progress_bar
+        self.meta_fields_to_embed = meta_fields_to_embed or []
+        self.embedding_separator = embedding_separator
+        self.timeout = timeout
+        self.headers = headers or {}
+        self.concurrency_limit = concurrency_limit
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(
+            self,
+            api_base_url=self.api_base_url,
+            token=self.token,
+            prefix=self.prefix,
+            suffix=self.suffix,
+            batch_size=self.batch_size,
+            progress_bar=self.progress_bar,
+            meta_fields_to_embed=self.meta_fields_to_embed,
+            embedding_separator=self.embedding_separator,
+            timeout=self.timeout,
+            headers=self.headers,
+            concurrency_limit=self.concurrency_limit,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPISparseDocumentEmbedder":
+        """Deserialize this component from a dictionary."""
+        return default_from_dict(cls, data)
+
+    def _client_kwargs(self) -> dict[str, Any]:
+        return _build_client_kwargs(
+            api_base_url=self.api_base_url, timeout=self.timeout, headers=self.headers, token=self.token
+        )
+
+    def _prepare_texts_to_embed(self, documents: list[Document]) -> list[str]:
+        texts = []
+        for document in documents:
+            meta = [
+                str(document.meta[field])
+                for field in self.meta_fields_to_embed
+                if field in document.meta and document.meta[field] is not None
+            ]
+            texts.append(self.prefix + self.embedding_separator.join([*meta, document.content or ""]) + self.suffix)
+        return texts
+
+    def _embed_batches(self, client: httpx.Client, texts: list[str]) -> list[SparseEmbedding]:
+        embeddings = []
+        for start in tqdm(
+            range(0, len(texts), self.batch_size),
+            disable=not self.progress_bar,
+            desc="Calculating sparse embeddings",
+        ):
+            embeddings.extend(_embed_sparse(client=client, inputs=texts[start : start + self.batch_size]))
+        return embeddings
+
+    async def _embed_batches_async(self, client: httpx.AsyncClient, texts: list[str]) -> list[SparseEmbedding]:
+        semaphore = Semaphore(self.concurrency_limit)
+        batches = [texts[start : start + self.batch_size] for start in range(0, len(texts), self.batch_size)]
+        progress = tqdm(total=len(batches), disable=not self.progress_bar, desc="Calculating sparse embeddings")
+
+        async def embed_batch(batch: list[str]) -> list[SparseEmbedding]:
+            async with semaphore:
+                result = await _embed_sparse_async(client=client, inputs=batch)
+                progress.update(1)
+                return result
+
+        try:
+            return list(chain.from_iterable(await gather(*(embed_batch(batch) for batch in batches))))
+        finally:
+            progress.close()
+
+    @staticmethod
+    def _validate_documents(documents: list[Document]) -> None:
+        if not isinstance(documents, list) or any(not isinstance(document, Document) for document in documents):
+            msg = (
+                "HuggingFaceAPISparseDocumentEmbedder expects a list of Documents as input. "
+                "To embed a string, use HuggingFaceAPISparseTextEmbedder."
+            )
+            raise TypeError(msg)
+
+    @component.output_types(documents=list[Document])
+    def run(self, documents: list[Document]) -> dict[str, list[Document]]:
+        """
+        Embed a list of Documents.
+
+        :param documents: Documents to embed.
+        :returns: Copies of the Documents with sparse embeddings.
+        """
+        self._validate_documents(documents)
+        texts = self._prepare_texts_to_embed(documents)
+        with httpx.Client(**self._client_kwargs()) as client:
+            embeddings = self._embed_batches(client, texts)
+        return {
+            "documents": [
+                replace(document, sparse_embedding=embedding)
+                for document, embedding in zip(documents, embeddings, strict=True)
+            ]
+        }
+
+    @component.output_types(documents=list[Document])
+    async def run_async(self, documents: list[Document]) -> dict[str, list[Document]]:
+        """
+        Embed a list of Documents asynchronously.
+
+        :param documents: Documents to embed.
+        :returns: Copies of the Documents with sparse embeddings.
+        """
+        self._validate_documents(documents)
+        texts = self._prepare_texts_to_embed(documents)
+        async with httpx.AsyncClient(**self._client_kwargs()) as client:
+            embeddings = await self._embed_batches_async(client, texts)
+        return {
+            "documents": [
+                replace(document, sparse_embedding=embedding)
+                for document, embedding in zip(documents, embeddings, strict=True)
+            ]
+        }

huggingface_api_haystack-0.6.0/src/haystack_integrations/components/embedders/huggingface_api/sparse_embedding_utils.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+import httpx
+from haystack.dataclasses import SparseEmbedding
+from haystack.utils import Secret
+
+
+def _build_client_kwargs(
+    *, api_base_url: str, timeout: float | None, headers: dict[str, str], token: Secret | None
+) -> dict[str, Any]:
+    """
+    Build the `httpx` client options shared by the sync and async clients.
+
+    `headers` is applied after the token, so an `Authorization` header passed at initialization wins over the one
+    derived from `token`. Otherwise, an explicit header would be silently replaced whenever `HF_TOKEN` happens to be
+    set in the environment.
+    """
+    request_headers: dict[str, str] = {}
+    if token and (token_value := token.resolve_value()):
+        request_headers["Authorization"] = f"Bearer {token_value}"
+    request_headers.update(headers)
+    return {"base_url": f"{api_base_url.rstrip('/')}/", "timeout": timeout, "headers": request_headers}
+
+
+def _parse_sparse_embeddings(result: Any, expected_count: int) -> list[SparseEmbedding]:
+    if not isinstance(result, list) or len(result) != expected_count:
+        msg = f"Expected one sparse embedding per input ({expected_count}), got {result!r}"
+        raise ValueError(msg)
+
+    embeddings = []
+    for sparse_values in result:
+        if not isinstance(sparse_values, list):
+            msg = f"Expected each sparse embedding to be a list, got {sparse_values!r}"
+            raise ValueError(msg)
+
+        indices = []
+        values = []
+        for sparse_value in sparse_values:
+            if not isinstance(sparse_value, dict) or "index" not in sparse_value or "value" not in sparse_value:
+                msg = f"Expected sparse values with 'index' and 'value' fields, got {sparse_value!r}"
+                raise ValueError(msg)
+            index = sparse_value["index"]
+            value = sparse_value["value"]
+            if (
+                not isinstance(index, int)
+                or isinstance(index, bool)
+                or not isinstance(value, int | float)
+                or isinstance(value, bool)
+            ):
+                msg = f"Invalid sparse value returned by TEI: {sparse_value!r}"
+                raise ValueError(msg)
+            indices.append(index)
+            values.append(float(value))
+
+        embeddings.append(SparseEmbedding(indices=indices, values=values))
+    return embeddings
+
+
+def _embed_sparse(*, client: httpx.Client, inputs: str | list[str]) -> list[SparseEmbedding]:
+    response = client.post("embed_sparse", json={"inputs": inputs})
+    response.raise_for_status()
+    return _parse_sparse_embeddings(response.json(), 1 if isinstance(inputs, str) else len(inputs))
+
+
+async def _embed_sparse_async(*, client: httpx.AsyncClient, inputs: str | list[str]) -> list[SparseEmbedding]:
+    response = await client.post("embed_sparse", json={"inputs": inputs})
+    response.raise_for_status()
+    return _parse_sparse_embeddings(response.json(), 1 if isinstance(inputs, str) else len(inputs))

huggingface_api_haystack-0.6.0/src/haystack_integrations/components/embedders/huggingface_api/sparse_text_embedder.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+import httpx
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import SparseEmbedding
+from haystack.utils import Secret
+from haystack.utils.url_validation import is_valid_http_url
+
+from .sparse_embedding_utils import _build_client_kwargs, _embed_sparse, _embed_sparse_async
+
+
+@component
+class HuggingFaceAPISparseTextEmbedder:
+    """
+    Embeds text into a sparse vector using a Hugging Face Text Embeddings Inference (TEI) server.
+
+    The TEI server must be running a sparse embedding model and expose the `/embed_sparse` endpoint.
+
+    ```python
+    from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseTextEmbedder
+
+    embedder = HuggingFaceAPISparseTextEmbedder(api_base_url="http://localhost:8080")
+    result = embedder.run("What is sparse retrieval?")
+    print(result["sparse_embedding"])
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_base_url: str = "http://localhost:8080",
+        token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+        prefix: str = "",
+        suffix: str = "",
+        timeout: float | None = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Create a sparse text embedder backed by TEI.
+
+        :param api_base_url: Base URL of the TEI server.
+        :param token: Token sent to TEI as HTTP bearer authorization, if set.
+        :param prefix: A string to add before the text.
+        :param suffix: A string to add after the text.
+        :param timeout: HTTP request timeout in seconds. Set to `None` to disable it.
+        :param headers: Additional HTTP headers to send with each request.
+        :raises ValueError: If `api_base_url` is not a valid HTTP URL.
+        """
+        if not is_valid_http_url(api_base_url):
+            msg = f"api_base_url must be a valid HTTP URL, but got {api_base_url}"
+            raise ValueError(msg)
+        self.api_base_url = api_base_url
+        self.token = token
+        self.prefix = prefix
+        self.suffix = suffix
+        self.timeout = timeout
+        self.headers = headers or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(
+            self,
+            api_base_url=self.api_base_url,
+            token=self.token,
+            prefix=self.prefix,
+            suffix=self.suffix,
+            timeout=self.timeout,
+            headers=self.headers,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPISparseTextEmbedder":
+        """Deserialize this component from a dictionary."""
+        return default_from_dict(cls, data)
+
+    def _client_kwargs(self) -> dict[str, Any]:
+        return _build_client_kwargs(
+            api_base_url=self.api_base_url, timeout=self.timeout, headers=self.headers, token=self.token
+        )
+
+    def _prepare_input(self, text: str) -> str:
+        if not isinstance(text, str):
+            msg = (
+                "HuggingFaceAPISparseTextEmbedder expects a string as input. "
+                "To embed Documents, use HuggingFaceAPISparseDocumentEmbedder."
+            )
+            raise TypeError(msg)
+        return self.prefix + text + self.suffix
+
+    @component.output_types(sparse_embedding=SparseEmbedding)
+    def run(self, text: str) -> dict[str, SparseEmbedding]:
+        """
+        Embed a single string.
+
+        :param text: Text to embed.
+        :returns: The sparse embedding of the input text.
+        """
+        with httpx.Client(**self._client_kwargs()) as client:
+            embeddings = _embed_sparse(client=client, inputs=self._prepare_input(text))
+        return {"sparse_embedding": embeddings[0]}
+
+    @component.output_types(sparse_embedding=SparseEmbedding)
+    async def run_async(self, text: str) -> dict[str, SparseEmbedding]:
+        """
+        Embed a single string asynchronously.
+
+        :param text: Text to embed.
+        :returns: The sparse embedding of the input text.
+        """
+        async with httpx.AsyncClient(**self._client_kwargs()) as client:
+            embeddings = await _embed_sparse_async(client=client, inputs=self._prepare_input(text))
+        return {"sparse_embedding": embeddings[0]}

huggingface_api_haystack-0.6.0/tests/test_sparse_document_embedder.py

@@ -0,0 +1,342 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from unittest.mock import MagicMock, call, patch
+
+import httpx
+import pytest
+from haystack import Document
+from haystack.dataclasses import SparseEmbedding
+from haystack.utils import Secret
+
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseDocumentEmbedder
+
+API_BASE_URL = "http://localhost:8080"
+MODULE = "haystack_integrations.components.embedders.huggingface_api.sparse_document_embedder"
+
+
+def sparse_response(data: Any) -> MagicMock:
+    response = MagicMock(spec=httpx.Response)
+    response.json.return_value = data
+    return response
+
+
+@contextmanager
+def patched_client(*, is_async: bool = False) -> Iterator[tuple[MagicMock, MagicMock]]:
+    """
+    Patch the `httpx` client constructor and yield the (client, constructor) mocks.
+
+    The component builds a client per call, so tests reach the client through the constructor rather than through
+    an attribute. `__enter__`/`__aenter__` yield the same mock, so `client.post` assertions read naturally.
+    """
+    name = "AsyncClient" if is_async else "Client"
+    client = MagicMock(spec=getattr(httpx, name))
+    if is_async:
+        client.__aenter__.return_value = client
+        client.__aexit__.return_value = False
+    else:
+        client.__enter__.return_value = client
+        client.__exit__.return_value = False
+    with patch(f"{MODULE}.httpx.{name}", return_value=client) as constructor:
+        yield client, constructor
+
+
+class TestHuggingFaceAPISparseDocumentEmbedder:
+    @pytest.mark.parametrize("api_base_url", ["not-a-url", "file:///path", "localhost:8080"])
+    def test_init_rejects_invalid_api_base_url(self, api_base_url: str) -> None:
+        with pytest.raises(ValueError, match="api_base_url must be a valid HTTP URL"):
+            HuggingFaceAPISparseDocumentEmbedder(api_base_url=api_base_url)
+
+    @pytest.mark.parametrize(("parameter", "value"), [("batch_size", 0), ("batch_size", -2), ("concurrency_limit", 0)])
+    def test_init_rejects_non_positive_numeric_options(self, parameter: str, value: int) -> None:
+        with pytest.raises(ValueError, match=f"{parameter} must be > 0"):
+            HuggingFaceAPISparseDocumentEmbedder(**{parameter: value})
+
+    def test_init_defaults(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder()
+
+        assert embedder.api_base_url == "http://localhost:8080"
+        assert embedder.batch_size == 32
+        assert embedder.progress_bar is True
+        assert embedder.meta_fields_to_embed == []
+        assert embedder.embedding_separator == "\n"
+        assert embedder.timeout == 30.0
+        assert embedder.headers == {}
+        assert embedder.concurrency_limit == 4
+
+    def test_to_dict_and_from_dict_preserve_configuration_and_secret(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CUSTOM_HF_TOKEN", "secret")
+        embedder = HuggingFaceAPISparseDocumentEmbedder(
+            api_base_url="https://tei.example.test",
+            token=Secret.from_env_var("CUSTOM_HF_TOKEN"),
+            prefix="passage: ",
+            suffix="!",
+            batch_size=2,
+            progress_bar=False,
+            meta_fields_to_embed=["title"],
+            embedding_separator=" | ",
+            timeout=None,
+            headers={"X-Test": "yes"},
+            concurrency_limit=3,
+        )
+
+        data = embedder.to_dict()
+
+        assert data["init_parameters"]["token"] == {
+            "type": "env_var",
+            "env_vars": ["CUSTOM_HF_TOKEN"],
+            "strict": True,
+        }
+        assert data["init_parameters"] == {
+            "api_base_url": "https://tei.example.test",
+            "token": {"type": "env_var", "env_vars": ["CUSTOM_HF_TOKEN"], "strict": True},
+            "prefix": "passage: ",
+            "suffix": "!",
+            "batch_size": 2,
+            "progress_bar": False,
+            "meta_fields_to_embed": ["title"],
+            "embedding_separator": " | ",
+            "timeout": None,
+            "headers": {"X-Test": "yes"},
+            "concurrency_limit": 3,
+        }
+        restored = HuggingFaceAPISparseDocumentEmbedder.from_dict(data)
+
+        assert restored.api_base_url == embedder.api_base_url
+        assert restored.prefix == "passage: "
+        assert restored.suffix == "!"
+        assert restored.batch_size == 2
+        assert restored.progress_bar is False
+        assert restored.meta_fields_to_embed == ["title"]
+        assert restored.embedding_separator == " | "
+        assert restored.timeout is None
+        assert restored.headers == {"X-Test": "yes"}
+        assert restored.concurrency_limit == 3
+        assert restored.token is not None and restored.token.resolve_value() == "secret"
+
+    def test_token_secret_cannot_be_serialized(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder(token=Secret.from_token("do-not-serialize"))
+
+        with pytest.raises(ValueError, match="Cannot serialize token-based secret"):
+            embedder.to_dict()
+
+    def test_prepare_texts_handles_metadata_prefix_suffix_and_missing_content(self) -> None:
+        documents = [
+            Document(content="body", meta={"title": "Title", "priority": 3, "ignored": "no"}),
+            Document(content=None, meta={"title": None, "priority": 0}),
+            Document(content="only body", meta={}),
+        ]
+        embedder = HuggingFaceAPISparseDocumentEmbedder(
+            prefix="<p>", suffix="</p>", meta_fields_to_embed=["title", "priority"], embedding_separator=" | "
+        )
+
+        assert embedder._prepare_texts_to_embed(documents) == [
+            "<p>Title | 3 | body</p>",
+            "<p>0 | </p>",
+            "<p>only body</p>",
+        ]
+
+    @pytest.mark.parametrize("documents", [None, "document", [1, 2], [Document(content="valid"), "invalid"]])
+    def test_run_rejects_invalid_and_mixed_inputs(self, documents: Any) -> None:
+        with pytest.raises(TypeError, match="expects a list of Documents"):
+            HuggingFaceAPISparseDocumentEmbedder(progress_bar=False).run(documents)
+
+    @pytest.mark.asyncio
+    async def test_run_async_rejects_mixed_inputs(self) -> None:
+        with pytest.raises(TypeError, match="expects a list of Documents"):
+            await HuggingFaceAPISparseDocumentEmbedder(progress_bar=False).run_async([Document(content="ok"), None])
+
+    def test_empty_list_returns_without_http_request(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with patched_client() as (client, _):
+            result = embedder.run([])
+
+        assert result == {"documents": []}
+        client.post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_empty_list_async_returns_without_http_request(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with patched_client(is_async=True) as (client, _):
+            result = await embedder.run_async([])
+
+        assert result == {"documents": []}
+        client.post.assert_not_called()
+
+    def test_run_batches_requests_preserves_order_and_copies_documents(self) -> None:
+        documents = [Document(content=f"doc {number}", meta={"number": number}) for number in range(5)]
+        responses = [
+            sparse_response([[{"index": 10, "value": 1}], [{"index": 11, "value": 2}]]),
+            sparse_response([[{"index": 12, "value": 3}], [{"index": 13, "value": 4}]]),
+            sparse_response([[{"index": 14, "value": 5}]]),
+        ]
+        embedder = HuggingFaceAPISparseDocumentEmbedder(
+            api_base_url="http://tei:80/root/",
+            token=Secret.from_token("token"),
+            prefix="passage: ",
+            batch_size=2,
+            progress_bar=False,
+            timeout=6,
+            headers={"X-Tenant": "tenant"},
+        )
+
+        with patched_client() as (client, constructor):
+            client.post.side_effect = responses
+            result = embedder.run(documents)
+
+        constructor.assert_called_once_with(
+            base_url="http://tei:80/root/",
+            timeout=6,
+            headers={"Authorization": "Bearer token", "X-Tenant": "tenant"},
+        )
+        assert client.post.call_args_list == [
+            call("embed_sparse", json={"inputs": ["passage: doc 0", "passage: doc 1"]}),
+            call("embed_sparse", json={"inputs": ["passage: doc 2", "passage: doc 3"]}),
+            call("embed_sparse", json={"inputs": ["passage: doc 4"]}),
+        ]
+        output = result["documents"]
+        assert [document.sparse_embedding.indices for document in output] == [[10], [11], [12], [13], [14]]
+        assert [document.sparse_embedding.values for document in output] == [[1.0], [2.0], [3.0], [4.0], [5.0]]
+        assert all(new is not original for original, new in zip(documents, output, strict=True))
+        assert all(original.sparse_embedding is None for original in documents)
+        assert [document.meta for document in output] == [document.meta for document in documents]
+
+    @pytest.mark.asyncio
+    async def test_run_async_batches_with_one_client_and_preserves_batch_order(self) -> None:
+        async def post(_url: str, *, json: dict[str, list[str]]) -> MagicMock:
+            inputs = json["inputs"]
+            # Let the second batch finish first; gather must still preserve input order.
+            await asyncio.sleep(0.01 if inputs[0] == "doc 0" else 0)
+            offset = int(inputs[0].split()[-1])
+            return sparse_response([[{"index": offset + position, "value": 1}] for position, _ in enumerate(inputs)])
+
+        documents = [Document(content=f"doc {number}") for number in range(4)]
+        embedder = HuggingFaceAPISparseDocumentEmbedder(
+            api_base_url="https://tei.test/", batch_size=2, progress_bar=False, timeout=None, headers={"X-Test": "yes"}
+        )
+
+        with patched_client(is_async=True) as (client, constructor):
+            client.post.side_effect = post
+            result = await embedder.run_async(documents)
+
+        # Both batches share the single client opened for this call.
+        constructor.assert_called_once_with(base_url="https://tei.test/", timeout=None, headers={"X-Test": "yes"})
+        assert client.post.await_args_list == [
+            call("embed_sparse", json={"inputs": ["doc 0", "doc 1"]}),
+            call("embed_sparse", json={"inputs": ["doc 2", "doc 3"]}),
+        ]
+        assert [document.sparse_embedding.indices for document in result["documents"]] == [[0], [1], [2], [3]]
+
+    @pytest.mark.asyncio
+    async def test_run_async_builds_and_closes_a_client_per_call(self) -> None:
+        """
+        The component must not hold on to an `httpx.AsyncClient`.
+
+        A cached client binds its keep-alive connection pool to the first event loop that used it, so a component
+        reused under a second `asyncio.run` would fail with `RuntimeError: Event loop is closed`.
+        """
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with patched_client(is_async=True) as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            await embedder.run_async([Document(content="one")])
+            await embedder.run_async([Document(content="two")])
+
+        assert constructor.call_count == 2
+        assert client.__aexit__.await_count == 2
+        assert not hasattr(embedder, "_async_client")
+
+    def test_run_builds_and_closes_a_client_per_call(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run([Document(content="one")])
+            embedder.run([Document(content="two")])
+
+        assert constructor.call_count == 2
+        assert client.__exit__.call_count == 2
+        assert not hasattr(embedder, "_client")
+
+    def test_explicit_authorization_header_wins_over_token(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """An explicit header must not be replaced by a token that only happens to be set in the environment."""
+        monkeypatch.delenv("HF_API_TOKEN", raising=False)
+        monkeypatch.setenv("HF_TOKEN", "env-token")
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False, headers={"Authorization": "Basic test-key"})
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run([Document(content="one")])
+
+        assert constructor.call_args.kwargs["headers"] == {"Authorization": "Basic test-key"}
+
+    @pytest.mark.asyncio
+    async def test_async_concurrency_limit_is_respected(self) -> None:
+        active = 0
+        maximum_active = 0
+
+        async def embed_batch(**kwargs: Any) -> list[SparseEmbedding]:
+            nonlocal active, maximum_active
+            active += 1
+            maximum_active = max(maximum_active, active)
+            await asyncio.sleep(0.01)
+            active -= 1
+            return [SparseEmbedding(indices=[int(text)], values=[1.0]) for text in kwargs["inputs"]]
+
+        embedder = HuggingFaceAPISparseDocumentEmbedder(batch_size=1, concurrency_limit=2, progress_bar=False)
+        client = MagicMock(spec=httpx.AsyncClient)
+        with patch(f"{MODULE}._embed_sparse_async", side_effect=embed_batch):
+            embeddings = await embedder._embed_batches_async(client, ["0", "1", "2", "3"])
+
+        assert maximum_active == 2
+        assert [embedding.indices for embedding in embeddings] == [[0], [1], [2], [3]]
+
+    def test_run_rejects_response_with_wrong_embedding_count(self) -> None:
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with (
+            patched_client() as (client, _),
+            pytest.raises(ValueError, match="Expected one sparse embedding per input"),
+        ):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run([Document(content="one"), Document(content="two")])
+
+    def test_run_propagates_http_error(self) -> None:
+        request = httpx.Request("POST", "http://localhost:8080/embed_sparse")
+        embedder = HuggingFaceAPISparseDocumentEmbedder(progress_bar=False)
+
+        with patched_client() as (client, _), pytest.raises(httpx.HTTPStatusError):
+            client.post.return_value = httpx.Response(500, request=request)
+            embedder.run([Document(content="text")])
+
+    @pytest.mark.integration
+    def test_live_run_tei(self) -> None:
+        documents = [Document(content="sparse retrieval"), Document(content="dense retrieval")]
+        result = HuggingFaceAPISparseDocumentEmbedder(api_base_url=API_BASE_URL, progress_bar=False).run(documents)
+
+        documents_with_embeddings = result["documents"]
+        assert len(documents_with_embeddings) == len(documents)
+        for document in documents_with_embeddings:
+            assert isinstance(document.sparse_embedding, SparseEmbedding)
+            assert document.sparse_embedding.indices
+
+    @pytest.mark.integration
+    @pytest.mark.asyncio
+    async def test_live_run_async_tei(self) -> None:
+        documents = [Document(content="sparse retrieval"), Document(content="dense retrieval")]
+        result = await HuggingFaceAPISparseDocumentEmbedder(api_base_url=API_BASE_URL, progress_bar=False).run_async(
+            documents
+        )
+
+        documents_with_embeddings = result["documents"]
+        assert len(documents_with_embeddings) == len(documents)
+        for document in documents_with_embeddings:
+            assert isinstance(document.sparse_embedding, SparseEmbedding)
+            assert document.sparse_embedding.indices

huggingface_api_haystack-0.6.0/tests/test_sparse_text_embedder.py

@@ -0,0 +1,263 @@
+# SPDX-FileCopyrightText: 2026-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from haystack.dataclasses import SparseEmbedding
+from haystack.utils import Secret
+
+from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseTextEmbedder
+
+API_BASE_URL = "http://localhost:8080"
+MODULE = "haystack_integrations.components.embedders.huggingface_api.sparse_text_embedder"
+
+
+def sparse_response(data: Any) -> MagicMock:
+    response = MagicMock(spec=httpx.Response)
+    response.json.return_value = data
+    return response
+
+
+@contextmanager
+def patched_client(*, is_async: bool = False) -> Iterator[tuple[MagicMock, MagicMock]]:
+    """
+    Patch the `httpx` client constructor and yield the (client, constructor) mocks.
+
+    The component builds a client per call, so tests reach the client through the constructor rather than through
+    an attribute. `__enter__`/`__aenter__` yield the same mock, so `client.post` assertions read naturally.
+    """
+    name = "AsyncClient" if is_async else "Client"
+    client = MagicMock(spec=getattr(httpx, name))
+    if is_async:
+        client.__aenter__.return_value = client
+        client.__aexit__.return_value = False
+    else:
+        client.__enter__.return_value = client
+        client.__exit__.return_value = False
+    with patch(f"{MODULE}.httpx.{name}", return_value=client) as constructor:
+        yield client, constructor
+
+
+class TestHuggingFaceAPISparseTextEmbedder:
+    @pytest.mark.parametrize("api_base_url", ["not-a-url", "ftp://localhost/path", "localhost:8080"])
+    def test_init_rejects_invalid_api_base_url(self, api_base_url: str) -> None:
+        with pytest.raises(ValueError, match="api_base_url must be a valid HTTP URL"):
+            HuggingFaceAPISparseTextEmbedder(api_base_url=api_base_url)
+
+    def test_init_defaults(self) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        assert embedder.api_base_url == "http://localhost:8080"
+        assert embedder.prefix == ""
+        assert embedder.suffix == ""
+        assert embedder.timeout == 30.0
+        assert embedder.headers == {}
+
+    def test_to_dict_and_from_dict_preserve_env_secret(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CUSTOM_HF_TOKEN", "resolved-token")
+        embedder = HuggingFaceAPISparseTextEmbedder(
+            api_base_url="https://tei.example.test/base/",
+            token=Secret.from_env_var("CUSTOM_HF_TOKEN"),
+            prefix="query: ",
+            suffix="!",
+            timeout=None,
+            headers={"X-Tenant": "test"},
+        )
+
+        data = embedder.to_dict()
+
+        assert data == {
+            "type": "haystack_integrations.components.embedders.huggingface_api.sparse_text_embedder."
+            "HuggingFaceAPISparseTextEmbedder",
+            "init_parameters": {
+                "api_base_url": "https://tei.example.test/base/",
+                "token": {"type": "env_var", "env_vars": ["CUSTOM_HF_TOKEN"], "strict": True},
+                "prefix": "query: ",
+                "suffix": "!",
+                "timeout": None,
+                "headers": {"X-Tenant": "test"},
+            },
+        }
+        restored = HuggingFaceAPISparseTextEmbedder.from_dict(data)
+        assert restored.api_base_url == embedder.api_base_url
+        assert restored.prefix == "query: "
+        assert restored.suffix == "!"
+        assert restored.timeout is None
+        assert restored.headers == {"X-Tenant": "test"}
+        assert restored.token is not None
+        assert restored.token.resolve_value() == "resolved-token"
+
+    def test_token_secret_cannot_be_serialized(self) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder(token=Secret.from_token("do-not-serialize"))
+
+        with pytest.raises(ValueError, match="Cannot serialize token-based secret"):
+            embedder.to_dict()
+
+    @pytest.mark.parametrize("invalid_text", [None, 42, ["text"]])
+    def test_run_rejects_non_string_input(self, invalid_text: Any) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with pytest.raises(TypeError, match="expects a string"):
+            embedder.run(invalid_text)
+
+    def test_run_posts_tei_request_and_converts_response(self) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder(
+            api_base_url="https://tei.example.test/api/",
+            token=Secret.from_token("secret"),
+            prefix="query: ",
+            suffix=" </s>",
+            timeout=4.5,
+            headers={"X-Tenant": "one"},
+        )
+
+        with patched_client() as (client, constructor):
+            response = sparse_response([[{"index": 12, "value": 1}, {"index": 99, "value": 0.25}]])
+            client.post.return_value = response
+            result = embedder.run("cheese")
+
+        constructor.assert_called_once_with(
+            base_url="https://tei.example.test/api/",
+            timeout=4.5,
+            headers={"Authorization": "Bearer secret", "X-Tenant": "one"},
+        )
+        client.post.assert_called_once_with("embed_sparse", json={"inputs": "query: cheese </s>"})
+        response.raise_for_status.assert_called_once_with()
+        assert result == {"sparse_embedding": SparseEmbedding(indices=[12, 99], values=[1.0, 0.25])}
+
+    def test_token_is_sent_as_bearer_authorization(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("HF_API_TOKEN", raising=False)
+        monkeypatch.setenv("HF_TOKEN", "env-token")
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run("text")
+
+        assert constructor.call_args.kwargs["headers"] == {"Authorization": "Bearer env-token"}
+
+    def test_explicit_authorization_header_wins_over_token(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """An explicit header must not be replaced by a token that only happens to be set in the environment."""
+        monkeypatch.delenv("HF_API_TOKEN", raising=False)
+        monkeypatch.setenv("HF_TOKEN", "env-token")
+        embedder = HuggingFaceAPISparseTextEmbedder(headers={"Authorization": "Basic test-key"})
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run("text")
+
+        assert constructor.call_args.kwargs["headers"] == {"Authorization": "Basic test-key"}
+
+    def test_token_is_resolved_per_call(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """The token is read at request time, so a rotated environment variable is picked up."""
+        monkeypatch.delenv("HF_API_TOKEN", raising=False)
+        monkeypatch.setenv("HF_TOKEN", "first-token")
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run("text")
+            monkeypatch.setenv("HF_TOKEN", "second-token")
+            embedder.run("text")
+
+        assert [each.kwargs["headers"]["Authorization"] for each in constructor.call_args_list] == [
+            "Bearer first-token",
+            "Bearer second-token",
+        ]
+
+    @pytest.mark.asyncio
+    async def test_run_async_uses_async_client_and_request_options(self) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder(
+            api_base_url="http://tei:8080/", token=Secret.from_token("token"), timeout=9, headers={"X-Test": "yes"}
+        )
+
+        with patched_client(is_async=True) as (client, constructor):
+            response = sparse_response([[{"index": 7, "value": 2.5}]])
+            client.post.return_value = response
+            result = await embedder.run_async("input")
+
+        constructor.assert_called_once_with(
+            base_url="http://tei:8080/", timeout=9, headers={"Authorization": "Bearer token", "X-Test": "yes"}
+        )
+        client.post.assert_awaited_once_with("embed_sparse", json={"inputs": "input"})
+        response.raise_for_status.assert_called_once_with()
+        assert result["sparse_embedding"] == SparseEmbedding(indices=[7], values=[2.5])
+
+    @pytest.mark.asyncio
+    async def test_run_async_builds_and_closes_a_client_per_call(self) -> None:
+        """
+        The component must not hold on to an `httpx.AsyncClient`.
+
+        A cached client binds its keep-alive connection pool to the first event loop that used it, so a component
+        reused under a second `asyncio.run` would fail with `RuntimeError: Event loop is closed`.
+        """
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client(is_async=True) as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            await embedder.run_async("one")
+            await embedder.run_async("two")
+
+        assert constructor.call_count == 2
+        assert client.__aexit__.await_count == 2
+        assert not hasattr(embedder, "_async_client")
+
+    def test_run_builds_and_closes_a_client_per_call(self) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client() as (client, constructor):
+            client.post.return_value = sparse_response([[{"index": 1, "value": 1}]])
+            embedder.run("one")
+            embedder.run("two")
+
+        assert constructor.call_count == 2
+        assert client.__exit__.call_count == 2
+        assert not hasattr(embedder, "_client")
+
+    @pytest.mark.parametrize(
+        "payload",
+        [
+            {"index": 1, "value": 0.5},
+            [],
+            ["not-a-list"],
+            [[{"index": 1}]],
+            [[{"index": "1", "value": 0.5}]],
+            [[{"index": 1, "value": True}]],
+        ],
+    )
+    def test_run_rejects_malformed_tei_responses(self, payload: Any) -> None:
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client() as (client, _), pytest.raises(ValueError):
+            client.post.return_value = sparse_response(payload)
+            embedder.run("text")
+
+    def test_run_propagates_http_error(self) -> None:
+        request = httpx.Request("POST", "http://localhost:8080/embed_sparse")
+        embedder = HuggingFaceAPISparseTextEmbedder()
+
+        with patched_client() as (client, _), pytest.raises(httpx.HTTPStatusError) as exc_info:
+            client.post.return_value = httpx.Response(503, request=request)
+            embedder.run("text")
+
+        assert exc_info.value.response.status_code == 503
+
+    @pytest.mark.integration
+    def test_live_run_tei(self) -> None:
+        result = HuggingFaceAPISparseTextEmbedder(api_base_url=API_BASE_URL).run("sparse retrieval")
+
+        assert isinstance(result["sparse_embedding"], SparseEmbedding)
+        assert result["sparse_embedding"].indices
+
+    @pytest.mark.integration
+    @pytest.mark.asyncio
+    async def test_live_run_async_tei(self) -> None:
+        result = await HuggingFaceAPISparseTextEmbedder(api_base_url=API_BASE_URL).run_async("sparse retrieval")
+
+        assert isinstance(result["sparse_embedding"], SparseEmbedding)
+        assert result["sparse_embedding"].indices

huggingface_api_haystack-0.5.0/src/haystack_integrations/components/embedders/huggingface_api/__init__.py

@@ -1,7 +0,0 @@
-# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
-#
-# SPDX-License-Identifier: Apache-2.0
-from .document_embedder import HuggingFaceAPIDocumentEmbedder
-from .text_embedder import HuggingFaceAPITextEmbedder
-
-__all__ = ["HuggingFaceAPIDocumentEmbedder", "HuggingFaceAPITextEmbedder"]