Disposition a sanctions alert

# Assemble the Decosa sanctions alert disposition record on this machine

You are setting up decision support for compliance analysts who clear sanctions name-screening alerts. For one alert
(a customer or payment party against one sanctions list entry) it does four things:
- It compares every identifier in code: name with transliteration and name order, date of birth, nationality, place of
  birth, ID numbers, IMO, address, and the kind of party.
- It proposes true match, false positive or needs more information, by a named rule that follows OFAC FAQ 5.
- An open model gives an independent typed reading and writes a rationale. Code checks every sentence against the
  fields it cites.
- The analyst's decision is sealed in a record signed by this box's own key. The record pins the list version and links
  to the previous record.

Work step by step, show me each command before you run anything with `sudo`, and stop to ask if a check fails.

## 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/sanctions-disposition-record.zip (2 KB, 13 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 sanctions-disposition-record` (the api image carries the same bundle under /app/rehearsal/sanctions-disposition-record/;
   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 sanctions-disposition-record --bundle sanctions-disposition-record.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 code proposes a false positive", "by the disqualifier rule", "the date of birth is the disqualifier"). 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.

## 0. Ground rules and licences
- Model: Qwen3.8-27B (Apache-2.0), two short calls per alert: the typed second reading and the rationale. The
  comparison, the proposal, the rationale check and the record are decosa-api (AGPL-3.0-or-later) and run on CPU.
- Lists: the bundled snapshot comes from the public OFAC SDN and Consolidated lists (US government work), the EU
  consolidated list (reuse allowed with acknowledgement) and the UK Sanctions List (Crown copyright, Open Government
  Licence assumed). Keep every snapshot you use; each record names its snapshot by hash.
- Customer records stay on this machine. Bind every port to 127.0.0.1. The service stores nothing: the review and the
  record go back to the caller, and logs carry decisions and counts, never names, dates of birth or numbers.
- Be honest about what it is. It is not a screening engine, and it never makes a compliance determination. The analyst
  decides.

## 1. Check the machine
1. `nvidia-smi`: one GPU with at least 32 GB. Qwen3.8-27B NVFP4 needs about 20 GB of weights plus KV cache. We measured
   on an RTX PRO 6000 96 GB; an RTX 5090 32 GB should fit, but we have not run it. Driver 570 or newer. Blackwell cards
   run NVFP4; on older cards use `Qwen/Qwen3.8-27B-FP8`. Without a GPU, `POST /sanctions/analyze` (the code analysis and
   proposal) still works.
2. `docker --version` and `docker compose version`. If Docker or the NVIDIA container toolkit is missing, ask me first,
   then install them from the official Docker and NVIDIA repositories. Check with
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
3. Disk: about 30 GB free.

