hermes-plugin-tinyfish 0.1.3__py3-none-any.whl

hermes_plugin_tinyfish/__init__.py

@@ -0,0 +1,35 @@
+"""TinyFish provider plugin for Hermes Agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+
+def register(ctx: Any) -> None:
+    """Register the TinyFish web provider and CLI setup commands."""
+
+    from .provider import TinyFishWebSearchProvider
+    from .setup_cli import dispatch_tinyfish_cli, setup_tinyfish_cli
+
+    provider = TinyFishWebSearchProvider(dispatch_tool=getattr(ctx, "dispatch_tool", None))
+    ctx.register_web_search_provider(provider)
+    ctx.register_cli_command(
+        name="tinyfish",
+        help="Configure and diagnose the TinyFish web provider",
+        setup_fn=setup_tinyfish_cli,
+        handler_fn=dispatch_tinyfish_cli,
+        description="Configure TinyFish MCP OAuth, API-key fallback, and Hermes web backend routing.",
+    )
+
+
+def __getattr__(name: str) -> Any:
+    if name == "TinyFishWebSearchProvider":
+        from .provider import TinyFishWebSearchProvider
+
+        return TinyFishWebSearchProvider
+    raise AttributeError(name)
+
+
+__all__ = ["TinyFishWebSearchProvider", "register"]

hermes_plugin_tinyfish/normalize.py

@@ -0,0 +1,175 @@
+"""Normalize TinyFish MCP and REST payloads into Hermes web-provider shapes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+
+class TinyFishPayloadError(ValueError):
+    """Raised when a TinyFish or MCP payload reports an error."""
+
+
+def parse_jsonish(value: Any) -> Any:
+    """Parse JSON strings when possible and return other values unchanged."""
+
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return text
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def unwrap_mcp_payload(raw: Any) -> Any:
+    """Convert Hermes' MCP wrapper output to the underlying TinyFish payload."""
+
+    payload = parse_jsonish(raw)
+    if isinstance(payload, dict) and payload.get("error"):
+        raise TinyFishPayloadError(str(payload["error"]))
+
+    if isinstance(payload, dict) and "structuredContent" in payload:
+        structured = payload.get("structuredContent")
+        if structured is not None:
+            return structured
+
+    if isinstance(payload, dict) and "result" in payload:
+        result = parse_jsonish(payload.get("result"))
+        if isinstance(result, dict) and result.get("error"):
+            raise TinyFishPayloadError(str(result["error"]))
+        return result
+
+    return payload
+
+
+def normalize_search_response(payload: Any, limit: int = 5) -> dict[str, Any]:
+    """Return Hermes' standard web-search response envelope."""
+
+    data = unwrap_mcp_payload(payload)
+    if isinstance(data, list):
+        results = data
+    elif isinstance(data, dict):
+        if data.get("error"):
+            raise TinyFishPayloadError(str(data["error"]))
+        if isinstance(data.get("data"), dict) and isinstance(data["data"].get("web"), list):
+            return {
+                "success": True,
+                "data": {"web": data["data"]["web"][: max(1, int(limit or 5))]},
+            }
+        results = data.get("results") or data.get("web") or []
+    else:
+        results = []
+
+    count = max(1, int(limit or 5))
+    web_results: list[dict[str, Any]] = []
+    for idx, item in enumerate(list(results)[:count]):
+        if not isinstance(item, dict):
+            continue
+        url = str(item.get("url") or item.get("link") or "")
+        web_results.append(
+            {
+                "title": str(item.get("title") or item.get("site_name") or url),
+                "url": url,
+                "description": str(
+                    item.get("snippet")
+                    or item.get("description")
+                    or item.get("content")
+                    or item.get("text")
+                    or ""
+                ),
+                "position": int(item.get("position") or idx + 1),
+            }
+        )
+    return {"success": True, "data": {"web": web_results}}
+
+
+def normalize_fetch_documents(payload: Any, fallback_urls: list[str] | None = None) -> list[dict[str, Any]]:
+    """Return Hermes' standard extract document list."""
+
+    urls = list(fallback_urls or [])
+    data = unwrap_mcp_payload(payload)
+    if isinstance(data, dict) and data.get("error"):
+        raise TinyFishPayloadError(str(data["error"]))
+
+    if isinstance(data, dict) and isinstance(data.get("data"), list):
+        return cast(list[dict[str, Any]], data["data"])
+
+    if isinstance(data, dict):
+        results = data.get("results") or data.get("documents") or []
+        errors = data.get("errors") or data.get("failed_results") or []
+    elif isinstance(data, list):
+        results = data
+        errors = []
+    else:
+        results = []
+        errors = []
+
+    documents: list[dict[str, Any]] = []
+    for idx, item in enumerate(list(results)):
+        if isinstance(item, str):
+            url = urls[idx] if idx < len(urls) else ""
+            documents.append(
+                {
+                    "url": url,
+                    "title": "",
+                    "content": item,
+                    "raw_content": item,
+                    "metadata": {"sourceURL": url},
+                }
+            )
+            continue
+        if not isinstance(item, dict):
+            continue
+        url = str(item.get("url") or item.get("final_url") or (urls[idx] if idx < len(urls) else ""))
+        raw = str(
+            item.get("text") or item.get("markdown") or item.get("raw_content") or item.get("content") or ""
+        )
+        documents.append(
+            {
+                "url": url,
+                "title": str(item.get("title") or ""),
+                "content": raw,
+                "raw_content": raw,
+                "metadata": {
+                    "sourceURL": url,
+                    "finalURL": str(item.get("final_url") or url),
+                    "description": str(item.get("description") or ""),
+                    "language": str(item.get("language") or ""),
+                },
+            }
+        )
+
+    for idx, item in enumerate(list(errors)):
+        if isinstance(item, dict):
+            url = str(item.get("url") or (urls[idx] if idx < len(urls) else ""))
+            error = str(item.get("error") or item.get("message") or "fetch failed")
+        else:
+            url = urls[idx] if idx < len(urls) else ""
+            error = str(item)
+        documents.append(
+            {
+                "url": url,
+                "title": "",
+                "content": "",
+                "raw_content": "",
+                "error": error,
+                "metadata": {"sourceURL": url},
+            }
+        )
+
+    if not documents and urls:
+        return [
+            {
+                "url": url,
+                "title": "",
+                "content": "",
+                "raw_content": "",
+                "error": "TinyFish returned no content",
+                "metadata": {"sourceURL": url},
+            }
+            for url in urls
+        ]
+    return documents

