Check CSR numbers against tables

# Assemble the Decosa CSR number-to-table verifier on this machine

You are setting up a self-hosted number check for clinical study reports on this Linux machine, for a medical writing or
regulatory operations team at a sponsor or CRO. It reads a CSR (the narrative of sections 10 to 12 with its in-text
tables and TLFs; as text and table rows, or as a PDF or scan) and returns:
- every number in the narrative with the table cell it reports (table, row, column, value), checked in code at the
  printed decimals, with percentages, differences, totals and relative reductions recomputed;
- flags for numbers that don't match their cell, numbers with no source and derived numbers that don't compute, each
  with what the table gives and the likely slip (the other arm's value, a value from an earlier data cut, transposed
  digits, rounding, a wrong denominator), and in-text tables compared with their source TLF;
- a Markdown QC report and a signed, hash-chained record of every number's cell and verdict and every 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:**
- Unblinded study results are confidential. On this box nothing leaves the machine: the language model, the retrieval
  models, the document reader and the checks all run here. Never point it at a hosted gateway while it holds a real report.
- This is a medical-writing QC aid, not a validated (GxP) system and not a regulatory submission tool. The medical writer
  and the QC reviewer decide what to change; the TLFs are the biostatistician's to validate. An unflagged number is not
  proven right.

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/csr-number-verifier.zip (15 KB, 15 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 csr-number-verifier` (the api image carries the same bundle under /app/rehearsal/csr-number-verifier/;
   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 csr-number-verifier --bundle csr-number-verifier.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 transposed mean age (75.5 for 57.5) is flagged", "the rounding slip in disposition (71.8% for 71.9%) is flagged", "the wrong N in the analysis sets (313 for 317) 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 |
| `retrieval` | built from `decosa-api/services/retrieval` | `Qwen/Qwen3-Embedding-0.6B` @ `97b0c614be4d77ee51c0cef4e5f07c00f9eb65b3` + `Qwen/Qwen3-Reranker-4B` @ `22e683669bc0f0bd69640a1354a6d0aebcfeede5`, Apache-2.0 | internal 8499 |
| `parser` | `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1` | `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 need text and table rows (no PDFs)? Leave out `parser` and `docreader` and their `depends_on` entry, and drop
`DECOSA_DOCREADER_URL`.

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 64 GB (the model about 20 GB plus KV cache, the retrieval models
   about 10 GB, the document reader about 6 GB) and driver 580 or newer.
   - Blackwell (RTX PRO 6000, B200): use the defaults below (NVFP4). This is the measured setup.
   - Hopper (H100/H200): set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8`, `LLM_REVISION=main` and `LLM_GPU_UTIL=0.65`. Not measured.
   - Smaller cards: tell me. Use keyword search (step 3) and leave the document reader out or put it on a second card
     (`DECOSA_GPU` per service).
   - `PARSER_GPU_UTIL` is a share of the whole card: 0.04 is about 3.8 GiB of a 96 GB card; raise it on a smaller one.
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, run
   `sudo nvidia-ctk runtime configure --runtime=docker` and restart Docker.
3. Confirm about 90 GB of free disk.

## 2. Get the images and the 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, build from source once `decosa-api` is published: clone it into `~/decosa-csr/decosa-api`, run
`docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`, and `docker compose build llm` from
its compose file. If neither works, stop and tell me. The `retrieval` and `docreader` services are always built from the
clone, so clone it either way.

## 3. Write the compose file

Create `~/decosa-csr/.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.62
PARSER_GPU_UTIL=0.04
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Pharma medical writing QC>"
```

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

```yaml
name: decosa-csr
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 }
  retrieval:
    build:
      context: ./decosa-api/services/retrieval
      dockerfile_inline: |
        FROM python:3.12-slim
        WORKDIR /app
        COPY requirements.txt .
        RUN pip install --no-cache-dir -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu130
        COPY *.py .
        CMD ["python", "server.py"]
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    restart: unless-stopped
    environment:
      RETRIEVAL_HOST: 0.0.0.0
      RETRIEVAL_PORT: "8499"
      RETRIEVAL_EMBED: qwen3-emb-0.6b
      RETRIEVAL_RERANK: qwen3-rr-4b
      HF_HOME: /root/.cache/huggingface
    volumes: [hf-cache:/root/.cache/huggingface]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8499/health', timeout=4)"], start_period: 600s }
  parser:
    image: vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1
    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: ["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", "${PARSER_GPU_UTIL:-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: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [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 }, retrieval: { 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_LOCAL_SIGNING: "on"                # Ed25519 key created at /data/attest/ed25519.pem on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_RETRIEVAL_URL: http://retrieval:8499
      DECOSA_DOCREADER_URL: http://docreader:8497
      DECOSA_CSR_SYNTHETIC_ONLY: "0"            # this box accepts real reports
      DECOSA_DOCREADER_SYNTHETIC_ONLY: "0"
      DECOSA_CSR_MAX_PAGES: "40"
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "400000"        # per session; a 12-page report uses a few thousand generated tokens
      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: {} }
