See what studies found for a supplement

# Decosa See what studies found for a supplement: use the hosted API

You are wiring Decosa's evidence table into this project. Given a supplement and an outcome, it searches PubMed for
trials, meta-analyses and systematic reviews and returns one row per study: PMID and PubMed link, design, n, population,
direction, the finding, a quote of at most 15 words that code found word for word in the abstract, and whether the
finding held up against its own abstract. A published rubric in code grades the body of evidence, and the studies it
left out come back with why. Each model call has its own signed receipt and the table ends in a signed record. 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 reports what studies found. It is not medical advice and gives no doses: a dosing or "should I take" question is
  refused with 400. Never show a row as a recommendation, and link every row to its PubMed record.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool's 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": "what-studies-found"}` returns
   `{"token", "expires_at", "budget"}`. Over a limit: HTTP 429 with `Retry-After`.
3. One table at a time per demo token (409 otherwise).

## Endpoints
- `GET /evidence/table/info` (no token): the rubric's full text and version, the wording guard, limits and data flow.
- `GET /evidence/table/samples` (no token): `{samples: [{id, title, supplement, outcome, summary}]}`.
- `POST /evidence/table` (token or key). Body: `{"supplement": "probiotics", "outcome": "antibiotic-associated diarrhea",
  "max_studies"?: 8, "designs"?: "trials" | "primary", "published_before"?: 2020, "stream"?: true}` or `{"sample_id": "probiotics-antibiotic-diarrhea"}`.
  - Limits: supplement up to 80 characters, outcome up to 120, 1 to 12 studies (8 by default).
  - `"designs": "primary"` reads primary trials only; the default also reads meta-analyses and systematic reviews.
  - With `"stream": true` it streams SSE: `search` (the PubMed term and hit counts), `candidates` (the studies picked),
    `receipt` after each model call (with its `pmid`), `row` per study read, `grade`, `result`, `budget`, `done`.
  - Without streaming: one JSON object `{supplement, outcome, headline, grade: {direction, label, claim, band, consistency,
    counts, reasons, rubric, harm_signal, safety}, rows: [...], excluded: [{pmid, title, why, harm}], search, steps,
    record, record_check, usage, ...}`. `grade.label` is the verdict to show: `Improves`, `Worsens`, `No clear difference`,
    `Unclear: evidence too weak to tell`, `Mixed results` or `Too few studies to tell`. "No clear difference" and
    "Unclear" are different verdicts: keep them apart. `grade.harm_signal` is `{level: reported | possible | none, label,
    studies: [{pmid, year, design, level, quote, counted}]}`: when the level is not `none`, show its `label`
    ("Possible harm: check the studies") with the studies, whatever the verdict says.
  - Each row: `{pmid, url, title, journal, year, design, n, n_in_abstract, k_studies, population, comparator, direction,
    finding, quote, quote_check, grounding: {verdict, ...}, harm: {level, quote, flag}, net_label, abstract_sha256,
    receipt_ids}`. `direction` is `improved`, `no_difference`, `worsened` or `mixed`; `net_label` is the row's verdict
    in words; `harm.flag` `possible` means the abstract reports a worse result that did not become the row's verdict. `grounding.verdict` is `supported` or `partial`; unsupported and
    contradicted rows are dropped and listed in `excluded`.
  - Errors: 400 missing or long fields, or a dosing or advice question; 502 PubMed did not answer; 402, 409, 429.
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.

## Example: build a table and print it (Python, `pip install httpx`)
```python
import httpx, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
r = httpx.post(f"{API}/evidence/table", headers=H, timeout=180,
               json={"supplement": "magnesium", "outcome": "sleep quality", "stream": False})
r.raise_for_status()
t = r.json()
for row in t["rows"]:
    print(row["url"], row["design"], row["n"], row["direction"], row["finding"], row["grounding"]["verdict"])
print(t["grade"]["label"], "| band:", t["grade"]["band"], t["grade"]["reasons"])
if t["grade"]["harm_signal"]["level"] != "none":
    print(t["grade"]["harm_signal"]["label"], [s["pmid"] for s in t["grade"]["harm_signal"]["studies"]])
for x in t["excluded"]:
    print("left out:", x["pmid"], x["why"])
```

## Honest limits
- It reads abstracts only, so results reported only in the full paper are missed.
- The one-line verdict is not a systematic review. On held-out pairs it matched the published review's in most tables,
  not all: show the rows, and treat the band as "our rubric over the abstracts found", not as a GRADE rating. The
  numbers are on the tool's page and in its eval.
- The rubric puts the newest Cochrane review first even when it studied a narrower group than the question. When reviews
  of different groups disagree the verdict is "Mixed results": show each row's `population`.
- The harm flag errs toward flagging. It is a prompt to read the study, not a finding of harm.
- The same search can give a different verdict on another run.
- A meta-analysis and trials it already pooled can both appear as rows.

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 See what studies found for a supplement: run it yourself (containers)

You are setting up Decosa's evidence table on this machine, so the tables, the model and the signing key are your own.
Given a supplement and an outcome it searches PubMed, reads each abstract with an open model, checks each quote and
finding against the abstract, grades the body of evidence with a published rubric in code and signs a record with this
box's own key. The only outside call is to NCBI's public PubMed service (the search words and PMIDs). 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/what-studies-found.zip (1 KB, 14 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 what-studies-found` (the api image carries the same bundle under /app/rehearsal/what-studies-found/;
   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 what-studies-found --bundle what-studies-found.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: "probiotics and antibiotic-associated diarrhea: the studies found a better result with probiotics", "the verdict is a benefit claim, labelled Improves", "a systematic review decides the verdict"). 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. GPU and Docker: `nvidia-smi` must show a card with at least 32 GB (Qwen3.8-27B NVFP4 is about 20 GB of weights plus
   KV cache). If `docker compose version` fails or the NVIDIA container toolkit is missing, install them from the official
   Docker and NVIDIA instructions after asking me.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `api` and `llm` services, and the `retrieval` service if there is room for about 8 GB more (the
   reranker). Keep the named `/data` volume and bind every port to 127.0.0.1.
3. Settings on the `api` service: `DECOSA_NCBI_TOOL` (a name for your deployment) and `DECOSA_NCBI_EMAIL` (a contact
   address I give you), so NCBI can reach you; optionally `NCBI_API_KEY` for higher limits. Without the reranker set
   `DECOSA_STUDIES_RERANK=off` (the engine then keeps PubMed's order and says so).
4. Pull and start: `docker compose pull && docker compose up -d`.
5. Check: `GET /evidence/table/info` shows `rubric.version` and `model.route`; `GET /attest/signing-key` shows this box's
   public key. Show me the key: it is what others pin to verify my tables.
6. Smoke test: get a token with `POST /demo/session {"vertical":"what-studies-found"}` and run
   `POST /evidence/table {"sample_id": "probiotics-antibiotic-diarrhea", "stream": false}`. Expect rows whose `url` starts with
   `https://pubmed.ncbi.nlm.nih.gov/`, quotes of at most 15 words with `quote_check: "found"`, a `grade` with `reasons`,
   and `record_check.ok: true`. Then `POST /record/verify` with the `record`: `ok` must be true; change one row's
   `direction` in it and verify again: it must fail. Finally `POST /evidence/table {"supplement": "probiotics",
   "outcome": "what dose should I take"}` must return 400.
7. Report back: the public key and key id, the sample's band and reasons, and how long the table took.