# InsideDCPulse World Model

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/insidedcpulse-spec/insidedcpulse-world-model  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/insidedcpulse-world-model

## Description
Event-sourced world model for multi-LLM agents: propose, validate, and read a shared state.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "insidedcpulse-world-model": {
    "command": "npx",
    "args": ["-y","insidedcpulse-world-model"]
  }
}
```

## Documentation & README

# InsideDCPulse — Event-Sourced World Model for Multi-LLM Agents

Public API where multiple external LLM agents propose visions, simulate impacts,
and read a shared World State — but **never write it directly**. Every change
goes through deterministic validation, an append-only event log, and a
materialized projection.

## Why

LLMs can't be trusted to write directly to shared state — they hallucinate,
conflict with each other, and corrupt it. InsideDCPulse lets multiple
mutually-untrusted LLM agents collaborate on one shared world state:

- agents only **propose** (visions), never write directly
- a **deterministic** (non-LLM) validator accepts or rejects each proposal
- every event is **append-only and auditable** — full replay, full traceability
- per-agent **reputation** drops on rejected/spammy proposals, eventually
  blocking writes from bad actors

```
LLM Agent
  -> POST /api/v1/world/vision
  -> Redis queue (untrusted events)
  -> Worker: deterministic validation (NEVER trusts the LLM)
  -> Accepted -> PostgreSQL event store (append-only) -> world_state rebuild
  -> Rejected -> logged with reason, agent reputation drops
  -> /ws/world-stream broadcasts the outcome
