Draft a tariff classification memo

# Assemble the Decosa tariff classification memo on this machine

You are setting up a self-hosted tariff classification memo on this Linux machine for a customs broker or an importer's
trade-compliance team. Given a product description, it searches public CBP rulings (CROSS, New York classification
rulings) and the HTS text, and returns:
- a proposed HTS heading, subheading and statistical number with the General Rules of Interpretation applied, up to two
  alternatives, and quotes from the rulings and the HTS, each quote checked word for word in code; or "needs a broker"
  with the reason (a missing fact, thin evidence, rulings that disagree, a quote that could not be verified);
- a memo in Markdown and a signed, hash-chained record naming the ruling-set version, the HTS release and the retrieval
  index hash.

Work step by step, show me each command before running anything that needs sudo, and stop if a check fails.

**Before anything else, remind me:**
- Product descriptions stay on this machine. The only outbound calls are the one-time downloads of the public ruling set
  (rulings.cbp.gov) and the HTS (hts.usitc.gov); after that it can run offline.
- This is a research and drafting aid. A licensed customs broker or the importer of record decides the classification,
  and only CBP issues binding rulings (19 CFR Part 177).

Repeat both points in your final summary.

## 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/tariff-classification.zip (2 KB, 9 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 tariff-classification` (the api image carries the same bundle under /app/rehearsal/tariff-classification/;
   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 tariff-classification --bundle tariff-classification.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 heater is proposed", "under heading 8516", "subheading 8516.29"). 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.

## What you are building

| service | image | model | port |
|---|---|---|---|
| `llm` | `${DECOSA_REGISTRY}/decosa-llm:0.1.0` (vLLM 0.29.0) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0 | internal 8000 |
| `retrieval` | built here from `services/retrieval` (PyTorch, CUDA) | `Qwen/Qwen3-Embedding-0.6B` + `Qwen/Qwen3-Reranker-4B`, Apache-2.0 (revisions pinned in `services/retrieval/models.py`) | internal 8499 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | none | `127.0.0.1:8445` |

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 64 GB (the LLM plus about 10 GB for the embedder and reranker),
   or two GPUs (LLM on one, retrieval on the other), driver 580 or newer. Blackwell uses the NVFP4 build (measured);
   Hopper: set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8` and `LLM_REVISION=main` (not measured).
2. Check `docker compose version` and `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the NVIDIA Container
   Toolkit is missing, install them from the official repositories, run `sudo nvidia-ctk runtime configure --runtime=docker`
   and restart Docker.
3. Confirm about 60 GB of free disk.

## 2. Get the source and the images

The images are **on request** while self-host is in early access: ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry (set it as `DECOSA_REGISTRY`), pull access and the compose file. Try `docker pull ${DECOSA_REGISTRY}/decosa-{llm,api}:0.1.0`; if that
fails, build from the decosa-api source (`docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`).
Clone decosa-api either way: the retrieval service is built from it. If neither works, stop and tell me.

Create `services/retrieval/Dockerfile` in the clone if it is not there:

```dockerfile
FROM pytorch/pytorch:2.9.0-cuda12.8-cudnn9-runtime
WORKDIR /app
COPY services/retrieval/ /app/
RUN pip install --no-cache-dir "transformers>=4.57,<6" "sentence-transformers>=5.1" "fastapi>=0.115" "uvicorn>=0.30" numpy
ENV RETRIEVAL_HOST=0.0.0.0 RETRIEVAL_PORT=8499 HF_HOME=/models
CMD ["python", "server.py"]
```

## 3. Write the compose file

`~/decosa-tariff/.env`:

```bash
DECOSA_TAG=0.1.0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_GPU_UTIL=0.70
DECOSA_SIGNER_NAME="<who signs the memo records, e.g. Example Customs Brokerage>"
```

