hermes-keenable-web 0.1.0__tar.gz

hermes_keenable_web-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+uv.lock

hermes_keenable_web-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.

hermes_keenable_web-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: hermes-keenable-web
+Version: 0.1.0
+Summary: Keenable web search + content fetch provider for Hermes Agent. Keyless by default; a key raises limits.
+Project-URL: Homepage, https://keenable.ai
+Project-URL: Documentation, https://docs.keenable.ai
+Project-URL: Repository, https://github.com/keenableai/hermes-keenable-web
+Author-email: Keenable <hello@keenable.ai>
+Maintainer: keenableai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,fetch,hermes,hermes-agent,keenable,plugin,web-search
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# hermes-keenable-web
+
+[Keenable](https://keenable.ai) as a web search + content-fetch backend for
+[Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Keenable is low-latency web search and page-to-markdown extraction built for
+agents. This is a **standalone plugin** (per Hermes' third-party-provider
+policy, `AGENTS.md`): it implements the `WebSearchProvider` ABC and registers
+through the normal plugin discovery path, so nothing in Hermes core changes.
+
+- **Search** and **extract** in one provider (`web_search` + `web_extract`).
+- **Keyless by default**: the free tier works with no key (rate-limited public
+  endpoint). Set `KEENABLE_API_KEY` to raise limits.
+- Every request sends `X-Keenable-Title: Hermes` for traffic attribution.
+
+## Install
+
+### pip (recommended)
+
+```bash
+pip install hermes-keenable-web
+```
+
+Hermes discovers it via the `hermes_agent.plugins` entry point. Enable it in
+`plugins.enabled`, then select it as the web backend.
+
+### User plugin directory
+
+Copy the package into your Hermes plugin dir:
+
+```bash
+mkdir -p ~/.hermes/plugins/web/keenable
+cp -r hermes_keenable_web/* ~/.hermes/plugins/web/keenable/
+```
+
+## Configure
+
+In `config.yaml`:
+
+```yaml
+web:
+  backend: keenable          # both search + extract
+  # or per-capability:
+  # search_backend: keenable
+  # extract_backend: keenable
+```
+
+Environment variables:
+
+```bash
+KEENABLE_API_KEY=...   # optional — blank uses the keyless free tier
+KEENABLE_API_URL=...   # optional — override https://api.keenable.ai
+```
+
+Keenable stays opt-in: it is never auto-selected in the no-credential fallback.
+It only services calls when you choose it explicitly via `web.backend` /
+`web.*_backend`.
+
+## Develop
+
+```bash
+uv run --with pytest --with httpx --no-project python -m pytest tests/ -q
+```
+
+## License
+
+MIT

hermes_keenable_web-0.1.0/README.md

@@ -0,0 +1,67 @@
+# hermes-keenable-web
+
+[Keenable](https://keenable.ai) as a web search + content-fetch backend for
+[Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Keenable is low-latency web search and page-to-markdown extraction built for
+agents. This is a **standalone plugin** (per Hermes' third-party-provider
+policy, `AGENTS.md`): it implements the `WebSearchProvider` ABC and registers
+through the normal plugin discovery path, so nothing in Hermes core changes.
+
+- **Search** and **extract** in one provider (`web_search` + `web_extract`).
+- **Keyless by default**: the free tier works with no key (rate-limited public
+  endpoint). Set `KEENABLE_API_KEY` to raise limits.
+- Every request sends `X-Keenable-Title: Hermes` for traffic attribution.
+
+## Install
+
+### pip (recommended)
+
+```bash
+pip install hermes-keenable-web
+```
+
+Hermes discovers it via the `hermes_agent.plugins` entry point. Enable it in
+`plugins.enabled`, then select it as the web backend.
+
+### User plugin directory
+
+Copy the package into your Hermes plugin dir:
+
+```bash
+mkdir -p ~/.hermes/plugins/web/keenable
+cp -r hermes_keenable_web/* ~/.hermes/plugins/web/keenable/
+```
+
+## Configure
+
+In `config.yaml`:
+
+```yaml
+web:
+  backend: keenable          # both search + extract
+  # or per-capability:
+  # search_backend: keenable
+  # extract_backend: keenable
+```
+
+Environment variables:
+
+```bash
+KEENABLE_API_KEY=...   # optional — blank uses the keyless free tier
+KEENABLE_API_URL=...   # optional — override https://api.keenable.ai
+```
+
+Keenable stays opt-in: it is never auto-selected in the no-credential fallback.
+It only services calls when you choose it explicitly via `web.backend` /
+`web.*_backend`.
+
+## Develop
+
+```bash
+uv run --with pytest --with httpx --no-project python -m pytest tests/ -q
+```
+
+## License
+
+MIT

hermes_keenable_web-0.1.0/hermes_keenable_web/__init__.py

@@ -0,0 +1,17 @@
+"""Keenable web search + extract — standalone Hermes plugin.
+
+Installed via pip (entry point ``hermes_agent.plugins``) or copied into
+``~/.hermes/plugins/web/keenable/``. Registers the Keenable provider through
+the standard plugin context; nothing in Hermes core needs to change.
+"""
+
+from __future__ import annotations
+
+from hermes_keenable_web.provider import KeenableWebSearchProvider
+
+__version__ = "0.1.0"
+
+
+def register(ctx) -> None:
+    """Register the Keenable provider with the plugin context."""
+    ctx.register_web_search_provider(KeenableWebSearchProvider())

hermes_keenable_web-0.1.0/hermes_keenable_web/plugin.yaml

@@ -0,0 +1,7 @@
+name: web-keenable
+version: 0.1.0
+description: "Keenable web search + content fetch — low-latency search and page-to-markdown extraction built for agents. Free tier works keyless; set KEENABLE_API_KEY (https://keenable.ai/signup) to raise limits."
+author: Keenable
+kind: backend
+provides_web_providers:
+  - keenable

hermes_keenable_web-0.1.0/hermes_keenable_web/provider.py

@@ -0,0 +1,270 @@
+"""Keenable web search + content extraction — standalone Hermes plugin.
+
+Subclasses :class:`agent.web_search_provider.WebSearchProvider`. Two
+capabilities, both sync (the underlying call is ``httpx``):
+
+- ``supports_search()``  -> True (Keenable ``GET /v1/search``)
+- ``supports_extract()`` -> True (Keenable ``GET /v1/fetch``, one URL per call)
+
+Config keys this provider responds to::
+
+    web:
+      search_backend: "keenable"      # explicit per-capability
+      extract_backend: "keenable"     # explicit per-capability
+      backend: "keenable"             # shared fallback for both
+
+Env vars::
+
+    KEENABLE_API_KEY=...             # https://keenable.ai/signup (optional)
+    KEENABLE_API_URL=...             # optional override of https://api.keenable.ai
+
+Keyless: Keenable's free tier works without a key. When ``KEENABLE_API_KEY``
+is unset the provider calls the ``/public`` endpoint variants (rate-limited)
+and omits the ``X-API-Key`` header — mirroring Keenable's own MCP client.
+
+``is_available()`` returns True even without a key so keyless selection works
+for both ``web.backend`` and the per-capability ``web.search_backend`` /
+``web.extract_backend`` keys (Hermes gates the latter on ``is_available()``).
+It remains opt-in in practice: the plugin is installed deliberately, and only
+surfaces as a no-config last-resort fallback when nothing else is configured.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List
+from urllib.parse import urlsplit
+
+from agent.web_search_provider import WebSearchProvider
+
+logger = logging.getLogger(__name__)
+
+# Identifies Hermes to Keenable for traffic attribution. Sent on every call.
+_CLIENT_TITLE = "Hermes"
+
+_DEFAULT_BASE_URL = "https://api.keenable.ai"
+
+
+def _provider_env(name: str) -> str:
+    """Read an env var through Hermes' managed-scope-aware helper when available.
+
+    Falls back to ``os.getenv`` on older cores that predate
+    ``get_provider_env`` so the plugin loads across a range of Hermes versions.
+    """
+    try:
+        from agent.web_search_provider import get_provider_env
+
+        return get_provider_env(name) or ""
+    except ImportError:
+        import os
+
+        return os.getenv(name, "") or ""
+
+
+def _keenable_base_url() -> str:
+    """Resolve the API base URL from ``KEENABLE_API_URL`` and enforce HTTPS.
+
+    An arbitrary base URL is a credential-forwarding / SSRF foothold — the
+    ``X-API-Key`` header would follow the request to whatever host is set — so
+    only ``https://`` (or ``http://`` against a loopback host, for local dev) is
+    accepted. Mirrors the other Keenable clients in this repo.
+    """
+    base = (_provider_env("KEENABLE_API_URL") or _DEFAULT_BASE_URL).rstrip("/")
+    parsed = urlsplit(base)
+    if parsed.hostname and not parsed.username and not parsed.password:
+        if parsed.scheme == "https":
+            return base
+        # Permit plain http only for local development against a loopback host.
+        if parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}:
+            return base
+    raise ValueError(f"KEENABLE_API_URL must be an https:// URL with a host, got {base!r}")
+
+
+def _api_key() -> str:
+    return _provider_env("KEENABLE_API_KEY").strip()
+
+
+def _keenable_headers(api_key: str) -> Dict[str, str]:
+    """Request headers; ``X-API-Key`` only when a key is present (keyless otherwise)."""
+    headers = {"X-Keenable-Title": _CLIENT_TITLE, "Content-Type": "application/json"}
+    if api_key:
+        headers["X-API-Key"] = api_key
+    return headers
+
+
+def _endpoint(base_url: str, path: str, api_key: str) -> str:
+    """Keyless calls hit the ``/public`` variant (no auth, rate-limited)."""
+    return f"{base_url}{path}" if api_key else f"{base_url}{path}/public"
+
+
+def _normalize_search_results(response: Dict[str, Any]) -> Dict[str, Any]:
+    """Map Keenable ``/v1/search`` response to ``{success, data: {web: [...]}}``.
+
+    Each result has ``title``, ``url``, ``description``.
+    """
+    web_results = []
+    for i, result in enumerate(response.get("results", []) or []):
+        web_results.append(
+            {
+                "title": result.get("title", ""),
+                "url": result.get("url", ""),
+                "description": result.get("description", ""),
+                "position": i + 1,
+            }
+        )
+    return {"success": True, "data": {"web": web_results}}
+
+
+class KeenableWebSearchProvider(WebSearchProvider):
+    """Keenable search + extract provider."""
+
+    @property
+    def name(self) -> str:
+        return "keenable"
+
+    @property
+    def display_name(self) -> str:
+        return "Keenable"
+
+    def is_available(self) -> bool:
+        """Always True — Keenable works keyless against the public endpoints.
+
+        Hermes gates per-capability backend selection (``web.search_backend`` /
+        ``web.extract_backend``) on ``is_available()``, so key-gating it here
+        would break keyless-by-default for those config keys (the selection
+        silently falls back to another provider). A key only raises rate
+        limits, never a prerequisite. As a deliberately-installed opt-in
+        plugin, keenable surfacing as a last-resort fallback when nothing else
+        is configured is acceptable.
+        """
+        return True
+
+    def supports_search(self) -> bool:
+        return True
+
+    def supports_extract(self) -> bool:
+        return True
+
+    def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
+        """Execute a Keenable search (``GET /v1/search?query=``).
+
+        The API takes no result-count param (query/mode/site/date filters
+        only), so ``limit`` is applied client-side to the ranked results.
+        """
+        try:
+            try:
+                from tools.interrupt import is_interrupted
+
+                if is_interrupted():
+                    return {"success": False, "error": "Interrupted"}
+            except ImportError:
+                pass
+
+            import httpx
+
+            api_key = _api_key()
+            # DEBUG, not INFO: queries can carry PII/secrets — keep them out of
+            # default-level logs.
+            logger.debug("Keenable search: '%s' (limit=%d)", query, limit)
+            response = httpx.get(
+                _endpoint(_keenable_base_url(), "/v1/search", api_key),
+                headers=_keenable_headers(api_key),
+                params={"query": query},
+                timeout=60,
+            )
+            response.raise_for_status()
+            normalized = _normalize_search_results(response.json())
+            # Guard against negative limits: a raw [:limit] slice would drop
+            # from the tail instead of returning nothing.
+            safe_limit = max(limit, 0)
+            normalized["data"]["web"] = normalized["data"]["web"][:safe_limit]
+            return normalized
+        except Exception as exc:  # noqa: BLE001 — including httpx errors
+            logger.warning("Keenable search error: %s", exc)
+            return {"success": False, "error": f"Keenable search failed: {exc}"}
+
+    def extract(self, urls: List[str], **kwargs: Any) -> List[Dict[str, Any]]:
+        """Extract content from URLs via Keenable (``GET /v1/fetch``, one per URL).
+
+        Sync — the underlying call is ``httpx.get(...)``. Returns the legacy
+        list-of-results shape; per-URL failures become items with ``error``.
+        """
+        try:
+            from tools.interrupt import is_interrupted
+        except ImportError:  # interrupt support is optional
+            def is_interrupted() -> bool:  # noqa: D401
+                return False
+
+        import httpx
+
+        base_url = _keenable_base_url()
+        api_key = _api_key()
+        headers = _keenable_headers(api_key)
+        fetch_url = _endpoint(base_url, "/v1/fetch", api_key)
+        documents: List[Dict[str, Any]] = []
+
+        # /v1/fetch takes a single ``url`` query param (no batch, no max_chars).
+        for url in urls:
+            if is_interrupted():
+                documents.append(
+                    {
+                        "url": url,
+                        "title": "",
+                        "content": "",
+                        "raw_content": "",
+                        "error": "Interrupted",
+                        "metadata": {"sourceURL": url},
+                    }
+                )
+                continue
+            try:
+                logger.debug("Keenable fetch: %s", url)
+                response = httpx.get(
+                    fetch_url,
+                    headers=headers,
+                    params={"url": url},
+                    timeout=60,
+                )
+                response.raise_for_status()
+                payload = response.json()
+                title = payload.get("title", "")
+                content = payload.get("content", "")
+                metadata = {"sourceURL": url, "title": title}
+                if isinstance(payload.get("metadata"), dict):
+                    metadata.update(payload["metadata"])
+                documents.append(
+                    {
+                        "url": payload.get("url", url),
+                        "title": title,
+                        "content": content,
+                        "raw_content": content,
+                        "metadata": metadata,
+                    }
+                )
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Keenable fetch error for %s: %s", url, exc)
+                documents.append(
+                    {
+                        "url": url,
+                        "title": "",
+                        "content": "",
+                        "raw_content": "",
+                        "error": f"Keenable fetch failed: {exc}",
+                        "metadata": {"sourceURL": url},
+                    }
+                )
+        return documents
+
+    def get_setup_schema(self) -> Dict[str, Any]:
+        return {
+            "name": "Keenable",
+            "badge": "free",
+            "tag": "Search + page fetch; free tier works keyless, key raises limits.",
+            "env_vars": [
+                {
+                    "key": "KEENABLE_API_KEY",
+                    "prompt": "Keenable API key (optional — blank uses the keyless free tier)",
+                    "url": "https://keenable.ai/signup",
+                },
+            ],
+        }

hermes_keenable_web-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hermes-keenable-web"
+version = "0.1.0"
+description = "Keenable web search + content fetch provider for Hermes Agent. Keyless by default; a key raises limits."
+authors = [{ name = "Keenable", email = "hello@keenable.ai" }]
+maintainers = [{ name = "keenableai" }]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "MIT"
+keywords = ["hermes", "hermes-agent", "web-search", "fetch", "keenable", "plugin", "agents"]
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.urls]
+Homepage = "https://keenable.ai"
+Documentation = "https://docs.keenable.ai"
+Repository = "https://github.com/keenableai/hermes-keenable-web"
+
+# Discovered by Hermes' PluginManager via importlib.metadata (group
+# "hermes_agent.plugins"). The value points at the module exposing register(ctx).
+[project.entry-points."hermes_agent.plugins"]
+keenable = "hermes_keenable_web"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.11",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["hermes_keenable_web/", "LICENSE", "README.md"]
+
+[tool.hatch.build.targets.wheel]
+include = ["hermes_keenable_web/"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"hermes_keenable_web/plugin.yaml" = "hermes_keenable_web/plugin.yaml"
+
+[tool.mypy]
+ignore_missing_imports = true
+python_version = "3.10"