https://github.com/srmdn/hermes-agent-kit
Production hardening pack for Hermes Agent gateways — per-topic model routing, fallback chains, rate limiting, and cost tracking via gateway hooks
https://github.com/srmdn/hermes-agent-kit
ai devtools gateway hermes-agent hooks production python telegram
Last synced: 19 days ago
JSON representation
Production hardening pack for Hermes Agent gateways — per-topic model routing, fallback chains, rate limiting, and cost tracking via gateway hooks
- Host: GitHub
- URL: https://github.com/srmdn/hermes-agent-kit
- Owner: srmdn
- License: mit
- Created: 2026-06-03T12:23:57.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-06-07T20:18:04.000Z (23 days ago)
- Last Synced: 2026-06-07T21:15:14.219Z (23 days ago)
- Topics: ai, devtools, gateway, hermes-agent, hooks, production, python, telegram
- Language: Python
- Size: 80.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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) v0.16.0 (pinned)
- **Hermes configured with a working model + provider** — hermes-kit is a plugin, not standalone. Hermes must be able to respond to messages BEFORE installing hooks.
- A configured gateway (Telegram, Discord, etc.)
### Verify Hermes works first
> **Critical**: hermes-kit won't fix a broken Hermes setup. Make sure your gateway responds to messages with the model you want BEFORE installing hooks.
```bash
# Set your model (pick one from opencode-go)
hermes /model opencode-go/mimo-v2.5-pro
# Or via config.yaml at ~/.hermes/config.yaml:
cat > ~/.hermes/config.yaml << 'EOF'
model:
default: opencode-go/mimo-v2.5-pro
provider: opencode-go
providers:
opencode-go:
api_key: OPENCODE_GO_API_KEY
base_url: https://opencode.ai/zen/go/v1
EOF
# Ensure API keys in ~/.hermes/.env
echo "OPENCODE_GO_API_KEY=sk-..." >> ~/.hermes/.env
echo "GATEWAY_ALLOW_ALL_USERS=true" >> ~/.hermes/.env
# Start gateway
hermes gateway run
# Send a test message on Telegram → verify you get a response
# Only then install hermes-kit
```
### Gateway Management
```bash
# Start (with hooks)
hermes-kit gateway run --accept-hooks
# Stop
# Press Ctrl+C in the terminal running the gateway
# Restart after config changes
# Ctrl+C then:
hermes-kit gateway run --accept-hooks
# Check status
hermes-kit status
```
## Install
```bash
pip install hermes-agent-kit
```
> **🔵 Naming — same project, two names:**
> | Context | Name |
> |---------|------|
> | PyPI / pip install | `hermes-agent-kit` |
> | GitHub repo | [`srmdn/hermes-agent-kit`](https://github.com/srmdn/hermes-agent-kit) |
> | CLI command | `hermes-kit` |
>
> Why the split? PyPI name matches the repo (`hermes-agent-kit`). The short CLI alias (`hermes-kit`) keeps commands terse — `hermes-kit install router` instead of `hermes-agent-kit install router`. Same project, same code, two names.
## Quickstart
```bash
# Install all hooks in one command
hermes-kit install router fallback rate-limiter cost-tracker model-switch
# 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//`. 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/qwen3.6-plus
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/qwen3.6-plus"
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](https://github.com/srmdn/hermes-agent-kit/blob/main/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/kimi-k2.6" # fallback
- "opencode-go/qwen3.6-plus" # 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 enforces limits at the bridge level — exceeding users get `RateLimitExceeded` on every request until their window resets. Set `window_seconds` to control reset timing.
### 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](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/quickstart.md) — agent-driven and manual install
- [Providers](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/providers.md) — supported AI providers and model lists
- Manual setup per module:
- [Router](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/router.md) — per-topic model routing + `/route` command
- [Fallback](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/fallback.md) — automatic retry chains
- [Rate Limiter](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/rate-limiter.md) — per-user quotas
- [Cost Tracker](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/cost-tracker.md) — budget alerts
- [Troubleshooting](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/troubleshooting.md) — common issues
## License
MIT