Pre-check promo claims for MLR

# Decosa promotional-claims pre-check: use the hosted API

You are wiring Decosa's promotional-claims pre-check into this project. It takes a promotional piece for a prescription
drug, a medical device or a dietary supplement (the text) and its reference pack (the label or prescribing information,
the cited studies, spec sheets, and optionally the approved claims matrix). It checks every sentence: is it supported by
the references (with the span), is it off-label, is a comparison backed by head-to-head data, is a superlative backed,
and for supplements, is it a disease claim. It then checks the whole piece for fair balance, the boxed warning and the
DSHEA disclaimer, and returns an MLR pre-review packet in Markdown plus a packet signed by the server. Every model call
has its own signed receipt. 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`.
- This is a pre-check that speeds up MLR review. It does not approve anything and does not replace the committee.
  Say so wherever you show results.
- The hosted API is for public labels and synthetic or already published copy. Unpublished study data and pre-launch
  pieces 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": "promo-claims-check"}` returns `{"token", "expires_at", "budget"}`.
   a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz); each session has a token allowance (its `budget`). Over a limit: HTTP 429 with `Retry-After`.
3. A check needs about 330 generated tokens per claim sentence plus 250 (402 otherwise), so a demo session covers two
   or three pieces of 15 claims. One check at a time per demo token.

## Endpoints
- `POST /promo/check` (token). Body:
  ```json
  {"piece": {"text": "...", "title": "..."},
   "product": {"type": "drug|device|supplement", "name": "...", "indication": "optional; read from the label otherwise"},
   "references": [{"title": "...", "kind": "label|study|other", "text": "..."}],
   "claims_matrix": [{"id": "M1", "claim": "..."}]}
  ```
  - Limits: piece up to 8,000 characters and 40 claim sentences; up to 10 references and 200,000 characters in total;
    up to 60 matrix entries. Send text, not URLs or PDFs: extract the text yourself.
  - The approved indication comes from `product.indication`, else from the INDICATIONS AND USAGE (or Indications for
    Use) section of a `kind: "label"` reference. With neither, the off-label check does not run (`no_indication`).
  - JSON by default: `{status: "issues"|"checks"|"clean", counts, indication, indication_source, claims: [{i, text, role,
    support, confidence, evidence: [{span, source, start, end, role, quote}], findings, support_reason, review_reason,
    comparative, superlative, off_label, claim_kind, matrix, h2h, receipt_ids}], piece: {findings, fair_balance},
    receipts, packet, packet_md, budget, note}`.
  - With `Accept: text/event-stream` (or `"stream": true`) it streams `ready`, `receipt` events and one `claim` event
    per sentence (not in text order), then `piece`, `packet`, `budget`, `done`.
- `POST /promo/verify` (no token) `{"packet": {...}, "text"?: "...", "references"?: [...], "packet_md"?: "..."}` →
  `{valid_signature, signed_by_this_server, status, piece_matches?, references_match?, packet_md_matches?}`.
- `GET /promo/info` (the finding codes, severities and limits), `GET /promo/samples`, `GET /attest/signing-key`.

Finding codes. Issues (likely violations): `unsupported`, `contradicted`, `off_label`, `comparative_unbacked`,
`superlative_unbacked`, `disease_claim`, `not_checked`, `fair_balance_missing`, `fair_balance_weak`,
`boxed_warning_missing`, `dshea_disclaimer_missing`. Checks (for the reviewer): `overstated`, `not_in_matrix`,
`pi_reference_missing`, `no_indication`.

## Example: pre-check a piece before it goes into the review queue (Python, `pip install httpx`)
```python
import httpx, os, pathlib
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
body = {"piece": {"text": piece_text, "title": "Spring HCP email"},
        "product": {"type": "drug", "name": "Metformin hydrochloride tablets"},
        "references": [{"title": "Prescribing information", "kind": "label", "text": label_text}],
        "claims_matrix": [{"id": "M1", "claim": "..."}]}
r = httpx.post(f"{API}/promo/check", json=body, headers=H, timeout=600)
r.raise_for_status()
res = r.json()
pathlib.Path(f"{res['packet']['id']}.md").write_text(res["packet_md"])      # attach this to the review job
pathlib.Path(f"{res['packet']['id']}.json").write_text(r.text)              # keep the signed packet with the piece
for c in res["claims"]:
    if c["findings"]:
        print(c["findings"], c["text"], "--", c["support_reason"])
```

## Verify a packet yourself (`pip install cryptography`)
```python
import hashlib, json, urllib.request
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
pub = json.load(urllib.request.urlopen("https://api.decosa.ai/attest/signing-key"))["pubkey"]
pk = res["packet"]
assert pk["signer"] == pub
body = {k: v for k, v in pk.items() if k != "sig"}
msg = pk["v"].encode() + b"\n" + json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
Ed25519PublicKey.from_public_bytes(bytes.fromhex(pub)).verify(bytes.fromhex(pk["sig"]), msg)
assert hashlib.sha256(piece_text.encode()).hexdigest() == pk["piece"]["sha256"]
assert hashlib.sha256(res["packet_md"].encode()).hexdigest() == pk["packet_md_sha256"]
```
The signed packet holds hashes, offsets, finding codes and receipt ids, never the copy. It embeds the signed grounding
report for the support verdicts. Each receipt id resolves at `GET https://api.decosa.ai/receipts/{id}`.

## Honest limits
- Text only: type size, placement and contrast (visual prominence) are not assessed. Fair balance is measured as risk
  text against benefit text plus whether the boxed warning and contraindications are conveyed.
- Findings come from a language model. On our planted-violation eval it caught most planted problems and raised some
  issues on compliant sentences; see the numbers on the Stack tab. A person reviews every finding.
- Not legal or regulatory advice.

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 promotional-claims pre-check: run it yourself (containers)

You are setting up the Decosa promotional-claims pre-check on this machine, so pre-launch pieces and unpublished study
data never leave it. It checks every claim of a promotional piece against its reference pack and returns a signed MLR
pre-review packet. Nothing is sent to Decosa's hosted API.

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/promo-claims-check.zip (5 KB, 10 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 promo-claims-check` (the api image carries the same bundle under /app/rehearsal/promo-claims-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 promo-claims-check --bundle promo-claims-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 piece comes back with issues", "at least two disease claims are flagged", "the planted 'cure insomnia' sentence is flagged as a disease claim"). 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. Never set the gateway route on this box: it would send the copy to the Decosa API.
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>/promo/info` lists the finding codes and limits; `GET /attest/signing-key`
   shows this box's public key. Show me the key: it is what reviewers pin to verify my packets.
5. Smoke test: get a token with `POST /demo/session {"vertical":"promo-claims-check"}`, fetch `GET /promo/samples`, and
   send the `metformin-planted` sample (piece, product, references, claims_matrix) to `POST /promo/check`. Expect
   `status: "issues"`, `off_label` on the weight-loss and heart-protection sentences, a comparison finding on "better
   than any other diabetes pill", and `fair_balance_missing` at piece level. Then send `metformin-compliant`: expect no
   issue-level findings. Then `POST /promo/verify` with the packet and the packet_md: `valid_signature`,
   `signed_by_this_server` and `packet_md_matches` must all be true.
6. Report back: the public key and key id, both statuses, the findings and how long each check took.

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

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/promo-claims-check-mac.md instead.