nvidia-haystack 1.2.0__tar.gz → 1.4.0__tar.gz

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [integrations/nvidia-v1.3.0] - 2026-08-04
+
+### 🐛 Bug Fixes
+
+- Support Haystack 3.0's lazy OpenAI client initialization in OpenAI-inheriting generators (#3536)
+- Fix new issues raised by ruff 0.16.0 (#3670)
+- Fix Nvidia NimBackend type error (#3719)
+- NvidiaRanker missing /ranking path for local NIM deployments (#3483)
+
+### 🧪 Testing
+
+- Trust test modules under Haystack 3.0's deserialization allowlist (#3537)
+
+### 🧹 Chores
+
+- Improve consistency of integrations folder structure (#3430)
+
+
+## [integrations/nvidia-v1.2.0] - 2026-06-05
+
+### 🧹 Chores
+
+- NVIDIA - deprecate generator (#3391)
+
+
 ## [integrations/nvidia-v1.1.1] - 2026-04-14
 
 ### 🐛 Bug Fixes

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-haystack
-Version: 1.2.0
+Version: 1.4.0
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/nvidia

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/pyproject.toml

@@ -133,6 +133,7 @@ ignore = [
   "PLR0912",
   "PLR0913",
   "PLR0915",
+  "PLR0917",
   # Misc
   "B008",
   "S101",

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/src/haystack_integrations/components/rankers/nvidia/ranker.py

@@ -3,18 +3,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import os
-import warnings
 from dataclasses import replace
 from typing import Any
 
-from haystack import Document, component, default_from_dict, default_to_dict, logging
+from haystack import Document, component, default_from_dict, default_to_dict
 from haystack.utils import Secret, deserialize_secrets_inplace
 
 from haystack_integrations.components.rankers.nvidia.truncate import RankerTruncateMode
 from haystack_integrations.utils.nvidia import DEFAULT_API_URL, Client, NimBackend, is_hosted, url_validation
 
-logger = logging.getLogger(__name__)
-
 
 @component
 class NvidiaRanker:
@@ -84,6 +81,8 @@ class NvidiaRanker:
         :param timeout:
             Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable
             or set to 60 by default.
+
+        :raises ValueError: If `top_k` is not > 0.
         """
         if model is not None and not isinstance(model, str):
             msg = "Ranker expects the `model` parameter to be a string."
@@ -96,6 +95,9 @@ class NvidiaRanker:
         if not isinstance(top_k, int):
             msg = "Ranker expects the `top_k` parameter to be an integer."
             raise TypeError(msg)
+        if top_k <= 0:
+            msg = f"top_k must be > 0, but got {top_k}"
+            raise ValueError(msg)
 
         # todo: detect default in non-hosted case (when api_url is provided)
         self.truncate = truncate
@@ -202,6 +204,7 @@ class NvidiaRanker:
         :param top_k: The number of documents to return.
 
         :raises TypeError: If the arguments are of the wrong type.
+        :raises ValueError: If `top_k` is not > 0.
 
         :returns: A dictionary containing the ranked documents.
         """
@@ -224,11 +227,10 @@ class NvidiaRanker:
         if len(documents) == 0:
             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)
         top_k = top_k if top_k is not None else self.top_k
-        if top_k < 1:
-            logger.warning("top_k should be at least 1, returning nothing")
-            warnings.warn("top_k should be at least 1, returning nothing", stacklevel=2)
-            return {"documents": []}
 
         assert self.backend is not None
 

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/src/haystack_integrations/utils/nvidia/nim_backend.py

@@ -42,6 +42,11 @@ class NimBackend:
         self.session.headers.update(headers)
 
         self.api_url = api_url
+        # Hosted ranking models are assigned a per-model endpoint that already includes the
+        # full path (e.g. ".../nv-rerankqa-mistral-4b-v3/reranking"), unlike other hosted
+        # endpoints which only override the host. `rank()` uses this to decide whether it
+        # still needs to append the `/ranking` path itself.
+        self._has_custom_ranking_endpoint = False
         if isinstance(client, str):
             client = Client.from_str(client)
         validated_model: Model | None = None
@@ -64,6 +69,8 @@ class NimBackend:
                 # we override the endpoint to use the custom endpoint
                 self.api_url = validated_model.endpoint
                 self.model_type = validated_model.model_type
+                if validated_model.model_type == "ranking":
+                    self._has_custom_ranking_endpoint = True
 
         self.model = validated_model.id if validated_model else model
         self.model_kwargs = model_kwargs or {}
@@ -89,8 +96,13 @@ class NimBackend:
             )
             res.raise_for_status()
         except requests.HTTPError as e:
-            logger.error("Error when calling NIM embedding endpoint: Error - {error}", error=e.response.text)
-            msg = f"Failed to query embedding endpoint: Error - {e.response.text}"
+            response_text = e.response.text.strip() if e.response is not None else ""
+            error_details = f": {response_text}" if response_text else ""
+            logger.error(
+                "Error when calling NIM embedding endpoint{error}",
+                error=error_details,
+            )
+            msg = f"Failed to query embedding endpoint{error_details}"
             raise ValueError(msg) from e
 
         data = res.json()
@@ -123,8 +135,13 @@ class NimBackend:
             )
             res.raise_for_status()
         except requests.HTTPError as e:
-            logger.error("Error when calling NIM chat completion endpoint: Error - {error}", error=e.response.text)
-            msg = f"Failed to query chat completion endpoint: Error - {e.response.text}"
+            response_text = e.response.text.strip() if e.response is not None else ""
+            error_details = f": {response_text}" if response_text else ""
+            logger.error(
+                "Error when calling NIM chat completion endpoint{error}",
+                error=error_details,
+            )
+            msg = f"Failed to query chat completion endpoint{error_details}"
             raise ValueError(msg) from e
 
         completions = res.json()
@@ -179,7 +196,10 @@ class NimBackend:
 
     def rank(self, query_text: str, document_texts: list[str]) -> list[dict[str, Any]]:
         """Rank documents by relevance to a query via the NIM API."""
-        url = self.api_url
+        # Hosted ranking models already carry the full path in their custom endpoint;
+        # everything else (local NIM containers, non-ranking-table models) needs the
+        # `/ranking` suffix appended explicitly, like the other endpoints below do.
+        url = self.api_url if self._has_custom_ranking_endpoint else f"{self.api_url}/ranking"
 
         try:
             res = self.session.post(
@@ -194,8 +214,13 @@ class NimBackend:
             )
             res.raise_for_status()
         except requests.HTTPError as e:
-            logger.error("Error when calling NIM ranking endpoint: Error - {error}", error=e.response.text)
-            msg = f"Failed to rank endpoint: Error - {e.response.text}"
+            response_text = e.response.text.strip() if e.response is not None else ""
+            error_details = f": {response_text}" if response_text else ""
+            logger.error(
+                "Error when calling NIM ranking endpoint{error}",
+                error=error_details,
+            )
+            msg = f"Failed to query ranking endpoint{error_details}"
             raise ValueError(msg) from e
 
         data = res.json()

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/tests/conftest.py

@@ -47,3 +47,13 @@ def mock_local_models(requests_mock: Mocker) -> None:
             ]
         },
     )
