ddgs-haystack 1.0.0__tar.gz → 2.0.0__tar.gz

ddgs_haystack-2.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [integrations/ddgs-v1.1.0] - 2026-07-22
+
+### 🚀 Features
+
+- Expose per-run parameter overrides on DDGSWebSearch (#3634)
+
+
+## [integrations/ddgs-v1.0.0] - 2026-07-21
+
+### 🚀 Features
+
+- Add ddgs (Dux Distributed Global Search) web search integration (#3623)
+
+<!-- generated by git-cliff -->

{ddgs_haystack-1.0.0 → ddgs_haystack-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ddgs-haystack
-Version: 1.0.0
+Version: 2.0.0
 Summary: Haystack integration for ddgs
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/ddgs#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
@@ -12,14 +12,14 @@ Keywords: agent tool,ddgs,duckduckgo,haystack,metasearch,web search,websearch
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: ddgs>=9.14.3
 Requires-Dist: haystack-ai>=2.24.1
 Description-Content-Type: text/markdown
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://img.shields.io/pypi/v/ddgs-haystack.svg)](https://pypi.org/project/ddgs-haystack)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ddgs-haystack.svg)](https://pypi.org/project/ddgs-haystack)
 
+- [Integration page](https://haystack.deepset.ai/integrations/ddgs)
 - [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/ddgs/CHANGELOG.md)
 
 ---
@@ -36,5 +37,3 @@ Description-Content-Type: text/markdown
 ## Contributing
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
-
-`ddgs` requires no API key, so the integration tests run without any environment variables.

{ddgs_haystack-1.0.0 → ddgs_haystack-2.0.0}/README.md

@@ -3,6 +3,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/ddgs-haystack.svg)](https://pypi.org/project/ddgs-haystack)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ddgs-haystack.svg)](https://pypi.org/project/ddgs-haystack)
 
+- [Integration page](https://haystack.deepset.ai/integrations/ddgs)
 - [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/ddgs/CHANGELOG.md)
 
 ---
@@ -10,5 +11,3 @@
 ## Contributing
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
-
-`ddgs` requires no API key, so the integration tests run without any environment variables.

{ddgs_haystack-1.0.0 → ddgs_haystack-2.0.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "ddgs-haystack"
 dynamic = ["version"]
 description = "Haystack integration for ddgs"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "Apache-2.0"
 keywords = ["haystack", "web search", "websearch", "ddgs", "duckduckgo", "metasearch", "agent tool"]
 authors = [{ name = "deepset GmbH", email = "info@deepset.ai" }]
@@ -15,11 +15,11 @@ classifiers = [
   "License :: OSI Approved :: Apache Software License",
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
@@ -127,6 +127,7 @@ ignore = [
     "PLR0912",
     "PLR0913",
     "PLR0915",
+    "PLR0917",
     # Allow `Any` type - used legitimately for dynamic types and SDK boundaries
     "ANN401",
 ]

ddgs_haystack-2.0.0/src/haystack_integrations/components/websearch/ddgs/ddgs_websearch.py

@@ -0,0 +1,217 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from typing import Any
+
+from haystack import Document, component, logging
+
+from ddgs import DDGS
+
+logger = logging.getLogger(__name__)
+
+
+@component
+class DDGSWebSearch:
+    """
+    Searches the web with ddgs (Dux Distributed Global Search) and returns results as Haystack Documents.
+
+    [ddgs](https://github.com/deedy5/ddgs) is a free, **keyless** metasearch library that aggregates
+    results from multiple backends (DuckDuckGo, Google, Bing, Brave, Yahoo, Yandex, Mullvad, and more),
+    so no API key is required.
+
+    ### Usage example
+
+    ```python
+    from haystack_integrations.components.websearch.ddgs import DDGSWebSearch
+
+    websearch = DDGSWebSearch(top_k=5)
+    result = websearch.run(query="What is Haystack by deepset?")
+
+    documents = result["documents"]
+    links = result["links"]
+    ```
+    """
+
+    def __init__(
+        self,
+        top_k: int = 10,
+        backend: str = "auto",
+        region: str = "us-en",
+        safesearch: str = "moderate",
+        search_params: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Initialize the DDGSWebSearch component.
+
+        :param top_k:
+            Maximum number of results to return.
+        :param backend:
+            Comma-separated ddgs backends to query, or `"auto"` to let ddgs choose
+            (for example `"duckduckgo, google, brave"`). See the ddgs docs for the full list.
+        :param region:
+            Region/locale for the search, for example `"us-en"`, `"de-de"`, or `"wt-wt"` (no region).
+        :param safesearch:
+            Safe-search level: `"on"`, `"moderate"`, or `"off"`.
+        :param search_params:
+            Additional keyword arguments forwarded to `DDGS().text()` (for example `page` or
+            `timelimit`). Values here override `backend`, `region`, `safesearch`, and `top_k`
+            on conflict.
+        """
+        self.top_k = top_k
+        self.backend = backend
+        self.region = region
+        self.safesearch = safesearch
+        self.search_params = search_params or {}
+        self._client: DDGS | None = None
+
+    def warm_up(self) -> None:
+        """
+        Initialize the ddgs client.
+
+        Called automatically on first use. Can be called explicitly to avoid cold-start latency.
+        """
+        if self._client is None:
+            self._client = DDGS()
+
+    def _search(
+        self,
+        query: str,
+        top_k: int | None = None,
+        backend: str | None = None,
+        region: str | None = None,
+        safesearch: str | None = None,
+        search_params: dict[str, Any] | None = None,
+    ) -> dict[str, list[Document] | list[str]]:
+        """
+        Run the blocking ddgs search and normalise the results.
+
+        :param query:
+            Search query.
+        :returns:
+            A dictionary with `documents` and `links` keys.
+        """
+        if self._client is None:
+            self.warm_up()
+        if self._client is None:
+            msg = "DDGSWebSearch client failed to initialize."
+            raise RuntimeError(msg)
+
+        params: dict[str, Any] = {
+            "region": region if region is not None else self.region,
+            "safesearch": safesearch if safesearch is not None else self.safesearch,
+            "backend": backend if backend is not None else self.backend,
+            "max_results": top_k if top_k is not None else self.top_k,
+        }
+        params.update(search_params if search_params is not None else self.search_params)
+
+        results = self._client.text(query, **params)
+        documents, links = self._parse_response(results)
+
+        logger.debug(
+            "ddgs returned {number_documents} documents for the query '{query}'",
+            number_documents=len(documents),
+            query=query,
+        )
+        return {"documents": documents, "links": links}
+
+    @component.output_types(documents=list[Document], links=list[str])
+    def run(
+        self,
+        query: str,
+        top_k: int | None = None,
+        *,
+        backend: str | None = None,
+        region: str | None = None,
+        safesearch: str | None = None,
+        search_params: dict[str, Any] | None = None,
+    ) -> dict[str, list[Document] | list[str]]:
+        """
+        Use ddgs to search the web.
+
+        :param query:
+            Search query.
+        :param top_k:
+            Optional per-run override of the maximum number of results. If not provided, the
+            init-time `top_k` is used.
+        :param backend:
+            Optional per-run override of the ddgs backends. If not provided, the init-time
+            `backend` is used.
+        :param region:
+            Optional per-run override of the region/locale. If not provided, the init-time
+            `region` is used.
+        :param safesearch:
+            Optional per-run override of the safe-search level. If not provided, the init-time
+            `safesearch` is used.
+        :param search_params:
+            Optional per-run override of the extra `DDGS().text()` arguments. If provided, fully
+            replaces the init-time `search_params`.
+        :returns:
+            A dictionary with the following keys:
+            - `documents`: List of documents returned by the search backends.
+            - `links`: List of links returned by the search backends.
+        """
+        return self._search(query, top_k, backend, region, safesearch, search_params)
+
+    @component.output_types(documents=list[Document], links=list[str])
+    async def run_async(
+        self,
+        query: str,
+        top_k: int | None = None,
+        *,
+        backend: str | None = None,
+        region: str | None = None,
+        safesearch: str | None = None,
+        search_params: dict[str, Any] | None = None,
+    ) -> dict[str, list[Document] | list[str]]:
+        """
+        Asynchronously use ddgs to search the web.
+
+        ddgs has no native async API, so the blocking search runs in a worker thread. Same parameters
+        and return values as :meth:`run`.
+
+        :param query:
+            Search query.
+        :param top_k:
+            Optional per-run override of the maximum number of results. If not provided, the
+            init-time `top_k` is used.
+        :param backend:
+            Optional per-run override of the ddgs backends. If not provided, the init-time
+            `backend` is used.
+        :param region:
+            Optional per-run override of the region/locale. If not provided, the init-time
+            `region` is used.
+        :param safesearch:
+            Optional per-run override of the safe-search level. If not provided, the init-time
+            `safesearch` is used.
+        :param search_params:
+            Optional per-run override of the extra `DDGS().text()` arguments. If provided, fully
+            replaces the init-time `search_params`.
+        :returns:
+            A dictionary with `documents` and `links` keys.
+        """
+        return await asyncio.to_thread(self._search, query, top_k, backend, region, safesearch, search_params)
+
+    @staticmethod
+    def _parse_response(results: list[dict[str, Any]]) -> tuple[list[Document], list[str]]:
+        """
+        Convert ddgs text results into Haystack Documents and links.
+
+        :param results:
+            The list of result dictionaries returned by `DDGS().text()`.
+        :returns:
+            A tuple of `(documents, links)`.
+        """
+        documents: list[Document] = []
+        links: list[str] = []
+
+        for result in results:
+            url = result.get("href", "")
+            title = result.get("title", "")
+            content = result.get("body", "")
+            documents.append(Document(content=content, meta={"title": title, "url": url}))
+            if url:
+                links.append(url)
+
+        return documents, links

{ddgs_haystack-1.0.0 → ddgs_haystack-2.0.0}/tests/test_ddgs_websearch.py

@@ -109,6 +109,25 @@ class TestDDGSWebSearch:
         assert kwargs["region"] == "fr-fr"
         assert kwargs["timelimit"] == "d"
 
+    @patch(DDGS_PATH)
+    def test_run_overrides_params_at_runtime(self, mock_ddgs):
+        mock_ddgs.return_value.text.return_value = []
+        ws = DDGSWebSearch(top_k=10, backend="auto", region="us-en", safesearch="moderate")
+        ws.run(
+            query="q",
+            top_k=3,
+            backend="duckduckgo, brave",
+            region="de-de",
+            safesearch="off",
+            search_params={"timelimit": "w"},
+        )
+        _, kwargs = mock_ddgs.return_value.text.call_args
+        assert kwargs["max_results"] == 3
+        assert kwargs["backend"] == "duckduckgo, brave"
+        assert kwargs["region"] == "de-de"
+        assert kwargs["safesearch"] == "off"
+        assert kwargs["timelimit"] == "w"
+
     @pytest.mark.asyncio
     @patch(DDGS_PATH)
     async def test_run_async(self, mock_ddgs):
@@ -117,9 +136,19 @@ class TestDDGSWebSearch:
         assert len(result["documents"]) == 2
         assert result["links"] == ["https://haystack.deepset.ai", "https://www.deepset.ai"]
 
+    @pytest.mark.asyncio
+    @patch(DDGS_PATH)
+    async def test_run_async_overrides_params_at_runtime(self, mock_ddgs):
+        mock_ddgs.return_value.text.return_value = []
+        ws = DDGSWebSearch(top_k=10, region="us-en")
+        await ws.run_async(query="q", top_k=3, region="de-de")
+        _, kwargs = mock_ddgs.return_value.text.call_args
+        assert kwargs["max_results"] == 3
+        assert kwargs["region"] == "de-de"
+
     @pytest.mark.integration
     def test_web_search_integration(self):
-        result = DDGSWebSearch(top_k=3).run(query="What is the deepset Haystack framework?")
+        result = DDGSWebSearch(top_k=3).run(query="Python programming language")
         assert len(result["documents"]) > 0
         assert all(isinstance(doc, Document) for doc in result["documents"])
         assert all(doc.meta.get("url") for doc in result["documents"])
@@ -128,6 +157,6 @@ class TestDDGSWebSearch:
     @pytest.mark.asyncio
     @pytest.mark.integration
     async def test_web_search_async_integration(self):
-        result = await DDGSWebSearch(top_k=3).run_async(query="What is the deepset Haystack framework?")
+        result = await DDGSWebSearch(top_k=3).run_async(query="Python programming language")
         assert len(result["documents"]) > 0
         assert result["links"]

ddgs_haystack-1.0.0/src/haystack_integrations/components/websearch/ddgs/ddgs_websearch.py

@@ -1,161 +0,0 @@
-# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
-#
-# SPDX-License-Identifier: Apache-2.0
-
-import asyncio
-from typing import Any
-
-from haystack import Document, component, logging
-
-from ddgs import DDGS
-
-logger = logging.getLogger(__name__)
-
-
-@component
-class DDGSWebSearch:
-    """
-    Searches the web with ddgs (Dux Distributed Global Search) and returns results as Haystack Documents.
-
-    [ddgs](https://github.com/deedy5/ddgs) is a free, **keyless** metasearch library that aggregates
-    results from multiple backends (DuckDuckGo, Google, Bing, Brave, Yahoo, Yandex, Mullvad, and more),
-    so no API key is required.
-
-    ### Usage example
-
-    ```python
-    from haystack_integrations.components.websearch.ddgs import DDGSWebSearch
-
-    websearch = DDGSWebSearch(top_k=5)
-    result = websearch.run(query="What is Haystack by deepset?")
-
-    documents = result["documents"]
-    links = result["links"]
-    ```
-    """
-
-    def __init__(
-        self,
-        top_k: int = 10,
-        backend: str = "auto",
-        region: str = "us-en",
-        safesearch: str = "moderate",
-        search_params: dict[str, Any] | None = None,
-    ) -> None:
-        """
-        Initialize the DDGSWebSearch component.
-
-        :param top_k:
-            Maximum number of results to return.
-        :param backend:
-            Comma-separated ddgs backends to query, or ``"auto"`` to let ddgs choose
-            (for example ``"duckduckgo, google, brave"``). See the ddgs docs for the full list.
-        :param region:
-            Region/locale for the search, for example ``"us-en"``, ``"de-de"``, or ``"wt-wt"`` (no region).
-        :param safesearch:
-            Safe-search level: ``"on"``, ``"moderate"``, or ``"off"``.
-        :param search_params:
-            Additional keyword arguments forwarded to ``DDGS().text()`` (for example ``page`` or
-            ``timelimit``). Values here override ``backend``, ``region``, ``safesearch``, and ``top_k``
-            on conflict.
-        """
-        self.top_k = top_k
-        self.backend = backend
-        self.region = region
-        self.safesearch = safesearch
-        self.search_params = search_params or {}
-        self._client: DDGS | None = None
-
-    def warm_up(self) -> None:
-        """
-        Initialize the ddgs client.
-
-        Called automatically on first use. Can be called explicitly to avoid cold-start latency.
-        """
-        if self._client is None:
-            self._client = DDGS()
-
-    def _search(self, query: str) -> dict[str, list[Document] | list[str]]:
-        """
-        Run the blocking ddgs search and normalise the results.
-
-        :param query:
-            Search query.
-        :returns:
-            A dictionary with ``documents`` and ``links`` keys.
-        """
-        if self._client is None:
-            self.warm_up()
-        if self._client is None:
-            msg = "DDGSWebSearch client failed to initialize."
-            raise RuntimeError(msg)
-
-        params: dict[str, Any] = {
-            "region": self.region,
-            "safesearch": self.safesearch,
-            "backend": self.backend,
-            "max_results": self.top_k,
-        }
-        params.update(self.search_params)
-
-        results = self._client.text(query, **params)
-        documents, links = self._parse_response(results)
-
-        logger.debug(
-            "ddgs returned {number_documents} documents for the query '{query}'",
-            number_documents=len(documents),
-            query=query,
-        )
-        return {"documents": documents, "links": links}
-
-    @component.output_types(documents=list[Document], links=list[str])
-    def run(self, query: str) -> dict[str, list[Document] | list[str]]:
-        """
-        Use ddgs to search the web.
-
-        :param query:
-            Search query.
-        :returns:
-            A dictionary with the following keys:
-            - ``documents``: List of documents returned by the search backends.
-            - ``links``: List of links returned by the search backends.
-        """
-        return self._search(query)
-
-    @component.output_types(documents=list[Document], links=list[str])
-    async def run_async(self, query: str) -> dict[str, list[Document] | list[str]]:
-        """
-        Asynchronously use ddgs to search the web.
-
-        ddgs has no native async API, so the blocking search runs in a worker thread. Same parameters
-        and return values as :meth:`run`.
-
-        :param query:
-            Search query.
-        :returns:
-            A dictionary with ``documents`` and ``links`` keys.
-        """
-        return await asyncio.to_thread(self._search, query)
-
-    @staticmethod
-    def _parse_response(results: list[dict[str, Any]]) -> tuple[list[Document], list[str]]:
-        """
-        Convert ddgs text results into Haystack Documents and links.
-
-        :param results:
-            The list of result dictionaries returned by ``DDGS().text()``.
-        :returns:
-            A tuple of ``(documents, links)``.
-        """
-        documents: list[Document] = []
-        links: list[str] = []
-
-        for result in results:
-            url = result.get("href", "")
-            title = result.get("title", "")
-            content = result.get("body", "")
-            documents.append(Document(content=content, meta={"title": title, "url": url}))
-            if url:
-                links.append(url)
-
-        return documents, links