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

huggingface_api_haystack-0.2.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [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.1.0 → huggingface_api_haystack-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: huggingface-api-haystack
-Version: 0.1.0
+Version: 0.2.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.1.0 → huggingface_api_haystack-0.2.0}/pydoc/config_docusaurus.yml

@@ -3,6 +3,7 @@ loaders:
       - haystack_integrations.components.embedders.huggingface_api.document_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
     search_path: [../src]
 processors:
   - type: filter

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

@@ -70,7 +70,8 @@ unit-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 3
 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 \
 -p haystack_integrations.components.embedders.huggingface_api \
--p haystack_integrations.components.generators.huggingface_api {args}"""
+-p haystack_integrations.components.generators.huggingface_api \
+-p haystack_integrations.components.rankers.huggingface_api {args}"""
 
 [tool.mypy]
 install_types = true

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

@@ -147,6 +147,9 @@ class HuggingFaceAPIDocumentEmbedder:
         :param concurrency_limit:
             The maximum number of requests that should be allowed to run concurrently.
             This parameter is only used in the `run_async` method.
+        :raises ValueError:
+            If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+            or the `api_type` is unknown.
         """
         if isinstance(api_type, str):
             api_type = HFEmbeddingAPIType.from_str(api_type)
@@ -331,6 +334,10 @@ class HuggingFaceAPIDocumentEmbedder:
         :param documents:
             Documents to embed.
 
+        :raises TypeError:
+            If `documents` is not a list of Documents.
+        :raises ValueError:
+            If the embeddings returned by the API have an unexpected shape.
         :returns:
             A dictionary with the following keys:
             - `documents`: A list of documents with embeddings.
@@ -360,6 +367,10 @@ class HuggingFaceAPIDocumentEmbedder:
         :param documents:
             Documents to embed.
 
+        :raises TypeError:
+            If `documents` is not a list of Documents.
+        :raises ValueError:
+            If the embeddings returned by the API have an unexpected shape.
         :returns:
             A dictionary with the following keys:
             - `documents`: A list of documents with embeddings.

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

@@ -113,6 +113,9 @@ class HuggingFaceAPITextEmbedder:
             Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS`
             if the backend uses Text Embeddings Inference.
             If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
+        :raises ValueError:
+            If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
+            or the `api_type` is unknown.
         """
         if isinstance(api_type, str):
             api_type = HFEmbeddingAPIType.from_str(api_type)
@@ -213,6 +216,10 @@ class HuggingFaceAPITextEmbedder:
         :param text:
             Text to embed.
 
+        :raises TypeError:
+            If `text` is not a string.
+        :raises ValueError:
+            If the embedding returned by the API has an unexpected shape.
         :returns:
             A dictionary with the following keys:
             - `embedding`: The embedding of the input text.
@@ -241,6 +248,10 @@ class HuggingFaceAPITextEmbedder:
         :param text:
             Text to embed.
 
+        :raises TypeError:
+            If `text` is not a string.
+        :raises ValueError:
+            If the embedding returned by the API has an unexpected shape.
         :returns:
             A dictionary with the following keys:
             - `embedding`: The embedding of the input text.

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

@@ -392,6 +392,9 @@ class HuggingFaceAPIChatGenerator:
             The chosen model should support tool/function calling, according to the model card.
             Support for tools in the Hugging Face API and TGI is not yet fully refined and you may experience
             unexpected behavior.
+        :raises ValueError:
+            If the required `model` or `url` is missing from `api_params`, the `url` is invalid, the `api_type`
+            is unknown, `tools` and `streaming_callback` are used together, or duplicate tool names are provided.
         """
         if isinstance(api_type, str):
             api_type = HFGenerationAPIType.from_str(api_type)
@@ -510,6 +513,8 @@ class HuggingFaceAPIChatGenerator:
         :param streaming_callback:
             An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
             parameter set during component initialization.
+        :raises ValueError:
+            If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
         :returns: A dictionary with the following keys:
             - `replies`: A list containing the generated responses as ChatMessage objects.
         """
@@ -568,6 +573,8 @@ class HuggingFaceAPIChatGenerator:
         :param streaming_callback:
             An optional callable for handling streaming responses. If set, it will override the `streaming_callback`
             parameter set during component initialization.