+
+
+@pytest.fixture(autouse=True)
+def allow_deserialization_of_test_modules(monkeypatch):
+    """
+    haystack-ai >= 3.0 refuses to deserialize classes and callables from modules outside its
+    trusted-module allowlist. Tools and callbacks defined in the test modules live outside that
+    allowlist, so trust them explicitly; haystack-ai 2.x ignores this environment variable.
+    """
+    monkeypatch.setenv("HAYSTACK_DESERIALIZATION_ALLOWLIST", "tests,test_*")

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/tests/test_nim_backend.py

@@ -289,6 +289,28 @@ class TestNimBackend:
                 timeout=60.0,
             )
 
+    def test_rank_local_nim_appends_ranking_path(self, monkeypatch):
+        # Local/self-hosted NIM deployments have no model-specific endpoint override,
+        # so `rank()` must append the `/ranking` path itself instead of relying on
+        # `validate_hosted_model` having already baked it into `self.api_url`.
+        with patch("requests.sessions.Session.post", side_effect=mock_rank_post_response) as mock_post:
+            monkeypatch.setenv("NVIDIA_API_KEY", "fake-api-key")
+            backend = NimBackend(model="custom-rerank-model", api_url="http://localhost:8000/v1", client="NvidiaRanker")
+            query_text = "query"
+            document_texts = ["text1", "text2"]
+            backend.rank(query_text=query_text, document_texts=document_texts)
+
+            expected_url = "http://localhost:8000/v1/ranking"
+            mock_post.assert_called_once_with(
+                expected_url,
+                json={
+                    "model": "custom-rerank-model",
+                    "query": {"text": query_text},
+                    "passages": [{"text": text} for text in document_texts],
+                },
+                timeout=60.0,
+            )
+
     def test_rank_raises_on_http_error(self, monkeypatch):
         error_response = requests.Response()
         error_response.status_code = 500
