Check the other side's brief

# Assemble "Check the other side's brief" on this machine

You are setting up a checker for the OTHER side's court filings. It takes their filing (a PDF, a Word file or text) and
returns findings for a reply: which cited cases, statutes and rules the public sources do not have (with the search
trail), which quotations differ from the opinion, which holdings the opinion does not contain, what the file hides
(text the page does not show, tiny or off-page text, invisible characters, metadata, comments) and whether any of that
hidden text is aimed at AI tools. It ends with a Word findings memo and a record signed by this box's own key. 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/check-their-brief.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 check-their-brief` (the api image carries the same bundle under /app/rehearsal/check-their-brief/;
   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 check-their-brief --bundle check-their-brief.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 PDF is read and its hidden-text scan runs", "the scan finds the hidden texts before any model runs", "the decision is: findings"). 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) as the judge for holdings and for the injection check. Everything else is CPU code:
  decosa-api (AGPL-3.0-or-later), eyecite and reporters-db (BSD-2-Clause) for citations, pypdfium2 (Apache-2.0 or BSD-3-Clause,
  PDFium BSD-3-Clause) to render pages and read the text layer, pypdf (BSD-3-Clause) for metadata and annotations,
  pdfplumber (MIT), and poppler's `pdftotext` (GPL-2.0, run as a separate program).
- A filed brief is a public record; your notes about it, and any paper that is served but not filed, are not. Bind every
  port to 127.0.0.1. Filings and results stay in memory for one hour and are never written to disk or logs. The only
  thing written to disk is a cache of public-source answers (the citation asked, the public opinion text), never the
  filing.
- Decide with me which mode to run:
  - **Offline** (`DECOSA_PREFLIGHT_OFFLINE=1`): nothing leaves this machine. Authorities are checked only against
    opinion texts I send with the request, or a local mirror of the Caselaw Access Project (step 2).
  - **Online lookups** (default): only citations (volume, reporter, page; a case name when a cite is not found; statute
    sections) go to static.case.law, courtlistener.com, uscode.house.gov, ecfr.gov and law.cornell.edu. A free
    CourtListener account token (`DECOSA_PREFLIGHT_COURTLISTENER_TOKEN`) avoids its anonymous rate limit.
- Be honest about what it does: "not found" means the public sources searched do not have it, not that the case is
  invented. It is not legal advice; a lawyer verifies every finding before using it.

## 1. Check the machine
1. `nvidia-smi`: one GPU with at least 32 GB for the judge (Qwen3.8-27B NVFP4 is about 20 GB of weights plus KV cache).
   Driver 570 or newer; Blackwell runs NVFP4, older cards use `Qwen/Qwen3.8-27B-FP8`.
2. No GPU? Set `DECOSA_THEIRBRIEF_JUDGE=off`: the hidden-text scan, existence, reporter and quotation checks and the
   pattern layer of the injection check still run; holdings are "not checked".
3. `docker --version` and `docker compose version`. If Docker or the NVIDIA container toolkit is missing, install them
   from the official repositories after asking me, then run
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
4. Disk: about 30 GB free for the model and images.

## 2. Images and weights
- `${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 tag that contains
  `decosa_api/verticals/theirbrief/` (`main` until one does), and build `docker/api/Dockerfile` (it installs the
  `theirbrief` extra and poppler). Without Docker: `pip install ".[theirbrief]"` and `apt install poppler-utils`.
- `vllm/vllm-openai:v0.29.0` for the judge; weights `nvidia/Qwen3.8-27B-NVFP4`.
- Scanned filings (no text layer) need the document reader service; without it, set `DECOSA_THEIRBRIEF_OCR=off` and
  scans are refused with a clear message. Born-digital PDFs and Word files need nothing extra.
- Optional offline case-law mirror: copy the reporters you need from `https://static.case.law/` (`ReportersMetadata.json`
  at the root, and for each `<reporter>/<volume>/` its `CasesMetadata.json` and `html/`) into `~/decosa/cap/`, serve it
  read-only (`python -m http.server 8480 --bind 127.0.0.1 -d ~/decosa/cap`) and set `DECOSA_PREFLIGHT_CAP_BASE`.

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

