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

{huggingface_api_haystack-0.6.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.6.0 → huggingface_api_haystack-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: huggingface-api-haystack
-Version: 0.6.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,9 +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: haystack-ai>=3.0.0
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: huggingface-hub[inference]>=0.35.0
+Requires-Dist: huggingface-hub[inference]>=1.0.0
 Description-Content-Type: text/markdown
 
 # huggingface-api-haystack

{huggingface_api_haystack-0.6.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", "httpx>=0.27.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.6.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-0.6.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-0.6.0 → huggingface_api_haystack-1.0.0}/src/haystack_integrations/components/embedders/huggingface_api/text_embedder.py

@@ -13,6 +13,7 @@ from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFModelType,
     _check_valid_model,
+    _check_valid_model_async,
 )
 
 logger = logging.getLogger(__name__)
@@ -125,7 +126,6 @@ class HuggingFaceAPITextEmbedder:
             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")
@@ -150,8 +150,39 @@ class HuggingFaceAPITextEmbedder:
         self.suffix = suffix
         self.truncate = truncate
         self.normalize = normalize
-        self._client = InferenceClient(model_or_url, token=token.resolve_value() if token else None)
-        self._async_client = AsyncInferenceClient(model_or_url, token=token.resolve_value() if token else None)
+        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 _prepare_input(self, text: str) -> tuple[str, bool | None, bool | None]:
         if not isinstance(text, str):
@@ -224,6 +255,9 @@ class HuggingFaceAPITextEmbedder:
             A dictionary with the following keys:
             - `embedding`: The embedding of the input text.
         """
+        self.warm_up()
+        assert self._client is not None  # noqa: S101
+
         text_to_embed, truncate_val, normalize_val = self._prepare_input(text)
 
         np_embedding = self._client.feature_extraction(
@@ -256,6 +290,9 @@ class HuggingFaceAPITextEmbedder:
             A dictionary with the following keys:
             - `embedding`: The embedding of the input text.
         """
+        await self.warm_up_async()
+        assert self._async_client is not None  # noqa: S101
+
         text_to_embed, truncate_val, normalize_val = self._prepare_input(text)
 
         np_embedding = await self._async_client.feature_extraction(

{huggingface_api_haystack-0.6.0 → huggingface_api_haystack-1.0.0}/src/haystack_integrations/components/generators/huggingface_api/chat/chat_generator.py

@@ -49,6 +49,7 @@ from haystack_integrations.common.huggingface_api.utils import (
     HFGenerationAPIType,
     HFModelType,
     _check_valid_model,
+    _check_valid_model_async,
 )
 
 logger = logging.getLogger(__name__)
@@ -280,7 +281,7 @@ class HuggingFaceAPIChatGenerator:
     api_type = "serverless_inference_api" # this is equivalent to the above
 
     generator = HuggingFaceAPIChatGenerator(api_type=api_type,
-                                            api_params={"model": "Qwen/Qwen2.5-7B-Instruct",
+                                            api_params={"model": "Qwen/Qwen3.5-9B",
                                                         "provider": "together"},
                                             token=Secret.from_token("<your-api-key>"))
 
@@ -305,8 +306,8 @@ class HuggingFaceAPIChatGenerator:
     generator = HuggingFaceAPIChatGenerator(
         api_type=HFGenerationAPIType.SERVERLESS_INFERENCE_API,
         api_params={
-            "model": "Qwen/Qwen2.5-VL-7B-Instruct",  # Vision Language Model
-            "provider": "hyperbolic"
+            "model": "Qwen/Qwen3.5-9B",  # Vision Language Model
+            "provider": "together"
         },
         token=Secret.from_token("<your-api-key>")
     )
@@ -404,7 +405,6 @@ class HuggingFaceAPIChatGenerator:
             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.GENERATION, token)
             model_or_url = model
         elif api_type in [HFGenerationAPIType.INFERENCE_ENDPOINTS, HFGenerationAPIType.TEXT_GENERATION_INFERENCE]:
             url = api_params.get("url")
@@ -438,27 +438,56 @@ class HuggingFaceAPIChatGenerator:
         self.token = token
         self.generation_kwargs = generation_kwargs
         self.streaming_callback = streaming_callback
-
-        resolved_api_params: dict[str, Any] = {k: v for k, v in api_params.items() if k not in ("model", "url")}
-        self._client = InferenceClient(
-            model_or_url, token=token.resolve_value() if token else None, **resolved_api_params
-        )
-        self._async_client = AsyncInferenceClient(
-            model_or_url, token=token.resolve_value() if token else None, **resolved_api_params
-        )
         self.tools = tools
-        self._is_warmed_up = False
+        self._model_or_url = model_or_url
+        self._client: InferenceClient | None = None
+        self._async_client: AsyncInferenceClient | None = None
+        self._tools_warmed_up = False
+
+    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,
+            **{k: v for k, v in self.api_params.items() if k not in ("model", "url")},
+        }
+
+    def _warm_up_tools(self) -> None:
+        if not self._tools_warmed_up:
+            warm_up_tools(self.tools)
+            self._tools_warmed_up = True
 
     def warm_up(self) -> None:
         """
         Warm up the Hugging Face API chat generator.
 
-        This will warm up the tools registered in the chat generator.
-        This method is idempotent and will only warm up the tools once.
+        This creates the synchronous client and warms up the configured tools.
         """
