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

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-1.0.0}/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## [unreleased]
+## [integrations/huggingface_api-v0.6.0] - 2026-08-27
+
+### 🚀 Features
+
+- *(huggingface_api)* Add SPLADE sparse embedder components (#3835)
+
+## [integrations/huggingface_api-v0.5.0] - 2026-08-24
+
+### 🐛 Bug Fixes
+
+- Fix new issues raised by ruff 0.16.0 (#3670)
+- Serialize missing init params in to_dict (transformers, huggingface_api, ragas) (#3808)
+
+### 🧹 Chores
+
+- Re-standardize READMEs (#3768)
+- Clarify how generation_kwargs passed in run are handled (#3805)
+
+
+## [integrations/huggingface_api-v0.4.0] - 2026-07-09
 
 ### 🧪 Testing
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: huggingface-api-haystack
-Version: 0.5.0
+Version: 1.0.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
@@ -19,8 +19,9 @@ Classifier: Programming Language :: Python :: 3.14
 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: huggingface-hub[inference]>=0.35.0
+Requires-Dist: haystack-ai>=3.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: huggingface-hub[inference]>=1.0.0
 Description-Content-Type: text/markdown
 
 # huggingface-api-haystack
@@ -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-1.0.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-1.0.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-1.0.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-1.0.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>=3.0.0", "httpx>=0.27.0", "huggingface_hub[inference]>=1.0.0"]
 
 [project.urls]
 Documentation = "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api#readme"

{huggingface_api_haystack-0.5.0 → huggingface_api_haystack-1.0.0}/src/haystack_integrations/common/huggingface_api/utils.py

@@ -7,6 +7,7 @@ from enum import Enum
 from haystack.utils import Secret
 from huggingface_hub import HfApi
 from huggingface_hub.errors import RepositoryNotFoundError
+from huggingface_hub.utils import build_hf_headers, get_async_session, hf_raise_for_status
 
 
 class HFGenerationAPIType(Enum):
@@ -82,14 +83,15 @@ class HFModelType(Enum):
 
 def _check_valid_model(model_id: str, model_type: HFModelType, token: Secret | None) -> None:
     """
-    Check if the provided model ID corresponds to a valid model on HuggingFace Hub.
+    Check if the provided model ID corresponds to a valid model on Hugging Face Hub.
 
-    Also check if the model is an embedding or generation model.
+    Also check if the model supports the requested embedding or generation task.
 
-    :param model_id: A string representing the HuggingFace model ID.
-    :param model_type: the model type, HFModelType.EMBEDDING or HFModelType.GENERATION
-    :param token: The optional authentication token.
-    :raises ValueError: If the model is not found or is not a embedding model.
+    :param model_id: A string representing the Hugging Face model ID.
+    :param model_type: The model type, `HFModelType.EMBEDDING` or `HFModelType.GENERATION`.
+    :param token: The optional authentication secret.
+    :raises ValueError: If the secret cannot be resolved, the model is not found, or it does not match the
+        requested type.
     """
     api = HfApi()
     try:
@@ -98,11 +100,42 @@ def _check_valid_model(model_id: str, model_type: HFModelType, token: Secret | N
         msg = f"Model {model_id} not found on HuggingFace Hub. Please provide a valid HuggingFace model_id."
         raise ValueError(msg) from e
 
+    _validate_model_type(model_id, model_type, model_info.pipeline_tag)
+
+
+async def _check_valid_model_async(model_id: str, model_type: HFModelType, token: Secret | None) -> None:
+    """
+    Asynchronously check if the provided model ID corresponds to a valid model on Hugging Face Hub.
+
+    Also check if the model supports the requested embedding or generation task.
+
+    :param model_id: A string representing the Hugging Face model ID.
+    :param model_type: The model type, `HFModelType.EMBEDDING` or `HFModelType.GENERATION`.
+    :param token: The optional authentication secret.
+    :raises ValueError: If the secret cannot be resolved, the model is not found, or it does not match the
+        requested type.
+    """
+    api = HfApi()
+    try:
+        async with get_async_session() as client:
+            response = await client.get(
+                f"{api.endpoint}/api/models/{model_id}",
+                headers=build_hf_headers(token=token.resolve_value() if token else None),
+            )
+            hf_raise_for_status(response)
+    except RepositoryNotFoundError as e:
+        msg = f"Model {model_id} not found on HuggingFace Hub. Please provide a valid HuggingFace model_id."
+        raise ValueError(msg) from e
+
+    _validate_model_type(model_id, model_type, response.json().get("pipeline_tag"))
+
+
+def _validate_model_type(model_id: str, model_type: HFModelType, pipeline_tag: str | None) -> None:
     if model_type == HFModelType.EMBEDDING:
-        allowed_model = model_info.pipeline_tag in ["sentence-similarity", "feature-extraction"]
+        allowed_model = pipeline_tag in ["sentence-similarity", "feature-extraction"]
         error_msg = f"Model {model_id} is not a embedding model. Please provide a embedding model."
     elif model_type == HFModelType.GENERATION:
-        allowed_model = model_info.pipeline_tag in ["text-generation", "text2text-generation", "image-text-to-text"]
+        allowed_model = pipeline_tag in ["text-generation", "text2text-generation", "image-text-to-text"]
         error_msg = f"Model {model_id} is not a text generation model. Please provide a text generation model."
     else:
         allowed_model = False

huggingface_api_haystack-1.0.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.5.0 → huggingface_api_haystack-1.0.0}/src/haystack_integrations/components/embedders/huggingface_api/document_embedder.py

@@ -18,6 +18,7 @@ from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFModelType,
     _check_valid_model,
+    _check_valid_model_async,
 )
 
 logger = logging.getLogger(__name__)
@@ -161,7 +162,6 @@ class HuggingFaceAPIDocumentEmbedder:
             if model is None:
                 msg = "To use the Serverless Inference API, you need to specify the `model` parameter in `api_params`."
                 raise ValueError(msg)
-            _check_valid_model(model, HFModelType.EMBEDDING, token)
             model_or_url = model
         elif api_type in [HFEmbeddingAPIType.INFERENCE_ENDPOINTS, HFEmbeddingAPIType.TEXT_EMBEDDINGS_INFERENCE]:
             url = api_params.get("url")
@@ -179,8 +179,6 @@ class HuggingFaceAPIDocumentEmbedder:
             msg = f"Unknown api_type {api_type}"
             raise ValueError(msg)
 
-        client_args: dict[str, Any] = {"model": model_or_url, "token": token.resolve_value() if token else None}
-
         self.api_type = api_type
         self.api_params = api_params
         self.token = token
@@ -193,8 +191,39 @@ class HuggingFaceAPIDocumentEmbedder:
         self.meta_fields_to_embed = meta_fields_to_embed or []
         self.embedding_separator = embedding_separator
         self.concurrency_limit = concurrency_limit
-        self._client = InferenceClient(**client_args)
-        self._async_client = AsyncInferenceClient(**client_args)
+        self._model_or_url = model_or_url
+        self._client: InferenceClient | None = None
+        self._async_client: AsyncInferenceClient | None = None
+
+    def _client_kwargs(self) -> dict[str, Any]:
+        """Build the keyword arguments used to create Hugging Face clients."""
+        return {"model": self._model_or_url, "token": self.token.resolve_value() if self.token else None}
+
+    def warm_up(self) -> None:
+        """Create the synchronous Hugging Face client."""
+        if self._client is None:
+            if self.api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
+                _check_valid_model(self._model_or_url, HFModelType.EMBEDDING, self.token)
+            self._client = InferenceClient(**self._client_kwargs())
+
+    async def warm_up_async(self) -> None:
+        """Create the asynchronous Hugging Face client."""
+        if self._async_client is None:
+            if self.api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
+                await _check_valid_model_async(self._model_or_url, HFModelType.EMBEDDING, self.token)
+            self._async_client = AsyncInferenceClient(**self._client_kwargs())
+
+    def close(self) -> None:
+        """Close the synchronous Hugging Face client."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    async def close_async(self) -> None:
+        """Close the asynchronous Hugging Face client."""
+        if self._async_client is not None:
+            await self._async_client.close()
+            self._async_client = None
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -270,6 +299,7 @@ class HuggingFaceAPIDocumentEmbedder:
         """
         Embed a list of texts in batches.
         """
+        assert self._client is not None  # noqa: S101
         truncate, normalize = self._adjust_api_parameters(self.truncate, self.normalize, self.api_type)
 
         all_embeddings: list = []
@@ -278,7 +308,12 @@ class HuggingFaceAPIDocumentEmbedder:
         ):
             batch = texts_to_embed[i : i + batch_size]
 
-            np_embeddings = self._client.feature_extraction(text=batch, truncate=truncate, normalize=normalize)
+            # a batch is accepted but text is typed as str
+            np_embeddings = self._client.feature_extraction(
+                text=batch,  # type: ignore[arg-type]
+                truncate=truncate,
+                normalize=normalize,
+            )
 
             if np_embeddings.ndim != _EXPECTED_EMBEDDING_NDIM or np_embeddings.shape[0] != len(batch):
                 msg = f"Expected embedding shape ({batch_size}, embedding_dim), got {np_embeddings.shape}"
@@ -292,6 +327,8 @@ class HuggingFaceAPIDocumentEmbedder:
         """
         Embed a list of texts in batches asynchronously.
         """
+        assert self._async_client is not None  # noqa: S101
+        async_client = self._async_client
         truncate, normalize = self._adjust_api_parameters(self.truncate, self.normalize, self.api_type)
         sem = Semaphore(max(1, self.concurrency_limit))
         num_batches = (len(texts_to_embed) + batch_size - 1) // batch_size
@@ -299,8 +336,11 @@ class HuggingFaceAPIDocumentEmbedder:
 
         async def _runner(batch: list[str]) -> list[list[float]]:
             async with sem:
-                np_embeddings = await self._async_client.feature_extraction(
-                    text=batch, truncate=truncate, normalize=normalize
+                # a batch is accepted but text is typed as str
+                np_embeddings = await async_client.feature_extraction(
+                    text=batch,  # type: ignore[arg-type]
+                    truncate=truncate,
+                    normalize=normalize,
                 )
 
                 if np_embeddings.ndim != _EXPECTED_EMBEDDING_NDIM or np_embeddings.shape[0] != len(batch):
@@ -342,6 +382,9 @@ class HuggingFaceAPIDocumentEmbedder:
             A dictionary with the following keys:
             - `documents`: A list of documents with embeddings.
         """
+        self.warm_up()
+        assert self._client is not None  # noqa: S101
+
         if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
             msg = (
                 "HuggingFaceAPIDocumentEmbedder expects a list of Documents as input."
@@ -375,6 +418,9 @@ class HuggingFaceAPIDocumentEmbedder:
             A dictionary with the following keys:
             - `documents`: A list of documents with embeddings.
         """
+        await self.warm_up_async()
+        assert self._async_client is not None  # noqa: S101
+
         if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
             msg = (
                 "HuggingFaceAPIDocumentEmbedder expects a list of Documents as input."

huggingface_api_haystack-1.0.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-1.0.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))