Write the inspection report

# Decosa Field reports: use the hosted API

You are adding Decosa's Field reports to this project. Decosa runs open models (Voxtral Mini 4B Realtime for speech,
Qwen3.8-27B for text) through the Decosa API. Every model output comes with a signed receipt.
Use only the endpoints below. If you need something that is not listed, stop and ask me; do not guess endpoints.

- Base URL: `https://api.decosa.ai`
- WebSocket base: `wss://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz` returns `{"ok": true, "asr": bool, "llm": bool, "live_sessions": n, "queue": n}`.

## Auth: API key (or a demo session)
1. Preferred: an API key. Create one on the tool page with "Get an API key"; it looks like `dk_…` and is shown
   only once. Keep it in an environment variable, never in code: `DECOSA_API_KEY=dk_…`. Send
   `Authorization: Bearer $DECOSA_API_KEY` on calls that need auth; WebSockets take `?token=$DECOSA_API_KEY` in the URL.
2. Without a key, use a short demo session: `POST https://api.decosa.ai/demo/session` with JSON `{"vertical": "field"}` returns
   `{"token": "<opaque>", "expires_at": <unix seconds>, "budget": {"seconds_audio": 300, "llm_tokens": 20000}}`.
3. Send `Authorization: Bearer <token>` on calls that need it (session-bound calls such as live audio, replay, chat and
   render jobs). WebSockets take `?token=<token>` in the URL instead. These need no token: `GET /healthz`,
   `GET /demo/scripts`, `GET /demo/recordings`, `GET /demo/recordings/{id}/events`, `GET /studio/gallery`,
   `GET /studio/jobs/{id}`, `GET /receipts/{id}`.
4. Demo-session limits: a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz), and a global cap on concurrent live audio sessions. Over a limit the API answers
   HTTP 429 with a `Retry-After` header (seconds): wait that long, then retry. Reuse a token until `expires_at`.
5. The API keeps no PII; session transcripts live in memory and are deleted when the session ends.

## Live audio
`WS wss://api.decosa.ai/ws/live?vertical=field&token=<token>`

Client to server:
- binary frames: 16 kHz mono PCM16 little-endian, about 100 ms each (1600 samples, 3200 bytes);
- a text frame `{"type":"stop"}` when the speaker is done. The server then writes final lanes, sends `done` and closes.

Server to client, JSON text frames:
- `{"type":"ready","vertical":"field","models":{"asr":"...","llm":"..."}}`
- `{"type":"transcript","t":12.4,"text":"...","final":true}` (partials have `final:false` and are replaced by the next update)
- `{"type":"lane","lane":"<lane id>","title":"<Title>","body":"<markdown or text>","data":{...optional...},"latency_ms":850}`
  Each lane event replaces the previous content of that lane.
- `{"type":"receipt","id":"<completion id>","model":"qwen3.8-27b","gateway_sig":"<hex>","provider":"<provider id>"}`
  
- `{"type":"budget","seconds_audio_left":240,"llm_tokens_left":15000}`
- `{"type":"error","message":"..."}`
- `{"type":"done","summary":{...final artifact...}}`

Lanes for `field`:
- `checklist`: inspection or site-walk checklist, ticked as items are covered
- `issues`: issues found, each with a severity
- `measurements`: measurements heard, with units
- `report`: on stop: a structured report (JSON in `data`) plus markdown in `body`

Final artifact in `done.summary`: the structured report JSON plus markdown.

Close codes the server uses:
- `4401` bad or expired token: get a new session, then reconnect.
- `4409` token already has a live socket: close the other one, or get a new session.
- `4429` busy (live-session cap): wait, then retry. Back off at least 15 s.
- `4400` bad parameters, `4402` budget exhausted, `4403` vertical or origin mismatch: do not retry; fix the cause.

On any other drop before `done`, reconnect with backoff (0.5 s, 1 s, 2 s, ... up to 8 s) using the same token while it
is valid. Stop sending audio when `seconds_audio_left` reaches 0.

## Testing without a microphone
`POST https://api.decosa.ai/demo/replay` with `Authorization: Bearer <token>` and JSON
`{"vertical":"field","script_id":"<script id>"}` streams the same event types over SSE (`text/event-stream`, one JSON
event per `data:` line). It runs a canned audio script through the real pipeline, so the output is live.
Script ids for `field`: `field-roof-inspection`, `field-electrical-panel`. `GET https://api.decosa.ai/demo/scripts` lists all scripts (no token).

## Receipts (public, read-only)
`GET https://api.decosa.ai/receipts/{id}` returns
`{"id", "model", "weights_root", "request_hash", "output_hash", "provider": {"miner_id", "pubkey", "sig"}, "gateway": {"pubkey", "sig"}, "proof": {"format", "verified"}, "checks": [{"name", "ok", "detail"}]}`.

## Patient and client data
The hosted API is a public demo. It must not receive PHI or any real patient or client information. For real
data, self-host (see the "Run it yourself" prompt) so audio and text never leave the site.

## Audio format
Convert a recording to the wire format with ffmpeg:
`ffmpeg -i input.wav -ar 16000 -ac 1 -f s16le input.pcm`

