mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-08 03:01:47 +00:00
docs: pluggable surfaces coverage — model-provider guide, full plugin map, opt-in fix (#20749)
* docs(providers): add model-provider-plugin authoring guide + fix stale refs
New docs:
- website/docs/developer-guide/model-provider-plugin.md — full authoring
guide (directory layout, minimal example, ProviderProfile fields,
overridable hooks, user overrides, api_mode selection, auth types,
testing, pip distribution)
- Wired into website/sidebars.ts under 'Extending'
- Cross-references added in:
- guides/build-a-hermes-plugin.md (tip block)
- developer-guide/adding-providers.md
- developer-guide/provider-runtime.md
User guide:
- user-guide/features/plugins.md: Plugin types table grows from 3 to 4
with 'Model providers' row
Stale comment cleanup (providers/*.py → plugins/model-providers/<name>/):
- hermes_cli/main.py:_is_profile_api_key_provider docstring
- hermes_cli/doctor.py:_build_apikey_providers_list docstring
- hermes_cli/auth.py: PROVIDER_REGISTRY + alias auto-extension comments
- hermes_cli/models.py: CANONICAL_PROVIDERS auto-extension comment
AGENTS.md:
- Project-structure tree: added plugins/model-providers/ row
- New section: 'Model-provider plugins' explaining discovery, override
semantics, PluginManager integration, kind auto-coerce heuristic
Verified: docusaurus build succeeds, new page renders, all 3 cross-links
resolve. 347/347 targeted tests pass (tests/providers/,
tests/hermes_cli/test_plugins.py, tests/hermes_cli/test_runtime_provider_resolution.py,
tests/run_agent/test_provider_parity.py).
* docs(plugins): add 'pluggable interfaces at a glance' maps to plugins.md + build-a-hermes-plugin
Devs landing on either the user-guide plugin page or the build-a-plugin
guide now get an upfront table of every distinct pluggable surface with
a link to the right authoring doc. Previously they'd have to read the
full general-plugin guide to discover that model providers / platforms
/ memory / context engines are separate systems.
user-guide/features/plugins.md:
- New 'Pluggable interfaces — where to go for each' section below the
existing 4-kinds table
- 10 rows covering every register_* surface (tool, hook, slash command,
CLI subcommand, skill, model provider, platform, memory, context
engine, image-gen)
- Explicit note: TTS/STT are NOT plugin-extensible yet — documented
with a pointer to the current config.yaml 'command providers' pattern
and a note that register_tts_provider()/register_stt_provider() may
come later
guides/build-a-hermes-plugin.md:
- New :::info 'Not sure which guide you need?' map at the top so devs
see all pluggable interfaces before investing in this 737-line
general-plugin walkthrough
- Existing bottom :::tip expanded to include platform adapters alongside
model/memory/context plugins
Verified:
- All 8 cross-doc links in the new plugins.md table resolve in a
docusaurus build (SUCCESS, no new broken links)
- TTS link corrected (features/voice → features/tts; latter exists)
- Pre-existing broken links/anchors (cron-script-only, llms.txt,
adding-platform-adapters#step-by-step-checklist) are unchanged
* docs(plugins): correct TTS/STT pluggability \u2014 they ARE plugins (command-providers)
Previous commit incorrectly said TTS/STT 'aren't plugin-extensible'. They
are, via the config-driven command-provider pattern \u2014 any CLI that reads
text and writes audio (or vice versa for STT) is automatically a plugin
with zero Python. The tts.md docs cover this extensively and I missed it.
plugins.md:
- TTS row: 'Config-driven (not a Python plugin)', points at
tts.md#custom-command-providers
- STT row: points at tts.md#voice-message-transcription-stt (STT docs
live in tts.md despite the filename)
- Expanded note: TTS/STT use config-driven shell-command templates as
their plugin surface (full tts.providers.<name> registry for TTS;
HERMES_LOCAL_STT_COMMAND escape hatch for STT)
- Any CLI that reads/writes files is automatically a plugin \u2014 no Python
register_* API needed
- Future register_tts_provider()/register_stt_provider() hooks mentioned
as nice-to-have for SDK/streaming cases, not as the primary story
build-a-hermes-plugin.md:
- Same map update: TTS/STT rows explicit, footer note corrected
Verified:
- tts.md anchors (custom-command-providers, voice-message-transcription-stt)
exist and resolve in docusaurus build (SUCCESS, no new broken links)
* docs(plugins): expand pluggable interfaces table with MCP / event hooks / shell hooks / skill taps
Broadened the scope beyond Python register_* hooks. Hermes has MULTIPLE
plugin-style extension surfaces; they're now all in one table instead of
being scattered across feature docs.
Added rows for:
- **MCP servers** — config.yaml mcp_servers.<name> auto-registers external
tools from any MCP server. Huge extensibility surface, previously not
linked from the plugin map.
- **Gateway event hooks** — drop HOOK.yaml + handler.py into
~/.hermes/hooks/<name>/ to fire on gateway:startup, session:*, agent:*,
command:* events. Separate from Python plugin hooks.
- **Shell hooks** — hooks: block in config.yaml runs shell commands on
events (notifications, auditing, etc.).
- **Skill sources (taps)** — hermes skills tap add <repo> to pull in new
skill registries beyond the built-in sources.
Both docs updated:
- user-guide/features/plugins.md: table column renamed to 'How' (mixes
Python API + config-driven + drop-in-dir surfaces accurately)
- guides/build-a-hermes-plugin.md: :::info map at top mirrors the new
surfaces with a forward-link to the consolidated table
Note block rewritten: instead of singling out TTS/STT as the 'different
style' exception, now honestly describes that Hermes deliberately
supports three plugin styles — Python APIs, config-driven commands, and
drop-in manifest directories — and devs should pick the one that fits
their integration.
Not included (considered and rejected):
- Transport layer (register_transport) — internal, not user-facing
- Tool-call parsers — internal, VLLM phase-2 thing
- Cloud browser providers — hardcoded registry, not drop-in yet
- Terminal backends — hardcoded if/elif, not drop-in yet
- Skill sources (the ABC) — hardcoded list, only taps are user-extensible
Verified:
- All 5 new anchors resolve (gateway-event-hooks, shell-hooks, skills-hub,
custom-command-providers, voice-message-transcription-stt)
- Docusaurus build SUCCESS, zero new broken links
- Same 3 pre-existing broken links on main (cron-script-only, llms.txt,
adding-platform-adapters#step-by-step-checklist)
* docs(plugins): cover every pluggable surface in both the overview and how-to
Both plugins.md and build-a-hermes-plugin.md now cover every extension
surface end-to-end \u2014 general plugin APIs, specialized plugin types,
config-driven surfaces \u2014 with concrete authoring patterns for each.
plugins.md:
- 'What plugins can do' table grows from 9 rows (general ctx.register_*
only) to 14 rows covering register_platform, register_image_gen_provider,
register_context_engine, MemoryProvider subclass, register_provider
(model). Each row links to its full authoring guide.
- New 'Plugin sub-categories' section under Plugin Discovery explains
how plugins/platforms/, plugins/image_gen/, plugins/memory/,
plugins/context_engine/, plugins/model-providers/ are routed to
different loaders \u2014 PluginManager vs the per-category own-loader
systems.
- Explicit mention of user-override semantics at
~/.hermes/plugins/model-providers/ and ~/.hermes/plugins/memory/.
build-a-hermes-plugin.md:
- New '## Specialized plugin types' section (5 sub-sections):
- Model provider plugins \u2014 ProviderProfile + plugin.yaml example,
auto-wiring summary, link to full guide
- Platform plugins \u2014 BasePlatformAdapter + register_platform() skeleton
- Memory provider plugins \u2014 MemoryProvider subclass example
- Context engine plugins \u2014 ContextEngine subclass example
- Image-generation backends \u2014 ImageGenProvider + kind: backend example
- New '## Non-Python extension surfaces' section (5 sub-sections):
- MCP servers \u2014 config.yaml mcp_servers.<name> example
- Gateway event hooks \u2014 HOOK.yaml + handler.py example
- Shell hooks \u2014 hooks: block in config.yaml example
- Skill sources (taps) \u2014 hermes skills tap add example
- TTS / STT command templates \u2014 tts.providers.<name> with type: command
- Distribute via pip / NixOS promoted from ### to ## (they were orphaned
after the reorganization)
Each specialized / non-Python section has a concrete, copy-pasteable
example plus a 'Full guide:' link to the authoritative doc. Devs arriving
at the build-a-hermes-plugin guide now see every extension surface at
their disposal, not just the general tool/hook/slash-command surface.
Verified:
- Docusaurus build SUCCESS, zero new broken links
- All new cross-links (developer-guide/model-provider-plugin,
adding-platform-adapters, memory-provider-plugin, context-engine-plugin,
user-guide/features/mcp, skills#skills-hub, hooks#gateway-event-hooks,
hooks#shell-hooks, tts#custom-command-providers,
tts#voice-message-transcription-stt) resolve
- Same 3 pre-existing broken links on main (cron-script-only, llms.txt,
adding-platform-adapters#step-by-step-checklist)
* docs(plugins): fix opt-in inconsistency — not every plugin is gated
The 'Every plugin is disabled by default' statement was wrong. Several
plugin categories intentionally bypass plugins.enabled:
- Bundled platform plugins (IRC, Teams) auto-load so shipped gateway
channels are available out of the box. Activation per channel is via
gateway.platforms.<name>.enabled.
- Bundled backends (plugins/image_gen/*) auto-load so the default
backend 'just works'. Selection via <category>.provider config.
- Memory providers are all discovered; one is active via memory.provider.
- Context engines are all discovered; one is active via context.engine.
- Model providers: all 33 discovered at first get_provider_profile();
user picks via --provider / config.
The plugins.enabled allow-list specifically gates:
- Standalone plugins (general tools/hooks/slash commands)
- User-installed backends
- User-installed platforms (third-party gateway adapters)
- Pip entry-point backends
Which matches the actual code in hermes_cli/plugins.py:737 where the
bundled+backend/platform check bypasses the allow-list.
Rewrote '## Plugins are opt-in' to:
- Retitle to 'Plugins are opt-in (with a few exceptions)'
- Narrow opening claim to 'General plugins and user-installed backends
are disabled by default'
- Added 'What the allow-list does NOT gate' subsection with a full
table of which bypass the gate and how they're activated instead
- Fixed migration section wording (bundled platform/backend plugins
never needed grandfathering)
Verified: docusaurus build SUCCESS, zero new broken links.
This commit is contained in:
Teknium
GitHub
parent
90a7adcb2e
commit
b62a82e0c3
11 changed files with 656 additions and 19 deletions
|
|
@ -121,7 +121,7 @@ When you add a plugin and it calls `register_provider()`, the following wire up
|
|||
|
||||
User plugins at `$HERMES_HOME/plugins/model-providers/<name>/` override bundled plugins of the same name (last-writer-wins in `register_provider()`) — so third parties can monkey-patch or replace any built-in profile without editing the repo.
|
||||
|
||||
See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a template, and `plugins/model-providers/README.md` for the full contract.
|
||||
See `plugins/model-providers/nvidia/` or `plugins/model-providers/gmi/` as a template, and the full [Model Provider Plugin guide](/docs/developer-guide/model-provider-plugin) for field reference, hook idioms, and end-to-end examples.
|
||||
|
||||
## Full path: OAuth and complex providers
|
||||
|
||||
|
|
|
|||
267
website/docs/developer-guide/model-provider-plugin.md
Normal file
267
website/docs/developer-guide/model-provider-plugin.md
Normal file
|
|
@ -0,0 +1,267 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
title: "Model Provider Plugins"
|
||||
description: "How to build a model provider (inference backend) plugin for Hermes Agent"
|
||||
---
|
||||
|
||||
# Building a Model Provider Plugin
|
||||
|
||||
Model provider plugins declare an inference backend — an OpenAI-compatible endpoint, an Anthropic Messages server, a Codex-style Responses API, or a Bedrock-native surface — that Hermes can route `AIAgent` calls through. Every built-in provider (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia, …) ships as one of these plugins. Third parties can add their own by dropping a directory under `$HERMES_HOME/plugins/model-providers/` with zero changes to the repo.
|
||||
|
||||
:::tip
|
||||
Model provider plugins are the third kind of **provider plugin**. The others are [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) (cross-session knowledge) and [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) (context compression strategies). All three follow the same "drop a directory, declare a profile, no repo edits" pattern.
|
||||
:::
|
||||
|
||||
## How discovery works
|
||||
|
||||
`providers/__init__.py._discover_providers()` runs lazily the first time any code calls `get_provider_profile()` or `list_providers()`. Discovery order:
|
||||
|
||||
1. **Bundled plugins** — `<repo>/plugins/model-providers/<name>/` — ship with Hermes
|
||||
2. **User plugins** — `$HERMES_HOME/plugins/model-providers/<name>/` — drop in any directory; no restart required for subsequent sessions
|
||||
3. **Legacy single-file** — `<repo>/providers/<name>.py` — back-compat for out-of-tree editable installs
|
||||
|
||||
**User plugins override bundled plugins of the same name** because `register_provider()` is last-writer-wins. Drop a `$HERMES_HOME/plugins/model-providers/gmi/` directory to replace the built-in GMI profile without touching the repo.
|
||||
|
||||
## Directory structure
|
||||
|
||||
```
|
||||
plugins/model-providers/my-provider/
|
||||
├── __init__.py # Calls register_provider(profile) at module-level
|
||||
├── plugin.yaml # kind: model-provider + metadata (optional but recommended)
|
||||
└── README.md # Setup instructions (optional)
|
||||
```
|
||||
|
||||
The only required file is `__init__.py`. `plugin.yaml` is used by `hermes plugins` for introspection and by the general PluginManager to route the plugin to the right loader; without it, the general loader falls back to a source-text heuristic.
|
||||
|
||||
## Minimal example — a simple API-key provider
|
||||
|
||||
```python
|
||||
# plugins/model-providers/acme-inference/__init__.py
|
||||
from providers import register_provider
|
||||
from providers.base import ProviderProfile
|
||||
|
||||
acme = ProviderProfile(
|
||||
name="acme-inference",
|
||||
aliases=("acme",),
|
||||
display_name="Acme Inference",
|
||||
description="Acme — OpenAI-compatible direct API",
|
||||
signup_url="https://acme.example.com/keys",
|
||||
env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
|
||||
base_url="https://api.acme.example.com/v1",
|
||||
auth_type="api_key",
|
||||
default_aux_model="acme-small-fast",
|
||||
fallback_models=(
|
||||
"acme-large-v3",
|
||||
"acme-medium-v3",
|
||||
"acme-small-fast",
|
||||
),
|
||||
)
|
||||
|
||||
register_provider(acme)
|
||||
```
|
||||
|
||||
```yaml
|
||||
# plugins/model-providers/acme-inference/plugin.yaml
|
||||
name: acme-inference
|
||||
kind: model-provider
|
||||
version: 1.0.0
|
||||
description: Acme Inference — OpenAI-compatible direct API
|
||||
author: Your Name
|
||||
```
|
||||
|
||||
That's it. After dropping these two files, the following **auto-wire** with no other edits:
|
||||
|
||||
| Integration | Where | What it gets |
|
||||
|---|---|---|
|
||||
| Credential resolution | `hermes_cli/auth.py` | `PROVIDER_REGISTRY["acme-inference"]` populated from profile |
|
||||
| `--provider` CLI flag | `hermes_cli/main.py` | Accepts `acme-inference` |
|
||||
| `hermes model` picker | `hermes_cli/models.py` | Appears in `CANONICAL_PROVIDERS`, model list fetched from `{base_url}/models` |
|
||||
| `hermes doctor` | `hermes_cli/doctor.py` | Health check for `ACME_API_KEY` + `{base_url}/models` probe |
|
||||
| `hermes setup` | `hermes_cli/config.py` | `ACME_API_KEY` appears in `OPTIONAL_ENV_VARS` and the setup wizard |
|
||||
| URL reverse-mapping | `agent/model_metadata.py` | Hostname → provider name for auto-detection |
|
||||
| Auxiliary model | `agent/auxiliary_client.py` | Uses `default_aux_model` for compression / summarization |
|
||||
| Runtime resolution | `hermes_cli/runtime_provider.py` | Returns correct `base_url`, `api_key`, `api_mode` |
|
||||
| Transport | `agent/transports/chat_completions.py` | Profile path generates kwargs via `prepare_messages` / `build_extra_body` / `build_api_kwargs_extras` |
|
||||
|
||||
## ProviderProfile fields
|
||||
|
||||
Full definition in `providers/base.py`. The most useful ones:
|
||||
|
||||
| Field | Type | Purpose |
|
||||
|---|---|---|
|
||||
| `name` | str | Canonical id — matches `--provider` choices and `HERMES_INFERENCE_PROVIDER` |
|
||||
| `aliases` | `tuple[str, ...]` | Alternative names resolved by `get_provider_profile()` (e.g. `grok` → `xai`) |
|
||||
| `api_mode` | str | `chat_completions` \| `codex_responses` \| `anthropic_messages` \| `bedrock_converse` |
|
||||
| `display_name` | str | Human label shown in `hermes model` picker |
|
||||
| `description` | str | Picker subtitle |
|
||||
| `signup_url` | str | Shown during first-run setup ("get an API key here") |
|
||||
| `env_vars` | `tuple[str, ...]` | API-key env vars in priority order; a final `*_BASE_URL` entry is used as the user base-URL override |
|
||||
| `base_url` | str | Default inference endpoint |
|
||||
| `models_url` | str | Explicit catalog URL (falls back to `{base_url}/models`) |
|
||||
| `auth_type` | str | `api_key` \| `oauth_device_code` \| `oauth_external` \| `copilot` \| `aws_sdk` \| `external_process` |
|
||||
| `fallback_models` | `tuple[str, ...]` | Curated list shown when live catalog fetch fails |
|
||||
| `default_headers` | `dict[str, str]` | Sent on every request (e.g. Copilot's `Editor-Version`) |
|
||||
| `fixed_temperature` | Any | `None` = use caller's value; `OMIT_TEMPERATURE` sentinel = don't send temperature at all (Kimi) |
|
||||
| `default_max_tokens` | `int \| None` | Provider-level max_tokens cap (Nvidia: 16384) |
|
||||
| `default_aux_model` | str | Cheap model for auxiliary tasks (compression, vision, summarization) |
|
||||
|
||||
## Overridable hooks
|
||||
|
||||
Subclass `ProviderProfile` for non-trivial quirks:
|
||||
|
||||
```python
|
||||
from typing import Any
|
||||
from providers.base import ProviderProfile
|
||||
|
||||
class AcmeProfile(ProviderProfile):
|
||||
def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
"""Provider-specific message preprocessing. Runs after codex
|
||||
sanitization, before developer-role swap. Default: pass-through."""
|
||||
# Example: Qwen normalizes plain-text content to a list-of-parts
|
||||
# array and injects cache_control; Kimi rewrites tool-call JSON
|
||||
return messages
|
||||
|
||||
def build_extra_body(self, *, session_id=None, **context) -> dict:
|
||||
"""Provider-specific extra_body fields merged into the API call.
|
||||
Context includes: session_id, provider_preferences, model, base_url,
|
||||
reasoning_config. Default: empty dict."""
|
||||
# Example: OpenRouter's provider-preferences block,
|
||||
# Gemini's thinking_config translation.
|
||||
return {}
|
||||
|
||||
def build_api_kwargs_extras(self, *, reasoning_config=None, **context):
|
||||
"""Returns (extra_body_additions, top_level_kwargs). Needed when some
|
||||
fields go top-level (Kimi's reasoning_effort) and some go in extra_body
|
||||
(OpenRouter's reasoning dict). Default: ({}, {})."""
|
||||
return {}, {}
|
||||
|
||||
def fetch_models(self, *, api_key=None, timeout=8.0) -> list[str] | None:
|
||||
"""Live catalog fetch. Default hits {models_url or base_url}/models with
|
||||
Bearer auth. Override for: custom auth (Anthropic), no REST endpoint
|
||||
(Bedrock → None), or public/unauthenticated catalogs (OpenRouter)."""
|
||||
return super().fetch_models(api_key=api_key, timeout=timeout)
|
||||
```
|
||||
|
||||
## Hook reference examples
|
||||
|
||||
Look at these bundled plugins for idioms:
|
||||
|
||||
| Plugin | Why look |
|
||||
|---|---|
|
||||
| `plugins/model-providers/openrouter/` | Aggregator with provider preferences, public model catalog |
|
||||
| `plugins/model-providers/gemini/` | `thinking_config` translation (native + OpenAI-compat nested forms) |
|
||||
| `plugins/model-providers/kimi-coding/` | `OMIT_TEMPERATURE`, `extra_body.thinking`, top-level `reasoning_effort` |
|
||||
| `plugins/model-providers/qwen-oauth/` | Message normalization, `cache_control` injection, VL high-res |
|
||||
| `plugins/model-providers/nous/` | Attribution tags, "omit reasoning when disabled" |
|
||||
| `plugins/model-providers/custom/` | Ollama `num_ctx` + `think: false` quirks |
|
||||
| `plugins/model-providers/bedrock/` | `api_mode="bedrock_converse"`, `fetch_models` returns None (no REST endpoint) |
|
||||
|
||||
## User overrides — replace a built-in without editing the repo
|
||||
|
||||
Say you want to point `gmi` at your private staging endpoint for testing. Create `~/.hermes/plugins/model-providers/gmi/__init__.py`:
|
||||
|
||||
```python
|
||||
from providers import register_provider
|
||||
from providers.base import ProviderProfile
|
||||
|
||||
register_provider(ProviderProfile(
|
||||
name="gmi",
|
||||
aliases=("gmi-cloud", "gmicloud"),
|
||||
env_vars=("GMI_API_KEY",),
|
||||
base_url="https://gmi-staging.internal.example.com/v1",
|
||||
auth_type="api_key",
|
||||
default_aux_model="google/gemini-3.1-flash-lite-preview",
|
||||
))
|
||||
```
|
||||
|
||||
Next session, `get_provider_profile("gmi").base_url` returns the staging URL. No repo patch, no rebuild. Because user plugins are discovered after bundled ones, the user `register_provider()` call wins.
|
||||
|
||||
## api_mode selection
|
||||
|
||||
Four values are recognized. Hermes picks one based on:
|
||||
|
||||
1. User explicit override (`config.yaml` `model.api_mode` when set)
|
||||
2. OpenCode's per-model dispatch (`opencode_model_api_mode` for Zen and Go)
|
||||
3. URL auto-detection — `/anthropic` suffix → `anthropic_messages`, `api.openai.com` → `codex_responses`, `api.x.ai` → `codex_responses`, `/coding` on Kimi domains → `chat_completions`
|
||||
4. **Profile `api_mode`** as a fallback when URL detection finds nothing
|
||||
5. Default `chat_completions`
|
||||
|
||||
Set `profile.api_mode` to match the default your provider ships — it acts as a hint. User URL overrides still win.
|
||||
|
||||
## Auth types
|
||||
|
||||
| `auth_type` | Meaning | Who uses it |
|
||||
|---|---|---|
|
||||
| `api_key` | Single env var carries a static API key | Most providers |
|
||||
| `oauth_device_code` | Device-code OAuth flow | — |
|
||||
| `oauth_external` | User signs in elsewhere, tokens land in `auth.json` | Anthropic OAuth, MiniMax OAuth, Gemini Cloud Code, Qwen Portal, Nous Portal |
|
||||
| `copilot` | GitHub Copilot token refresh cycle | `copilot` plugin only |
|
||||
| `aws_sdk` | AWS SDK credential chain (IAM role, profile, env) | `bedrock` plugin only |
|
||||
| `external_process` | Auth handled by a subprocess the agent spawns | `copilot-acp` plugin only |
|
||||
|
||||
`auth_type` gates which codepaths treat your provider as a "simple api-key provider" — if it's not `api_key`, the PluginManager still records the manifest but Hermes' CLI-level automation (doctor checks, `--provider` flag, setup wizard delegation) may skip over it.
|
||||
|
||||
## Discovery timing
|
||||
|
||||
Provider discovery is **lazy** — triggered by the first `get_provider_profile()` or `list_providers()` call in the process. In practice this happens early at startup (`auth.py` module load extends `PROVIDER_REGISTRY` eagerly). If you need to verify your plugin loaded, run:
|
||||
|
||||
```bash
|
||||
hermes doctor
|
||||
```
|
||||
|
||||
— a successful `auth_type="api_key"` profile appears under the Provider Connectivity section with a `/models` probe.
|
||||
|
||||
For programmatic inspection:
|
||||
|
||||
```python
|
||||
from providers import list_providers
|
||||
for p in list_providers():
|
||||
print(p.name, p.base_url, p.api_mode)
|
||||
```
|
||||
|
||||
## Testing your plugin
|
||||
|
||||
Point `HERMES_HOME` at a temp directory so you don't pollute your real config:
|
||||
|
||||
```bash
|
||||
export HERMES_HOME=/tmp/hermes-plugin-test
|
||||
mkdir -p $HERMES_HOME/plugins/model-providers/my-provider
|
||||
cat > $HERMES_HOME/plugins/model-providers/my-provider/__init__.py <<'EOF'
|
||||
from providers import register_provider
|
||||
from providers.base import ProviderProfile
|
||||
register_provider(ProviderProfile(
|
||||
name="my-provider",
|
||||
env_vars=("MY_API_KEY",),
|
||||
base_url="https://api.my-provider.example.com/v1",
|
||||
auth_type="api_key",
|
||||
))
|
||||
EOF
|
||||
|
||||
export MY_API_KEY=your-test-key
|
||||
hermes -z "hello" --provider my-provider -m some-model
|
||||
```
|
||||
|
||||
## General PluginManager integration
|
||||
|
||||
The general `PluginManager` (the thing `hermes plugins` operates on) **sees** model-provider plugins but does not import them — `providers/__init__.py` owns their lifecycle. The manager records the manifest for introspection and categorizes by `kind: model-provider`. When you drop an unlabeled user plugin into `$HERMES_HOME/plugins/` that happens to call `register_provider` with a `ProviderProfile`, the manager auto-coerces it to `kind: model-provider` via a source-text heuristic — so the plugin still routes correctly even without `plugin.yaml`.
|
||||
|
||||
## Distribute via pip
|
||||
|
||||
Like any Hermes plugin, model providers can ship as a pip package. Add an entry point to your `pyproject.toml`:
|
||||
|
||||
```toml
|
||||
[project.entry-points."hermes.plugins"]
|
||||
acme-inference = "acme_hermes_plugin:register"
|
||||
```
|
||||
|
||||
…where `acme_hermes_plugin:register` is a function that calls `register_provider(profile)`. The general PluginManager picks up entry-point plugins during `discover_and_load()`. For `kind: model-provider` pip plugins, you still need to declare the kind in your manifest (or rely on the source-text heuristic).
|
||||
|
||||
See [Building a Hermes Plugin](/docs/guides/build-a-hermes-plugin#distribute-via-pip) for the full entry-points setup.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Provider Runtime](/docs/developer-guide/provider-runtime) — resolution precedence + where each layer reads the profile
|
||||
- [Adding Providers](/docs/developer-guide/adding-providers) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration)
|
||||
- [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin)
|
||||
- [Context Engine Plugins](/docs/developer-guide/context-engine-plugin)
|
||||
- [Building a Hermes Plugin](/docs/guides/build-a-hermes-plugin) — general plugin authoring
|
||||
|
|
@ -25,7 +25,7 @@ Primary implementation:
|
|||
|
||||
`get_provider_profile()` in `providers/` returns a `ProviderProfile` for a given provider id. `runtime_provider.py` calls this at resolution time to get the canonical `base_url`, `env_vars` priority list, `api_mode`, and `fallback_models` without needing to duplicate that data in multiple files. Adding a new plugin under `plugins/model-providers/<your-provider>/` (or `$HERMES_HOME/plugins/model-providers/<your-provider>/`) that calls `register_provider()` is enough for `runtime_provider.py` to pick it up — no branch needed in the resolver itself.
|
||||
|
||||
If you are trying to add a new first-class inference provider, read [Adding Providers](./adding-providers.md) alongside this page.
|
||||
If you are trying to add a new first-class inference provider, read [Adding Providers](./adding-providers.md) and the [Model Provider Plugin guide](./model-provider-plugin.md) alongside this page.
|
||||
|
||||
## Resolution precedence
|
||||
|
||||
|
|
|
|||
|
|
@ -9,6 +9,28 @@ description: "Step-by-step guide to building a complete Hermes plugin with tools
|
|||
|
||||
This guide walks through building a complete Hermes plugin from scratch. By the end you'll have a working plugin with multiple tools, lifecycle hooks, shipped data files, and a bundled skill — everything the plugin system supports.
|
||||
|
||||
:::info Not sure which guide you need?
|
||||
Hermes has several distinct pluggable interfaces — some use Python `register_*` APIs, others are config-driven or drop-in directories. Use this map first:
|
||||
|
||||
| If you want to add… | Read |
|
||||
|---|---|
|
||||
| Custom tools, hooks, slash commands, skills, or CLI subcommands | **This guide** (the general plugin surface) |
|
||||
| An **LLM / inference backend** (new provider) | [Model Provider Plugins](/docs/developer-guide/model-provider-plugin) |
|
||||
| A **gateway channel** (Discord/Telegram/IRC/Teams/etc.) | [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
|
||||
| A **memory backend** (Honcho/Mem0/Supermemory/etc.) | [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) |
|
||||
| A **context-compression engine** | [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
|
||||
| An **image-generation backend** | See bundled examples in `plugins/image_gen/openai/` and `plugins/image_gen/xai/` |
|
||||
| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, voice cloning, …) | [TTS custom command providers](/docs/user-guide/features/tts#custom-command-providers) — config-driven, no Python needed |
|
||||
| An **STT backend** (custom whisper / ASR CLI) | [Voice Message Transcription](/docs/user-guide/features/tts#voice-message-transcription-stt) — set `HERMES_LOCAL_STT_COMMAND` to a shell template |
|
||||
| **External tools via MCP** (filesystem, GitHub, Linear, any MCP server) | [MCP](/docs/user-guide/features/mcp) — declare `mcp_servers.<name>` in `config.yaml` |
|
||||
| **Gateway event hooks** (fire on startup, session events, commands) | [Event Hooks](/docs/user-guide/features/hooks#gateway-event-hooks) — drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` |
|
||||
| **Shell hooks** (run a shell command on events) | [Shell Hooks](/docs/user-guide/features/hooks#shell-hooks) — declare under `hooks:` in `config.yaml` |
|
||||
| **Additional skill sources** (custom GitHub repos, private skill indexes) | [Skills](/docs/user-guide/features/skills) — `hermes skills tap add <repo>` |
|
||||
| A first-class **core** inference provider (not a plugin) | [Adding Providers](/docs/developer-guide/adding-providers) |
|
||||
|
||||
See the full [Pluggable interfaces table](/docs/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each) for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles.
|
||||
:::
|
||||
|
||||
## What you're building
|
||||
|
||||
A **calculator** plugin with two tools:
|
||||
|
|
@ -668,12 +690,267 @@ def register(ctx):
|
|||
This is the public, stable interface for tool dispatch from plugin commands. Plugins should not reach into `ctx._cli_ref.agent` or similar private state.
|
||||
|
||||
:::tip
|
||||
This guide covers **general plugins** (tools, hooks, slash commands, CLI commands). For specialized plugin types, see:
|
||||
- [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) — cross-session knowledge backends
|
||||
- [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) — alternative context management strategies
|
||||
This guide covers **general plugins** (tools, hooks, slash commands, CLI commands). The sections below sketch the authoring pattern for each specialized plugin type; each links to its full guide for field reference and examples.
|
||||
:::
|
||||
|
||||
### Distribute via pip
|
||||
## Specialized plugin types
|
||||
|
||||
Hermes has five specialized plugin types beyond the general surface. Each ships as a directory under `plugins/<category>/<name>/` (bundled) or `~/.hermes/plugins/<category>/<name>/` (user). The contract differs by category — pick the one you need, then read its full guide.
|
||||
|
||||
### Model provider plugins — add an LLM backend
|
||||
|
||||
Drop a profile into `plugins/model-providers/<name>/`:
|
||||
|
||||
```python
|
||||
# plugins/model-providers/acme/__init__.py
|
||||
from providers import register_provider
|
||||
from providers.base import ProviderProfile
|
||||
|
||||
register_provider(ProviderProfile(
|
||||
name="acme",
|
||||
aliases=("acme-inference",),
|
||||
display_name="Acme Inference",
|
||||
env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
|
||||
base_url="https://api.acme.example.com/v1",
|
||||
auth_type="api_key",
|
||||
default_aux_model="acme-small-fast",
|
||||
fallback_models=("acme-large-v3", "acme-medium-v3"),
|
||||
))
|
||||
```
|
||||
|
||||
```yaml
|
||||
# plugins/model-providers/acme/plugin.yaml
|
||||
name: acme-provider
|
||||
kind: model-provider
|
||||
version: 1.0.0
|
||||
description: Acme Inference — OpenAI-compatible direct API
|
||||
```
|
||||
|
||||
Lazy-discovered the first time anything calls `get_provider_profile()` or `list_providers()` — `auth.py`, `config.py`, `doctor.py`, `models.py`, `runtime_provider.py`, and the chat_completions transport auto-wire to it. User plugins override bundled ones by name.
|
||||
|
||||
**Full guide:** [Model Provider Plugins](/docs/developer-guide/model-provider-plugin) — field reference, overridable hooks (`prepare_messages`, `build_extra_body`, `build_api_kwargs_extras`, `fetch_models`), api_mode selection, auth types, testing.
|
||||
|
||||
### Platform plugins — add a gateway channel
|
||||
|
||||
Drop an adapter into `plugins/platforms/<name>/`:
|
||||
|
||||
```python
|
||||
# plugins/platforms/myplatform/adapter.py
|
||||
from gateway.platforms.base import BasePlatformAdapter
|
||||
|
||||
class MyPlatformAdapter(BasePlatformAdapter):
|
||||
async def connect(self): ...
|
||||
async def send(self, chat_id, text): ...
|
||||
async def disconnect(self): ...
|
||||
|
||||
def check_requirements():
|
||||
import os
|
||||
return bool(os.environ.get("MYPLATFORM_TOKEN"))
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_platform(
|
||||
name="myplatform",
|
||||
label="MyPlatform",
|
||||
adapter_factory=lambda cfg: MyPlatformAdapter(cfg),
|
||||
check_fn=check_requirements,
|
||||
required_env=["MYPLATFORM_TOKEN"],
|
||||
emoji="💬",
|
||||
platform_hint="You are chatting via MyPlatform. Keep responses concise.",
|
||||
)
|
||||
```
|
||||
|
||||
```yaml
|
||||
# plugins/platforms/myplatform/plugin.yaml
|
||||
name: myplatform-platform
|
||||
kind: platform
|
||||
version: 1.0.0
|
||||
description: MyPlatform gateway adapter
|
||||
requires_env: [MYPLATFORM_TOKEN]
|
||||
```
|
||||
|
||||
**Full guide:** [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) — complete `BasePlatformAdapter` contract, message routing, auth gating, setup wizard integration. Look at `plugins/platforms/irc/` for a stdlib-only working example.
|
||||
|
||||
### Memory provider plugins — add a cross-session knowledge backend
|
||||
|
||||
Drop an implementation of `MemoryProvider` into `plugins/memory/<name>/`:
|
||||
|
||||
```python
|
||||
# plugins/memory/my-memory/__init__.py
|
||||
from agent.memory_provider import MemoryProvider
|
||||
|
||||
class MyMemoryProvider(MemoryProvider):
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "my-memory"
|
||||
|
||||
def is_available(self) -> bool:
|
||||
import os
|
||||
return bool(os.environ.get("MY_MEMORY_API_KEY"))
|
||||
|
||||
def initialize(self, session_id: str, **kwargs) -> None:
|
||||
self._session_id = session_id
|
||||
|
||||
def sync_turn(self, user_message, assistant_response, **kwargs) -> None:
|
||||
...
|
||||
|
||||
def prefetch(self, query: str, **kwargs) -> str | None:
|
||||
...
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_memory_provider(MyMemoryProvider())
|
||||
```
|
||||
|
||||
Memory providers are single-select — only one is active at a time, chosen via `memory.provider` in `config.yaml`.
|
||||
|
||||
**Full guide:** [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) — full `MemoryProvider` ABC, threading contract, profile isolation, CLI command registration via `cli.py`.
|
||||
|
||||
### Context engine plugins — replace the context compressor
|
||||
|
||||
```python
|
||||
# plugins/context_engine/my-engine/__init__.py
|
||||
from agent.context_engine import ContextEngine
|
||||
|
||||
class MyContextEngine(ContextEngine):
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "my-engine"
|
||||
|
||||
def should_compress(self, messages, model) -> bool: ...
|
||||
def compress(self, messages, model) -> list[dict]: ...
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_context_engine(MyContextEngine())
|
||||
```
|
||||
|
||||
Context engines are single-select — chosen via `context.engine` in `config.yaml`.
|
||||
|
||||
**Full guide:** [Context Engine Plugins](/docs/developer-guide/context-engine-plugin).
|
||||
|
||||
### Image-generation backends
|
||||
|
||||
Drop a provider into `plugins/image_gen/<name>/`:
|
||||
|
||||
```python
|
||||
# plugins/image_gen/my-imggen/__init__.py
|
||||
from agent.image_gen_provider import ImageGenProvider
|
||||
|
||||
class MyImageGenProvider(ImageGenProvider):
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "my-imggen"
|
||||
|
||||
def is_available(self) -> bool: ...
|
||||
def generate(self, prompt: str, **kwargs) -> str: ... # returns image path
|
||||
|
||||
def register(ctx):
|
||||
ctx.register_image_gen_provider(MyImageGenProvider())
|
||||
```
|
||||
|
||||
```yaml
|
||||
# plugins/image_gen/my-imggen/plugin.yaml
|
||||
name: my-imggen
|
||||
kind: backend
|
||||
version: 1.0.0
|
||||
description: Custom image generation backend
|
||||
```
|
||||
|
||||
**Reference examples:** `plugins/image_gen/openai/` (DALL-E / GPT-Image via OpenAI SDK), `plugins/image_gen/openai-codex/`, `plugins/image_gen/xai/` (Grok image gen).
|
||||
|
||||
## Non-Python extension surfaces
|
||||
|
||||
Hermes also accepts extensions that aren't Python plugins at all. These are shown in the [Pluggable interfaces table](/docs/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each); the sections below sketch each authoring style briefly.
|
||||
|
||||
### MCP servers — register external tools
|
||||
|
||||
Model Context Protocol (MCP) servers register their own tools into Hermes without any Python plugin. Declare them in `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
timeout: 120
|
||||
|
||||
linear:
|
||||
url: "https://mcp.linear.app/sse"
|
||||
auth:
|
||||
type: "oauth"
|
||||
```
|
||||
|
||||
Hermes connects to each server at startup, lists its tools, and registers them alongside built-ins. The LLM sees them exactly like any other tool. **Full guide:** [MCP](/docs/user-guide/features/mcp).
|
||||
|
||||
### Gateway event hooks — fire on lifecycle events
|
||||
|
||||
Drop a manifest + handler into `~/.hermes/hooks/<name>/`:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/hooks/long-task-alert/HOOK.yaml
|
||||
name: long-task-alert
|
||||
description: Send a push notification when a long task finishes
|
||||
events:
|
||||
- agent:end
|
||||
```
|
||||
|
||||
```python
|
||||
# ~/.hermes/hooks/long-task-alert/handler.py
|
||||
async def handle(event_type: str, context: dict) -> None:
|
||||
if context.get("duration_seconds", 0) > 120:
|
||||
# send notification …
|
||||
pass
|
||||
```
|
||||
|
||||
Events include `gateway:startup`, `session:start`, `session:end`, `session:reset`, `agent:start`, `agent:step`, `agent:end`, and wildcard `command:*`. Errors in hooks are caught and logged — they never block the main pipeline.
|
||||
|
||||
**Full guide:** [Gateway Event Hooks](/docs/user-guide/features/hooks#gateway-event-hooks).
|
||||
|
||||
### Shell hooks — run a shell command on tool calls
|
||||
|
||||
If you just want to run a script when a tool fires (notifications, audit logs, desktop alerts, auto-formatters), use shell hooks in `config.yaml` — no Python required:
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
- event: post_tool_call
|
||||
command: "notify-send 'Tool ran: {tool_name}'"
|
||||
when:
|
||||
tools: [terminal, patch, write_file]
|
||||
```
|
||||
|
||||
Supports all the same events as Python plugin hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`, `pre_gateway_dispatch`) plus structured JSON output for `pre_tool_call` blocking decisions.
|
||||
|
||||
**Full guide:** [Shell Hooks](/docs/user-guide/features/hooks#shell-hooks).
|
||||
|
||||
### Skill sources — add a custom skill registry
|
||||
|
||||
If you maintain a private GitHub repo of skills (or want to pull from a community index beyond the built-in sources), add it as a **tap**:
|
||||
|
||||
```bash
|
||||
hermes skills tap add myorg/skills-repo
|
||||
hermes skills search my-workflow --source myorg/skills-repo
|
||||
hermes skills install myorg/skills-repo/my-workflow
|
||||
```
|
||||
|
||||
**Full guide:** [Skills Hub](/docs/user-guide/features/skills#skills-hub).
|
||||
|
||||
### TTS / STT via command templates
|
||||
|
||||
Any CLI that reads/writes audio or text can be plugged in through `config.yaml` — no Python code:
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
provider: voxcpm
|
||||
providers:
|
||||
voxcpm:
|
||||
type: command
|
||||
command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
|
||||
output_format: mp3
|
||||
voice_compatible: true
|
||||
```
|
||||
|
||||
For STT, point `HERMES_LOCAL_STT_COMMAND` at a shell template. Supported placeholders: `{input_path}`, `{output_path}`, `{format}`, `{voice}`, `{model}`, `{speed}` (TTS); `{input_path}`, `{output_dir}`, `{language}`, `{model}` (STT). Any path-interacting CLI is automatically a plugin.
|
||||
|
||||
**Full guides:** [TTS custom command providers](/docs/user-guide/features/tts#custom-command-providers) · [STT](/docs/user-guide/features/tts#voice-message-transcription-stt).
|
||||
|
||||
## Distribute via pip
|
||||
|
||||
For sharing plugins publicly, add an entry point to your Python package:
|
||||
|
||||
|
|
@ -688,7 +965,7 @@ pip install hermes-plugin-calculator
|
|||
# Plugin auto-discovered on next hermes startup
|
||||
```
|
||||
|
||||
### Distribute for NixOS
|
||||
## Distribute for NixOS
|
||||
|
||||
NixOS users can install your plugin declaratively if you provide a `pyproject.toml` with entry points:
|
||||
|
||||
|
|
|
|||
|
|
@ -93,6 +93,8 @@ Project-local plugins under `./.hermes/plugins/` are disabled by default. Enable
|
|||
|
||||
## What plugins can do
|
||||
|
||||
Every `ctx.*` API below is available inside a plugin's `register(ctx)` function.
|
||||
|
||||
| Capability | How |
|
||||
|-----------|-----|
|
||||
| Add tools | `ctx.register_tool(name=..., toolset=..., schema=..., handler=...)` |
|
||||
|
|
@ -105,6 +107,11 @@ Project-local plugins under `./.hermes/plugins/` are disabled by default. Enable
|
|||
| Bundle skills | `ctx.register_skill(name, path)` — namespaced as `plugin:skill`, loaded via `skill_view("plugin:skill")` |
|
||||
| Gate on env vars | `requires_env: [API_KEY]` in plugin.yaml — prompted during `hermes plugins install` |
|
||||
| Distribute via pip | `[project.entry-points."hermes_agent.plugins"]` |
|
||||
| Register a gateway platform (Discord, Telegram, IRC, …) | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — see [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
|
||||
| Register an image-generation backend | `ctx.register_image_gen_provider(provider)` — see `plugins/image_gen/openai/` for an example |
|
||||
| Register a context-compression engine | `ctx.register_context_engine(engine)` — see [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
|
||||
| Register a memory backend | Subclass `MemoryProvider` in `plugins/memory/<name>/__init__.py` — see [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) (uses a separate discovery system) |
|
||||
| Register an inference backend (LLM provider) | `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/__init__.py` — see [Model Provider Plugins](/docs/developer-guide/model-provider-plugin) (uses a separate discovery system) |
|
||||
|
||||
## Plugin discovery
|
||||
|
||||
|
|
@ -118,9 +125,24 @@ Project-local plugins under `./.hermes/plugins/` are disabled by default. Enable
|
|||
|
||||
Later sources override earlier ones on name collision, so a user plugin with the same name as a bundled plugin replaces it.
|
||||
|
||||
## Plugins are opt-in
|
||||
### Plugin sub-categories
|
||||
|
||||
**Every plugin — user-installed, bundled, or pip — is disabled by default.** Discovery finds them (so they show up in `hermes plugins` and `/plugins`), but nothing loads until you add the plugin's name to `plugins.enabled` in `~/.hermes/config.yaml`. This stops anything with hooks or tools from running without your explicit consent.
|
||||
Within each source, Hermes also recognizes sub-category directories that route plugins to specialized discovery systems:
|
||||
|
||||
| Sub-directory | What it holds | Discovery system |
|
||||
|---|---|---|
|
||||
| `plugins/` (root) | General plugins — tools, hooks, slash commands, CLI commands, bundled skills | `PluginManager` (kind: `standalone` or `backend`) |
|
||||
| `plugins/platforms/<name>/` | Gateway channel adapters (`ctx.register_platform()`) | `PluginManager` (kind: `platform`, one level deeper) |
|
||||
| `plugins/image_gen/<name>/` | Image-generation backends (`ctx.register_image_gen_provider()`) | `PluginManager` (kind: `backend`, one level deeper) |
|
||||
| `plugins/memory/<name>/` | Memory providers (subclass `MemoryProvider`) | **Own loader** in `plugins/memory/__init__.py` (kind: `exclusive` — one active at a time) |
|
||||
| `plugins/context_engine/<name>/` | Context-compression engines (`ctx.register_context_engine()`) | **Own loader** in `plugins/context_engine/__init__.py` (one active at a time) |
|
||||
| `plugins/model-providers/<name>/` | LLM provider profiles (`register_provider(ProviderProfile(...))`) | **Own loader** in `providers/__init__.py` (lazily scanned on first `get_provider_profile()` call) |
|
||||
|
||||
User plugins at `~/.hermes/plugins/model-providers/<name>/` and `~/.hermes/plugins/memory/<name>/` override bundled plugins of the same name — last-writer-wins in `register_provider()` / `register_memory_provider()`. Drop a directory in, and it replaces the built-in without any repo edits.
|
||||
|
||||
## Plugins are opt-in (with a few exceptions)
|
||||
|
||||
**General plugins and user-installed backends are disabled by default** — discovery finds them (so they show up in `hermes plugins` and `/plugins`), but nothing with hooks or tools loads until you add the plugin's name to `plugins.enabled` in `~/.hermes/config.yaml`. This stops third-party code from running without your explicit consent.
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
|
|
@ -141,9 +163,25 @@ hermes plugins disable <name> # remove from allow-list + add to disabled
|
|||
|
||||
After `hermes plugins install owner/repo`, you're asked `Enable 'name' now? [y/N]` — defaults to no. Skip the prompt for scripted installs with `--enable` or `--no-enable`.
|
||||
|
||||
### What the allow-list does NOT gate
|
||||
|
||||
Several categories of plugin bypass `plugins.enabled` — they're part of Hermes' built-in surface and would break basic functionality if gated off by default:
|
||||
|
||||
| Plugin kind | How it's activated instead |
|
||||
|---|---|
|
||||
| **Bundled platform plugins** (IRC, Teams, etc. under `plugins/platforms/`) | Auto-loaded so every shipped gateway channel is available. The actual channel turns on via `gateway.platforms.<name>.enabled` in `config.yaml`. |
|
||||
| **Bundled backends** (image-gen providers under `plugins/image_gen/`, etc.) | Auto-loaded so the default backend "just works". Selection happens via `<category>.provider` in `config.yaml` (e.g. `image_gen.provider: openai`). |
|
||||
| **Memory providers** (`plugins/memory/`) | All discovered; exactly one is active, chosen by `memory.provider` in `config.yaml`. |
|
||||
| **Context engines** (`plugins/context_engine/`) | All discovered; one is active, chosen by `context.engine` in `config.yaml`. |
|
||||
| **Model providers** (`plugins/model-providers/`) | All 33 providers discover and register at the first `get_provider_profile()` call. The user picks one at a time via `--provider` or `config.yaml`. |
|
||||
| **Pip-installed `backend` plugins** | Opt-in via `plugins.enabled` (same as general plugins). |
|
||||
| **User-installed platforms** (under `~/.hermes/plugins/platforms/`) | Opt-in via `plugins.enabled` — third-party gateway adapters need explicit consent. |
|
||||
|
||||
In short: **bundled "always-works" infrastructure loads automatically; third-party general plugins are opt-in.** The `plugins.enabled` allow-list is the gate specifically for arbitrary code a user drops into `~/.hermes/plugins/`.
|
||||
|
||||
### Migration for existing users
|
||||
|
||||
When you upgrade to a version of Hermes that has opt-in plugins (config schema v21+), any user plugins already installed under `~/.hermes/plugins/` that weren't already in `plugins.disabled` are **automatically grandfathered** into `plugins.enabled`. Your existing setup keeps working. Bundled plugins are NOT grandfathered — even existing users have to opt in explicitly.
|
||||
When you upgrade to a version of Hermes that has opt-in plugins (config schema v21+), any user plugins already installed under `~/.hermes/plugins/` that weren't already in `plugins.disabled` are **automatically grandfathered** into `plugins.enabled`. Your existing setup keeps working. Bundled standalone plugins are NOT grandfathered — even existing users have to opt in explicitly. (Bundled platform/backend plugins never needed grandfathering because they were never gated.)
|
||||
|
||||
## Available hooks
|
||||
|
||||
|
|
@ -164,15 +202,43 @@ Plugins can register callbacks for these lifecycle events. See the **[Event Hook
|
|||
|
||||
## Plugin types
|
||||
|
||||
Hermes has three kinds of plugins:
|
||||
Hermes has four kinds of plugins:
|
||||
|
||||
| Type | What it does | Selection | Location |
|
||||
|------|-------------|-----------|----------|
|
||||
| **General plugins** | Add tools, hooks, slash commands, CLI commands | Multi-select (enable/disable) | `~/.hermes/plugins/` |
|
||||
| **Memory providers** | Replace or augment built-in memory | Single-select (one active) | `plugins/memory/` |
|
||||
| **Context engines** | Replace the built-in context compressor | Single-select (one active) | `plugins/context_engine/` |
|
||||
| **Model providers** | Declare an inference backend (OpenRouter, Anthropic, …) | Multi-register, picked by `--provider` / `config.yaml` | `plugins/model-providers/` |
|
||||
|
||||
Memory providers and context engines are **provider plugins** — only one of each type can be active at a time. General plugins can be enabled in any combination.
|
||||
Memory providers and context engines are **provider plugins** — only one of each type can be active at a time. Model providers are also plugins, but many load simultaneously; the user picks one at a time via `--provider` or `config.yaml`. General plugins can be enabled in any combination.
|
||||
|
||||
## Pluggable interfaces — where to go for each
|
||||
|
||||
The table above shows the four plugin categories, but within "General plugins" the `PluginContext` exposes several distinct extension points — and Hermes also accepts extensions outside the Python plugin system (config-driven backends, shell-hooked commands, external servers, etc.). Use this table to find the right doc for what you want to build:
|
||||
|
||||
| Want to add… | How | Authoring guide |
|
||||
|---|---|---|
|
||||
| A **tool** the LLM can call | Python plugin — `ctx.register_tool()` | [Build a Hermes Plugin](/docs/guides/build-a-hermes-plugin) · [Adding Tools](/docs/developer-guide/adding-tools) |
|
||||
| A **lifecycle hook** (pre/post LLM, session start/end, tool filter) | Python plugin — `ctx.register_hook()` | [Hooks reference](/docs/user-guide/features/hooks) · [Build a Hermes Plugin](/docs/guides/build-a-hermes-plugin) |
|
||||
| A **slash command** for the CLI / gateway | Python plugin — `ctx.register_command()` | [Build a Hermes Plugin](/docs/guides/build-a-hermes-plugin) · [Extending the CLI](/docs/developer-guide/extending-the-cli) |
|
||||
| A **subcommand** for `hermes <thing>` | Python plugin — `ctx.register_cli_command()` | [Extending the CLI](/docs/developer-guide/extending-the-cli) |
|
||||
| A bundled **skill** that your plugin ships | Python plugin — `ctx.register_skill()` | [Creating Skills](/docs/developer-guide/creating-skills) |
|
||||
| An **inference backend** (LLM provider: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Provider plugin — `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/` | **[Model Provider Plugins](/docs/developer-guide/model-provider-plugin)** · [Adding Providers](/docs/developer-guide/adding-providers) |
|
||||
| A **gateway channel** (Discord / Telegram / IRC / Teams / etc.) | Platform plugin — `ctx.register_platform()` in `plugins/platforms/<name>/` | [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
|
||||
| A **memory backend** (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass `MemoryProvider` in `plugins/memory/<name>/` | [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) |
|
||||
| A **context-compression strategy** | Context-engine plugin — `ctx.register_context_engine()` | [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
|
||||
| An **image-generation backend** (DALL·E, SDXL, …) | Backend plugin — `ctx.register_image_gen_provider()` | See bundled examples in `plugins/image_gen/openai/` and `plugins/image_gen/xai/` |
|
||||
| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, xtts, voice-cloning scripts, …) | Config-driven — declare under `tts.providers.<name>` with `type: command` in `config.yaml` | [TTS setup](/docs/user-guide/features/tts#custom-command-providers) |
|
||||
| An **STT backend** (custom whisper binary, local ASR CLI) | Config-driven — set `HERMES_LOCAL_STT_COMMAND` env var to a shell template | [Voice Message Transcription (STT)](/docs/user-guide/features/tts#voice-message-transcription-stt) |
|
||||
| **External tools via MCP** (filesystem, GitHub, Linear, Notion, any MCP server) | Config-driven — declare `mcp_servers.<name>` with `command:` / `url:` in `config.yaml`. Hermes auto-discovers the server's tools and registers them alongside built-ins. | [MCP](/docs/user-guide/features/mcp) |
|
||||
| **Additional skill sources** (custom GitHub repos, private skill indexes) | CLI — `hermes skills tap add <repo>` | [Skills Hub](/docs/user-guide/features/skills#skills-hub) |
|
||||
| **Gateway event hooks** (fire on `gateway:startup`, `session:start`, `agent:end`, `command:*`) | Drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` | [Event Hooks](/docs/user-guide/features/hooks#gateway-event-hooks) |
|
||||
| **Shell hooks** (run a shell command on events — notifications, audit logs, desktop alerts) | Config-driven — declare under `hooks:` in `config.yaml` | [Shell Hooks](/docs/user-guide/features/hooks#shell-hooks) |
|
||||
|
||||
:::note
|
||||
Not everything is a Python plugin. Some extension surfaces intentionally use **config-driven shell commands** (TTS, STT, shell hooks) so any CLI you already have becomes a plugin without writing Python. Others are **external servers** (MCP) the agent connects to and auto-registers tools from. And some are **drop-in directories** (gateway hooks) with their own manifest format. Pick the right surface for the integration style that fits your use case; the authoring guides in the table above each cover placeholders, discovery, and examples.
|
||||
:::
|
||||
|
||||
## NixOS declarative plugins
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue