diff --git a/AGENTS.md b/AGENTS.md index b77a1d2699..0c8550d459 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,7 @@ hermes-agent/ ├── plugins/ # Plugin system (see "Plugins" section below) │ ├── memory/ # Memory-provider plugins (honcho, mem0, supermemory, ...) │ ├── context_engine/ # Context-engine plugins +│ ├── model-providers/ # Inference backend plugins (openrouter, anthropic, gmi, ...) │ ├── kanban/ # Multi-agent board dispatcher + worker plugin │ ├── hermes-achievements/ # Gamified achievement tracking │ ├── observability/ # Metrics / traces / logs plugin @@ -512,6 +513,31 @@ generic plugin surface (new hook, new ctx method) — never hardcode plugin-specific logic into core. PR #5295 removed 95 lines of hardcoded honcho argparse from `main.py` for exactly this reason. +### Model-provider plugins (`plugins/model-providers//`) + +Every inference backend (openrouter, anthropic, gmi, deepseek, nvidia, …) +ships as a plugin here. Each plugin's `__init__.py` calls +`providers.register_provider(ProviderProfile(...))` at module load. +`providers/__init__.py._discover_providers()` is a **lazy, separate +discovery system** — scanned on first `get_provider_profile()` or +`list_providers()` call, NOT by the general PluginManager. + +Scan order: +1. Bundled: `/plugins/model-providers//` +2. User: `$HERMES_HOME/plugins/model-providers//` +3. Legacy: `/providers/.py` (back-compat) + +User plugins of the same name override bundled ones — `register_provider()` +is last-writer-wins. This lets third parties swap out any built-in +profile without a repo patch. + +The general PluginManager records `kind: model-provider` manifests but does +NOT import them (would double-instantiate `ProviderProfile`). Plugins +without an explicit `kind:` get auto-coerced via a source-text heuristic +(`register_provider` + `ProviderProfile` in `__init__.py`). + +Full authoring guide: `website/docs/developer-guide/model-provider-plugin.md`. + ### Dashboard / context-engine / image-gen plugin directories `plugins/context_engine/`, `plugins/image_gen/`, `plugins/example-dashboard/`, diff --git a/hermes_cli/auth.py b/hermes_cli/auth.py index 6695c9ab95..48abb1fa12 100644 --- a/hermes_cli/auth.py +++ b/hermes_cli/auth.py @@ -418,7 +418,7 @@ PROVIDER_REGISTRY: Dict[str, ProviderConfig] = { # Auto-extend PROVIDER_REGISTRY with any api-key provider registered in # providers/ that is not already declared above. New providers only need a -# providers/*.py file — no edits to this file required. +# plugins/model-providers// plugin — no edits to this file required. try: from providers import list_providers as _list_providers_for_registry for _pp in _list_providers_for_registry(): @@ -1229,7 +1229,7 @@ def resolve_provider( "vllm": "custom", "llamacpp": "custom", "llama.cpp": "custom", "llama-cpp": "custom", } - # Extend with aliases declared in providers/*.py that aren't already mapped. + # Extend with aliases declared in plugins/model-providers// that aren't already mapped. # This keeps providers/ as the single source for new aliases while the # hardcoded dict above remains authoritative for existing ones. try: diff --git a/hermes_cli/doctor.py b/hermes_cli/doctor.py index 4940b7fa5a..fce4b533d9 100644 --- a/hermes_cli/doctor.py +++ b/hermes_cli/doctor.py @@ -197,7 +197,7 @@ def _build_apikey_providers_list() -> list: Tuple format: (name, env_vars, default_url, base_env, supports_models_endpoint) Base list augmented with any ProviderProfile with auth_type="api_key" not - already present — adding providers/*.py is sufficient to get into doctor. + already present — adding plugins/model-providers// is sufficient to get into doctor. """ _static = [ ("Z.AI / GLM", ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL", True), diff --git a/hermes_cli/main.py b/hermes_cli/main.py index 19029d7207..26d957f819 100644 --- a/hermes_cli/main.py +++ b/hermes_cli/main.py @@ -1706,7 +1706,7 @@ def _is_profile_api_key_provider(provider_id: str) -> bool: """Return True when provider_id maps to a profile with auth_type='api_key'. Used as a catch-all in select_provider_and_model() so that new providers - declared in providers/*.py automatically dispatch to _model_flow_api_key_provider + declared in plugins/model-providers// automatically dispatch to _model_flow_api_key_provider without requiring an explicit elif branch here. """ try: diff --git a/hermes_cli/models.py b/hermes_cli/models.py index 8b00cf5d10..40a8f3c107 100644 --- a/hermes_cli/models.py +++ b/hermes_cli/models.py @@ -811,9 +811,9 @@ CANONICAL_PROVIDERS: list[ProviderEntry] = [ ] # Auto-extend CANONICAL_PROVIDERS with any provider registered in providers/ -# that is not already in the list above. Adding providers/*.py is sufficient -# to expose a new provider in the model picker, /model, and all downstream -# consumers — no edits to this file needed. +# that is not already in the list above. Adding plugins/model-providers// +# is sufficient to expose a new provider in the model picker, /model, and all +# downstream consumers — no edits to this file needed. _canonical_slugs = {p.slug for p in CANONICAL_PROVIDERS} try: from providers import list_providers as _list_providers_for_canonical diff --git a/website/docs/developer-guide/adding-providers.md b/website/docs/developer-guide/adding-providers.md index 3cd358849a..212152fb03 100644 --- a/website/docs/developer-guide/adding-providers.md +++ b/website/docs/developer-guide/adding-providers.md @@ -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//` 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 diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.md new file mode 100644 index 0000000000..529eec28f8 --- /dev/null +++ b/website/docs/developer-guide/model-provider-plugin.md @@ -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** — `/plugins/model-providers//` — ship with Hermes +2. **User plugins** — `$HERMES_HOME/plugins/model-providers//` — drop in any directory; no restart required for subsequent sessions +3. **Legacy single-file** — `/providers/.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 diff --git a/website/docs/developer-guide/provider-runtime.md b/website/docs/developer-guide/provider-runtime.md index 40d6cd7d9a..492a213e1f 100644 --- a/website/docs/developer-guide/provider-runtime.md +++ b/website/docs/developer-guide/provider-runtime.md @@ -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//` (or `$HERMES_HOME/plugins/model-providers//`) 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 diff --git a/website/docs/guides/build-a-hermes-plugin.md b/website/docs/guides/build-a-hermes-plugin.md index d702b70b43..a005035d5c 100644 --- a/website/docs/guides/build-a-hermes-plugin.md +++ b/website/docs/guides/build-a-hermes-plugin.md @@ -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.` 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//` | +| **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 ` | +| 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///` (bundled) or `~/.hermes/plugins///` (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//`: + +```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//`: + +```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//`: + +```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//`: + +```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//`: + +```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: diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md index 383c8aaa83..bd49b02bf6 100644 --- a/website/docs/user-guide/features/plugins.md +++ b/website/docs/user-guide/features/plugins.md @@ -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//__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//__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//` | Gateway channel adapters (`ctx.register_platform()`) | `PluginManager` (kind: `platform`, one level deeper) | +| `plugins/image_gen//` | Image-generation backends (`ctx.register_image_gen_provider()`) | `PluginManager` (kind: `backend`, one level deeper) | +| `plugins/memory//` | Memory providers (subclass `MemoryProvider`) | **Own loader** in `plugins/memory/__init__.py` (kind: `exclusive` — one active at a time) | +| `plugins/context_engine//` | Context-compression engines (`ctx.register_context_engine()`) | **Own loader** in `plugins/context_engine/__init__.py` (one active at a time) | +| `plugins/model-providers//` | 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//` and `~/.hermes/plugins/memory//` 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 # 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..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 `.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 ` | 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//` | **[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//` | [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) | +| A **memory backend** (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass `MemoryProvider` in `plugins/memory//` | [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.` 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.` 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 ` | [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//` | [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 diff --git a/website/sidebars.ts b/website/sidebars.ts index 96ea3d6179..611bdbf554 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -210,6 +210,7 @@ const sidebars: SidebarsConfig = { 'developer-guide/adding-platform-adapters', 'developer-guide/memory-provider-plugin', 'developer-guide/context-engine-plugin', + 'developer-guide/model-provider-plugin', 'developer-guide/creating-skills', 'developer-guide/extending-the-cli', ],