prose-contracts/hermes-config-template.prose.md at 0c976ddbf7394b6b911699356beef74939d88be1

SyslogSolution/prose-contracts

Fork 0

Files

T

jerome 94b3bf84b4 Add README + Quickstart sections for agent execution

2026-06-28 13:49:06 -04:00

12 KiB

Raw Blame History

kind, name, description

kind	name	description
template	hermes-config-template	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")

Quickstart — How to Run This Contract

For the Agent Running This Contract

Read this section first. It tells you exactly what to do.

When to run:

Setting up a new agent profile for the first time
An existing profile is missing web search, firecrawl, or MCP configs
User says: "apply the config template" or "fix my infra config"
User says: "configure <agent_name> with <model>"

How to run (via OpenProse CLI):

# Minimal — only agent name required
prose run hermes-config-template agent_name=syslog-code

# Full control
prose run hermes-config-template \
  agent_name=syslog-devops \
  default_model=claude-sonnet-4 \
  auxiliary_model=gemma-4-12b \
  fallback_model=deepseek-chat \
  fallback_provider=deepseek

How to Follow the Template (Manual)

If prose CLI is not available:

Fetch this contract: curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/hermes-config-template.prose.md
Open the target config.yaml — the profile you're updating
Compare each of the 5 required sections below against what exists in the profile
For each section:
- If it says SHARED INFRA — DO NOT CHANGE: Copy the value exactly as shown
- If it says USER CHOOSES: Use the agent's assigned model/provider
- If missing entirely: Add the full section
Verify every endpoint responds (see Verification section at the end)
Restart the gateway

Decision Tree

What kind of profile is this?
├── Main profile (~/.hermes/config.yaml)
│   └── Replace web.*, mcp_servers.*, compression.*, auxiliary.*, custom_providers.*
│   └── model.default + fallback: use current values (USER CHOOSES)
│
├── Worker profile (~/.hermes/profiles/<name>/config.yaml)
│   ├── Does it have web.search_backend?
│   │   ├── NO → Add the full web.* section (copy exactly)
│   │   └── YES → Verify it points to the right IP
│   ├── Does it have mcp_servers.ra-h-os?
│   │   ├── NO → Add mcp_servers.* section (copy exactly)
│   │   └── YES → Verify URL
│   └── model.default: USE the worker's assigned model (don't copy main)
│
└── Non-Syslog profile (personal/lifestyle agent)
    └── Skip — use default Hermes config or Tanko's config instead

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)

# ─── 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:

curl the model endpoint to confirm auth works
curl the web stack endpoints (Firecrawl, SearXNG)
Check that hermes gateway --restart reloads cleanly

Execution

Check current config — Read the target agent's config.yaml
Compare against template — Identify missing or divergent sections
Apply shared infra — Lock the web/MCP/compression sections to template values
Apply model choice — Set default/fallback/auxiliary models per agent's workload
Preserve agent-specific — Keep platform configs, plugins, terminal settings, skills
Remove stale — Drop any old infra endpoints that don't match the template
Verify — curl all shared endpoints, test the model
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 |

12 KiB Raw Blame History