Restructure for challenges

README.md

@@ -5,7 +5,7 @@ colorFrom: red
 colorTo: red
 sdk: gradio
 sdk_version: 6.9.0
-app_file: main.py
+app_file: app.py
 pinned: false
 hf_oauth: true
 hf_oauth_scopes:

app.py

@@ -0,0 +1,16 @@
+import gradio as gr
+
+from challenges.home import build_home
+from challenges.object_localization.page import build_ol_page
+from challenges.answer_therapy.page import build_at_page
+from challenges.vqa.page import build_vqa_page
+
+with gr.Blocks() as demo:
+    build_home(demo)
+
+build_ol_page(demo)
+build_vqa_page(demo)
+build_at_page(demo)
+
+if __name__ == "__main__":
+    demo.launch()

auth_utils.py

@@ -0,0 +1,21 @@
+import gradio as gr
+
+from hf_utils import _count_submissions_today, _get_cap_for_phase
+
+
+def get_user_greeting(profile: gr.OAuthProfile | None) -> str:
+    if profile is None:
+        return "👋 Log in with your HuggingFace account to submit predictions."
+    return f"👤 Logged in as **{profile.username}**"
+
+
+def get_daily_cap_info(profile: gr.OAuthProfile | None, phases: list = None) -> str:
+    if profile is None:
+        return ""
+    lines = []
+    for p in phases or []:
+        cap       = _get_cap_for_phase(p["codename"])
+        used      = _count_submissions_today(profile.username, p["codename"])
+        remaining = cap - used
+        lines.append(f"**{p['label'].split('(')[0].strip()}:** {remaining}/{cap} remaining")
+    return "  \n".join(lines)

challenges/answer_therapy/config.py

@@ -0,0 +1,59 @@
+PHASES = [
+    {"label": "Dev (test-dev2025)",             "codename": "test-dev2025"},
+    {"label": "Standard (test-standard2025)",   "codename": "test-standard2025"},
+    {"label": "Challenge (test-challenge2025)", "codename": "test-challenge2025"},
+]
+
+LEADERBOARD_METRICS = [
+    "overall_f1", "overall_precision", "overall_recall",
+    "vizwiz_f1",  "vizwiz_precision",  "vizwiz_recall",
+    "vqav2_f1",   "vqa_precision",     "vqa_recall",
+]
+DEFAULT_SORT_METRIC = "overall_f1"
+LEADERBOARD_FILE    = "leaderboards/answer-therapy.jsonl"
+CHALLENGE_PHASE     = "test-challenge2025"
+SUBFOLDER           = "answer-therapy"
+CHALLENGE_TYPE      = "VQA Answer Therapy"
+
+EVAL_DETAILS_MD = """
+### How is the Score Calculated?
+
+Each entry is a binary classification: does the visual question produce answers that all
+share the **same image region** (single grounding), or do different answers point to
+**different regions** (multiple groundings)?
+
+Your `single_grounding` confidence score is thresholded at **0.5** for evaluation.
+
+| Metric | Description |
+|--------|-------------|
+| `Overall F1` | F1 score across all questions *(default ranking metric)* |
+| `Overall Precision` | Precision across all questions |
+| `Overall Recall` | Recall across all questions |
+| `VizWiz F1` | F1 on questions from the VizWiz dataset |
+| `VQAv2 F1` | F1 on questions from the VQAv2 dataset |
+
+Scores are reported as percentages (0–100).
+"""
+
+FORMAT_MD = """
+### Submission Format
+
+Your JSON file must be a **list of result objects**, one per visual question:
+
+```json
+[
+  {
+    "question_id": "VizWiz_test_000000020000.jpg",
+    "single_grounding": 0.85
+  },
+  {
+    "question_id": "249549029",
+    "single_grounding": 0.12
+  },
+  ...
+]
+```
+
+- **`question_id`** — string. Use the image filename for VizWiz questions (e.g. `VizWiz_test_00002183.jpg`) and the numeric string ID for VQAv2 questions.
+- **`single_grounding`** — float between 0.0 and 1.0. Confidence that all answers share the same grounding region. `1` = single grounding, `0` = multiple groundings.
+"""

challenges/answer_therapy/page.py

@@ -0,0 +1,283 @@
+import json
+import os
+from datetime import datetime, timezone
+
+import gradio as gr
+import pandas as pd
+
+from auth_utils import get_user_greeting, get_daily_cap_info
+from hf_utils import (
+    _load_leaderboard_df,
+    _load_user_submissions,
+    _create_submission_record,
+    _count_submissions_today,
+    _get_cap_for_phase,
+    _today_utc_str,
+)
+from config import DAILY_SUBMISSION_CAP, SUBMISSIONS_TOKEN
+from challenges.answer_therapy.config import (
+    PHASES, LEADERBOARD_METRICS, DEFAULT_SORT_METRIC,
+    LEADERBOARD_FILE, CHALLENGE_PHASE, SUBFOLDER, CHALLENGE_TYPE,
+    EVAL_DETAILS_MD, FORMAT_MD,
+)
+from challenges.answer_therapy.validate import validate_submission
+
+
+def load_leaderboard():
+    """Load VQA Answer Therapy leaderboard, filtered to challenge phase."""
+    try:
+        df = _load_leaderboard_df(LEADERBOARD_FILE, LEADERBOARD_METRICS)
+    except Exception as e:
+        return pd.DataFrame(), f"❌ Could not load leaderboard: {e}"
+
+    if not df.empty and "phase_codename" in df.columns:
+        df = df[df["phase_codename"] == CHALLENGE_PHASE]
+
+    if df.empty:
+        return pd.DataFrame(), "ℹ️ No scored Challenge phase submissions yet. Be the first!"
+
+    df = df.sort_values(by=DEFAULT_SORT_METRIC, ascending=False, kind="mergesort")
+    df_display = df.copy()
+    df_display.insert(0, "Rank", range(1, len(df_display) + 1))
+    if "timestamp" in df_display.columns:
+        df_display["Scored At"] = pd.to_datetime(
+            df_display["timestamp"], unit="s", errors="coerce"
+        ).dt.strftime("%d %b %Y, %I:%M %p")
+        df_display.drop(columns=["timestamp"], inplace=True)
+    for col in ["username", "email", "phase_codename", "submission_id"]:
+        if col in df_display.columns:
+            df_display.drop(columns=[col], inplace=True)
+
+    rename = {
+        "team": "Team", "model": "Model",
+        "overall_f1":        "Overall F1",
+        "overall_precision": "Precision (Overall)",
+        "overall_recall":    "Recall (Overall)",
+        "vizwiz_f1":         "VizWiz F1",
+        "vizwiz_precision":  "Precision (VizWiz)",
+        "vizwiz_recall":     "Recall (VizWiz)",
+        "vqav2_f1":          "VQAv2 F1",
+        "vqa_precision":     "Precision (VQA)",
+        "vqa_recall":        "Recall (VQA)",
+    }
+    df_display.rename(columns=rename, inplace=True)
+    return df_display, ""
+
+
+def handle_submit(file, team, model_name, phase_label, profile: gr.OAuthProfile | None):
+    """Handle VQA Answer Therapy submission."""
+    if profile is None:
+        return "❌ You must be logged in with your HuggingFace account to submit.", ""
+    username = profile.username
+    email = getattr(profile, "email", "") or ""
+
+    if not SUBMISSIONS_TOKEN:
+        return "❌ Missing SUBMISSIONS_TOKEN. Add it in Space Settings → Secrets.", ""
+    if file is None:
+        return "❌ Please upload a JSON file.", ""
+    if not team.strip():
+        return "❌ Please enter a Team / Display Name.", ""
+    if not model_name.strip():
+        return "❌ Please enter a Model Name.", ""
+
+    phase_codename = next((p["codename"] for p in PHASES if p["label"] == phase_label), phase_label)
+    cap = _get_cap_for_phase(phase_codename)
+    subs_today = _count_submissions_today(username, phase_codename)
+    if subs_today >= cap:
+        phase_str = "challenge" if "challenge" in phase_codename else "this"
+        return f"⛔ You've reached your daily limit of {cap} submission(s) for the {phase_str} phase. Come back tomorrow!", ""
+
+    try:
+        with open(file, "r", encoding="utf-8") as f:
+            pred_obj = json.load(f)
+    except Exception:
+        return "❌ Could not parse JSON file.", ""
+
+    ok, msg = validate_submission(pred_obj)
+    if not ok:
+        return f"❌ Invalid submission format: {msg}", ""
+
+    original_filename = os.path.basename(file)
+    try:
+        submission_id = _create_submission_record(
+            pred=pred_obj,
+            team=team,
+            model_name=model_name,
+            phase_codename=phase_codename,
+            challenge_type=CHALLENGE_TYPE,
+            original_filename=original_filename,
+            username=username,
+            email=email,
+            subfolder=SUBFOLDER,
+        )
+    except Exception as e:
+        return f"❌ Upload failed: {e}", ""
+
+    remaining = cap - subs_today - 1
+    return (
+        f"✅ Submission queued! Visit **My Submissions** to track results. "
+        f"You have {remaining}/{cap} submissions remaining today for this phase.",
+        submission_id,
+    )
+
+
+def load_my_submissions(phase_filter: str, profile: gr.OAuthProfile | None):
+    if profile is None:
+        return pd.DataFrame(), "❌ Please log in to view your submissions.", ""
+    username = profile.username
+    submissions = _load_user_submissions(username, subfolder=SUBFOLDER)
+
+    if not submissions:
+        return pd.DataFrame(), "ℹ️ No submissions yet. Head to Submit Predictions to get started!", ""
+
+    all_submissions = submissions[:]
+    if phase_filter and phase_filter != "All":
+        submissions = [s for s in submissions if s["phase"] == phase_filter]
+    if not submissions:
+        return pd.DataFrame(), f"ℹ️ No submissions found for phase **{phase_filter}**.", ""
+
+    state_icons = {"queued": "🟡", "running": "🔵", "done": "🟢", "failed": "🔴", "unknown": "⚪"}
+    df = pd.DataFrame(submissions)
+    if "timestamp" in df.columns:
+        df["Submitted At"] = pd.to_datetime(
+            df["timestamp"], unit="s", errors="coerce"
+        ).dt.strftime("%d %b %Y, %I:%M %p")
+    if "state" in df.columns:
+        df["Status"] = df["state"].apply(lambda s: f"{state_icons.get(s, '⚪')} {s.capitalize()}")
+
+    display_cols = ["Submitted At", "Status", "team", "model", "phase", "error"]
+    metric_cols  = [m for m in LEADERBOARD_METRICS if m in df.columns]
+    display_cols += metric_cols
+    df_display = df[[c for c in display_cols if c in df.columns]].copy()
+    df_display.rename(columns={
+        "team": "Team", "model": "Model", "phase": "Phase", "error": "Error",
+        "overall_f1": "Overall F1", "overall_precision": "Precision", "overall_recall": "Recall",
+        "vizwiz_f1": "VizWiz F1", "vqav2_f1": "VQAv2 F1",
+    }, inplace=True)
+    for m in metric_cols:
+        if m in df_display.columns:
+            df_display[m] = df_display[m].apply(lambda x: f"{x:.2f}" if pd.notna(x) else "")
+
+    total = len(all_submissions)
+    done  = sum(1 for s in all_submissions if s["state"] == "done")
+    today_count = sum(
+        1 for s in all_submissions
+        if datetime.fromtimestamp(s["timestamp"], tz=timezone.utc).strftime("%Y-%m-%d") == _today_utc_str()
+    )
+    stats = (
+        f"**Total:** {total}  |  "
+        f"**Scored:** {done}  |  "
+        f"**Today:** {today_count}/{DAILY_SUBMISSION_CAP}"
+    )
+    return df_display, "", stats
+
+
+def build_at_page(demo: gr.Blocks) -> None:
+    with demo.route("VQA Answer Therapy", "/answer-therapy") as at_page:
+
+        with gr.Row():
+            with gr.Column(scale=5):
+                gr.Markdown("# 📍 Answer Therapy Challenge")
+                gr.Markdown(
+                    "Predict whether answers to a visual question all share the same image region. "
+                    "Evaluated with F1, Precision, and Recall across VizWiz and VQAv2 question sets."
+                )
+            with gr.Column(scale=1, min_width=160):
+                gr.LoginButton(size="lg")
+                at_greeting = gr.Markdown("👋 Log in to submit.")
+
+        gr.Markdown("---")
+
+        with gr.Tabs():
+
+            # ── Leaderboard ──
+            with gr.TabItem("🏆 Leaderboard"):
+                gr.Markdown("### Challenge Phase Rankings")
+                gr.Markdown("Ranked by **Overall F1** (descending). Challenge phase only.")
+                with gr.Accordion("📐 How is the Score Calculated?", open=False):
+                    gr.Markdown(EVAL_DETAILS_MD)
+                at_lb_msg   = gr.Markdown("")
+                at_lb_table = gr.Dataframe(interactive=False, wrap=True)
+                at_refresh_lb_btn = gr.Button("🔄 Refresh Leaderboard", variant="secondary", size="sm")
+
+                def refresh_at_leaderboard(profile: gr.OAuthProfile | None):
+                    df, msg = load_leaderboard()
+                    return df, msg, get_user_greeting(profile)
+
+                at_refresh_lb_btn.click(refresh_at_leaderboard, outputs=[at_lb_table, at_lb_msg, at_greeting])
+                at_page.load(refresh_at_leaderboard, outputs=[at_lb_table, at_lb_msg, at_greeting])
+
+            # ── Submit ──
+            with gr.TabItem("🚀 Submit Predictions"):
+                with gr.Row():
+                    at_submit_greeting = gr.Markdown("👋 Log in with HuggingFace to submit.")
+                    at_cap_info        = gr.Markdown("")
+                gr.Markdown("---")
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        gr.Markdown("#### Upload Submission File")
+                        at_file_input = gr.File(label="Choose a JSON file", file_types=[".json"])
+                        with gr.Accordion("📄 Submission Format", open=False):
+                            gr.Markdown(FORMAT_MD)
+                    with gr.Column(scale=2):
+                        gr.Markdown("#### Submission Info")
+                        at_team_input  = gr.Textbox(label="Team / Display Name", placeholder="e.g. My Awesome Team")
+                        at_model_input = gr.Textbox(label="Model Name", placeholder="e.g. CLIP-ViT-L")
+                        at_phase_input = gr.Dropdown(
+                            label="Phase",
+                            choices=[p["label"] for p in PHASES],
+                            value=PHASES[0]["label"],
+                        )
+                at_submit_btn    = gr.Button("Submit (Queue for Evaluation)", variant="primary", size="lg")
+                at_submit_status = gr.Markdown("")
+                at_sid_box       = gr.Code(label="Submission ID", language=None, visible=False)
+
+                def do_at_submit(file, team, model_name, phase_label, profile: gr.OAuthProfile | None):
+                    msg, sid = handle_submit(file, team, model_name, phase_label, profile)
+                    return msg, gr.update(value=sid, visible=bool(sid))
+
+                at_submit_btn.click(
+                    do_at_submit,
+                    inputs=[at_file_input, at_team_input, at_model_input, at_phase_input],
+                    outputs=[at_submit_status, at_sid_box],
+                )
+
+                def update_at_submit_ui(profile: gr.OAuthProfile | None):
+                    return get_user_greeting(profile), get_daily_cap_info(profile, PHASES)
+
+                at_page.load(update_at_submit_ui, outputs=[at_submit_greeting, at_cap_info])
+
+            # ── My Submissions ──
+            with gr.TabItem("📋 My Submissions"):
+                at_my_sub_greeting = gr.Markdown("👋 Log in with HuggingFace to view your submissions.")
+                at_my_sub_stats    = gr.Markdown("")
+                with gr.Row():
+                    at_phase_filter = gr.Dropdown(
+                        label="Filter by Phase",
+                        choices=["All"] + [p["codename"] for p in PHASES],
+                        value="All",
+                        scale=2,
+                    )
+                    at_refresh_my_btn = gr.Button("🔄 Refresh", variant="secondary", scale=1)
+                at_my_sub_msg   = gr.Markdown("")
+                at_my_sub_table = gr.Dataframe(interactive=False, wrap=True)
+
+                def refresh_at_my_subs(phase_filter, profile: gr.OAuthProfile | None):
+                    df, msg, stats = load_my_submissions(phase_filter, profile)
+                    return df, msg, stats, get_user_greeting(profile)
+
+                at_refresh_my_btn.click(
+                    refresh_at_my_subs,
+                    inputs=[at_phase_filter],
+                    outputs=[at_my_sub_table, at_my_sub_msg, at_my_sub_stats, at_my_sub_greeting],
+                )
+                at_phase_filter.change(
+                    refresh_at_my_subs,
+                    inputs=[at_phase_filter],
+                    outputs=[at_my_sub_table, at_my_sub_msg, at_my_sub_stats, at_my_sub_greeting],
+                )
+                at_page.load(
+                    refresh_at_my_subs,
+                    inputs=[at_phase_filter],
+                    outputs=[at_my_sub_table, at_my_sub_msg, at_my_sub_stats, at_my_sub_greeting],
+                )

