Check if a video is made for kids

# Assemble the Decosa made-for-kids content pre-flight on this machine

You are setting up a self-hosted made-for-kids pre-flight on this Linux machine for a YouTube channel, an MCN, or a kids'
app or game studio. Before a video, short, live stream or app listing is published (or when a back catalogue is audited),
it:
- decides whether the upload is directed to children under 13, with one typed answer and probability per FTC factor
  (16 CFR 312.2) and the lines that show it;
- compares that with the uploader's made-for-kids setting (a kids-directed video set "not made for kids" by a channel
  default is the pattern in the FTC's 2025 Disney order);
- when it is kids-directed, lists what has to change: comments, personalised ads, links, requests for children's
  details, undisclosed paid promotion, AI labels, and for apps purchases, third-party ads and analytics;
- seals a named reviewer's designation into a signed review record.

Work step by step. Show me each command before running anything that needs sudo, and stop if a check fails.

**Before anything else, remind me:**
- This is a pre-flight and a review record. It is not a COPPA compliance determination and not legal advice; a named
  person makes the designation.
- Unreleased episodes, trailers and app builds stay on this machine: the model route stays local (`direct`).
- It never needs children's personal data. Do not paste real children's names, comments or messages into it.

Repeat these points in your final summary.

## 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/kids-content-preflight.zip (4 KB, 13 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 kids-content-preflight` (the api image carries the same bundle under /app/rehearsal/kids-content-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 kids-content-preflight --bundle kids-content-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 counting song is assessed as made for kids", "the channel-default 'not made for kids' setting is a high-severity mismatch", "the mismatch is rated high"). 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.

## What you are building

| service | image | model | port |
|---|---|---|---|
| `llm` | `${DECOSA_REGISTRY}/decosa-llm:0.1.0` (vLLM 0.29.0, `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1`) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0 | internal 8000 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU; ffmpeg and Tesseract inside) | none | `127.0.0.1:8445` |
| `diarize` (optional, videos without a transcript) | built from the decosa-api source (`services/diarize`) | `OpenMOSS-Team/MOSS-Transcribe-Diarize` @ `704aa4a9c304e8520be88901e0d1960158ef5b15`, Apache-2.0 | internal 8092 |

Titles, descriptions, transcripts and app listings need only `llm` and `api`. Frame OCR runs inside `api`.

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 48 GB and driver 580 or newer.
   - Blackwell (RTX PRO 6000, B200): use the defaults below (NVFP4). This is the measured setup.
   - Hopper (H100/H200) or 48 GB Ada/L40S: set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8` and `LLM_REVISION=main`; on 48 GB also
     set `LLM_MAX_LEN=32768`. Not measured.
   - Under 48 GB: stop and tell me it will not fit.
2. Check `docker --version`, `docker compose version` and `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the
   NVIDIA Container Toolkit is missing, install them from the official Docker and NVIDIA repositories
   (`sudo nvidia-ctk runtime configure --runtime=docker`, then restart Docker).
3. Confirm about 60 GB of free disk.

## 2. Get the images

The images are **on request** while self-host is in early access: ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry (set it as `DECOSA_REGISTRY`), pull access and the compose file.
1. Try `docker pull ${DECOSA_REGISTRY}/decosa-{llm,api}:0.1.0`.
2. If a pull fails, build from source once the `decosa-api` source is published. Clone it, then run
   `docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .` in it, and
   `docker compose build llm` from its compose file.
3. If neither works, stop and tell me.

## 3. Write the compose file

Create `~/decosa-kids/.env`:

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_MAX_LEN=65536
LLM_GPU_UTIL=0.85
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Studios trust and safety>"
```

Create `~/decosa-kids/docker-compose.yml` with exactly these services:

```yaml
name: decosa-kids
x-health: &health
  interval: 15s
  timeout: 5s
  retries: 5
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:${DECOSA_TAG}
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--language-model-only", "--max-model-len", "${LLM_MAX_LEN}", "--gpu-memory-utilization", "${LLM_GPU_UTIL}",
              "--max-num-seqs", "16", "--kv-cache-dtype", "fp8_e4m3", "--speculative-config", '{"method":"mtp","num_speculative_tokens":3}',
              "--seed", "0", "--enable-force-include-usage", "--disable-uvicorn-access-log", "--host", "0.0.0.0", "--port", "8000"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)"], start_period: 900s }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy } }
    environment:
      DECOSA_LLM_ROUTE: direct                  # local model only; receipts are signed by this box's key ("attested")
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_LOCAL_SIGNING: "on"                # Ed25519 key created at /data/attest/ed25519.pem on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "200000"        # per session; one upload needs about 800 generated tokens
      DECOSA_SESSION_TTL_S: "28800"
      DECOSA_DIARIZE_URL: ""                    # set to http://diarize:8092 with the optional service (step 4)
      DECOSA_KIDS_VISION: "0"                   # the served model above is --language-model-only; see step 4
      DECOSA_CORS_ORIGIN_REGEX: '^https?://(localhost|127\.0\.0\.1)(:\d+)?$$'
    ports: ["127.0.0.1:8445:8445"]
    volumes: [decosa-data:/data]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/healthz', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, decosa-data: {} }
