huggingface-api-haystack 0.2.0__tar.gz → 0.3.0__tar.gz

huggingface_api_haystack-0.3.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [integrations/huggingface_api-v0.2.0] - 2026-06-05
+
+### 🚀 Features
+
+- Move HuggingFaceTEIRanker from Haystack (#3407)
+
+### 📚 Documentation
+
+- Document raised exceptions in HF API components (#3406)
+
+
+## [integrations/huggingface_api-v0.1.0] - 2026-06-05
+
+### 🚀 Features
+
+- Move HF API components to core integrations (#3403)
+
+<!-- generated by git-cliff -->

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huggingface-api-haystack
-Version: 0.2.0
+Version: 0.3.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

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/pyproject.toml

@@ -68,7 +68,7 @@ integration = 'pytest -m "integration" {args:tests}'
 all = 'pytest {args:tests}'
 unit-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x -m "not integration" {args:tests}'
 integration-cov-append-retry = 'pytest --cov=haystack_integrations --cov-append --reruns 3 --reruns-delay 30 -x -m "integration" {args:tests}'
-types = """mypy -p haystack_integrations.components.common.huggingface_api \
+types = """mypy -p haystack_integrations.common.huggingface_api \
 -p haystack_integrations.components.embedders.huggingface_api \
 -p haystack_integrations.components.generators.huggingface_api \
 -p haystack_integrations.components.rankers.huggingface_api {args}"""

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/src/haystack_integrations/components/embedders/huggingface_api/document_embedder.py

@@ -14,7 +14,7 @@ from haystack.utils.url_validation import is_valid_http_url
 from huggingface_hub import AsyncInferenceClient, InferenceClient
 from tqdm import tqdm
 
-from haystack_integrations.components.common.huggingface_api.utils import (
+from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFModelType,
     _check_valid_model,

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/src/haystack_integrations/components/embedders/huggingface_api/text_embedder.py

@@ -9,7 +9,7 @@ from haystack.utils import Secret
 from haystack.utils.url_validation import is_valid_http_url
 from huggingface_hub import AsyncInferenceClient, InferenceClient
 
-from haystack_integrations.components.common.huggingface_api.utils import (
+from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFModelType,
     _check_valid_model,

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/src/haystack_integrations/components/generators/huggingface_api/chat/chat_generator.py

@@ -45,7 +45,7 @@ from huggingface_hub import (
     InferenceClient,
 )
 
-from haystack_integrations.components.common.huggingface_api.utils import (
+from haystack_integrations.common.huggingface_api.utils import (
     HFGenerationAPIType,
     HFModelType,
     _check_valid_model,
@@ -270,7 +270,7 @@ class HuggingFaceAPIChatGenerator:
     from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
     from haystack.dataclasses import ChatMessage
     from haystack.utils import Secret
-    from haystack_integrations.components.common.huggingface_api.utils import HFGenerationAPIType
+    from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
 
     messages = [ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
                 ChatMessage.from_user("What's Natural Language Processing?")]
@@ -294,7 +294,7 @@ class HuggingFaceAPIChatGenerator:
     from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
     from haystack.dataclasses import ChatMessage, ImageContent
     from haystack.utils import Secret
-    from haystack_integrations.components.common.huggingface_api.utils import HFGenerationAPIType
+    from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
 
     # Create an image from file path, URL, or base64
     image = ImageContent.from_file_path("path/to/your/image.jpg")

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/src/haystack_integrations/components/rankers/huggingface_api/ranker.py

@@ -93,6 +93,9 @@ class HuggingFaceTEIRanker:
         self.max_retries = max_retries
         self.retry_status_codes = retry_status_codes
         self.raw_scores = raw_scores
+        if top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -201,6 +204,9 @@ class HuggingFaceTEIRanker:
         # Return empty if no documents provided
         if not documents:
             return {"documents": []}
+        if top_k is not None and top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
 
         # Prepare the payload
         deduplicated_documents = _deduplicate_documents(documents)
@@ -265,6 +271,9 @@ class HuggingFaceTEIRanker:
         # Return empty if no documents provided
         if not documents:
             return {"documents": []}
+        if top_k is not None and top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
 
         # Prepare the payload
         deduplicated_documents = _deduplicate_documents(documents)

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/conftest.py

@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import os
 from pathlib import Path
 
 import pytest
@@ -13,9 +14,9 @@ def test_files_path():
 
 
 @pytest.fixture()
-def del_hf_env_vars(monkeypatch):
+def del_hf_env_vars_if_empty(monkeypatch):
     """
-    Delete Hugging Face environment variables for tests.
+    Delete Hugging Face environment variables for tests if empty.
 
     Prevents passing empty tokens to Hugging Face, which would cause API calls to fail.
     This is particularly relevant for PRs opened from forks, where secrets are not available
@@ -23,5 +24,6 @@ def del_hf_env_vars(monkeypatch):
 
     See https://github.com/deepset-ai/haystack/issues/8811 for more details.
     """
-    monkeypatch.delenv("HF_API_TOKEN", raising=False)
-    monkeypatch.delenv("HF_TOKEN", raising=False)
+    for var in ("HF_API_TOKEN", "HF_TOKEN"):
+        if not os.environ.get(var, "").strip():
+            monkeypatch.delenv(var, raising=False)

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/test_chat_generator.py

@@ -28,7 +28,7 @@ from huggingface_hub import (
 )
 from huggingface_hub.errors import RepositoryNotFoundError
 
-from haystack_integrations.components.common.huggingface_api.utils import HFGenerationAPIType
+from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType
 from haystack_integrations.components.generators.huggingface_api.chat.chat_generator import (
     HuggingFaceAPIChatGenerator,
     _convert_chat_completion_stream_output_to_streaming_chunk,

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/test_document_embedder.py

@@ -13,7 +13,7 @@ from haystack.utils.auth import Secret
 from huggingface_hub.utils import RepositoryNotFoundError
 from numpy import array
 
-from haystack_integrations.components.common.huggingface_api.utils import HFEmbeddingAPIType
+from haystack_integrations.common.huggingface_api.utils import HFEmbeddingAPIType
 from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
 
 

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/test_ranker.py

@@ -13,14 +13,14 @@ from haystack_integrations.components.rankers.huggingface_api import HuggingFace
 
 
 class TestHuggingFaceTEIRanker:
-    def test_init(self, del_hf_env_vars):
+    def test_init(self, del_hf_env_vars_if_empty):
         """Test initialization with default and custom parameters"""
         # Default parameters
         ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
         assert ranker.url == "https://api.my-tei-service.com"
         assert ranker.top_k == 10
         assert ranker.timeout == 30
-        assert not ranker.token.resolve_value()
+        assert ranker.token == Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False)
         assert ranker.max_retries == 3
         assert ranker.retry_status_codes is None
 
@@ -41,7 +41,7 @@ class TestHuggingFaceTEIRanker:
         assert ranker.max_retries == 5
         assert ranker.retry_status_codes == [500, 502, 503]
 
-    def test_to_dict(self, del_hf_env_vars):
+    def test_to_dict(self, del_hf_env_vars_if_empty):
         """Test serialization to dict with Secret token"""
         component = HuggingFaceTEIRanker(
             url="https://api.my-tei-service.com", top_k=5, timeout=30, max_retries=4, retry_status_codes=[500, 502]
@@ -60,7 +60,7 @@ class TestHuggingFaceTEIRanker:
         assert data["init_parameters"]["max_retries"] == 4
         assert data["init_parameters"]["retry_status_codes"] == [500, 502]
 
-    def test_from_dict(self, del_hf_env_vars):
+    def test_from_dict(self, del_hf_env_vars_if_empty):
         """Test deserialization from dict with environment variable token"""
         data = {
             "type": "haystack_integrations.components.rankers.huggingface_api.ranker.HuggingFaceTEIRanker",
@@ -82,14 +82,28 @@ class TestHuggingFaceTEIRanker:
         assert component.max_retries == 4
         assert component.retry_status_codes == [500, 502]
 
-    def test_empty_documents(self, del_hf_env_vars):
+    def test_empty_documents(self, del_hf_env_vars_if_empty):
         """Test that empty documents list returns empty result"""
         ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
         result = ranker.run(query="test query", documents=[])
         assert result == {"documents": []}
 
+    def test_init_fail_with_zero_top_k(self):
+        with pytest.raises(ValueError, match="top_k must be > 0, but got 0"):
+            HuggingFaceTEIRanker(url="http://localhost:8080", top_k=0)
+
+    def test_init_fail_with_negative_top_k(self):
+        with pytest.raises(ValueError, match=r"top_k must be > 0, but got -5"):
+            HuggingFaceTEIRanker(url="http://localhost:8080", top_k=-5)
+
+    def test_run_fail_with_invalid_top_k_override(self):
+        ranker = HuggingFaceTEIRanker(url="http://localhost:8080")
+        docs = [Document(content="doc")]
+        with pytest.raises(ValueError, match="top_k must be > 0, but got 0"):
+            ranker.run(query="q", documents=docs, top_k=0)
+
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
-    def test_run_with_mock(self, mock_request, del_hf_env_vars):
+    def test_run_with_mock(self, mock_request, del_hf_env_vars_if_empty):
         """Test run method with mocked API response"""
         # Setup mock response
         mock_response = MagicMock(spec=httpx.Response)
@@ -137,7 +151,7 @@ class TestHuggingFaceTEIRanker:
         assert result["documents"][2].score == 0.75
 
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
-    def test_run_with_truncation_direction(self, mock_request, del_hf_env_vars):
+    def test_run_with_truncation_direction(self, mock_request, del_hf_env_vars_if_empty):
         """Test run method with truncation direction parameter"""
         # Setup mock response
         mock_response = MagicMock(spec=httpx.Response)
@@ -170,7 +184,7 @@ class TestHuggingFaceTEIRanker:
         )
 
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
-    def test_run_with_custom_top_k(self, mock_request, del_hf_env_vars):
+    def test_run_with_custom_top_k(self, mock_request, del_hf_env_vars_if_empty):
         """Test run method with custom top_k parameter"""
         # Setup mock response with 5 documents
         mock_response = MagicMock(spec=httpx.Response)
@@ -207,7 +221,7 @@ class TestHuggingFaceTEIRanker:
         assert result["documents"][1].content == "Document 3"
 
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
-    def test_run_deduplicates_documents(self, mock_request, del_hf_env_vars):
+    def test_run_deduplicates_documents(self, mock_request, del_hf_env_vars_if_empty):
         """Test that duplicate documents are removed before sending to the API."""
         mock_response = MagicMock(spec=httpx.Response)
         mock_response.json.return_value = [{"index": 1, "score": 0.9}, {"index": 0, "score": 0.2}]
@@ -228,7 +242,7 @@ class TestHuggingFaceTEIRanker:
             url="https://api.my-tei-service.com/rerank",
             json={"query": "test query", "texts": ["keep me", "unique"], "raw_scores": False},
             timeout=30,
-            headers={},
+            headers={"Authorization": f"Bearer {ranker.token.resolve_value()}"} if ranker.token.resolve_value() else {},
             attempts=3,
             status_codes_to_retry=None,
         )
@@ -237,7 +251,7 @@ class TestHuggingFaceTEIRanker:
         assert result["documents"][1].content == "keep me"
 
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
-    def test_error_handling(self, mock_request, del_hf_env_vars):
+    def test_error_handling(self, mock_request, del_hf_env_vars_if_empty):
         """Test error handling in the ranker"""
         # Setup mock response with error
         mock_response = MagicMock(spec=httpx.Response)
@@ -261,7 +275,7 @@ class TestHuggingFaceTEIRanker:
 
     @pytest.mark.asyncio
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.async_request_with_retry")
-    async def test_run_async_with_mock(self, mock_request, del_hf_env_vars):
+    async def test_run_async_with_mock(self, mock_request, del_hf_env_vars_if_empty):
         """Test run_async method with mocked API response"""
         # Setup mock response
         mock_response = MagicMock(spec=httpx.Response)
@@ -310,7 +324,7 @@ class TestHuggingFaceTEIRanker:
 
     @pytest.mark.asyncio
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.async_request_with_retry")
-    async def test_run_async_deduplicates_documents(self, mock_request, del_hf_env_vars):
+    async def test_run_async_deduplicates_documents(self, mock_request, del_hf_env_vars_if_empty):
         """Test that duplicate documents are removed before sending to the API."""
         mock_response = MagicMock(spec=httpx.Response)
         mock_response.json.return_value = [{"index": 1, "score": 0.9}, {"index": 0, "score": 0.2}]
@@ -331,7 +345,7 @@ class TestHuggingFaceTEIRanker:
             url="https://api.my-tei-service.com/rerank",
             json={"query": "test query", "texts": ["keep me", "unique"], "raw_scores": False},
             timeout=30,
-            headers={},
+            headers={"Authorization": f"Bearer {ranker.token.resolve_value()}"} if ranker.token.resolve_value() else {},
             attempts=3,
             status_codes_to_retry=None,
         )
@@ -341,7 +355,7 @@ class TestHuggingFaceTEIRanker:
 
     @pytest.mark.asyncio
     @patch("haystack_integrations.components.rankers.huggingface_api.ranker.async_request_with_retry")
-    async def test_run_async_empty_documents(self, mock_request, del_hf_env_vars):
+    async def test_run_async_empty_documents(self, mock_request, del_hf_env_vars_if_empty):
         """Test run_async with empty documents list"""
         ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
         result = await ranker.run_async(query="test query", documents=[])

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/test_text_embedder.py

@@ -12,7 +12,7 @@ from haystack.utils.auth import Secret
 from huggingface_hub.utils import RepositoryNotFoundError
 from numpy import array
 
-from haystack_integrations.components.common.huggingface_api.utils import HFEmbeddingAPIType
+from haystack_integrations.common.huggingface_api.utils import HFEmbeddingAPIType
 from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
 
 

{huggingface_api_haystack-0.2.0 → huggingface_api_haystack-0.3.0}/tests/test_utils.py

@@ -7,7 +7,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 from huggingface_hub.errors import RepositoryNotFoundError
 
-from haystack_integrations.components.common.huggingface_api.utils import (
+from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFGenerationAPIType,
     HFModelType,
@@ -30,19 +30,19 @@ class TestAPITypes:
 
 
 class TestCheckValidModel:
-    @patch("haystack_integrations.components.common.huggingface_api.utils.HfApi")
+    @patch("haystack_integrations.common.huggingface_api.utils.HfApi")
     def test_valid_model(self, mock_hf_api):
         mock_hf_api.return_value.model_info.return_value = MagicMock(pipeline_tag="feature-extraction")
         _check_valid_model("BAAI/bge-small-en-v1.5", HFModelType.EMBEDDING, token=None)
         mock_hf_api.return_value.model_info.assert_called_once_with("BAAI/bge-small-en-v1.5", token=None)
 
-    @patch("haystack_integrations.components.common.huggingface_api.utils.HfApi")
+    @patch("haystack_integrations.common.huggingface_api.utils.HfApi")
     def test_wrong_model_type(self, mock_hf_api):
         mock_hf_api.return_value.model_info.return_value = MagicMock(pipeline_tag="text-generation")
         with pytest.raises(ValueError, match="not a embedding model"):
             _check_valid_model("microsoft/phi-2", HFModelType.EMBEDDING, token=None)
 
-    @patch("haystack_integrations.components.common.huggingface_api.utils.HfApi")
+    @patch("haystack_integrations.common.huggingface_api.utils.HfApi")
     def test_model_not_found(self, mock_hf_api):
         mock_hf_api.return_value.model_info.side_effect = RepositoryNotFoundError("not found", response=MagicMock())
         with pytest.raises(ValueError, match="not found on HuggingFace Hub"):

huggingface_api_haystack-0.2.0/CHANGELOG.md

@@ -1,9 +0,0 @@
-# Changelog
-
-## [integrations/huggingface_api-v0.1.0] - 2026-06-05
-
-### 🚀 Features
-
-- Move HF API components to core integrations (#3403)
-
-<!-- generated by git-cliff -->