Pre-flight a synthetic-performer ad

# Decosa synthetic-performer disclosure and S&P pre-flight: use the hosted API

You are wiring Decosa's disclosure pre-flight into this project. It takes an ad or short (the video, its script or
transcript, and who is in it) and returns:

- which performers are synthetic, and on what evidence: the file's C2PA credential, Decosa's render receipt or
  watermark, or the declaration;
- whether an AI label is visible, from OCR on six frames;
- the New York (GBL § 396-b) and EU AI Act (Art. 50) checks;
- a consent-ledger decision for each real performer, by ledger id;
- script flags (real people, other brands, profanity, rating triggers, music cues) with their lines.

When a rule needs it, the pre-flight burns in the label and signs a C2PA marking. A named reviewer then signs off, and
the sign-off is sealed into a signed AI-use attestation. Each model call (script checks 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`.
- It is advisory, not a legal clearance. Show every result as something for a person to decide.
- No model looks at the video. A performer counts as synthetic only when the file's provenance says so or I declare it.
  A file with neither comes back as "needs a declaration".
- Unreleased ads are confidential. For those, use the self-host prompt.

## 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, and send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "disclosure-preflight"}` returns
   `{"token", "expires_at", "budget"}`. The limit is a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz). Over a limit you get HTTP 429 with
   `Retry-After`.
3. One check at a time per demo token (409 otherwise).

## Endpoints

### `POST /disclosure/check` (token)

Body:

```json
{"video_b64": "<base64 MP4 or MOV>", "script": "...", "advertiser": "...", "product": "...", "performers": [{"label": "Maya", "kind": "synthetic|human|replica", "identity_id": "id_…", "face": true, "voice": true}], "project": "spring-campaign", "territory": "US", "markets": ["US-NY", "EU"], "apply_disclosure": true, "judge": true, "use_model": true, "stream": true}
```

Or send `{"sample": "raw-declared"}` to run a demo sample (`GET /disclosure/samples`).

- Send a video, a script, or both.
- `project` is required when a performer has an `id_` identity, because consent is checked for a named project.
- Limits: the video up to 40 MB and 3 minutes; the script up to 20,000 characters.

With `"stream": true` it streams these events: `ready`, `stage`, `media`, `label` (before, and after the label is
added), `consent` per performer and kind, `performer`, a `receipt` per model call, `flag`, `disclosure`, `report`,
`done` (`run_id`, `video_url`, `signoff_url`) and `budget`.

With `"stream": false` it returns one JSON object: `{run_id, status, totals, video_url, receipts, consent, report,
budget}`.

What the report holds:

- `report.status`: `needs_changes`, `needs_review` or `no_issues_found`.
- `report.rules[]`: `{rule: ny-gbl-396b|eu-ai-act-50-2|eu-ai-act-50-4, status: met|partial|missing|needs_declaration|not_triggered|not_checked, why}`.
- `report.performers[]`: `{id, label, kind, evidence, consent: [{kind, state, code, reason, receipt_id}], consent_state, issues}`.
- `report.flags[]`: `{id, category: real_person|trademark|profanity|rating|music, text, lines, line_text, confidence: high|review|info, p, action}`.
- `report.disclosure`: what was added, the OCR read-back and the C2PA check.

Errors:

| Code | Meaning |
|---|---|
| 400 | Bad input; the message names the field |
| 402 | Budget exhausted |
| 404 | A sample's video is not on this server |
| 409 | This demo token already has a check running |
| 413 | Body too large |
| 429 | Busy |

### Other endpoints

- `GET /disclosure/runs/{run_id}/video` (token): the disclosed MP4.
- `POST /disclosure/runs/{run_id}/signoff` (token): `{"name", "role", "decisions": {"F1": "fix|cleared|accept_risk|not_an_issue"}, "note"?, "confirm": true}`
  returns `{attestation, check, signoff}`. You can sign off once per run.
- `GET /disclosure/runs/{run_id}/export?format=md|csv|attestation`.
- `POST /record/verify` (no token): `{"record": <attestation>}` returns `{ok, ...}`.
- No token needed: `GET /disclosure/info` (the laws with dates and links, limits and eval), `GET /disclosure/samples`,
  `GET /attest/signing-key`.

## Example: check an ad, then sign off (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 = {"video_b64": base64.b64encode(pathlib.Path("ad.mp4").read_bytes()).decode(),
        "script": pathlib.Path("script.txt").read_text(), "advertiser": "Tidewell", "product": "Tidewell All-Surface",
        "performers": [{"label": "Presenter", "kind": "synthetic"}], "stream": False}
