README.md

metadata

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
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 (sbp_...):

# 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:

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

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)

python app.py

Open with a demo invite token:

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

Reviewer UX is specified in 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.

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

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

5. Run analytics

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
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.