Check a lay summary's numbers

# Decosa EU trial lay summary: use the hosted API

You are wiring Decosa's EU trial lay summary into this project. Given a trial with results posted on ClinicalTrials.gov
it drafts the lay summary the EU Clinical Trials Regulation requires (Regulation (EU) No 536/2014, Article 37(4); the
content is set by Annex V), or checks a draft someone wrote. Every number is traced in code to a results cell, or to
arithmetic on the cells a sentence cites; comparisons are checked against the table; a result the posted analysis says
could be chance must say so; serious side effects and deaths must be given for every group; promotional and softening
words are flagged; every narrative sentence goes through a grounding judge. It returns Annex V coverage, the reading
grade, a Markdown review file and a record signed by the server, with a signed receipt for every model call. Use only
what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- It never says a summary is compliant or meets Annex V. Do not add that claim in your UI. The sponsor's medical writer
  reviews every flag, fills the `[Sponsor to add: ...]` gaps (EU trial number, contact details, follow-up plans,
  participants per country) and approves.
- The hosted API is for results that are already public. Unpublished results belong on a self-hosted box.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "eu-trial-lay-summary"}` returns
   `{"token", "expires_at", "budget"}`. Sessions per IP are limited; over a limit you get HTTP 429 with `Retry-After`.
3. A draft needs about 14,800 generated tokens of budget, a check with grounding about 6,400 (402 otherwise). One run at
   a time per demo token (409 while one is going).

## Endpoints
- `POST /laysummary/sources` (no token, no model): `{"nct_id": "NCT04880850"}` (or `{"sample_id": ...}` or
  `{"study": <a ClinicalTrials.gov API v2 study record>}`) → the registry facts `F1..`, results cells `C1..` (table, row,
  group, value, and for counts the group size), tables `T1..`, protocol sentences `P1..` and the posted analyses, with
  whether each difference could be chance. Only the NCT number leaves for ClinicalTrials.gov.
- `POST /laysummary/draft` (token): `{"nct_id": "...", "inputs": {"eu_ct_number": "2025-521150-42-00", "sponsor_contact":
  "...", "follow_up": "...", "participants_by_country": "..."}, "stream": true}`. English only. Takes about two minutes
  (six section drafts, one repair pass, a grounding call per sentence).
- `POST /laysummary/check`: `{"draft": "<Markdown with headings>", "nct_id": "...", "language": "en", "grounding": true}`.
  Source ids in brackets (`[C12, F3]`) are optional; an uncited number is looked up in its own section's tables. With
  `"grounding": false` it makes no model call and needs no token. `language` is en, de, fr, it, nl or es: numbers
  (decimal comma) and readability work in all six; word lists, comparisons and hedges are English only.
- Answer (JSON, or SSE with `Accept: text/event-stream` / `"stream": true`: `ready`, `section`, `receipt`, `draft`,
  `sentence`, `coverage`, `readability`, `doc_flag`, `warning`, `result`, `budget`, `done`): `{mode, draft, reader_copy,
  sentences: [{i, section, text, cites, status: ok | check | fail | needs_input, numbers: [{text, status: ok | ok_uncited
  | elsewhere | mismatch | unsupported, reason, trace: {op, cells, value, why}, nearest}], flags: [{kind, severity, why}],
  grounding}], counts, coverage (Annex V's ten elements: covered | partial | missing | needs_input), readability,
  doc_flags, first_pass, repairs, review_md, record, record_check, receipts}`.
- `POST /laysummary/translate` (token): `{"draft": "<the finished English summary>", "nct_id": "..." (or "sample_id"),
  "languages": ["de", "fr", "pl"], "stream": true}` → Member-State versions (up to six of de, fr, es, it, nl, pl, pt, cs):
  each sentence translated by Hy-MT2-7B, its numbers checked against the English sentence and traced to the results
  cells in that language: `{languages: [{lang, draft, sentences: [{en, text, cites, status, preservation, numbers}], counts,
  readability}], record}`. Machine translations: a native speaker and a lay reader read each version before submission.
- `POST /record/verify` (no token): the `record` → `{ok, checks, summary}`.
- `GET /laysummary/info`, `GET /laysummary/samples` (no token): Annex V verbatim with the date it was read, the
  deadline rule, the checks, limits, and three sample trials.

## Build it like this
Show each sentence with its status, and make every number clickable to its `trace.why` (the results cell). Show `fail`
sentences before `check` ones, and never hide `[Sponsor to add]` gaps. Store the `record` next to the approved summary.

## Errors
400 bad input (the message names the field), 401/403 token, 402 budget, 409 a run already going on this demo token,
413 body over 5 MB, 429 busy (`Retry-After`), 502 ClinicalTrials.gov could not be reached or has no such study.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa EU trial lay summary: run it yourself (containers)

You are setting up the Decosa EU trial lay summary on this machine, so unpublished trial results never leave it. It drafts
or checks the lay summary for Annex V of Regulation (EU) No 536/2014: every number traced in code to a results cell,
comparisons and "could be chance" checked against the posted analysis, side effects checked for every group, each claim
through a grounding judge, and a signed record of every check. It never says a summary is compliant; the sponsor's
medical writer approves.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## 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/eu-trial-lay-summary.zip (17 KB, 9 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 eu-trial-lay-summary` (the api image carries the same bundle under /app/rehearsal/eu-trial-lay-summary/;
   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 eu-trial-lay-summary --bundle eu-trial-lay-summary.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 results are read into cells with no model call, and the icodec serious side-effect count is cell C114 (22 of 291)", "the correct glargine sentence is traced to its cell and passes", "the grounding judge supports it"). 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.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). Install the NVIDIA container toolkit and check
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM, with prefix caching on) and the `api` service. For the `api`
   service set `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b` and bind
   every port to 127.0.0.1. For results that are not public, also set `DECOSA_LAYSUMMARY_FETCH=0` (then send the study
   record as `study`; nothing calls ClinicalTrials.gov). Never set the gateway route for unpublished results.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
   downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/laysummary/info` lists Annex V's ten elements and the date they were read;
   `GET /attest/signing-key` shows this box's public key. Show me the key: QC and auditors pin it to verify records.
5. Smoke test: `POST /laysummary/check` with `{"sample_id": "icodec-weekly-insulin", "grounding": false, "draft": "## What
   side effects were seen\n23 out of 291 people (8%) in the Insulin Icodec group had a serious side effect. [C114]\nNo one
   in the trial died.\n"}` (no token needed without grounding). Expect the first sentence `fail` with a number `mismatch`
   whose nearest cell is C114 (22 of 291), and a `contradicts_table` document flag. Send the `record` to
   `POST /record/verify`: `ok` must be true. Then get a token (`POST /demo/session {"vertical":"eu-trial-lay-summary"}`)
   and run `POST /laysummary/draft {"sample_id": "ruxolitinib-covid"}`: expect ten sections, every number traced, and
   "could be due to chance" in the results.
6. Member-State versions (optional): add the language pack's translation model to the compose file (vLLM serving
   `tencent/Hy-MT2-7B` at revision 9b0eb4e8f001def3e5ff6469a0ac96fdb39ec223 with `--enforce-eager`, about 18 GB) and set
   `DECOSA_LANG_MT_URL=http://mt:8000/v1` on the api. Then `POST /laysummary/translate {"sample_id": "ruxolitinib-covid",
   "draft": <the draft>, "languages": ["de"]}` must return German sentences with their numbers traced.
7. Report back: the public key, the smoke results, and how long the draft took.

Off by default. Joining as a provider serves other people's requests on this GPU; never do it on a box that holds
unpublished results. If I ask for it later, follow the Provide page instead of improvising.

No NVIDIA GPU? Parts of this tool also run on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/eu-trial-lay-summary-mac.md instead.