Turn a script into an animatic

# Decosa script to animatic: use the hosted API

You are wiring Decosa's script-to-animatic into this project. It takes a short script or ad brief (up to about two
pages: screenplay, stage play or ad format), drafts a shot list where every shot cites the script lines it covers,
checks coverage and each shot's action against its lines, and, once the user has edited the shots and cast temp
voices, renders an MP4 animatic with shot numbers, timecode, subtitles and an AI label, a C2PA credential, a shot-list
CSV, a storyboard PDF and a signed record of which steps were AI and which were human edits. Model calls carry signed
receipts. 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`.
- Previsualisation, not finished work: frames are rough and characters only partly consistent from shot to shot.
- Send only scripts the user may share: the hosted demo keeps a run 7 days so it can be edited and re-rendered.
- Temp voices are stock synthetic voices; each is checked in the consent ledger at render time. Never promise a voice.

## 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 `DECOSA_API_KEY`, never in
   code. Send `Authorization: Bearer $DECOSA_API_KEY`. A key renders 3 times per UTC day on the shared GPU.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "animatic-studio"}` returns `{"token", ...}`.
   3 renders per session. Over a limit: HTTP 429 with `Retry-After`.

## Endpoints
- `POST /animatic/shotlist` (token). Body `{"script": "...", "title"?: "...", "style"?: "sketch"|"grey"|"colour", "stream"?: true}`.
  Returns `run_id`, `lines` (`L1`… with kind, speaker), `shots` (`n`, `lines`, `framing`, `angle`, `movement`,
  `characters`, `setting`, `action`, `duration_s`, `dialogue` taken word for word from the script), `characters`
  (a `look` per character: the model's design choice), `coverage` (`pct`, `missing`, `dialogue_spoken_once`),
  `grounding` (per shot: `supported`, `partial`, `unsupported`, `contradicted`) and `receipts`. With `stream: true`
  it is SSE: `lines`, `receipt`, `shotlist`, one `grounding` per shot, `report`, `done`. 400 on an empty or oversized
  script (7,000 characters, 160 lines).
- `GET /animatic/voices` (no token): voices you can cast (`identity_id`, `group`: house, cast, or roster voices whose
  consent does not cover animatics).
- `POST /animatic/runs/{run_id}/render` (token). Body `{"shots"?: [...edited shots...], "characters"?: [{name, look}],
  "cast"?: {"SPEAKER": "identity_id"}, "style"?: ...}`; shots are validated (every shot must cite script lines; a shot's
  dialogue is always rebuilt from its line ids; `motion: true` on up to 6 shots). 202 `{version, consent: [{speaker,
  allowed, code, reason, decision_id}], coverage, edits, poll}`. A refused voice is subtitled, not voiced.
- `POST /animatic/runs/{run_id}/shots/{n}/render` (token). Body `{"shot": {changed fields}}`: re-renders one shot and
  re-cuts (202). Needs one full render first.
- `GET /animatic/runs/{run_id}` (token): poll every 5-10 s until `versions[-1].status` is `done` or `failed`. The latest
  version has `progress` while running and, when done, `video_url` (relative: prefix `https://api.decosa.ai`), `timeline`
  (per shot `tc_in`, `tc_out`, `frame_url`), `sheets`, `credential`, `receipt_url`, `label_check`, `record` and `exports`.
- `GET /animatic/runs/{run_id}/shotlist.csv` and `/shotlist.pdf` (token; `?v=N`).
- `GET /animatic/records/{run_id}-v{N}` (no token): the signed record; verify it at `POST /record/verify` with
  `{"record": ...}`; `?format=md` for the readable one.
- `GET /animatic/info`, `GET /animatic/samples` (no token).

## Example: shot list, render, save the cut and the record (Python, `pip install httpx`)
```python
import httpx, os, pathlib, time
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
script = pathlib.Path("scene.txt").read_text()
sl = httpx.post(f"{API}/animatic/shotlist", headers=H, timeout=600, json={"script": script, "style": "sketch"})
sl.raise_for_status()
sl = sl.json()
print(sl["coverage"]["pct"], [g["label"] for g in sl["grounding"]])
run_id = sl["run_id"]
acc = httpx.post(f"{API}/animatic/runs/{run_id}/render", headers=H, timeout=120,
                 json={"cast": {sp: "id_house-af-heart" for sp in sl["speakers"][:1]}}).json()
while True:
    time.sleep(10)
    v = httpx.get(f"{API}/animatic/runs/{run_id}", headers=H, timeout=120).json()["versions"][-1]
    if v["status"] in ("done", "failed"):
        break
if v["status"] == "failed":
    raise SystemExit(v.get("error"))
pathlib.Path("animatic.mp4").write_bytes(httpx.get(API + v["video_url"]).content)
pathlib.Path("record.md").write_text(httpx.get(API + v["record"]["markdown"]).text)
```

## Honest limits
- The model's own shot list covered every script line in 10 of 10 eval runs, and dialogue can't be invented (code
  inserts it); shot descriptions can still add details, which the grounding check flags (it caught 10 of 10 planted
  inventions, and it also marks harmless staging details as "partial").
- Frames aren't checked against existing characters; review for resemblance before sharing. Describe each character's
  shape, colour and silhouette in its `look`: a vague look can drift towards a familiar character.
- Character consistency is partial: frames repeat each character's look in words; no identity adapter is used.
- Renders share one GPU; a full animatic takes several minutes, longer when other renders are queued.

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 script to animatic: run it yourself (containers)

You are setting up Decosa's script-to-animatic on this machine: Qwen3.8-27B for the shot list and the grounding check,
Wan2.2-VACE-Fun-A14B in ComfyUI for sheets, frames and motion, Kokoro-82M stock voices on CPU, the consent ledger, and
ffmpeg for the cut. Unreleased scripts stay here; 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. Don't substitute other images or models.

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/animatic-studio.zip (2 KB, 9 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 animatic-studio` (the api image carries the same bundle under /app/rehearsal/animatic-studio/;
   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 animatic-studio --bundle animatic-studio.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: "every action, dialogue and on-screen-text line is covered by a shot", "each dialogue line is spoken exactly once, in the script's words", "the shot list has at least four shots"). 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.

## Rules first
- Every temp voice goes through the consent ledger. Never bypass it, and never clone a real person's voice.
- Keep the burned-in AI label and the C2PA credential on every cut.

## Steps
1. Docker and the NVIDIA container toolkit: if `docker compose version` or
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi` fails, install them from the official
   instructions. The frames need about 34 GB of free VRAM while a job runs; Qwen3.8-27B NVFP4 about 57 GB (one 96 GB
   card each, or a remote text endpoint).
2. ComfyUI at the pinned commit with the Wan2.2-VACE-Fun-A14B, Wan2.2-Lightning, umt5-xxl and Wan2.1 VAE weights: the
   tool's assemble prompt lists the exact downloads and file names.
3. Fetch the compose file: `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`. Keep the
   `llm` and `api` services. The api image needs the render layer (FFmpeg, Tesseract, DejaVu fonts, c2pa-python and a
   `/opt/kokoro` venv); the assemble prompt has the Dockerfile. Use named volumes and bind every port to 127.0.0.1.
4. `docker compose up -d`, wait for the health checks, then create the C2PA signing material once:
   `docker compose exec api python scripts/provenance_devcert.py && docker compose restart api`.
5. Smoke test: get a token from `POST /demo/session {"vertical":"animatic-studio"}`, draft the `night-shift-ad` sample
   (`POST /animatic/shotlist`) and check `coverage.pct` is 100; render it with `{"cast":{"VO":"id_house-af-heart",
   "DANA":"id_demo-ines-okafor"}}` and check DANA is refused; poll to `done` and check `credential` is `c2pa` and the
   record verifies at `POST /record/verify`.
6. Report back: the signing key id (`GET /attest/signing-key`), the render time and the seconds per frame.