SyslogSolution/prose-contracts
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add hermes-config-template prose contract with shared infra + flexible models

Browse Source
This commit is contained in:
jerome
2026-06-28 13:33:06 -04:00
parent 8711840b26
commit 6a8a2c61da
1 changed files with 246 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
hermes-config-template.prose.md
+246
View File
@@ -0,0 +1,246 @@
---
kind: template
name: hermes-config-template
description: >
Standard Hermes configuration template for Syslog Solution LLC agents.
Enforces shared infrastructure setup (Firecrawl, SearXNG, local models,
RA-H OS MCP) while keeping model/provider choices flexible per agent role.
Every new agent profile should start from this template.
---
## Maintains
- template_version: string — Current template version (e.g., "1.0.0")
- last_applied: timestamp — When any agent was last configured from this template
- agents_configured: array — Which agents/profiles were created from this template
- infra_endpoints_verified: array — Firecrawl, SearXNG, RA-H OS, LiteLLM endpoints last confirmed working
- known_deviations: array — Profiles that diverge from the template (and why)
## Parameters
- agent_name: string — Name of the agent/profile (e.g., "syslog-code", "syslog-devops")
- default_model: string — Agent's primary model (e.g., "qwen3.6-27B-code", "syslog-auto")
- default_provider: string — Inference provider for the primary model (default: "harness")
- fallback_model: string — Fallback model when primary is down (default: "gemma-4-12b")
- fallback_provider: string — Fallback provider (default: "harness")
- auxiliary_model: string — Model for vision/compression/extraction tasks (default: "gemma-4-12b")
- enable_firecrawl_searxng: boolean — Whether to configure web search/extract (default: true)
- enable_ra_h_os_mcp: boolean — Whether to wire up RA-H OS MCP bridge (default: true)
- enable_compression: boolean — Whether to enable context compression (default: true)
- custom_provider_name: string — Custom provider name (default: "harness")
- custom_provider_model: string — Custom provider model (default: same as default_model)
- custom_provider_url: string — LiteLLM base URL (default: "http://litellm.sysloggh.net/litellm/v1")
- extra_auxiliary: array — Additional auxiliary tasks to configure (vision, compression, etc.)
- output_dir: string — Where to write the config (default: "~/.hermes/profiles/<agent_name>/config.yaml")
## Infrastructure Stack
This template provisions the following shared infrastructure. Every agent should point to the same endpoints unless explicitly overridden.
| Component | Endpoint | Purpose |
|---|---|---|
| Firecrawl | `http://192.168.68.7:3002/` | Web content extraction |
| SearXNG | `http://storepve:8888` | Privacy-respecting web search |
| LiteLLM | `http://litellm.sysloggh.net/litellm/v1` | Unified model gateway |
| RA-H OS MCP | `http://192.168.68.65:3100/mcp` | Knowledge graph bridge |
| Context7 MCP | `http://localhost:8079/mcp` | Documentation queries |
**API Key Rules:**
- `api_key: sk-_SW...B8nw` — Hardcoded LiteLLM master key for custom_providers and auxiliary tasks
- `api_key_env: DEEPSEEK_API_KEY` — Env-var based key for fallback provider
- Worker profiles should inherit proxy config via `harness` custom_provider, NOT hardcode LiteLLM keys
**For workers that need API keys overridden:** Set `api_key: ''` in the model section (inherits from custom_providers), or use `api_key_env` for env-based auth.
## Template Structure
### Required Sections (every agent MUST have)
```yaml
# ─── Model Selection (USER CHOOSES) ───
model:
# !! CHANGE THIS for your agent !!
default: <agent_default_model>
provider: <agent_default_provider>
# LiteLLM base URL (shared infra)
base_url: http://litellm.sysloggh.net/litellm/v1
fallback_providers:
# !! OPTIONAL: overridable fallback !!
provider: <fallback_provider>
model: <fallback_model>
# ─── Web Stack (SHARED INFRA — DO NOT CHANGE) ───
web:
backend: firecrawl
search_backend: searxng
extract_backend: firecrawl
firecrawl:
base_url: http://192.168.68.7:3002/
# ─── MCP Servers (SHARED INFRA — DO NOT CHANGE) ───
mcp_servers:
context7:
connect_timeout: 60
timeout: 300
url: http://localhost:8079/mcp
ra-h-os:
url: http://192.168.68.65:3100/mcp
timeout: 120
connect_timeout: 60
# ─── Compression (SHARED — can override model) ───
compression:
enabled: true
provider: harness
model: <auxiliary_model> # default: gemma-4-12b
threshold: 0.5
target_ratio: 0.25
protect_last_n: 30
hygiene_hard_message_limit: 400
# ─── Auxiliary Tasks (SHARED INFRA + MODEL) ───
auxiliary:
vision:
provider: harness
model: <auxiliary_model>
web_extract:
provider: harness
model: <auxiliary_model>
session_search:
provider: harness
model: <auxiliary_model>
max_concurrency: 3
# ─── Custom Provider (SHARED INFRA — LiteLLM) ───
custom_providers:
- name: <custom_provider_name>
model: <custom_provider_model>
base_url: http://litellm.sysloggh.net/litellm/v1
api_key: <liteLLM_master_key>
api_mode: chat_completions
```
### Optional Sections (agent-specific)
- **Platform configs** (Telegram, Discord, WhatsApp bot tokens)
- **Display/skin** options (compact mode, personality)
- **Plugin lists** (zulip-platform, etc.)
- **Terminal settings** (container image, timeouts)
- **Security/approvals** (command allowlists)
- **Kanban/worker** settings (if this profile is a Kanban worker)
- **Skills auto_load** list
- **Timezone** override
## Continuity
Configuration drift detection is **event-driven**:
- **On agent onboarding**: Always scaffold from this template
- **On infra change**: If Firecrawl/SearXNG/LiteLLM endpoints change, update template + all profiles
- **On new model**: When a new model is deployed on Litellm, any agent can change their `default` independently
- **Periodic**: Every 2 weeks — check if any profile's infra section has drifted from the template
- **On connection failure**: If web search/extract fails, check if that agent has missing `web.*` config
## Success Criteria
The configuration is CONSIDERED GOOD when ALL of these pass:
### Infra Connectivity
- `web.backend == "firecrawl"` — Firecrawl backend configured
- `web.search_backend == "searxng"` — SearXNG search configured
- `web.extract_backend == "firecrawl"` — Firecrawl extraction configured
- `web.firecrawl.base_url` points to `192.168.68.7:3002`
- `mcp_servers.ra-h-os.url` points to `192.168.68.65:3100/mcp`
- All endpoints respond to `curl` health checks
### Model Flexibility
- `model.default` is settable per agent (not hardcoded)
- `model.provider` is settable per agent
- `custom_providers[0].model` matches the agent's workload (code vs general)
### Completeness
- `auxiliary.vision` configured (even if provider=auto)
- `compression.enabled` set (true for most agents)
- Fallback provider configured (deepseek or another harness model)
- `_config_version` correctly set (currently `30`)
### No Drift
- No duplicate infra endpoints (one canonical Firecrawl URL)
- No stale endpoints (old IPs, dead services)
- All profiles consistent on shared infra
## Configuration Rules
### Rule 1: Shared Infra Is Locked
The following MUST be identical across ALL profiles:
- `web.backend`, `web.search_backend`, `web.extract_backend`
- `web.firecrawl.base_url`
- `mcp_servers.ra-h-os.url`
- `custom_providers[0].base_url`
### Rule 2: Model Choice Is Free
The following are OWNED by each agent and can differ:
- `model.default` — the primary model
- `model.provider` — where it runs
- `fallback_providers.model` — backup model
- `custom_providers[0].model` — what this agent uses LiteLLM for
### Rule 3: Workers Inherit, Not Duplicate
Worker profiles (syslog-code, syslog-devops, etc.) generally inherit from the main config. Only override what's DIFFERENT:
- Different default model → override `model.default`
- Different auxiliary model → override auxiliary sections
- No web search needed → still keep the config (tools won't enable without it)
### Rule 4: API Key Placement
- **Custom provider keys** (`custom_providers[0].api_key`): Must be hardcoded (the LiteLLM master key or a virtual key)
- **Model section keys** (`model.api_key`): Prefer empty. Workers inherit from custom_providers.
- **Environment keys** (`api_key_env`): For fallback providers that need separate auth (DeepSeek, OpenRouter)
- **Hardcoded keys in profile**: If a worker's `model.api_key` is set, it overrides custom_providers. Only use when the worker needs a DIFFERENT provider than Litellm.
### Rule 5: Verify After Every Config Change
After changing a profile's config:
1. `curl` the model endpoint to confirm auth works
2. `curl` the web stack endpoints (Firecrawl, SearXNG)
3. Check that `hermes gateway --restart` reloads cleanly
## Execution
1. **Check current config** — Read the target agent's config.yaml
2. **Compare against template** — Identify missing or divergent sections
3. **Apply shared infra** — Lock the web/MCP/compression sections to template values
4. **Apply model choice** — Set default/fallback/auxiliary models per agent's workload
5. **Preserve agent-specific** — Keep platform configs, plugins, terminal settings, skills
6. **Remove stale** — Drop any old infra endpoints that don't match the template
7. **Verify** — curl all shared endpoints, test the model
8. **Report** — What was changed, what was preserved, what's still custom
## Example Output
```
## Config Template Applied: syslog-code ✅
### Shared Infrastructure (Locked)
| Section | Before | After |
|---|---|---|
| web.backend | firecrawl | firecrawl ✅ |
| web.search_backend | NOT SET | searxng ✅ |
| web.firecrawl.base_url | NOT SET | http://192.168.68.7:3002/ ✅ |
| mcp_servers.ra-h-os | present | present ✅ |
### Agent Model Choices (Preserved)
| Setting | Value |
|---|---|
| model.default | qwen3.6-27B-code (code agent) |
| fallback | gemma-4-12b (harness) |
| auxiliary | gemma-4-12b (harness) |
| compression | gemma-4-12b (harness) |
### Endpoint Verification
| Endpoint | Status |
|---|---|
| Firecrawl :3002 | ✅ 200 OK |
| SearXNG :8888 | ✅ 200 OK |
| LiteLLM | ✅ 200 OK |
| RA-H OS MCP | ✅ Connected |
```