Fill a form from your own papers

# Assemble Decosa "Fill it, I'll press Submit" on this machine

You are setting up a self-hosted form filler on this Linux machine. It:
- reads my documents (text, PDFs; with the optional document reader also scans and phone photos) into numbered lines;
- opens a web form in a throwaway browser and fills each field my documents answer, checking in code that every typed
  value is in the line the model points at; everything else is left for me;
- never types passwords, card, bank, routing, IBAN, Social Security, tax, passport, licence, national ID or Medicare
  numbers, signatures or declarations;
- holds, in the browser's network layer, every request that would send the form (POST, form navigation, fetch, beacon,
  websocket), so it stops before Submit; flags text on the page that tries to instruct an AI;
- writes a signed, replayable record of the run and, when I approve, a signed approval naming me.

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:**
- It fills only what my documents say and never advises what to answer. I review every field and press Submit myself.
- No immigration forms, court filings or customs entries.
- Only use it on sites and accounts that are mine, at my own request; some sites' terms forbid automation.
- Forms with health or account data stay on this machine: the model route stays local (`direct`).

Repeat these 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/fill-and-stop.zip (3 KB, 12 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 fill-and-stop` (the api image carries the same bundle under /app/rehearsal/fill-and-stop/;
   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 fill-and-stop --bundle fill-and-stop.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 policy number is typed, with its source line", "at least 15 fields are filled from the two documents", "the date of birth, in no document, is left for the person"). 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, `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1`) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0, with its vision tower | internal 8000 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` built **with `WITH_BROWSER=1`** (Chromium BSD-3-Clause, Playwright Apache-2.0) | none | `127.0.0.1:8445` |

Optional, for scans and a translated review: the document reader (`services/docreader`, PaddleOCR-VL-1.6 Apache-2.0 +
Docling MIT, about 6 GB of GPU) and the language pack's Hy-MT2-7B (Apache-2.0, about 18 GB). Without them, text and
born-digital PDFs work and the review is in English.

## 1. Check the GPU, driver and Docker

1. `nvidia-smi`: one NVIDIA GPU with at least 64 GB (measured on an RTX PRO 6000 96 GB), driver 580 or newer.
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 repositories (`sudo nvidia-ctk runtime configure --runtime=docker`).
3. About 70 GB of free disk.

## 2. Get 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.
1. `docker pull ${DECOSA_REGISTRY}/decosa-llm:0.1.0`.
2. Build the api image with the browser from the `decosa-api` source:
   `docker build -f docker/api/Dockerfile --build-arg WITH_BROWSER=1 -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`
   Without `WITH_BROWSER=1` there is no Chromium and fill runs fail.
3. If none of this works, stop and tell me.

## 3. Write the compose file

`~/decosa-fill/.env` (mode 0600):

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
DECOSA_SIGNER_NAME="<who signs the records, e.g. Maria Lopez's laptop>"
DECOSA_ADMIN_SECRET=<a long random string>
# sites the API itself may open (the CLI in step 6 needs none of this)
FILL_ALLOWED_HOSTS=
```

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

```yaml
name: decosa-fill
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", "65536", "--gpu-memory-utilization", "0.80", "--max-num-seqs", "16",
              "--kv-cache-dtype", "fp8_e4m3", "--limit-mm-per-prompt", '{"image":4,"video":0}', "--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 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy } }
    shm_size: 1gb                              # Chromium needs more than Docker's 64 MB default
    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"
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_ADMIN_SECRET: ${DECOSA_ADMIN_SECRET}
      DECOSA_FILL_ALLOWED_HOSTS: ${FILL_ALLOWED_HOSTS}
      DECOSA_FILL_MAX_RUNS: "2"
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      # optional blocks, if you run them: DECOSA_DOCREADER_URL (scans, photos), DECOSA_LANG_MT_URL (translated review)
    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: {}, decosa-data: {} }
```

Keep the named volumes: a root-owned host bind mount makes the API fail on `/data/keys.sqlite`.

## 4. Start it

1. `docker compose up -d`; poll `docker compose ps` until both are healthy (the model takes 5-10 minutes the first time).
2. `curl -s localhost:8445/fill/info | jq '{route: .model.route, demo_forms: .targets.demo_forms, available}'`: route
   `direct`, demo form `harbor-mutual`, available `true`.

## 5. Smoke test

```bash
cd ~/decosa-fill && docker compose exec api python scripts/rehearse.py fill-and-stop --base-url http://127.0.0.1:8445
```

Pass if all 12 checks pass: the policy number typed with its source line, 15+ fields filled, the date of birth and the
bank fields left for the person, the hidden instruction to AI agents flagged and Comments left empty, the run stopped at
"Submit claim", the record verifies and a changed copy fails, approval refused until the flag is acknowledged, then the
approval names the person and releases the one held Submit to the demo insurer.

## 6. Fill a real site with your own login (the command-line path)

The API container has no screen, so for a live site run the CLI on your desktop (Python 3.12, `pip install
"decosa-api[flight]"` from the source, `playwright install chromium`), pointing it at the model you started:

```bash
export DECOSA_LLM_ROUTE=direct DECOSA_LLM_URL=http://127.0.0.1:8000/v1 DECOSA_LLM_MODEL=qwen3.8-27b
python -m decosa_api.verticals.fillstop.cli --url https://portal.example-insurer.com/claims/new \
  --doc policy-letter.pdf --doc repair-invoice.pdf --login --headed --out ./my-claim
```

(Expose the model to your desktop with `ports: ["127.0.0.1:8000:8000"]` on the `llm` service, or run the CLI on the same
box with a display.) A fresh browser opens: log in yourself and open the form, press Enter in the terminal, and the agent
fills it. It prints each field with the line it came from, writes `review.json` and the signed `record.json`, and hands
the browser back: check the form, fill what is left, and press Submit yourself. Add `--allow cdn.example.com` for hosts
the page loads from.

## 6b. Optional: the commit detector (our own model, CPU)

Without it the agent still stops at every commit word (32 languages) and the browser still holds every request that could
send the form. With it, clicks the model chooses (custom widgets) are also judged by the model in context. On the same box:

```bash
python3 -m venv /opt/commit-detector && /opt/commit-detector/bin/pip install torch transformers safetensors fastapi uvicorn \
  --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple
huggingface-cli download decosaai/decosa-commit-detector-xlmr-large --revision 3642232829db351b90bba0f902d2dd99bb3625a4 --local-dir /opt/commit-detector/weights
COMMIT_MODEL_DIR=/opt/commit-detector/weights /opt/commit-detector/bin/python services/commit_detector/server.py   # 127.0.0.1:8494
```

Set `DECOSA_COMMIT_URL=http://127.0.0.1:8494` for the api (from inside compose, the host's address). About 2.3 GB of RAM,
no GPU. `GET /fill/info` shows `commit_detector.available`.

## 7. Point your tools at it

- The console on the Decosa site talks to `NEXT_PUBLIC_DECOSA_API`; set it to `http://127.0.0.1:8445` for a local build.
- Verify any record with `curl -s localhost:8445/flight/verify -H 'content-type: application/json' -d @my-claim/record.json`.