Make a settlement video

# Assemble the Decosa settlement-video maker on this machine

You are setting up a self-hosted tool for a plaintiff's personal-injury firm on this Linux machine. From a matter's
medical records, itemized bills, the client's signed statement and the client's own photos, it makes:
- a medical chronology where every line cites the file, page and box (the "Build a medical chronology" tool);
- a 7-scene settlement video script where every line names the chronology entries or statement paragraphs it rests on,
  with the cites attached in code, each line checked against what it cites, every date, count and amount checked against
  the record, and the bills added up in code (a statement's wrong total, duplicate charges, charges before the injury and
  charges with no matching visit flagged);
- after the attorney edits and approves every scene: an MP4 drawn from the exhibits (no video-generation model), narrated
  by the attorney's own recording, a stock house voice, or the attorney's voice with a consent-ledger entry, with content
  credentials, a cite sheet PDF and a signed, hash-chained record.

Work step by step, show me each command before running anything that needs sudo, and stop if a check fails.

**Before anything else, remind me:**
- Medical records, bills and client photos are protected health information and work product. On this box nothing leaves
  the machine: the model, the document reader, the voices and the renderer run here. Never point it at a hosted gateway
  while it holds client material.
- The client's photos and statement are used only with the client's recorded consent (POST /settlement/consent), and the
  attorney approves every scene. It is a drafting aid, not legal advice; it never writes a demand figure.

## 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/settlement-video.zip (2 KB, 11 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 settlement-video` (the api image carries the same bundle under /app/rehearsal/settlement-video/;
   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 settlement-video --bundle settlement-video.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 bills tie to $24,331.00 in code", "the statement whose printed total is off its own lines is flagged", "the duplicate therapy charge is flagged and counted once"). 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.

## What you are building

| service | image | model | port |
|---|---|---|---|
| `llm` | `${DECOSA_REGISTRY}/decosa-llm:0.1.0` (vLLM 0.29.0) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0 | internal 8000 |
| `parser` | `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1` | `PaddlePaddle/PaddleOCR-VL-1.6` @ `c5630abae1d940eafe0697512a0325494b02ab42`, Apache-2.0 | internal 8498 |
| `docreader` | built from `decosa-api/services/docreader` | Docling layout `docling-project/docling-layout-heron` @ `8f39ad3c0b4c58e9c2d2c84a38465abf757272d8` (MIT + Apache-2.0) | internal 8497 |
| `api` | built: `decosa-api` + a Kokoro layer (`docker/drama/Dockerfile`), no GPU | Kokoro-82M `hexgrad/Kokoro-82M` @ `f3ff3571791e39611d31c381e3a41a3af07b4987`, Apache-2.0, CPU | `127.0.0.1:8445` |

The attorney's consented voice uses Chatterbox Multilingual (`ResembleAI/chatterbox` @ `5bb1f6ee58e50c3b8d408bc82a6d3740c2db6e18`,
MIT) in its own venv; it is optional (step 6). Without it, narrate with the attorney's own recording or a house voice.

## 1. Check the GPU, driver and Docker

1. `nvidia-smi`: one NVIDIA GPU with at least 48 GB (the model about 20 GB plus KV cache, the parser and layout model
   about 6 GB). Driver 580 or newer. Blackwell (RTX PRO 6000) runs the NVFP4 defaults below; on Hopper or a 48 GB card use
   `LLM_MODEL=Qwen/Qwen3.8-27B-FP8`, `LLM_REVISION=main`, `LLM_GPU_UTIL=0.62`, `LLM_MAX_LEN=32768` (not measured).
