Check split sheets and metadata

# Decosa Split-sheet and metadata checker: use the hosted API

You are wiring Decosa's split-sheet and metadata checker into this project. It takes a release's documents (split
sheets as text, PDF, DOCX or scans; the release metadata as a DDEX ERN message or a distributor CSV; publishing
contract excerpts; society registration exports as CSV) and returns every discrepancy with the lines it came from:
splits that do not add up to 100%, co-writers missing from a source, role and society mismatches, missing publishers,
and ISRC, ISWC, IPI and UPC format or check-digit errors. It proposes one credit sheet, which a person confirms, and
signs records of the check and the confirmation. Each model call has its own signed receipt. Use only what is listed
below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- The hosted API is for released metadata, test catalogs and integration testing. Unreleased catalogs and contract
  terms are confidential: for those use the self-host prompt instead.
- It is a checking aid, not legal or accounting advice. Show every result as something to check.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "split-sheet-check"}` returns `{"token", "expires_at", "budget"}`.
   a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz); each session has a token allowance (its `budget`) (a release of three to five split sheets uses about
   1,500). Over a limit: HTTP 429 with `Retry-After`.
3. One check at a time per demo token (409 otherwise).

## Endpoints
- `POST /splits/check` (token). Body:
  `{"documents": [{"name": "...", "kind": "split_sheet" | "release" | "contract" | "registration", "text": "..."} | {"name", "kind", "data_b64": "<base64 of a PDF, DOCX, PNG or JPEG>"}], "extract"?: true, "stream"?: true}`,
  or `{"sample": "harbor-lights-planted"}` (see `GET /splits/samples`).
  - Release metadata and registrations must be DDEX XML or CSV text (headers are matched loosely: title, writer or first
    and last name, role, IPI or CAE, society or PRO, share, publisher). Split sheets and contracts can be anything; the
    model reads them and every value it reads must be found in the document, or it is not used.
  - Limits: 12 documents, 8 of them split sheets or contracts, 4 MB per file, 60,000 characters per document.
  - With `"stream": true` (or `Accept: text/event-stream`) it streams `intake`, `parsed` or `extracted` per document
    (every value with its line and quote), `receipt` after each model call, `judgment` per same-writer or role call,
    then `report`, `done` and `budget`. With `"stream": false`: one JSON object `{run_id, sources, receipts, report, budget}`.
  - `report.issues`: `[{id, kind, severity: error|warning, work, writer, message, sources: [{src, name, line, where, quote}]}]`.
    Kinds: `share_total`, `share_mismatch`, `missing_writer`, `role_mismatch`, `id_invalid`, `id_mismatch`,
    `pro_mismatch`, `publisher_missing`, `publisher_mismatch`, `share_unreadable`, `work_missing`.
  - `report.proposal`: per song, per writer, each field `{value, status: agreed|chosen|invalid|missing, from, alternatives, rule}`.
- `POST /splits/parse` (token): the same body, code only (no split sheets or contracts read, no budget), always JSON.
- `POST /splits/ids` (token) `{"values": ["T-034.524.680-1", "00000000199"]}`: identifier checks only.
- `POST /splits/runs/{run_id}/confirm` `{"reviewer": "...", "edits": [{"work": "W1", "writer": 0, "field": "share", "value": "33 1/3"}], "accept": true}`:
  422 lists what still blocks signing (shares not adding to 100%, a bad IPI, a field the sources disagree on that was
  neither edited nor accepted); 200 returns the signed credit sheet.
- `GET /splits/runs/{run_id}/export?format=csv` (the proposed or confirmed sheet), `md` (report), `record` (signed check), `sheet` (signed confirmed sheet).
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.
- `GET /splits/info`, `GET /splits/samples`, `GET /splits/samples/{id}`, `GET /attest/signing-key` (no token).

## Example: check a release before delivery (Python, `pip install httpx`)
```python
import httpx, os, pathlib
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
docs = [{"name": p.name, "kind": "split_sheet", "text": p.read_text()} for p in pathlib.Path("split-sheets").glob("*.txt")]
docs.append({"name": "release.xml", "kind": "release", "text": pathlib.Path("release.xml").read_text()})
docs.append({"name": "mlc-export.csv", "kind": "registration", "text": pathlib.Path("mlc-export.csv").read_text()})
r = httpx.post(f"{API}/splits/check", headers=H, timeout=600, json={"documents": docs, "stream": False})
r.raise_for_status()
run = r.json()
for x in run["report"]["issues"]:
    print(x["severity"], x["kind"], x["message"], [(s["src"], s["line"]) for s in x["sources"]])
```

## Honest limits
- Measured on synthetic catalogs only (fictional songs and writers); see the numbers on the Stack tab.
- Scans are read with Tesseract OCR: handwriting-style scans lose identifiers often, and an OCR misread is marked as
  such rather than trusted.
- Registration and distributor CSVs are matched by header names; an unusual layout may need its columns renamed.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa Split-sheet and metadata checker: run it yourself (containers)

You are setting up the Decosa split-sheet and metadata checker on this machine, so unreleased catalogs and contract
terms never leave it. It reconciles split sheets, release metadata (DDEX or CSV), contract excerpts and society
registrations, checks every identifier and share sum in code, proposes a credit sheet for a person to confirm, and
signs records. Nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## 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/split-sheet-check.zip (124 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 split-sheet-check` (the api image carries the same bundle under /app/rehearsal/split-sheet-check/;
   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 split-sheet-check --bundle split-sheet-check.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: "all seven documents are read", "the 105% split is found", "the wrong ISWC check digit is found"). 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.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). Also install the NVIDIA container toolkit and
   check `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service. For the `api` service set
   `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b`,
   `DECOSA_SPLITS_MAX_DOCUMENTS=40`, and bind every port to 127.0.0.1. The api image includes Tesseract for scans.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
   downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/splits/info` shows `"route": "direct"` and `"ocr": true`;
   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify my records.
5. Smoke test: get a token with `POST /demo/session {"vertical":"split-sheet-check"}` and run
   `POST /splits/check {"sample": "harbor-lights-planted", "stream": false}`. Expect every document read, and issues
   for a 105% split, an ISWC check digit, a missing co-writer, a composer/lyricist swap, a society mismatch and a
   missing publisher, each with its source lines; every receipt `attested`. Then `POST /record/verify` with
   `report.record`: `ok` must be true.
6. Report back: the public key and key id, the totals, the issues and how long the run took.

Off, and keep it off on a box that holds unreleased catalogs or contracts: joining serves other people's requests on
this GPU. If I ask for it later, on a separate machine, follow the Provide page instead of improvising.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/split-sheet-check-mac.md instead.