challenges/answer_therapy/validate.py

@@ -0,0 +1,24 @@
+from typing import Any, Tuple
+
+
+def validate_submission(obj: Any) -> Tuple[bool, str]:
+    """Validate VQA Answer Therapy submission format."""
+    if not isinstance(obj, list):
+        return False, "Submission must be a JSON list of result objects."
+    if len(obj) == 0:
+        return False, "Submission list is empty."
+    for i, item in enumerate(obj):
+        if not isinstance(item, dict):
+            return False, f"Entry at index {i} must be a JSON object."
+        if "question_id" not in item:
+            return False, f"Entry at index {i} missing 'question_id'."
+        if "single_grounding" not in item:
+            return False, f"Entry at index {i} missing 'single_grounding'."
+        if not isinstance(item["question_id"], str):
+            return False, f"'question_id' at index {i} must be a string."
+        sg = item["single_grounding"]
+        if not isinstance(sg, (int, float)):
+            return False, f"'single_grounding' at index {i} must be a float (0=multiple, 1=single)."
+        if not (0.0 <= float(sg) <= 1.0):
+            return False, f"'single_grounding' at index {i} must be between 0.0 and 1.0."
+    return True, "OK"

challenges/home.py

@@ -0,0 +1,99 @@
+import gradio as gr
+
+from auth_utils import get_user_greeting
+
+CHALLENGES = [
+    {
+        "id": "object-localization",
+        "title": "Object Localization",
+        "emoji": "🎯",
+        "description": "Detect and segment objects in images taken by blind photographers. Submit bounding box and instance segmentation predictions evaluated with pycocotools.",
+        "metrics": "bbox_mAP · bbox_AP50 · segm_mAP · segm_AP50",
+        "route": "/object-localization",
+        "active": True,
+    },
+    {
+        "id": "vqa",
+        "title": "Visual Question Answering",
+        "emoji": "🤔",
+        "description": "Answer open-ended questions about images taken by blind users. Models are evaluated on answer accuracy and relevance.",
+        "metrics": "Coming soon",
+        "route": "/vqa",
+        "active": True,
+    },
+    {
+        "id": "answer-therapy",
+        "title": "VQA Answer Therapy",
+        "emoji": "📍",
+        "description": "Predict whether a visual question produces answers that all share the same image region. Evaluated with F1, Precision, and Recall across VizWiz and VQAv2 subsets.",
+        "metrics": "Overall F1 · VizWiz F1 · VQAv2 F1",
+        "route": "/answer-therapy",
+        "active": True,
+    },
+]
+
+
+def _challenge_card_html(c: dict) -> str:
+    if c["active"]:
+        return f"""
+        <div style="border:2px solid #2563eb;border-radius:12px;padding:24px;
+                    background:#f0f7ff;display:flex;flex-direction:column;height:260px;box-sizing:border-box;">
+            <div style="font-size:2rem;margin-bottom:8px;">{c['emoji']}</div>
+            <h3 style="margin:0 0 6px 0;color:#1e40af;font-size:1rem;font-weight:700;">{c['title']}</h3>
+            <p style="margin:0 0 10px 0;color:#374151;font-size:0.82rem;line-height:1.45;flex:1;">{c['description']}</p>
+            <div style="background:#dbeafe;border-radius:5px;padding:4px 8px;
+                        font-size:0.72rem;color:#1d4ed8;font-family:monospace;margin-bottom:14px;">
+                📊 {c['metrics']}
+            </div>
+            <button onclick="window.location.href='{c['route']}'"
+                style="background:#2563eb;color:white;border:none;padding:8px 0;width:100%;
+                       border-radius:7px;font-size:0.85rem;font-weight:600;cursor:pointer;">
+                Enter Challenge →
+            </button>
+        </div>"""
+    else:
+        return f"""
+        <div style="border:2px solid #e5e7eb;border-radius:12px;padding:24px;
+                    background:#f9fafb;display:flex;flex-direction:column;height:260px;box-sizing:border-box;opacity:0.55;">
+            <div style="font-size:2rem;margin-bottom:8px;">{c['emoji']}</div>
+            <h3 style="margin:0 0 6px 0;color:#6b7280;font-size:1rem;font-weight:700;">{c['title']}</h3>
+            <p style="margin:0 0 10px 0;color:#9ca3af;font-size:0.82rem;line-height:1.45;flex:1;">{c['description']}</p>
+            <div style="background:#f3f4f6;border-radius:5px;padding:4px 8px;
+                        font-size:0.72rem;color:#9ca3af;font-family:monospace;margin-bottom:14px;">
+                📊 {c['metrics']}
+            </div>
+            <button disabled
+                style="background:#e5e7eb;color:#9ca3af;border:none;padding:8px 0;width:100%;
+                       border-radius:7px;font-size:0.85rem;font-weight:600;cursor:not-allowed;">
+                🔒 Coming Soon
+            </button>
+        </div>"""
+
+
+def build_home(demo: gr.Blocks) -> None:
+    with gr.Row():
+        with gr.Column(scale=5):
+            gr.Markdown("# 🏆 VizWiz Benchmark Arena")
+            gr.Markdown(
+                "Automated evaluation platform for VizWiz challenges — "
+                "datasets collected from blind photographers using a smartphone app."
+            )
+        with gr.Column(scale=1, min_width=160):
+            gr.LoginButton(size="lg")
+            home_greeting = gr.Markdown("👋 Log in to submit.")
+
+    gr.Markdown("---")
+    gr.Markdown("## Challenges")
+    gr.Markdown(
+        "Choose a challenge to view its leaderboard, submit predictions, and track your results."
+    )
+    with gr.Row(equal_height=True):
+        for c in CHALLENGES:
+            with gr.Column(scale=1):
+                gr.HTML(_challenge_card_html(c))
+
+    gr.Markdown(
+        "---\n*More challenges coming soon. "
+        "All challenges use HuggingFace OAuth — log in once to access everything.*"
+    )
+    demo.load(get_user_greeting, outputs=[home_greeting])