hermes_plugin_tinyfish/provider.py

@@ -0,0 +1,271 @@
+"""Hermes WebSearchProvider implementation for TinyFish."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from typing import Any, cast
+
+try:
+    from agent.web_search_provider import WebSearchProvider as _HermesWebSearchProvider
+except Exception:  # pragma: no cover - lets package import outside Hermes
+
+    class _HermesWebSearchProvider:  # type: ignore[no-redef]
+        pass
+
+
+from . import rest_client
+from .normalize import TinyFishPayloadError, normalize_fetch_documents, normalize_search_response
+
+logger = logging.getLogger(__name__)
+
+MCP_SERVER_NAME = "tinyfish"
+MCP_SEARCH_TOOLS = (
+    "mcp__tinyfish__search",
+    "mcp_tinyfish_search",
+)
+MCP_FETCH_TOOLS = (
+    "mcp__tinyfish__fetch_content",
+    "mcp__tinyfish__fetch",
+    "mcp_tinyfish_fetch_content",
+    "mcp_tinyfish_fetch",
+)
+
+
+def _provider_env(name: str) -> str:
+    """Read Hermes config-aware environment values when available."""
+
+    try:
+        from agent.web_search_provider import get_provider_env
+
+        return str(get_provider_env(name) or "").strip()
+    except Exception:
+        return str(os.getenv(name, "") or "").strip()
+
+
+def _registry() -> Any | None:
+    try:
+        from tools.registry import registry
+
+        return registry
+    except Exception:
+        return None
+
+
+def _registered_tool_names() -> set[str]:
+    registry = _registry()
+    if registry is None:
+        return set()
+    try:
+        return set(registry.get_all_tool_names())
+    except Exception:
+        pass
+    try:
+        return set(getattr(registry, "_tools", {}).keys())
+    except Exception:
+        return set()
+
+
+def _tinyfish_mcp_configured() -> bool:
+    try:
+        from hermes_cli.config import load_config
+
+        config = load_config() or {}
+    except Exception:
+        return False
+    mcp_config = (config.get("mcp_servers") or {}).get(MCP_SERVER_NAME) or {}
+    return bool(mcp_config.get("url") and mcp_config.get("auth") == "oauth")
+
+
+def _discover_tinyfish_mcp_tools() -> None:
+    """Register configured MCP tools for this process without prompting for OAuth."""
+
+    if not _tinyfish_mcp_configured():
+        return
+    try:
+        from tools.mcp_oauth import suppress_interactive_oauth
+    except Exception:
+        suppress_interactive_oauth = None
+
+    try:
+        from tools.mcp_tool import discover_mcp_tools
+    except Exception:
+        return
+
+    if suppress_interactive_oauth is None:
+        discover_mcp_tools()
+        return
+    with suppress_interactive_oauth():
+        discover_mcp_tools()
+
+
+def _first_registered(candidates: tuple[str, ...]) -> str | None:
+    names = _registered_tool_names()
+    for candidate in candidates:
+        if candidate in names:
+            return candidate
+    return None
+
+
+class TinyFishWebSearchProvider(_HermesWebSearchProvider):  # type: ignore[misc]
+    """TinyFish search and extract provider.
+
+    The provider prefers TinyFish's hosted MCP server because that path uses
+    OAuth and Hermes' built-in MCP token storage. If MCP tools are unavailable,
+    it falls back to direct REST calls using ``TINYFISH_API_KEY``.
+    """
+
+    def __init__(self, dispatch_tool: Callable[[str, dict[str, Any]], str] | None = None):
+        self._dispatch_tool = dispatch_tool
+
+    @property
+    def name(self) -> str:
+        return "tinyfish"
+
+    @property
+    def display_name(self) -> str:
+        return "TinyFish"
+
+    def is_available(self) -> bool:
+        """Cheap availability check: registered MCP tools or API key only."""
+
+        return bool(
+            _first_registered(MCP_SEARCH_TOOLS)
+            or _first_registered(MCP_FETCH_TOOLS)
+            or _provider_env("TINYFISH_API_KEY")
+        )
+
+    def supports_search(self) -> bool:
+        return True
+
+    def supports_extract(self) -> bool:
+        return True
+
+    def supports_crawl(self) -> bool:
+        return False
+
+    def get_setup_schema(self) -> dict[str, Any]:
+        return {
+            "name": "TinyFish",
+            "badge": "free search/fetch",
+            "tag": "OAuth MCP preferred; TINYFISH_API_KEY REST fallback.",
+            "env_vars": [
+                {
+                    "key": "TINYFISH_API_KEY",
+                    "prompt": "TinyFish API key (fallback when MCP OAuth is not configured)",
+                    "url": "https://agent.tinyfish.ai/api-keys",
+                }
+            ],
+        }
+
+    def _dispatch_registered_tool(self, tool_name: str, args: dict[str, Any]) -> str:
+        if self._dispatch_tool is not None:
+            return self._dispatch_tool(tool_name, args)
+        registry = _registry()
+        if registry is None:
+            raise TinyFishPayloadError("Hermes tool registry is not available")
+        return cast(str, registry.dispatch(tool_name, args))
+
+    def _call_mcp(self, candidates: tuple[str, ...], args: dict[str, Any]) -> Any | None:
+        tool_name = _first_registered(candidates)
+        if tool_name is None:
+            _discover_tinyfish_mcp_tools()
+            tool_name = _first_registered(candidates)
+        if tool_name is None:
+            return None
+        logger.debug("TinyFish using MCP tool %s", tool_name)
+        return self._dispatch_registered_tool(tool_name, args)
+
+    def search(self, query: str, limit: int = 5) -> dict[str, Any]:
+        try:
+            from tools.interrupt import is_interrupted
+
+            if is_interrupted():
+                return {"success": False, "error": "Interrupted"}
+        except Exception:
+            pass
+
+        mcp_error = ""
+        try:
+            payload = self._call_mcp(MCP_SEARCH_TOOLS, {"query": query})
+            if payload is not None:
+                return normalize_search_response(payload, limit=limit)
+        except Exception as exc:  # noqa: BLE001 - REST fallback may still work
+            mcp_error = str(exc)
+            logger.info("TinyFish MCP search unavailable, trying REST fallback: %s", exc)
+
+        api_key = _provider_env("TINYFISH_API_KEY")
+        if not api_key:
+            suffix = f" MCP error: {mcp_error}" if mcp_error else ""
+            return {
+                "success": False,
+                "error": (
+                    "TinyFish is not configured. Run `hermes tinyfish setup` "
+                    "to configure MCP OAuth, or set TINYFISH_API_KEY for REST fallback." + suffix
+                ),
+            }
+
+        try:
+            raw = rest_client.search(query, api_key=api_key)
+            return normalize_search_response(raw, limit=limit)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("TinyFish REST search failed: %s", exc)
+            detail = f"; MCP error: {mcp_error}" if mcp_error else ""
+            return {"success": False, "error": f"TinyFish search failed: {exc}{detail}"}
+
+    def extract(self, urls: list[str], **kwargs: Any) -> list[dict[str, Any]]:
+        try:
+            from tools.interrupt import is_interrupted
+
+            if is_interrupted():
+                return [{"url": url, "title": "", "content": "", "error": "Interrupted"} for url in urls]
+        except Exception:
+            pass
+
+        output_format = str(kwargs.get("format") or kwargs.get("output_format") or "markdown")
+        mcp_error = ""
+        try:
+            payload = self._call_mcp(
+                MCP_FETCH_TOOLS,
+                {"urls": urls, "format": output_format},
+            )
+            if payload is not None:
+                return normalize_fetch_documents(payload, fallback_urls=urls)
+        except Exception as exc:  # noqa: BLE001 - REST fallback may still work
+            mcp_error = str(exc)
+            logger.info("TinyFish MCP fetch unavailable, trying REST fallback: %s", exc)
+
+        api_key = _provider_env("TINYFISH_API_KEY")
+        if not api_key:
+            suffix = f" MCP error: {mcp_error}" if mcp_error else ""
+            return [
+                {
+                    "url": url,
+                    "title": "",
+                    "content": "",
+                    "raw_content": "",
+                    "error": (
+                        "TinyFish is not configured. Run `hermes tinyfish setup` "
+                        "to configure MCP OAuth, or set TINYFISH_API_KEY for REST fallback." + suffix
+                    ),
+                }
+                for url in urls
+            ]
+
+        try:
+            raw = rest_client.fetch(urls, api_key=api_key, output_format=output_format)
+            return normalize_fetch_documents(raw, fallback_urls=urls)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("TinyFish REST fetch failed: %s", exc)
+            detail = f"; MCP error: {mcp_error}" if mcp_error else ""
+            return [
+                {
+                    "url": url,
+                    "title": "",
+                    "content": "",
+                    "raw_content": "",
+                    "error": f"TinyFish fetch failed: {exc}{detail}",
+                }
+                for url in urls
+            ]

hermes_plugin_tinyfish/rest_client.py

@@ -0,0 +1,64 @@
+"""TinyFish REST API client used as the API-key fallback path."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import httpx
+
+SEARCH_URL = "https://api.search.tinyfish.ai"
+FETCH_URL = "https://api.fetch.tinyfish.ai"
+
+
+class TinyFishRestError(RuntimeError):
+    """Raised for TinyFish REST transport or HTTP failures."""
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {"X-API-Key": api_key, "Accept": "application/json"}
+
+
+def search(query: str, *, api_key: str, timeout: float = 30.0) -> dict[str, Any]:
+    """Run a TinyFish Search API query."""
+
+    try:
+        response = httpx.get(
+            SEARCH_URL,
+            params={"query": query},
+            headers=_headers(api_key),
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return cast(dict[str, Any], response.json())
+    except httpx.HTTPStatusError as exc:
+        raise TinyFishRestError(f"TinyFish Search returned HTTP {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        raise TinyFishRestError(f"Could not reach TinyFish Search: {exc}") from exc
+    except ValueError as exc:
+        raise TinyFishRestError("TinyFish Search returned invalid JSON") from exc
+
+
+def fetch(
+    urls: list[str],
+    *,
+    api_key: str,
+    output_format: str = "markdown",
+    timeout: float = 60.0,
+) -> dict[str, Any]:
+    """Run the TinyFish Fetch API for one or more URLs."""
+
+    try:
+        response = httpx.post(
+            FETCH_URL,
+            json={"urls": urls, "format": output_format},
+            headers=_headers(api_key),
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return cast(dict[str, Any], response.json())
+    except httpx.HTTPStatusError as exc:
+        raise TinyFishRestError(f"TinyFish Fetch returned HTTP {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        raise TinyFishRestError(f"Could not reach TinyFish Fetch: {exc}") from exc
+    except ValueError as exc:
+        raise TinyFishRestError("TinyFish Fetch returned invalid JSON") from exc

hermes_plugin_tinyfish/setup_cli.py

@@ -0,0 +1,266 @@
+"""CLI helpers for ``hermes tinyfish``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from .provider import (
+    MCP_FETCH_TOOLS,
+    MCP_SEARCH_TOOLS,
+    TinyFishWebSearchProvider,
+    _discover_tinyfish_mcp_tools,
+)
+
+TINYFISH_MCP_URL = "https://agent.tinyfish.ai/mcp"
+
+
+def setup_tinyfish_cli(parser: argparse.ArgumentParser) -> None:
+    sub = parser.add_subparsers(dest="tinyfish_command")
+
+    setup = sub.add_parser("setup", help="Configure TinyFish for Hermes web search/extract")
+    setup.add_argument("--yes", "-y", action="store_true", help="Accept config changes without prompts")
+    setup.add_argument("--api-key", help="Save TINYFISH_API_KEY as REST fallback")
+    setup.add_argument("--skip-mcp", action="store_true", help="Do not configure TinyFish MCP OAuth")
+    setup.add_argument("--skip-login", action="store_true", help="Do not run `hermes mcp login tinyfish`")
+    setup.add_argument(
+        "--login", action="store_true", help="Run `hermes mcp login tinyfish` after writing config"
+    )
+    setup.add_argument(
+        "--no-web-backend", action="store_true", help="Do not set web.search_backend/extract_backend"
+    )
+    setup.add_argument("--live", action="store_true", help="Run live doctor checks after setup")
+
+    doctor = sub.add_parser("doctor", help="Check TinyFish plugin configuration")
+    doctor.add_argument("--json", action="store_true", help="Print machine-readable JSON")
+    doctor.add_argument("--live", action="store_true", help="Run a live search/fetch check")
+
+    status = sub.add_parser("status", help="Print non-secret TinyFish configuration status")
+    status.add_argument("--json", action="store_true", help="Print machine-readable JSON")
+
+
+def dispatch_tinyfish_cli(args: argparse.Namespace) -> int:
+    command = getattr(args, "tinyfish_command", None) or "status"
+    if command == "setup":
+        return cmd_setup(args)
+    if command == "doctor":
+        return cmd_doctor(args)
+    if command == "status":
+        return cmd_status(args)
+    print("Usage: hermes tinyfish {setup,doctor,status}", file=sys.stderr)
+    return 2
+
+
+def _load_config() -> dict[str, Any]:
+    from hermes_cli.config import load_config
+
+    return dict(load_config() or {})
+
+
+def _save_config(config: dict[str, Any]) -> None:
+    from hermes_cli.config import save_config
+
+    save_config(config)
+
+
+def _get_env(name: str) -> str:
+    try:
+        from hermes_cli.config import get_env_value
+
+        return str(get_env_value(name) or "").strip()
+    except Exception:
+        return str(os.getenv(name, "") or "").strip()
+
+
+def _save_env(name: str, value: str) -> None:
+    from hermes_cli.config import save_env_value
+
+    save_env_value(name, value)
+
+
+def _hermes_home() -> Path:
+    try:
+        from hermes_constants import get_hermes_home
+
+        return Path(get_hermes_home())
+    except Exception:
+        return Path(os.getenv("HERMES_HOME") or Path.home() / ".hermes")
+
+
+def _confirm(question: str, *, default: bool = True, assume_yes: bool = False) -> bool:
+    if assume_yes:
+        return True
+    if not sys.stdin.isatty():
+        return default
+    suffix = "Y/n" if default else "y/N"
+    try:
+        answer = input(f"{question} [{suffix}]: ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return default
+    if not answer:
+        return default
+    return answer in {"y", "yes"}
+
+
+def _prompt_secret(question: str) -> str:
+    import getpass
+
+    try:
+        return getpass.getpass(question).strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return ""
+
+
+def _apply_mcp_config(config: dict[str, Any]) -> None:
+    config.setdefault("mcp_servers", {})["tinyfish"] = {
+        "url": TINYFISH_MCP_URL,
+        "auth": "oauth",
+        "tools": {
+            "include": ["search", "fetch_content"],
+            "resources": False,
+            "prompts": False,
+        },
+    }
+
+
+def _apply_web_backend_config(config: dict[str, Any]) -> None:
+    web = config.setdefault("web", {})
+    web["search_backend"] = "tinyfish"
+    web["extract_backend"] = "tinyfish"
+    if not web.get("backend"):
+        web["backend"] = "tinyfish"
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    config = _load_config()
+
+    if not getattr(args, "skip_mcp", False):
+        _apply_mcp_config(config)
+        print("Configured TinyFish hosted MCP OAuth at https://agent.tinyfish.ai/mcp")
+
+    if not getattr(args, "no_web_backend", False) and _confirm(
+        "Set Hermes web.search_backend and web.extract_backend to tinyfish?",
+        default=True,
+        assume_yes=bool(getattr(args, "yes", False)),
+    ):
+        _apply_web_backend_config(config)
+        print("Configured Hermes web backends to use TinyFish")
+
+    _save_config(config)
+
+    api_key = (getattr(args, "api_key", None) or "").strip()
+    if (
+        not api_key
+        and not _get_env("TINYFISH_API_KEY")
+        and sys.stdin.isatty()
+        and _confirm(
+            "Add TINYFISH_API_KEY as REST fallback now?",
+            default=False,
+            assume_yes=False,
+        )
+    ):
+        api_key = _prompt_secret("TinyFish API key: ")
+    if api_key:
+        _save_env("TINYFISH_API_KEY", api_key)
+        print("Saved TINYFISH_API_KEY fallback in Hermes .env")
+
+    should_login = bool(getattr(args, "login", False))
+    if not should_login and not getattr(args, "skip_login", False) and sys.stdin.isatty():
+        should_login = _confirm("Run `hermes mcp login tinyfish` now?", default=True)
+    if should_login:
+        result = subprocess.run(["hermes", "mcp", "login", "tinyfish"], check=False)
+        if result.returncode != 0:
+            print("TinyFish MCP login did not complete. You can retry with `hermes mcp login tinyfish`.")
+
+    if getattr(args, "live", False):
+        doctor_args = argparse.Namespace(json=False, live=True)
+        return cmd_doctor(doctor_args)
+
+    print("Run `hermes tinyfish doctor --live` to verify the setup.")
+    return 0
+
+
+def _tool_names(*, discover_mcp: bool = False) -> set[str]:
+    if discover_mcp:
+        _discover_tinyfish_mcp_tools()
+    try:
+        from tools.registry import registry
+
+        return set(registry.get_all_tool_names())
+    except Exception:
+        return set()
+
+
+def collect_status(*, live: bool = False) -> dict[str, Any]:
+    config = _load_config()
+    mcp_cfg = (config.get("mcp_servers") or {}).get("tinyfish") or {}
+    web_cfg = config.get("web") or {}
+    names = _tool_names(discover_mcp=live)
+    token_path = _hermes_home() / "mcp-tokens" / "tinyfish.json"
+    api_key_configured = bool(_get_env("TINYFISH_API_KEY"))
+    provider = TinyFishWebSearchProvider()
+
+    checks: dict[str, Any] = {
+        "plugin_loaded": True,
+        "provider_available": provider.is_available(),
+        "mcp_configured": bool(mcp_cfg.get("url") == TINYFISH_MCP_URL and mcp_cfg.get("auth") == "oauth"),
+        "mcp_search_tool_registered": any(name in names for name in MCP_SEARCH_TOOLS),
+        "mcp_fetch_tool_registered": any(name in names for name in MCP_FETCH_TOOLS),
+        "mcp_token_cached": token_path.exists(),
+        "api_key_fallback_configured": api_key_configured,
+        "web_search_backend": web_cfg.get("search_backend") or web_cfg.get("backend") or "",
+        "web_extract_backend": web_cfg.get("extract_backend") or web_cfg.get("backend") or "",
+    }
+
+    checks["web_backend_configured"] = (
+        checks["web_search_backend"] == "tinyfish" and checks["web_extract_backend"] == "tinyfish"
+    )
+
+    if live:
+        search = provider.search("TinyFish web agent", limit=1)
+        checks["live_search_ok"] = bool(search.get("success") and search.get("data", {}).get("web"))
+        fetch = provider.extract(["https://docs.tinyfish.ai/"], format="markdown")
+        checks["live_fetch_ok"] = bool(fetch and not fetch[0].get("error"))
+
+    checks["ok"] = bool(
+        checks["web_backend_configured"]
+        and (checks["mcp_configured"] or checks["api_key_fallback_configured"])
+    )
+    return checks
+
+
+def _print_status(status: dict[str, Any]) -> None:
+    print("TinyFish Hermes plugin status")
+    for key in sorted(status):
+        value = status[key]
+        if isinstance(value, bool):
+            value = "yes" if value else "no"
+        print(f"  {key}: {value}")
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    status = collect_status(live=False)
+    if getattr(args, "json", False):
+        print(json.dumps(status, indent=2, sort_keys=True))
+    else:
+        _print_status(status)
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    status = collect_status(live=bool(getattr(args, "live", False)))
+    if getattr(args, "json", False):
+        print(json.dumps(status, indent=2, sort_keys=True))
+    else:
+        _print_status(status)
+        if not status["ok"]:
+            print()
+            print("Recommended next step: run `hermes tinyfish setup`.")
+    return 0 if status["ok"] else 1

hermes_plugin_tinyfish-0.1.3.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-tinyfish
+Version: 0.1.3
+Summary: TinyFish web search and extraction provider plugin for Hermes Agent
+Project-URL: Homepage, https://github.com/gabeosx/hermes-plugin-tinyfish
+Project-URL: Documentation, https://github.com/gabeosx/hermes-plugin-tinyfish#readme
+Project-URL: Issues, https://github.com/gabeosx/hermes-plugin-tinyfish/issues
+Project-URL: Changelog, https://github.com/gabeosx/hermes-plugin-tinyfish/blob/main/CHANGELOG.md
+Author: gabeosx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: hermes-agent,mcp,tinyfish,web-extraction,web-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hermes TinyFish Plugin
+
+[![CI](https://github.com/gabeosx/hermes-plugin-tinyfish/actions/workflows/ci.yml/badge.svg)](https://github.com/gabeosx/hermes-plugin-tinyfish/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/badge/PyPI-pending-lightgrey.svg)](https://github.com/gabeosx/hermes-plugin-tinyfish/releases)
+[![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Security Policy](https://img.shields.io/badge/Security-policy-green.svg)](SECURITY.md)
+
+TinyFish web search and content extraction for [Hermes Agent](https://hermes-agent.nousresearch.com/docs/).
+
+The plugin adds `tinyfish` as a native Hermes `web_search` and `web_extract`
+backend. It prefers TinyFish's hosted OAuth MCP server and falls back to direct
+REST API calls with `TINYFISH_API_KEY` when MCP OAuth is unavailable.
+
+## Install
+
+Hermes Git plugin install:
+
+```bash
+hermes plugins install gabeosx/hermes-plugin-tinyfish --enable
+hermes tinyfish setup
+```
+
+Hermes' Git plugin installer currently clones the repository default branch.
+Stable release artifacts are published on the
+[GitHub Releases page](https://github.com/gabeosx/hermes-plugin-tinyfish/releases).
+
+PyPI install is planned after PyPI Trusted Publishing is configured:
+
+```bash
+pip install hermes-plugin-tinyfish
+hermes plugins enable web-tinyfish
+hermes tinyfish setup
+```
+
+## What Setup Does
+
+`hermes tinyfish setup` writes ordinary user configuration only:
+
+```yaml
+mcp_servers:
+  tinyfish:
+    url: https://agent.tinyfish.ai/mcp
+    auth: oauth
+    tools:
+      include: [search, fetch_content]
+      resources: false
+      prompts: false
+
+web:
+  search_backend: tinyfish
+  extract_backend: tinyfish
+```
+
+It may also save `TINYFISH_API_KEY` to `~/.hermes/.env` if you choose to add
+an API-key fallback.
+
+The plugin does not patch Hermes Agent, update scripts, Dockerfiles, or any
+files inside a Hermes checkout.
+
+## Verify
+
+```bash
+hermes tinyfish doctor
+hermes tinyfish doctor --live
+```
+
+`doctor --live` performs a real TinyFish search and fetch. It requires either
+working MCP OAuth or `TINYFISH_API_KEY`.
+
+## Manual Configuration
+
+OAuth MCP only:
+
+```bash
+hermes mcp add tinyfish --url https://agent.tinyfish.ai/mcp --auth oauth
+hermes mcp login tinyfish
+hermes mcp configure tinyfish
+```
+
+Then set:
+
+```yaml
+web:
+  search_backend: tinyfish
+  extract_backend: tinyfish
+```
+
+REST fallback only:
+
+```bash
+export TINYFISH_API_KEY="..."
+```
+
+## Upgrade Safety
+
+This plugin uses public Hermes extension points:
+
+- `ctx.register_web_search_provider(...)`
+- `ctx.register_cli_command(...)`
+- Hermes MCP config under `mcp_servers`
+- Hermes `.env` config helpers for optional API-key fallback
+
+Because it is installed as a user plugin or Python entry point, normal
+`hermes update` operations do not overwrite it.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+ruff format .
+ruff check .
+mypy hermes_plugin_tinyfish
+pytest
+python -m build
+```
+
+Live tests are opt-in:
+
+```bash
+TINYFISH_LIVE_TESTS=1 TINYFISH_API_KEY=... pytest tests/test_live.py
+```
+
+## References
+
+- [TinyFish MCP Integration](https://docs.tinyfish.ai/mcp-integration)
+- [TinyFish Authentication](https://docs.tinyfish.ai/authentication)
+- [TinyFish Search API](https://docs.tinyfish.ai/search-api)
+- [TinyFish Fetch API](https://docs.tinyfish.ai/fetch-api)
+- [Hermes Web Search Provider Plugins](https://hermes-agent.nousresearch.com/docs/developer-guide/web-search-provider-plugin)
+- [Hermes Plugins](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins)
+- [Hermes MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

hermes_plugin_tinyfish-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+hermes_plugin_tinyfish/__init__.py,sha256=kYdF_yi9sAGVi-3CitDlIXDaP-z7OF-AOIg5XB2v9Vk,1069
+hermes_plugin_tinyfish/normalize.py,sha256=UR7iwSC57wks88GnvSSWzXWImGOKvWpHVW0imcbFJ8M,5899
+hermes_plugin_tinyfish/provider.py,sha256=5rvkpse7hu2KhCBt54JPmDUZaW3rpprrIltjZcaHQiE,9003
+hermes_plugin_tinyfish/rest_client.py,sha256=bHVpF0CJ-T5kSoFCL1O97P7YAyuyQwSOVxefRbQI7Pk,2091
+hermes_plugin_tinyfish/setup_cli.py,sha256=WbDa61oPQzGQYJMCtyxoXUUJb2YBrL6QtubR-00Tn4U,9031
+hermes_plugin_tinyfish-0.1.3.dist-info/METADATA,sha256=fTZb-8VE79MlGO5k4_tgUeAHClkh5zp3op1STNaJBBk,5121
+hermes_plugin_tinyfish-0.1.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hermes_plugin_tinyfish-0.1.3.dist-info/entry_points.txt,sha256=qWGzby0SgzF97ICje8dr15LZyA-PBexEeC96FmruWpg,61
+hermes_plugin_tinyfish-0.1.3.dist-info/licenses/LICENSE,sha256=hy8tmDdq46UUrOKt91rKGzBVtHnQs2Qoqt7i-UtL3m8,1064
+hermes_plugin_tinyfish-0.1.3.dist-info/RECORD,,

hermes_plugin_tinyfish-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

hermes_plugin_tinyfish-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+web-tinyfish = hermes_plugin_tinyfish

hermes_plugin_tinyfish-0.1.3.dist-info/licenses/LICENSE

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