feat(plugins): add llm-switch example plugin for local server management

[crxssrazr93]

Summary

Example plugin demonstrating the lifecycle hooks activated in #3542. Auto-manages a local llama-server (or any OpenAI-compatible server) when the active model matches a locally configured model name.

This is a plugin-only PR — no core changes. All hook infrastructure was already merged in #3542.

Supersedes #2930 (which included core hook patches before #3542 was merged).

What it does

• pre_llm_call hook: Detects when the active model name matches a key in models.yaml. If the correct server isn't running, starts it automatically before the LLM call proceeds.
• on_session_end hook: Kills the server when the session ends.
• switch_local_llm tool: Mid-session model switching — the agent calls this when asked "switch to the code model". Swaps the server behind the scenes while the endpoint stays the same.
• Declarative YAML config: Define models with GGUF paths, context sizes, KV cache quantization, and sampling params. Replaces shell scripts.

Example models.yaml

server:
  binary: llama-server
  models_dir: ~/llama-models
  port: 8080
  gpu_layers: 99
  flash_attention: true

models:
  write:
    description: "SEO articles and content briefs"
    gguf: qwen3.5-9b/Qwen3.5-9B-UD-Q6_K_XL.gguf
    context: 49152
    kv_cache: { key: q8_0, value: q4_0 }
    sampling: { temp: 0.7, top_p: 0.8, top_k: 20 }

  code:
    description: "Agentic coding and tool calling"
    gguf: omnicoder-9b/omnicoder-9b-q4_k_m.gguf
    context: 65536
    sampling: { temp: 0.6, top_p: 0.95 }

User flow

1. hermes model → select custom provider → pick model name matching models.yaml key
2. Start chatting → pre_llm_call hook auto-starts the server on first message
3. Mid-session: "switch to the code model" → agent calls switch_local_llm tool → server swaps
4. Exit → on_session_end kills server

Relationship to other PRs

• Builds on feat: activate plugin lifecycle hooks (pre/post_llm_call, session start/end) #3542 — uses the lifecycle hooks activated there
• Complements feat: restore /model slash command for CLI and gateway #3360 / fix(cli): restore /model command handler #3548 — once /model is restored as a slash command, /model custom:write would trigger the pre_llm_call hook to auto-start the right server seamlessly

Changes

6 new files in docs/llm-switch-plugin-example/:

File	Purpose
plugin.yaml	Manifest
__init__.py	Registration, hook handlers, tool handler
schemas.py	Tool schema for switch_local_llm
server.py	Pure Python server lifecycle (start, stop, health check)
models.yaml.example	Example config with full schema documentation
README.md	Setup instructions, usage, and config reference

Testing

• Plugin is self-contained — copy to ~/.hermes/plugins/llm-switch/, add models.yaml, verify with /plugins
• No existing code is modified — zero regression risk

Platforms tested

• Linux (Arch)

[teknium1]

Thanks for the self-contained plugin implementation and the detailed setup material.

This automated hermes-sweeper review is closing it under the standing in-tree-provider-integration policy:

• docs/llm-switch-plugin-example/plugin.yaml:1 and README.md:3 implement an installable integration for llama.cpp/vLLM-style third-party local-server products.
• AGENTS.md:126-136 requires third-party product integrations to ship as standalone plugin repositories, installed under ~/.hermes/plugins/ (or as a pip entry point), rather than being maintained in this repository.
• Hermes already supports local OpenAI-compatible endpoints through named custom providers (website/docs/integrations/providers.md:1178), so a standalone plugin can target that supported extension surface.

Please publish this as a standalone plugin repo that users can install under ~/.hermes/plugins/, and promote it in #plugins-skills-and-skins. That keeps ownership and compatibility maintenance with the integration while preserving the plugin approach used here.

---

Closed as not-planned per standing maintainer policy (in-tree-provider-integration). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.