Turn a family interview into a film

# Assemble the Decosa family interview film on this machine

You are setting up a tool that turns a recorded family interview into a film: it tells the storyteller's voice from the
interviewer's, hears her words in her language, finds the chapters of her life and her best lines (each re-found at the
second she said it), puts English subtitles under her own words with a meaning check, reads the handwriting on the backs
of photos, and cuts a trailer, a film and a book with QR codes that play her quotes. Her real voice and her real photos
only: no voice clone, and no model draws or changes a picture. Work step by step, show me each command before you run
anything with `sudo`, and stop to ask if a check fails.

## 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/family-film.zip (102 KB, 8 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 family-film` (the api image carries the same bundle under /app/rehearsal/family-film/;
   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 family-film --bundle family-film.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: "a refusal in her own words is refused", "the sample is ready", "at least 4 chapters of her life"). 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.

## 0. Ground rules and licences
- Models: Qwen3.8-27B (chapters, quotes, titles; Apache-2.0), Qwen3-ASR-1.7B (speech; Apache-2.0), Hy-MT2-7B
  (translation; Apache-2.0), PaddleOCR-VL-1.6 (photo backs; Apache-2.0), ECAPA-TDNN from
  `speechbrain/spkrec-ecapa-voxceleb` (speakers, CPU, ONNX; Apache-2.0), and the Ultra-Light face detector (MIT, bundled
  in the api image). The score is a pre-rendered ACE-Step 1.5 cue (MIT) shipped with the api.
- Record only someone who agrees. The api asks for her consent in her own words first, checks what she means (a
  refusal or a hesitation stops the project), keeps it in the consent ledger with her own revocation link, and deletes
  the project when she uses it. The ledger keeps a voiceprint of her consent recording; some laws treat voiceprints as
  biometric data, so get the consent your law asks for.
- The fronts of photos never go to any model. A picture is read only when the face detector finds no face in it.
- Bind every port to 127.0.0.1. Logs carry ids, counts and hashes, never her words.

## 1. Check the machine
1. `nvidia-smi`: one card with about 45 GB free runs speech (about 5 GB while loaded), translation (vLLM at
   `--gpu-memory-utilization 0.18`, about 18 GB), the photo-back reader (0.04) and, with room to spare, the text model
   (about 20 GB, NVFP4 needs a Blackwell card; use a server you already run otherwise). We measured it on a shared RTX
   PRO 6000 96 GB.
2. `docker --version`, `docker compose version`; if Docker or the NVIDIA container toolkit is missing, ask me, then
   install them from the official repositories and check `docker run --rm --gpus all ubuntu nvidia-smi`.
3. Disk: about 60 GB (Qwen 20 GB, Hy-MT2 15 GB, ASR 4 GB, reader 2 GB, images).

