Check their discovery responses

# Assemble the Decosa discovery-response check on this machine

You are setting up a self-hosted review aid on this Linux machine, for a litigation team. It takes a set of written
discovery responses (interrogatory answers, responses to requests for production or admission; text, PDF or Word) and
returns:
- each numbered request and response, split in code;
- flags per response, each with a quote from the response at a character offset, what is missing, and the rule text it
  falls short of (Federal Rules of Civil Procedure, California Code of Civil Procedure or Texas Rules of Civil Procedure,
  from a rules pack of verbatim quotes read on 28 Sep 2026): objections with no specifics, incorporated general objections,
  no statement of whether anything is withheld, no production date, evasive or incomplete answers, admission responses
  that neither admit nor deny, privilege claims with no log;
- set-level flags: general objections, no verification under oath, no signature, late service (the deadline is computed
  from the date the requests were served and the service method); in California, the 45-day motion-to-compel date;
- for the other side's responses, a meet-and-confer letter written in code from the flags (downloadable as Word); for our
  own draft, a fix list that never removes an objection;
- a signed, hash-chained record of the document hash, the flags, their rule ids and every model receipt id.

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:**
- Discovery responses carry client facts and are often under a protective order. On this box nothing leaves the machine:
  the language model and the checks run here. Never point it at a hosted gateway while it holds client material.
- It is a review aid, not legal advice. It cites rule text, not case law, local rules or a judge's standing order; an
  attorney decides what to raise and edits and signs the letter.

## 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/discovery-deficiency.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 discovery-deficiency` (the api image carries the same bundle under /app/rehearsal/discovery-deficiency/;
   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 discovery-deficiency --bundle discovery-deficiency.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 set is deficient", "late service is flagged (due 17 Apr, served 20 Apr)", "the missing verification is flagged (the proof of service oath does not count)"). 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 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | none | `127.0.0.1:8445` |

Scanned PDFs (no text layer) need the document reader too: add the `parser` and `docreader` services exactly as in the
label-consistency-check or medical-chronology assemble prompts and set `DECOSA_DOCREADER_URL`. PDFs with a text layer,
Word files and pasted text need only the two services above.

## 1. Check the GPU, driver and Docker

1. `nvidia-smi`: one NVIDIA GPU with at least 32 GB (Qwen3.8-27B NVFP4 is about 20 GB of weights plus KV cache), driver
   580 or newer. NVFP4 needs Blackwell; on Hopper set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8` and `LLM_REVISION=main` (not
   measured). Smaller cards: tell me.
2. `docker --version`, `docker compose version`, `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the NVIDIA
   Container Toolkit is missing, install them from the official Docker and NVIDIA repositories after asking me.
3. About 40 GB of free disk.

## 2. Images and source

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 a pull
fails, clone `decosa-api` (access required) into `~/decosa-discovery/decosa-api`, check out the newest tag that contains
`decosa_api/verticals/discovery/` (`main` until one does), and build
`docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`.

## 3. The compose file

`~/decosa-discovery/.env`:

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_GPU_UTIL=0.55
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example LLP litigation support>"
```

`~/decosa-discovery/docker-compose.yml`:

```yaml
name: decosa-discovery
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: ["${DECOSA_GPU:-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", "--max-model-len", "32768",
              "--gpu-memory-utilization", "${LLM_GPU_UTIL}", "--max-num-seqs", "16", "--seed", "0", "--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 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy } }
    environment:
      DECOSA_LLM_ROUTE: direct                  # local model only; receipts are signed by this box's key ("attested")
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_LOCAL_SIGNING: "on"                # Ed25519 key created at /data/attest/ on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_DISCOVERY_SYNTHETIC_ONLY: "0"      # this box accepts client material
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "400000"        # per session; a 25-request set uses about 5,000 generated tokens
      DECOSA_SESSION_TTL_S: "28800"
    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/discovery/info', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, decosa-data: {} }
```

Use the named volumes exactly as written: the api image runs as an unprivileged user, and a root-owned host bind mount
makes it fail on `/data/keys.sqlite`. Run `docker compose up -d` and poll `docker compose ps` until both services are
healthy (the LLM takes 5-10 minutes the first time). Back up the signing key with
`docker compose cp api:/data/attest ./attest-backup`; keep it private and never print it.

## 4. Smoke test on the bundled invented cases

```bash
API=localhost:8445
curl -s $API/discovery/info | jq '{synthetic_only, rules_read_on, jurisdictions}'
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"discovery-deficiency"}' | jq -r .token)
curl -s $API/discovery/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"harbor-rfp"}' > /tmp/h.json
jq -r '.status, .counts.flags, (.flags[] | "\(.item // "set")\t\(.category)\t\(.rules[0].id)")' /tmp/h.json
jq '{record}' /tmp/h.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
curl -s $API/discovery/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample_id":"marlowe-rogs"}' | jq '.status, .motion_deadline.due, [.flags[] | select(.level=="set") | .category]'
```

Pass if: `synthetic_only` is `false`; the federal sample is `deficient`, with `untimely` and `general_objections` for the
set, `withholding_unstated` on requests 2, 3 and 10, and no flag on requests 1, 4 and 7; the record verifies; and the
California sample shows `missing_verification` and `untimely` with a motion deadline of `2026-06-09` and no
`outdated_standard` flag. Every receipt should be `attested`. Each sample takes a few seconds on an idle GPU; tell me what
you measure.

## 5. Check a real set

```bash
python3 - <<'PY' > req.json
import base64, json, pathlib
f = pathlib.Path("responses.pdf")                       # or .docx / .txt
print(json.dumps({"file_b64": base64.b64encode(f.read_bytes()).decode(), "filename": f.name,
                  "jurisdiction": "federal", "mode": "theirs",              # "ours" for our own draft before service
                  "requests_served_on": "2026-05-01", "requests_service": "email",
                  "privilege_log": "not_served",
                  "parties": {"responding_party": "Defendant Co.", "our_client": "Plaintiff LLC"}}))
PY
curl -s $API/discovery/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @req.json > out.json
jq -r .letter.text out.json > letter.txt
jq '{paragraphs: .letter.paragraphs}' out.json | curl -s $API/discovery/letter.docx -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @- -o letter.docx
```

Keep the request headings in the document ("REQUEST FOR PRODUCTION NO. 3:", "RESPONSE:", "INTERROGATORY NO. 3", "ANSWER:"):
responses are found by them. Limits: 400,000 characters, 250 responses, 12 MB per file.

## 6. Point tools at the local API

- Base URL `http://localhost:8445`; for a web app set `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`.
- `POST /discovery/check` returns JSON, or Server-Sent Events with `Accept: text/event-stream`. `GET /discovery/info` lists
  the categories, the rules pack sources and read date, and what it does not check.
- Keep the record with the matter file; anyone can re-check it 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 response text to the hosted Decosa API. Leave it off for client material.