Build a medical chronology

# Assemble Decosa medical chronology with page cites on this machine

You are setting up a self-hosted medical chronology for a law firm, an insurer's claims or underwriting team, or a
record-review vendor. It reads a packet of medical records (typed PDFs, scans and faxes, handwriting, lab tables) and
returns:
- a dated chronology of encounters, diagnoses, procedures, imaging, labs, medications and referrals, every line citing
  the file, page and box it came from (and the chunk and byte span in the retrieval index);
- copies from different providers merged; conflicting dates for the same procedure, gaps in treatment after the date of
  injury, and conditions documented before it flagged;
- a signed, hash-chained record of hashes: each file and its document-reader receipt, the index and layout hashes, every
  entry's cites and quote hashes, the judgments and every model receipt id. No record text.

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:**
- Medical records are protected health information (HIPAA). On this box nothing leaves the machine: the document reader,
  the retrieval models, the language model and the checks all run here. Never point it at a hosted gateway while it
- This is a paralegal and reviewer aid, not medical or legal advice. A person checks each line at its box; it does not
  judge causation, standard of care or damages.

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/medical-chronology.zip (943 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 medical-chronology` (the api image carries the same bundle under /app/rehearsal/medical-chronology/;
   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 medical-chronology --bundle medical-chronology.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: "every page was read and gave an answer", "the rotator cuff repair is listed and its conflicting date is flagged", "the 138-day gap in treatment is found"). 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 |
| `parser` | the same vLLM image | `PaddlePaddle/PaddleOCR-VL-1.6` @ `c5630abae1d940eafe0697512a0325494b02ab42`, Apache-2.0 | internal 8498 |
| `docreader` | built from `decosa-api/services/docreader` | Docling layout `docling-project/docling-layout-heron` @ `8f39ad3c0b4c58e9c2d2c84a38465abf757272d8` (MIT + Apache-2.0) | internal 8497 |
| `retrieval` | built from `decosa-api/services/retrieval` | `Qwen/Qwen3-Embedding-0.6B` @ `97b0c614be4d77ee51c0cef4e5f07c00f9eb65b3` + `Qwen/Qwen3-Reranker-4B` @ `22e683669bc0f0bd69640a1354a6d0aebcfeede5`, Apache-2.0 | internal 8499 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | none | `127.0.0.1:8445` |

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 48 GB: the model about 20 GB plus KV cache, the page parser
   and layout model about 6 GB, the retrieval models about 10 GB. Driver 580 or newer.
   - Blackwell (RTX PRO 6000, B200): the defaults below (NVFP4) are the measured setup.
   - Hopper (H100/H200) or a 48 GB card: `LLM_MODEL=Qwen/Qwen3.8-27B-FP8`, `LLM_REVISION=main`, `LLM_GPU_UTIL=0.62`;
     on 48 GB also `LLM_MAX_LEN=32768` and `PARSER_GPU_UTIL=0.10`. Not measured.
   - Under 48 GB: tell me, and use the BM25 option in step 3 (no `retrieval` service).
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, clone `decosa-api` into `~/decosa-chrono/decosa-api` and build the api with
`docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`. The `docreader` and `retrieval`
services are always built from the clone, so clone it either way. If neither works, stop and tell me.

## 3. Write the compose file

Create `~/decosa-chrono/.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.05
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example LLP records team>"
```

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

```yaml
name: decosa-chrono
x-gpu: &gpu { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
x-health: &health { interval: 15s, timeout: 5s, retries: 5 }
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", "${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", "--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 }
  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", "--trust-remote-code",
              "--max-model-len", "8192", "--gpu-memory-utilization", "${PARSER_GPU_UTIL}", "--max-num-seqs", "16",
              "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0", "--generation-config", "vllm", "--host", "0.0.0.0", "--port", "8498"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8498/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_URL: http://parser:8498/v1
      DOCREADER_PARSER_MODEL: PaddlePaddle/PaddleOCR-VL-1.6
      DOCLING_DEVICE: cuda
    volumes: [hf-cache:/models]
  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: *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 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, docreader: { condition: service_healthy }, retrieval: { 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_DOCREADER_URL: http://docreader:8497
      DECOSA_RETRIEVAL_URL: http://retrieval:8499
      DECOSA_CHRONO_SYNTHETIC_ONLY: "0"         # this box accepts real records
      DECOSA_DOCREADER_SYNTHETIC_ONLY: "0"
      DECOSA_CHRONO_MAX_PAGES: "600"            # pages per run (hosted demo: 40)
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "600000"        # per session; about 350 generated tokens a page
      DECOSA_SESSION_TTL_S: "28800"
      DECOSA_LLM_TIMEOUT_S: "300"
      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: {} }
```

**No room for the retrieval models?** Delete `retrieval` and its `depends_on` entry, drop `DECOSA_RETRIEVAL_URL`, and add
`DECOSA_CHRONO_RETRIEVAL: bm25` to the api: cites are still located in the index by keyword chunks; the conflict sweep
uses BM25 instead of the reranker.

Use the named volume `decosa-data` exactly as written: a root-owned host bind mount makes the API 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 to 10 minutes the first time). `curl -s localhost:8445/chronology/info | jq '{synthetic_only, blocks}'` should
show `synthetic_only: false`, the document reader reachable and retrieval `hybrid+rerank`.

## 4. Smoke test on the bundled synthetic packet

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"medical-chronology"}' | jq -r .token)
curl -s $API/chronology/run -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"whitlock"}' > /tmp/chrono.json
jq -r '.entries[] | "\(.date)\t\(.type)\t\(.label[0:50])\t\(.cites[0].cite)\t\(.flags|join(","))"' /tmp/chrono.json
jq '{counts, gaps: [.gaps[] | {from, to, days}], preexisting: [.preexisting[] | {date, label, related}], copies}' /tmp/chrono.json
jq '{record}' /tmp/chrono.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
```

Pass if: the procedure "right shoulder arthroscopic rotator cuff repair" on 2024-04-28 carries the flag `conflict` with
the other date 2024-05-05; there is one gap from 2024-05-12 to 2024-09-27; the 2022-11-15 low back pain diagnosis is
flagged before the injury and judged related; the pages F1 p4 and F5 p2 are listed as copies; every entry has at least one
cite with a box; and the record verifies. About 20 to 40 entries is normal; the planted answer key has 32 required events.

## 5. Run a real packet

```bash
python3 - <<'PY' > packet.json
import base64, json, pathlib
files = [{"name": p.name, "file_b64": base64.b64encode(p.read_bytes()).decode()} for p in sorted(pathlib.Path("records").iterdir())
         if p.suffix.lower() in (".pdf", ".png", ".jpg", ".jpeg", ".tif", ".tiff")]
print(json.dumps({"files": files, "incident_date": "2024-03-08", "claimed": ["low back", "right shoulder"], "gap_days": 60}))
PY
curl -s $API/chronology/run -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @packet.json > run.json
jq -r .markdown run.json > chronology.md
jq .record run.json > chronology-record.json
```

Limits per run: 12 files of 12 MB, and `DECOSA_CHRONO_MAX_PAGES` pages in all. Measured on our server's shared gateway:
about 5 to 7 s a page end to end; a private GPU runs faster. For a very large packet, split it by provider and run
each, or raise the limits. Check `complete` and `incomplete_pages` in every result.

## 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 /chronology/run` returns JSON, or Server-Sent Events with `Accept: text/event-stream`. `POST /docreader/read` and
  `POST /retrieval/index-scans` are the two building blocks on their own.
- Keep the chronology and the record with the case 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, and handle the box
  under your HIPAA security program (access control, audit logs, encryption at rest).

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send page text and images to the hosted Decosa
API. Leave it off: this box holds PHI.

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