Abiba
dfacab12f5
- All 17 contracts now documented (was 7). Grouped by domain (Infra, GPU, LiteLLM, Zulip, Memory, Ops, Agent-config) and kind (responsibility/function/pattern). - Patterns split: 'Instantiable Templates' vs 'Reference Documents' for clarity. - Contract Structure section now distinguishes responsibility/function/pattern section sets (was incorrectly claiming all contracts share one structure). - Scripts table now covers all 3 scripts/ files (was missing daily-infra-report and zulip-monitor). - Functions: litellm-health, infrastructure-monitoring, hello-world. Templates: hermes-config-template. Reference: infrastructure-control, pi-approval-architecture, zulip-adapter-lessons.
140 lines
6.0 KiB
Markdown
140 lines
6.0 KiB
Markdown
# Prose Contracts — Syslog Solution LLC
|
|
|
|
Operating contracts for Syslog agents. Each `.prose.md` file defines a **function** (callable helper), **responsibility** (recurring duty with state), or **pattern** (instantiable knowledge/template) that agents can execute via OpenProse or follow manually.
|
|
|
|
## How Agents Run These Contracts
|
|
|
|
### Option A: Via OpenProse CLI (preferred)
|
|
|
|
```bash
|
|
prose run <contract-name> [param1=value1 param2=value2 ...]
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Run a memory audit with default parameters
|
|
prose run memory-audit-maintenance
|
|
|
|
# Run a memory audit with custom threshold
|
|
prose run memory-audit-maintenance memory_threshold=90 verify_configs=true
|
|
|
|
# Configure a new agent with the template
|
|
prose run hermes-config-template agent_name=syslog-devops default_model=claude-sonnet-4
|
|
|
|
# Configure an agent with a different auxiliary model
|
|
prose run hermes-config-template agent_name=syslog-code default_model=qwen3.6-27B-code auxiliary_model=gemma-4-12b
|
|
```
|
|
|
|
### Option B: Manual Execution
|
|
|
|
If `prose` CLI isn't available, any agent can:
|
|
1. Fetch the raw contract: `curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/<filename>`
|
|
2. Read the **Execution** section
|
|
3. Follow the steps
|
|
|
|
**Example for fetching:**
|
|
```bash
|
|
curl -sL https://git.sysloggh.net/SyslogSolution/prose-contracts/raw/branch/master/memory-audit-maintenance.prose.md
|
|
```
|
|
|
|
## Available Contracts
|
|
|
|
### Responsibilities (Recurring Duties — `kind: responsibility`)
|
|
|
|
Run on trigger or schedule. Maintain persistent world-model state across runs.
|
|
|
|
| Contract | Domain | Description |
|
|
|---|---|---|
|
|
| `memory-audit-maintenance` | Memory | Audits & reorganizes an agent's native memory (MEMORY.md, USER.md). Categorizes entries, moves rules to skills, verifies configs. |
|
|
| `build-zulip-plugin` | Zulip | Generates and iteratively improves a Hermes Zulip platform plugin. Each run produces a new version. |
|
|
| `zulip-health` | Zulip | Checks Zulip connectivity, message flow, and bot responsiveness. |
|
|
| `zulip-mention-reliability` | Zulip | Diagnoses and fixes @mention detection issues in Zulip. |
|
|
| `zulip-approval-fix` | Zulip | Fixes broken /approve and /deny slash commands for Hermes agents. |
|
|
| `litellm-self-heal` | LiteLLM | Standing responsibility — monitors LiteLLM health and auto-remediates: key rotation, container restart, config reload, roster fixes. |
|
|
| `gpu-fleet` | GPU | Manages the GPU inference fleet: model deployment, registration, health checks, LiteLLM sync. |
|
|
| `gpu-monitor` | GPU | Comprehensive GPU fleet monitor — polls sidecars, router, LiteLLM every 15s, renders SSE dashboard. |
|
|
| `proxmox-monitor` | Infra | Proxmox cluster + Docker monitoring via the existing Grafana/Prometheus stack on CT 116. |
|
|
| `pm2-self-heal` | Ops | Monitors PM2 processes (abiba-zulip, abiba-telegram) and auto-restarts any that are stopped or errored. |
|
|
|
|
### Instantiable Templates (`kind: pattern` — run with `prose run`)
|
|
|
|
Generate configs or perform a transformation on demand. No persistent state.
|
|
|
|
| Contract | Description | Key Parameters |
|
|
|---|---|---|
|
|
| `hermes-config-template` | Standard Hermes config for any Syslog agent. Enforces shared infra (Firecrawl, SearXNG, RA-H OS MCP, LiteLLM). | `agent_name` (required), `default_model`, `auxiliary_model` |
|
|
|
|
### Reference Documents (`kind: pattern` — read for context, not run)
|
|
|
|
Encode topology, architectural decisions, and lessons. You read them before planning; you don't `prose run` them.
|
|
|
|
| Contract | Description |
|
|
|---|---|
|
|
| `infrastructure-control` | Full topology and control pattern: 5-node Proxmox cluster, 3 Docker ecosystems, NFS storage, network verification, IP-first configuration doctrine. |
|
|
| `pi-approval-architecture` | pi's approval model vs Hermes, available commands, architectural constraints. |
|
|
| `zulip-adapter-lessons` | Failure modes, fixes, and patterns from building the pi Zulip extension and Hermes Zulip plugin. |
|
|
|
|
### Functions (`kind: function` — callable helpers, no state)
|
|
|
|
Called on-demand as single-render tools.
|
|
|
|
| Contract | Description |
|
|
|---|---|
|
|
| `litellm-health` | Verifies LiteLLM inference stack health: containers, router, GPU fleet, model inference, agent keys. |
|
|
| `infrastructure-monitoring` | Deploys Prometheus + GPU exporters + Grafana to monitor the inference fleet from CT 116. |
|
|
| `hello-world` | Minimal test contract — verifies the OpenProse execution pipeline works. |
|
|
|
|
### Scripts (`scripts/`)
|
|
|
|
Companion shell scripts that contracts delegate to.
|
|
|
|
| File | Description |
|
|
|---|---|
|
|
| `daily-infra-report.py` | Generates the daily infrastructure dashboard (HTML email to jerome@sysloggh.com). |
|
|
| `zulip-monitor.sh` | Monitors Zulip bot health and message flow. |
|
|
| `pm2-self-heal.sh` | Shell companion to the pm2-self-heal contract — restarts crashed PM2 processes. |
|
|
|
|
## Contract Structure
|
|
|
|
Kinds determine the section set.
|
|
|
|
**`kind: responsibility`** (recurring duty with persistent state):
|
|
```
|
|
## Maintains — World-model state this contract tracks
|
|
## Parameters — Tunable inputs (with defaults)
|
|
## Requires — External dependencies and preconditions
|
|
## Continuity — When to run (triggers & cadence)
|
|
## Remembers — What to learn between runs
|
|
## Invariants — Inviolable rules for execution
|
|
## Execution — Step-by-step instructions
|
|
## Example Output — What a good run looks like
|
|
```
|
|
|
|
**`kind: function`** (stateless callable helper):
|
|
```
|
|
## Parameters — Tunable inputs (with defaults)
|
|
## Returns — Output schema
|
|
## Requires — External dependencies
|
|
## Execution — Step-by-step instructions
|
|
```
|
|
|
|
**`kind: pattern`** (instantiable knowledge):
|
|
```
|
|
Variable — templates use Parameters + Execution; reference docs are prose-driven.
|
|
```
|
|
|
|
**`kind: gateway`** / **`kind: test`** — not currently used in this repo.
|
|
|
|
## Adding New Contracts
|
|
|
|
1. Create a `.prose.md` file following the structure above
|
|
2. Push to this repo
|
|
3. The contract is immediately available for any agent to `prose run`
|
|
|
|
## Repository
|
|
|
|
- **URL:** https://git.sysloggh.net/SyslogSolution/prose-contracts
|
|
- **Branch:** master
|
|
- **Auth:** mumuni-bot (write access via PAT)
|