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