Update app.py

app.py

@@ -1,7 +1,10 @@
 """Caption Preference Study — Gradio Space.
 
-Participants see an image and two captions (human vs. model) and pick a
-preference. State is persisted across Space restarts via a private HF dataset.
+Participants register with their full name + email, then see an image and two
+captions (human vs. model) and pick a preference. Per-participant results are
+stored as ``firstname-lastname.csv`` in a private HF dataset. If a participant
+returns later their session resumes from wherever they left off, and if they
+have already completed the study they are told so.
 """
 
 from __future__ import annotations
@@ -10,9 +13,9 @@ import io
 import json
 import os
 import random
+import re
 import threading
 import time
-import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -33,6 +36,19 @@ CSV_PATH = Path(__file__).parent / "Qwen3-VL-8B-Instruct.csv"
 IMAGE_DIR = Path(os.environ.get("IMAGE_DIR", "/tmp/caption_experiment_images"))
 IMAGE_DIR.mkdir(parents=True, exist_ok=True)
 
+RESULTS_COLUMNS = [
+    "id",
+    "image_id",
+    "filename",
+    "type",
+    "human_caption",
+    "model_caption",
+    "preference",
+    "response_time",
+]
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+SLUG_RE = re.compile(r"[^a-z0-9]+")
+
 api = HfApi(token=HF_TOKEN)
 
 
@@ -41,12 +57,6 @@ api = HfApi(token=HF_TOKEN)
 # ---------------------------------------------------------------------------
 
 def _clean_caption(value: Any) -> str:
-    """Display captions verbatim without outer string-delimiter quotes.
-
-    pandas already unwraps CSV double-quote delimiters, but defensively strip a
-    single layer of matching outer single/double quotes if present so all
-    captions render uniformly.
-    """
     if value is None:
         return ""
     text = str(value)
@@ -65,13 +75,16 @@ TEST_DF = df[_test_mask].reset_index(drop=True)
 NONTEST_DF = df[~_test_mask].reset_index(drop=True)
 
 NONTEST_IMAGE_IDS: list = list(NONTEST_DF["image_id"].unique())
+NONTEST_IMAGE_ID_SET = set(NONTEST_IMAGE_IDS)
 IMAGE_ID_TO_FILENAMES: dict = {
     img_id: list(NONTEST_DF[NONTEST_DF["image_id"] == img_id]["filename"].unique())
     for img_id in NONTEST_IMAGE_IDS
 }
+TEST_ROW_IDS = set(int(x) for x in TEST_DF["id"]) if len(TEST_DF) else set()
+TOTAL_TRIALS_PER_PARTICIPANT = len(NONTEST_IMAGE_IDS) + len(TEST_DF)
 print(
     f"[startup] {len(df)} rows | {len(NONTEST_IMAGE_IDS)} non-test image_ids | "
-    f"{len(TEST_DF)} test rows"
+    f"{len(TEST_DF)} test rows | {TOTAL_TRIALS_PER_PARTICIPANT} trials per participant"
 )
 
 
@@ -152,16 +165,16 @@ def _save_state() -> None:
 _load_state()
 
 
-def _assign_filenames_for_participant() -> dict:
-    """Pick one filename per non-test image_id using round-robin across participants.
+def _assign_filenames(image_ids_to_assign: list) -> dict:
+    """Round-robin filename pick for a given set of image_ids.
 
