serpapi-hermes-plugin 0.1.0__py3-none-any.whl

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/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/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/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/py.typed

@@ -0,0 +1 @@
+

serpapi_hermes_plugin/schemas.py

@@ -0,0 +1,168 @@
+"""Hermes tool schemas for SerpApi's specialized search engines."""
+
+from __future__ import annotations
+
+MAPS_SEARCH_SCHEMA = {
+    "name": "serpapi_maps_search",
+    "description": (
+        "Search Google Maps through SerpApi for places, local businesses, restaurants, "
+        "shops, attractions, and services. Use this instead of web_search when the user "
+        "wants physical places, ratings, addresses, opening status, or coordinates."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Place or business search, such as 'coffee shops' or 'museums'.",
+            },
+            "location": {
+                "type": "string",
+                "description": "Optional search origin, such as 'New York, NY' or '560001'.",
+            },
+            "latitude": {
+                "type": "number",
+                "minimum": -90,
+                "maximum": 90,
+                "description": "Optional precise search-origin latitude; requires longitude.",
+            },
+            "longitude": {
+                "type": "number",
+                "minimum": -180,
+                "maximum": 180,
+                "description": "Optional precise search-origin longitude; requires latitude.",
+            },
+            "zoom": {
+                "type": "integer",
+                "minimum": 3,
+                "maximum": 30,
+                "default": 14,
+                "description": "Map zoom when a location or coordinates are supplied.",
+            },
+            "nearby": {
+                "type": "boolean",
+                "default": False,
+                "description": "Prioritize results close to the supplied search origin.",
+            },
+            "language": {
+                "type": "string",
+                "description": "Optional two-letter language code, such as 'en' or 'es'.",
+            },
+            "country": {
+                "type": "string",
+                "description": "Optional two-letter country code, such as 'us' or 'in'.",
+            },
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 20,
+                "default": 5,
+                "description": "Maximum number of places to return.",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+}
+
+NEWS_SEARCH_SCHEMA = {
+    "name": "serpapi_news_search",
+    "description": (
+        "Search recent Google News results through SerpApi. Use this for current events, "
+        "breaking news, recent reporting, and coverage from news publications."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "News search query.",
+            },
+            "location": {
+                "type": "string",
+                "description": "Optional city-level origin for geographically relevant news.",
+            },
+            "language": {
+                "type": "string",
+                "description": "Optional two-letter language code, such as 'en' or 'fr'.",
+            },
+            "country": {
+                "type": "string",
+                "description": "Optional two-letter country code, such as 'us' or 'in'.",
+            },
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 20,
+                "default": 5,
+                "description": "Maximum number of news results to return.",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+}
+
+SHOPPING_SEARCH_SCHEMA = {
+    "name": "serpapi_shopping_search",
+    "description": (
+        "Search Google Shopping through SerpApi for products, merchants, prices, ratings, "
+        "and delivery information. Use this for shopping and product-comparison requests."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Product search query.",
+            },
+            "location": {
+                "type": "string",
+                "description": "Optional city-level origin for local prices and availability.",
+            },
+            "language": {
+                "type": "string",
+                "description": "Optional two-letter language code, such as 'en' or 'de'.",
+            },
+            "country": {
+                "type": "string",
+                "description": "Optional two-letter country code, such as 'us' or 'in'.",
+            },
+            "minimum_price": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Optional minimum product price in the selected market currency.",
+            },
+            "maximum_price": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Optional maximum product price in the selected market currency.",
+            },
+            "sort": {
+                "type": "string",
+                "enum": ["relevance", "price_low_to_high", "price_high_to_low"],
+                "default": "relevance",
+                "description": "How to order products.",
+            },
+            "free_shipping": {
+                "type": "boolean",
+                "default": False,
+                "description": "Return only products offering free shipping.",
+            },
+            "on_sale": {
+                "type": "boolean",
+                "default": False,
+                "description": "Return only products currently on sale.",
+            },
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 20,
+                "default": 5,
+                "description": "Maximum number of products to return.",
+            },
+        },
+        "required": ["query"],
+        "additionalProperties": False,
+    },
+}

serpapi_hermes_plugin/tools.py

