hermes-plugin-tinyfish 0.1.3__tar.gz

hermes_plugin_tinyfish-0.1.3/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/
+htmlcov/

hermes_plugin_tinyfish-0.1.3/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses semantic versioning.
+
+## [0.1.3] - 2026-07-07
+
+### Changed
+
+- Enabled PyPI publication through Trusted Publishing.
+
+## [0.1.2] - 2026-07-06
+
+### Changed
+
+- Corrected public package author metadata to use the repository owner handle.
+
+## [0.1.1] - 2026-07-06
+
+### Changed
+
+- Clarified that Hermes Git plugin installs clone the repository default branch.
+- Added gated PyPI publishing directly to the tag-based release workflow for future releases.
+
+## [0.1.0] - 2026-07-06
+
+### Added
+
+- Initial TinyFish Hermes web provider.
+- OAuth MCP-first routing for search and fetch.
+- REST API-key fallback for `TINYFISH_API_KEY`.
+- `hermes tinyfish setup`, `doctor`, and `status` CLI commands.
+- CI, release, dependency review, and PyPI publishing workflows.

hermes_plugin_tinyfish-0.1.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct.
+
+Be respectful, constructive, and specific. Harassment, abuse, and bad-faith
+participation are not acceptable in issues, pull requests, or discussions.
+
+Maintainers may remove comments, close threads, or block users who violate
+these expectations.

hermes_plugin_tinyfish-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Contributions are welcome.
+
+## 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
+```
+
+## Pull Request Expectations
+
+- Include tests for behavior changes.
+- Keep the plugin upgrade-safe: do not modify Hermes core files, local update
+  scripts, Dockerfiles, or generated user state.
+- Do not log or print API keys, OAuth tokens, or MCP token file contents.
+- Use TinyFish MCP OAuth first when possible and REST API keys only as fallback.

hermes_plugin_tinyfish-0.1.3/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.

hermes_plugin_tinyfish-0.1.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,135 @@
+# 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/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are released for the latest minor version.
+
+## Reporting a Vulnerability
+
+Please report security issues privately by opening a GitHub security advisory
+for this repository. Do not disclose vulnerabilities in public issues until a
+fix is available.
+
+## Design Notes
+
+- The plugin does not modify Hermes Agent source files.
+- The preferred TinyFish authentication path is Hermes' OAuth MCP support.
+- API keys are only used as an explicit REST fallback through
+  `TINYFISH_API_KEY`.
+- `hermes tinyfish status` and `doctor` never print secret values.
+- Live tests are opt-in and are not run by default in CI.

hermes_plugin_tinyfish-0.1.3/__init__.py

@@ -0,0 +1,15 @@
+"""Directory-plugin entry point for ``hermes plugins install``.
+
+Hermes loads this file directly when the repository is installed as a user
+plugin. The package entry point in ``pyproject.toml`` imports the same
+``register`` function when installed from PyPI.
+"""
+
+from __future__ import annotations
+
+try:
+    from .hermes_plugin_tinyfish import register
+except ImportError:  # pragma: no cover - used for pip entry-point import shape
+    from hermes_plugin_tinyfish import register
+
+__all__ = ["register"]

hermes_plugin_tinyfish-0.1.3/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-0.1.3/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