-    For each image_id, keep a list of filenames that have been used since the last
-    reset. Choose uniformly at random from filenames NOT yet used. When all
-    filenames for an image_id have been used, reset and start a fresh cycle.
+    For each image_id, choose uniformly from filenames not yet used since the
+    last reset. When all filenames have been used, reset and start a fresh
+    cycle. Independent per image_id.
     """
     with _STATE_LOCK:
         assignments: dict = {}
-        for img_id in NONTEST_IMAGE_IDS:
+        for img_id in image_ids_to_assign:
             all_fns = IMAGE_ID_TO_FILENAMES[img_id]
             key = _state_key(img_id)
             used = list(_STATE["image_id_used"].get(key, []))
@@ -173,32 +186,103 @@ def _assign_filenames_for_participant() -> dict:
             used.append(chosen)
             _STATE["image_id_used"][key] = used
             assignments[img_id] = chosen
-        try:
-            _save_state()
-        except Exception as exc:  # noqa: BLE001
-            print(f"[state] WARNING: could not persist state.json ({exc}).")
+        if assignments:
+            try:
+                _save_state()
+            except Exception as exc:  # noqa: BLE001
+                print(f"[state] WARNING: could not persist state.json ({exc}).")
     return assignments
 
 
 # ---------------------------------------------------------------------------
-# Trial construction
+# Per-participant CSV + registry
 # ---------------------------------------------------------------------------
 
-def _build_trials_for_participant() -> list[dict]:
-    assignments = _assign_filenames_for_participant()
-    trials: list[dict] = []
+def _slugify(s: str) -> str:
+    s = (s or "").strip().lower()
+    s = SLUG_RE.sub("-", s)
+    return s.strip("-")
+
+
+def _participant_filename(first: str, last: str) -> str:
+    return f"results/{_slugify(first)}-{_slugify(last)}.csv"
+
+
+def _load_participant_results(participant_file: str) -> list[dict]:
+    if not HF_TOKEN:
+        return []
+    try:
+        path = hf_hub_download(
+            repo_id=RESULTS_REPO,
+            repo_type="dataset",
+            filename=participant_file,
+            token=HF_TOKEN,
+            force_download=True,
+        )
+        frame = pd.read_csv(path)
+        return frame.to_dict(orient="records")
+    except (EntryNotFoundError, RepositoryNotFoundError, FileNotFoundError):
+        return []
+    except Exception as exc:  # noqa: BLE001
+        print(f"[participant] Could not load {participant_file} ({exc})")
+        return []
+
+
+def _completed_keys(prior_results: list[dict]) -> tuple[set, set]:
+    """Return (done_nontest_image_ids, done_test_row_ids) from a CSV-loaded list."""
+    done_image_ids = set()
+    done_test_ids = set()
+    for r in prior_results:
+        try:
+            row_id = int(r["id"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        if row_id in TEST_ROW_IDS:
+            done_test_ids.add(row_id)
+            continue
+        img_id_str = str(r.get("image_id"))
+        if "test" in img_id_str.lower():
+            done_test_ids.add(row_id)
+            continue
+        img_id_val = r.get("image_id")
+        if img_id_val in NONTEST_IMAGE_ID_SET:
+            done_image_ids.add(img_id_val)
+        else:
+            try:
+                coerced = int(img_id_val)
+                if coerced in NONTEST_IMAGE_ID_SET:
+                    done_image_ids.add(coerced)
+            except (TypeError, ValueError):
+                pass
+    return done_image_ids, done_test_ids
 
-    for img_id in NONTEST_IMAGE_IDS:
+
+def _is_complete(prior_results: list[dict]) -> bool:
+    done_image_ids, done_test_ids = _completed_keys(prior_results)
+    return done_image_ids >= NONTEST_IMAGE_ID_SET and done_test_ids >= TEST_ROW_IDS
+
+
+def _build_remaining_trials(prior_results: list[dict]) -> list[dict]:
+    done_image_ids, done_test_ids = _completed_keys(prior_results)
+
+    remaining_image_ids = [
+        iid for iid in NONTEST_IMAGE_IDS if iid not in done_image_ids
+    ]
+    assignments = _assign_filenames(remaining_image_ids)
+
+    trials: list[dict] = []
+    for img_id in remaining_image_ids:
         fn = assignments[img_id]
         match = NONTEST_DF[
             (NONTEST_DF["image_id"] == img_id) & (NONTEST_DF["filename"] == fn)
         ]
         if match.empty:
             continue
-        row = match.iloc[0]
-        trials.append(_row_to_trial(row))
+        trials.append(_row_to_trial(match.iloc[0]))
 
     for _, row in TEST_DF.iterrows():
+        if int(row["id"]) in done_test_ids:
+            continue
         trials.append(_row_to_trial(row))
 
     random.shuffle(trials)
@@ -206,12 +290,16 @@ def _build_trials_for_participant() -> list[dict]:
 
 
 def _row_to_trial(row: pd.Series) -> dict:
+    raw_image_id = row["image_id"]
+    if isinstance(raw_image_id, (int,)) or (
+        isinstance(raw_image_id, str) and raw_image_id.lstrip("-").isdigit()
+    ):
+        image_id_out: Any = int(raw_image_id)
+    else:
+        image_id_out = str(raw_image_id)
     return {
         "id": int(row["id"]),
-        "image_id": (
-            int(row["image_id"]) if str(row["image_id"]).lstrip("-").isdigit()
-            else str(row["image_id"])
-        ),
+        "image_id": image_id_out,
         "filename": str(row["filename"]),
         "type": str(row["type"]),
         "human_caption": str(row["human_caption"]),
@@ -220,91 +308,213 @@ def _row_to_trial(row: pd.Series) -> dict:
     }
 
 
-# ---------------------------------------------------------------------------
-# Results persistence
-# ---------------------------------------------------------------------------
-
-def _save_results(session_id: str, results: list[dict]) -> None:
+def _save_results(participant_file: str, results: list[dict]) -> None:
     if not HF_TOKEN or not results:
         return
-    frame = pd.DataFrame(
-        results,
-        columns=[
-            "id",
-            "image_id",
-            "filename",
-            "type",
-            "human_caption",
-            "model_caption",
-            "preference",
-            "response_time",
-        ],
-    )
+    frame = pd.DataFrame(results, columns=RESULTS_COLUMNS)
     buf = io.BytesIO()
     frame.to_csv(buf, index=False)
     buf.seek(0)
     api.upload_file(
         path_or_fileobj=buf,
-        path_in_repo=f"results/{session_id}.csv",
+        path_in_repo=participant_file,
         repo_id=RESULTS_REPO,
         repo_type="dataset",
-        commit_message=f"Update results for {session_id} (n={len(results)})",
+        commit_message=f"Update {participant_file} (n={len(results)})",
     )
 
 
+def _load_participants_registry() -> dict:
+    if not HF_TOKEN:
+        return {}
+    try:
+        path = hf_hub_download(
+            repo_id=RESULTS_REPO,
+            repo_type="dataset",
+            filename="participants.json",
+            token=HF_TOKEN,
+            force_download=True,
+        )
+        with open(path) as f:
+            return json.load(f)
+    except (EntryNotFoundError, RepositoryNotFoundError, FileNotFoundError):
+        return {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"[participants] Could not load registry ({exc})")
+        return {}
+
+
+_REGISTRY_LOCK = threading.Lock()
+
+
+def _register_participant(slug: str, first: str, last: str, email: str) -> None:
+    if not HF_TOKEN:
+        return
+    with _REGISTRY_LOCK:
+        registry = _load_participants_registry()
+        entry = registry.get(slug, {})
+        now_iso = datetime.now(timezone.utc).isoformat()
+        if not entry:
+            entry = {
+                "full_name": f"{first} {last}".strip(),
+                "first_name": first,
+                "last_name": last,
+                "email": email,
+                "registered_at": now_iso,
+                "last_session_at": now_iso,
+            }
+        else:
+            entry.setdefault("first_name", first)
+            entry.setdefault("last_name", last)
+            entry.setdefault("registered_at", now_iso)
+            entry["full_name"] = f"{first} {last}".strip()
+            entry["email"] = email
+            entry["last_session_at"] = now_iso
+        registry[slug] = entry
+        payload = json.dumps(registry, indent=2).encode()
+        try:
+            api.upload_file(
+                path_or_fileobj=io.BytesIO(payload),
+                path_in_repo="participants.json",
+                repo_id=RESULTS_REPO,
+                repo_type="dataset",
+                commit_message=f"Register/update participant {slug}",
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"[participants] WARNING: could not save registry ({exc}).")
+
+
 # ---------------------------------------------------------------------------
 # Gradio handlers
 # ---------------------------------------------------------------------------
 
 WELCOME_HTML = """