`~/decosa-tariff/docker-compose.yml` (set `context` to the clone's path):

```yaml
name: decosa-tariff
x-health: &health { interval: 15s, timeout: 5s, retries: 5 }
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:${DECOSA_TAG}
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["0"], capabilities: [gpu] } ] } } }
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b", "--language-model-only",
              "--max-model-len", "65536", "--gpu-memory-utilization", "${LLM_GPU_UTIL}", "--kv-cache-dtype", "fp8_e4m3",
              "--seed", "0", "--enable-force-include-usage", "--host", "0.0.0.0", "--port", "8000"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)"], start_period: 900s }
  retrieval:
    build: { context: /path/to/decosa-api, dockerfile: services/retrieval/Dockerfile }
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["0"], capabilities: [gpu] } ] } } }
    restart: unless-stopped
    environment: { RETRIEVAL_EMBED: qwen3-emb-0.6b, RETRIEVAL_RERANK: qwen3-rr-4b }
    volumes: [retrieval-models:/models]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8499/health', timeout=4)"], start_period: 600s }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, retrieval: { condition: service_healthy } }
    environment:
      DECOSA_LLM_ROUTE: direct                 # local model; receipts signed by this box's key ("attested")
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_RETRIEVAL_URL: http://retrieval:8499
      DECOSA_TARIFF_DATA: /data/tariff          # the ruling set and the index cache live in the data volume
      DECOSA_TARIFF_WARM: "1"                   # build the ruling index at start-up
      DECOSA_LOCAL_SIGNING: "on"
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "200000"
    ports: ["127.0.0.1:8445:8445"]
    volumes: [decosa-data:/data]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/healthz', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, retrieval-models: {}, decosa-data: {} }
```

Use the named volumes exactly as written (a root-owned bind mount breaks `/data`). Run `docker compose up -d --build` and
poll `docker compose ps` until all three are healthy. The first start downloads about 20 GB of LLM weights and 9 GB of
retrieval weights.

## 4. Fetch the ruling set and the HTS

Without this step the API uses the small sample set bundled with it (fine for the smoke test, too small for real use).

```bash
docker compose exec api python scripts/tariff_fetch.py --out /data/tariff   # about 1 hour at 2 requests a second
docker compose restart api                                                   # the index builds at start-up (a few minutes)
curl -s localhost:8445/tariff/info | jq '{ruling_set, hts, index, retrieval}'
```

`ruling_set.count` should be about 2,000 and `retrieval.reachable` true. Re-run the fetch to refresh; the ruling-set hash
and the index hash in every memo then change, which is the point.

## 5. Smoke test

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"tariff-classification"}' | jq -r .token)
curl -s $API/tariff/classify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"sample_id":"wall-heater"}' > /tmp/memo.json
jq '{status, code: .proposal.display, reasons, quotes: [.proposal.ruling_citations[] | {ruling, ok}], rulings: [.rulings[].ruling]}' /tmp/memo.json
jq '{record}' /tmp/memo.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
curl -s $API/tariff/classify -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"vague-bag"}' | jq '{status, reasons}'
```

Pass if the heater memo proposes heading 8516 with at least one verified ruling quote, every receipt is `attested`, the
record verifies, and the vague bag comes back `needs_broker`.

## 6. Use it

- `POST /tariff/classify {"description": "...", "facts": "...", "title": "..."}` returns JSON, or Server-Sent Events with
  `Accept: text/event-stream`. `GET /tariff/info` lists the ruling set, the HTS release, the models and the limits.
- Save `memo_md` and `record` in the product's classification file. Anyone can re-check the record with
  `POST /record/verify` against the key at `GET /attest/signing-key`.
- Keep the API on 127.0.0.1; for other users, put a TLS reverse proxy with authentication in front.

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send prompts (your product description and the rulings) to the hosted Decosa
API. Leave it
off for unreleased products.

Finish with a summary: what is running, the health output, the ruling-set count and index hash, the smoke-test results,
and the reminders above.