Compare safety sections across labels

# Assemble the Decosa label consistency check on this machine

You are setting up a self-hosted labelling QC aid on this Linux machine, for a regulatory affairs or labelling team. It
takes the label documents for one medicine (the company core data sheet (CCDS), the US Prescribing Information, the EU
SmPC and package leaflet in several languages, and carton text or a carton scan) and returns:
- the sections of each document aligned (indications, dosing, contraindications, warnings, adverse reactions, storage,
  strengths);
- every difference with a quote from each document at a character offset: a dose, interval, strength or temperature that
  disagrees, a missing warning or contraindication, a translation that dropped a negation or changed a number, an SmPC
  heading that is not the QRD template's;
- a triage per difference (likely error, likely deliberate, unclear) using the regional conventions it knows and our
  deviation log;
- a signed, hash-chained record of the document hashes, flags, triage and every model receipt id.

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:**
- Unapproved labelling and variation drafts are confidential. On this box nothing leaves the machine: the language model,
  the translation model, the document reader and the checks all run here. Never point it at a hosted gateway while it
  holds real labelling.
- It is a QC aid, not a regulatory decision. The triage is a model judgment; regulatory affairs decides what is deliberate
  and records approved deviations. It compares seven sections only (not interactions, pregnancy, pharmacology or artwork
  layout), and QRD headings in English, German and French only.

## 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/label-consistency-check.zip (8 KB, 7 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 label-consistency-check` (the api image carries the same bundle under /app/rehearsal/label-consistency-check/;
   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 label-consistency-check --bundle label-consistency-check.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 set is reported as drifted", "the US PI against the CCDS has at least two likely errors in its warnings (the 6-month interval and the missing warning)", "the dropped German negation is flagged in the translation"). 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 |
| `mt` | `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1` | `tencent/Hy-MT2-7B` @ `9b0eb4e8f001def3e5ff6469a0ac96fdb39ec223`, Apache-2.0 | internal 8000 |
| `parser` | same vLLM image | `PaddlePaddle/PaddleOCR-VL-1.6` @ `c5630abae1d940eafe0697512a0325494b02ab42`, Apache-2.0 | internal 8000 |
| `docreader` | built from `decosa-api/services/docreader` | Docling 2.130 (MIT) with `docling-project/docling-layout-heron` @ `8f39ad3c0b4c58e9c2d2c84a38465abf757272d8` (Apache-2.0) | internal 8497 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | none | `127.0.0.1:8445` |

Only text documents (no scans or PDFs)? Leave out `parser` and `docreader` and their `depends_on` entry, and drop
`DECOSA_DOCREADER_URL`. Only English documents? You can leave out `mt` too and send `"meaning": false`; numbers and
negations in translations are still checked in code.

## 1. Check the GPU, driver and Docker

1. `nvidia-smi`: one NVIDIA GPU with at least 64 GB (Qwen3.8-27B NVFP4 about 20 GB plus KV cache, Hy-MT2-7B about 18 GB
   at `--gpu-memory-utilization 0.18`, the document reader about 6 GB), driver 580 or newer. NVFP4 needs Blackwell; on
   Hopper set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8` and `LLM_REVISION=main` (not measured). Smaller cards: tell me.
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 Docker and NVIDIA repositories after asking me.
3. About 80 GB of free disk.

## 2. Images and source

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, clone `decosa-api` (access required) into `~/decosa-label/decosa-api`, check out the newest tag that contains
`decosa_api/verticals/labelcheck/` (`main` until one does), and build `docker build -f docker/api/Dockerfile -t
${DECOSA_REGISTRY}/decosa-api:0.1.0 .`. The `docreader` service is always built from the clone.

## 3. The compose file

`~/decosa-label/.env`:

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_GPU_UTIL=0.55
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Pharma labelling QC>"
```

`~/decosa-label/docker-compose.yml`:

```yaml
name: decosa-label
x-health: &health { interval: 15s, timeout: 5s, retries: 5 }
x-gpu: &gpu { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:${DECOSA_TAG}
    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", "32768",
              "--gpu-memory-utilization", "${LLM_GPU_UTIL}", "--limit-mm-per-prompt", '{"image":4}', "--max-num-seqs", "16",
              "--seed", "0", "--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 }
  mt:
    image: vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1
    deploy: *gpu
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    # vLLM 0.29 serves Hy-MT2 through its Transformers backend; CUDA-graph capture fails there, hence --enforce-eager
    command: ["tencent/Hy-MT2-7B", "--revision", "9b0eb4e8f001def3e5ff6469a0ac96fdb39ec223", "--served-model-name", "hy-mt2-7b",
              "--max-model-len", "8192", "--gpu-memory-utilization", "0.18", "--max-num-seqs", "16", "--enforce-eager",
              "--generation-config", "vllm", "--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: 600s }
  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", "--served-model-name", "PaddlePaddle/PaddleOCR-VL-1.6",
              "--trust-remote-code", "--max-model-len", "8192", "--gpu-memory-utilization", "0.04", "--max-num-seqs", "16",
              "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0", "--generation-config", "vllm", "--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: 600s }
  docreader:
    build: { context: ./decosa-api/services/docreader }
    deploy: *gpu
    restart: unless-stopped
    depends_on: { parser: { condition: service_healthy } }
    environment: { DOCREADER_PARSER: paddle-openai, DOCREADER_PARSER_URL: "http://parser:8000/v1", DOCREADER_PARSER_MODEL: PaddlePaddle/PaddleOCR-VL-1.6 }
    volumes: [hf-cache:/models]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8497/health', timeout=4)"], start_period: 300s }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, mt: { condition: service_healthy }, docreader: { 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_LANG_MT_URL: http://mt:8000/v1
      DECOSA_LANG_MT_MODEL: hy-mt2-7b
      DECOSA_DOCREADER_URL: http://docreader:8497
      DECOSA_LOCAL_SIGNING: "on"                # Ed25519 key created at /data/attest/ on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_LABELCHECK_SYNTHETIC_ONLY: "0"     # this box accepts real labelling
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "400000"        # per session; a seven-document set uses about 15,000 generated tokens
      DECOSA_SESSION_TTL_S: "28800"
    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/label/info', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, decosa-data: {} }
```

Use the named volumes exactly as written: the api image runs as an unprivileged user, and a root-owned host bind mount
makes it fail on `/data/keys.sqlite`. Run `docker compose up -d --build` and poll `docker compose ps` until every service
is healthy (the LLM takes 5-10 minutes the first time). Back up the signing key with
`docker compose cp api:/data/attest ./attest-backup`; keep it private and never print it.

## 4. Smoke test on the bundled invented medicine

```bash
API=localhost:8445
curl -s $API/label/info | jq '{synthetic_only, qrd: .qrd_headings["4.3"]}'
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"label-consistency-check"}' | jq -r .token)
curl -s $API/label/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"norvexa-quick"}' > /tmp/q.json
jq -r '.status, (.flags[] | "\(.judgement.label)\t\(.section)\t\(.what)")' /tmp/q.json
jq '{record}' /tmp/q.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
curl -s $API/label/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"norvexa-drift"}' | jq '.status, .counts'
curl -s $API/label/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"norvexa-scan"}' | jq '.status, .warnings, [.flags[].other.text]'
```

Pass if: `synthetic_only` is `false` and the 4.3 heading is `Gegenanzeigen` in German; the quick sample is `drift` with a
likely error in warnings (the liver-test interval, 6 months against 3) and none in indications (that difference is in
the sample's deviation log); the record verifies; the full set is `drift` with at least five likely errors; and the scan
flags the carton's 25°C against the SmPC's 30°C. Every receipt should be `attested`. The quick sample takes about 30 s
and the full set a few minutes; tell me what you measure.

## 5. Check our own labels

```bash
python3 - <<'PY' > req.json
import json, pathlib
docs = [("ccds", "en", "ccds.txt"), ("us_pi", "en", "uspi.txt"), ("eu_smpc", "en", "smpc_en.txt"), ("eu_smpc", "de", "smpc_de.txt")]
print(json.dumps({"documents": [{"role": r, "lang": l, "text": pathlib.Path(f).read_text()} for r, l, f in docs],
                  "declared_deviations": [l.strip() for l in pathlib.Path("deviations.txt").read_text().splitlines() if l.strip()]}))
PY
curl -s $API/label/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @req.json > qc.json
jq .record qc.json > label-check-record.json
```

Keep section headings in the text (4.3 Contraindications, 5 WARNINGS AND PRECAUTIONS): sections are found by the QRD and
21 CFR 201.57 numbers, and by heading words for a CCDS. Export Word or PDF labels to text first; a carton can go as a scan
(`{"role": "carton", "file_b64": "...", "media_type": "image/png"}`, up to 2 files per run). Limits: 8 documents, 30,000
characters each. Put each known, approved regional difference on one line of the deviation log.

## 6. Point tools at the local API

- Base URL `http://localhost:8445`; for a web app set `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`.
- `POST /label/check` returns JSON, or Server-Sent Events with `Accept: text/event-stream`. `GET /label/info` lists the
  sources, the regional conventions, the QRD headings and what it does not check.
- Keep the record with the change-control file; 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, put a TLS reverse proxy with authentication in front.

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send label text to the hosted Decosa API. Leave it off for real labelling.