Tie out MD&A figures

# Assemble the Decosa filing tie-out on this machine

You are setting up a tie-out aid for SEC reporting teams and auditors. Given a 10-K or 10-Q in inline XBRL (a draft
from your disclosure tool, or a filed one from EDGAR), or tables pasted as CSV with a draft, it ties every figure in
the MD&A prose to the tagged statements and notes: the cell it equals (fact id, table, period), or the change,
percentage change, margin or sum it was computed from, or why it does not tie (wrong value, another period's figure,
the wrong scale, the other direction, a note reference to the wrong note, a note table that disagrees with a
statement). It writes a workpaper (Markdown and CSV) and a JSON 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/filing-tieout.zip (3 KB, 16 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 filing-tieout` (the api image carries the same bundle under /app/rehearsal/filing-tieout/;
   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 filing-tieout --bundle filing-tieout.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 synthetic draft does not tie", "the transposed 2024 net income is a value mismatch naming the table's figure", "the inventories accounts do not roll up to the balance sheet"). 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
- decosa-api (AGPL-3.0-or-later) does the tie-out in plain Python on the CPU: no GPU and no model are needed for figures,
  periods, scale, direction, note references or the record. That is the lite tier.
- Optional: Qwen3.8-27B (Apache-2.0) reads claims in words ("gross margin improved") against the named lines, at most
  12 calls a run. That is the standard tier and needs a GPU.
- Drafts before release are material non-public information. Keep everything on this machine and bind every port to
  127.0.0.1. The service stores nothing but a cache of public EDGAR documents; logs carry counts only. Keep it that way.
- It is a preparer's and reviewer's aid: not an audit, not an opinion, never "compliant". A person reviews every flag
  and every untraced figure.

## 1. Check the machine
1. `docker --version` and `docker compose version`. If Docker is missing, install it from Docker's official
   repository after asking me.
2. Lite tier: any x86-64 or arm64 machine, 2 GB RAM free. A 10-K parses and ties in about half a second on one core.
3. Standard tier only: `nvidia-smi` shows one GPU with at least 32 GB and driver 570+, and the NVIDIA container
   toolkit works (`docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`). On a card without
   NVFP4 use `Qwen/Qwen3.8-27B-FP8`.

## 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 release tag that
  contains `decosa_api/verticals/tieout/` (`main` until one does), and build `docker/api/Dockerfile`.
- Standard tier: `vllm/vllm-openai:v0.29.0` and `nvidia/Qwen3.8-27B-NVFP4` (revision
  `482ca0f3832238542f8f5295dde86b5f22711d80`).

## 3. docker-compose.yml
Write this in `~/decosa/tieout/`. For the lite tier, delete the `llm` service and the `depends_on` block, and set
`judge_claims: false` in requests.

```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_TIEOUT_PUBLIC_ONLY: "0"
      DECOSA_TIEOUT_EDGAR: "1"
      DECOSA_CONTACT_EMAIL: you@example.com
      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/tieout/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
```

- `DECOSA_TIEOUT_PUBLIC_ONLY: "0"` lets this box take drafts; the hosted service refuses anything not declared public.
- `DECOSA_CONTACT_EMAIL` goes in the User-Agent of EDGAR requests (SEC's fair-access policy asks for one). Put a real
  address, or set `DECOSA_TIEOUT_EDGAR: "0"` if this box must never reach the internet: drafts do not need EDGAR.
- The api keeps its state (keys, receipts, this box's signing key, the EDGAR cache) in the named volume `decosa-data`,
  not a host folder: the image runs as uid 10001, and a host folder Docker creates is owned by root, which stops the api
  with `PermissionError: [Errno 13] Permission denied: '/data/keys.sqlite'`.

Start it: `docker compose up -d`. On first start the api creates this box's Ed25519 key in `/data/attest/` (mode 0600).
Back it up with `docker compose cp api:/data/attest ./attest-backup`, keep that copy private, never print it. Model
calls on the direct route get receipts signed with that key (`attested`: an attestation by me, the operator, not a
proof). Never set `DECOSA_LLM_ROUTE=gateway` here: that would send draft text to the Decosa API.

## 4. Smoke test
1. `curl -s localhost:8445/tieout/info | jq '{public_only, edgar: .edgar.enabled, statuses: (.statuses | keys)}'` shows
   `public_only: false` and the statuses `computed`, `mismatch`, `tied`, `untraced`.
2. Token: `T=$(curl -s -XPOST localhost:8445/demo/session -H 'content-type: application/json' -d '{"vertical":"filing-tieout"}' | jq -r .token)`.
3. The planted sample (AMD's filed MD&A with six planted errors, bundled in the image):
   `curl -s -XPOST localhost:8445/tieout/check -H "authorization: Bearer $T" -H 'content-type: application/json' -d '{"sample":"amd-fy2025-planted","judge_claims":false}' > res.json`.
   Expect `status: "mismatches"` and, under `sentences[].figures[]`, mismatches with `reason` value, value, period and
   scale (the scale one says "$577 billion looks 1,000 times too large"); one `direction` flag ("says increased, but
   Embedded went from ..."), one wrong `Note 6`, and in `cross_refs` one `same_fact_two_values` (Net revenue shown as
   34,639 and 34,729). `coverage.traced` should be 44 of 57.
4. The clean case: the same with `"sample":"amd-fy2025"`: no mismatches.
5. `jq '{report, workpaper_md, workpaper_csv}' res.json | curl -s -XPOST localhost:8445/tieout/verify -H 'content-type: application/json' -d @-`
   must show `valid_signature`, `signed_by_this_server`, `workpaper_md_matches` and `workpaper_csv_matches` true.
   Change `status` in the report and verify again: it must fail.
6. Your own document: `jq -Rs '{html: ., judge_claims: false}' my-10k.htm | curl -s -XPOST localhost:8445/tieout/check -H "authorization: Bearer $T" -H 'content-type: application/json' -d @- > mine.json`
   (a draft iXBRL export from your disclosure tool works the same way; to tie a revised MD&A against a filing's facts,
   add `draft`). Then `jq -r .workpaper_md mine.json > workpaper.md`.
7. Standard tier: repeat step 3 with `"judge_claims": true` and check that each claim read has a `receipt_ids` entry.
8. Time it and tell me what you measure. On our machine the planted sample took 0.1 s without claims and 7-10 s with
   one claim read through the shared gateway.

## 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 /tieout/check` from your
close or disclosure checklist and file `workpaper_md`, `workpaper_csv` and the signed `report` with the draft. The
rehearsal bundle (`python scripts/rehearse.py filing-tieout`) runs a synthetic company and the planted sample against
this box. Contract: `API_CONTRACT.md`, section "Filing tie-out and MD&A grounding".

Off by default. Joining serves other people's requests on this GPU; never do it on a box that holds unreleased
financial statements. If I ask for it, follow the provider guide at `/provide` on the site, and only with my explicit yes.