Use case: grid reliability

A control-room answer is only worth what the telemetry behind it is worth. When an operator asks which substations have active outages right now?they need the certified incident record and the live breaker status — not last shift's notes, and never a confident guess about whether a line is de-energized. This guide builds that reliability assistant end to end for a regional grid operator, touching seven module slices: Intake to bring the asset and outage records in, Atlas to type them, Warrant to certify the source of truth, Conduit to wire in the live grid-operations database, Lens to answer with citations under a policy that abstains without telemetry, Lineage to trace any answer back to its source, and Crucible + Ports to keep it accurate and hand it to an agent. Seed it with yarn demo:seed energy and it opens as the Helios Grid Utilities (Energy) workspace, so you can follow every call below against real content.

Prerequisites

• A workspace key with kb:write, kb:read, data:read, data:run, agents:run, and runs:read, exported as $ELI_KEY. See Getting started.
• Owner/admin on the workspace, to create connectors and certify concepts.
• The seeded helios-grid-ops Postgres connector reachable, so the live grid queries return rows instead of a structured failure.
• An enabled chat model, so /query can generate — otherwise 409 no-model-configured.

1 · Intake — bring the grid's records in

Helios's operational knowledge is a folder of markdown: a substation record per bus, an outage finding per event, crew rosters, and the NERC/FERC compliance program. The seed loads all of it, but the shape is a plain document post — headings define the chunks retrieval uses, while graph enrichment follows the storage commit independently. Here is the Ridgeline substation record going in:

curl -s -X POST https://your-host/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "substations/ridgeline-substation.md",
    "title": "Substation — Ridgeline",
    "content": "# [[Ridgeline Substation]]\n\nA 230kV bulk transmission substation, western terminus of the [[Ridgeline-Cascade 230kV Line]]. Maintained by [[Substation Crew Bravo]], monitored by the [[SCADA System]]. Impacted by the [[Ridgeline Storm Outage]]; breaker B3 is overdue for a [[NERC PRC-005]] inspection."
  }'

{ "docId": "01KY30RIDGELINE000000000AA", "path": "substations/ridgeline-substation.md", "contentHash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "title": "Substation — Ridgeline" }

Repeat across the pack — the four substations, the Ridgeline-Cascade 230kV Line, the outage findings, the crew logs, and the NERC CIPprogram doc — and the workspace holds Helios's asset base as searchable, citable text. After detached enrichment, referenced names (Ridgeline Substation, SCADA System, Line Crew Alpha) can resolve into the Atlas graph the next slice types and connects. The create response itself carries no graph-readiness status.

2 · Atlas — type the assets, wire the graph

Extraction gives you named nodes; the ontology gives them meaning. This workspace types six kinds of thing — Substation, TransmissionLine, OutageEvent, Crew, ControlSystem, and Regulation — joined by typed relations (connects, maintained_by, impacts, governed_by) so retrieval is structured, not just text. Pin a key asset with its type, then assert the edge that makes it a network:

curl -s -X POST https://your-host/api/v1/entities \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ridgeline Substation", "type": "Substation" }'

{ "id": "01KY30RIDGEENT000000000AA", "name": "Ridgeline Substation", "type": "Substation", "confidence": 1, "origin": "manual", "authority": "asserted" }

curl -s -X POST https://your-host/api/v1/relations \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "srcEntityId": "01KY30LINEENT0000000000AA",
    "dstEntityId": "01KY30RIDGEENT000000000AA",
    "type": "connects"
  }'

{ "id": "01KY30REL00000000000000AA", "srcEntityId": "01KY30LINEENT0000000000AA", "dstEntityId": "01KY30RIDGEENT000000000AA", "type": "connects", "confidence": 1, "origin": "manual" }

3 · Warrant — certify the source of truth

Extraction lands concepts at authority machine_extracted — a starting point, not a truth. Reliability messaging has to be vouched for. In Warrant, curate the concepts an operator will lean on and certify the ones an assistant may state plainly. The Outage Management System is the book of record for outage events, so pin its canonical definition as a reviewable change, then sign off:

curl -s -X POST https://your-host/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZOMSENTITY0000000000AA",
    "payload": { "description": "Book of record for outage events, crew dispatch, and estimated restoration times; its customers-affected counts are the basis for reliability reporting." },
    "note": "Pin OMS as the canonical outage book of record"
  }'

{ "id": "01KZCR00000000000000000AA", "entityId": "01KZOMSENTITY0000000000AA", "kind": "update", "status": "open" }