2. `docker --version`, `docker compose version`, `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the NVIDIA
   Container Toolkit is missing, install them from the official repositories and run `sudo nvidia-ctk runtime configure --runtime=docker`.
3. About 80 GB of free disk; at least 8 CPU cores (frames are drawn on CPU, about a minute for a 3-minute video on 8 cores).

## 2. Get the source and build the api image

```bash
mkdir -p ~/decosa-settle && cd ~/decosa-settle
git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>     # publishing soon; if it fails, stop and tell me
cd decosa-api
docker build -f docker/api/Dockerfile -t decosa-api:local .
docker build -f docker/drama/Dockerfile --build-arg BASE=decosa-api:local -t decosa-api:settle .
cd ..
```
The second image adds Kokoro-82M and its stock voicepacks on CPU (`/opt/kokoro`), so the house voices run offline.

## 3. Write the compose file

Create `~/decosa-settle/.env`:
```bash
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_MAX_LEN=65536
LLM_GPU_UTIL=0.62
PARSER_GPU_UTIL=0.05
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Injury Law records team>"
```

Create `~/decosa-settle/docker-compose.yml`:
```yaml
name: decosa-settle
x-gpu: &gpu { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
x-health: &health { interval: 15s, timeout: 5s, retries: 5 }
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:0.1.0
    deploy: *gpu
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--max-model-len", "${LLM_MAX_LEN}", "--gpu-memory-utilization", "${LLM_GPU_UTIL}", "--max-num-seqs", "16",
              "--kv-cache-dtype", "fp8_e4m3", "--seed", "0", "--enable-force-include-usage", "--host", "0.0.0.0", "--port", "8000"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)"], start_period: 900s }
  parser:
    image: vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1
    deploy: *gpu
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["PaddlePaddle/PaddleOCR-VL-1.6", "--revision", "c5630abae1d940eafe0697512a0325494b02ab42", "--trust-remote-code",
              "--max-model-len", "8192", "--gpu-memory-utilization", "${PARSER_GPU_UTIL}", "--max-num-seqs", "16",
              "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0", "--generation-config", "vllm", "--host", "0.0.0.0", "--port", "8498"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8498/health', timeout=4)"], start_period: 600s }
  docreader:
    build: { context: ./decosa-api/services/docreader }
    deploy: *gpu
    restart: unless-stopped
    depends_on: { parser: { condition: service_healthy } }
    environment: { DOCREADER_PARSER_URL: "http://parser:8498/v1", DOCREADER_PARSER_MODEL: PaddlePaddle/PaddleOCR-VL-1.6, DOCLING_DEVICE: cuda }
    volumes: [hf-cache:/models]
  api:
    image: decosa-api:settle
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, docreader: { condition: service_started } }
    environment:
      DECOSA_LLM_ROUTE: direct                  # local model only; receipts are signed by this box's key ("attested")
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_LOCAL_SIGNING: "on"
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_DOCREADER_URL: http://docreader:8497
      DECOSA_CHRONO_RETRIEVAL: bm25             # the chronology's cite index without the retrieval service
      DECOSA_CHRONO_SYNTHETIC_ONLY: "0"         # this box accepts real records
      DECOSA_SETTLE_SYNTHETIC_ONLY: "0"         # and real matters, with recorded consent
      DECOSA_CHRONO_MAX_PAGES: "600"
      DECOSA_STUDIO_KOKORO_PYTHON: /opt/kokoro/bin/python
      DECOSA_SETTLE_RENDER_WORKERS: "6"
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "600000"
      DECOSA_SESSION_TTL_S: "28800"
      DECOSA_LLM_TIMEOUT_S: "300"
      DECOSA_CORS_ORIGIN_REGEX: '^https?://(localhost|127\.0\.0\.1)(:\d+)?$$'
    ports: ["127.0.0.1:8445:8445"]
    volumes: [decosa-data:/data]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/healthz', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, decosa-data: {} }
