hermes-agent-kit 0.2.1__py3-none-any.whl

hermes_agent_kit-0.2.1.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: hermes-agent-kit
+Version: 0.2.1
+Summary: Production hardening pack for Hermes Agent — per-topic model routing, fallback chains, rate limiting, and cost tracking via gateway hooks
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# hermes-kit
+
+Production hardening pack for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Self-hosted Hermes gateways are powerful but built for single-user setups. Multi-user deployments hit walls: no per-topic model routing, API failures surface as hard errors, one heavy user can burn your API budget with no alert.
+
+hermes-kit fills these gaps with production-grade hooks.
+
+> ⚠️ **How it works**: hermes-kit monkey-patches Hermes Agent's internal model resolver at runtime. This is intentionally fragile — Hermes Agent updates may break your setup. We're working on an upstream PR to replace the patch with native hook return values. Until then, test after every Hermes upgrade.
+
+## Prerequisites
+
+- Python ≥ 3.11
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed
+- A configured gateway (Telegram, Discord, etc.)
+
+## Install
+
+```bash
+pip install hermes-agent-kit
+```
+
+## Quickstart
+
+```bash
+# Install all hooks in one command
+hermes-kit install router fallback rate-limiter cost-tracker
+
+# Verify
+hermes-kit doctor
+
+# Start gateway with bridge auto-patched
+hermes-kit gateway run --accept-hooks
+
+# If new users get "I don't recognize you":
+GATEWAY_ALLOW_ALL_USERS=true hermes-kit gateway run --accept-hooks
+```
+
+Hooks land in `~/.hermes/hooks/<name>/`. Hermes discovers them on restart.
+
+## Modules
+
+### router — Per-Topic Model Routing
+
+Route Telegram topics to different AI models. Finance chat uses Qwen, coding chat uses DeepSeek, everything else falls back to GPT-4o-mini.
+
+**Via CLI:**
+```bash
+hermes-kit router set-default --model opencode-go/gpt-4o-mini
+hermes-kit router add 42 --model opencode-go/deepseek-v4-pro
+hermes-kit router show
+```
+
+**Via YAML** (`~/.hermes/hooks/router/topic_router.yaml`):
+```yaml
+default:
+  model: "opencode-go/gpt-4o-mini"
+
+topics:
+  "42":
+    model: "opencode-go/deepseek-v4-pro"
+```
+
+**Multi-provider** — route specific topics to native providers:
+```bash
+hermes-kit router add 42 --model gpt-4o --provider openai
+hermes-kit router add 7 --model claude-sonnet-4-20250514 --provider anthropic
+```
+
+Hermes resolves API keys from `~/.hermes/.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). See [providers guide](docs/providers.md) for all supported providers and model IDs.
+
+### fallback — Automatic Fallback Chain
+
+Define a chain of models to try when the primary fails.
+
+**Via YAML** (`~/.hermes/hooks/fallback/fallback_chain.yaml`):
+```yaml
+chains:
+  global:
+    - "opencode-go/deepseek-v4-pro"     # primary
+    - "opencode-go/claude-sonnet-4"      # fallback
+    - "opencode-go/gpt-4o-mini"          # last resort
+```
+
+After a failure, call `hermes_kit.bridge.retry_with_fallback(session_key)` to advance to the next model.
+
+### rate-limiter — Per-User Rate Limiting
+
+Prevent a single user or chat from draining your API budget.
+
+**Via YAML** (`~/.hermes/hooks/rate-limiter/rate_limits.yaml`):
+```yaml
+limits:
+  global:
+    max_messages_per_window: 100
+    window_seconds: 3600
+  per_user:
+    "123456789":
+      max_messages_per_window: 50
+```
+
+> ⚠️ Rate limiter currently tracks usage but does not block messages. Enforcement is planned for an upcoming release.
+
+### cost-tracker — Real-Time Cost Tracking
+
+Track token costs per session and alert when thresholds are exceeded.
+
+**Via YAML** (`~/.hermes/hooks/cost-tracker/cost_tracker.yaml`):
+```yaml
+alert_threshold_usd: 1.0
+```
+
+Set to `0` to disable alerts but continue tracking.
+
+## Docs
+
+- [Quickstart](docs/quickstart.md) — agent-driven and manual install
+- [Providers](docs/providers.md) — supported AI providers and model lists
+- Manual setup per module:
+  - [Router](docs/manual/router.md) — per-topic model routing
+  - [Fallback](docs/manual/fallback.md) — automatic retry chains
+  - [Rate Limiter](docs/manual/rate-limiter.md) — per-user quotas
+  - [Cost Tracker](docs/manual/cost-tracker.md) — budget alerts
+- [Troubleshooting](docs/troubleshooting.md) — common issues
+
+## License
+
+MIT

hermes_agent_kit-0.2.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+hermes_agent_kit-0.2.1.dist-info/licenses/LICENSE,sha256=gbOQIITSiUtvLsO_NrQePHVPJQ3VMzi0IGIs5MWauGc,1062
+hermes_kit/__init__.py,sha256=MWwqX2Yqp-kKZRorkcUHHdbMRCd4eYKKmPhFVrMXHMg,66
+hermes_kit/bridge.py,sha256=i6ZAgNDrEhGj1x9Pmgh3C0wqUbhr4ynNl42A75V5K7U,5252
+hermes_kit/cli.py,sha256=dQuNqkECaYDsEdUsG89HMqDNEWLWLoYVfV1OHRZPvyA,7081
+hermes_kit/hooks/cost_tracker/HOOK.yaml,sha256=gf-t2oRmRqicBQLWKDPAMTFn4LSFCPIX-pH9d3NaAYA,142
+hermes_kit/hooks/cost_tracker/cost_tracker.yaml,sha256=UiKQ2yLuaWI7J7SN4s5jgZp9_dx00h9HJdbmDkEjxy8,25
+hermes_kit/hooks/cost_tracker/handler.py,sha256=GCutxEh35CeingZPxavp-HIhiy9ZbWsG40-M0YHZFeY,1101
+hermes_kit/hooks/fallback/HOOK.yaml,sha256=CmQARDcxjkE0tCcKsNTZMd0hf_JerNAN6FSZwyqtKo4,108
+hermes_kit/hooks/fallback/fallback_chain.yaml,sha256=Uv5ayi9AkrmRySoeplK1j7oettBPufCf5qQ2RC4r7Is,130
+hermes_kit/hooks/fallback/handler.py,sha256=qTPQWtfhnph3KgNlQTLSRi5RjsxSPykU53sS_MLfiFk,601
+hermes_kit/hooks/rate_limiter/HOOK.yaml,sha256=BZ8R1Dvq4jgBqIr734uJRO6b3TOvWhGwh4uhYO7Kask,136
+hermes_kit/hooks/rate_limiter/handler.py,sha256=K6xt0kr-6_FgCcoJSw3IX3fyGzDO-NRBCCoPVeuE9IQ,1433
+hermes_kit/hooks/rate_limiter/rate_limits.yaml,sha256=3CwSafKtKAA3pleNb7PnNEhkGxL9QlbDFBUhRpGkUpY,174
+hermes_kit/hooks/router/HOOK.yaml,sha256=5smejjub_n1vUfaMAsWWdfWBHXAiGXjYaZJLQQJngpQ,135
+hermes_kit/hooks/router/handler.py,sha256=GrR2PQOr61OcRr9WuP1dQUOf3kC2i3MXhqT0fV1yYpA,1304
+hermes_kit/hooks/router/topic_router.yaml,sha256=UwcdJSGilb4zkm0xAQLfKkLn6zdFaWdiOrLF-Q13AVk,129
+hermes_kit/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hermes_kit/lib/hermes_api.py,sha256=GEd8DNGH256zr9D_7p80kcvA9QD_0zNz-sBHa_kVqlI,167
+hermes_agent_kit-0.2.1.dist-info/METADATA,sha256=KjFy9nWVtpVmBX_13rkhpjpGkN2mT-xBukZ6C80AxKk,4333
+hermes_agent_kit-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hermes_agent_kit-0.2.1.dist-info/entry_points.txt,sha256=JM-aLWkod-nGmOnUWMvY0h3cGmHU9SJTDK8m4nkoi6A,51
+hermes_agent_kit-0.2.1.dist-info/top_level.txt,sha256=s9-u5hHpWuLxsybiueBHXzhJHMyZ-jGXB0ASvmkDcR0,11
+hermes_agent_kit-0.2.1.dist-info/RECORD,,

hermes_agent_kit-0.2.1.dist-info/WHEEL

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

hermes_agent_kit-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hermes-kit = hermes_kit.cli:main

hermes_agent_kit-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 srmdn
+
+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_agent_kit-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+hermes_kit

hermes_kit/__init__.py

@@ -0,0 +1 @@
+"""hermes-kit — Production hardening hooks for Hermes Agent."""

hermes_kit/bridge.py

@@ -0,0 +1,168 @@
+from typing import Optional
+import time
+
+_model_overrides: dict[str, dict[str, Optional[str]]] = {}
+_fallback_chains: dict[str, list[str]] = {}
+_fallback_index: dict[str, int] = {}
+
+_rate_counters: dict[str, int] = {}
+_rate_windows: dict[str, float] = {}
+_rate_limited: set[str] = set()
+
+
+def set_override(session_key: str, model: str, provider: Optional[str] = None) -> None:
+    _model_overrides[session_key] = {
+        "model": model,
+        "provider": provider,
+    }
+
+
+def get_override(session_key: str) -> Optional[dict]:
+    return _model_overrides.get(session_key)
+
+
+def clear_override(session_key: str) -> None:
+    _model_overrides.pop(session_key, None)
+
+
+def set_fallback_chain(session_key: str, chain: list[str]) -> None:
+    _fallback_chains[session_key] = chain
+    _fallback_index[session_key] = 0
+
+
+def get_fallback_chain(session_key: str) -> list[str] | None:
+    return _fallback_chains.get(session_key)
+
+
+def advance_fallback(session_key: str) -> None:
+    if session_key in _fallback_index:
+        _fallback_index[session_key] += 1
+
+
+def get_current_fallback(session_key: str) -> str | None:
+    chain = _fallback_chains.get(session_key)
+    if not chain:
+        return None
+    idx = _fallback_index.get(session_key, 0)
+    if idx < len(chain):
+        return chain[idx]
+    return None
+
+
+def retry_with_fallback(session_key: str) -> str | None:
+    advance_fallback(session_key)
+    model = get_current_fallback(session_key)
+    if model:
+        set_override(session_key, model=model)
+    return model
+
+
+def reset_rate_counter(session_key: str) -> None:
+    _rate_counters[session_key] = 0
+    _rate_windows[session_key] = time.time()
+    _rate_limited.discard(session_key)
+
+
+def increment_rate_counter(session_key: str) -> int:
+    _rate_counters[session_key] = _rate_counters.get(session_key, 0) + 1
+    if session_key not in _rate_windows:
+        _rate_windows[session_key] = time.time()
+    return _rate_counters[session_key]
+
+
+def get_rate_window_start(session_key: str) -> float:
+    return _rate_windows.get(session_key, 0.0)
+
+
+def set_rate_limited(session_key: str) -> None:
+    _rate_limited.add(session_key)
+
+
+def is_rate_limited(session_key: str) -> bool:
+    return session_key in _rate_limited
+
+
+_session_costs: dict[str, dict[str, float]] = {}
+_cost_pricing: dict[str, tuple[float, float]] = {
+    "gpt-4o": (2.50, 10.00),
+    "gpt-4o-mini": (0.15, 0.60),
+    "claude-sonnet-4": (3.00, 15.00),
+    "deepseek-chat": (0.14, 0.28),
+    "qwen-3.6-plus": (0.40, 0.80),
+}
+
+
+def track_cost(session_key: str, model: str, prompt_tokens: int, completion_tokens: int) -> None:
+    if session_key not in _session_costs:
+        _session_costs[session_key] = {}
+    if model not in _session_costs[session_key]:
+        _session_costs[session_key][model] = 0.0
+
+    input_price, output_price = _cost_pricing.get(model, (0.0, 0.0))
+    cost = (prompt_tokens / 1_000_000) * input_price + (completion_tokens / 1_000_000) * output_price
+    _session_costs[session_key][model] += cost
+
+
+def get_session_cost(session_key: str) -> float:
+    if session_key not in _session_costs:
+        return 0.0
+    return sum(_session_costs[session_key].values())
+
+
+def get_session_cost_breakdown(session_key: str) -> dict[str, float]:
+    return _session_costs.get(session_key, {})
+
+
+def reset_session_cost(session_key: str) -> None:
+    _session_costs.pop(session_key, None)
+
+
+def alert_cost_exceeded(session_key: str, total: float, threshold: float) -> None:
+    print(f"[hermes-kit] COST ALERT: session {session_key} total ${total:.4f} exceeds threshold ${threshold:.2f}")
+
+
+_RUNTIME_KEYS = ("provider", "api_key", "base_url", "api_mode")
+
+
+def _apply_override(override: dict, model: str, runtime_kwargs: dict) -> tuple[str, dict]:
+    model = override.get("model", model)
+    for key in _RUNTIME_KEYS:
+        val = override.get(key)
+        if val is not None:
+            runtime_kwargs[key] = val
+    return model, runtime_kwargs
+
+
+def patch_gateway_resolver() -> None:
+    import inspect
+    from gateway.run import GatewayRunner
+
+    original = GatewayRunner._resolve_session_agent_runtime
+    original_is_async = inspect.iscoroutinefunction(original)
+
+    if original_is_async:
+        async def patched_resolver(self, *args, **kwargs):
+            model, runtime_kwargs = await original(self, *args, **kwargs)
+            session_key = kwargs.get("session_key") or (args[0] if args else None)
+            if session_key:
+                override = get_override(session_key)
+                if override:
+                    model, runtime_kwargs = _apply_override(override, model, runtime_kwargs)
+            return model, runtime_kwargs
+    else:
+        def patched_resolver(self, *args, **kwargs):
+            model, runtime_kwargs = original(self, *args, **kwargs)
+            session_key = kwargs.get("session_key") or (args[0] if args else None)
+            if session_key:
+                override = get_override(session_key)
+                if override:
+                    model, runtime_kwargs = _apply_override(override, model, runtime_kwargs)
+            return model, runtime_kwargs
+
+    GatewayRunner._resolve_session_agent_runtime = patched_resolver
+
+
+try:
+    patch_gateway_resolver()
+except ImportError:
+    pass

hermes_kit/cli.py

@@ -0,0 +1,240 @@
+import shutil
+import sys
+from pathlib import Path
+
+import yaml
+
+from hermes_kit.lib.hermes_api import get_hooks_dir
+
+
+HOOKS_SRC = Path(__file__).parent / "hooks"
+
+_hook_dir_names = [d.name for d in HOOKS_SRC.iterdir() if d.is_dir()]
+
+_hook_names: dict[str, str] = {}
+_hook_dirs: dict[str, str] = {}
+for _dir in _hook_dir_names:
+    _hook_yaml = HOOKS_SRC / _dir / "HOOK.yaml"
+    if _hook_yaml.exists():
+        _name = yaml.safe_load(_hook_yaml.read_text()).get("name", _dir)
+    else:
+        _name = _dir
+    _hook_names[_dir] = _name
+    _hook_dirs[_name] = _dir
+
+AVAILABLE_HOOKS = sorted(_hook_dirs.keys())
+
+
+def install(hook_name: str) -> None:
+    dir_name = _hook_dirs.get(hook_name)
+    if not dir_name:
+        print(f"Unknown hook: {hook_name}. Available: {', '.join(AVAILABLE_HOOKS)}")
+        sys.exit(1)
+
+    src = HOOKS_SRC / dir_name
+    dest = Path(get_hooks_dir()) / hook_name
+    if dest.exists():
+        print(f"Hook '{hook_name}' already installed. Use 'hermes-kit reinstall {hook_name}' to overwrite.")
+        return
+
+    shutil.copytree(src, dest)
+    print(f"Installed '{hook_name}' → {dest}")
+
+
+def doctor() -> None:
+    hooks_dir = Path(get_hooks_dir())
+    if not hooks_dir.exists():
+        print("OK: No hooks installed yet. Run 'hermes-kit install <name>' to add hooks.")
+        return
+
+    installed = [d.name for d in hooks_dir.iterdir() if d.is_dir()]
+    if not installed:
+        print("OK: Hooks directory exists but is empty.")
+        return
+
+    for name in installed:
+        hook_dir = hooks_dir / name
+        hook_yaml = hook_dir / "HOOK.yaml"
+        handler = hook_dir / "handler.py"
+
+        status = []
+        if hook_yaml.exists():
+            status.append("HOOK.yaml ✓")
+        else:
+            status.append("HOOK.yaml ✗ (missing)")
+        if handler.exists():
+            status.append("handler.py ✓")
+        else:
+            status.append("handler.py ✗ (missing)")
+
+        print(f"  {name}: {' '.join(status)}")
+
+    print("Done.")
+
+
+def gateway_run() -> None:
+    from hermes_kit.bridge import patch_gateway_resolver
+
+    patch_gateway_resolver()
+
+    sys.argv = ["hermes", "gateway", "run"] + sys.argv[3:]
+
+    from hermes_cli.main import main as hermes_main
+
+    hermes_main()
+
+
+def _router_config_path() -> Path:
+    return Path(get_hooks_dir()) / "router" / "topic_router.yaml"
+
+
+def _read_router_config() -> dict:
+    path = _router_config_path()
+    if path.exists():
+        return yaml.safe_load(path.read_text()) or {}
+    return {}
+
+
+def _write_router_config(config: dict) -> None:
+    path = _router_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+
+
+def router_add(topic_id: str, model: str, provider: str | None = None) -> None:
+    config = _read_router_config()
+    topics = config.get("topics") or {}
+    entry: dict[str, str] = {"model": model}
+    if provider:
+        entry["provider"] = provider
+    topics[topic_id] = entry
+    config["topics"] = topics
+    _write_router_config(config)
+    provider_msg = f" (provider: {provider})" if provider else ""
+    print(f"Added topic '{topic_id}' → {model}{provider_msg}")
+
+
+def router_remove(topic_id: str) -> None:
+    config = _read_router_config()
+    topics = config.get("topics") or {}
+    if topic_id in topics:
+        del topics[topic_id]
+        _write_router_config(config)
+        print(f"Removed topic '{topic_id}'.")
+    else:
+        print(f"Topic '{topic_id}' not found.")
+
+
+def router_show() -> None:
+    config = _read_router_config()
+    default = config.get("default") or {}
+    topics = config.get("topics") or {}
+
+    if default:
+        line = f"Default: {default.get('model', 'not set')}"
+        if default.get("provider"):
+            line += f" (provider: {default['provider']})"
+        print(line)
+    if topics:
+        if default:
+            print()
+        for tid, route in topics.items():
+            line = f"  {tid}  →  {route.get('model', 'unknown')}"
+            if route.get("provider"):
+                line += f" (provider: {route['provider']})"
+            print(line)
+    if not default and not topics:
+        print("No routing configured.")
+
+
+def router_set_default(model: str, provider: str | None = None) -> None:
+    config = _read_router_config()
+    entry: dict[str, str] = {"model": model}
+    if provider:
+        entry["provider"] = provider
+    config["default"] = entry
+    _write_router_config(config)
+    provider_msg = f" (provider: {provider})" if provider else ""
+    print(f"Default model: {model}{provider_msg}")
+
+
+def _parse_flag(flag: str, args: list[str]) -> str | None:
+    try:
+        idx = args.index(flag)
+        return args[idx + 1]
+    except (ValueError, IndexError):
+        return None
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: hermes-kit <install|doctor|list|gateway run|router>")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+
+    if cmd == "install":
+        if len(sys.argv) < 3:
+            print(f"Usage: hermes-kit install <hook> [<hook> ...]. Available: {', '.join(AVAILABLE_HOOKS)}")
+            sys.exit(1)
+        for hook_name in sys.argv[2:]:
+            install(hook_name)
+
+    elif cmd == "doctor":
+        doctor()
+
+    elif cmd == "list":
+        print("Available hooks:")
+        for h in AVAILABLE_HOOKS:
+            installed = " (installed)" if (Path(get_hooks_dir()) / h).exists() else ""
+            print(f"  {h}{installed}")
+
+    elif cmd == "gateway":
+        if len(sys.argv) < 3 or sys.argv[2] != "run":
+            print("Usage: hermes-kit gateway run [--accept-hooks] [-- ...]")
+            sys.exit(1)
+        gateway_run()
+
+    elif cmd == "router":
+        if len(sys.argv) < 3:
+            print("Usage: hermes-kit router <add|remove|show|set-default> [args]")
+            sys.exit(1)
+
+        subcmd = sys.argv[2]
+        args = sys.argv[3:]
+
+        if subcmd == "show":
+            router_show()
+
+        elif subcmd == "add":
+            topic_id = args[0] if args else None
+            model = _parse_flag("--model", args)
+            if not topic_id or not model:
+                print("Usage: hermes-kit router add <topic-id> --model <model> [--provider <provider>]")
+                sys.exit(1)
+            router_add(topic_id, model, provider=_parse_flag("--provider", args))
+
+        elif subcmd == "remove":
+            if not args:
+                print("Usage: hermes-kit router remove <topic-id>")
+                sys.exit(1)
+            router_remove(args[0])
+
+        elif subcmd == "set-default":
+            model = _parse_flag("--model", args)
+            if not model:
+                print("Usage: hermes-kit router set-default --model <model> [--provider <provider>]")
+                sys.exit(1)
+            router_set_default(model, provider=_parse_flag("--provider", args))
+
+        else:
+            print(f"Unknown router command: {subcmd}")
+            sys.exit(1)
+
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

hermes_kit/hooks/cost_tracker/HOOK.yaml

@@ -0,0 +1,5 @@
+name: cost-tracker
+description: Real-time token cost tracking with per-topic breakdown and budget alerts
+events:
+  - agent:step
+  - agent:end

hermes_kit/hooks/cost_tracker/cost_tracker.yaml

@@ -0,0 +1 @@
+alert_threshold_usd: 1.0

hermes_kit/hooks/cost_tracker/handler.py

@@ -0,0 +1,30 @@
+import yaml
+from pathlib import Path
+from hermes_kit import bridge
+
+_ALERT_THRESHOLD: float = 0.0
+_hook_dir = Path(__file__).parent
+_cfg_path = _hook_dir / "cost_tracker.yaml"
+if _cfg_path.exists():
+    raw = yaml.safe_load(_cfg_path.read_text()) or {}
+    _ALERT_THRESHOLD = raw.get("alert_threshold_usd", 0.0)
+
+
+async def handle(event_type: str, context: dict) -> None:
+    session_key = context.get("session_key")
+    if not session_key:
+        return
+
+    if event_type == "agent:step":
+        usage = context.get("usage", {})
+        if usage:
+            prompt_tokens = usage.get("prompt_tokens", 0)
+            completion_tokens = usage.get("completion_tokens", 0)
+            model = context.get("model", "unknown")
+            bridge.track_cost(session_key, model, prompt_tokens, completion_tokens)
+
+    elif event_type == "agent:end":
+        total = bridge.get_session_cost(session_key)
+        if total > 0 and _ALERT_THRESHOLD > 0 and total > _ALERT_THRESHOLD:
+            bridge.alert_cost_exceeded(session_key, total, _ALERT_THRESHOLD)
+        bridge.reset_session_cost(session_key)

hermes_kit/hooks/fallback/HOOK.yaml

@@ -0,0 +1,4 @@
+name: fallback
+description: Automatic model fallback chain when primary model fails
+events:
+  - agent:start

hermes_kit/hooks/fallback/fallback_chain.yaml

@@ -0,0 +1,5 @@
+chains:
+  # global:
+  #   - "opencode-go/deepseek-v4-pro"
+  #   - "opencode-go/claude-sonnet-4"
+  #   - "opencode-go/gpt-4o-mini"

hermes_kit/hooks/fallback/handler.py

@@ -0,0 +1,23 @@
+import yaml
+from pathlib import Path
+from hermes_kit import bridge
+
+_CHAINS: dict[str, list[str]] = {}
+_hook_dir = Path(__file__).parent
+_chain_path = _hook_dir / "fallback_chain.yaml"
+if _chain_path.exists():
+    raw = yaml.safe_load(_chain_path.read_text()) or {}
+    _CHAINS = raw.get("chains", {})
+
+
+async def handle(event_type: str, context: dict) -> None:
+    if event_type != "agent:start":
+        return
+
+    session_key = context.get("session_key")
+    if not session_key:
+        return
+
+    chain = _CHAINS.get("global")
+    if chain:
+        bridge.set_fallback_chain(session_key, chain)

hermes_kit/hooks/rate_limiter/HOOK.yaml

@@ -0,0 +1,5 @@
+name: rate-limiter
+description: Per-user and per-chat rate limiting to prevent API cost spikes
+events:
+  - session:start
+  - agent:step

hermes_kit/hooks/rate_limiter/handler.py

@@ -0,0 +1,48 @@
+import time
+import yaml
+from pathlib import Path
+from hermes_kit import bridge
+
+_LIMITS: dict = {}
+_hook_dir = Path(__file__).parent
+_limits_path = _hook_dir / "rate_limits.yaml"
+if _limits_path.exists():
+    raw = yaml.safe_load(_limits_path.read_text()) or {}
+    _LIMITS = raw.get("limits", {})
+
+
+def _get_limit(user_id: str) -> dict | None:
+    per_user = _LIMITS.get("per_user", {})
+    if user_id in per_user:
+        return per_user[user_id]
+    return _LIMITS.get("global")
+
+
+def _is_within_window(window_start: float, window_seconds: int) -> bool:
+    return (time.time() - window_start) < window_seconds
+
+
+async def handle(event_type: str, context: dict) -> None:
+    session_key = context.get("session_key")
+    if not session_key:
+        return
+
+    limit = _get_limit(context.get("user_id", ""))
+    if not limit:
+        return
+
+    if event_type == "session:start":
+        bridge.reset_rate_counter(session_key)
+
+    elif event_type == "agent:step":
+        count = bridge.increment_rate_counter(session_key)
+        window_seconds = limit.get("window_seconds", 3600)
+        max_messages = limit.get("max_messages_per_window", 100)
+
+        window_start = bridge.get_rate_window_start(session_key)
+        if not _is_within_window(window_start, window_seconds):
+            bridge.reset_rate_counter(session_key)
+            return
+
+        if count > max_messages:
+            bridge.set_rate_limited(session_key)

hermes_kit/hooks/rate_limiter/rate_limits.yaml

@@ -0,0 +1,8 @@
+limits:
+  global:
+    max_messages_per_window: 100
+    window_seconds: 3600
+  # per_user:
+  #   "123456789":
+  #     max_messages_per_window: 50
+  #     window_seconds: 3600

hermes_kit/hooks/router/HOOK.yaml

@@ -0,0 +1,5 @@
+name: router
+description: Route messages to different AI models based on Telegram topic ID
+events:
+  - session:start
+  - session:reset

hermes_kit/hooks/router/handler.py

@@ -0,0 +1,47 @@
+import yaml
+from pathlib import Path
+from hermes_kit import bridge
+
+_ROUTING: dict[str, dict] = {}
+_DEFAULT: dict | None = None
+_hook_dir = Path(__file__).parent
+_routing_path = _hook_dir / "topic_router.yaml"
+if _routing_path.exists():
+    raw = yaml.safe_load(_routing_path.read_text()) or {}
+    _ROUTING = raw.get("topics", {})
+    _DEFAULT = raw.get("default")
+
+
+def _extract_routing_id(context: dict) -> str | None:
+    session_key = context.get("session_key", "")
+    chat_id = context.get("chat_id")
+    if not session_key:
+        return None
+
+    parts = session_key.split(":")
+    if len(parts) >= 5:
+        return parts[4]
+
+    return chat_id
+
+
+async def handle(event_type: str, context: dict) -> None:
+    session_key = context.get("session_key")
+    if not session_key:
+        return
+
+    if event_type == "session:start":
+        routing_id = _extract_routing_id(context)
+        if routing_id:
+            route = _ROUTING.get(routing_id)
+            if not route:
+                route = _DEFAULT
+            if route:
+                bridge.set_override(
+                    session_key,
+                    model=route["model"],
+                    provider=route.get("provider"),
+                )
+
+    elif event_type == "session:reset":
+        bridge.clear_override(session_key)

hermes_kit/hooks/router/topic_router.yaml

@@ -0,0 +1,7 @@
+default:
+  model: "opencode-go/gpt-4o-mini"
+
+topics:
+  # "42":
+  #   model: "opencode-go/qwen-3.6-plus"
+  #   profile: "finance"

hermes_kit/lib/hermes_api.py

@@ -0,0 +1,6 @@
+import os
+
+
+def get_hooks_dir() -> str:
+    hermes_home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+    return os.path.join(hermes_home, "hooks")