-<div style="text-align:center; padding: 16px;">
+<div style="text-align:center; padding: 12px 16px 4px;">
   <h2 style="margin-bottom: 8px;">Caption Preference Study</h2>
-  <p style="font-size: 1.05em;">
+  <p style="font-size: 1.05em; margin: 0;">
     You will see images with two captions. Click the caption that better
     describes the image.
   </p>
 </div>
 """
 
-DONE_HTML = """
+DONE_NEW_HTML = """
 <div style="text-align:center; padding: 32px;">
   <h2>All done — thank you for participating!</h2>
   <p>You can close this tab now.</p>
 </div>
 """
 
+DONE_ALREADY_HTML_TMPL = """
+<div style="text-align:center; padding: 32px;">
+  <h2>You've already completed this study.</h2>
+  <p>Thank you, {name}! Our records show you finished all
+  {total} trials. There's nothing more to do — feel free to close this tab.</p>
+</div>
+"""
 
-def start_session():
-    session_id = str(uuid.uuid4())
-    trials = _build_trials_for_participant()
-    if not trials:
+
+def _validation_error(message: str):
+    return (
+        None,                                  # state
+        gr.update(visible=True),               # intro
+        gr.update(visible=False),              # trial group
+        gr.update(visible=False, value=""),    # done panel
+        None,                                  # image
+        gr.update(value=""),                   # left button
+        gr.update(value=""),                   # right button
+        "",                                    # progress
+        gr.update(value=message, visible=True),  # error markdown
+    )
+
+
+def start_session(first_name: str, last_name: str, email: str):
+    first = (first_name or "").strip()
+    last = (last_name or "").strip()
+    email_v = (email or "").strip()
+
+    if not first:
+        return _validation_error("Please enter your **first name**.")
+    if not last:
+        return _validation_error("Please enter your **last name**.")
+    if not EMAIL_RE.match(email_v):
+        return _validation_error("Please enter a valid **email address**.")
+
+    slug_first = _slugify(first)
+    slug_last = _slugify(last)
+    if not slug_first or not slug_last:
+        return _validation_error(
+            "Your name must include at least one letter or digit."
+        )
+
+    participant_file = _participant_filename(first, last)
+    prior = _load_participant_results(participant_file)
+
+    if _is_complete(prior):
+        msg = DONE_ALREADY_HTML_TMPL.format(
+            name=f"{first} {last}",
+            total=TOTAL_TRIALS_PER_PARTICIPANT,
+        )
+        # Still log that they came back (no overwrite of prior CSV).
+        threading.Thread(
+            target=_register_participant,
+            args=(f"{slug_first}-{slug_last}", first, last, email_v),
+            daemon=True,
+        ).start()
         return (
             None,
             gr.update(visible=False),
             gr.update(visible=False),
-            gr.update(value="<h3>No trials available.</h3>", visible=True),
+            gr.update(value=msg, visible=True),
             None,
+            gr.update(value=""),
+            gr.update(value=""),
             "",
+            gr.update(value="", visible=False),
+        )
+
+    trials = _build_remaining_trials(prior)
+    if not trials:
+        # Defensive: no trials remaining but not "complete" by the strict
+        # check — treat as done so the participant isn't stuck.
+        msg = DONE_ALREADY_HTML_TMPL.format(
+            name=f"{first} {last}",
+            total=TOTAL_TRIALS_PER_PARTICIPANT,
+        )
+        return (
+            None,
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(value=msg, visible=True),
+            None,
+            gr.update(value=""),
+            gr.update(value=""),
             "",
-            "",
+            gr.update(value="", visible=False),
         )