challenges/object_localization/config.py

@@ -0,0 +1,45 @@
+PHASES = [
+    {"label": "Dev (test-dev2024)",             "codename": "test-dev2024"},
+    {"label": "Standard (test-standard2024)",   "codename": "test-standard2024"},
+    {"label": "Challenge (test-challenge2024)", "codename": "test-challenge2024"},
+]
+
+CHALLENGE_TYPES = ["Object Detection", "Instance Segmentation"]
+
+LEADERBOARD_METRICS  = ["bbox_mAP", "bbox_AP50", "segm_mAP", "segm_AP50"]
+DEFAULT_SORT_METRIC  = "segm_AP50"
+LEADERBOARD_FILE     = "leaderboard.jsonl"
+CHALLENGE_PHASE      = "test-challenge2024"
+
+EVAL_DETAILS_MD = """
+### How is the Score Calculated?
+
+Your submission is evaluated automatically against hidden ground-truth annotations using **pycocotools**.
+
+| Metric | Description |
+|--------|-------------|
+| `bbox_mAP` | Bounding box mean average precision |
+| `bbox_AP50` | Bounding box AP at IoU = 0.50 |
+| `segm_mAP` | Segmentation mean average precision |
+| `segm_AP50` | Segmentation AP at IoU = 0.50 *(default ranking metric)* |
+"""
+
+FORMAT_MD = """
+### Submission Format
+
+Your JSON file must be a **list of annotation objects**, each containing:
+
+```json
+[
+  {
+    "image_id": 123,
+    "category_id": 101,
+    "score": 0.95,
+    "area": 1024.0,
+    "bbox": [x, y, width, height],
+    "segmentation": [[x1, y1, x2, y2, ...]]
+  },
+  ...
+]
+```
+"""