```

The retrieval, parser and docreader services download their models into the shared `hf-cache` volume on first start.

**No room for the retrieval models?** Delete the `retrieval` service and its `depends_on` entry, drop
`DECOSA_RETRIEVAL_URL`, and add `DECOSA_CSR_RETRIEVAL: bm25` to the api. Tables are then found by keyword search only
(explicit "Table 14.2.1" references in the text are always used first); the comparisons and the record are unchanged.

Use the named volumes exactly as written: a root-owned host bind mount makes the API fail on `/data/keys.sqlite`.

Run `docker compose up -d --build`, then poll `docker compose ps` until every service is healthy (the LLM takes 5-10
minutes the first time). `curl -s localhost:8445/csr/info | jq '{synthetic_only, blocks}'` should show
`synthetic_only: false`, and `curl -s localhost:8445/docreader/info | jq .service` should show the reader reachable.

## 4. Smoke test on the bundled fictional report

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"csr-number-verifier"}' | jq -r .token)
curl -s $API/csr/verify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"zenavotide-301"}' > /tmp/csr.json
jq -r '.results[] | select(.status=="mismatch" or .status=="derived_wrong" or .status=="untraceable") | "\(.section)\t\(.text)\t\(.status)\t\(.expected)\t\(.slip.detail // "")"' /tmp/csr.json
jq '.table_mismatches | length' /tmp/csr.json
jq '{record}' /tmp/csr.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
curl -s $API/csr/verify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"zenavotide-301-clean"}' | jq '.counts'
curl -s $API/csr/verify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"zenavotide-301-scan"}' | jq '.counts, .read.pages'
```

Pass if the seeded report gives flags in sections 10.1, 11.1, 11.2, 11.4.3, 12.2.1 and 12.3.1 (the six seeded errors:
rounding, a wrong N, transposed digits, the other arm's value, a stale interim value and a wrong denominator) and at
least one in-text table mismatch (Table 11-1 against 14.2.1); every receipt is `attested`; the record verifies; the clean
report gives no flags; and the scan is read (12 pages) with the same kinds of flags.

## 5. Check a real report

As a PDF (born-digital or scanned, up to 40 pages per run; split a longer report by section):

```bash
python3 - <<'PY' > req.json
import base64, json, pathlib
print(json.dumps({"file_b64": base64.b64encode(pathlib.Path("csr.pdf").read_bytes()).decode(), "sections": ["10", "11", "12"]}))
PY
curl -s $API/csr/verify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @req.json > qc.json
jq -r .markdown qc.json > number-qc.md
jq .record qc.json > number-qc-record.json
```

Or as text and rows, which is more exact than reading a PDF: `{"csr": {"narrative": "<sections 10-12 as text, headings like
11.4.1 Primary Efficacy>", "tables": [{"id": "14.2.1", "title": "...", "rows": [[...], ...]}], "previous_tables": [...the
interim TLFs, optional...]}}`. Export TLF outputs (RTF, SAS) to PDF or rows first; RTF is not read directly.

## 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 /csr/verify` returns JSON, or Server-Sent Events with `Accept: text/event-stream`. `GET /csr/info` lists what it
  checks and what it does not.
- Keep the QC report and the record with the document's QC file. Anyone can re-check the record 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 the report's sentences and tables to the hosted Decosa
API. Leave it off for real reports.

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