Find the themes in your interviews

# Assemble Decosa interview themes on this machine

You are setting up Decosa interview themes on this Linux machine for a researcher (or a lab) with recorded interviews under an ethics or IRB protocol. It returns:
- speaker-separated transcripts, with interviewer turns kept apart and never coded or quoted;
- a proposed codebook of 8 to 12 codes that I rename, merge, split and approve before anything is coded;
- every passage of participant talk coded against the approved codebook;
- themes with participant counts (computed in code) and three quotes each, every quote checked word for word against the transcript and the person it is credited to;
- a REFI-QDA project (.qdpx) and codebook (.qdc), CSVs, a methods paragraph and a signed record of every model call;
- optionally, a small model trained on my own reviewed codes that codes the rest (CPU).

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:**
- Interview audio and transcripts stay on this machine: the model route is local (`direct`), `DECOSA_THEMES_SAMPLES_ONLY=0` lets the API take my own files, and the API keeps nothing after each request. The study lives in my browser or my own client until I export it.
- It proposes codes and themes; I decide them. It does not replace my ethics approval.

Repeat both points in your final summary.

## 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/interview-themes.zip (32 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 interview-themes` (the api image carries the same bundle under /app/rehearsal/interview-themes/;
   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 interview-themes --bundle interview-themes.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: "at least 40 passages of participant talk were coded", "no passage comes from the interviewer or another voice", "at least three themes"). 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, `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1`) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0 | internal 8000 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | voice check `speechbrain/spkrec-ecapa-voxceleb` (Apache-2.0, CPU); your own model `BAAI/bge-small-en-v1.5` (MIT, CPU) | `127.0.0.1:8445` |
| `diarize` (only for recordings) | built from the decosa-api source (`services/diarize`) | `OpenMOSS-Team/MOSS-Transcribe-Diarize` @ `704aa4a9c304e8520be88901e0d1960158ef5b15`, Apache-2.0 | 8092 on the docker bridge |

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 48 GB and driver 580 or newer.
   - Blackwell (RTX PRO 6000, B200): use the defaults below (NVFP4). This is the measured setup.
   - Hopper (H100/H200) or a 48 GB Ada/L40S: set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8` and `LLM_REVISION=main`; on 48 GB also set `LLM_MAX_LEN=32768`. Not measured.
   - No suitable GPU: I can still bring transcripts and point `DECOSA_LLM_URL` at a model server my institution approves. Ask me before doing that.
2. Check `docker --version`, `docker compose version` and `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the NVIDIA Container Toolkit is missing, install them from the official Docker and NVIDIA repositories, and show me the commands first.
3. Confirm about 70 GB of free disk.

## 2. Get the images

The images are **on request** while self-host is in early access: ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry (set it as `DECOSA_REGISTRY`), pull access and the compose file. Try `docker pull ${DECOSA_REGISTRY}/decosa-{llm,api}:0.1.0`.
If a pull fails, build from source once the `decosa-api` source is published: in the clone, `docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`, and `docker compose build llm` from its compose file.

## 3. Write the compose file

Create `~/decosa-themes/.env`:

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_MAX_LEN=65536
LLM_GPU_UTIL=0.80
DECOSA_SIGNER_NAME="<who signs these records, e.g. the lab's name>"
```

Create `~/decosa-themes/docker-compose.yml` with exactly these services:

```yaml
name: decosa-themes
x-health: &health
  interval: 15s
  timeout: 5s
  retries: 5
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:${DECOSA_TAG}
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--language-model-only", "--max-model-len", "${LLM_MAX_LEN}", "--gpu-memory-utilization", "${LLM_GPU_UTIL}",
              "--max-num-seqs", "16", "--kv-cache-dtype", "fp8_e4m3", "--speculative-config", '{"method":"mtp","num_speculative_tokens":3}',
              "--seed", "0", "--enable-force-include-usage", "--disable-uvicorn-access-log", "--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 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy } }
    extra_hosts: ["host.docker.internal:host-gateway"]
    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"                # Ed25519 key created at /data/attest/ed25519.pem on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_THEMES_SAMPLES_ONLY: "0"           # take my own recordings and transcripts
      DECOSA_THEMES_EMBED_DIR: /data/models/bge-small-en-v1.5
      DECOSA_DIARIZE_URL: ""                    # step 4 sets this for recordings
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "2000000"       # a 40-interview study codes a few thousand passages
      DECOSA_SESSION_TTL_S: "28800"
      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 host bind mount owned by root makes the API fail on `/data/keys.sqlite`.
