AirfieldpathOrlando Sanford International

5.4 · The Interchange · Documents

The AI hook

Where a model judgement enters the Interchange and how a person confirms it.

No picture for this component.

Document · The Interchange · Documents

The AI hook

Where a model judgement enters the Interchange and how a person confirms it.

  1. Sources
  2. Interchange
  3. Twin
  4. Screens
  5. Plan
Kind
Document
Status
not linked
Airport layer
not linked
Airport area
not linked
System
not linked
Sensor type
not linked

Open the detail

Level 2 of 3 This component, complete on its own. Its files, sources and tests are the detail below. Open the detail

The AI hook

When an event from Simplify i3 lands in Jira, the hub raises an AI request for StellarView. StellarView picks it up, runs it through Claude Code, and posts the result back. The result is a suggestion, and a person decides.

State: the hook is built here. The call is an interface StellarView implements; it is not built.

What the hub provides

  • Requests. GET /hub/ai-requests?state=open returns open requests, each matching contracts/ai_request.schema.json:
  • request_id
  • tasks: any of summarise, suggest_asset, suggest_work_order
  • prompts: the prompt file for each task, under prompts/ai/
  • trigger: the Interchange event, the Jira key and the i3 record
  • context: the event, the Jira issue as the hub knows it, the candidate assets with their codes and locations, and the open work orders
  • reply_to
  • Results. POST /hub/ai-results/<request_id> takes a result matching contracts/ai_result.schema.json. The request is then marked answered, and the result is kept as "suggestion: waits for a person".
  • Rules. Which arrivals raise a request is set in mappings/rules.json: the ai.request action, today on cmms.work_order.completed and cmms.inspection.failed.

What StellarView implements

One function, called for each open request:

processHubAiRequest(request) -> result
  1. Run each task through Claude Code, never an API key. For each task, run Claude Code with the task's prompt file, and the request as JSON after it, in a block headed request. Each prompt names the JSON it must return.
  2. Check each answer against its part of contracts/ai_result.schema.json. An answer that does not match is an error, shown. It is never a default answer.
  3. Post the result to reply_to: ``json { "request_id": "<the request's id>", "by": "<the StellarView component, e.g. stellarview/hub-ai>", "model_route": "claude-code", "answered_at": "<ISO time>", "results": { "summarise": { "summary": "...", "cites": ["..."] }, "suggest_asset": { "asset_id": "...", "why": "...", "confidence": "high" }, "suggest_work_order": { "action": "close", "why": "..." } } } ``
  4. Fail visibly. If Claude Code is not reachable, the request stays open with the error shown on StellarView's side. Nothing is posted in its place.

What it must not do

  • Act. A suggestion closes nothing, opens nothing and moves no Jira issue. A person reads it in Jira or the twin and decides.
  • Hold prompts in code. They live in prompts/ai/ and Setup can edit them.
  • Use anything but Claude Code.

Source file

FileSizesha256
docs/ai-hook.md3 KB3c69fb90066f5ed393047bbae4faf913602640dfbcbfe95b9fcc53ea53b3453e