@@ -298,7 +320,7 @@ class TestNimBackend:
             backend = NimBackend(
                 model="nvidia/llama-3.2-nv-rerankqa-1b-v2", api_url=DEFAULT_API_URL, client="NvidiaRanker"
             )
-            with pytest.raises(ValueError, match="Failed to rank endpoint"):
+            with pytest.raises(ValueError, match="Failed to query ranking endpoint"):
                 backend.rank(query_text="q", document_texts=["a"])
 
     def test_rank_raises_when_rankings_missing(self, monkeypatch):

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/tests/test_nvidia_chat_generator.py

@@ -119,15 +119,23 @@ class TestNvidiaChatGenerator:
     def test_init_default(self, monkeypatch):
         monkeypatch.setenv("NVIDIA_API_KEY", "test-api-key")
         component = NvidiaChatGenerator()
-        assert component.client.api_key == "test-api-key"
+        assert component.api_key.resolve_value() == "test-api-key"
         assert component.model == "meta/llama-3.1-8b-instruct"
         assert component.streaming_callback is None
         assert not component.generation_kwargs
 
+    def test_warm_up(self, monkeypatch):
+        monkeypatch.setenv("NVIDIA_API_KEY", "test-api-key")
+        component = NvidiaChatGenerator()
+        component.warm_up()  # with haystack-ai >= 3.0 the client is created during warm-up
+        assert component.client.api_key == "test-api-key"
+
     def test_init_fail_wo_api_key(self, monkeypatch):
         monkeypatch.delenv("NVIDIA_API_KEY", raising=False)
         with pytest.raises(ValueError, match=r"None of the .* environment variables are set"):
-            NvidiaChatGenerator()
+            # haystack-ai 2.x raises at init; haystack-ai >= 3.0 raises when the client is created in warm_up
+            component = NvidiaChatGenerator()
+            component.warm_up()
 
     def test_init_with_parameters(self):
         component = NvidiaChatGenerator(
@@ -137,7 +145,7 @@ class TestNvidiaChatGenerator:
             api_base_url="test-base-url",
             generation_kwargs={"max_tokens": 10, "some_test_param": "test-params"},
         )
-        assert component.client.api_key == "test-api-key"
+        assert component.api_key.resolve_value() == "test-api-key"
         assert component.model == "meta/llama-3.1-8b-instruct"
         assert component.streaming_callback is print_streaming_chunk
         assert component.generation_kwargs == {"max_tokens": 10, "some_test_param": "test-params"}
@@ -463,13 +471,16 @@ class TestNvidiaChatGenerator:
 
 
 class TestNvidiaChatGeneratorAsync:
-    def test_init_default_async(self, monkeypatch):
+    @pytest.mark.asyncio
+    async def test_warm_up_async(self, monkeypatch):
         monkeypatch.setenv("NVIDIA_API_KEY", "test-api-key")
         component = NvidiaChatGenerator()
+        if hasattr(component, "warm_up_async"):
+            # haystack-ai >= 3.0 creates the async client during async warm-up
+            await component.warm_up_async()
 
         assert isinstance(component.async_client, AsyncOpenAI)
         assert component.async_client.api_key == "test-api-key"
-        assert not component.generation_kwargs
 
     @pytest.mark.asyncio
     async def test_run_async(self, chat_messages, mock_async_chat_completion, monkeypatch):  # noqa: ARG002

{nvidia_haystack-1.2.0 → nvidia_haystack-1.4.0}/tests/test_ranker.py

@@ -120,6 +120,36 @@ class TestNvidiaRanker:
         assert response[0].content == documents[1].content
         assert response[0].score == 4.2
 