```
Use the named volume `decosa-data` exactly as written (a root-owned bind mount breaks `/data`). Run `docker compose up -d --build`
and poll `docker compose ps` until healthy (the LLM takes 5 to 10 minutes the first time).
`curl -s localhost:8445/settlement/info | jq '{synthetic_only, narration}'` should show `synthetic_only: false`.

## 4. Smoke test on the bundled synthetic matter (fictional client, stand-in photos)

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"settlement-video"}' | jq -r .token)
curl -s $API/settlement/draft -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"whitlock"}' > /tmp/draft.json
jq '{counts, specials: .tie.specials, flags: [.tie.flags[].kind]}' /tmp/draft.json
jq -r '.lines[] | "\(.id)\t\(.status)\t\(.scene)\t\(.text[0:70])"' /tmp/draft.json
jq '{draft_id, edit: {lines: [.lines[] | select(.status=="ok" or .status=="argument")], approved: {before:true, incident:true, timeline:true, injuries:true, treatment:true, bills:true, after:true}}, narration: {mode: "house", voice: "am_michael"}}' /tmp/draft.json \
  | curl -s $API/settlement/render -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @- | tee /tmp/job.json
JOB=$(jq -r .job_id /tmp/job.json); until curl -s $API/settlement/jobs/$JOB -H "authorization: Bearer $TOKEN" | jq -e '.status=="done" or .status=="error"' >/dev/null; do sleep 5; done
curl -s $API/settlement/jobs/$JOB -H "authorization: Bearer $TOKEN" | jq '{status, error, outputs: .outputs | {seconds, cited_lines, credential, timings_s}}'
curl -s "$API/settlement/jobs/$JOB/video.mp4?token=$TOKEN" -o settlement-video.mp4
curl -s "$API/settlement/jobs/$JOB/cite-sheet.pdf?token=$TOKEN" -o cite-sheet.pdf
curl -s "$API/settlement/jobs/$JOB/record.json?token=$TOKEN" | jq '{record: .}' | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
```
Pass if: the bills tie to `$24,514.00` with the flags `mis_total`, `duplicate`, `pre_incident` and `no_record`; most lines are
`ok`, and a line naming the MRI level "L4-15" (the scanned page's read slip) is held back as `numbers`; the job is `done`
with a video of about 3 minutes and `credential: "c2pa"`; and the record verifies.

## 5. A real matter

1. Build the chronology first: `POST /chronology/run` with the record files (see the medical chronology's own prompt).
2. Record the client's consent: show the client the sentence from `POST /settlement/consent` (it is in the 422 answer when the
   read-back fails), record it on a phone, then
   `POST /settlement/consent {"role":"client","name":"<client>","matter":"<matter id>","recording_b64":"<audio>"}`.
3. `POST /settlement/draft` with `{chronology, files: [{id, title, role: record|bills|statement, file_b64}], photos: [{file_b64, when}],
   matter: {client_name, incident, id, caption, prepared_by}, consent: {client: <identity_id>, matter: <matter>}}`. File ids must
   match the chronology's (F1, F2, ... in the order you sent them). Mark a photo of a child `minor: true`: it is refused for now.
4. Edit and approve in the web app, or send the final lines to `POST /settlement/render` as in step 4.

## 6. Optional: the attorney's consented voice

Create a venv with Chatterbox (`python -m venv /opt/chatterbox && /opt/chatterbox/bin/pip install chatterbox-tts==0.1.4`)
inside the api container or a derived image, set `DECOSA_DUB_TTS_PYTHON=/opt/chatterbox/bin/python`, enrol the attorney
with `POST /settlement/consent {"role":"attorney", ...}` and render with `{"mode":"consented","identity_id":"<id>","reference_b64":"<the same recording>"}`.
It runs on CPU here (`DECOSA_SETTLE_TTS_DEVICE=cpu`): several minutes for a 3-minute script. Generated voices are disclosed
on the end card and in the content credential.

## 7. Point the web app at it, and keep the network off

- Base URL `http://localhost:8445`; for the web app set `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`.
- Drafts and renders are deleted after two hours (`DECOSA_SETTLE_TTL_S`); keep the MP4, the cite sheet and the record with the file.
- `DECOSA_LLM_ROUTE=gateway` would send record text to a the gateway: leave it off on a box with client material.

Finish with a summary: what is running, the health output, the smoke-test results and the reminders above.