For "your own model", put the ONNX export of `BAAI/bge-small-en-v1.5` (`model.onnx` and `tokenizer.json`) in the volume at `/data/models/bge-small-en-v1.5`; without it the API falls back to hashed word features and says so on the model card.
Run `docker compose up -d`, then poll `docker compose ps` until both services are healthy (5-10 minutes the first time). `curl -s localhost:8445/healthz` should show `"llm": true`.

## 4. Recordings (diarize service)

Skip this if I only bring transcripts (plain text with `Name:` labels, or WebVTT/SRT).
The `diarize` service (MOSS-Transcribe-Diarize 0.9B, Apache-2.0) has no published image yet. Run `services/diarize` from the decosa-api source on this box (install with the `uv` commands at the top of `services/diarize/requirements.txt`, then `DIARIZE_HOST=172.17.0.1 DIARIZE_PORT=8092 DIARIZE_DEVICE=cuda:0 .venv-diarize/bin/python services/diarize/server.py`; `172.17.0.1` is the docker bridge address from `ip -4 addr show docker0`, reachable from containers and not from the LAN). Set `DECOSA_DIARIZE_URL: http://host.docker.internal:8092` on `api` and `docker compose up -d api`. The 0.9B model needs a few GB beside the LLM; if it doesn't fit, lower `LLM_GPU_UTIL` to 0.70. That fit is an estimate, not measured.

## 5. Smoke test

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"interview-themes"}' | jq -r .token)
curl -s $API/themes/info | jq '{samples_only, limits}'
printf 'Interviewer: What is a normal day like for you?\nMaria: We start at seven with a check-in, then I spend most of the morning on patient calls, which I find draining but meaningful.\nInterviewer: What helps?\nMaria: Honestly the routine helps, and talking with my colleagues at lunch keeps me going when the calls are hard.\n' > /tmp/iv1.txt
jq -Rs '{text: ., title: "Test interview"}' /tmp/iv1.txt | curl -sN $API/themes/transcript -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @- \
  | sed -n 's/^data: //p' | jq -c 'select(.type=="result") | .interview' > /tmp/iv1.json
jq '{turns: (.turns | length), roles: [.turns[].role] | unique}' /tmp/iv1.json
```

Pass if `samples_only` is `false`, the interview has 4 turns, and the roles are `interviewer` and `participant` (Maria). Then propose a codebook (it needs at least a few participant passages, so this tiny interview may be refused with a clear message; that is a pass too):

```bash
jq '{interviews: [.], question: "What helps staff cope with hard calls?", n_codes: [3, 5]}' /tmp/iv1.json \
  | curl -sN $API/themes/codebook -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @- | sed -n 's/^data: //p' | jq -c '{type, message, codes: (.codebook.codes // [] | map(.name))}'
```

Then verify a signed record from any `result` event: `jq '{record}' result.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'` must say `ok: true`.

## 6. The signing key

1. `curl -s localhost:8445/attest/signing-key` shows the public key. Show me the `pubkey`, and tell me to back up the `decosa-data` volume (it holds `/data/attest/ed25519.pem`).
2. Receipts from this box say `status: "attested"`: signed by its own key. They show nothing was changed after signing and which key signed; they do not prove the transcript or the codes are right.

## 7. Point the app at the local API

The console at decosa.ai runs in my browser; my study never leaves it except to go to the API I choose. To use this box, run the site from source with `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` (`npm ci && npm run build && npm start`), or call the API from my own scripts with the same bearer token: `POST /themes/transcribe` (recording as the body), `/themes/transcript`, `/themes/codebook`, `/themes/codebook/split`, `/themes/analyze`, `/themes/train` and `/themes/export`.

## 8. Optional: provide compute to the network

Off by default, and never for interview data: this box runs the tool for me only. If I later want to offer spare GPU time to the Decosa network for public workloads, that is a separate setup on a separate machine; see decosa.ai/provide.

## Final summary

Tell me: which services are healthy, the signing key's `pubkey`, where the compose file is, whether recordings are enabled (step 4), and repeat the two reminders from the top.