challenges/object_localization/page.py

@@ -0,0 +1,265 @@
+import json
+import os
+from datetime import datetime, timezone
+
+import gradio as gr
+import pandas as pd
+
+from auth_utils import get_user_greeting, get_daily_cap_info
+from hf_utils import (
+    _load_leaderboard_df,
+    _load_user_submissions,
+    _create_submission_record,
+    _count_submissions_today,
+    _get_cap_for_phase,
+    _today_utc_str,
+)
+from config import DAILY_SUBMISSION_CAP
+from challenges.object_localization.config import (
+    PHASES, CHALLENGE_TYPES, LEADERBOARD_METRICS, DEFAULT_SORT_METRIC,
+    LEADERBOARD_FILE, CHALLENGE_PHASE, EVAL_DETAILS_MD, FORMAT_MD,
+)
+from challenges.object_localization.validate import validate_submission
+
+
+def load_leaderboard():
+    try:
+        df = _load_leaderboard_df(LEADERBOARD_FILE, LEADERBOARD_METRICS)
+    except Exception as e:
+        return pd.DataFrame(), f"❌ Could not load leaderboard: {e}"
+
+    if not df.empty and "phase_codename" in df.columns:
+        df = df[df["phase_codename"] == CHALLENGE_PHASE]
+
+    if df.empty:
+        return pd.DataFrame(), "ℹ️ No scored Challenge phase submissions yet. Be the first!"
+
+    df = df.sort_values(by=DEFAULT_SORT_METRIC, ascending=False, kind="mergesort")
+    df_display = df.copy()
+    df_display.insert(0, "Rank", range(1, len(df_display) + 1))
+    if "timestamp" in df_display.columns:
+        df_display["Scored At"] = pd.to_datetime(
+            df_display["timestamp"], unit="s", errors="coerce"
+        ).dt.strftime("%d %b %Y, %I:%M %p")
+        df_display.drop(columns=["timestamp"], inplace=True)
+    for col in ["username", "email", "phase_codename", "submission_id"]:
+        if col in df_display.columns:
+            df_display.drop(columns=[col], inplace=True)
+    return df_display, ""
+
+
+def handle_submit(file, team, model_name, phase_label, challenge_type, profile: gr.OAuthProfile | None):
+    if profile is None:
+        return "❌ You must be logged in with your HuggingFace account to submit.", ""
+    username = profile.username
+    email = getattr(profile, "email", "") or ""
+
+    from config import SUBMISSIONS_TOKEN
+    if not SUBMISSIONS_TOKEN:
+        return "❌ Missing SUBMISSIONS_TOKEN. Add it in Space Settings → Secrets.", ""
+    if file is None:
+        return "❌ Please upload a JSON file.", ""
+    if not team.strip():
+        return "❌ Please enter a Team / Display Name.", ""
+    if not model_name.strip():
+        return "❌ Please enter a Model Name.", ""
+
+    phase_codename = next((p["codename"] for p in PHASES if p["label"] == phase_label), phase_label)
+    cap = _get_cap_for_phase(phase_codename)
+    subs_today = _count_submissions_today(username, phase_codename)
+    if subs_today >= cap:
+        phase_label_str = "challenge" if phase_codename == "test-challenge2024" else "this"
+        return f"⛔ You've reached your daily limit of {cap} submission(s) for the {phase_label_str} phase. Come back tomorrow!", ""
+
+    try:
+        with open(file, "r", encoding="utf-8") as f:
+            pred_obj = json.load(f)
+    except Exception:
+        return "❌ Could not parse JSON file.", ""
+
+    ok, msg = validate_submission(pred_obj)
+    if not ok:
+        return f"❌ Invalid submission format: {msg}", ""
+
+    original_filename = os.path.basename(file)
+    try:
+        submission_id = _create_submission_record(
+            pred=pred_obj, team=team, model_name=model_name,
+            phase_codename=phase_codename, challenge_type=challenge_type,
+            original_filename=original_filename, username=username, email=email,
+        )
+    except Exception as e:
+        return f"❌ Upload failed: {e}", ""
+
+    remaining = cap - subs_today - 1
+    return (
+        f"✅ Submission queued successfully! Visit **My Submissions** to see the results. "
+        f"You have {remaining}/{cap} submissions remaining today for this phase.",
+        submission_id,
+    )
+
+
+def load_my_submissions(phase_filter: str, profile: gr.OAuthProfile | None):
+    if profile is None:
+        return pd.DataFrame(), "❌ Please log in to view your submissions.", ""
+    username = profile.username
+    submissions = _load_user_submissions(username)
+
+    if not submissions:
+        return pd.DataFrame(), "ℹ️ No submissions yet. Head to Submit Predictions to get started!", ""
+
+    all_submissions = submissions[:]
+    if phase_filter and phase_filter != "All":
+        submissions = [s for s in submissions if s["phase"] == phase_filter]
+    if not submissions:
+        return pd.DataFrame(), f"ℹ️ No submissions found for phase **{phase_filter}**.", ""
+
+    state_icons = {"queued": "🟡", "running": "🔵", "done": "🟢", "failed": "🔴", "unknown": "⚪"}
+    df = pd.DataFrame(submissions)
+    if "timestamp" in df.columns:
+        df["Submitted At"] = pd.to_datetime(
+            df["timestamp"], unit="s", errors="coerce"
+        ).dt.strftime("%d %b %Y, %I:%M %p")
+    if "state" in df.columns:
+        df["Status"] = df["state"].apply(lambda s: f"{state_icons.get(s, '⚪')} {s.capitalize()}")
+
+    display_cols = ["Submitted At", "Status", "team", "model", "phase", "challenge_type", "error"]
+    metric_cols  = [m for m in LEADERBOARD_METRICS if m in df.columns]
+    display_cols += metric_cols
+    df_display = df[[c for c in display_cols if c in df.columns]].copy()
+    df_display.rename(columns={
+        "team": "Team", "model": "Model", "phase": "Phase",
+        "challenge_type": "Challenge Type", "error": "Error",
+    }, inplace=True)
+    for m in metric_cols:
+        if m in df_display.columns:
+            df_display[m] = df_display[m].apply(lambda x: f"{x:.4f}" if pd.notna(x) else "")
+
+    total = len(all_submissions)
+    done  = sum(1 for s in all_submissions if s["state"] == "done")
+    today_count = sum(
+        1 for s in all_submissions
+        if datetime.fromtimestamp(s["timestamp"], tz=timezone.utc).strftime("%Y-%m-%d") == _today_utc_str()
+    )
+    stats = (
+        f"**Total:** {total}  |  "
+        f"**Scored:** {done}  |  "
+        f"**Today:** {today_count}/{DAILY_SUBMISSION_CAP}"
+    )
+    return df_display, "", stats
+
+
+def build_ol_page(demo: gr.Blocks) -> None:
+    with demo.route("Object Localization", "/object-localization") as obj_loc:
+
+        with gr.Row():
+            with gr.Column(scale=5):
+                gr.Markdown("# 🎯 Object Localization Challenge")
+                gr.Markdown(
+                    "Submit bounding box and instance segmentation predictions "
+                    "evaluated automatically against hidden ground-truth annotations."
+                )
+            with gr.Column(scale=1, min_width=160):
+                gr.LoginButton(size="lg")
+                ol_greeting = gr.Markdown("👋 Log in to submit.")
+
+        gr.Markdown("---")
+
+        with gr.Tabs():
+
+            # ── Leaderboard ──
+            with gr.TabItem("🏆 Leaderboard"):
+                gr.Markdown("### Challenge Phase Rankings")
+                gr.Markdown(f"Ranked by **{DEFAULT_SORT_METRIC}** (descending). Challenge phase only.")
+                with gr.Accordion("📐 How is the Score Calculated?", open=False):
+                    gr.Markdown(EVAL_DETAILS_MD)
+                ol_lb_msg   = gr.Markdown("")
+                ol_lb_table = gr.Dataframe(interactive=False, wrap=True)
+                ol_refresh_lb_btn = gr.Button("🔄 Refresh Leaderboard", variant="secondary", size="sm")
+
+                def refresh_ol_leaderboard(profile: gr.OAuthProfile | None):
+                    df, msg = load_leaderboard()
+                    return df, msg, get_user_greeting(profile)
+
+                ol_refresh_lb_btn.click(refresh_ol_leaderboard, outputs=[ol_lb_table, ol_lb_msg, ol_greeting])
+                obj_loc.load(refresh_ol_leaderboard, outputs=[ol_lb_table, ol_lb_msg, ol_greeting])
+
+            # ── Submit ──
+            with gr.TabItem("🚀 Submit Predictions"):
+                with gr.Row():
+                    ol_submit_greeting = gr.Markdown("👋 Log in with HuggingFace to submit.")
+                    ol_cap_info        = gr.Markdown("")
+                gr.Markdown("---")
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        gr.Markdown("#### Upload Submission File")
+                        ol_file_input = gr.File(label="Choose a JSON file", file_types=[".json"])
+                        with gr.Accordion("📄 Submission Format", open=False):
+                            gr.Markdown(FORMAT_MD)
+                    with gr.Column(scale=2):
+                        gr.Markdown("#### Submission Info")
+                        ol_team_input  = gr.Textbox(label="Team / Display Name", placeholder="e.g. My Awesome Team")
+                        ol_model_input = gr.Textbox(label="Model Name", placeholder="e.g. ResNet50-FPN")
+                        ol_phase_input = gr.Dropdown(
+                            label="Phase",
+                            choices=[p["label"] for p in PHASES],
+                            value=PHASES[0]["label"],
+                        )
+                        ol_challenge_input = gr.Radio(
+                            label="Challenge Type",
+                            choices=CHALLENGE_TYPES,
+                            value=CHALLENGE_TYPES[0],
+                        )
+                ol_submit_btn    = gr.Button("Submit (Queue for Evaluation)", variant="primary", size="lg")
+                ol_submit_status = gr.Markdown("")
+                ol_sid_box       = gr.Code(label="Submission ID", language=None, visible=False)
+
+                def do_ol_submit(file, team, model_name, phase_label, challenge_type, profile: gr.OAuthProfile | None):
+                    msg, sid = handle_submit(file, team, model_name, phase_label, challenge_type, profile)
+                    return msg, gr.update(value=sid, visible=bool(sid))
+
+                ol_submit_btn.click(
+                    do_ol_submit,
+                    inputs=[ol_file_input, ol_team_input, ol_model_input, ol_phase_input, ol_challenge_input],
+                    outputs=[ol_submit_status, ol_sid_box],
+                )
+
+                def update_ol_submit_ui(profile: gr.OAuthProfile | None):
+                    return get_user_greeting(profile), get_daily_cap_info(profile, PHASES)
+
+                obj_loc.load(update_ol_submit_ui, outputs=[ol_submit_greeting, ol_cap_info])
+
+            # ── My Submissions ──
+            with gr.TabItem("📋 My Submissions"):
+                ol_my_sub_greeting = gr.Markdown("👋 Log in with HuggingFace to view your submissions.")
+                ol_my_sub_stats    = gr.Markdown("")
+                with gr.Row():
+                    ol_phase_filter = gr.Dropdown(
+                        label="Filter by Phase",
+                        choices=["All"] + [p["codename"] for p in PHASES],
+                        value="All",
+                        scale=2,
+                    )
+                    ol_refresh_my_btn = gr.Button("🔄 Refresh", variant="secondary", scale=1)
+                ol_my_sub_msg   = gr.Markdown("")
+                ol_my_sub_table = gr.Dataframe(interactive=False, wrap=True)
+
+                def refresh_ol_my_subs(phase_filter, profile: gr.OAuthProfile | None):
+                    df, msg, stats = load_my_submissions(phase_filter, profile)
+                    return df, msg, stats, get_user_greeting(profile)
+
+                ol_refresh_my_btn.click(
+                    refresh_ol_my_subs,
+                    inputs=[ol_phase_filter],
+                    outputs=[ol_my_sub_table, ol_my_sub_msg, ol_my_sub_stats, ol_my_sub_greeting],
+                )
+                ol_phase_filter.change(
+                    refresh_ol_my_subs,
+                    inputs=[ol_phase_filter],
+                    outputs=[ol_my_sub_table, ol_my_sub_msg, ol_my_sub_stats, ol_my_sub_greeting],
+                )
+                obj_loc.load(
+                    refresh_ol_my_subs,
+                    inputs=[ol_phase_filter],
+                    outputs=[ol_my_sub_table, ol_my_sub_msg, ol_my_sub_stats, ol_my_sub_greeting],
+                )