curl -s -X POST https://your-host/api/v1/entities/01KZOMSENTITY0000000000AA/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by Wendy Chao (NERC Compliance) and Nadia Fournier (VP Grid Ops)"}'

{ "authority": "certified", "lifecycleStatus": "published", "version": 3, "nextReviewAt": "2027-01-18T09:10:00.000Z" }

Do the same for the source document itself — verify the Ridgeline storm incident record so its provenance carries a governance tier:

curl -s -X POST https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"verified","note":"Reviewed against SCADA telemetry for the Ridgeline storm event"}'

{ "id": "01KY10AAAAAAAAAAAAAAAAAAAA", "verification": "verified", "verifiedAt": "2026-07-22T09:12:00.000Z", "nextVerifyAt": "2026-10-20T00:00:00.000Z" }

4 · Conduit — wire in the live grid-ops database

Documents describe the grid; they don't know what it is doing this second. Breaker status and customers-affected change by the minute, so bind a read-only view of the operations database as a data connector. The seed ships helios-grid-ops (Postgres, helios_grid_ops) with three governed named queries — active-outages, asset-health-by-substation, and peak-load-by-substation — each a parameter-validated, capped, provenance-logged component. List what you can run:

curl -s https://your-host/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"

{
  "queries": [
    {
      "slug": "active-outages",
      "title": "Active outages by impact",
      "description": "Currently active outage events joined to their substation, largest customer impact first. No parameters.",
      "connectorName": "helios-grid-ops",
      "params": []
    }
  ]
}

curl -s -X POST https://your-host/api/v1/data/queries/active-outages/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'

{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "helios-grid-ops",
  "queryTitle": "Active outages by impact",
  "columns": ["outage_id", "substation", "cause", "customers_affected", "started_at"],
  "rows": [
    { "outage_id": "OMS-4471", "substation": "Ridgeline Substation", "cause": "lightning-induced fault", "customers_affected": 18400, "started_at": "2026-07-21T18:22:00.000Z" },
    { "outage_id": "OMS-4488", "substation": "Cascade Junction Substation", "cause": "degraded cable splice", "customers_affected": 3200, "started_at": "2026-07-22T02:05:00.000Z" }
  ],
  "rowCount": 2,
  "truncated": false,
  "durationMs": 37,
  "executedAt": "2026-07-22T09:14:03.412Z"
}

5 · Lens — the operator asks, and gets a policy-gated answer

Now the payoff. An operator asks in plain language; Lens retrieves documents, detects the entities in the question, runs their bound live queries, and returns an answer grounded in both — inline [Sn] citations for documents and [Dn] for live rows — with a policy decision that says how much to trust it. Set includeData: true and ask the golden operations question verbatim:

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Which substations have active outages right now?","includeData":true}'