## 2. Images and weights
- `${DECOSA_REGISTRY}/decosa-api:<tag>` (**publishing soon**). If the pull fails, build from source:
  `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required), check out the newest release that contains
  `decosa_api/studio_core/family_film/` (`main` until one does), and `docker build -f docker/api/Dockerfile -t decosa-api:family .`.
  The image carries FFmpeg (libass), fonts, onnxruntime and c2pa-python.
- The speaker model: in a throwaway venv with `speechbrain` and CPU torch, run
  `python scripts/consent/export_ecapa_onnx.py ./ecapa` from the same checkout. It downloads
  `speechbrain/spkrec-ecapa-voxceleb`, writes `ecapa/ecapa.onnx` once and checks parity; the api needs only onnxruntime.
- `vllm/vllm-openai:v0.29.0` for the text model (`nvidia/Qwen3.8-27B-NVFP4`, revision `482ca0f3832238542f8f5295dde86b5f22711d80`),
  translation (`tencent/Hy-MT2-7B`) and the reader (`PaddlePaddle/PaddleOCR-VL-1.6`, revision `c5630ab`).
- The speech service: `services/lang/server.py` from the checkout in its own Python 3.12 venv (we run torch 2.8.0+cu128,
  `qwen-asr` 0.0.6, fastapi, uvicorn, soundfile and librosa 1.0.0), with `Qwen/Qwen3-ASR-1.7B` (revision `7278e1e70fe206f11671096ffdd38061171dd6e5`)
  in `LANG_MODELS/Qwen3-ASR-1.7B/`. Run it with `LANG_HOST=127.0.0.1 LANG_PORT=8492 LANG_DEVICE=cuda:0`.

## 3. docker-compose.yml
Write this in `~/decosa/family/`. `network_mode: host` lets the api reach the speech service on 127.0.0.1:8492.

```yaml
services:
  llm:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "nvidia/Qwen3.8-27B-NVFP4", "--served-model-name", "qwen3.8-27b", "--host", "127.0.0.1", "--port", "8114",
              "--max-model-len", "32768", "--enable-prefix-caching", "--gpu-memory-utilization", "0.30"]
    network_mode: host
    volumes: ["hf-cache:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
    healthcheck: { test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8114/v1/models', timeout=4)"], interval: 30s, retries: 30 }
  mt:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "tencent/Hy-MT2-7B", "--served-model-name", "hy-mt2-7b", "--host", "127.0.0.1", "--port", "8491",
              "--model-impl", "transformers", "--enforce-eager", "--gpu-memory-utilization", "0.18", "--max-model-len", "8192"]
    network_mode: host
    volumes: ["hf-cache:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
  reader:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "PaddlePaddle/PaddleOCR-VL-1.6", "--revision", "c5630ab", "--served-model-name", "PaddlePaddle/PaddleOCR-VL-1.6",
              "--trust-remote-code", "--host", "127.0.0.1", "--port", "8498", "--gpu-memory-utilization", "0.04", "--max-model-len", "8192"]
    network_mode: host
    volumes: ["hf-cache:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
  api:
    image: decosa-api:family
    network_mode: host
    environment:
      DECOSA_HOST: 127.0.0.1
      DECOSA_PORT: "8445"
      DECOSA_DATA_DIR: /data
      DECOSA_LLM_ROUTE: direct
      DECOSA_LLM_URL: http://127.0.0.1:8114/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_LANG_SPEECH_URL: http://127.0.0.1:8492
      DECOSA_LANG_MT_URL: http://127.0.0.1:8491/v1
      DECOSA_LANG_MT_MODEL: hy-mt2-7b
      DECOSA_DOCREADER_PARSER_URL: http://127.0.0.1:8498/v1
      DECOSA_CONSENT_SPK_MODEL: /models/ecapa/ecapa.onnx
      DECOSA_STUDIO_GPU_USD_PER_H: "1.32"              # what your GPU hour costs you, for the estimates
      DECOSA_PROVENANCE_DIR: /provenance
    volumes: ["decosa-data:/data", "decosa-provenance:/provenance", "./ecapa:/models/ecapa:ro"]
    depends_on: { llm: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/studio/family/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
  decosa-provenance:
  hf-cache:
```

Use named volumes for state (the api runs as uid 10001). `docker compose up -d`, start the speech service, and wait for
the health checks. Create the C2PA signing material once, then restart: `docker compose exec api python
scripts/provenance_devcert.py && docker compose restart api` (a development CA: public validators show the signature as
valid and the issuer as untrusted). Back up the box's Ed25519 key: `docker compose cp api:/data/attest ./attest-backup`.

## 4. Smoke test
```bash
B=http://127.0.0.1:8445
curl -s $B/studio/family/info | jq '{languages: [.languages[].id], models}'
T=$(curl -s -XPOST $B/demo/session -H 'content-type: application/json' -d '{"vertical":"studio"}' | jq -r .token)
P=$(curl -s -XPOST $B/studio/projects -H "authorization: Bearer $T" -H 'content-type: application/json' -d '{"name":"[TEST] family"}')
PID=$(echo "$P" | jq -r .project.id); K=$(echo "$P" | jq -r .project_key)
F=$(curl -s -XPOST "$B/studio/projects/$PID/family/sample?key=$K" -H "authorization: Bearer $T" | jq -r .id)
until curl -s "$B/studio/family/$F?key=$K" -H "authorization: Bearer $T" | jq -e '.films.trailer.status=="done" or .status=="failed"' >/dev/null; do sleep 10; done
curl -s "$B/studio/family/$F?key=$K" -H "authorization: Bearer $T" | jq '{status, chapters: (.chapters|length), tracing, speakers: .speakers.ok, meaning: {ok: .meaning.ok, check: .meaning.check, error: .meaning.error}, trailer: .films.trailer.credential}'
```
Expect `ready`, 6-8 chapters, `tracing.rate` 1.0, `speakers: true`, English on every quote, and `trailer: "c2pa"`,
about a minute after the sample starts on our server. Open the trailer URL from `.films.trailer.url` and watch it.
Report the times you measure.

## 5. Your own interview
In the app (or the API): create a project, record her consent (`POST /studio/projects/{pid}/family` with
`storyteller`, `language` and `consent_b64`, her own words on the consent text from `/family/consent-text`), then
upload the interview (`/studio/family/{fid}/interview`, up to 60 MB, 2 hours) and up to 40 photos. Keep the
revocation link the consent step returns: give it to her.

## 6. Point the app at the local API
Set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in the site's `.env.local`. Contract: `API_CONTRACT.md`, the Changes entry
"Studio: family interview film, music video starring you, our story film" (29 Sep 2026).