challenges/object_localization/validate.py

@@ -0,0 +1,28 @@
+from typing import Any, Tuple
+
+
+def validate_submission(obj: Any) -> Tuple[bool, str]:
+    if not isinstance(obj, list):
+        return False, "Submission must be a JSON list of annotations."
+    required_keys = {"image_id", "score", "category_id", "area", "bbox", "segmentation"}
+    for i, ann in enumerate(obj):
+        if not isinstance(ann, dict):
+            return False, f"Annotation at index {i} must be an object/dict."
+        missing = required_keys - set(ann.keys())
+        if missing:
+            return False, f"Annotation at index {i} missing keys: {sorted(list(missing))}"
+        if not isinstance(ann["image_id"], int):
+            return False, f"image_id at index {i} must be an integer."
+        if not isinstance(ann["category_id"], int):
+            return False, f"category_id at index {i} must be an integer."
+        if not isinstance(ann["score"], (int, float)):
+            return False, f"score at index {i} must be a number."
+        if not isinstance(ann["area"], (int, float)):
+            return False, f"area at index {i} must be a number."
+        bbox = ann["bbox"]
+        if not (isinstance(bbox, list) and len(bbox) == 4
+                and all(isinstance(x, (int, float)) for x in bbox)):
+            return False, f"bbox at index {i} must be a list of 4 numbers."
+        if not isinstance(ann["segmentation"], list):
+            return False, f"segmentation at index {i} must be a list."
+    return True, "OK"

