serpapi-hermes-plugin 0.1.0__tar.gz

serpapi_hermes_plugin-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 SerpApi
+
+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.
+

serpapi_hermes_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: serpapi-hermes-plugin
+Version: 0.1.0
+Summary: SerpApi search plugin for Hermes Agent: web, Maps, News, and Shopping
+Author: SerpApi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/serpapi/serpapi-hermes-plugin
+Project-URL: Repository, https://github.com/serpapi/serpapi-hermes-plugin
+Project-URL: Issues, https://github.com/serpapi/serpapi-hermes-plugin/issues
+Keywords: hermes-agent,plugin,serpapi,web-search,maps,news,shopping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28.1
+Dynamic: license-file
+
+# SerpApi for Hermes Agent
+
+Give [Hermes Agent](https://hermes-agent.nousresearch.com/) fast, fresh search
+results from the web, Google Maps, Google News, and Google Shopping with
+[SerpApi](https://serpapi.com/).
+
+The plugin adds SerpApi to Hermes in two ways:
+
+- Hermes's built-in `web_search` uses the fast Google Light engine.
+- Dedicated Maps, News, and Shopping tools let Hermes choose the right SerpApi
+  engine for local places, current reporting, and product searches.
+
+## Ask Hermes to install it
+
+You can let Hermes install and configure the plugin for you. Paste the message
+below into a Hermes chat, then approve the install or terminal commands if
+Hermes prompts you:
+
+```text
+Install serpapi-hermes-plugin into the same Python environment that runs this
+Hermes Agent. If this is a standard Hermes installation, run:
+
+cd ~/.hermes/hermes-agent
+uv pip install --python venv/bin/python serpapi-hermes-plugin
+
+Otherwise, use the active Hermes Python environment to run:
+
+uv pip install --python /path/to/hermes/python serpapi-hermes-plugin
+
+Request my approval for install or terminal commands whenever required; do not
+bypass approvals. After the package is installed, run:
+
+hermes plugins enable serpapi
+
+If Hermes asks whether to allow this plugin to replace built-in tools, answer
+no; serpapi-hermes-plugin does not need tool-override access.
+
+Then ask me for my SerpApi Private API Key, which I can copy from the SerpApi
+dashboard. Do not ask for the key until installation and enablement succeed.
+After I provide it, save it as SERPAPI_API_KEY in ~/.hermes/.env without
+printing, logging, or committing it. Configure SerpApi as the Hermes web search
+backend, tell me whether Hermes must be restarted, and verify that web search,
+Maps, News, and Shopping tools are available. Use this key for future SerpApi
+searches and never expose it in output.
+```
+
+## Install
+
+You need a working
+[Hermes Agent installation](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/)
+and a SerpApi account.
+
+Install the plugin from PyPI in the same Python environment as Hermes. If you
+installed Hermes with its standard installer, use its `venv` interpreter
+explicitly:
+
+```bash
+cd ~/.hermes/hermes-agent
+uv pip install --python venv/bin/python serpapi-hermes-plugin
+```
+
+The explicit `--python` is important: the standard Hermes installer creates a
+directory named `venv`, while bare `uv pip install` automatically looks for a
+directory named `.venv`.
+
+For a custom Hermes installation, point uv at the Python interpreter that runs
+Hermes:
+
+```bash
+uv pip install --python /path/to/hermes/python serpapi-hermes-plugin
+```
+
+If that environment already has pip and is activated, the equivalent command
+is `python -m pip install serpapi-hermes-plugin`.
+
+Restart any running Hermes session after installation.
+
+## Get your SerpApi API key
+
+1. [Create a SerpApi account](https://serpapi.com/users/sign_up), or sign in to
+   your existing account.
+2. Open the [SerpApi dashboard](https://serpapi.com/dashboard).
+3. Find your **Private API Key** in the dashboard and copy it.
+
+One API key powers every engine in this plugin. Keep it private and never add it
+to source control.
+
+## Connect the API key to Hermes
+
+Enable the installed plugin:
+
+```bash
+hermes plugins enable serpapi
+```
+
+If prompted about permission to replace built-in tools, answer **no**. This
+plugin adds new tools and a web-search provider; it does not replace built-in
+tool handlers.
+
+Open Hermes's interactive tool configuration:
+
+```bash
+hermes tools
+```
+
+In the **Web Search & Extract** section:
+
+1. Select **SerpApi**.
+2. Paste the Private API Key copied from your SerpApi dashboard.
+3. Confirm the selection.
+
+Hermes saves the key as `SERPAPI_API_KEY` in its environment configuration and
+selects SerpApi for future `web_search` calls. Restart Hermes if a session was
+already running.
+
+## Manual API-key setup
+
+Instead of using `hermes tools`, add the key to `~/.hermes/.env`:
+
+```dotenv
+SERPAPI_API_KEY=your_private_api_key
+```
+
+Then configure `~/.hermes/config.yaml`:
+
+```yaml
+plugins:
+  enabled:
+    - serpapi
+
+web:
+  search_backend: serpapi
+```
+
+You may also export `SERPAPI_API_KEY` in the environment that starts Hermes.
+The environment variable takes precedence over the value in `~/.hermes/.env`.
+
+## Search capabilities
+
+| What you ask for | Hermes tool | SerpApi engine |
+|---|---|---|
+| General web research | `web_search` | `google_light` |
+| Places and local businesses | `serpapi_maps_search` | `google_maps` |
+| Current and recent news | `serpapi_news_search` | `google_news_light` |
+| Products, prices, and merchants | `serpapi_shopping_search` | `google_shopping_light` |
+
+Hermes chooses a tool from your request. Each tool selects and validates its own
+SerpApi engine, so you do not need to specify an engine name.
+
+Example prompts:
+
+- "Search the web for the latest Python 3.14 release notes."
+- "Find highly rated coffee shops near Times Square."
+- "Show me recent news about reusable rockets."
+- "Find well-reviewed laptops under $1,200 with free shipping."
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, pull request
+guidelines, and the release process.
+
+## License
+
+[MIT](LICENSE)

serpapi_hermes_plugin-0.1.0/README.md

@@ -0,0 +1,164 @@
+# SerpApi for Hermes Agent
+
+Give [Hermes Agent](https://hermes-agent.nousresearch.com/) fast, fresh search
+results from the web, Google Maps, Google News, and Google Shopping with
+[SerpApi](https://serpapi.com/).
+
+The plugin adds SerpApi to Hermes in two ways:
+
+- Hermes's built-in `web_search` uses the fast Google Light engine.
+- Dedicated Maps, News, and Shopping tools let Hermes choose the right SerpApi
+  engine for local places, current reporting, and product searches.
+
+## Ask Hermes to install it
+
+You can let Hermes install and configure the plugin for you. Paste the message
+below into a Hermes chat, then approve the install or terminal commands if
+Hermes prompts you:
+
+```text
+Install serpapi-hermes-plugin into the same Python environment that runs this
+Hermes Agent. If this is a standard Hermes installation, run:
+
+cd ~/.hermes/hermes-agent
+uv pip install --python venv/bin/python serpapi-hermes-plugin
+
+Otherwise, use the active Hermes Python environment to run:
+
+uv pip install --python /path/to/hermes/python serpapi-hermes-plugin
+
+Request my approval for install or terminal commands whenever required; do not
+bypass approvals. After the package is installed, run:
+
+hermes plugins enable serpapi
+
+If Hermes asks whether to allow this plugin to replace built-in tools, answer
+no; serpapi-hermes-plugin does not need tool-override access.
+
+Then ask me for my SerpApi Private API Key, which I can copy from the SerpApi
+dashboard. Do not ask for the key until installation and enablement succeed.
+After I provide it, save it as SERPAPI_API_KEY in ~/.hermes/.env without
+printing, logging, or committing it. Configure SerpApi as the Hermes web search
+backend, tell me whether Hermes must be restarted, and verify that web search,
+Maps, News, and Shopping tools are available. Use this key for future SerpApi
+searches and never expose it in output.
+```
+
+## Install
+
+You need a working
+[Hermes Agent installation](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/)
+and a SerpApi account.
+
+Install the plugin from PyPI in the same Python environment as Hermes. If you
+installed Hermes with its standard installer, use its `venv` interpreter
+explicitly:
+
+```bash
+cd ~/.hermes/hermes-agent
+uv pip install --python venv/bin/python serpapi-hermes-plugin
+```
+
+The explicit `--python` is important: the standard Hermes installer creates a
+directory named `venv`, while bare `uv pip install` automatically looks for a
+directory named `.venv`.
+
+For a custom Hermes installation, point uv at the Python interpreter that runs
+Hermes:
+
+```bash
+uv pip install --python /path/to/hermes/python serpapi-hermes-plugin
+```
+
+If that environment already has pip and is activated, the equivalent command
+is `python -m pip install serpapi-hermes-plugin`.
+
+Restart any running Hermes session after installation.
+
+## Get your SerpApi API key
+
+1. [Create a SerpApi account](https://serpapi.com/users/sign_up), or sign in to
+   your existing account.
+2. Open the [SerpApi dashboard](https://serpapi.com/dashboard).
+3. Find your **Private API Key** in the dashboard and copy it.
+
+One API key powers every engine in this plugin. Keep it private and never add it
+to source control.
+
+## Connect the API key to Hermes
+
+Enable the installed plugin:
+
+```bash
+hermes plugins enable serpapi
+```
+
+If prompted about permission to replace built-in tools, answer **no**. This
+plugin adds new tools and a web-search provider; it does not replace built-in
+tool handlers.
+
+Open Hermes's interactive tool configuration:
+
+```bash
+hermes tools
+```
+
+In the **Web Search & Extract** section:
+
+1. Select **SerpApi**.
+2. Paste the Private API Key copied from your SerpApi dashboard.
+3. Confirm the selection.
+
+Hermes saves the key as `SERPAPI_API_KEY` in its environment configuration and
+selects SerpApi for future `web_search` calls. Restart Hermes if a session was
+already running.
+
+## Manual API-key setup
+
+Instead of using `hermes tools`, add the key to `~/.hermes/.env`:
+
+```dotenv
+SERPAPI_API_KEY=your_private_api_key
+```
+
+Then configure `~/.hermes/config.yaml`:
+
+```yaml
+plugins:
+  enabled:
+    - serpapi
+
+web:
+  search_backend: serpapi
+```
+
+You may also export `SERPAPI_API_KEY` in the environment that starts Hermes.
+The environment variable takes precedence over the value in `~/.hermes/.env`.
+
+## Search capabilities
+
+| What you ask for | Hermes tool | SerpApi engine |
+|---|---|---|
+| General web research | `web_search` | `google_light` |
+| Places and local businesses | `serpapi_maps_search` | `google_maps` |
+| Current and recent news | `serpapi_news_search` | `google_news_light` |
+| Products, prices, and merchants | `serpapi_shopping_search` | `google_shopping_light` |
+
+Hermes chooses a tool from your request. Each tool selects and validates its own
+SerpApi engine, so you do not need to specify an engine name.
+
+Example prompts:
+
+- "Search the web for the latest Python 3.14 release notes."
+- "Find highly rated coffee shops near Times Square."
+- "Show me recent news about reusable rockets."
+- "Find well-reviewed laptops under $1,200 with free shipping."
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, pull request
+guidelines, and the release process.
+
+## License
+
+[MIT](LICENSE)

serpapi_hermes_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=77,<83"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serpapi-hermes-plugin"
+version = "0.1.0"
+description = "SerpApi search plugin for Hermes Agent: web, Maps, News, and Shopping"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SerpApi" }]
+keywords = ["hermes-agent", "plugin", "serpapi", "web-search", "maps", "news", "shopping"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Plugins",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = [
+  "httpx>=0.28.1,<1",
+]
+
+[project.entry-points."hermes_agent.plugins"]
+serpapi = "serpapi_hermes_plugin"
+
+[project.urls]
+Homepage = "https://github.com/serpapi/serpapi-hermes-plugin"
+Repository = "https://github.com/serpapi/serpapi-hermes-plugin"
+Issues = "https://github.com/serpapi/serpapi-hermes-plugin/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<10",
+  "ruff>=0.12,<1",
+  "twine>=6.1,<7",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+serpapi_hermes_plugin = ["plugin.yaml", "py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+markers = [
+  "live: makes real SerpApi requests and requires SERPAPI_API_KEY",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]

serpapi_hermes_plugin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serpapi_hermes_plugin-0.1.0/src/serpapi_hermes_plugin/__init__.py

@@ -0,0 +1,30 @@
+"""SerpApi web, Maps, News, and Shopping search for Hermes Agent."""
+
+from __future__ import annotations
+
+from .provider import SerpApiWebSearchProvider
+from .schemas import MAPS_SEARCH_SCHEMA, NEWS_SEARCH_SCHEMA, SHOPPING_SEARCH_SCHEMA
+from .tools import maps_search, news_search, shopping_search
+
+__all__ = ["SerpApiWebSearchProvider", "register"]
+
+
+def register(ctx) -> None:
+    """Register SerpApi's web provider and specialized search tools."""
+    provider = SerpApiWebSearchProvider()
+    ctx.register_web_search_provider(provider)
+
+    for schema, handler in (
+        (MAPS_SEARCH_SCHEMA, maps_search),
+        (NEWS_SEARCH_SCHEMA, news_search),
+        (SHOPPING_SEARCH_SCHEMA, shopping_search),
+    ):
+        ctx.register_tool(
+            name=schema["name"],
+            toolset="serpapi",
+            schema=schema,
+            handler=handler,
+            check_fn=provider.is_available,
+            requires_env=["SERPAPI_API_KEY"],
+            description=schema["description"],
+        )

serpapi_hermes_plugin-0.1.0/src/serpapi_hermes_plugin/client.py

@@ -0,0 +1,98 @@
+"""Shared SerpApi HTTP client for the provider and specialized tools."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+API_KEY_ENV = "SERPAPI_API_KEY"
+ENDPOINT = "https://serpapi.com/search.json"
+TIMEOUT_SECONDS = 15.0
+
+
+class SerpApiError(RuntimeError):
+    """A safe, user-facing SerpApi request error."""
+
+
+def get_api_key() -> str:
+    """Read the key through Hermes so values in ``~/.hermes/.env`` work."""
+    from agent.web_search_provider import get_provider_env
+
+    return get_provider_env(API_KEY_ENV)
+
+
+def is_configured() -> bool:
+    """Return whether Hermes can resolve a SerpApi API key locally."""
+    return bool(get_api_key())
+
+
+def _safe_api_error(value: Any, api_key: str) -> str:
+    """Return a bounded API error without ever echoing the credential."""
+    message = str(value or "Unknown SerpApi error").replace(api_key, "[redacted]")
+    return message[:500]
+
+
+def call_serpapi(engine: str, params: Mapping[str, Any]) -> dict[str, Any]:
+    """Call one SerpApi engine and return its decoded JSON response."""
+    api_key = get_api_key()
+    if not api_key:
+        raise SerpApiError(f"{API_KEY_ENV} is not set. Run `hermes tools` to configure SerpApi.")
+
+    request_params = {
+        key: value
+        for key, value in params.items()
+        if key not in {"api_key", "engine"} and value is not None and value != ""
+    }
+    request_params.update(
+        {
+            "engine": engine,
+            "api_key": api_key,
+            "output": "json",
+        }
+    )
+
+    try:
+        response = httpx.get(
+            ENDPOINT,
+            params=request_params,
+            headers={
+                "Accept": "application/json",
+                "X-Client-Source": "hermes",
+            },
+            timeout=TIMEOUT_SECONDS,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        logger.warning("SerpApi returned HTTP %d", status)
+        if status == 401:
+            message = "SerpApi rejected the API key"
+        elif status == 429:
+            message = "SerpApi quota exhausted; try again later"
+        elif status >= 500:
+            message = f"SerpApi upstream error (HTTP {status}); try again shortly"
+        else:
+            message = f"SerpApi request failed (HTTP {status})"
+        raise SerpApiError(message) from None
+    except httpx.RequestError as exc:
+        logger.warning("SerpApi request failed (%s)", type(exc).__name__)
+        raise SerpApiError("Could not reach SerpApi; try again shortly") from None
+
+    try:
+        payload = response.json()
+    except ValueError:
+        logger.warning("SerpApi returned malformed JSON")
+        raise SerpApiError("SerpApi returned malformed JSON") from None
+
+    if not isinstance(payload, dict):
+        raise SerpApiError("SerpApi returned an unexpected response")
+
+    if payload.get("error"):
+        raise SerpApiError(_safe_api_error(payload["error"], api_key))
+
+    return payload

serpapi_hermes_plugin-0.1.0/src/serpapi_hermes_plugin/plugin.yaml

@@ -0,0 +1,16 @@
+name: serpapi
+version: 0.1.0
+description: "SerpApi search for Hermes Agent: web, Maps, News, and Shopping."
+author: SerpApi
+kind: backend
+provides_web_providers:
+  - serpapi
+provides_tools:
+  - serpapi_maps_search
+  - serpapi_news_search
+  - serpapi_shopping_search
+requires_env:
+  - name: SERPAPI_API_KEY
+    description: "API key for SerpApi web search"
+    url: "https://serpapi.com/manage-api-key"
+    secret: true

serpapi_hermes_plugin-0.1.0/src/serpapi_hermes_plugin/provider.py

@@ -0,0 +1,94 @@
+"""Hermes web-search provider backed by SerpApi's Google Light API."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agent.web_search_provider import WebSearchProvider
+
+from .client import API_KEY_ENV, SerpApiError, call_serpapi, is_configured
+
+logger = logging.getLogger(__name__)
+
+_ENGINE = "google_light"
+_MAX_RESULTS = 20
+
+
+class SerpApiWebSearchProvider(WebSearchProvider):
+    """Search-only Hermes provider using SerpApi's low-latency Google Light engine."""
+
+    @property
+    def name(self) -> str:
+        return "serpapi"
+
+    @property
+    def display_name(self) -> str:
+        return "SerpApi"
+
+    def is_available(self) -> bool:
+        """Check local configuration without making a network request."""
+        return is_configured()
+
+    def supports_search(self) -> bool:
+        return True
+
+    def supports_extract(self) -> bool:
+        return False
+
+    def search(self, query: str, limit: int = 5) -> dict[str, Any]:
+        """Search Google Light and return Hermes's standard web result envelope."""
+        query = str(query or "").strip()
+        if not query:
+            return {"success": False, "error": "Search query must not be empty"}
+
+        try:
+            result_limit = max(1, min(int(limit), _MAX_RESULTS))
+        except (TypeError, ValueError):
+            result_limit = 5
+
+        try:
+            payload = call_serpapi(
+                _ENGINE,
+                {
+                    "q": query,
+                    "num": result_limit,
+                },
+            )
+        except SerpApiError as exc:
+            return {"success": False, "error": str(exc)}
+
+        organic_results = payload.get("organic_results", [])
+        if not isinstance(organic_results, list):
+            return {"success": False, "error": "SerpApi returned an unexpected response"}
+
+        web_results = []
+        for result in organic_results[:result_limit]:
+            if not isinstance(result, dict):
+                continue
+            web_results.append(
+                {
+                    "title": str(result.get("title", "")),
+                    "url": str(result.get("link", "")),
+                    "description": str(result.get("snippet", "")),
+                    "position": len(web_results) + 1,
+                }
+            )
+
+        logger.info("SerpApi search returned %d result(s)", len(web_results))
+        return {"success": True, "data": {"web": web_results}}
+
+    def get_setup_schema(self) -> dict[str, Any]:
+        """Describe SerpApi to Hermes's interactive provider picker."""
+        return {
+            "name": "SerpApi",
+            "badge": "Google Light",
+            "tag": "Fast Google Light web search via SerpApi.",
+            "env_vars": [
+                {
+                    "key": API_KEY_ENV,
+                    "prompt": "SerpApi API key",
+                    "url": "https://serpapi.com/manage-api-key",
+                }
+            ],
+        }

serpapi_hermes_plugin-0.1.0/src/serpapi_hermes_plugin/py.typed

@@ -0,0 +1 @@
+