Redact a public-records release

# Decosa Public-records desk: use the hosted API

You are wiring Decosa's public-records desk into this project. It takes a FOIA or state public-records request and the
agency's records, and returns a search scope, a responsiveness call per record, proposed redactions (each with its
exemption, category and a reason that does not repeat the withheld words), a release PDF with the withheld text removed
and checked, an index of withheld information, a response letter draft and a signed record. Each 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`.
- The hosted API is for the fictional and public sample sets and for testing your integration. Unredacted records carry
  personal data: for real requests use the self-host prompt instead. Never send real records here.
- It proposes; the records officer decides. Show every redaction, exemption and letter as a draft, never as a decision.

## 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": "foia-desk"}` 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 15 records). Over a limit: HTTP 429 with `Retry-After`.
3. One review at a time per demo token (409 otherwise).

## Endpoints
- `POST /foia/scope` (token) `{"request": {"text", "id"?, "received"?, "requester"?, "agency"?}}` → `{scope, text, receipt}`:
  `scope = {summary, subjects, keywords, custodians, date_from, date_to, record_types, examples, exclusions, clarify}`.
  Show it to the officer to edit. `record_types` is a limit only when the officer sets it; `examples` never excludes anything.
- `POST /foia/review` (token). Body:
  `{"request": {...}, "scope"?: {...}, "documents": [{"id", "date"?, "from"?, "to"?: [...], "cc"?: [...], "subject"?, "custodian"?, "body"}], "people"?: {"attorneys": [{"name", "email"}], "client_domains": ["agency.gov"]}, "agency_domains"?: ["agency.gov"], "jurisdiction"?: "federal" | "ca-cpra" | {"name", "items": [{"code", "label", "categories"}]}, "names"?: "private" | "none", "stream"?: true}`
  or `{"sample": "coastal-permits", "use_sample_scope": true}` to run a sample set.
  - Limits: 25 records per request, 20,000 characters each, 150,000 in all; the request text up to 6,000 characters.
  - With `"stream": true` (or `Accept: text/event-stream`) it streams `scope`, `ready`, a `receipt` after each model call,
    a `document` event per record (replace by `id`), then `consistency`, `release`, `index`, `letter`, `report`, `done`
    and `budget`. With `"stream": false`: one JSON object `{run_id, scope, documents, exemptions, consistency, release, index, letter, report, export, budget}`.
  - Each record: `{id, text, disposition: release_in_full|release_in_part|withhold_in_full|not_responsive, responsive: {answer, p, by, reason}, redactions: [{id, start, end, category, exemption, source, what, reason}], kept, withheld?, privilege?, review_reasons, copy_of?}`.
    Offsets point into `text` (header lines, a blank line, the body). A record with `review_reasons` needs the officer first.
  - `release.integrity.ok` must be true before any release goes out.
- `POST /foia/runs/{run_id}/decisions` `{"decisions": [{"redaction", "decision": "accept"|"reject"|"change", "category"?, "reviewer"}, {"doc", "decision": "confirm"|"change", "disposition"?, "reviewer"}, {"add": {"doc", "text", "category"}, "reviewer"}]}`:
  the officer's calls; the release is rebuilt and checked again.
- `GET /foia/runs/{run_id}/export?format=pdf` (the release), `csv` (index), `letter`, `md` (review memo), `record` (signed), `ledger` (signed, with the decisions).
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.
- `GET /foia/info`, `GET /foia/samples`, `GET /foia/samples/{id}`, `GET /attest/signing-key` (no token).

## Example: answer a request and save the release (Python, `pip install httpx`)
```python
import httpx, os, pathlib
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
s = httpx.get(f"{API}/foia/samples/coastal-permits").json()          # your own request has the same shape
scope = httpx.post(f"{API}/foia/scope", headers=H, json={"request": s["request"]}, timeout=120).json()["scope"]
# ... let the officer edit `scope` here ...
r = httpx.post(f"{API}/foia/review", headers=H, timeout=900,
               json={"request": s["request"], "scope": scope, "documents": s["documents"], "people": s["people"],
                     "agency_domains": s["agency_domains"], "jurisdiction": s["jurisdiction"], "stream": False})
r.raise_for_status()
run = r.json()
assert run["release"]["integrity"]["ok"]
for d in run["documents"]:
    print(d["id"], d["disposition"], [(x["id"], x["exemption"]) for x in d["redactions"]], d["review_reasons"])
pathlib.Path("release.pdf").write_bytes(httpx.get(f"{API}{run['export']['pdf']}", headers=H).content)
```

## Honest limits
- The calls are drafts from an open model and code rules. On labelled synthetic records they miss some personal details
  (most often part of a medical detail) and some responsive records; see the measured rates on the Stack tab.
- The release is typeset from the records' text: it does not keep the original layout, and it cannot read scanned
  images. Exemption lists: federal FOIA and California CPRA are checked; a custom list is yours to check.

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 Public-records desk: run it yourself (containers)

You are setting up the Decosa public-records desk on this machine, so unredacted agency records never leave it. It
scopes a FOIA or state public-records request, finds the responsive records, proposes redactions with exemptions and
reasons, builds a release PDF with the withheld text removed and checked, drafts the index and the letter, and signs a
record. 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/foia-desk.zip (4 KB, 11 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 foia-desk` (the api image carries the same bundle under /app/rehearsal/foia-desk/;
   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 foia-desk --bundle foia-desk.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 resident's comment (CP-002) is released in part", "her phone number and email address are redacted under (b)(6)", "both Social Security numbers on the dive roster (CP-007) are redacted"). 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). 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`,
   `DECOSA_FOIA_MAX_DOCS=200`, use a named volume for `/data`, and bind every port to 127.0.0.1. Nothing in this use
   case needs the internet after the weights are downloaded.
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>/foia/info` shows `"method": "logprobs (one call per question)"` and the
   `federal` and `ca-cpra` exemption lists; `GET /attest/signing-key` shows this box's public key. Show me the key: it is
   what others pin to verify my records.
5. Smoke test: get a token with `POST /demo/session {"vertical":"foia-desk"}` and run
   `POST /foia/review {"sample": "coastal-permits", "use_sample_scope": true, "stream": false}`. Expect CP-010 not
   responsive (dated before the range), CP-004 and CP-005 withheld in full under (b)(5), the resident's details in
   CP-002 redacted under (b)(6) and `release.integrity.ok` true. Download `export?format=pdf` and confirm that copying the
   text out of it gives none of the withheld words. Then `POST /record/verify` with `report.record`: `ok` must be true.
6. Report back: the public key and key id, the totals, the integrity result and how long the run took.

Off, and keep it off on a box that holds unredacted records: joining serves other people's requests on this GPU.
If I ask for it later, on a separate machine, 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/foia-desk-mac.md instead.