Catch AI answers your sources don't back

# Decosa Grounding check: use the hosted API

You are wiring Decosa's grounding check into this project. It takes a text (an answer, an email, a FAQ, a summary) and
the sources it is supposed to rest on, and says for each sentence whether the sources support it: `supported`,
`partial`, `unsupported` or `contradicted`, with the source span it rests on and a confidence. A claims gate turns that
into pass, flag or block before the text ships. Every verdict is one model call with its own signed receipt, and the
check ends with a report signed by the server. 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`.
- "Supported by the sources" is not "true": the check reads only the sources you send. Say so wherever you show results.

## 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": "grounding"}` 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`) (about 120 sentences). Over a limit: HTTP 429 with `Retry-After`.
3. A check needs about 160 generated tokens of budget per sentence (402 otherwise). One check at a time per demo token.

## Endpoints
- `POST /grounding/check` (token). Body:
  `{"text": "...", "sources": [{"title": "...", "text": "..."}], "question"?: "...", "gate"?: {"block_on": ["contradicted", "unsupported"], "flag_on": ["partial"], "min_confidence": 0}}`
  - Limits: text up to 8,000 characters and 40 sentences; up to 10 sources and 60,000 characters in total. Send text, not URLs:
    fetch pages yourself.
  - JSON by default: `{decision, counts, blocking, flagged, clean_text, sentences: [{i, text, verdict, certainty, confidence, evidence: [{span, source, start, end, role, quote}], reason, receipt_ids}], receipts, report, budget, note}`.
  - With `Accept: text/event-stream` (or `"stream": true`) it streams: `ready` (sentence and span offsets), then a `receipt`
    and a `sentence` event per sentence as each finishes (not in text order), then `report`, `budget`, `done`.
- `POST /grounding/gate` (token): same body, always JSON → `{decision: "pass"|"flag"|"block", issues: [{i, text, verdict, confidence, reason, evidence, action}], clean_text, counts, report, receipts}`.
  The default policy blocks `contradicted` and `unsupported`, flags `partial`, and blocks any sentence that could not be judged.
- `POST /grounding/verify` (no token) `{"report": {...}, "text"?: "...", "sources"?: [...]}` → `{valid_signature, signed_by_this_server, text_matches?, sources_match?}`.
- `GET /grounding/info`, `GET /grounding/samples`, `GET /attest/signing-key` (no token).

Offsets (`start`, `end`) are Python string indices (Unicode code points) into the text or source exactly as sent. In
JavaScript, index with `Array.from(text)` if the text can contain emoji or other characters outside the BMP.

## Example: block an outbound email that says things the profile does not (Python, `pip install httpx`)
```python
import httpx, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
body = {"text": email_draft, "sources": [{"title": "Candidate profile", "text": profile}, {"title": "Role brief", "text": role}]}
r = httpx.post(f"{API}/grounding/gate", json=body, headers=H, timeout=180)
r.raise_for_status()
g = r.json()
if g["decision"] == "block":
    for issue in g["issues"]:
        print(issue["action"], issue["verdict"], issue["confidence"], issue["text"], "--", issue["reason"])
    raise SystemExit("not sending: fix the flagged sentences")
```

## Verify a report 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"]
assert report["signer"] == pub
body = {k: v for k, v in report.items() if k != "sig"}
msg = report["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(report["sig"]), msg)
assert hashlib.sha256(email_draft.encode()).hexdigest() == report["text"]["sha256"]
```
The report carries hashes and offsets, never the text, so you can store it next to the sent email as evidence of the check.
Each id in `report["receipts"]` resolves at `GET https://api.decosa.ai/receipts/{id}` to the signed model receipt for that verdict.

## Honest limits
- On the RAGTruth benchmark the judge finds most sentences that human annotators marked as unsupported, and also flags
  sentences they left alone: see the numbers on the Stack tab before you let the gate block without a human look.
- Confidence is the measured agreement of that verdict and certainty with human labels on a dev set, not a guarantee.

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

You are setting up the Decosa grounding check on this machine, so unpublished drafts and their sources never leave it.
It checks each sentence of a text against the sources I give it and signs a report. 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/grounding.zip (2 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 grounding` (the api image carries the same bundle under /app/rehearsal/grounding/;
   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 grounding --bundle grounding.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 claims gate blocks the answer", "every claim sentence got a verdict (none errored)", "the battery-life sentence is contradicted or not backed"). 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). For the GPU judge, also 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) 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. Without a GPU, set `DECOSA_GROUNDING_NLI=cross-encoder/nli-deberta-v3-base` instead and use `"judge": "nli"`
   in requests (CPU only, lower accuracy, no model receipts).
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>/grounding/info` lists the verdicts and the judge; `GET /attest/signing-key`
   shows this box's public key. Show me the key: it is what others pin to verify my reports.
5. Smoke test: get a token with `POST /demo/session {"vertical":"grounding"}`, fetch `GET /grounding/samples`, and send the
   `support-answer` sample to `POST /grounding/gate`. Expect `decision: "block"` with the battery-life and 240 V sentences
   as `contradicted`, and the reset steps as `supported`. Then `POST /grounding/verify` with the report: `valid_signature`
   and `signed_by_this_server` must both be true.
6. Report back: the public key and key id, the smoke-test decision, the verdicts and how long the 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
confidential drafts. 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/grounding-mac.md instead.