@@ -0,0 +1,255 @@
+"""Specialized SerpApi tool handlers exposed directly to Hermes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import SerpApiError, call_serpapi
+
+_MAX_RESULTS = 20
+
+
+def _json(value: dict[str, Any]) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _error(message: str) -> str:
+    return _json({"success": False, "error": message})
+
+
+def _query(args: dict[str, Any]) -> str:
+    return str(args.get("query") or "").strip()
+
+
+def _limit(args: dict[str, Any]) -> int:
+    try:
+        return max(1, min(int(args.get("limit", 5)), _MAX_RESULTS))
+    except (TypeError, ValueError):
+        return 5
+
+
+def _code(args: dict[str, Any], name: str) -> str | None:
+    value = str(args.get(name) or "").strip().lower()
+    if not value:
+        return None
+    if len(value) != 2 or not value.isalpha():
+        raise ValueError(f"{name} must be a two-letter code")
+    return value
+
+
+def _optional_fields(item: dict[str, Any], names: tuple[str, ...]) -> dict[str, Any]:
+    return {name: item[name] for name in names if item.get(name) not in (None, "", [])}
+
+
+def maps_search(args: dict[str, Any], **kwargs: Any) -> str:
+    """Search Google Maps for places and local businesses."""
+    del kwargs
+    query = _query(args)
+    if not query:
+        return _error("Search query must not be empty")
+
+    location = str(args.get("location") or "").strip()
+    latitude = args.get("latitude")
+    longitude = args.get("longitude")
+    has_coordinates = latitude is not None or longitude is not None
+    if has_coordinates and (latitude is None or longitude is None):
+        return _error("latitude and longitude must be provided together")
+    if location and has_coordinates:
+        return _error("Use either location or latitude/longitude, not both")
+
+    try:
+        params: dict[str, Any] = {
+            "q": query,
+            "type": "search",
+            "hl": _code(args, "language"),
+            "gl": _code(args, "country"),
+        }
+        if location:
+            params.update({"location": location, "z": int(args.get("zoom", 14))})
+        elif has_coordinates:
+            params.update(
+                {
+                    "lat": float(latitude),
+                    "lon": float(longitude),
+                    "z": int(args.get("zoom", 14)),
+                }
+            )
+        if args.get("nearby"):
+            if not location and not has_coordinates:
+                return _error("nearby requires a location or latitude/longitude")
+            params["nearby"] = "true"
+        payload = call_serpapi("google_maps", params)
+    except (TypeError, ValueError) as exc:
+        return _error(str(exc))
+    except SerpApiError as exc:
+        return _error(str(exc))
+
+    results = []
+    raw_results = payload.get("local_results", [])
+    if not isinstance(raw_results, list):
+        return _error("SerpApi returned an unexpected Google Maps response")
+    for index, item in enumerate(raw_results[: _limit(args)], start=1):
+        if not isinstance(item, dict):
+            continue
+        result = {
+            "position": item.get("position", index),
+            **_optional_fields(
+                item,
+                (
+                    "title",
+                    "type",
+                    "address",
+                    "rating",
+                    "reviews",
+                    "price",
+                    "open_state",
+                    "phone",
+                    "website",
+                    "place_id",
+                ),
+            ),
+        }
+        coordinates = item.get("gps_coordinates")
+        if isinstance(coordinates, dict):
+            result["coordinates"] = coordinates
+        results.append(result)
+
+    return _json(
+        {
+            "success": True,
+            "engine": "google_maps",
+            "query": query,
+            "results_count": len(results),
+            "results": results,
+        }
+    )
+
+
+def news_search(args: dict[str, Any], **kwargs: Any) -> str:
+    """Search Google News Light for recent reporting."""
+    del kwargs
+    query = _query(args)
+    if not query:
+        return _error("Search query must not be empty")
+
+    try:
+        payload = call_serpapi(
+            "google_news_light",
+            {
+                "q": query,
+                "location": str(args.get("location") or "").strip(),
+                "hl": _code(args, "language"),
+                "gl": _code(args, "country"),
+            },
+        )
+    except (TypeError, ValueError) as exc:
+        return _error(str(exc))
+    except SerpApiError as exc:
+        return _error(str(exc))
+
+    results = []
+    raw_results = payload.get("news_results", [])
+    if not isinstance(raw_results, list):
+        return _error("SerpApi returned an unexpected Google News response")
+    for index, item in enumerate(raw_results[: _limit(args)], start=1):
+        if not isinstance(item, dict):
+            continue
+        results.append(
+            {
+                "position": item.get("position", index),
+                **_optional_fields(item, ("title", "link", "source", "date", "snippet")),
+            }
+        )
+
+    return _json(
+        {
+            "success": True,
+            "engine": "google_news_light",
+            "query": query,
+            "results_count": len(results),
+            "results": results,
+        }
+    )
+
+
+def shopping_search(args: dict[str, Any], **kwargs: Any) -> str:
+    """Search Google Shopping Light for products and prices."""
+    del kwargs
+    query = _query(args)
+    if not query:
+        return _error("Search query must not be empty")
+
+    minimum_price = args.get("minimum_price")
+    maximum_price = args.get("maximum_price")
+    if minimum_price is not None and maximum_price is not None:
+        try:
+            if float(minimum_price) > float(maximum_price):
+                return _error("minimum_price must not exceed maximum_price")
+        except (TypeError, ValueError):
+            return _error("minimum_price and maximum_price must be numbers")
+
+    sort_by = {
+        "price_low_to_high": "1",
+        "price_high_to_low": "2",
+    }.get(str(args.get("sort") or "relevance"))
+
+    try:
+        payload = call_serpapi(
+            "google_shopping_light",
+            {
+                "q": query,
+                "location": str(args.get("location") or "").strip(),
+                "hl": _code(args, "language"),
+                "gl": _code(args, "country"),
+                "min_price": minimum_price,
+                "max_price": maximum_price,
+                "sort_by": sort_by,
+                "free_shipping": "true" if args.get("free_shipping") else None,
+                "on_sale": "true" if args.get("on_sale") else None,
+            },
+        )
+    except (TypeError, ValueError) as exc:
+        return _error(str(exc))
+    except SerpApiError as exc:
+        return _error(str(exc))
+
+    results = []
+    raw_results = payload.get("shopping_results", [])
+    if not isinstance(raw_results, list):
+        return _error("SerpApi returned an unexpected Google Shopping response")
+    for index, item in enumerate(raw_results[: _limit(args)], start=1):
+        if not isinstance(item, dict):
+            continue
+        result = {
+            "position": item.get("position", index),
+            **_optional_fields(
+                item,
+                (
+                    "title",
+                    "source",
+                    "price",
+                    "extracted_price",
+                    "old_price",
+                    "rating",
+                    "reviews",
+                    "delivery",
+                    "snippet",
+                    "product_id",
+                ),
+            ),
+        }
+        link = item.get("link") or item.get("product_link")
+        if link:
+            result["link"] = link
+        results.append(result)
+
+    return _json(
+        {
+            "success": True,
+            "engine": "google_shopping_light",
+            "query": query,
+            "results_count": len(results),
+            "results": results,
+        }
+    )

serpapi_hermes_plugin-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+serpapi_hermes_plugin/__init__.py,sha256=KDSW9Cu-OVfMJ7n-XcMvZC3cPdv1x3pTtazwccCjA-E,1008
+serpapi_hermes_plugin/client.py,sha256=vBPB2GhhZCbvo4Q_bX4CQbzPPHG8KzhenEdbYM0DrVs,3094
+serpapi_hermes_plugin/plugin.yaml,sha256=Dr7O5AwCoE498liP9xMvnPjNjNrjCvLsqmwRh59G7jY,419
+serpapi_hermes_plugin/provider.py,sha256=7GclAF8JCXM423YD4OC0NCSxSmzvaCx5xFhn471t8l8,2969
+serpapi_hermes_plugin/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+serpapi_hermes_plugin/schemas.py,sha256=yqjOstdyGI9FJGP9wCcd3mVmy6drX98NBhtRr0OtcQY,6064
+serpapi_hermes_plugin/tools.py,sha256=OnZcC1QLfgN3XrszYNIebv9a2oGiAYRllT0D5G2f6BY,8084
+serpapi_hermes_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=3U38OtHYEdO6tpAyF3_N3kNiLzlaP-gR43Ulqaztlio,1065
+serpapi_hermes_plugin-0.1.0.dist-info/METADATA,sha256=IGxhMzxip2qEHM96jMsOpLq0QemthCjeFDmWnF16ipA,6243
+serpapi_hermes_plugin-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+serpapi_hermes_plugin-0.1.0.dist-info/entry_points.txt,sha256=UKdIGfIw1Qr7a7xok4xUVT8vwY3r1-1RF6F4epZXZv4,55
+serpapi_hermes_plugin-0.1.0.dist-info/top_level.txt,sha256=dQ_7H05QyBzHhcN5vrbAqItW02MJknlOJ6vEmdFNlcI,22
+serpapi_hermes_plugin-0.1.0.dist-info/RECORD,,

serpapi_hermes_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

serpapi_hermes_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+serpapi = serpapi_hermes_plugin

serpapi_hermes_plugin-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+serpapi_hermes_plugin