-        if not self._is_warmed_up:
-            warm_up_tools(self.tools)
-            self._is_warmed_up = True
+        self._warm_up_tools()
+        if self._client is None:
+            if self.api_type == HFGenerationAPIType.SERVERLESS_INFERENCE_API:
+                _check_valid_model(self._model_or_url, HFModelType.GENERATION, self.token)
+            self._client = InferenceClient(**self._client_kwargs())
+
+    async def warm_up_async(self) -> None:
+        """Create the asynchronous Hugging Face client and warm up the configured tools."""
+        self._warm_up_tools()
+        if self._async_client is None:
+            if self.api_type == HFGenerationAPIType.SERVERLESS_INFERENCE_API:
+                await _check_valid_model_async(self._model_or_url, HFModelType.GENERATION, 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]:
         """
@@ -520,8 +549,8 @@ class HuggingFaceAPIChatGenerator:
         :returns: A dictionary with the following keys:
             - `replies`: A list containing the generated responses as ChatMessage objects.
         """
-        if not self._is_warmed_up:
-            self.warm_up()
+        self.warm_up()
+        assert self._client is not None  # noqa: S101
 
         messages = _normalize_messages(messages)
 
@@ -582,8 +611,8 @@ class HuggingFaceAPIChatGenerator:
         :returns: A dictionary with the following keys:
             - `replies`: A list containing the generated responses as ChatMessage objects.
         """
-        if not self._is_warmed_up:
-            self.warm_up()
+        await self.warm_up_async()
+        assert self._async_client is not None  # noqa: S101
 
         messages = _normalize_messages(messages)
 
@@ -615,6 +644,7 @@ class HuggingFaceAPIChatGenerator:
         generation_kwargs: dict[str, Any],
         streaming_callback: SyncStreamingCallbackT,
     ) -> dict[str, list[ChatMessage]]:
+        assert self._client is not None  # noqa: S101
         api_output: Iterable[ChatCompletionStreamOutput] = self._client.chat_completion(
             messages,
             stream=True,
@@ -643,6 +673,7 @@ class HuggingFaceAPIChatGenerator:
         generation_kwargs: dict[str, Any],
         tools: list["ChatCompletionInputTool"] | None = None,
     ) -> dict[str, list[ChatMessage]]:
+        assert self._client is not None  # noqa: S101
         api_chat_output: ChatCompletionOutput = self._client.chat_completion(
             messages=messages, tools=tools, **generation_kwargs
         )
@@ -686,6 +717,7 @@ class HuggingFaceAPIChatGenerator:
         generation_kwargs: dict[str, Any],
         streaming_callback: StreamingCallbackT,
     ) -> dict[str, list[ChatMessage]]:
+        assert self._async_client is not None  # noqa: S101
         api_output: AsyncIterable[ChatCompletionStreamOutput] = await self._async_client.chat_completion(
             messages,
             stream=True,
@@ -717,6 +749,7 @@ class HuggingFaceAPIChatGenerator:
         generation_kwargs: dict[str, Any],
         tools: list["ChatCompletionInputTool"] | None = None,
     ) -> dict[str, list[ChatMessage]]:
+        assert self._async_client is not None  # noqa: S101
         api_chat_output: ChatCompletionOutput = await self._async_client.chat_completion(
             messages=messages, tools=tools, **generation_kwargs
         )