## Example: TypeScript (Node 22+, global fetch and WebSocket)
```ts
import { readFileSync } from "node:fs";

const BASE = "https://api.decosa.ai";
// Prefer your API key (dk_…); fall back to a short demo session.
let token = process.env.DECOSA_API_KEY;
if (!token) {
  const session = await fetch(`${BASE}/demo/session`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ vertical: "field" }),
  });
  if (session.status === 429) throw new Error(`busy, retry after ${session.headers.get("Retry-After")} s`);
  ({ token } = await session.json());
}

const ws = new WebSocket(
  `${BASE.replace(/^http/, "ws")}/ws/live?vertical=field&token=${encodeURIComponent(token)}`,
);
ws.binaryType = "arraybuffer";
ws.onmessage = (m) => {
  const ev = JSON.parse(String(m.data));
  if (ev.type === "transcript" && ev.final) console.log("heard:", ev.text);
  if (ev.type === "lane") console.log(`[${ev.lane}]`, ev.body);
  if (ev.type === "receipt") console.log("receipt:", `${BASE}/receipts/${ev.id}`);
  if (ev.type === "done") { console.log("final:", ev.summary); ws.close(); }
};
ws.onopen = async () => {
  const pcm = readFileSync("input.pcm"); // 16 kHz mono PCM16 LE
  for (let i = 0; i < pcm.length; i += 3200) {
    ws.send(pcm.subarray(i, i + 3200));
    await new Promise((r) => setTimeout(r, 100)); // real time
  }
  ws.send(JSON.stringify({ type: "stop" }));
};
```

## Example: Python (`pip install requests websockets`)
```python
import asyncio, json, os, requests, websockets

BASE = "https://api.decosa.ai"
token = os.environ.get("DECOSA_API_KEY")  # dk_… API key preferred
if not token:
    r = requests.post(f"{BASE}/demo/session", json={"vertical": "field"})
    if r.status_code == 429:
        raise SystemExit(f"busy, retry after {r.headers.get('Retry-After')} s")
    token = r.json()["token"]

async def main():
    url = BASE.replace("http", "ws", 1) + f"/ws/live?vertical=field&token={token}"
    async with websockets.connect(url) as ws:
        async def send_audio():
            with open("input.pcm", "rb") as f:  # 16 kHz mono PCM16 LE
                while chunk := f.read(3200):
                    await ws.send(chunk)
                    await asyncio.sleep(0.1)
            await ws.send(json.dumps({"type": "stop"}))
        sender = asyncio.create_task(send_audio())
        async for msg in ws:
            ev = json.loads(msg)
            if ev["type"] == "lane":
                print(f"[{ev['lane']}]", ev["body"])
            elif ev["type"] == "receipt":
                print("receipt:", f"{BASE}/receipts/{ev['id']}")
            elif ev["type"] == "done":
                print("final:", ev["summary"])
                break
        await sender

asyncio.run(main())
```

## What to build
1. A small client module for the calls above (session, socket, reconnect, 429 handling).
2. UI or CLI output that shows the transcript, each lane, and a link to every receipt.
3. A config value for the base URL, so it can point at a self-hosted box later with no code change.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa Field reports: run it yourself (containers)

You are setting up Decosa Field reports to run entirely on this machine's NVIDIA GPU(s). Nothing is sent to Decosa's
hosted API and there are no Decosa charges. The local service speaks the same API as the hosted one, so apps built
against the hosted API only need a new base URL.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Hardware: 1x RTX PRO 6000 (96 GB), or 2x RTX 5090 (32 GB each). Linux x86_64 with a recent NVIDIA driver.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/field.zip (665 KB, 9 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py field` (the api image carries the same bundle under /app/rehearsal/field/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py field --bundle field.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the session ends with a done event", "the session reports no errors", "the report is titled for the site (Oak Street)"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Check the GPU and driver: `nvidia-smi`. If it fails, stop and tell me; do not install drivers without asking.
   Check free disk: the first start downloads model weights (tens of GB).
2. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). Add me to the `docker` group only if I agree.
3. NVIDIA Container Toolkit: if `docker run --rm --gpus all ubuntu nvidia-smi` fails, install the toolkit using
   NVIDIA's official instructions (docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html),
   then run `sudo nvidia-ctk runtime configure --runtime=docker` and `sudo systemctl restart docker`. Re-run the check.
4. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. If it references an `.env` file or variables, ask me for any values. Never print secrets.
5. Pull and start: `docker compose pull && docker compose up -d`.
6. Wait for health. Find the host port that compose.yaml publishes for the API (`docker compose ps`), then poll
   `curl -fsS http://localhost:<PORT>/healthz` every 10 s until it returns `"ok": true` with `"asr": true` and
   `"llm": true`. The first start can take a while as weights download. Show me `docker compose logs --tail=50` if it
   has not come up after 20 minutes.
7. Smoke test: `curl -fsS -X POST http://localhost:<PORT>/demo/session -H 'Content-Type: application/json' -d '{"vertical":"field"}'`
   should return a token.
8. Report back: GPU model(s) and memory, Docker and toolkit versions, the `/healthz` output, and the local base URL.

## Sensitive data
Site walks can capture addresses, names and client details. Keep the service on a private network, with no public
port forwarding or tunnels.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 48 GB of unified memory or more): use https://decosa.ai/prompts/field-mac.md instead.