+    @pytest.mark.parametrize(
+        ("model", "api_url", "expected_url"),
+        [
+            (
+                _DEFAULT_MODEL,
+                None,
+                "https://ai.api.nvidia.com/v1/retrieval/nvidia/nv-rerankqa-mistral-4b-v3/reranking",
+            ),
+            ("custom-rerank-model", "http://localhost:8000/v1", "http://localhost:8000/v1/ranking"),
+        ],
+        ids=["hosted", "local-nim"],
+    )
+    def test_ranking_url(self, requests_mock, monkeypatch, model, api_url, expected_url) -> None:
+        # Hosted models are assigned a per-model endpoint that already includes the full path,
+        # while local/self-hosted NIM deployments get no such override and need `/ranking`
+        # appended to the base URL. Registering only the exact expected URL means any other
+        # URL raises NoMockAddress instead of silently passing.
+        monkeypatch.setenv("NVIDIA_API_KEY", "fake-api-key")
+        requests_mock.post(expected_url, json={"rankings": [{"index": 0, "logit": 1.0}]}, complete_qs=True)
+
+        api_url_param = {} if api_url is None else {"api_url": api_url}
+        client = NvidiaRanker(model=model, top_k=1, **api_url_param)
+        client.warm_up()
+
+        response = client.run(query="q", documents=[Document(content="doc")])["documents"]
+
+        assert len(response) == 1
+        assert requests_mock.last_request is not None
+        assert requests_mock.last_request.url == expected_url
+
     @pytest.mark.parametrize("truncate", [True, False, 1, 0, 1.0, "START", "BOGUS"])
     def test_truncate_invalid(self, truncate: Any) -> None:
         with pytest.raises(ValueError) as e:
@@ -181,6 +211,7 @@ class TestNvidiaRanker:
         client = NvidiaRanker(
             model=os.environ["NVIDIA_NIM_RANKER_MODEL"],
             api_url=os.environ["NVIDIA_NIM_RANKER_ENDPOINT_URL"],
+            api_key=None,
             top_k=2,
         )
         client.warm_up()
@@ -190,20 +221,27 @@ class TestNvidiaRanker:
         assert len(response) == 2
         assert {response[0].content, response[1].content} == {documents[0].content, documents[1].content}
 
-    def test_top_k_warn(self, monkeypatch) -> None:
+    @pytest.mark.parametrize("top_k", [0, -1])
+    def test_top_k_init_invalid(self, monkeypatch, top_k: int) -> None:
         monkeypatch.setenv("NVIDIA_API_KEY", "fake-api-key")
+        with pytest.raises(ValueError, match=rf"top_k must be > 0, but got {top_k}"):
+            NvidiaRanker(top_k=top_k)
 
-        client = NvidiaRanker(top_k=0)
+    @pytest.mark.parametrize("top_k", [0, -1])
+    def test_top_k_run_invalid(self, monkeypatch, top_k: int) -> None:
+        monkeypatch.setenv("NVIDIA_API_KEY", "fake-api-key")
+        client = NvidiaRanker()
         client.warm_up()
-        with pytest.warns(UserWarning) as record0:
-            client.run("query", [Document(content="doc")])
-        assert "top_k should be at least 1" in str(record0[0].message)
+        with pytest.raises(ValueError, match=rf"top_k must be > 0, but got {top_k}"):
+            client.run("query", [Document(content="doc")], top_k=top_k)
 
-        client = NvidiaRanker(top_k=1)
+    def test_top_k_zero_at_run_does_not_fall_back_to_instance_top_k(self, monkeypatch) -> None:
+        # a runtime top_k=0 must raise, not silently fall back to the instance top_k
+        monkeypatch.setenv("NVIDIA_API_KEY", "fake-api-key")
+        client = NvidiaRanker(top_k=5)
         client.warm_up()
-        with pytest.warns(UserWarning) as record1:
+        with pytest.raises(ValueError, match=r"top_k must be > 0, but got 0"):
             client.run("query", [Document(content="doc")], top_k=0)
-        assert "top_k should be at least 1" in str(record1[0].message)
 
     def test_model_typeerror(self) -> None:
         with pytest.raises(TypeError) as e: