Review a collections call

# Assemble the Decosa collections and servicing call QA on this machine

You are setting up a self-hosted call-QA checker on this Linux machine for a debt-collection agency or a mortgage servicer.
It takes the transcript of a recorded collection or servicing call and the account's call log.
- **On the call**, each answer is yes, no or unclear, with a quote and a time. It checks:
  - the debt-collector disclosure;
  - whether identity was confirmed before the debt came up;
  - whether the debt was disclosed to a third party;
  - false or threatening statements;
  - whether a stop request or a dispute was brushed aside;
  - for a delinquent mortgage, whether loss-mitigation options were mentioned.
- **From the call log**, computed in code:
  - the Regulation F call-frequency presumptions (12 CFR 1006.14(b)(2));
  - calling hours in every time zone on file (1006.6(b)(1)(i));
  - calls after a stop request or a lawyer;
  - Regulation X live contact by day 36 (1024.39(a)).
- It seals everything in a signed, hash-chained record to keep with the recording for three years (1006.100(b)).
- With the optional diarizer, it turns a recording into a timed, speaker-labelled transcript.

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:**
- Collection calls carry Social Security numbers, dates of birth and account numbers. Keep everything on this machine: the
  model route stays local (`direct`), and nothing goes to a hosted service.
- Some states require every party's consent before a call is recorded (for example California Penal Code 632). Each
  check needs a consent statement, and the statement goes into the record.
- This is QA triage for a person to review. It is not a compliance verdict and not legal advice.

Repeat these 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/collections-call-qa.zip (3 KB, 12 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 collections-call-qa` (the api image carries the same bundle under /app/rehearsal/collections-call-qa/;
   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 collections-call-qa --bundle collections-call-qa.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 six call checks ran", "every call check got a typed answer", "the planted sheriff threat is flagged"). 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) | none | `127.0.0.1:8445` |
| `diarize` (optional, recordings only) | built from the decosa-api source (`services/diarize`) | `OpenMOSS-Team/MOSS-Transcribe-Diarize` @ `704aa4a9c304e8520be88901e0d1960158ef5b15`, Apache-2.0 | internal 8092 |

Typed, WebVTT or SRT transcripts need no speech model. The call-log findings need no model at all (`POST /collections/log`).

## 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 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.
   - Under 48 GB: stop and tell me it will not fit.
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 (`sudo nvidia-ctk runtime configure --runtime=docker`, then restart Docker).
3. Confirm about 60 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.
1. Try `docker pull ${DECOSA_REGISTRY}/decosa-{llm,api}:0.1.0`.
2. If a pull fails, build from source once the `decosa-api` source is published. Clone it, then run
   `docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .` in it, and
   `docker compose build llm` from its compose file.
3. If neither works, stop and tell me.

## 3. Write the compose file

Create `~/decosa-cq/.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.85
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Recovery compliance>"
```

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

```yaml
name: decosa-cq
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 } }
    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_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "200000"        # per session; a call needs about 2,100 generated tokens
      DECOSA_SESSION_TTL_S: "28800"
      DECOSA_COLLECTIONS_AUDIO: "0"             # "1" only with the diarize service
      DECOSA_DIARIZE_URL: ""
      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` as written: a host bind mount owned by root makes the API fail on
`/data/keys.sqlite`.
1. Run `docker compose up -d`.
2. Poll `docker compose ps` until both services are healthy. The LLM takes 5-10 minutes the first time.
3. `curl -s localhost:8445/healthz` should show `"llm": true`. `asr` is false here, and that is fine.

## 4. Optional: recordings (diarize)

Do this only if I want transcripts made from call recordings.
1. Build `services/diarize` from the decosa-api source on a CUDA PyTorch base image. Give it the env
   `DIARIZE_HOST=0.0.0.0 DIARIZE_PORT=8092 DIARIZE_DEVICE=cuda:0`, the `hf-cache` volume, the same GPU, and a health
   check on `GET /health`.
2. Lower `LLM_GPU_UTIL` to 0.80. On the api, set `DECOSA_DIARIZE_URL: http://diarize:8092` and
   `DECOSA_COLLECTIONS_AUDIO: "1"`.
3. `POST /collections/transcribe` then takes a 16 kHz mono 16-bit WAV
   (`ffmpeg -i in.m4a -ac 1 -ar 16000 -sample_fmt s16 out.wav`) and returns timed segments with a speech receipt.
4. Pass the segments to `/collections/check` as `segments`, with `speakers` to name S01 and S02.

The fit beside the LLM 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":"collections-call-qa"}' | jq -r .token)
curl -s $API/collections/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"sample_id":"tb1-showcase"}' > /tmp/cq.json
jq '{counts, retain_until, receipts: (.receipts|length), statuses: [.receipts[].status] | unique}' /tmp/cq.json
jq -r '.checklist[] | "\(.status)\t\(.answer)\t\(.at // "")\t\(.id)\t\([.calls[]?.id] | join(","))"' /tmp/cq.json
jq '{record}' /tmp/cq.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
```

In this sample, a fictional agency makes its first contact after 8 calls in 7 days. One call was at 8:10 a.m. Central to
a mobile with a Denver number. On the call the agent threatens the sheriff. Pass if:
- `false_misleading` is `flag` with a time;
- `freq_7in7` is `flag` with call `c8`;
- `calling_hours` is `flag` with call `c1`;
- every receipt has `"status": "attested"`;
- the record verifies (`ok: true`), and `retain_until` is `2029-03-08`.

Then try the call log on its own (no model: `freq_7in7` and `calling_hours` flag again), and a pasted transcript with your own log and consent:

```bash
curl -s $API/collections/log -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"tb1-showcase"}' | jq -r '.items[] | "\(.status)\t\(.id)"'
curl -s $API/collections/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
  "transcript": "[00:00] AGENT: This call is recorded. Is this Alex Doe?\n[00:04] CONSUMER: Yes.\n[00:06] AGENT: We will have you arrested if you do not pay today.",
  "call_log": {"account": {"kind": "consumer_debt", "debt_collector": true}, "consumer": {"time_zones": ["America/New_York"]},
               "calls": [{"id": "c1", "at": "2026-03-02T21:30:00-05:00", "outcome": "conversation"}], "recorded_call": "c1"},
  "consent": {"recorded_lawfully": true, "method": "all_parties_notified_on_call"}}' | jq -r '.checklist[] | "\(.status)\t\(.answer)\t\(.id)"'
```

Pass if `false_misleading` and `calling_hours` (21:30 in New York) are `flag`. Without `consent`, the API answers 400.

## 6. Point the app at the local API

- The base URL is `http://localhost:8445` (web app: `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`). Add other origins to
  `DECOSA_CORS_ORIGINS`.
- `POST /collections/check` returns JSON, or streams Server-Sent Events with `Accept: text/event-stream`.
  `GET /collections/info` lists the call-log fields and the check ids.
- Map your dialer export onto the call log:
  - one log per debt;
  - times with a UTC offset;
  - `outcome` is `conversation`, `voicemail`, `no_answer` or `not_connected` (busy, not in service);
  - every time zone the file points to goes in `consumer.time_zones`, or as `tz` on a number;
  - add letters and written notices as `events`.
- The server stores nothing. Keep each signed record (JSON) with the recording for three years. Anyone can re-check it
  with `POST /record/verify` against the key at `GET /attest/signing-key`.
- Keep the API on 127.0.0.1. For other users on the LAN, put a TLS reverse proxy with authentication in front and set
  `DECOSA_TRUSTED_PROXIES`.

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send prompts, which contain the call transcript, to the hosted Decosa
API. Never use it for
real calls; at most, use it for synthetic training material.

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