{
  "answer": "Ridgeline Substation has an active outage: transformer T2 tripped on the Ridgeline-Cascade 230kV Line from a lightning-induced fault, interrupting ~18,400 customers [S1][D1]. A second event is active at Cascade Junction Substation (~3,200 customers) from a degraded cable splice [D1]. Both are open in the Outage Management System.",
  "claims": [
    { "text": "Ridgeline Substation has an active outage from a lightning-induced fault on the Ridgeline-Cascade 230kV Line", "citations": ["S1", "D1"] },
    { "text": "About 18,400 customers are affected at Ridgeline", "citations": ["D1"] }
  ],
  "sources": [
    { "id": "S1", "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "docTitle": "Outage — Ridgeline Storm", "docPath": "outages/ridgeline-storm-outage.md", "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB" }
  ],
  "data": [
    { "id": "D1", "connectorName": "helios-grid-ops", "querySlug": "active-outages", "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC" }
  ],
  "entities": [ { "id": "01KZOMSENTITY0000000000AA", "name": "Outage Management System", "type": "ControlSystem", "authority": "certified" } ],
  "policy": { "decision": "answer", "confidence": 0.81, "stage": "post", "reasons": ["confidence_above_answer_floor"] },
  "groundedness": { "verified": 2, "total": 2 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" }
}

The policy block is the trust signal, and it is what makes this safe for a control room. Ask something speculative — "Will the grid hold up through the next heat wave?" — and the policy engine returns abstain_with_pointers at 0.11 (reason no_relevant_chunks): a reliability claim with no telemetry behind it earns pointers, not a fabricated forecast. Ask "Is Ridgeline transformer T2 safe to load to 110% of nameplate?" and it returns answer_with_caveat at 0.41 (confidence_in_caveat_band) — it will not assert an asset is safe without backing. That is exactly the behavior grid operations demands.

6 · Lineage — trace the answer back to its source

A reliability engineer reviewing the assistant asks the fair question: where is this coming from, and can I trust it? The answer cited S1 → docId 01KY10… and D1 → dataCall 01KY10…. Pull that document's lineage and read the whole trail in one call — origin, governance, and the downstream answers it is grounding right now:

curl -s https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/lineage \
  -H "Authorization: Bearer $ELI_KEY" | jq '{origin: .origin, verification: .governance.verification, citedBy: .downstream.citedByAnswers}'

{
  "origin": {
    "kind": "document",
    "sourceType": "markdown",
    "path": "outages/ridgeline-storm-outage.md",
    "ingestedAt": "2026-07-22T08:40:12.500Z"
  },
  "verification": "verified",
  "citedBy": 9
}

There it is, closed loop: the document half of the answer traces to the seeded Ridgeline storm incident record, it is verified, and it is currently grounding 9 answers — so an edit to it has a known blast radius. And the live half is auditable too: the [D1] row came from the active-outages run, which wrote an append-only data_calls provenance row recording the exact SQL, params, and status behind dataCall 01KY10…. The engineer didn't have to trust the model; they read the pedigree of both layers. The full trail also lists the derived concepts and the dependent cache entries that would invalidate if the incident record changed.

7 · Crucible & Ports — lock the accuracy in, then hand it off

Grid conditions and standards change constantly, and a wrong answer during a storm is expensive. Capture the questions operators actually ask as a golden set so Crucible can prove the assistant still answers them after every content change. Anchor a golden item — say "Why did the Cascade feeder fault escalate from momentary to sustained?" — to the incident chunk that should ground it, and seed a provenance qrel:

curl -s -X POST https://your-host/api/v1/qrels \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "01KZGOLDCASCADE00000000AA",
    "chunkId": "01KY20BBBBBBBBBBBBBBBBBBBB",
    "docId": "01KY20AAAAAAAAAAAAAAAAAAAA",
    "grade": 3,
    "source": "provenance"
  }'

{ "id": "01KZQREL0000000000000000A", "queryId": "01KZGOLDCASCADE00000000AA", "grade": 3, "source": "provenance" }

Run the "Grid reliability Q&A baseline" set from the evals workspace, then read the metrics for the run. Retrieval and abstention numbers are deterministic; RAGAS numbers carry the judge model that produced them:

curl -s https://your-host/api/v1/evals/runs/01KZRUNGRID0000000000000A/metrics \
  -H "Authorization: Bearer $ELI_KEY"

{
  "runId": "01KZRUNGRID0000000000000A",
  "n": 36,
  "retrieval": { "recallAtK": 0.78, "ndcgAt10": 0.73, "mrr": 0.81, "hitAtK": 0.94 },
  "ragas": { "faithfulness": 0.93, "responseRelevancy": 0.85, "contextPrecision": 0.69 },
  "abstention": { "truthfulness": 0.66, "abstainRate": 0.14, "aurc": 0.068 }
}

Finally, hand the whole pipeline to an operator-facing worker. The seed ships the agent grid-reliability-analyst, whose system prompt makes the abstention rule a standing instruction — never assert that an asset is safe, restored, or de-energized without telemetry backing — and whose memories carry the N-1 criterion and the storm-restoration priority. Start a run with POST /api/v1/agents/grid-reliability-analyst/runs and poll GET /api/v1/runs/{id}; the seeded run and its report are already in the workspace to inspect. When a metric drops after a content or standards update, the golden set names exactly which question regressed — and promoting that miss back into the set makes it a permanent test. That is the dashed loop in the diagram: Crucible's regressions and Lens's abstentions steer the next round of Warrant curation. Compare two configs with a two-gate significance test in Measure & compare.

The leverage

Seven slices, one knowledge base plus one read-only grid-ops database, one audit trail. The operator gets a fast answer grounded in both the certified record and live telemetry; the engineer can trace any answer to its document and its data call and see the blast radius; the policy abstains rather than guess at whether a line is safe; and the whole thing is measured, so reliability accuracy is a number you watch rather than a hope. Swap the electric grid for water, gas, or telecom and the shape is identical — the platform doesn't care what the assets are, only that every answer is grounded, governed, traceable, and measured.