---
title: Cat Image Review
emoji: 🐱
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "6.25.0"
app_file: app.py
python_version: "3.12"
pinned: false
license: mit
short_description: Private invite-link cat image review (Phase 0)
---

# Cat Image Feedback Fine-Tuning

Feedback-driven system for generating and evaluating images of specific cats. Phase 0 is a static evaluation prototype: no training or generation.

## Phase 0 scope

- Private invite links for three reviewers
- Three pages of four static candidate images each (twelve images total)
- Multi-select feedback stored in Supabase
- Batch analytics report computing acceptance rate

## Setup

### 1. Supabase project and secret key

1. Create a new project at [supabase.com](https://supabase.com)
2. Open **Settings > API Keys**, click **Create new API Keys** if needed, and copy:
   - Project URL → `SUPABASE_URL`
   - **Secret key** (`sb_secret_...`) → `SUPABASE_SECRET_KEY`  
     Use this on the backend only. It replaces the legacy `service_role` JWT (deprecated by the end of 2026). Do not put it in `Authorization: Bearer`; the Python client sends it as `apikey`.

Secret keys authenticate the Data API (review backend and analytics). They **cannot** apply schema DDL.

### 2. Apply schema (Management API or CLI)

**Recommended programmatic path** — Management API with a [personal access token](https://supabase.com/dashboard/account/tokens) (`sbp_...`):

```bash
# add SUPABASE_ACCESS_TOKEN=sbp_... to .env
python scripts/migrate_remote.py
```

That script calls `POST /v1/projects/{ref}/database/migrations` for each file in `supabase/migrations/`, then runs `supabase/seed.sql` via `POST /v1/projects/{ref}/database/query`.

**CLI equivalent:**

```bash
supabase login
supabase link --project-ref <your-project-ref>
supabase db push --include-seed
```

`supabase db push` uses your CLI login (or `SUPABASE_ACCESS_TOKEN`) plus the database password. It is not authenticated with `sb_secret_...`.

### 3. Local environment

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with SUPABASE_URL and SUPABASE_SECRET_KEY
```

### 4. Review UI (Gradio)

```bash
python app.py
```

Open with a demo invite token:

```text
http://127.0.0.1:7860/?invite=invite-reviewer-1-a7b3c9d2
```

Reviewer UX is specified in [`docs/gradio-frontend.md`](docs/gradio-frontend.md). Backend access lives in `app/db.py` (`SupabaseReviewStore`, `get_review_store()`).

**Hugging Face Space:** set Space secrets `SUPABASE_URL` and `SUPABASE_SECRET_KEY`. Entry point is root [`app.py`](app.py).

Demo invite tokens (wire into your frontend as `?invite=…`):

```
invite-reviewer-1-a7b3c9d2
invite-reviewer-2-e4f8a1b6
invite-reviewer-3-c2d5f7a9
```

### 5. Run analytics

```bash
python analytics/report.py
```

Prints acceptance-rate tables and saves charts under `analytics/output/`.

## Project layout

| Directory | Purpose |
| --- | --- |
| `app/` | Supabase review store, Gradio UI (`app/app.py`), models, config |
| `app.py` | Hugging Face Space / local Gradio entrypoint |
| `analytics/` | Feedback queries and acceptance-rate reports |
| `supabase/` | SQL migration, seed data, and [data model diagram](docs/data-model.md) |
| `data/static/` | Static candidate images for Phase 0 |
| `scripts/` | Migration and validation helpers |

## Primary metric

```
acceptance rate = accepted images / images shown
```

## Guiding principles

- Feedback is collected in batches; clicking never updates a model.
- Raw feedback is append-only; metrics are derived in analytics.
- Every image row carries provenance metadata for later version comparisons.