```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_BUDGET_LLM_TOKENS: "60000"         # per demo session; about 170 generated tokens per holding checked
      DECOSA_THEIRBRIEF_OCR: "off"              # on only if the document reader service runs next to it
      DECOSA_THEIRBRIEF_MAX_CONCURRENT: "2"
      # DECOSA_PREFLIGHT_OFFLINE: "1"           # uncomment to send nothing outside (see step 0)
      # DECOSA_PREFLIGHT_COURTLISTENER_TOKEN: "" # a free CourtListener token, if you have one
    volumes: ["decosa-data:/data"]
    depends_on: { llm: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8445/theirbrief/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
```

State (keys, receipts, this box's signing key, the public-source cache) lives in the named volume `decosa-data`, not a
host folder: the image runs as uid 10001, and a root-owned host folder stops the api with a PermissionError on
`/data/keys.sqlite`. Start everything: `docker compose up -d`. The signing key is created on first start under
`/data/attest/` (mode 0600): back it up, never print it. Records are signed with it: an attestation by you, the operator.

## 4. Smoke test
1. `curl -s localhost:8445/theirbrief/info | jq '{checks, offline, judge, ocr}'` lists the six checks and the mode.
2. Token: `T=$(curl -s -XPOST localhost:8445/demo/session -H 'content-type: application/json' -d '{"vertical":"check-their-brief"}' | jq -r .token)`.
3. Run the fictional sample (a PDF shipped with the api):
   `curl -s -XPOST localhost:8445/theirbrief/check -H "authorization: Bearer $T" -H 'content-type: application/json' -d '{"sample_id":"demo-opposition","stream":false}' > run.json`.
   Expect `decision: "findings"` and, among the problems: three hidden instructions aimed at AI tools (white text on
   page 1, 1-point text on page 2, the Keywords property), Hollis v. Brentwood School District at 925 F.3d 1339 not
   found (that page is inside J.D. v. Azar), the T.L.O. quotation with "any" for "strict", the Redding holding, and the
   student's full birth date. With lookups off, case items are "unverified" unless you pass opinions in `authorities`.
4. Your own file: `curl -s -XPOST 'localhost:8445/theirbrief/parse?name=opp.pdf' -H "authorization: Bearer $T" -H 'content-type: application/pdf' --data-binary @opp.pdf | jq '{upload_id, chars, hidden: .hidden.findings | length}'`,
   then check it with `{"upload_id": "..."}`.
5. Stream with `-H 'accept: text/event-stream' -N` and `"stream": true`: `ready`, `stage`, `item`, a `receipt` after
   each model call, then `report`, `done` and `budget`.
6. `jq '{record: .report.record}' run.json | curl -s -XPOST localhost:8445/record/verify -H 'content-type: application/json' -d @-`
   must say `ok: true`. Change one item's status in the record and verify again: it must fail and name that entry.
7. The Word memo: `curl -s localhost:8445/theirbrief/runs/<run_id>/export?format=docx -H "authorization: Bearer $T" -o findings.docx`.
8. Time it and tell me. On our shared RTX PRO 6000 the fictional sample took about 30 s with lookups on (28 Sep 2026);
   most of the time is lookups and judge calls.

## 5. Point the app at the local API
Set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in the site's `.env.local`, or call `POST /theirbrief/check` from
your document system when an opposing filing arrives and keep the Word memo and the signed record in the matter file.
Contract: `API_CONTRACT.md`, section "Check their brief".

Off by default. It serves other people's requests on this GPU; never on a box that holds client work. Do not enable it
without my explicit yes; the guide is at `/provide` on the site.