Check generated product images

# Assemble Decosa honest product imagery on this machine

You are setting up a self-hosted checker for AI-made product and lifestyle images on this Linux machine, for an
e-commerce seller, a DTC brand or the agency that makes their images. It:
- compares an AI image with photos of the real product: net quantity and count, colour (CIEDE2000), pack text and claims
  (read by the document reader), the logo, warnings, and parts or extra units the product does not have, plus a
  side-by-side comparison by Qwen3.8-27B;
- refuses any image with a person in it unless each person is a consent-ledger identity whose consent covers this
  advertising use;
- writes IPTC metadata (and Amazon's synthetic-performer keyword when it applies), burns in a label where New York
  s.396-b or EU AI Act Art. 50(4) asks for a visible one, adds a C2PA credential and seals a signed 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 an automated aid, not legal advice or a statement that a listing or ad is lawful. A person should look at every
  flagged image and a sample of the passing ones.
- Unreleased products and model shoots stay on this machine: the model route stays local (`direct`).
- It checks images; it does not generate them.

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/honest-product-imagery.zip (404 KB, 11 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 honest-product-imagery` (the api image carries the same bundle under /app/rehearsal/honest-product-imagery/;
   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 honest-product-imagery --bundle honest-product-imagery.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 750 ml image is not approved", "the size misrepresentation is named", "no image is released for it"). 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, **with its vision tower** | internal 8000 |
| `parser` | `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1` | `PaddlePaddle/PaddleOCR-VL-1.6` @ `c5630abae1d940eafe0697512a0325494b02ab42`, Apache-2.0 | internal 8000 |
| `docreader` | built from `services/docreader` in decosa-api (no published image yet) | `docling-project/docling-layout-heron` @ `8f39ad3c0b4c58e9c2d2c84a38465abf757272d8` (MIT + Apache-2.0) | internal 8497 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU; Tesseract and c2pa inside) | none | `127.0.0.1:8445` |

`parser` and `docreader` together are the document reader block (measured 5.7 GB peak on a shared 96 GB card). Without
them the checker still runs (the pixel checks and the model), but printed quantities, claims and warnings
are then judged by the model only, so those findings stay warnings for a person.

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. You need one NVIDIA GPU with at least 64 GB (the measured setup is an RTX PRO 6000 96 GB) and driver
   580 or newer. The document reader adds about 6 GB.
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 repositories
   (`sudo nvidia-ctk runtime configure --runtime=docker`, then restart Docker).
3. Confirm about 70 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: in it,
   `docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`, and `docker compose build llm`.
3. Build the document reader: `docker build -t decosa-docreader:local services/docreader`, and download the parser weights:
   `hf download PaddlePaddle/PaddleOCR-VL-1.6 --revision c5630abae1d940eafe0697512a0325494b02ab42 --local-dir ~/models/PaddleOCR-VL-1.6`.
4. If none of this works, stop and tell me.

## 3. Write the compose file

Create `~/decosa-imagery/.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.80
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Brand studio team>"
```

Create `~/decosa-imagery/docker-compose.yml`:

```yaml
name: decosa-imagery
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]
    # no --language-model-only: the checker sends images (up to 3 per call)
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--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}',
              "--limit-mm-per-prompt", '{"image":4,"video":0}', "--seed", "0", "--enable-force-include-usage", "--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 }
  parser:
    image: vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    ipc: host
    restart: unless-stopped
    volumes: ["${HOME}/models/PaddleOCR-VL-1.6:/model:ro"]    # read-only weights; nothing is written here
    command: ["/model", "--served-model-name", "PaddlePaddle/PaddleOCR-VL-1.6", "--trust-remote-code", "--max-model-len", "8192",
              "--gpu-memory-utilization", "0.04", "--max-num-seqs", "16", "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0",
              "--generation-config", "vllm", "--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: 600s }
  docreader:
    image: decosa-docreader:local
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    restart: unless-stopped
    depends_on: { parser: { condition: service_healthy } }
    environment:
      DOCREADER_PARSER: paddle-openai
      DOCREADER_PARSER_URL: http://parser:8000/v1
      DOCREADER_PARSER_MODEL: PaddlePaddle/PaddleOCR-VL-1.6
    volumes: [docreader-models:/models]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8497/health', timeout=4)"], start_period: 600s }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, docreader: { 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_DOCREADER_URL: http://docreader:8497
      DECOSA_LOCAL_SIGNING: "on"
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_PROVENANCE_DIR: /provenance        # C2PA signing material (step 4)
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "200000"
      DECOSA_CORS_ORIGIN_REGEX: '^https?://(localhost|127\.0\.0\.1)(:\d+)?$$'
    ports: ["127.0.0.1:8445:8445"]
    volumes: [decosa-data:/data, decosa-provenance:/provenance]
    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: {}, docreader-models: {}, decosa-data: {}, decosa-provenance: {} }
```

Use the named volumes as written: a host bind mount owned by root makes the API fail on `/data/keys.sqlite` (the api image
owns `/data`).

## 4. Start it and create the C2PA signing material

1. `docker compose up -d llm parser docreader`, then `docker compose run --rm api python scripts/provenance_devcert.py` (a
   development CA and signer in the `decosa-provenance` volume; public C2PA validators will show it as untrusted until you
   use a certificate from a C2PA-trusted CA).
2. `docker compose up -d`, then poll `docker compose ps` until all four are healthy (the LLM takes 5-10 minutes the first time).
3. `curl -s localhost:8445/imagery/info | jq '{reader, model: .model.route, record}'`: reader `on`, route `direct`,
   `record.signed: true`.

## 5. The consent ledger for your models

The hosted demo checks fictional `id_demo-*` identities only. For your own models, enrol each consent in the consent
ledger (tool 47, `POST /consent/entries`) with the scope, purpose `advertising`, projects, territories, pay and
duration the model agreed to (the New York Fashion Workers Act asks for scope, purpose, rate of pay and duration), and pass
the identity ids as `people` with the `project`. A synthetic performer (an AI person who resembles no one) is enrolled as
a `fictional` identity so it is labelled as one.

## 6. Smoke test

```bash
cd ~/decosa-imagery && docker compose exec api python scripts/rehearse.py honest-product-imagery --base-url http://127.0.0.1:8445
```

Then run two samples by hand:

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"honest-product-imagery"}' | jq -r .token)
for s in size-750ml no-identity faithful-cafe; do
  curl -s $API/imagery/runs -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
    -d "{\"sample\":\"$s\",\"stream\":false}" | jq -c '{status, verdict, receipts: (.receipts|length)}'
done
```

Pass if `size-750ml` is `not_approved` with a `size` violation, `no-identity` is `consent_refused` before any comparison,
and `faithful-cafe` is `approved`; `GET /imagery/runs/<run_id>/image` then returns a JPEG whose XMP carries
`Iptc4xmpExt:DigitalSourceType` and which carries a C2PA credential, and its record verifies at `POST /record/verify`.
Every model call receipt is `attested`.

## 7. Point your tools at it

- The console on the Decosa site talks to `NEXT_PUBLIC_DECOSA_API`; set it to `http://127.0.0.1:8445` for a local build.
- From your own pipeline, `POST /imagery/runs` with `reference_b64` (1-3 product photos), `image_b64`, `facts`, `people`,
  `project`, `territory`, `targets` and `role`; keep the approved JPEG as delivered, because re-saving it through a tool
  that strips metadata removes the IPTC tag and the credential.