## 2. Images and weights
- API image: `${DECOSA_REGISTRY}/decosa-api:<tag>` (**publishing soon**). If the pull fails, build from source:
  `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required). Check out the newest release tag that
  contains `decosa_api/verticals/sanctions/` (use `main` until one does), then build `docker/api/Dockerfile`. The list
  snapshot (`decosa_api/verticals/sanctions/data/snapshot.json.gz`, 3.4 MB) is package data inside the image.
- Model: `vllm/vllm-openai:v0.29.0` with weights `nvidia/Qwen3.8-27B-NVFP4` (revision
  `482ca0f3832238542f8f5295dde86b5f22711d80`), or `Qwen/Qwen3.8-27B-FP8` on a card without NVFP4.

## 3. docker-compose.yml
Write this in `~/decosa/sanctions/`:

```yaml
services:
  llm:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "nvidia/Qwen3.8-27B-NVFP4", "--served-model-name", "qwen3.8-27b", "--max-model-len", "32768",
              "--enable-prefix-caching"]
    ports: ["127.0.0.1:8114:8000"]
    volumes: ["~/.cache/huggingface:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
    healthcheck: { test: ["CMD", "curl", "-fs", "http://localhost:8000/v1/models"], interval: 30s, retries: 20 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:<tag>
    ports: ["127.0.0.1:8445:8445"]
    environment:
      DECOSA_HOST: 0.0.0.0
      DECOSA_PORT: "8445"
      DECOSA_DATA_DIR: /data
      DECOSA_LLM_ROUTE: direct
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_SANCTIONS_SYNTHETIC_ONLY: "0"
      DECOSA_SANCTIONS_MAX_CONCURRENT: "4"
      DECOSA_BUDGET_LLM_TOKENS: "60000"
    volumes: ["decosa-data:/data"]
    depends_on: { llm: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8445/sanctions/lists', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
```

About these settings:
- `DECOSA_SANCTIONS_SYNTHETIC_ONLY: "0"` lets this box take real customer records. The hosted service refuses anything
  not marked `"synthetic": true`.
- The api keeps its state (keys, receipts, this box's signing key) in the named volume `decosa-data`, not in a host
  folder. The image runs as an unprivileged user (uid 10001). A host folder that Docker creates is owned by root, and
  the api then stops with `PermissionError`.

Start everything with `docker compose up -d`.

On the first start the api creates this box's Ed25519 key in the volume (`/data/attest/`, mode 0600). Back it up with
`docker compose cp api:/data/attest ./attest-backup`, keep that copy private, and never print it.

Every review, record and model call on the direct route is signed with that key (receipt status `attested`). That is
an attestation by me, the operator, not a proof of computation. Never set `DECOSA_LLM_ROUTE=gateway` on this box: that
sends customer data to the Decosa API.

## 4. Refresh the lists (daily, or when OFAC publishes)
```
docker compose exec api python -m decosa_api.verticals.sanctions.lists build --fetch /data/lists --out /data/snapshot-$(date +%F).json.gz
```
Then set `DECOSA_SANCTIONS_SNAPSHOT: /data/snapshot-<date>.json.gz` in the compose file and run
`docker compose up -d api`. The build prints the new version and each source file's sha256. Keep old snapshot files:
a record from last year names last year's version, and an examiner may ask for it. `GET /sanctions/lists` shows which
snapshot is loaded.

## 5. Smoke test
1. `curl -s localhost:8445/sanctions/lists | jq '{version, entries, sources: [.sources[] | {list, publish_date}]}'`
   should show four lists and about 32,000 entries (fewer or more after a refresh).
2. Get a token:
   `T=$(curl -s -XPOST localhost:8445/demo/session -H 'content-type: application/json' -d '{"vertical":"sanctions-disposition-record"}' | jq -r .token)`.
3. Take the sample and review it:
   - `curl -s localhost:8445/sanctions/samples | jq '.[] | select(.id=="dob-mismatch") | .body' > alert.json`
   - `curl -s -XPOST localhost:8445/sanctions/review -H "authorization: Bearer $T" -H 'content-type: application/json' -d @alert.json > review.json`

   Expect:
   - `.analysis.proposal` to show `false_positive` by rule `R-DISQ`, with F.dob `conflict` and F.nationality `match`;
   - two receipts with status `attested`;
   - at least one rationale sentence with status `grounded`.
4. Decide and verify:
   `jq '{review: .review, decision: "false_positive", analyst: {id: "setup-check"}}' review.json | curl -s -XPOST localhost:8445/sanctions/decide -H "authorization: Bearer $T" -H 'content-type: application/json' -d @- > decided.json`,
   then `jq '{record: .record}' decided.json | curl -s -XPOST localhost:8445/sanctions/verify -H 'content-type: application/json' -d @- | jq .ok`
   must print `true`. Change `.record.statement.decision` and verify again: it must print `false`.
5. Deciding against the proposal without `override_reason` must answer 422. So must clearing the `vessel-imo` sample
   (its IMO matches) without a `second_reviewer`.
6. Time the review and tell me what you measure. On our shared GPU through the gateway it took 3-15 s. The direct
   route on an idle card is usually faster.

## 6. Point your alert queue at it
- Set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in the site's `.env.local`, or call it from your case manager:
  `POST /sanctions/review` per alert, show the fields, the proposal and the rationale to the analyst, then
  `POST /sanctions/decide` with their decision.
- Store each record for 10 years in your own storage. Pass the previous record's `record_sha256` as
  `prev_record_sha256` so the log forms one chain.
- For QA or an examiner: `POST /sanctions/verify {records: [...]}` checks the chain, and `POST /sanctions/audit-sample`
  draws a reproducible, signed sample.
- Contract: `API_CONTRACT.md`, section "Sanctions alert disposition record".

Off by default. Joining serves other people's requests on this GPU. Never do it on a box that holds customer data. If I
ask for it, follow the provider guide at `/provide` on the site, and do not turn it on without my explicit yes.