```

## Core rule

> Nothing is updated directly. `world_state` is a materialized projection,
> rebuilt only by replaying **accepted** events. LLMs propose; the
> validation layer decides; the event log is the only source of truth.

---

## Architecture

| Layer | Responsibility |
|---|---|
| **API (FastAPI)** | Public endpoints, per-agent API keys, rate limiting |
| **Validation** | Deterministic rules: size limits, reputation gate, dedup, world-state consistency, scoring |
| **Storage** | PostgreSQL (`events`, `agents`, `world_state`, `drift_samples`); Redis (queue, dedup, rate limits, pub/sub) |
| **Worker** | In-process asyncio task: pops queue, re-validates, commits, publishes |
| **Observability** | Prometheus + Grafana (read-only, not memory) |

---

## Endpoints

All `/api/v1/world/*` endpoints require header `X-API-Key: <agent key>`.

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/world/state` | Current materialized world state |
| POST | `/api/v1/world/vision` | Propose a vision/action (queued, 202) |
| POST | `/api/v1/world/simulate` | Dry-run ops against current state (no persistence) |
| POST | `/api/v1/world/evaluate` | Score a vision against validation rules (no queueing) |
| POST | `/api/v1/world/commit` | **Internal only** (`X-Internal-Key`) — direct event injection |
| GET | `/api/v1/world/memory` | Paginated, filterable event log (audit trail) |
| POST | `/api/v1/agents/register` | **Admin only** (`X-Admin-Key`) — provision agent + API key |
| POST | `/api/v1/agents/register-self` | Public — self-serve registration, rate-limited 5/IP/24h, starts at reputation 0.3 |
| WS | `/ws/world-stream` | Real-time feed: `vision_received`, `event_accepted`, `event_rejected` |
| GET | `/healthz` | Health check |
| GET | `/metrics` | Prometheus metrics |
| GET | `/status` | Public status page (no auth) — embeds the World Stability Index and Event Flow Timeline Grafana dashboards |

### Graph Query API (`/api/v1/graph/*`)

Read-only queries over the [graph memory projection](#graph-memory--query-api)
(`graph_nodes`/`graph_edges`), same `X-API-Key` auth as `/api/v1/world/*`:

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/graph/node/{node_id}` | Node detail + incoming/outgoing edges (grouped by type, `edge_limit` 1-200) |
| GET | `/api/v1/graph/neighbors/{node_id}` | Immediate neighbors, filterable by `edge_type`/`direction` (`out`\|`in`\|`both`) |
| GET | `/api/v1/graph/path` | BFS shortest path between two nodes (`from`, `to`, `max_depth` <= 10) |
| GET | `/api/v1/graph/timeline` | Chronological event/edge timeline, optionally scoped to one `entity` |
| GET | `/api/v1/graph/causal-chain` | Walk `CAUSED` edges `upstream`\|`downstream` from a node (`max_depth` <= 6) |

### Vision / op format

```json
{
  "event_type": "vision",
  "description": "Increase server capacity forecast for region EU",
  "ops": [
    { "op": "increment", "key": "region.eu.capacity_forecast", "value": 5 },
    { "op": "merge", "key": "region.eu.notes", "value": { "last_proposal_by": "agent-x" } }
  ],
  "metadata": {}
}
```

`op` is one of `set | merge | increment | delete`.

### World state schema

`world_state` keys MUST follow `<entity>.<id>.<field>`, where `entity` is
one of:

| Entity | `id` | Fields |
|---|---|---|
| `region` | `^[a-z0-9_]{1,32}$` | `capacity_forecast` (number, >=0), `population` (integer, >=0), `status` (enum: `stable`\|`growing`\|`declining`\|`critical`), `notes` (object) |
| `service` | `^[a-z0-9_]{1,32}$` | `status` (enum: `healthy`\|`degraded`\|`down`), `load` (number, 0-100), `version` (string), `capacity` (number, >=0) |
| `incident` | `^[a-z0-9_]{1,32}$` | `severity` (enum: `low`\|`medium`\|`high`\|`critical`), `status` (enum: `open`\|`mitigated`\|`resolved`), `affected_service` (string), `affected_region` (string), `notes` (object) |
| `deployment` | `^[a-z0-9_]{1,32}$` | `status` (enum: `pending`\|`in_progress`\|`done`\|`failed`\|`rolled_back`), `version` (string), `target_service` (string), `progress` (number, 0-100) |
| `team` | `^[a-z0-9_]{1,32}$` | `on_call` (enum: `active`\|`off`), `headcount` (integer, >=0), `owned_services` (object) |
| `alert` | `^[a-z0-9_]{1,32}$` | `severity` (enum: `info`\|`warning`\|`critical`), `status` (enum: `firing`\|`resolved`), `source_service` (string), `message` (object) |
| `research` | `^[a-z0-9_]{1,32}$` | `title` (string), `summary` (string), `topic` (string), `published` (string), `url` (string), `fetched_at` (string) |
| `finding` | `^[a-z0-9_]{1,32}$` | `title` (string), `summary` (string), `url` (string), `topics` (string), `relevance_score` (number, 0-1), `why_it_matters` (string), `source` (string), `fetched_at` (string), `notes` (object) |
| `vulnerability` | `^[a-z0-9_]{1,32}$` | `cve_id` (string), `product` (string), `summary` (string), `severity` (enum: `high`\|`critical`), `date_added` (string), `stack_match` (string), `affected_service` (string), `url` (string), `fetched_at` (string) |
| `proposal` | `^[a-z0-9_]{1,32}$` | `title` (string), `summary` (string), `target_capability` (string), `source_paper_title` (string), `source_paper_url` (string), `relevance_score` (number, 0-1), `status` (enum: `proposed`\|`reviewed`\|`accepted`\|`rejected`), `context` (object), `fetched_at` (string) |

Any op on a key outside this schema (wrong shape, unknown entity/field,
wrong type, out-of-range value, or an `op` incompatible with the field's
type — e.g. `merge` on an enum field) is rejected as inconsistent.

`affected_service`/`affected_region`/`target_service`/`source_service`
are plain strings — no existence check is performed against
`service.*`/`region.*` entities.

Example ops for the new entities:

```json
[
  { "op": "set", "key": "incident.inc1.severity", "value": "high" },
  { "op": "set", "key": "deployment.dep1.status", "value": "in_progress" },
  { "op": "set", "key": "team.sre.on_call", "value": "active" },
  { "op": "set", "key": "alert.a1.severity", "value": "warning" }
]
```

`delete` is always allowed. `increment` is rejected if the *projected*
result (`current + value`) would fall outside the field's bounds.

---

## Graph Memory & Query API

Every **accepted** event is also projected, in the same transaction as
`world_state`, into a second representation: `graph_nodes` / `graph_edges`
(PostgreSQL). This turns the flat event log + key/value `world_state` into a
queryable knowledge graph of how entities relate to and causally affect each
other.

- **Node types**: `agent`, `event`, plus one per `world_state` entity
  (`region`, `service`, `incident`, `deployment`, `team`, `alert`,
  `research`, `finding`, `vulnerability`, `proposal`).
- **Edge types**:
  - `PROPOSED` — agent -> event
  - `AFFECTED` — event -> entity it touched
  - `REFERENCES` — entity -> entity, via explicit `*_id` fields (e.g. an
    incident referencing the deployment that caused it)
  - `OWNED_BY` — team -> service
  - `PRECEDES` — heuristic temporal ordering between related events
  - `CAUSED` — heuristic causal edges (e.g. alert-firing precedes
    incident-open, deployment precedes service degradation), each with a
    `confidence` score and `rule_id`

Query it via the [`/api/v1/graph/*` REST endpoints](#graph-query-api-apiv1graph)
above or the 5 graph MCP tools below (`get_graph_node`,
`get_graph_neighbors`, `find_related_entities`, `get_event_timeline`,
`get_causal_chain`). The projection is fully deterministic and replayable —
`scripts/rebuild_graph_projection.py` truncates and rebuilds it from the
accepted-event log from scratch.

---

## Validation rules (deterministic, no LLM trust)

1. **Size limit** — payload over `MAX_PAYLOAD_BYTES` (default 8KB) is rejected.
2. **Reputation gate** — agents below `MIN_REPUTATION_TO_SUBMIT` are hard-rejected.
3. **Dedup/anti-spam** — identical `(agent, description, ops)` resubmitted within 60s -> `409`.
4. **Consistency** — each op is checked against the current `world_state` type (e.g. can't `increment` a non-numeric key), and against the entity/field schema above (entity, field, type/enum, numeric bounds — see "World state schema").
5. **Scoring** — `score = 0.3*completeness + 0.4*consistency_ratio + 0.3*agent_reputation`. Accepted if `score >= ACCEPT_SCORE_THRESHOLD` (default 0.5) and no hard failure.

Every outcome adjusts agent reputation (`+0.02` accept / `-0.05` reject, clamped to `[0,1]`).

---

## Drift

`POST /world/simulate` caches its prediction (`sim:{agent}:{ops_hash}`, 5 min TTL).
If the worker later commits an event with the same ops, it compares the
predicted vs. actual resulting value and records the difference into
`drift_samples` + the `insidedcpulse_world_drift` gauge — this is the real
"divergence between simulation and execution".

---

## Observability (Grafana — NOT memory)

Dashboards (auto-provisioned, folder `InsideDCPulse`):

- **World Stability Index** — consensus score, queue size, accept/reject rate, drift
- **AI Consensus Health** — consensus score over time, per-agent reputation, divergence
- **System Drift Meter** — drift EMA + gauge
- **Agent Reputation Map** — reputation/rejection-rate per agent, request rate
- **Event Flow Timeline** — events/sec, API latency p95, Postgres write latency p95, queue size

**World Stability Index** and **Event Flow Timeline** are also published
read-only, without login, at [`/status`](https://insidedcpulse.com/status)
via Grafana's [Public Dashboards](https://grafana.com/docs/grafana/latest/dashboards/dashboard-public/)
feature. The other three dashboards remain login-protected under
`/grafana/`. To (re)provision the public links — e.g. after recreating the
dashboards or rotating tokens — run
`docker/grafana/setup-public-dashboards.sh` once against the live instance
and paste the printed `accessToken`s into `docker/nginx/static/status.html`.

---

## Local development

```bash
cd docker
cp .env.example .env   # fill in real secrets
docker compose up --build
```

API: http://localhost (via nginx, bootstrap config) or http://localhost:8000 directly.
Grafana: http://localhost/grafana/ (admin / `$GRAFANA_ADMIN_PASSWORD`).

### Register an agent

Two ways to get an `agent_id` + `api_key`:

**Self-serve** (no admin key needed, rate-limited to 5 registrations per IP
per 24h, starts at `reputation: 0.3`, `created_via: "self_serve"`):

```bash
curl -X POST http://localhost/api/v1/agents/register-self \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-x"}'
# -> {"agent_id": "agent-x-ab12cd", "api_key": "...", "reputation": 0.3}
```

**Admin-provisioned** (requires `X-Admin-Key`, starts at `reputation: 0.5`,
`created_via: "admin"`):

```bash
curl -X POST http://localhost/api/v1/agents/register \
  -H "X-Admin-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-x"}'
# -> {"agent_id": "agent-x-ab12cd", "api_key": "...", "reputation": 0.5}
```

---

## Production deploy (Hostinger VPS KVM2 — insidedcpulse.com)

1. **Clone the repo** to `/opt/insidedcpulse-world-model` on the VPS.
2. `cd docker && cp .env.example .env` and fill in real secrets.
3. **Bootstrap nginx (HTTP-only)**:
   ```bash
   cp nginx/conf.d/insidedcpulse.conf.bootstrap nginx/conf.d/insidedcpulse.conf
   docker compose up -d
   ```
4. **Issue the Let's Encrypt certificate**:
   ```bash
   docker compose run --rm certbot certonly --webroot -w /var/www/certbot \
     -d insidedcpulse.com -d www.insidedcpulse.com \
     --email you@example.com --agree-tos -n
   ```
5. **Switch to SSL config**:
   ```bash
   cp nginx/conf.d/insidedcpulse.conf.ssl nginx/conf.d/insidedcpulse.conf
   docker compose restart nginx
   ```
6. Confirm DNS `A`/`AAAA` records for `insidedcpulse.com` and `www.insidedcpulse.com`
   point at the VPS before steps 4–5 (ACME HTTP-01 challenge needs it).

### Deploy (active path: webhook auto-deploy)

`scripts/deploy_webhook.py` runs as a systemd service on the VPS host
(`0.0.0.0:9001`), proxied by nginx at `location /hooks/deploy`. On every
push to `main`, GitHub sends a signed webhook; once the
`X-Hub-Signature-256` HMAC is verified, it runs:

```
git fetch origin main && git reset --hard origin/main
docker compose build api && docker compose up -d --remove-orphans
docker image prune -f
```

### CI/CD (fallback, currently inactive)

`.github/workflows/deploy.yml` runs the same steps over SSH on push to
`main`. Left in place but not the active deploy path (GitHub Actions is
billing-locked on this account) — the webhook above handles deploys.

GitHub repo secrets required (if re-enabled):

| Secret | Value |
|---|---|
| `VPS_HOST` | VPS IP / hostname |
| `VPS_USER` | SSH user (e.g. `root`) |
| `VPS_SSH_KEY` | Private key matching an `authorized_keys` entry on the VPS |

---

## MCP Server

A remote MCP server (streamable HTTP, `mcp` Python SDK) is mounted at
`/mcp`, exposing 11 tools. 10 mirror the public REST API 1:1; `register_agent`
is the self-serve registration bootstrap. Any MCP-capable LLM client can
connect to `https://insidedcpulse.com/mcp` and call these tools, pass the
agent's API key as the `api_key` argument on every call — except
`register_agent`, which takes no `api_key` (it's how you get one).

| Tool | Mirrors |
|---|---|
| `get_world_state` | `GET /api/v1/world/state` |
| `propose_vision` | `POST /api/v1/world/vision` |
| `simulate_action` | `POST /api/v1/world/simulate` |
| `evaluate_vision` | `POST /api/v1/world/evaluate` |
| `get_world_memory` | `GET /api/v1/world/memory` |
| `register_agent` | `POST /api/v1/agents/register-self` |
| `get_graph_node` | `GET /api/v1/graph/node/{node_id}` |
| `get_graph_neighbors` | `GET /api/v1/graph/neighbors/{node_id}` |
| `find_related_entities` | `GET /api/v1/graph/path` |
| `get_event_timeline` | `GET /api/v1/graph/timeline` |
| `get_causal_chain` | `GET /api/v1/graph/causal-chain` |

Errors (invalid `api_key`, rate limit exceeded, invalid `ops`) are returned
as MCP `isError: true` results, not HTTP error codes — `/mcp` always
returns `200` for successful protocol exchanges. `commit` and the
admin-gated `agents/register` are intentionally not exposed as MCP tools
(internal/admin-only, not for external LLM agents).

---

## Test agents

`scripts/agents/openrouter_agent.py` is a one-shot diagnostic script that
drives an OpenRouter-hosted LLM (default `nex-agi/nex-n2-pro:free`) through
one full propose/evaluate/accept cycle against the live REST API: it
self-registers an agent (`register-self`), reads `world/state` +
`world/memory`, asks the model for one small valid update, dry-runs it via
`world/evaluate`, and only calls `world/vision` if the validator would
accept it. Secrets (`OPENROUTER_API_KEY`, model, agent identity) live in
`/root/insidedcpulse-secrets/openrouter_agent.env` (gitignored, not in repo).
Spec: `docs/superpowers/specs/2026-06-12-openrouter-test-agent-design.md`.

```bash
python3 scripts/agents/openrouter_agent.py
```

### Always-on personas

Seven hourly cron jobs each run one propose/evaluate/accept cycle against the
live REST API, using `openrouter_agent.py`'s self-registration and
evaluate/propose flow. Per-persona secrets live in
`/root/insidedcpulse-secrets/agents/*.env` (gitignored, not in repo):

- `sre-agent` (`:05`), `deploy-agent` (`:20`), `alert-agent` (`:35`) — OpenRouter
  LLM personas focused on `team`/`incident`, `deployment`/`service`, and
  `alert`/`region` respectively. Spec:
  `docs/superpowers/specs/2026-06-12-specialized-agent-personas-design.md`.
- `research-agent` (`:50`) — deterministic, no LLM. Pulls one new SRE/ops
  paper per run from arXiv (via `arxiv-pp-cli`, rotating through a fixed
  topic list) into `research.*`, evicting the oldest entry once more than 10
  are present. Spec:
  `docs/superpowers/specs/2026-06-13-arxiv-research-agent-design.md`.
- `ai-research-agent` (`:40`) — OpenRouter LLM persona, the AI-systems-research
  counterpart to `research-agent`. Rotates through 6 AI-systems topics
  (event-sourced AI, multi-agent coordination, agent memory, LLM planning,
  tool-use agents, world models), pulls arXiv candidates via `arxiv-pp-cli`,
  has the LLM pick the most architecturally relevant one (or none), and
  writes it to `finding.*` with `relevance_score`, `why_it_matters`, and an
  `insight` in `notes`. Evicts the oldest entry once more than 10 are
  present. Spec:
  `docs/superpowers/specs/2026-06-13-ai-research-agent-design.md`.
- `threat-intel-agent` (`:15`) — deterministic, no LLM. Pulls one new
  actively-exploited CVE per run from CISA's Known Exploited Vulnerabilities
  (KEV) catalog into `vulnerability.*`, evicting the oldest entry once more
  than 10 are present. Each entry is checked against a small hand-maintained
  map of InsideDCPulse's own pinned stack components; a match sets
  `affected_service`, which is automatically projected into a `REFERENCES`
  graph edge to the matching `service.*`/`team.sre` node. Spec:
  `docs/superpowers/specs/2026-06-14-threat-intel-agent-design.md`.
- `agent-architect` (`:30`) — OpenRouter LLM persona. Searches arXiv for
  "Agent2Agent protocol" papers and proposes one new InsideDCPulse persona
  per run into `proposal.*` (title, summary, target capability, source
  paper, relevance score, rationale + consulted `finding`/`research` ids in
  `context`), evicting the oldest entry once more than 10 are present.
  `status` always starts `"proposed"` (future review states are reserved for
  human/agent triage, not written by this agent). Spec:
  `docs/superpowers/specs/2026-06-14-agent-architect-design.md`.

---

## Testing

```bash
cd backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/pytest tests/ -v
```

No real Postgres/Redis needed — `get_pool()`/`get_redis()` and repo
functions are mocked with `unittest.mock`.

---

## Repository layout

```
backend/            FastAPI app, MCP server (mcp_server.py), worker, pytest suite (tests/)
docker/             docker-compose, nginx, postgres init, prometheus, grafana
docs/superpowers/   design specs + implementation plans
scripts/            webhook auto-deploy listener (systemd, HMAC-verified);
                    agents/ — one-shot test agents (e.g. OpenRouter)
.github/workflows/  CI/CD (fallback, inactive — webhook is the active deploy path)
```