hermes-plugin-clawrouter 0.1.0__tar.gz

hermes_plugin_clawrouter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlockRun
+
+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_clawrouter-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-clawrouter
+Version: 0.1.0
+Summary: ClawRouter for Hermes — 55+ models, x402 USDC micropayments, smart routing
+Author: BlockRun
+License: MIT
+Project-URL: Homepage, https://github.com/BlockRunAI/ClawRouter
+Project-URL: Repository, https://github.com/BlockRunAI/ClawRouter-Hermes
+Project-URL: Bug Tracker, https://github.com/BlockRunAI/ClawRouter-Hermes/issues
+Keywords: hermes,hermes-agent,clawrouter,x402,llm-router,blockrun
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: bip_utils>=2.9
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# hermes-plugin-clawrouter
+
+ClawRouter for [Hermes](https://github.com/NousResearch/hermes-agent) — 55+ LLMs, x402 USDC micropayments, smart routing.
+
+Wraps the existing [ClawRouter](https://github.com/BlockRunAI/ClawRouter) TypeScript proxy as a Hermes plugin. Wallet (BIP-39, Base + Solana), routing (15-dimension scorer), and x402 payment all stay in the canonical TS implementation — this is a thin Python adapter.
+
+## Install
+
+```bash
+pip install hermes-plugin-clawrouter
+hermes plugins enable clawrouter
+hermes-clawrouter setup
+hermes-clawrouter doctor
+```
+
+`setup` writes the model-provider plugin to `~/.hermes/plugins/model-providers/clawrouter/`, seeds `CLAWROUTER_API_KEY=clawrouter-local` in `~/.hermes/.env`, and registers ClawRouter in `~/.hermes/config.yaml` so Hermes' `/model` picker can show the provider and curated BlockRun chat models.
+
+`hermes-clawrouter` is provided because some Hermes releases do not add plugin-defined top-level CLI commands before the plugin is enabled. Once the plugin is loaded, `hermes clawrouter <setup|wallet|doctor|route|stats>` may also be available.
+
+## Usage
+
+In a Hermes chat:
+
+- Set model to `blockrun/auto` to use ClawRouter's smart routing.
+- `/clawrouter wallet` — address + USDC balance
+- `/clawrouter stats` — proxy usage stats
+- `/clawrouter status` — proxy health
+- `/clawrouter route <eco|auto|premium>` — switch routing profile
+
+Tools (callable from chat):
+
+- `clawrouter_image_generate` — 55+ models incl. DALL-E 3, Flux, Nano Banana
+- `clawrouter_video_generate` — Seedance, Grok Imagine
+- `clawrouter_web_search` — Exa-powered
+
+## Wallet
+
+The plugin **reads** the canonical wallet at `~/.openclaw/blockrun/mnemonic` (24-word BIP-39 phrase, mode 0o600). To create one:
+
+```bash
+npx @blockrun/clawrouter setup
+```
+
+Then fund USDC on Base or Solana — $5 covers thousands of requests, non-custodial. The plugin never writes to the wallet.
+
+### Headless / CI
+
+Set `BLOCKRUN_WALLET_KEY=<0x raw EVM hex>` to bypass the mnemonic file (EVM-only — Solana derivation unavailable).
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `CLAWROUTER_PROXY_URL` | Point at an externally-managed proxy (e.g. `https://my-host/v1`). Skips local spawn entirely. |
+| `HERMES_CLAWROUTER_AUTOSPAWN=0` | Disable lazy spawn; require `npx @blockrun/clawrouter` to be running already. |
+| `BLOCKRUN_WALLET_KEY` | Raw EVM hex private key — overrides the mnemonic file. |
+| `CLAWROUTER_ROUTING_PROFILE` | `eco` / `auto` / `premium`. Forwarded to the proxy on spawn. |
+
+## How it works
+
+1. `hermes` starts → the entry-point plugin is loaded → `register(ctx)` wires tools, slash commands, CLI, and the skill.
+2. `hermes-clawrouter setup` materializes `~/.hermes/plugins/model-providers/clawrouter/{plugin.yaml,__init__.py}` from bundled package data and writes Hermes config/env hints needed by current Hermes provider and gateway model-picker paths.
+3. Hermes' `providers/__init__.py` discovers the materialized directory and registers the `ClawRouterProfile`, pointing `base_url` at `http://127.0.0.1:<port>/v1`.
+4. First tool call or chat turn → the supervisor probes `:8402`, spawns `npx -y @blockrun/clawrouter --port <port>` if needed, waits ≤30s for `/v1/models`, then forwards the request.
+5. A heartbeat thread restarts the subprocess on death (max 3 restarts/min).
+
+## Distribution
+
+The Python package ships **both** logical plugins:
+
+- **Standalone** plugin (this PyPI entry point): tools, slash commands, CLI, skill.
+- **Model-provider** plugin (materialized into `~/.hermes/plugins/model-providers/clawrouter/` by `hermes clawrouter setup`): `ProviderProfile` registration.
+
+This split is required because Hermes' PluginManager (`hermes_cli/plugins.py`) skips `register(ctx)` for `kind: model-provider`, and entry-point plugins always load as `kind: standalone`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. © BlockRun.

hermes_plugin_clawrouter-0.1.0/README.md

@@ -0,0 +1,85 @@
+# hermes-plugin-clawrouter
+
+ClawRouter for [Hermes](https://github.com/NousResearch/hermes-agent) — 55+ LLMs, x402 USDC micropayments, smart routing.
+
+Wraps the existing [ClawRouter](https://github.com/BlockRunAI/ClawRouter) TypeScript proxy as a Hermes plugin. Wallet (BIP-39, Base + Solana), routing (15-dimension scorer), and x402 payment all stay in the canonical TS implementation — this is a thin Python adapter.
+
+## Install
+
+```bash
+pip install hermes-plugin-clawrouter
+hermes plugins enable clawrouter
+hermes-clawrouter setup
+hermes-clawrouter doctor
+```
+
+`setup` writes the model-provider plugin to `~/.hermes/plugins/model-providers/clawrouter/`, seeds `CLAWROUTER_API_KEY=clawrouter-local` in `~/.hermes/.env`, and registers ClawRouter in `~/.hermes/config.yaml` so Hermes' `/model` picker can show the provider and curated BlockRun chat models.
+
+`hermes-clawrouter` is provided because some Hermes releases do not add plugin-defined top-level CLI commands before the plugin is enabled. Once the plugin is loaded, `hermes clawrouter <setup|wallet|doctor|route|stats>` may also be available.
+
+## Usage
+
+In a Hermes chat:
+
+- Set model to `blockrun/auto` to use ClawRouter's smart routing.
+- `/clawrouter wallet` — address + USDC balance
+- `/clawrouter stats` — proxy usage stats
+- `/clawrouter status` — proxy health
+- `/clawrouter route <eco|auto|premium>` — switch routing profile
+
+Tools (callable from chat):
+
+- `clawrouter_image_generate` — 55+ models incl. DALL-E 3, Flux, Nano Banana
+- `clawrouter_video_generate` — Seedance, Grok Imagine
+- `clawrouter_web_search` — Exa-powered
+
+## Wallet
+
+The plugin **reads** the canonical wallet at `~/.openclaw/blockrun/mnemonic` (24-word BIP-39 phrase, mode 0o600). To create one:
+
+```bash
+npx @blockrun/clawrouter setup
+```
+
+Then fund USDC on Base or Solana — $5 covers thousands of requests, non-custodial. The plugin never writes to the wallet.
+
+### Headless / CI
+
+Set `BLOCKRUN_WALLET_KEY=<0x raw EVM hex>` to bypass the mnemonic file (EVM-only — Solana derivation unavailable).
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `CLAWROUTER_PROXY_URL` | Point at an externally-managed proxy (e.g. `https://my-host/v1`). Skips local spawn entirely. |
+| `HERMES_CLAWROUTER_AUTOSPAWN=0` | Disable lazy spawn; require `npx @blockrun/clawrouter` to be running already. |
+| `BLOCKRUN_WALLET_KEY` | Raw EVM hex private key — overrides the mnemonic file. |
+| `CLAWROUTER_ROUTING_PROFILE` | `eco` / `auto` / `premium`. Forwarded to the proxy on spawn. |
+
+## How it works
+
+1. `hermes` starts → the entry-point plugin is loaded → `register(ctx)` wires tools, slash commands, CLI, and the skill.
+2. `hermes-clawrouter setup` materializes `~/.hermes/plugins/model-providers/clawrouter/{plugin.yaml,__init__.py}` from bundled package data and writes Hermes config/env hints needed by current Hermes provider and gateway model-picker paths.
+3. Hermes' `providers/__init__.py` discovers the materialized directory and registers the `ClawRouterProfile`, pointing `base_url` at `http://127.0.0.1:<port>/v1`.
+4. First tool call or chat turn → the supervisor probes `:8402`, spawns `npx -y @blockrun/clawrouter --port <port>` if needed, waits ≤30s for `/v1/models`, then forwards the request.
+5. A heartbeat thread restarts the subprocess on death (max 3 restarts/min).
+
+## Distribution
+
+The Python package ships **both** logical plugins:
+
+- **Standalone** plugin (this PyPI entry point): tools, slash commands, CLI, skill.
+- **Model-provider** plugin (materialized into `~/.hermes/plugins/model-providers/clawrouter/` by `hermes clawrouter setup`): `ProviderProfile` registration.
+
+This split is required because Hermes' PluginManager (`hermes_cli/plugins.py`) skips `register(ctx)` for `kind: model-provider`, and entry-point plugins always load as `kind: standalone`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. © BlockRun.

hermes_plugin_clawrouter-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermes-plugin-clawrouter"
+version = "0.1.0"
+description = "ClawRouter for Hermes — 55+ models, x402 USDC micropayments, smart routing"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "BlockRun" }
+]
+requires-python = ">=3.9"
+keywords = ["hermes", "hermes-agent", "clawrouter", "x402", "llm-router", "blockrun"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27",
+    "bip_utils>=2.9",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.entry-points."hermes_agent.plugins"]
+clawrouter = "clawrouter_hermes"
+
+[project.scripts]
+hermes-clawrouter = "clawrouter_hermes.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/BlockRunAI/ClawRouter"
+Repository = "https://github.com/BlockRunAI/ClawRouter-Hermes"
+"Bug Tracker" = "https://github.com/BlockRunAI/ClawRouter-Hermes/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+clawrouter_hermes = [
+    "plugin.yaml",
+    "provider_template/*.yaml",
+    "provider_template/*.tmpl",
+    "skills/clawrouter/*.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

hermes_plugin_clawrouter-0.1.0/setup.cfg

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

hermes_plugin_clawrouter-0.1.0/src/clawrouter_hermes/__init__.py

@@ -0,0 +1,122 @@
+"""ClawRouter Hermes plugin — entry point.
+
+Hermes' PluginManager discovers this module via the ``hermes_agent.plugins``
+entry-point group and calls :func:`register` once at startup. We register:
+
+- Tools (image / video / web_search) forwarded to the local ClawRouter proxy
+- A single slash command ``/clawrouter`` with several subcommands
+- A CLI subcommand ``hermes clawrouter <setup|wallet|doctor|route|stats>``
+- A read-only skill ``clawrouter:guide``
+
+The model-provider half (``ProviderProfile`` registration) is NOT done here
+because Hermes loads model-provider plugins from
+``~/.hermes/plugins/model-providers/<name>/`` only, not from entry-point
+plugins. ``hermes clawrouter setup`` materializes that directory from the
+bundled ``provider_template/`` resources.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from . import cli as _cli
+from . import commands, proxy_supervisor, schemas, tools
+
+__all__ = ["register"]
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "0.1.0"
+
+
+def register(ctx) -> None:
+    """Wire all surfaces into the Hermes plugin context."""
+    _install_compat()
+    _register_tools(ctx)
+    _register_slash_command(ctx)
+    _register_cli(ctx)
+    _register_skill(ctx)
+    # Best-effort, non-blocking probe so users see whether the proxy is up
+    # without paying spawn latency at startup.
+    try:
+        status = proxy_supervisor.ensure_running(autospawn=False)
+        if status.reachable:
+            logger.info("clawrouter: proxy reachable at %s", status.base_url)
+        else:
+            logger.debug("clawrouter: proxy not yet running (will spawn on first use)")
+    except Exception as exc:
+        logger.debug("clawrouter: startup probe failed: %s", exc)
+
+
+def _install_compat() -> None:
+    """Best-effort setup for Hermes versions that need provider/config hints."""
+    try:
+        _cli.install_hermes_compat()
+        _cli.patch_hermes_model_catalog()
+    except Exception as exc:
+        logger.debug("clawrouter: compatibility setup skipped: %s", exc)
+
+
+def _register_tools(ctx) -> None:
+    ctx.register_tool(
+        name="clawrouter_image_generate",
+        toolset="clawrouter",
+        schema=schemas.IMAGE_GENERATE,
+        handler=tools.image_generate,
+        description="Generate images via ClawRouter (x402-billed)",
+        emoji="🎨",
+    )
+    ctx.register_tool(
+        name="clawrouter_video_generate",
+        toolset="clawrouter",
+        schema=schemas.VIDEO_GENERATE,
+        handler=tools.video_generate,
+        description="Generate short videos via ClawRouter (x402-billed)",
+        emoji="🎬",
+    )
+    ctx.register_tool(
+        name="clawrouter_web_search",
+        toolset="clawrouter",
+        schema=schemas.WEB_SEARCH,
+        handler=tools.web_search,
+        description="Web search via ClawRouter Exa (x402-billed)",
+        emoji="🔎",
+    )
+
+
+def _register_slash_command(ctx) -> None:
+    ctx.register_command(
+        name="clawrouter",
+        handler=commands.clawrouter_dispatch,
+        description="ClawRouter wallet / stats / routing controls",
+        args_hint="<wallet|stats|status|route|help>",
+    )
+
+
+def _register_cli(ctx) -> None:
+    ctx.register_cli_command(
+        name="clawrouter",
+        help="ClawRouter setup, wallet, doctor, routing",
+        setup_fn=_cli.register_cli,
+        handler_fn=_cli.clawrouter_command,
+        description=(
+            "Manage the ClawRouter for Hermes plugin — install the model-provider "
+            "plugin, inspect the wallet, diagnose health, and set the routing profile."
+        ),
+    )
+
+
+def _register_skill(ctx) -> None:
+    skill_path = Path(__file__).parent / "skills" / "clawrouter" / "SKILL.md"
+    if not skill_path.exists():
+        logger.debug("clawrouter: skill file missing at %s", skill_path)
+        return
+    try:
+        ctx.register_skill(
+            name="guide",
+            path=skill_path,
+            description="ClawRouter usage guide — models, pricing, wallet, slash commands",
+        )
+    except Exception as exc:
+        logger.debug("clawrouter: skill registration failed: %s", exc)