{"id":50763566,"url":"https://github.com/srmdn/hermes-agent-kit","last_synced_at":"2026-06-11T12:30:50.387Z","repository":{"id":363186597,"uuid":"1258266163","full_name":"srmdn/hermes-agent-kit","owner":"srmdn","description":"Production hardening pack for Hermes Agent gateways — per-topic model routing, fallback chains, rate limiting, and cost tracking via gateway hooks","archived":false,"fork":false,"pushed_at":"2026-06-07T20:18:04.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T21:15:14.219Z","etag":null,"topics":["ai","devtools","gateway","hermes-agent","hooks","production","python","telegram"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srmdn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T12:23:57.000Z","updated_at":"2026-06-07T20:18:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/srmdn/hermes-agent-kit","commit_stats":null,"previous_names":["srmdn/hermes-agent-kit"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/srmdn/hermes-agent-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmdn%2Fhermes-agent-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmdn%2Fhermes-agent-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmdn%2Fhermes-agent-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmdn%2Fhermes-agent-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srmdn","download_url":"https://codeload.github.com/srmdn/hermes-agent-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmdn%2Fhermes-agent-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34199516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","devtools","gateway","hermes-agent","hooks","production","python","telegram"],"created_at":"2026-06-11T12:30:49.740Z","updated_at":"2026-06-11T12:30:50.376Z","avatar_url":"https://github.com/srmdn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hermes-kit\n\nProduction hardening pack for [Hermes Agent](https://github.com/NousResearch/hermes-agent).\n\nSelf-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.\n\nhermes-kit fills these gaps with production-grade hooks.\n\n\u003e ⚠️ **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.\n\n## Prerequisites\n\n- Python ≥ 3.11\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent) v0.16.0 (pinned)\n- **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.\n- A configured gateway (Telegram, Discord, etc.)\n\n### Verify Hermes works first\n\n\u003e **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.\n\n```bash\n# Set your model (pick one from opencode-go)\nhermes /model opencode-go/mimo-v2.5-pro\n\n# Or via config.yaml at ~/.hermes/config.yaml:\ncat \u003e ~/.hermes/config.yaml \u003c\u003c 'EOF'\nmodel:\n  default: opencode-go/mimo-v2.5-pro\n  provider: opencode-go\n\nproviders:\n  opencode-go:\n    api_key: OPENCODE_GO_API_KEY\n    base_url: https://opencode.ai/zen/go/v1\nEOF\n\n# Ensure API keys in ~/.hermes/.env\necho \"OPENCODE_GO_API_KEY=sk-...\" \u003e\u003e ~/.hermes/.env\necho \"GATEWAY_ALLOW_ALL_USERS=true\" \u003e\u003e ~/.hermes/.env\n\n# Start gateway\nhermes gateway run\n\n# Send a test message on Telegram → verify you get a response\n# Only then install hermes-kit\n```\n\n### Gateway Management\n\n```bash\n# Start (with hooks)\nhermes-kit gateway run --accept-hooks\n\n# Stop\n# Press Ctrl+C in the terminal running the gateway\n\n# Restart after config changes\n# Ctrl+C then:\nhermes-kit gateway run --accept-hooks\n\n# Check status\nhermes-kit status\n```\n\n## Install\n\n```bash\npip install hermes-agent-kit\n```\n\n\u003e **🔵 Naming — same project, two names:**\n\u003e | Context | Name |\n\u003e |---------|------|\n\u003e | PyPI / pip install | `hermes-agent-kit` |\n\u003e | GitHub repo | [`srmdn/hermes-agent-kit`](https://github.com/srmdn/hermes-agent-kit) |\n\u003e | CLI command | `hermes-kit` |\n\u003e\n\u003e 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.\n\n## Quickstart\n\n```bash\n# Install all hooks in one command\nhermes-kit install router fallback rate-limiter cost-tracker model-switch\n\n# Verify\nhermes-kit doctor\n\n# Start gateway with bridge auto-patched\nhermes-kit gateway run --accept-hooks\n\n# If new users get \"I don't recognize you\":\nGATEWAY_ALLOW_ALL_USERS=true hermes-kit gateway run --accept-hooks\n```\n\nHooks land in `~/.hermes/hooks/\u003cname\u003e/`. Hermes discovers them on restart.\n\n## Modules\n\n### router — Per-Topic Model Routing\n\nRoute Telegram topics to different AI models. Finance chat uses Qwen, coding chat uses DeepSeek, everything else falls back to GPT-4o-mini.\n\n**Via CLI:**\n```bash\nhermes-kit router set-default --model opencode-go/qwen3.6-plus\nhermes-kit router add 42 --model opencode-go/deepseek-v4-pro\nhermes-kit router show\n```\n\n**Via YAML** (`~/.hermes/hooks/router/topic_router.yaml`):\n```yaml\ndefault:\n  model: \"opencode-go/qwen3.6-plus\"\n\ntopics:\n  \"42\":\n    model: \"opencode-go/deepseek-v4-pro\"\n```\n\n**Multi-provider** — route specific topics to native providers:\n```bash\nhermes-kit router add 42 --model gpt-4o --provider openai\nhermes-kit router add 7 --model claude-sonnet-4-20250514 --provider anthropic\n```\n\nHermes 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.\n\n### fallback — Automatic Fallback Chain\n\nDefine a chain of models to try when the primary fails.\n\n**Via YAML** (`~/.hermes/hooks/fallback/fallback_chain.yaml`):\n```yaml\nchains:\n  global:\n    - \"opencode-go/deepseek-v4-pro\"     # primary\n    - \"opencode-go/kimi-k2.6\"      # fallback\n    - \"opencode-go/qwen3.6-plus\"          # last resort\n```\n\nAfter a failure, call `hermes_kit.bridge.retry_with_fallback(session_key)` to advance to the next model.\n\n### rate-limiter — Per-User Rate Limiting\n\nPrevent a single user or chat from draining your API budget.\n\n**Via YAML** (`~/.hermes/hooks/rate-limiter/rate_limits.yaml`):\n```yaml\nlimits:\n  global:\n    max_messages_per_window: 100\n    window_seconds: 3600\n  per_user:\n    \"123456789\":\n      max_messages_per_window: 50\n```\n\n\u003e 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.\n\n### cost-tracker — Real-Time Cost Tracking\n\nTrack token costs per session and alert when thresholds are exceeded.\n\n**Via YAML** (`~/.hermes/hooks/cost-tracker/cost_tracker.yaml`):\n```yaml\nalert_threshold_usd: 1.0\n```\n\nSet to `0` to disable alerts but continue tracking.\n\n## Docs\n\n- [Quickstart](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/quickstart.md) — agent-driven and manual install\n- [Providers](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/providers.md) — supported AI providers and model lists\n- Manual setup per module:\n  - [Router](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/router.md) — per-topic model routing + `/route` command\n  - [Fallback](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/fallback.md) — automatic retry chains\n  - [Rate Limiter](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/rate-limiter.md) — per-user quotas\n  - [Cost Tracker](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/manual/cost-tracker.md) — budget alerts\n- [Troubleshooting](https://github.com/srmdn/hermes-agent-kit/blob/main/docs/troubleshooting.md) — common issues\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmdn%2Fhermes-agent-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrmdn%2Fhermes-agent-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmdn%2Fhermes-agent-kit/lists"}