Pre-check samples and lyrics

# Decosa Sample and lyric clearance pre-check: use the hosted API

You are wiring Decosa's clearance pre-check into this project. It takes a track (audio), its lyrics and the list of
samples the artist declared, and returns a checklist: every sample (even pitched, stretched, filtered or looped),
re-played melody and lifted lyric line it finds in the reference catalog, with its time in the track and in the
reference, a confidence, whether it was declared (and with a clearance document), and whether to clear, replace or
remove it. It ends with a signed record. Each model call (lyric labels only) 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 checks against a small demo catalog (35 CC BY recordings and six synthetic melodies) and 156
  public-domain songs; it is for trying the method and testing your integration. Unreleased tracks and your own
  catalog belong on your own machine: use the self-host prompt for that.
- It is triage for clearance staff, not legal 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": "sample-clearance"}` returns `{"token", "expires_at", "budget"}`.
   a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz). Over a limit: HTTP 429 with `Retry-After`.
3. One check at a time per demo token (409 otherwise).

## Endpoints
- `POST /clearance/check` (token). Body:
  `{"audio_b64": "<base64 of the file>", "lyrics": "[00:20.00] a line\n...", "declared": "Title - Artist | sample | licence LIC-014", "title"?: "...", "judge_lyrics"?: true, "assume_reserved"?: false, "stream"?: true}`,
  or `{"sample": "planted"}` (the demo track). At least audio or lyrics.
  - Audio: WAV, FLAC, MP3, OGG, Opus or M4A as base64, up to 20 MB; the first 10 minutes are checked. Lyrics: one
    line per line, LRC timestamps kept, up to 20,000 characters. Declared: a list `[{title, artist?, catalog_id?, type?: sample|interpolation|lyric, document?}]`
    or text, one entry per line. `assume_reserved: true` treats every reference as all rights reserved.
  - With `"stream": true` (or `Accept: text/event-stream`) it streams `ready`, `stage`, a `finding` per item, a
    `receipt` after each model call, then `report`, `done` and `budget`. With `"stream": false`: one JSON object
    `{run_id, totals, export, receipts, report, budget}`.
  - `report.checklist[]`: `{id, kind: sample|interpolation|lyric, ref: {id, title, artist, rights, licence, source}, confidence: high|medium, where: [{start_s, end_s, ref_start_s, ref_end_s}] or [{line, start_s}], status: undeclared|declared_no_document|documented, action: clear|replace|remove, alternatives, why, how}`.
    `report.declared_not_found[]`: declared entries the catalog does not hold. `report.record`: the signed record.
  - Errors: 400 (the message says what is wrong, including audio that cannot be decoded), 402 budget, 413 over 28 MB,
    429 busy, 503 when the catalog is not ready (lyrics-only checks still work).
- `GET /clearance/runs/{run_id}/export?format=csv` (checklist), `md`, `record` (signed).
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.
- `GET /clearance/info`, `GET /clearance/catalog`, `GET /clearance/samples`, `GET /clearance/samples/{id}`, `GET /attest/signing-key` (no token).

## Example: check a track and save the checklist (Python, `pip install httpx`)
```python
import base64, httpx, os, pathlib
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
body = {"audio_b64": base64.b64encode(pathlib.Path("track.mp3").read_bytes()).decode(),
        "lyrics": pathlib.Path("lyrics.lrc").read_text(), "declared": "Dirt Rhodes - Kevin MacLeod | sample | LIC-014",
        "stream": False}
r = httpx.post(f"{API}/clearance/check", headers=H, json=body, timeout=300)
r.raise_for_status()
run = r.json()
for x in run["report"]["checklist"]:
    print(x["id"], x["kind"], x["ref"]["title"], x["confidence"], x["status"], x["action"])
pathlib.Path("clearance.csv").write_text(httpx.get(f"{API}{run['export']['csv']}", headers=H).text)
```

## Honest limits
- It finds only what is in the catalog it checks; the hosted catalog is a 41-reference demo.
- Measured recall on planted borrowings is moderate (57% on the test split; quiet samples and short loops are missed
  most); high-confidence items were all correct. See the Stack tab.
- Heavy paraphrases of a lyric line are not flagged; lyric matching is English.

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 Sample and lyric clearance pre-check: run it yourself (containers)

You are setting up the Decosa clearance pre-check on this machine, so unreleased tracks and our catalog never leave
it. It matches a track's audio against our catalog (samples, even pitched, stretched, filtered or looped, and re-played
melodies), matches its lyrics against a lyric set, compares what it finds with what was declared, and signs a record.
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/sample-clearance.zip (649 KB, 10 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 sample-clearance` (the api image carries the same bundle under /app/rehearsal/sample-clearance/;
   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 sample-clearance --bundle sample-clearance.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 undeclared Fork and Spoon slice is flagged", "the Fork and Spoon slice is placed near 0:30", "the declared Dirt Rhodes loop is found and documented"). 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). For the lyric labels, 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_CLEARANCE_CATALOG=/data/clearance/catalog`, `DECOSA_CLEARANCE_EMBED_DIR=/data/clearance/minilm`, and bind
   every port to 127.0.0.1. Without a GPU, drop `llm` and send `"judge_lyrics": false`.
3. Pull and start: `docker compose pull && docker compose up -d`.
4. Embedding files and a catalog:
   `docker compose exec api python -m decosa_api.verticals.clearance.embed fetch /data/clearance/minilm`, then either the
   demo catalog (`docker compose exec api python scripts/clearance_catalog.py demo /data/clearance/catalog`, 35 CC BY
   recordings, about 180 MB) or ours: our audio plus a `catalog.json` in that folder (see API_CONTRACT.md, "Sample and
   lyric clearance pre-check"), then `python -m decosa_api.verticals.clearance.catalog build /data/clearance/catalog`.
   Restart the api service.
5. Check: `curl -fsS http://127.0.0.1:<PORT>/clearance/info` shows `catalog.state: "ready"` and `"route": "direct"`;
   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify my records.
6. Smoke test (demo catalog): get a token with `POST /demo/session {"vertical":"sample-clearance"}` and run
   `POST /clearance/check {"sample": "planted", "stream": false}`. Expect "Dirt Rhodes" documented, "Fork and Spoon"
   and "Synthetic melody 02" undeclared, lyric lines 5 and 8 flagged, "Night Train Breaks" in `declared_not_found`,
   receipts `attested`. Then `POST /record/verify` with `report.record`: `ok` must be true. `{"sample": "clean"}`
   must come back empty.
7. Report back: the public key and key id, the checklist and how long the run took.

Off, and keep it off on a box that holds unreleased masters: 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/sample-clearance-mac.md instead.