+        :raises ValueError:
+            If `tools` and a streaming callback are used together, or if duplicate tool names are provided.
         :returns: A dictionary with the following keys:
             - `replies`: A list containing the generated responses as ChatMessage objects.
         """

huggingface_api_haystack-0.2.0/src/haystack_integrations/components/rankers/huggingface_api/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+from .ranker import HuggingFaceTEIRanker, TruncationDirection
+
+__all__ = ["HuggingFaceTEIRanker", "TruncationDirection"]

huggingface_api_haystack-0.2.0/src/haystack_integrations/components/rankers/huggingface_api/ranker.py

@@ -0,0 +1,297 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from dataclasses import replace
+from enum import Enum
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.utils import Secret
+from haystack.utils.misc import _deduplicate_documents
+from haystack.utils.requests_utils import async_request_with_retry, request_with_retry
+
+
+class TruncationDirection(str, Enum):
+    """
+    Defines the direction to truncate text when input length exceeds the model's limit.
+
+    Attributes:
+        LEFT: Truncate text from the left side (start of text).
+        RIGHT: Truncate text from the right side (end of text).
+    """
+
+    LEFT = "Left"
+    RIGHT = "Right"
+
+
+@component
+class HuggingFaceTEIRanker:
+    """
+    Ranks documents based on their semantic similarity to the query.
+
+    It can be used with a Text Embeddings Inference (TEI) API endpoint:
+    - [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference)
+    - [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints)
+
+    Usage example:
+    ```python
+    from haystack import Document
+    from haystack.utils import Secret
+
+    from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
+
+    reranker = HuggingFaceTEIRanker(
+        url="http://localhost:8080",
+        top_k=5,
+        timeout=30,
+        token=Secret.from_token("my_api_token")
+    )
+
+    docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")]
+
+    result = reranker.run(query="What is the capital of France?", documents=docs)
+
+    ranked_docs = result["documents"]
+    print(ranked_docs)
+    # >> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767),
+    # >>                Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]}
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        top_k: int = 10,
+        raw_scores: bool = False,
+        timeout: int | None = 30,
+        max_retries: int = 3,
+        retry_status_codes: list[int] | None = None,
+        token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
+    ) -> None:
+        """
+        Initializes the TEI reranker component.
+
+        :param url: Base URL of the TEI reranking service (for example, "https://api.example.com").
+        :param top_k: Maximum number of top documents to return.
+        :param raw_scores: If True, include raw relevance scores in the API payload.
+        :param timeout: Request timeout in seconds.
+        :param max_retries: Maximum number of retry attempts for failed requests.
+        :param retry_status_codes: List of HTTP status codes that will trigger a retry.
+            When None, HTTP 408, 418, 429 and 503 will be retried (default: None).
+        :param token: The Hugging Face token to use as HTTP bearer authorization. Not always required
+            depending on your TEI server configuration.
+            Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
+        """
+        self.url = url
+        self.top_k = top_k
+        self.timeout = timeout
+        self.token = token
+        self.max_retries = max_retries
+        self.retry_status_codes = retry_status_codes
+        self.raw_scores = raw_scores
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Serializes the component to a dictionary.
+
+        :returns:
+            Dictionary with serialized data.
+        """
+        return default_to_dict(
+            self,
+            url=self.url,
+            top_k=self.top_k,
+            timeout=self.timeout,
+            token=self.token,
+            max_retries=self.max_retries,
+            retry_status_codes=self.retry_status_codes,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceTEIRanker":
+        """
+        Deserializes the component from a dictionary.
+
+        :param data:
+            Dictionary to deserialize from.
+        :returns:
+            Deserialized component.
+        """
+        return default_from_dict(cls, data)
+
+    def _compose_response(
+        self, result: dict[str, str] | list[dict[str, Any]], top_k: int | None, documents: list[Document]
+    ) -> dict[str, list[Document]]:
+        """
+        Processes the API response into a structured format.
+
+        :param result: The raw response from the API.
+
+        :returns: A dictionary with the following keys:
+            - `documents`: A list of reranked documents.
+
+        :raises RuntimeError:
+            - If the API request fails.
+
+        :raises RuntimeError:
+            - If the API returns an error response.
+
+        :raises TypeError:
+            - If the API response is not in the expected list format.
+        """
+        if isinstance(result, dict) and "error" in result:
+            error_type = result.get("error_type", "UnknownError")
+            error_msg = result.get("error", "No additional information.")
+            msg = f"HuggingFaceTEIRanker API call failed ({error_type}): {error_msg}"
+            raise RuntimeError(msg)
+
+        # Ensure we have a list of score dicts
+        if not isinstance(result, list):
+            # Expected list or dict, but encountered an unknown response format.
+            error_msg = f"Expected a list of score dictionaries, but got `{type(result).__name__}`. "
+            error_msg += f"Response content: {result}"
+            msg = f"Unexpected response format from text-embeddings-inference rerank API: {error_msg}"
+            raise TypeError(msg)
+
+        # Determine number of docs to return
+        final_k = min(top_k or self.top_k, len(result))
+
+        # Select and return the top_k documents
+        ranked_docs = []
+        for item in result[:final_k]:
+            index: int = item["index"]
+            ranked_docs.append(replace(documents[index], score=item["score"]))
+        return {"documents": ranked_docs}
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        query: str,
+        documents: list[Document],
+        top_k: int | None = None,
+        truncation_direction: TruncationDirection | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Reranks the provided documents by relevance to the query using the TEI API.
+
+        Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+        if a score is present.
+
+        :param query: The user query string to guide reranking.
+        :param documents: List of `Document` objects to rerank.
+        :param top_k: Optional override for the maximum number of documents to return.
+        :param truncation_direction: If set, enables text truncation in the specified direction.
+
+        :returns: A dictionary with the following keys:
+            - `documents`: A list of reranked documents.
+
+        :raises RuntimeError:
+            - If the API request fails.
+
+        :raises RuntimeError:
+            - If the API returns an error response.
+
+        :raises TypeError:
+            - If the API response is not in the expected list format.
+        """
+        # Return empty if no documents provided
+        if not documents:
+            return {"documents": []}
+
+        # Prepare the payload
+        deduplicated_documents = _deduplicate_documents(documents)
+        texts = [doc.content for doc in deduplicated_documents]
+        payload: dict[str, Any] = {"query": query, "texts": texts, "raw_scores": self.raw_scores}
+        if truncation_direction:
+            payload.update({"truncate": True, "truncation_direction": truncation_direction.value})
+
+        headers = {}
+        if self.token and self.token.resolve_value():
+            headers["Authorization"] = f"Bearer {self.token.resolve_value()}"
+
+        # Call the external service with retry
+        try:
+            response = request_with_retry(
+                method="POST",
+                url=urljoin(self.url, "/rerank"),
+                json=payload,
+                timeout=self.timeout,
+                headers=headers,
+                attempts=self.max_retries,
+                status_codes_to_retry=self.retry_status_codes,
+            )
+        except httpx.HTTPStatusError as e:
+            msg = f"HuggingFaceTEIRanker API call failed. Error: {e}, Response: {e.response.text}"
+            raise RuntimeError(msg) from e
+
+        result: dict[str, str] | list[dict[str, Any]] = response.json()
+
+        return self._compose_response(result, top_k, deduplicated_documents)
+
+    @component.output_types(documents=list[Document])
+    async def run_async(
+        self,
+        query: str,
+        documents: list[Document],
+        top_k: int | None = None,
+        truncation_direction: TruncationDirection | None = None,
+    ) -> dict[str, list[Document]]:
+        """
+        Asynchronously reranks the provided documents by relevance to the query using the TEI API.
+
+        Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
+        if a score is present.
+
+        :param query: The user query string to guide reranking.
+        :param documents: List of `Document` objects to rerank.
+        :param top_k: Optional override for the maximum number of documents to return.
+        :param truncation_direction: If set, enables text truncation in the specified direction.
+
+        :returns: A dictionary with the following keys:
+            - `documents`: A list of reranked documents.
+
+        :raises httpx.RequestError:
+            - If the API request fails.
+        :raises RuntimeError:
+            - If the API returns an error response.
+
+        :raises TypeError:
+            - If the API response is not in the expected list format.
+        """
+        # Return empty if no documents provided
+        if not documents:
+            return {"documents": []}
+
+        # Prepare the payload
+        deduplicated_documents = _deduplicate_documents(documents)
+        texts = [doc.content for doc in deduplicated_documents]
+        payload: dict[str, Any] = {"query": query, "texts": texts, "raw_scores": self.raw_scores}
+        if truncation_direction:
+            payload.update({"truncate": True, "truncation_direction": truncation_direction.value})
+
+        headers = {}
+        if self.token and self.token.resolve_value():
+            headers["Authorization"] = f"Bearer {self.token.resolve_value()}"
+
+        # Call the external service with retry
+        try:
+            response = await async_request_with_retry(
+                method="POST",
+                url=urljoin(self.url, "/rerank"),
+                json=payload,
+                timeout=self.timeout,
+                headers=headers,
+                attempts=self.max_retries,
+                status_codes_to_retry=self.retry_status_codes,
+            )
+        except httpx.HTTPStatusError as e:
+            msg = f"HuggingFaceTEIRanker API call failed. Error: {e}, Response: {e.response.text}"
+            raise RuntimeError(msg) from e
+
+        result: dict[str, str] | list[dict[str, Any]] = response.json()
+
+        return self._compose_response(result, top_k, deduplicated_documents)

huggingface_api_haystack-0.2.0/tests/conftest.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture()
+def test_files_path():
+    return Path(__file__).parent / "test_files"
+
+
+@pytest.fixture()
+def del_hf_env_vars(monkeypatch):
+    """
+    Delete Hugging Face environment variables for tests.
+
+    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
+    and empty environment variables might be set instead of being removed.
+
+    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)

huggingface_api_haystack-0.2.0/tests/test_ranker.py

@@ -0,0 +1,351 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+from haystack import Document
+from haystack.utils import Secret
+
+from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker, TruncationDirection
+
+
+class TestHuggingFaceTEIRanker:
+    def test_init(self, del_hf_env_vars):
+        """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.max_retries == 3
+        assert ranker.retry_status_codes is None
+
+        # Custom parameters
+        token = Secret.from_token("my_api_token")
+        ranker = HuggingFaceTEIRanker(
+            url="https://api.my-tei-service.com",
+            top_k=5,
+            timeout=60,
+            token=token,
+            max_retries=5,
+            retry_status_codes=[500, 502, 503],
+        )
+        assert ranker.url == "https://api.my-tei-service.com"
+        assert ranker.top_k == 5
+        assert ranker.timeout == 60
+        assert ranker.token == token
+        assert ranker.max_retries == 5
+        assert ranker.retry_status_codes == [500, 502, 503]
+
+    def test_to_dict(self, del_hf_env_vars):
+        """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]
+        )
+        data = component.to_dict()
+
+        assert data["type"] == "haystack_integrations.components.rankers.huggingface_api.ranker.HuggingFaceTEIRanker"
+        assert data["init_parameters"]["url"] == "https://api.my-tei-service.com"
+        assert data["init_parameters"]["top_k"] == 5
+        assert data["init_parameters"]["timeout"] == 30
+        assert data["init_parameters"]["token"] == {
+            "env_vars": ["HF_API_TOKEN", "HF_TOKEN"],
+            "strict": False,
+            "type": "env_var",
+        }
+        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):
+        """Test deserialization from dict with environment variable token"""
+        data = {
+            "type": "haystack_integrations.components.rankers.huggingface_api.ranker.HuggingFaceTEIRanker",
+            "init_parameters": {
+                "url": "https://api.my-tei-service.com",
+                "top_k": 5,
+                "timeout": 30,
+                "token": {"type": "env_var", "env_vars": ["HF_API_TOKEN", "HF_TOKEN"], "strict": False},
+                "max_retries": 4,
+                "retry_status_codes": [500, 502],
+            },
+        }
+
+        component = HuggingFaceTEIRanker.from_dict(data)
+
+        assert component.url == "https://api.my-tei-service.com"
+        assert component.top_k == 5
+        assert component.timeout == 30
+        assert component.max_retries == 4
+        assert component.retry_status_codes == [500, 502]
+
+    def test_empty_documents(self, del_hf_env_vars):
+        """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": []}
+
+    @patch("haystack_integrations.components.rankers.huggingface_api.ranker.request_with_retry")
+    def test_run_with_mock(self, mock_request, del_hf_env_vars):
+        """Test run method with mocked API response"""
+        # Setup mock response
+        mock_response = MagicMock(spec=httpx.Response)
+        mock_response.json.return_value = [
+            {"index": 2, "score": 0.95},
+            {"index": 1, "score": 0.85},
+            {"index": 0, "score": 0.75},
+        ]
+        mock_request.return_value = mock_response
+
+        # Create ranker and test documents
+        token = Secret.from_token("test_token")
+        ranker = HuggingFaceTEIRanker(
+            url="https://api.my-tei-service.com",
+            top_k=3,
+            timeout=30,
+            token=token,
+            max_retries=4,
+            retry_status_codes=[500, 502],
+        )
+
+        docs = [Document(content="Document A"), Document(content="Document B"), Document(content="Document C")]
+
+        # Run the ranker
+        result = ranker.run(query="test query", documents=docs)
+
+        # Check that request_with_retry was called with correct parameters
+        mock_request.assert_called_once_with(
+            method="POST",
+            url="https://api.my-tei-service.com/rerank",
+            json={"query": "test query", "texts": ["Document A", "Document B", "Document C"], "raw_scores": False},
+            timeout=30,
+            headers={"Authorization": "Bearer test_token"},
+            attempts=4,
+            status_codes_to_retry=[500, 502],
+        )
+
+        # Check that documents are ranked correctly
+        assert len(result["documents"]) == 3
+        assert result["documents"][0].content == "Document C"
+        assert result["documents"][0].score == 0.95
+        assert result["documents"][1].content == "Document B"
+        assert result["documents"][1].score == 0.85
+        assert result["documents"][2].content == "Document A"
+        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):
+        """Test run method with truncation direction parameter"""
+        # Setup mock response
+        mock_response = MagicMock(spec=httpx.Response)
+        mock_response.json.return_value = [{"index": 0, "score": 0.95}]
+        mock_request.return_value = mock_response
+
+        # Create ranker and test documents
+        token = Secret.from_token("test_token")
+        ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com", token=token)
+        docs = [Document(content="Document A")]
+
+        # Run the ranker with truncation direction
+        ranker.run(query="test query", documents=docs, truncation_direction=TruncationDirection.LEFT)
+
+        # Check that request includes truncation parameters
+        mock_request.assert_called_once_with(
+            method="POST",
+            url="https://api.my-tei-service.com/rerank",
+            json={
+                "query": "test query",
+                "texts": ["Document A"],
+                "raw_scores": False,
+                "truncate": True,
+                "truncation_direction": "Left",
+            },
+            timeout=30,
+            headers={"Authorization": "Bearer test_token"},
+            attempts=3,
+            status_codes_to_retry=None,
+        )
+
+    @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):
+        """Test run method with custom top_k parameter"""
+        # Setup mock response with 5 documents
+        mock_response = MagicMock(spec=httpx.Response)
+        mock_response.json.return_value = [
+            {"index": 4, "score": 0.95},
+            {"index": 3, "score": 0.90},
+            {"index": 2, "score": 0.85},
+            {"index": 1, "score": 0.80},
+            {"index": 0, "score": 0.75},
+        ]
+        mock_request.return_value = mock_response
+
+        # Create ranker with top_k=3
+        ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com", top_k=3)
+
+        # Create 5 test documents
+        docs = [Document(content=f"Document {i}") for i in range(5)]
+
+        # Run the ranker
+        result = ranker.run(query="test query", documents=docs)
+
+        # Check that only top 3 documents are returned
+        assert len(result["documents"]) == 3
+        assert result["documents"][0].content == "Document 4"
+        assert result["documents"][1].content == "Document 3"
+        assert result["documents"][2].content == "Document 2"
+
+        # Test with run-time top_k override
+        result = ranker.run(query="test query", documents=docs, top_k=2)
+
+        # Check that only top 2 documents are returned
+        assert len(result["documents"]) == 2
+        assert result["documents"][0].content == "Document 4"
+        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):
+        """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}]
+        mock_request.return_value = mock_response
+
+        ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
+        # Document with duplicate id and lower score should be dropped
+        docs = [
+            Document(id="duplicate", content="keep me", score=0.9),
+            Document(id="duplicate", content="drop me", score=0.1),
+            Document(id="unique", content="unique"),
+        ]
+
+        result = ranker.run(query="test query", documents=docs)
+
+        mock_request.assert_called_once_with(
+            method="POST",
+            url="https://api.my-tei-service.com/rerank",
+            json={"query": "test query", "texts": ["keep me", "unique"], "raw_scores": False},
+            timeout=30,
+            headers={},
+            attempts=3,
+            status_codes_to_retry=None,
+        )
+        assert len(result["documents"]) == 2
+        assert result["documents"][0].content == "unique"
+        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):
+        """Test error handling in the ranker"""
+        # Setup mock response with error
+        mock_response = MagicMock(spec=httpx.Response)
+        mock_response.json.return_value = {"error": "Some error occurred", "error_type": "TestError"}
+        mock_request.return_value = mock_response
+
+        # Create ranker and test documents
+        ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
+        docs = [Document(content="Document A")]
+
+        # Test that RuntimeError is raised with the correct message
+        with pytest.raises(
+            RuntimeError, match=r"HuggingFaceTEIRanker API call failed \(TestError\): Some error occurred"
+        ):
+            ranker.run(query="test query", documents=docs)
+
+        # Test unexpected response format
+        mock_response.json.return_value = {"unexpected": "format"}
+        with pytest.raises(TypeError, match="Unexpected response format from text-embeddings-inference rerank API"):
+            ranker.run(query="test query", documents=docs)
+
+    @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):
+        """Test run_async method with mocked API response"""
+        # Setup mock response
+        mock_response = MagicMock(spec=httpx.Response)
+        mock_response.json.return_value = [
+            {"index": 2, "score": 0.95},
+            {"index": 1, "score": 0.85},
+            {"index": 0, "score": 0.75},
+        ]
+        mock_request.return_value = mock_response
+
+        # Create ranker and test documents
+        token = Secret.from_token("test_token")
+        ranker = HuggingFaceTEIRanker(
+            url="https://api.my-tei-service.com",
+            top_k=3,
+            timeout=30,
+            token=token,
+            max_retries=4,
+            retry_status_codes=[500, 502],
+        )
+
+        docs = [Document(content="Document A"), Document(content="Document B"), Document(content="Document C")]
+
+        # Run the ranker asynchronously
+        result = await ranker.run_async(query="test query", documents=docs)
+
+        # Check that async_request_with_retry was called with correct parameters
+        mock_request.assert_called_once_with(
+            method="POST",
+            url="https://api.my-tei-service.com/rerank",
+            json={"query": "test query", "texts": ["Document A", "Document B", "Document C"], "raw_scores": False},
+            timeout=30,
+            headers={"Authorization": "Bearer test_token"},
+            attempts=4,
+            status_codes_to_retry=[500, 502],
+        )
+
+        # Check that documents are ranked correctly
+        assert len(result["documents"]) == 3
+        assert result["documents"][0].content == "Document C"
+        assert result["documents"][0].score == 0.95
+        assert result["documents"][1].content == "Document B"
+        assert result["documents"][1].score == 0.85
+        assert result["documents"][2].content == "Document A"
+        assert result["documents"][2].score == 0.75
+
+    @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):
+        """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}]
+        mock_request.return_value = mock_response
+
+        ranker = HuggingFaceTEIRanker(url="https://api.my-tei-service.com")
+        # Document with duplicate id and lower score should be dropped
+        docs = [
+            Document(id="duplicate", content="keep me", score=0.9),
+            Document(id="duplicate", content="drop me", score=0.1),
+            Document(id="unique", content="unique"),
+        ]
+
+        result = await ranker.run_async(query="test query", documents=docs)
+
+        mock_request.assert_called_once_with(
+            method="POST",
+            url="https://api.my-tei-service.com/rerank",
+            json={"query": "test query", "texts": ["keep me", "unique"], "raw_scores": False},
+            timeout=30,
+            headers={},
+            attempts=3,
+            status_codes_to_retry=None,
+        )
+        assert len(result["documents"]) == 2
+        assert result["documents"][0].content == "unique"
+        assert result["documents"][1].content == "keep me"
+
+    @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):
+        """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=[])
+
+        # Check that no API call was made
+        mock_request.assert_not_called()
+        assert result == {"documents": []}

huggingface_api_haystack-0.1.0/tests/conftest.py

@@ -1,12 +0,0 @@
-# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from pathlib import Path
-
-import pytest
-
-
-@pytest.fixture()
-def test_files_path():
-    return Path(__file__).parent / "test_files"