config.py

@@ -0,0 +1,11 @@
+import os
+
+# =========================
+# DATABASE / HF REPO
+# =========================
+
+DB_REPO_ID    = os.getenv("DB_REPO_ID", "VizWiz-Challenges/submissions-db")
+DB_REPO_TYPE  = "dataset"
+SUBMISSIONS_TOKEN = os.getenv("SUBMISSIONS_TOKEN", "")
+
+DAILY_SUBMISSION_CAP = 5

hf_utils.py

@@ -0,0 +1,213 @@
+import json
+import os
+import tempfile
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+import pandas as pd
+from huggingface_hub import HfApi, hf_hub_download
+from huggingface_hub.utils import HfHubHTTPError
+
+from config import DB_REPO_ID, DB_REPO_TYPE, SUBMISSIONS_TOKEN, DAILY_SUBMISSION_CAP
+
+# =========================
+# HF API CLIENT
+# =========================
+
+_api = None
+def api_client() -> HfApi:
+    global _api
+    if _api is None:
+        _api = HfApi()
+    return _api
+
+# =========================
+# DATE / CAP HELPERS
+# =========================
+
+def _today_utc_str() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+def _get_cap_for_phase(phase_codename: str) -> int:
+    """Return the daily submission cap for a given phase."""
+    if phase_codename in ("test-challenge2024", "test-challenge2025"):
+        return 1
+    return DAILY_SUBMISSION_CAP
+
+def _count_submissions_today(username: str, phase_codename: str | None = None) -> int:
+    """Count today's submissions for a user, optionally filtered by phase."""
+    try:
+        files = api_client().list_repo_files(
+            repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE, token=SUBMISSIONS_TOKEN
+        )
+        today = _today_utc_str()
+        count = 0
+        for f in files:
+            if not (f.startswith("submissions/") and f.endswith("/meta.json")):
+                continue
+            try:
+                p = hf_hub_download(
+                    repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE,
+                    filename=f, token=SUBMISSIONS_TOKEN
+                )
+                meta = json.load(open(p))
+                if meta.get("username", "").lower() != username.lower():
+                    continue
+                if phase_codename and meta.get("phase_codename") != phase_codename:
+                    continue
+                ts = meta.get("timestamp", 0)
+                sub_date = datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+                if sub_date == today:
+                    count += 1
+            except Exception:
+                continue
+        return count
+    except Exception:
+        return 0
+
+# =========================
+# UPLOAD HELPERS
+# =========================
+
+def _upload_json(data: Any, path_in_repo: str, commit_message: str = "") -> None:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as tmp:
+        json.dump(data, tmp, ensure_ascii=False)
+        tmp_path = tmp.name
+    try:
+        api_client().upload_file(
+            path_or_fileobj=tmp_path,
+            path_in_repo=path_in_repo,
+            repo_id=DB_REPO_ID,
+            repo_type=DB_REPO_TYPE,
+            token=SUBMISSIONS_TOKEN,
+            commit_message=commit_message or f"Add {path_in_repo}",
+        )
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+def _create_submission_record(*, pred, team, model_name, phase_codename,
+                               challenge_type, original_filename, username, email,
+                               subfolder: str = "") -> str:
+    """
+    Write pred.json / meta.json / status.json to the dataset repo.
+    subfolder: e.g. "answer-therapy" → submissions/answer-therapy/<uuid>/
+    """
+    if not SUBMISSIONS_TOKEN:
+        raise ValueError("Missing SUBMISSIONS_TOKEN.")
+    submission_id = str(uuid.uuid4())
+    ts = int(time.time())
+    meta = {
+        "submission_id": submission_id,
+        "team":              team.strip(),
+        "model":             model_name.strip(),
+        "phase_codename":    phase_codename,
+        "challenge_type":    challenge_type,
+        "timestamp":         ts,
+        "original_filename": original_filename,
+        "username":          username,
+        "email":             email,
+    }
+    status = {"state": "queued", "timestamp": ts}
+    prefix = f"submissions/{subfolder}/{submission_id}" if subfolder else f"submissions/{submission_id}"
+    _upload_json(pred,   f"{prefix}/pred.json",   f"pred {submission_id}")
+    _upload_json(meta,   f"{prefix}/meta.json",   f"meta {submission_id}")
+    _upload_json(status, f"{prefix}/status.json", f"status {submission_id}")
+    return submission_id
+
+# =========================
+# READ HELPERS
+# =========================
+
+def _load_user_submissions(username: str, subfolder: str = "") -> List[Dict]:
+    """Load all submissions for a user from a given subfolder (or root)."""
+    if not SUBMISSIONS_TOKEN:
+        return []
+    try:
+        files = api_client().list_repo_files(
+            repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE, token=SUBMISSIONS_TOKEN
+        )
+    except Exception:
+        return []
+
+    prefix = f"submissions/{subfolder}/" if subfolder else "submissions/"
+    results = []
+    for f in files:
+        if not (f.startswith(prefix) and f.endswith("/meta.json")):
+            continue
+        try:
+            parts = f.split("/")
+            sid = parts[2] if subfolder else parts[1]
+            meta_path = hf_hub_download(
+                repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE,
+                filename=f, token=SUBMISSIONS_TOKEN
+            )
+            meta = json.load(open(meta_path))
+            if meta.get("username", "").lower() != username.lower():
+                continue
+            status_file = f"{prefix}{sid}/status.json"
+            try:
+                status_path = hf_hub_download(
+                    repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE,
+                    filename=status_file, token=SUBMISSIONS_TOKEN
+                )
+                status = json.load(open(status_path))
+            except Exception:
+                status = {"state": "unknown"}
+            metrics = status.get("metrics", {}) if status.get("state") == "done" else {}
+            error   = status.get("error",   "") if status.get("state") == "failed" else ""
+            results.append({
+                "submission_id":  sid,
+                "team":           meta.get("team", ""),
+                "model":          meta.get("model", ""),
+                "phase":          meta.get("phase_codename", ""),
+                "challenge_type": meta.get("challenge_type", ""),
+                "timestamp":      meta.get("timestamp", 0),
+                "state":          status.get("state", "unknown"),
+                "error":          error[:120] if error else "",
+                **metrics,
+            })
+        except Exception:
+            continue
+
+    results.sort(key=lambda x: x["timestamp"], reverse=True)
+    return results
+
+def _load_leaderboard_df(leaderboard_file: str, metric_cols: list) -> pd.DataFrame:
+    """Generic leaderboard loader for any challenge."""
+    empty = pd.DataFrame(columns=["team", "model", "phase_codename", *metric_cols, "timestamp"])
+    if not SUBMISSIONS_TOKEN:
+        return empty
+    try:
+        path = hf_hub_download(
+            repo_id=DB_REPO_ID, repo_type=DB_REPO_TYPE,
+            filename=leaderboard_file, token=SUBMISSIONS_TOKEN
+        )
+    except HfHubHTTPError as e:
+        if "404" in str(e):
+            return empty
+        raise
+
+    rows = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    if not rows:
+        return empty
+
+    df = pd.DataFrame(rows)
+    for col in ["team", "model", "phase_codename", "timestamp", *metric_cols]:
+        if col not in df.columns:
+            df[col] = None
+    return df