README.md

---
title: Echo AI Image Detector
emoji: 🔎
colorFrom: indigo
colorTo: purple
sdk: gradio
app_file: app.py
python_version: "3.10"
pinned: true
models:
  - OwensLab/commfor-model-384
---

# Echo self-hosted AI image detector

Private inference service for Echo's public-image provenance pipeline. It runs two independent, open-source classifiers and never calls a commercial detection API:

- Community Forensics `OwensLab/commfor-model-384` (MIT, official 21.8M-parameter checkpoint).
- GRIP-UNINA `clipdet_latent10k_plus` (Apache-2.0, official CLIP-based checkpoint).

The service deliberately returns both raw model results. It does not decide Echo's label; Echo's calibrated database ensemble owns that decision.

The same source can run as a free Hugging Face CPU Space. The application starts its authenticated FastAPI server directly; the `gradio` Space SDK is used only as the free Python hosting runtime. Pinned upstream source archives and the small GRIP classifier head are bootstrapped and verified at startup.

## Run locally

```bash
cd services/ai-image-detector
export DETECTOR_AUTH_TOKEN="$(openssl rand -hex 32)"
docker compose up --build
```

The first start downloads the Community Forensics and CLIP backbone weights into the named model cache. Keep that volume between deployments.

```bash
curl -H "Authorization: Bearer $DETECTOR_AUTH_TOKEN" http://127.0.0.1:8091/health
curl -H "Authorization: Bearer $DETECTOR_AUTH_TOKEN" -F file=@sample.jpg http://127.0.0.1:8091/v1/detect
```

Configure the Supabase Edge Function with:

```bash
supabase secrets set \
  SELF_HOSTED_AI_DETECTOR_URL=https://detector.internal.example \
  SELF_HOSTED_AI_DETECTOR_TOKEN="$DETECTOR_AUTH_TOKEN"
```

The URL must be HTTPS in production. Keep the service private when the hosting platform supports private networking; bearer authentication remains required.

## GPU build

The default image installs CPU-only PyTorch. For NVIDIA inference, build with a CUDA wheel index compatible with the host driver, for example:

```bash
docker build \
  --build-arg TORCH_INDEX_URL=https://download.pytorch.org/whl/cu124 \
  -t echo-ai-image-detector:gpu .
```

Run with the NVIDIA container runtime and set `DETECTOR_DEVICE=cuda`. CPU mode is useful for smoke tests and small review batches; the full public corpus should use a temporary GPU worker.

## Operational guarantees

- Maximum upload is 15 MB by default.
- Only image bytes supplied by Echo are processed; the service does not fetch arbitrary URLs.
- One inference request runs at a time per container to avoid GPU-memory spikes.
- Both models must load successfully or `/v1/detect` returns 503.
- Model source revisions are pinned in the Dockerfile.
- Model disagreement remains unknown until Echo's calibration/review layer resolves it.

These classifiers estimate likelihood. They do not prove origin, and their raw probabilities must not be presented as calibrated confidence.