Turn an expert video into an SOP

# Decosa Expert-to-SOP: use the hosted API

You are wiring Decosa's Expert-to-SOP into this project (a training portal, a work-instruction library or an internal
runbook tool). It takes a recording of an expert doing a procedure (screen or bench, with narration) and returns a draft
SOP: each step cites a time range and a keyframe from the recording and is checked against what was said; steps said
but never shown come back as "needs confirmation". A named reviewer decides the flagged steps and signs the revision into
a record anyone can verify. Use only what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- It is a draft for a qualified person to review, not an approved procedure and not safety advice. Never label an SOP
  "approved" or "compliant" from this output alone.
- Send recordings you have the right to upload, made with the knowledge of the people in them. Confidential recordings
  belong on a self-hosted box.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page, kept in `DECOSA_API_KEY`, never in code.
   Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "expert-to-sop"}` returns
   `{"token", "expires_at", "budget"}`. Sessions per IP are limited (HTTP 429 with `Retry-After`); a demo token runs one
   draft at a time (409).
3. A draft needs about 7,700 generated tokens of budget before it starts (402 otherwise); a 40 s recording uses far less.

## Endpoints
- `POST /sop/draft` (token). Body: `{"video_b64": "<MP4, MOV or WebM as base64>" | "sample": "<id>", "title"?: "...", "transcript"?: [{"start": 2.1, "end": 3.8, "text": "..."}], "stream"?: true}`.
  - Recordings up to 64 MB and 10 minutes. Without `transcript`, the narration is transcribed on Decosa's hosted service (a
    model-call receipt). The model sees the recording at one frame a second (one frame every 2.5 s past 4 minutes).
  - JSON response: `{run_id, status: "draft_awaiting_signoff", totals, report, budget}`. `report.steps`:
    `[{n, action, start_s, end_s, range, evidence, seen, status: "confirmed"|"not_narrated"|"narration_differs"|"needs_confirmation", narration: {verdict, quote, reason}, keyframe: {t_s, sha256, jpeg_b64}}]`;
    `report.timing_warning` is a string when the cited times look wrong (check the keyframes), else null.
  - With `Accept: text/event-stream` (or `"stream": true`): `video`, `transcript`, `receipt`, `draft`, `step`,
    `said_only`, `timing_warning`, `keyframes`, `report`, `done`, `budget`.
- `POST /sop/runs/{run_id}/signoff` (same token) `{"name", "role", "revision"?: "1", "decisions"?: {"<step n>": "keep"|"confirmed_by_expert"|"remove"}, "default_decision"?, "confirm": true}`
  → `{record, check, signoff}`. Every step marked needs_confirmation or narration_differs must be decided. Runs are kept for one hour.
- `GET /sop/runs/{run_id}/export?format=md|json|record`, `POST /record/verify` `{"record"}` (no token),
  `GET /sop/info`, `GET /sop/samples`, `GET /sop/samples/{id}/video`, `GET /attest/signing-key`.

## Example: draft, review the flagged steps, sign (Python, `pip install httpx`)
```python
import base64, httpx, json, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
video = base64.b64encode(open("procedure.mp4", "rb").read()).decode()
r = httpx.post(f"{API}/sop/draft", json={"video_b64": video, "title": "Calibrate the crimp press"}, headers=H, timeout=600).json()
rep = r["report"]
if rep["timing_warning"]:
    print("check the keyframes:", rep["timing_warning"])
decisions = {}
for s in rep["steps"]:
    print(s["n"], s["range"], s["status"], s["action"])
    if s["status"] in ("needs_confirmation", "narration_differs"):
        decisions[str(s["n"])] = input(f"step {s['n']}: keep / confirmed_by_expert / remove? ").strip()
signed = httpx.post(f"{API}/sop/runs/{r['run_id']}/signoff", headers=H, json={"name": "A. Reviewer", "role": "CI lead",
                    "revision": "1", "decisions": decisions, "confirm": True}).json()
open("sop.md", "w").write(httpx.get(f"{API}/sop/runs/{r['run_id']}/export?format=md", headers=H).text)
json.dump(signed["record"], open("sop-revision-1.record.json", "w"))   # anyone can re-check it at /record/verify
```

## Receipts
Every model call on the hosted route gets a gateway-signed receipt; the video calls' request hash covers the video's
sha256 and the sampling settings. The speech to text gets a model-call receipt signed by Decosa's instance key. The
revision record lists them all and holds hashes only.

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 Expert-to-SOP: run it yourself (containers)

You are setting up Decosa's Expert-to-SOP on this machine, so recordings of internal systems and shop floors never leave
it. It turns a narrated recording of a procedure into a draft SOP whose steps cite a time range and a keyframe, checked
against what was said, and seals a named reviewer's sign-off into a signed revision record. Nothing is sent to Decosa's
hosted API. It drafts; it does not approve procedures.

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.

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/expert-to-sop.zip (693 KB, 10 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 expert-to-sop` (the api image carries the same bundle under /app/rehearsal/expert-to-sop/;
   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 expert-to-sop --bundle expert-to-sop.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 gloves instruction (said, never shown) needs confirmation", "the offset typed on screen but never said is marked not narrated", "zeroing the height sensor is seen and said"). 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. 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). Install the NVIDIA container toolkit and check
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM; it must run with `--limit-mm-per-prompt '{"image":4,"video":1}'`
   and `--media-io-kwargs '{"video":{"num_frames":240,"fps":1}}'`, not `--language-model-only`) and the `api` service.
   For the `api` service set `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b`
   and bind every port to 127.0.0.1. For narration, keep a `diarize` service if the compose file has one and set
   `DECOSA_DIARIZE_URL=http://diarize:8092`; otherwise send the transcript with each recording. Never set the gateway
   route on this box.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
   downloads about 20 GB of weights).
4. Smoke test: get a token with `POST /demo/session {"vertical":"expert-to-sop"}` and send
   `{"sample": "hmi-crimp-calibration", "stream": false}` to `POST /sop/draft`. Expect 8-14 steps, each with a keyframe;
   the gloves instruction `needs_confirmation`; the offset step `not_narrated`; no `timing_warning`; every receipt
   `"attested"` (signed by this box). Then `POST /sop/runs/<run_id>/signoff` with
   `{name, role, default_decision: "remove", confirm: true}` and `POST /record/verify` with the record: `ok` must be true.
5. Report back: `GET /attest/signing-key` (the public key a reviewer pins), the smoke-test results and how long the draft took.

Off by default. Joining as a provider serves other people's requests on this GPU; never do it on a box that holds
confidential recordings. If I ask for it later, follow the Provide page instead of improvising.