+
+    _register_participant(f"{slug_first}-{slug_last}", first, last, email_v)
+
     state = {
-        "session_id": session_id,
+        "participant_file": participant_file,
         "trials": trials,
         "current_idx": 0,
         "trial_start_time": time.time(),
-        "results": [],
+        "results": list(prior),
+        "prior_count": len(prior),
+        "total_trials": TOTAL_TRIALS_PER_PARTICIPANT,
     }
     img_path, left, right, progress = _current_display(state)
     return (
         state,
-        gr.update(visible=False),
-        gr.update(visible=True),
-        gr.update(visible=False),
-        img_path,
-        left,
-        right,
-        progress,
+        gr.update(visible=False),                          # intro
+        gr.update(visible=True),                           # trial group
+        gr.update(value="", visible=False),                # done panel
+        img_path,                                          # image
+        gr.update(value=left),                             # left button
+        gr.update(value=right),                            # right button
+        progress,                                          # progress
+        gr.update(value="", visible=False),                # error
     )
 
 
@@ -317,13 +527,23 @@ def _current_display(state: dict) -> tuple:
         left, right = trial["human_caption"], trial["model_caption"]
     else:
         left, right = trial["model_caption"], trial["human_caption"]
-    progress = f"Trial {state['current_idx'] + 1} of {len(state['trials'])}"
+    completed = state["prior_count"] + state["current_idx"]
+    total = state["total_trials"]
+    progress = f"Trial {completed + 1} of {total}"
     return img_path, left, right, progress
 
 
 def _make_choice(state: dict, side: str):
     if state is None:
-        return state, gr.update(), gr.update(), None, "", "", ""
+        return (
+            state,
+            gr.update(visible=False),
+            gr.update(visible=False),
+            None,
+            gr.update(value=""),
+            gr.update(value=""),
+            "",
+        )
     elapsed = min(time.time() - state["trial_start_time"], RESPONSE_TIME_CAP)
     trial = state["trials"][state["current_idx"]]
     chose_human = trial["human_on_left"] if side == "left" else not trial["human_on_left"]
@@ -340,24 +560,23 @@ def _make_choice(state: dict, side: str):
         }
     )
 
-    # Persist after each trial. Fire-and-forget on a background thread so the UI
-    # advances immediately; failures are logged but don't block the participant.
     threading.Thread(
         target=_save_results,
-        args=(state["session_id"], list(state["results"])),
+        args=(state["participant_file"], list(state["results"])),
         daemon=True,
     ).start()
 
     state["current_idx"] += 1
     if state["current_idx"] >= len(state["trials"]):
+        total = state["total_trials"]
         return (
             state,
             gr.update(visible=False),
-            gr.update(visible=True, value=DONE_HTML),
+            gr.update(value=DONE_NEW_HTML, visible=True),
             None,
-            "",
-            "",
-            f"Done — {len(state['trials'])} / {len(state['trials'])}",
+            gr.update(value=""),
+            gr.update(value=""),
+            f"Done — {total} / {total}",
         )
 
     state["trial_start_time"] = time.time()
@@ -367,8 +586,8 @@ def _make_choice(state: dict, side: str):
         gr.update(visible=True),
         gr.update(visible=False),
         img_path,
-        left,
-        right,
+        gr.update(value=left),
+        gr.update(value=right),
         progress,
     )
 
@@ -387,6 +606,7 @@ custom_css = """
     text-align: left !important;
 }
 .center-img img { max-height: 60vh !important; object-fit: contain !important; }
+.form-error { color: #b91c1c !important; }
 """
 
 with gr.Blocks(title="Caption Preference Study", css=custom_css) as demo:
@@ -398,8 +618,20 @@ with gr.Blocks(title="Caption Preference Study", css=custom_css) as demo:
         with gr.Row():
             with gr.Column(scale=1):
                 pass
-            with gr.Column(scale=1):
+            with gr.Column(scale=2):
+                first_input = gr.Textbox(
+                    label="First name", placeholder="e.g. Jane", max_lines=1
+                )
+                last_input = gr.Textbox(
+                    label="Last name", placeholder="e.g. Smith", max_lines=1
+                )
+                email_input = gr.Textbox(
+                    label="Email address",
+                    placeholder="you@example.com",
+                    max_lines=1,
+                )
                 start_btn = gr.Button("Start", variant="primary", size="lg")
+                error_md = gr.Markdown("", visible=False, elem_classes=["form-error"])
             with gr.Column(scale=1):
                 pass
 
@@ -420,8 +652,18 @@ with gr.Blocks(title="Caption Preference Study", css=custom_css) as demo:
 
     start_btn.click(
         start_session,
-        inputs=[],
-        outputs=[state, intro, trial_group, done_panel, image, left_btn, right_btn, progress],
+        inputs=[first_input, last_input, email_input],
+        outputs=[
+            state,
+            intro,
+            trial_group,
+            done_panel,
+            image,
+            left_btn,
+            right_btn,
+            progress,
+            error_md,
+        ],
     )
 
     left_btn.click(