keenable-haystack 0.1.0__tar.gz

keenable_haystack-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+dist/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyc
+tests/.red_team_scratch/
+red_team_report.*

keenable_haystack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keenable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keenable_haystack-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: keenable-haystack
+Version: 0.1.0
+Summary: Keenable web-search and page-fetch components for Haystack. Keyless by default.
+Project-URL: Homepage, https://keenable.ai
+Project-URL: Documentation, https://docs.keenable.ai
+Project-URL: Repository, https://github.com/keenableai/keenable-haystack
+Author-email: Keenable <hello@keenable.ai>
+Maintainer: keenableai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,fetch,haystack,haystack-ai,keenable,rag,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: haystack-ai>=2.0.0
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# keenable-haystack
+
+[Keenable](https://keenable.ai) web search + page fetch for
+[Haystack](https://haystack.deepset.ai) 2.x, as two components:
+
+- **`KeenableWebSearch`** — searches the web and returns `documents` +
+  `links`, the same output shape as Haystack's built-in `SerperDevWebSearch` /
+  `SearchApiWebSearch`, so it is drop-in for pipelines wired to those.
+- **`KeenableFetcher`** — fetches a list of URLs and returns `documents` whose
+  content is the page's main text as markdown (Keenable extracts it server-side,
+  so you don't need a separate `LinkContentFetcher` + `HTMLToDocument` step).
+
+**Keyless by default**: with no API key the keyless public endpoints are used.
+Provide a key to use the authenticated endpoints (required for `mode="realtime"`
+and for higher rate limits).
+
+## Install
+
+```bash
+pip install keenable-haystack
+```
+
+## Usage
+
+```python
+from haystack_integrations.components.websearch.keenable import KeenableWebSearch
+from haystack_integrations.components.fetchers.keenable import KeenableFetcher
+
+# No key -> keyless public endpoints. Set KEENABLE_API_KEY to lift limits.
+websearch = KeenableWebSearch(top_k=5)
+hits = websearch.run(query="latest developments in AI agents")
+print(hits["links"])
+
+fetcher = KeenableFetcher()
+pages = fetcher.run(urls=hits["links"][:2])
+print(pages["documents"][0].content)
+```
+
+In a pipeline (drop-in for any web-search component):
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+
+pipe = Pipeline()
+pipe.add_component("search", KeenableWebSearch(top_k=5))
+pipe.add_component("prompt", PromptBuilder(template="Answer using:\n{{ documents }}"))
+pipe.connect("search.documents", "prompt.documents")
+```
+
+`KeenableWebSearch.run` accepts optional per-query filters (`site`,
+`published_after/before`, `acquired_after/before`, `mode`). There is no
+`max_results`: the API returns a fixed-size result set; `top_k` (constructor)
+trims it client-side.
+
+## Configuration
+
+- **API key (optional).** `api_key=Secret.from_token(...)` / the default
+  `Secret.from_env_var("KEENABLE_API_KEY", strict=False)`. Blank/unset → keyless
+  public endpoints. Serializes by env-var name, never the key value.
+- **Endpoint (optional).** `KEENABLE_API_URL` overrides the base URL (HTTPS
+  enforced; plain `http` only for loopback). The endpoint is never a component
+  argument the model can set, so it cannot be used to redirect requests.
+
+`KeenableFetcher` rejects non-`http(s)` schemes and private/internal hosts
+client-side before sending, and (like `LinkContentFetcher`) skips failed URLs by
+default — set `raise_on_failure=True` to surface errors instead.
+
+## License
+
+MIT © Keenable

keenable_haystack-0.1.0/README.md

@@ -0,0 +1,71 @@
+# keenable-haystack
+
+[Keenable](https://keenable.ai) web search + page fetch for
+[Haystack](https://haystack.deepset.ai) 2.x, as two components:
+
+- **`KeenableWebSearch`** — searches the web and returns `documents` +
+  `links`, the same output shape as Haystack's built-in `SerperDevWebSearch` /
+  `SearchApiWebSearch`, so it is drop-in for pipelines wired to those.
+- **`KeenableFetcher`** — fetches a list of URLs and returns `documents` whose
+  content is the page's main text as markdown (Keenable extracts it server-side,
+  so you don't need a separate `LinkContentFetcher` + `HTMLToDocument` step).
+
+**Keyless by default**: with no API key the keyless public endpoints are used.
+Provide a key to use the authenticated endpoints (required for `mode="realtime"`
+and for higher rate limits).
+
+## Install
+
+```bash
+pip install keenable-haystack
+```
+
+## Usage
+
+```python
+from haystack_integrations.components.websearch.keenable import KeenableWebSearch
+from haystack_integrations.components.fetchers.keenable import KeenableFetcher
+
+# No key -> keyless public endpoints. Set KEENABLE_API_KEY to lift limits.
+websearch = KeenableWebSearch(top_k=5)
+hits = websearch.run(query="latest developments in AI agents")
+print(hits["links"])
+
+fetcher = KeenableFetcher()
+pages = fetcher.run(urls=hits["links"][:2])
+print(pages["documents"][0].content)
+```
+
+In a pipeline (drop-in for any web-search component):
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+
+pipe = Pipeline()
+pipe.add_component("search", KeenableWebSearch(top_k=5))
+pipe.add_component("prompt", PromptBuilder(template="Answer using:\n{{ documents }}"))
+pipe.connect("search.documents", "prompt.documents")
+```
+
+`KeenableWebSearch.run` accepts optional per-query filters (`site`,
+`published_after/before`, `acquired_after/before`, `mode`). There is no
+`max_results`: the API returns a fixed-size result set; `top_k` (constructor)
+trims it client-side.
+
+## Configuration
+
+- **API key (optional).** `api_key=Secret.from_token(...)` / the default
+  `Secret.from_env_var("KEENABLE_API_KEY", strict=False)`. Blank/unset → keyless
+  public endpoints. Serializes by env-var name, never the key value.
+- **Endpoint (optional).** `KEENABLE_API_URL` overrides the base URL (HTTPS
+  enforced; plain `http` only for loopback). The endpoint is never a component
+  argument the model can set, so it cannot be used to redirect requests.
+
+`KeenableFetcher` rejects non-`http(s)` schemes and private/internal hosts
+client-side before sending, and (like `LinkContentFetcher`) skips failed URLs by
+default — set `raise_on_failure=True` to surface errors instead.
+
+## License
+
+MIT © Keenable

keenable_haystack-0.1.0/haystack_integrations/components/fetchers/keenable/__init__.py

@@ -0,0 +1,3 @@
+from haystack_integrations.components.fetchers.keenable.fetcher import KeenableFetcher
+
+__all__ = ["KeenableFetcher"]

keenable_haystack-0.1.0/haystack_integrations/components/fetchers/keenable/fetcher.py

@@ -0,0 +1,111 @@
+"""Keenable page-fetch component for Haystack."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+# The transport lives in the websearch leaf package so it is defined once; the
+# fetcher reuses it (keyed/keyless selection, attribution headers, SSRF guard).
+from haystack_integrations.components.websearch.keenable._client import (
+    KeenableError,
+    keenable_get,
+    normalize_key,
+    reject_private_fetch_target,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@component
+class KeenableFetcher:
+    """Fetches web pages via Keenable and returns their content as Documents.
+
+    Given a list of URLs, returns one ``Document`` per successfully fetched page
+    (``content`` is the page's main content as markdown; ``meta`` carries
+    ``url``, ``title`` and any other fields the page exposes). Pairs with
+    :class:`KeenableWebSearch` — discover URLs with search, then read full pages
+    here. Unlike Haystack's ``LinkContentFetcher`` + ``HTMLToDocument`` two-step,
+    Keenable returns clean extracted markdown, so this is a single component that
+    returns Documents directly.
+
+    Keyless by default (``/v1/fetch/public``); an ``api_key`` (or
+    ``KEENABLE_API_KEY``) switches to ``/v1/fetch`` and lifts limits. Non-http(s)
+    and private/internal URLs are rejected client-side before sending.
+
+    ### Usage
+
+    ```python
+    from haystack_integrations.components.fetchers.keenable import KeenableFetcher
+
+    fetcher = KeenableFetcher()
+    result = fetcher.run(urls=["https://example.com/article"])
+    print(result["documents"][0].content)
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Secret = Secret.from_env_var("KEENABLE_API_KEY", strict=False),  # noqa: B008
+        raise_on_failure: bool = False,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        :param api_key: Keenable API key. Falls back to ``KEENABLE_API_KEY``; when
+            absent (or blank) the keyless public endpoint is used.
+        :param raise_on_failure: If ``True``, a failed fetch raises; if ``False``
+            (default, matching ``LinkContentFetcher``), the URL is logged and
+            skipped so one bad URL does not fail the whole batch.
+        :param timeout: Per-request timeout in seconds.
+        """
+        if timeout <= 0:
+            msg = f"timeout must be a positive number of seconds, got {timeout!r}"
+            raise ValueError(msg)
+        self.api_key = api_key
+        self.raise_on_failure = raise_on_failure
+        self.timeout = timeout
+
+    def to_dict(self) -> dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            raise_on_failure=self.raise_on_failure,
+            timeout=self.timeout,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "KeenableFetcher":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    def _fetch_one(self, url: str, api_key: Optional[str]) -> Document:
+        if not url.lower().startswith(("http://", "https://")):
+            msg = f"Refusing to fetch a non-http(s) URL: {url!r}"
+            raise KeenableError(msg)
+        reject_private_fetch_target(url)
+        data = keenable_get("/v1/fetch/public", "/v1/fetch", {"url": url}, api_key, self.timeout)
+        content = data.get("content") or ""
+        return Document(content=content, meta=dict(data))
+
+    @component.output_types(documents=list[Document])
+    def run(self, urls: list[str]) -> dict[str, Any]:
+        """Fetch each URL and return the extracted pages as Documents.
+
+        :param urls: The URLs to fetch.
+        :returns: A dict with ``documents`` (``list[Document]``), one per page
+            fetched successfully.
+        """
+        api_key = normalize_key(self.api_key.resolve_value())
+        documents: list[Document] = []
+        for url in urls:
+            try:
+                documents.append(self._fetch_one(url, api_key))
+            except Exception as e:  # noqa: BLE001 - contract: one bad URL must not fail the batch
+                if self.raise_on_failure:
+                    raise
+                logger.warning("Keenable could not fetch %r; skipping (%s).", url, e)
+        return {"documents": documents}

keenable_haystack-0.1.0/haystack_integrations/components/websearch/keenable/__init__.py

@@ -0,0 +1,3 @@
+from haystack_integrations.components.websearch.keenable.web_search import KeenableWebSearch
+
+__all__ = ["KeenableWebSearch"]

keenable_haystack-0.1.0/haystack_integrations/components/websearch/keenable/_client.py

@@ -0,0 +1,232 @@
+"""Shared transport for the Keenable Haystack components.
+
+One place for the parts of the Keenable contract both components need: keyed vs.
+keyless endpoint selection, the attribution headers, HTTPS-only base-URL
+resolution, the client-side SSRF guard, and turning a non-2xx response into a
+readable error. The endpoint is read from the environment and is never a
+component argument the model/pipeline can set (an arbitrary base URL is an SSRF
+foothold).
+
+The fetcher component imports from this module too, so the transport lives in
+exactly one place across both `haystack_integrations.components.websearch.keenable`
+and `...fetchers.keenable`.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+from importlib import metadata
+from typing import Any
+from urllib.parse import urlsplit
+
+import requests
+
+try:
+    _VERSION = metadata.version("keenable-haystack")
+except metadata.PackageNotFoundError:  # pragma: no cover - editable/source checkout
+    _VERSION = "unknown"
+
+# Tagged User-Agent so Keenable can attribute traffic from this integration.
+_USER_AGENT = f"keenable-haystack/{_VERSION}"
+
+# The load-bearing attribution signal: the Keenable backend segments traffic by
+# this header (adoption dashboards). The User-Agent above is a secondary tag.
+_ATTRIBUTION_TITLE = "Haystack"
+
+_DEFAULT_BASE_URL = "https://api.keenable.ai"
+_BASE_URL_ENV = "KEENABLE_API_URL"
+
+
+class KeenableError(RuntimeError):
+    """A Keenable transport/API error carrying a message safe to show a user."""
+
+
+def normalize_key(raw: str | None) -> str | None:
+    """Return the non-blank key, else ``None`` to use the keyless free tier.
+
+    Haystack's :class:`~haystack.utils.Secret` already resolves the
+    ``KEENABLE_API_KEY`` env var (with ``strict=False`` it yields ``None`` when
+    unset); this just collapses a blank/whitespace value to ``None`` so an empty
+    string never selects the authenticated endpoint.
+    """
+    key = raw.strip() if isinstance(raw, str) else ""
+    return key or None
+
+
+def resolve_base_url() -> str:
+    """Resolve the API base URL from ``KEENABLE_API_URL`` and enforce HTTPS."""
+    base = (os.environ.get(_BASE_URL_ENV) or _DEFAULT_BASE_URL).rstrip("/")
+    parsed = urlsplit(base)
+    host = (parsed.hostname or "").rstrip(".")
+    if not host:
+        msg = f"{_BASE_URL_ENV} must be an https:// URL with a host, got {base!r}"
+        raise KeenableError(msg)
+    # Local-dev escape hatch: plain http only to an explicit loopback host.
+    if parsed.scheme == "http" and host in {"localhost", "127.0.0.1", "::1"}:
+        return base
+    if parsed.scheme != "https":
+        msg = f"{_BASE_URL_ENV} must be an https:// URL with a host, got {base!r}"
+        raise KeenableError(msg)
+    # Over https, refuse a base URL pointing at a private/internal destination —
+    # a misconfigured KEENABLE_API_URL must never ship API keys to an internal
+    # host (the same SSRF set as reject_private_fetch_target).
+    if host == "metadata.google.internal" or any(
+        ip.is_loopback
+        or ip.is_private
+        or ip.is_link_local
+        or ip.is_multicast
+        or ip.is_unspecified
+        for ip in _candidate_ips(host)
+    ):
+        msg = f"{_BASE_URL_ENV} must not point at a private/internal address, got {base!r}"
+        raise KeenableError(msg)
+    return base
+
+
+def _candidate_ips(host: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Every IP address ``host`` could denote, without doing DNS.
+
+    Covers dotted/colon literals *and* the numeric IPv4 encodings that resolvers
+    accept but :func:`ipaddress.ip_address` rejects as strings — decimal
+    (``2130706433``), hex (``0x7f000001``), octal (``0177.0.0.1``) and short
+    ``a.b``/``a.b.c`` forms — all of which ``socket.inet_aton`` canonicalizes to a
+    real IPv4 so the private-range check below sees the true address.
+    """
+    candidates: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
+    try:
+        candidates.append(ipaddress.ip_address(host))
+    except ValueError:
+        pass
+    try:
+        packed = socket.inet_aton(host)
+    except OSError:
+        pass
+    else:
+        candidates.append(ipaddress.ip_address(socket.inet_ntoa(packed)))
+    return candidates
+
+
+def reject_private_fetch_target(url: str) -> None:
+    """Refuse obviously private/internal fetch targets before sending (SSRF).
+
+    The backend enforces this server-side too, but a client-side guard avoids
+    leaking an internal hostname in a request and is required by our integration
+    contract. Hostnames that are not IP literals (and not a numeric IPv4 form)
+    pass through; the backend's SSRF guard is the backstop for those.
+    """
+    host = (urlsplit(url).hostname or "").strip().lower()
+    # A trailing dot is the FQDN form of the same name (``localhost.`` ==
+    # ``localhost``); strip it so it can't slip past the checks below.
+    host = host.rstrip(".")
+    if not host:
+        msg = f"Refusing to fetch a URL with no host: {url!r}"
+        raise KeenableError(msg)
+    if host in {"localhost", "metadata.google.internal"}:
+        msg = f"Refusing to fetch a private/internal host: {host!r}"
+        raise KeenableError(msg)
+    for ip in _candidate_ips(host):
+        # ``is_reserved`` is intentionally omitted: it flags non-routable but
+        # harmless ranges (e.g. the 2001:db8::/32 documentation prefix). The
+        # checks below are the ones that matter for SSRF.
+        if (
+            ip.is_loopback
+            or ip.is_private
+            or ip.is_link_local
+            or ip.is_multicast
+            or ip.is_unspecified
+        ):
+            msg = f"Refusing to fetch a private/internal address: {host!r}"
+            raise KeenableError(msg)
+
+
+def _headers(api_key: str | None) -> dict[str, str]:
+    headers = {"User-Agent": _USER_AGENT, "X-Keenable-Title": _ATTRIBUTION_TITLE}
+    if api_key:
+        headers["X-API-Key"] = api_key
+    return headers
+
+
+def _redact(text: str, api_key: str | None) -> str:
+    """Strip the API key from any text bound for an exception message or log.
+
+    Server error bodies and transport-exception strings are attacker- or
+    misconfiguration-influenced; a server that echoed the ``X-API-Key`` request
+    header back in its response would otherwise leak the key into our
+    ``KeenableError`` text, logs, and Haystack pipeline traces.
+    """
+    return text.replace(api_key, "***") if api_key else text
+
+
+def _raise_for_status(response: requests.Response, api_key: str | None) -> None:
+    """Map a non-2xx Keenable response to a readable :class:`KeenableError`."""
+    if response.ok:
+        return
+    detail = ""
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            detail = str(body.get("message") or body.get("error") or body.get("detail") or "")
+    except ValueError:
+        detail = (response.text or "").strip()
+    detail = _redact(detail[:200], api_key)
+    label = {
+        401: "Keenable authentication failed (401)",
+        402: "Keenable: insufficient credits (402)",
+        429: "Keenable rate limit exceeded (429)",
+    }.get(response.status_code, f"Keenable API error ({response.status_code})")
+    raise KeenableError(f"{label}: {detail}" if detail else label)
+
+
+def _decode(response: requests.Response, api_key: str | None) -> dict[str, Any]:
+    _raise_for_status(response, api_key)
+    try:
+        data = response.json()
+    except ValueError as e:
+        snippet = _redact((response.text or "")[:200], api_key)
+        msg = f"Keenable API returned a non-JSON response: {snippet!r}"
+        raise KeenableError(msg) from e
+    if not isinstance(data, dict):
+        msg = f"Unexpected response from the Keenable API: {_redact(repr(data)[:200], api_key)}"
+        raise KeenableError(msg)
+    return data
+
+
+def _transport_error(e: Exception, api_key: str | None) -> KeenableError:
+    """Wrap a transport exception, redacting the key from its message text.
+
+    Standard ``requests`` exceptions never carry headers, but a custom adapter /
+    proxy middleware could put one in the exception string; redact defensively so
+    the key can't reach an exception message, logs, or pipeline tracing.
+    """
+    return KeenableError(
+        f"Could not reach the Keenable API: {type(e).__name__}: {_redact(str(e), api_key)}"
+    )
+
+
+def keenable_post(
+    public_path: str, keyed_path: str, payload: dict[str, Any], api_key: str | None, timeout: float
+) -> dict[str, Any]:
+    """POST ``payload`` to the keyed or keyless endpoint and return the body."""
+    path = keyed_path if api_key else public_path
+    url = f"{resolve_base_url()}{path}"
+    headers = {**_headers(api_key), "Content-Type": "application/json"}
+    try:
+        response = requests.post(url, json=payload, headers=headers, timeout=timeout)
+    except requests.RequestException as e:
+        raise _transport_error(e, api_key) from e
+    return _decode(response, api_key)
+
+
+def keenable_get(
+    public_path: str, keyed_path: str, params: dict[str, Any], api_key: str | None, timeout: float
+) -> dict[str, Any]:
+    """GET the keyed or keyless endpoint with query ``params``; return the body."""
+    path = keyed_path if api_key else public_path
+    url = f"{resolve_base_url()}{path}"
+    try:
+        response = requests.get(url, params=params, headers=_headers(api_key), timeout=timeout)
+    except requests.RequestException as e:
+        raise _transport_error(e, api_key) from e
+    return _decode(response, api_key)

keenable_haystack-0.1.0/haystack_integrations/components/websearch/keenable/web_search.py

@@ -0,0 +1,156 @@
+"""Keenable web-search component for Haystack."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+from haystack_integrations.components.websearch.keenable._client import (
+    KeenableError,
+    keenable_post,
+    normalize_key,
+)
+
+
+@component
+class KeenableWebSearch:
+    """Searches the web with Keenable, a search engine built for AI agents.
+
+    Mirrors the output shape of Haystack's built-in web-search components
+    (``SerperDevWebSearch`` / ``SearchApiWebSearch``): ``run()`` returns
+    ``documents`` (one ``Document`` per result, snippet as content, result
+    fields as ``meta``) and ``links`` (the result URLs), so it is drop-in for
+    pipelines wired to those.
+
+    Keyless by default: with no API key the keyless public endpoint
+    (``/v1/search/public``) is used. Provide an API key (the ``api_key`` argument
+    or the ``KEENABLE_API_KEY`` environment variable) to use the authenticated
+    endpoint (``/v1/search``), required for ``mode="realtime"`` and for higher
+    rate limits.
+
+    The API endpoint is read from ``KEENABLE_API_URL`` (HTTPS enforced), never a
+    ``run`` argument, so the search cannot be redirected to an arbitrary host.
+
+    ### Usage
+
+    ```python
+    from haystack_integrations.components.websearch.keenable import KeenableWebSearch
+
+    # No key -> keyless public endpoint. Set KEENABLE_API_KEY to lift limits.
+    websearch = KeenableWebSearch(top_k=5)
+    result = websearch.run(query="latest developments in AI agents")
+    print(result["documents"])
+    print(result["links"])
+    ```
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Secret = Secret.from_env_var("KEENABLE_API_KEY", strict=False),  # noqa: B008
+        top_k: Optional[int] = None,
+        mode: str = "pro",
+        site: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        :param api_key: Keenable API key. Falls back to ``KEENABLE_API_KEY``; when
+            absent (or blank) the keyless public endpoint is used.
+        :param top_k: Keep at most this many results (applied client-side; the API
+            returns a fixed-size set with no count parameter). ``None`` keeps all.
+        :param mode: Default search mode, ``"pro"`` (deeper) or ``"realtime"``
+            (low latency). ``"realtime"`` requires an API key. Overridable per run.
+        :param site: Default single-domain restriction, e.g. ``"github.com"``.
+            Overridable per run.
+        :param timeout: Per-request timeout in seconds.
+        """
+        if timeout <= 0:
+            msg = f"timeout must be a positive number of seconds, got {timeout!r}"
+            raise ValueError(msg)
+        if top_k is not None and top_k < 1:
+            msg = f"top_k must be None or a positive integer, got {top_k!r}"
+            raise ValueError(msg)
+        self.api_key = api_key
+        self.top_k = top_k
+        self.mode = mode
+        self.site = site
+        self.timeout = timeout
+
+    def to_dict(self) -> dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            top_k=self.top_k,
+            mode=self.mode,
+            site=self.site,
+            timeout=self.timeout,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "KeenableWebSearch":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+    @component.output_types(documents=list[Document], links=list[str])
+    def run(
+        self,
+        query: str,
+        site: Optional[str] = None,
+        published_after: Optional[str] = None,
+        published_before: Optional[str] = None,
+        acquired_after: Optional[str] = None,
+        acquired_before: Optional[str] = None,
+        mode: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Run a Keenable web search.
+
+        :param query: The search query.
+        :param site: Restrict results to a single domain (overrides the default).
+        :param published_after: Only pages published on/after this date (YYYY-MM-DD).
+        :param published_before: Only pages published on/before this date (YYYY-MM-DD).
+        :param acquired_after: Only pages indexed on/after this date (YYYY-MM-DD).
+        :param acquired_before: Only pages indexed on/before this date (YYYY-MM-DD).
+        :param mode: Override the default search mode for this query.
+        :returns: A dict with ``documents`` (``list[Document]``) and ``links``
+            (``list[str]``).
+        """
+        effective_mode = mode or self.mode
+        api_key = normalize_key(self.api_key.resolve_value())
+        if effective_mode == "realtime" and api_key is None:
+            msg = "mode='realtime' requires an API key; it is not available on the keyless endpoint."
+            raise KeenableError(msg)
+
+        payload: dict[str, Any] = {"query": query, "mode": effective_mode}
+        for field, value in (
+            ("site", site or self.site),
+            ("published_after", published_after),
+            ("published_before", published_before),
+            ("acquired_after", acquired_after),
+            ("acquired_before", acquired_before),
+        ):
+            if value:
+                payload[field] = value
+
+        data = keenable_post("/v1/search/public", "/v1/search", payload, api_key, self.timeout)
+        results = data.get("results")
+        if not isinstance(results, list):
+            msg = f"Unexpected response from the Keenable search API: {data!r}"
+            raise KeenableError(msg)
+
+        if self.top_k is not None:
+            results = results[: self.top_k]
+
+        documents: list[Document] = []
+        links: list[str] = []
+        for result in results:
+            if not isinstance(result, dict):
+                continue
+            content = result.get("description") or result.get("title") or ""
+            documents.append(Document(content=content, meta=dict(result)))
+            link = result.get("url")
+            if link:
+                links.append(link)
+
+        return {"documents": documents, "links": links}

keenable_haystack-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keenable-haystack"
+version = "0.1.0"
+description = "Keenable web-search and page-fetch components for Haystack. Keyless by default."
+authors = [{ name = "Keenable", email = "hello@keenable.ai" }]
+maintainers = [{ name = "keenableai" }]
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+keywords = ["haystack", "haystack-ai", "keenable", "web-search", "fetch", "agents", "rag"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "haystack-ai>=2.0.0",
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://keenable.ai"
+Documentation = "https://docs.keenable.ai"
+Repository = "https://github.com/keenableai/keenable-haystack"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.11",
+    "mypy>=1.10",
+]
+
+# PEP 420 namespace package: ship the whole `haystack_integrations` tree (no
+# __init__.py at the namespace levels) so Keenable coexists with other
+# haystack_integrations.* packages.
+[tool.hatch.build.targets.sdist]
+include = ["haystack_integrations/", "LICENSE", "README.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["haystack_integrations"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+# Two namespace-package leaves share the basename `keenable`, so mypy needs
+# explicit package bases + namespace mode to map files to modules. python_version
+# is the analysis target (mypy dropped 3.9 as a target); the package floor stays
+# 3.9 via requires-python.
+[tool.mypy]
+ignore_missing_imports = true
+python_version = "3.10"
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = "."