deploy 4-style study

.gitattributes

@@ -33,3 +33,163 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0000_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0000_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0001_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0001_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0002_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0002_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0003_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0003_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0004_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0004_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0005_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0005_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0006_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0006_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0007_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0007_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0008_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0008_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0009_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0009_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0010_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0010_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0011_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0011_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0012_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0012_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0013_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0013_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0014_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0014_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0015_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0015_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0016_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0016_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0017_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0017_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0018_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0018_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0019_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0019_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0020_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0020_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0021_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0021_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0022_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0022_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0023_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0023_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0024_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0024_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0025_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0025_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0026_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0026_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0027_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0027_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0028_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0028_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0029_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0029_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0030_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0030_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0031_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0031_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0032_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0032_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0033_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0033_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0034_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0034_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0035_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0035_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0036_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0036_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0037_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0037_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0038_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0038_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0039_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0039_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0040_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0040_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0041_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0041_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0042_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0042_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0043_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0043_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0044_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0044_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0045_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0045_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0046_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0046_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0047_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0047_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0048_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0048_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0049_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0049_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0050_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0050_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0051_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0051_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0052_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0052_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0053_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0053_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0054_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0054_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0055_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0055_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0056_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0056_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0057_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0057_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0058_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0058_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0059_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0059_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0060_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0060_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0061_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0061_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0062_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0062_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0063_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0063_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0064_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0064_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0065_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0065_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0066_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0066_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0067_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0067_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0068_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0068_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0069_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0069_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0070_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0070_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0071_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0071_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0072_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0072_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0073_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0073_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0074_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0074_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0075_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0075_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0076_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0076_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0077_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0077_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0078_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0078_R.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0079_L.png filter=lfs diff=lfs merge=lfs -text
+app/static/imgs/0079_R.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,10 @@
 ---
 title: Image Preference Study
-emoji: 💻
-colorFrom: purple
-colorTo: green
+emoji: 🖼️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+A short 2-alternative forced-choice image preference study.

app/main.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python
+"""Human-preference study (2AFC pairwise) — SD3.5-Medium ImageReward-guided vs vanilla, 4 styles.
+Accepted T2I protocol (Imagen/Parti/Emu/Diffusion-DPO): two questions/pair (overall preference + prompt
+alignment), tie option, neutral labels, left/right randomized, gold catch trials, email-gated (one
+submission/person). SQLite backend, JSON API + single-page UI.
+
+Run:  ./env/bin/python -m uvicorn human_study.app.main:app --host 0.0.0.0 --port 8000
+DB:   human_study/data/study.db    Manifest: human_study/data/pairs.json
+Admin: GET /api/stats?key=$STUDY_ADMIN_KEY   GET /api/export?key=...  (CSV)
+"""
+import json, os, sqlite3, time, uuid, random, csv, io, shutil
+from pathlib import Path
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.responses import HTMLResponse, PlainTextResponse
+from fastapi.staticfiles import StaticFiles
+
+HERE = Path(__file__).resolve().parent
+# STUDY_DATA (pairs.json + study.db) and STUDY_STATIC (index.html + imgs/) are env-overridable so the same
+# app code can host multiple independent studies (e.g. the 4-style study and a photo-only study).
+DATA = Path(os.environ.get("STUDY_DATA", str(HERE.parent / "data")))
+STATIC = Path(os.environ.get("STUDY_STATIC", str(HERE / "static")))
+DB = DATA / "study.db"
+PAIRS = {p["pair_id"]: p for p in json.load(open(DATA / "pairs.json"))}
+ADMIN_KEY = os.environ.get("STUDY_ADMIN_KEY", "rsfg-admin")
+
+# Durable storage on Hugging Face Spaces (ephemeral disk): restore the response DB from a private Dataset on
+# startup, back it up after every submission. No-op when the env vars are unset (e.g. local runs).
+PERSIST_REPO = os.environ.get("HF_PERSIST_REPO")          # e.g. "bs82/image-study-db"
+STUDY_NAME = os.environ.get("STUDY_NAME", "study")        # subfolder in the Dataset (one per study)
+HF_TOKEN = os.environ.get("HF_TOKEN")
+_DB_IN_REPO = f"{STUDY_NAME}/study.db"
+
+def restore_db():
+    if not (PERSIST_REPO and HF_TOKEN):
+        return
+    try:
+        from huggingface_hub import hf_hub_download
+        p = hf_hub_download(PERSIST_REPO, _DB_IN_REPO, repo_type="dataset", token=HF_TOKEN)
+        shutil.copy(p, DB)
+        print(f"[persist] restored DB from {PERSIST_REPO}:{_DB_IN_REPO}")
+    except Exception as e:
+        print(f"[persist] no prior DB ({e}); starting fresh")
+
+def backup_db():
+    if not (PERSIST_REPO and HF_TOKEN):
+        return
+    try:
+        from huggingface_hub import HfApi
+        HfApi(token=HF_TOKEN).upload_file(path_or_fileobj=str(DB), path_in_repo=_DB_IN_REPO,
+                                          repo_id=PERSIST_REPO, repo_type="dataset",
+                                          commit_message=f"backup {STUDY_NAME}")
+    except Exception as e:
+        print(f"[persist] backup failed: {e}")
+
+def db():
+    c = sqlite3.connect(DB); c.row_factory = sqlite3.Row; return c
+
+def init_db():
+    DATA.mkdir(parents=True, exist_ok=True)
+    with db() as c:
+        c.execute("""CREATE TABLE IF NOT EXISTS participants(
+            token TEXT PRIMARY KEY, email TEXT UNIQUE, created REAL, completed INTEGER DEFAULT 0,
+            n_catch INTEGER DEFAULT 0, n_catch_pass INTEGER DEFAULT 0, record INTEGER DEFAULT 1)""")
+        c.execute("""CREATE TABLE IF NOT EXISTS votes(
+            token TEXT, email TEXT, pair_id INTEGER, kind TEXT, style TEXT, question TEXT,
+            choice TEXT, guided_chosen INTEGER, ts REAL)""")  # guided_chosen: 1 guided, 0 vanilla, NULL tie
+restore_db()
+init_db()
+
+app = FastAPI(title="Image preference study")
+app.mount("/static", StaticFiles(directory=str(STATIC)), name="static")
+
+@app.get("/", response_class=HTMLResponse)
+def index():
+    return (STATIC / "index.html").read_text()
+
+@app.get("/api/info")
+def info():
+    n = len(PAIRS)
+    return {"n_pairs": n, "est_minutes": max(1, round(n * 3.5 / 60))}
+
+def norm_email(e):
+    e = (e or "").strip().lower()
+    if "@" not in e or "." not in e.split("@")[-1] or len(e) < 5:
+        raise HTTPException(400, "Please enter a valid email address.")
+    return e
+
+@app.post("/api/register")
+async def register(req: Request):
+    body = await req.json()
+    email = norm_email(body.get("email"))
+    record = 0 if body.get("record") is False else 1   # opt-out checkbox; default = record
+    with db() as c:
+        row = c.execute("SELECT token, completed FROM participants WHERE email=?", (email,)).fetchone()
+        if row and row["completed"]:
+            raise HTTPException(409, "This email has already completed the study. Thank you!")
+        token = row["token"] if row else uuid.uuid4().hex
+        if not row:
+            c.execute("INSERT INTO participants(token,email,created,record) VALUES(?,?,?,?)",
+                      (token, email, time.time(), record))
+        else:
+            c.execute("UPDATE participants SET record=? WHERE token=?", (record, token))
+    order = list(PAIRS.values())
+    random.Random(hash(token) & 0xffffffff).shuffle(order)
+    pairs = [{"pair_id": p["pair_id"], "prompt": p["prompt"],
+              "left": f"/static/imgs/{p['left']}", "right": f"/static/imgs/{p['right']}"} for p in order]
+    return {"token": token, "pairs": pairs}
+
+def _summarize(votes):
+    """Per-participant own results (thank-you page): one-click guided-preference counts overall + per style."""
+    overall = [0, 0]; by_style = {}
+    for v in votes:
+        p = PAIRS.get(int(v.get("pair_id", -1)))
+        ch = v.get("choice")
+        if not p or p["kind"] != "real" or ch not in ("left", "right"):
+            continue
+        gw = int(ch == p["guided_side"])
+        overall[0] += gw; overall[1] += 1
+        s = by_style.setdefault(p["style"], [0, 0]); s[0] += gw; s[1] += 1
+    return {"pref": {"guided": overall[0], "n": overall[1],
+                     "rate": (overall[0] / overall[1]) if overall[1] else None,
+                     "by_style": {k: {"guided": x[0], "n": x[1], "rate": (x[0] / x[1]) if x[1] else None}
+                                  for k, x in by_style.items()}}}
+
+@app.post("/api/submit")
+async def submit(req: Request):
+    body = await req.json()
+    token, votes = body.get("token", ""), body.get("votes", [])
+    with db() as c:
+        row = c.execute("SELECT email, completed, record FROM participants WHERE token=?", (token,)).fetchone()
+        if not row:
+            raise HTTPException(404, "Unknown session.")
+        if row["completed"]:
+            raise HTTPException(409, "Already submitted.")
+        email, record = row["email"], row["record"]
+        n_catch = n_pass = 0
+        for v in votes:
+            p = PAIRS.get(int(v.get("pair_id", -1)))
+            ch = v.get("choice")
+            if not p or ch not in ("left", "right"):
+                continue
+            if p["kind"] == "catch":
+                gc = int(ch == p["correct_side"]); n_catch += 1; n_pass += gc
+            else:
+                gc = int(ch == p["guided_side"])
+            if record:   # opt-out: skip persisting votes (results still shown to the participant)
+                c.execute("INSERT INTO votes VALUES(?,?,?,?,?,?,?,?,?)",
+                          (token, email, p["pair_id"], p["kind"], p["style"], "pref", ch, gc, time.time()))
+        c.execute("UPDATE participants SET completed=1, n_catch=?, n_catch_pass=? WHERE token=?",
+                  (n_catch, n_pass, token))
+    backup_db()
+    return {"ok": True, "recorded": bool(record), "results": _summarize(votes)}
+
+@app.get("/api/stats")
+def stats(key: str = ""):
+    if key != ADMIN_KEY:
+        raise HTTPException(403, "bad key")
+    with db() as c:
+        np_ = c.execute("SELECT COUNT(*) n FROM participants WHERE completed=1").fetchone()["n"]
+        # attentive = passed all catch preference trials
+        attn = "token IN (SELECT token FROM participants WHERE completed=1 AND n_catch_pass=n_catch AND n_catch>0)"
+        out = {"completed_participants": np_, "by_question": {}}
+        for q in ("pref", "align"):
+            rows = c.execute(f"""SELECT style, COUNT(*) n, SUM(guided_chosen) g,
+                SUM(CASE WHEN guided_chosen IS NULL THEN 1 ELSE 0 END) ties
+                FROM votes WHERE kind='real' AND question=? AND token IN
+                (SELECT token FROM participants WHERE completed=1) GROUP BY style""", (q,)).fetchall()
+            tot = c.execute(f"""SELECT COUNT(*) n, SUM(guided_chosen) g FROM votes
+                WHERE kind='real' AND question=? AND guided_chosen IS NOT NULL
+                AND token IN (SELECT token FROM participants WHERE completed=1)""", (q,)).fetchone()
+            out["by_question"][q] = {
+                "overall_n_nontie": tot["n"], "overall_guided_wins": tot["g"],
+                "overall_guided_winrate": (tot["g"]/tot["n"]) if tot["n"] else None,
+                "by_style": {r["style"]: {"n": r["n"], "guided": r["g"], "ties": r["ties"]} for r in rows}}
+    return out
+
+@app.get("/api/export")
+def export(key: str = ""):
+    if key != ADMIN_KEY:
+        raise HTTPException(403, "bad key")
+    buf = io.StringIO(); w = csv.writer(buf)
+    w.writerow(["email", "pair_id", "kind", "style", "question", "choice", "guided_chosen", "ts"])
+    with db() as c:
+        for r in c.execute("SELECT email,pair_id,kind,style,question,choice,guided_chosen,ts FROM votes ORDER BY ts"):
+            w.writerow([r["email"], r["pair_id"], r["kind"], r["style"], r["question"], r["choice"],
+                        "" if r["guided_chosen"] is None else r["guided_chosen"], r["ts"]])
+    return PlainTextResponse(buf.getvalue(), media_type="text/csv")