# 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)