run = httpx.post(f"{API}/disclosure/check", headers=H, json=body, timeout=300).raise_for_status().json()
rep = run["report"]
print(rep["status"], [(r["rule"], r["status"]) for r in rep["rules"]])
for f in rep["flags"]:
    print(f["id"], f["category"], f["text"], "line", f["lines"], f["confidence"])
if run["video_url"]:
    pathlib.Path("ad-disclosed.mp4").write_bytes(httpx.get(f"{API}{run['video_url']}", headers=H).content)
# a named person reviews the flags, then:
att = httpx.post(f"{API}/disclosure/runs/{run['run_id']}/signoff", headers=H, timeout=30,
                 json={"name": "Reviewer Name", "role": "Ad-ops reviewer", "confirm": True,
                       "decisions": {f["id"]: "fix" for f in rep["flags"] if f["confidence"] != "info"}}).json()
pathlib.Path("attestation.json").write_text(__import__("json").dumps(att["attestation"]))
```

## Honest limits

- A synthetic performer with no provenance and no declaration is not found.
- The label check reads our label style; other styles may not be read.
- Whether a label is "conspicuous" is a legal judgement, not a measurement.
- Script recall was measured on short synthetic scripts (27 of 29 planted issues, no false flags). Real scripts will do
  worse.
- Logos and faces in the picture are not checked yet.
- Consent is checked only for identities enrolled in the consent ledger. The `id_demo-…` identities are fictional.

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 synthetic-performer disclosure and S&P pre-flight: run it yourself (containers)

You are setting up the Decosa disclosure pre-flight on this machine, so unreleased ads and scripts never leave it. For
each ad it:

- finds synthetic performers from the file's provenance and my declaration;
- reads the frames for an AI label;
- burns in the label and signs a C2PA marking when the New York or EU rules need them;
- checks real performers against the consent ledger by id;
- flags the script;
- seals a named reviewer's sign-off into a signed AI-use attestation.

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/disclosure-preflight.zip (254 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 disclosure-preflight` (the api image carries the same bundle under /app/rehearsal/disclosure-preflight/;
   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 disclosure-preflight --bundle disclosure-preflight.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 hit song is flagged", "the celebrity is flagged", "the other brand is flagged"). 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 script checks, also install the NVIDIA
   container toolkit and check `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. **Compose file.** Fetch it:

   ```sh
   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` and
     `DECOSA_PROVENANCE_DIR=/provenance`;
   - add a named volume at `/provenance`;
   - bind every port to 127.0.0.1.

   Without a GPU, drop `llm` and send `"use_model": false`. That uses the word lists only: no names, brands or rating
   triggers.
3. **Start.** `docker compose pull && docker compose up -d`.
4. **C2PA signing certificate.** Run `docker compose run --rm api python scripts/provenance_devcert.py`, then restart
   the api service.
   - This is a development certificate: public validators show the marking's issuer as untrusted. Tell me that.
   - For production, a certificate from a C2PA trust-list issuer goes into the same volume. Never print a private key.
5. **Check.** `curl -fsS http://127.0.0.1:<PORT>/disclosure/info` shows:
   - `tools` all true (ffmpeg, tesseract, font);
   - `c2pa_signing: true`;
   - `"route": "direct"`.

   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify my
   attestations.
6. **Smoke test.** Get a token with `POST /demo/session {"vertical":"disclosure-preflight"}`.
   - Run `POST /disclosure/check {"sample": "script-planted", "stream": false}`. Expect five flags: "Walking on
     Sunshine", "Serena Williams", "Starbucks", "shit" and the backflip. Ava should be granted and Ben refused (both
     fictional demo identities), with receipts `attested`.
   - Run `{"sample": "raw-declared", "stream": false}`. Expect `report.disclosure.applied` true, the label read back on
     6 of 6 frames, and a C2PA marking with `content_intact: true`.
   - Sign off: `POST /disclosure/runs/{run_id}/signoff {"name": "...", "role": "...", "confirm": true}`. Then send the
     attestation to `POST /record/verify`: `ok` must be true.
   - The Decosa-ad samples show `available: false` here. That is expected: they are Decosa's hosted renders.
7. **Report back.** Tell me the public key and key id, the flags, and how long each run took.

## Consent ledger

Real performers are checked by id against the consent ledger (tool 47) once it is configured on this server. Until
then they are reported as unchecked, never as cleared. Enrol people through that tool, not this one.

Off, and keep it off on a box that holds unreleased ads: 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.