```

Use the named volume `decosa-data` as written: a host bind mount owned by root makes the API fail on `/data/keys.sqlite`.
1. Run `docker compose up -d`.
2. Poll `docker compose ps` until both services are healthy. The LLM takes 5-10 minutes the first time.
3. `curl -s localhost:8445/healthz` should show `"llm": true`.

## 4. Optional: speech to text and frame descriptions

- **Videos without a transcript.** Build `services/diarize` from the decosa-api source on a CUDA PyTorch base image, with
  the env `DIARIZE_HOST=0.0.0.0 DIARIZE_PORT=8092 DIARIZE_DEVICE=cuda:0`, the `hf-cache` volume, the same GPU and a health
  check on `GET /health`. Lower `LLM_GPU_UTIL` to 0.80 and set `DECOSA_DIARIZE_URL: http://diarize:8092` on the api. A
  video sent to `/kids/check` without a transcript is then transcribed, with a signed speech receipt. The fit beside the
  LLM is an estimate, not measured.
- **Frame descriptions (vision).** Only if you serve the model with its vision tower: drop `--language-model-only`, then
  set `DECOSA_KIDS_VISION: "1"`. Requests that send `"vision": true` then have 4 frames described by the model. Not
  measured on this setup.

## 5. Smoke test

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"kids-content-preflight"}' | jq -r .token)
curl -s $API/kids/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"sample":"preschool-puppet","stream":false}' > /tmp/kids.json
jq '{status, designation: .report.assessment.designation, p: .report.assessment.p_made_for_kids,
     setting: .report.consistency.status, severity: .report.consistency.severity, flags: [.report.flags[].id],
     receipts: (.receipts|length), statuses: [.receipts[].status] | unique}' /tmp/kids.json
RUN=$(jq -r .run_id /tmp/kids.json)
curl -s $API/kids/runs/$RUN/signoff -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"Test Reviewer","role":"trust and safety","designation":"made_for_kids","setting_action":"will_change","confirm":true}' \
  | jq '{record}' | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok}'
```

The sample is a synthetic preschool counting song with a puppet, uploaded under a channel default of "not made for kids",
with comments and personalised ads on and a sign-up link. Pass if:
- the designation is `made_for_kids` and the setting check is `mismatch`, severity `high`;
- the flags include `comments_on`, `personalized_ads` and `data_requests`;
- every receipt has `"status": "attested"`;
- the record verifies (`ok: true`).

Then a harder case and a back-catalogue audit:

```bash
curl -s $API/kids/check -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"parenting-vlog","stream":false}' \
  | jq '{designation: .report.assessment.designation, setting: .report.consistency.status}'
curl -s $API/kids/batch -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"catalogue-audit"}' \
  | jq -r '.items[] | "\(.setting_status)\t\(.p_made_for_kids)\t\(.title)"'
```

Pass if the parenting vlog (a toddler on screen, made for parents) is `not_made_for_kids` and `consistent`, and the
catalogue shows the unset lullaby video as `not_set`. The mock-data rehearsal runs the same checks:
`docker compose exec api python scripts/rehearse.py kids-content-preflight --base-url http://127.0.0.1:8445`.

## 6. Point the app at the local API

- The base URL is `http://localhost:8445` (web app: `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`). Add other origins to
  `DECOSA_CORS_ORIGINS`.
- `POST /kids/check` takes `{kind, title, description, tags, transcript, on_screen_text, app, setting: {made_for_kids,
  source}, features, performers?}` or a `video_b64`, and returns JSON or streams Server-Sent Events with
  `Accept: text/event-stream`. `GET /kids/info` lists the factors, the feature names and the rules with their dates.
- For a back catalogue, send up to 25 uploads at a time to `POST /kids/batch` (audience and setting only; add
  `"stream": true` for NDJSON), then run the mismatches through `/kids/check` for the full factors and flags.
- The server keeps reports in memory for one hour and deletes uploaded videos when the run ends. Keep each signed review
  record (JSON) with the upload's history. Anyone can re-check it with `POST /record/verify` against the key at
  `GET /attest/signing-key`.
- Keep the API on 127.0.0.1. For other users on the LAN, put a TLS reverse proxy with authentication in front and set
  `DECOSA_TRUSTED_PROXIES`.

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send prompts, which contain the upload's text, to the hosted Decosa
API. Leave it off for
unreleased content.

Finish with a summary: what is running, the health output, the smoke-test results, and the reminders above.