Deploy v0.1.2

Co-authored-by: HungryTorch <HungryTorch@users.noreply.huggingface.co>
Co-authored-by: scienta-hermes[bot] <scienta-hermes[bot]@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz 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

LICENSE-STRABLE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 The STRABLE developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,285 @@
+---
+title: PRIMO Benchmark
+emoji: 🧬
+colorFrom: indigo
+colorTo: blue
+sdk: gradio
+sdk_version: 5.50.0
+python_version: "3.13"
+app_file: app.py
+pinned: false
+hf_oauth: true
+thumbnail: https://huggingface.co/spaces/PRIMOmics/primo-eval/resolve/main/assets/primo-social-preview.png
+---
+
+# PRIMO: Patient Representations in Multi-Omics
+
+**A blind benchmark for omics foundation models.**
+
+PRIMO grades how well a model turns a patient's omics data into a useful
+**patient embedding**. You select one modality, embed its datasets, and upload
+**one** file; a fixed probe scores each hidden task, and the results roll up into a blind,
+per-category leaderboard. The datasets are opaque (`d002`, `d003`…) and you never
+see the disease, tissue, or target, which leaves you grading the *embedding*
+itself with no room for per-task tuning.
+
+A top bar navigates five pages: **Leaderboard** (one ranking at a time, picked
+with the Modality, Therapeutic area and Task pills), **Tasks**, a **Submit** form
+(sign in with Hugging Face), **Contribute**, and **Method**. Every page has its
+own URL, as `?tab=contribute`, and every view too, as
+`?modality=bulk-rna&area=oncology&task=all`, so both are shareable deep links.
+Old `?board=oncology-bulk-rna` links still open their view.
+
+The last panel of the leaderboard names the omics layers and the therapeutic
+areas PRIMO does not cover yet, and links to Contribute. They are declared in
+`boards.py` (`OPEN_BOARDS`) and drop out on their own once the registry covers
+that slice. Task categories deliberately get none, because a
+category is pinned to a single metric, so an open one would advertise a probe
+that does not exist.
+
+🌐 Website: http://primomics.org/ ·
+📦 Data: https://huggingface.co/datasets/PRIMOmics/primo
+
+## What's in the data
+
+PRIMO benchmarks any omics modality. It includes **bulk RNA** and **single-cell
+RNA** tasks, all with real clinical labels or treatment-induced expression
+responses from published cohorts. Tasks are grouped in four therapeutic areas:
+
+- **Immunology & inflammation**: Crohn's disease, ulcerative colitis, celiac
+  disease, psoriasis, atopic dermatitis, hidradenitis suppurativa, rheumatoid
+  arthritis, systemic sclerosis, Sjögren's disease and multiple sclerosis
+- **Oncology**: breast, ovarian, prostate, bladder, lung and rectal cancer,
+  melanoma, and acute leukaemias
+- **Infectious diseases**: sepsis, COVID-19 and tuberculosis
+- **Metabolic diseases**: fatty liver disease (MASH)
+
+A task that fits no area is marked **Other**: today COPD, kidney graft
+rejection, graft-versus-host disease and lung fibrosis. It has no area board,
+but it is still ranked on its modality and category boards.
+
+Perturbation-response tasks cover adalimumab transfer between inflammatory skin
+diseases, mouse-to-human dupilumab transfer, and paired pre/post treatment
+cohorts in COPD (inhaled corticosteroids), prostate (enzalutamide), rectal
+(galunisertib) and breast cancer (neoadjuvant chemotherapy).
+
+## Submission format
+
+One file, one row per (`dataset_id`, `sample_id`), spanning one modality:
+
+- **CSV / TSV / Parquet**: a `dataset_id` column, a `sample_id` column, and one
+  numeric column per embedding dimension. Embedding dim may differ per dataset
+  (pad short datasets with blank columns; blank/NaN padding columns are dropped
+  per dataset).
+- **NPZ**: `dataset_ids`, `sample_ids`, and a 2-D `embeddings` array.
+
+The valid `dataset_id`s and how to download each dataset's `expression.h5ad` are
+listed in the public `datasets.yaml` manifest. Alignment is by join, so row
+order does not matter; every labelled sample of a task must be present with no
+NaN/inf, or that task is skipped.
+
+Bulk H5AD files have one row per required submission sample. Single-cell H5AD
+files have one sparse raw-count row per cell; opaque cell ids are in
+`obs_names`, and the only public cell metadata is `obs["sample_id"]`, which maps
+each cell to its opaque collection sample. Submissions remain sample-level: emit
+exactly one embedding for every unique `sample_id`, not one embedding per cell.
+
+## How it works
+
+Each dataset is embedded once and scored on every hidden task defined for it.
+Learned embedding rows are scaled to unit length; gene-space baselines keep
+their row scale. Then, per task: standardise on the outer training fold, fit
+logistic regression (classification) or ridge regression with the penalty
+chosen by subject-grouped inner cross-validation, and predict each held-out
+fold. Ridge penalties use an exact spectral search over the fixed grid; when
+regression tasks have identical samples and fold assignments, their matrix
+factorizations are shared while each target still selects its own penalty. We
+calculate the native metric per fold and average it over frozen,
+subject-grouped partitions: **AUROC**
+(classification) or **Pearson r** (regression). Binary tasks with fewer than 30
+subjects use leave-pair-out instead: each positive-negative pair of subjects is
+held out once, the probe is fit on all other subjects, and the AUROC is the
+share of held-out sample pairs ranked correctly. A few tasks instead use a
+fixed train/test split: the probe is fit once on the training portion and
+scored on the held-out portion, with the same subject-grouped penalty
+selection.
+
+Tasks are grouped into **four families**, each reported in its own native
+metric. Two families are never merged into one column:
+
+- **Treatment outcome**: response to anti-TNF therapy (**AUROC**)
+- **Clinical scores**: disease-severity regression (**Pearson r**)
+- **Endotype**: molecular-subtype classification (**AUROC**)
+- **Perturbation response**: hidden post-minus-pre DEG decoding (**centered
+  Spearman**), where 1 is perfect, 0 is uninformative, and -1 is an inverse gene
+  ranking.
+
+A leaderboard shows one column per family, in its own metric. Elo orders the
+rows, and no column averages across metrics.
+
+## Boards
+
+Results are shown as **boards**, self-contained leaderboards over a slice of the
+registry: the whole modality, one therapeutic area, one task family. A board
+ranks only the models that covered **all of its tasks**, so a submission that
+skipped Infectious diseases is still ranked on Oncology. Modality is where we draw
+the line: an area or category board never spans two modalities, because an AUROC
+on bulk RNA and an AUROC on single-cell are not measuring the same thing.
+
+Partial and failed submissions still get feedback, and their scores always appear
+in each board's **per-task** table even when they are not ranked.
+
+## Public tasks
+
+The tasks listed in `public_tasks/manifest.yaml` of the data repo have
+downloadable labels. They are tagged **Public** in the task tables and are
+scored like every other task.
+
+When the version has public tasks, a **Public tasks** pill shows. Set to
+**Hide**, it re-ranks the view on its private tasks only, without a page reload.
+It shows every task by default. The Tasks page always shows every task.
+
+## Make a submission
+
+`quickstart.py` is the shortest path: it downloads one modality and embeds its
+datasets
+(log2(CPM+1) → PCA for bulk; per-cell log2(CP10K+1) → sample mean → PCA for
+single-cell) and writes the file the Submit tab wants. Swap its `embed`
+function for your encoder and nothing else changes. `example_submission.csv`
+shows the expected shape in four lines.
+
+```bash
+pip install anndata scikit-learn pandas pyarrow pyyaml huggingface_hub
+python quickstart.py --modality bulk-rna --out submission.parquet
+```
+
+## Run the scorer locally
+
+```bash
+pip install -r requirements.txt
+export HF_TOKEN=...   # read access to the PRIMO datasets
+python evaluator.py --modality bulk-rna --submission my_embeddings.parquet
+```
+
+It reads the data commits of the current board version (see "Board versions"
+below). Long local runs can be resumed task by task with `--checkpoint-dir PATH`.
+Checkpoints are namespaced by the submission contents, representation,
+reference features and scoring configuration, and are invalidated when private
+task inputs change.
+
+`--reference PATH` scores the `+ HVG` variant: the submission rows (after their
+usual normalisation) are joined by sample with a gene-space file of the same
+layout, and every concatenated row is L2-normalised.
+
+## Baselines
+
+`task_results.csv` carries an `is_baseline` flag. Reference submissions we
+produce ourselves are published with it set, rendered as `name (baseline)`, and
+**ranked in place**. The published `HVG-1200-genes` entry is the **HVG-1200
+log-normalized linear baseline**: bulk samples use log2(CPM+1), while single-cell
+profiles use per-cell log2(CP10K+1) followed by sample-level mean pooling. It
+keeps 1,200 highest-variance genes and the resulting row scale rather than
+receiving the L2 row normalisation applied to learned embeddings, then uses
+train-fold standardisation and the regularisation-tuned linear probe. Gene
+selection is label-blind but fit over every sample of a dataset, so this is an
+information-rich transductive reference rather than a naïve raw-count baseline
+or an expected lower bound. `scripts/baselines.py` builds it from the public data.
+
+## `+ HVG` entries
+
+Every Space submission is scored a second time concatenated with the
+`HVG-1200-genes` features and stored as `<model> + HVG`, with the parent's
+owner, credits and `submission_id`. The features are kept privately at
+`baselines/HVG-1200-genes/submission.parquet` in `PRIMOmics/primo-results`.
+`scripts/baselines.py --publish` uploads them and logs the commit that holds them.
+The reference is pinned by the board version. A new reference opens a new
+version, and the rescore below scores the baseline and every `+ HVG` entry again
+with it.
+
+## Board versions
+
+A board version is a minor release of primo-eval: version `0.1` is scored by the
+`v0.1.x` releases. `versions.yaml` lists every version with its release tag, the
+day it opened, the Hub commits its scores read, and its `notes`: one line on what
+changed. The commits are `data` in `PRIMOmics/primo`, `labels` in
+`PRIMOmics/primo-labels`, and `reference`, the commit of `PRIMOmics/primo-results`
+that holds the HVG features. `current` is the version this code scores.
+
+The scorer reads these commits, not the latest ones, so a push to a data repo
+changes no score until a release opens a new version. `requirements.txt` pins the
+packages that can move a score (numpy, pandas, joblib, scikit-learn, scipy) to the
+versions the Space runs.
+
+Each result row records the version that scored it, and a board shows only the
+rows of its version. Rows written before versions existed carry none, so they are
+shown on no board.
+
+The "Release notes" section, at the bottom of the leaderboard, lists every version
+with its notes and links to the board of each one. `?version=0.1` opens a closed
+version, read-only: its registry at its pinned commits and the rows it scored,
+with a notice under the top bar that links back to the current version. Every link keeps
+the version, except Submit: a submission always goes to the current version.
+
+When a release opens a new version, `rescore.py` fills its board from the archived
+embedding files of the previous version, so nobody has to submit again. Each live
+submission is scored again, plain and `+ HVG`, and keeps its name, credits,
+submission id and date. The `HVG-1200-genes` baseline is scored again from the
+reference features. An entry keeps its tasks, plus the tasks the new version adds.
+If an entry fails, or gets no score on a task it held, nothing is published. The
+release steps are in `CONTRIBUTING.md`.
+
+## Space configuration
+
+- **`hf_oauth: true`** (set above) turns on the Submit tab's *Sign in with
+  Hugging Face* button; submitting requires a logged-in HF account.
+- `primo submit` calls the **`/submit`** endpoint of `submit_api.py`, with the
+  fields of the form and the caller's token. The endpoint reads the token only
+  to learn the account name, and never stores it. The form and the endpoint
+  share the same checks and one queue, so one submission runs at a time.
+- Set an **`HF_TOKEN`** Space secret (fine-grained) with: **read** on
+  `PRIMOmics/primo` (the public `datasets.yaml` manifest) and
+  `PRIMOmics/primo-labels` (the private `tasks.yaml` registry +
+  `<task_id>/labels.csv` and perturbation `<task_id>/targets.npz`), and **read + write** on
+  `PRIMOmics/primo-results` (the persisted leaderboard).
+- Results persist as one normalized `task_results.csv` (`model_name, task_id,
+  score, repeat_scores, diagnostics, submitted_at, is_baseline, hf_username,
+  version`) in the results dataset; the
+  leaderboard is recomputed from it by joining the registry, so it survives
+  Space restarts.
+- Among the rows of its version, a board keeps the **latest result for each
+  `(model name, is_baseline, task)`**,
+  so submissions accumulate: a later one fills in the tasks it covers and leaves
+  the rest standing, and resubmitting a task replaces just that result. Because a
+  task belongs to exactly one modality, one name can hold bulk and single-cell
+  results at once without either displacing the other.
+- A model name is owned by the account that first submitted it: `hf_username`
+  locks it, and Submit refuses a name somebody else holds. It is never rendered
+  anywhere: it works as a lock rather than as a credit. Names colliding with a
+  per-task column (`Task`, `Family`, `Area`, `Modality`, `Metric`, `Best`) are
+  refused too, since model names become column headers, and so are names
+  containing the `+ HVG` tag.
+- The boards show a **Submissions count** per model — the most times any one of
+  its task results was resubmitted in the board's version — so a task tuned
+  against by repeated resubmission is visible. An account can publish 4
+  submissions in 24 hours, and a file can weigh 500 MB at most.
+- Submitter contact metadata (HF username, email, paper / model links, notes)
+  persists to a separate `submissions.csv` in the same **private** results
+  dataset, and never reaches the public leaderboard.
+
+## Moving to another Hugging Face org
+
+The three dataset repos are derived from one constant, `ORG` in `evaluator.py`.
+The rest of the org name is spelled out and has to be changed by hand:
+
+- `PUBLIC_REPO` in `quickstart.py` (standalone, so it cannot import `ORG`)
+- `SOCIAL_PREVIEW_URL` in `app.py`
+- the links in this file, including the YAML `thumbnail:` above, and in
+  `pages/*.md`
+- outside this folder: `DATA_REPO` in `src/primomics/data.py`, `SPACE` in
+  `src/primomics/submit.py`, the links of the top-level `README.md`, and
+  the deploy command in `CONTRIBUTING.md`
+
+The theme follows the PRIMO charter: Funnel Display for headings, Funnel Sans for
+everything else, Scienta Navy `#080F5F` / PRIMO Cyan `#16B3C0` on Paper
+`#F3F8F8`. `colorFrom`/`colorTo` above stay `indigo`/`blue` because Hugging Face
+only accepts eight named colours and none of them is cyan.

app.py

@@ -0,0 +1,884 @@
+"""Gradio front-end for the PRIMO public benchmark.
+
+A top bar navigates five pages: Leaderboard (one ranking, chosen with the
+Modality, Therapeutic area and Task pills), Tasks ("what is actually being
+tested?"), Submit ("how do I enter?"), Contribute ("what is missing, and how do
+I add it?"), Method ("can I trust this?"). Every page is addressable --
+``?tab=contribute`` opens a tab and ``?modality=bulk-rna&area=oncology&task=all``
+a view; old ``?board=<slug>`` links still open their view. The tab strip is
+hidden in CSS; the top bar is the navigation.
+``&version=<number>`` shows a closed board version, read-only: its registry at
+its pinned commits and the rows it scored. Submit always shows the current one.
+
+Choose one modality and upload its embedding file (rows keyed by ``dataset_id``
++ ``sample_id``); a fixed task probe scores each task (a dataset may carry
+several hidden targets). Results roll up into boards -- the whole modality, one
+therapeutic area, one task family -- and each board ranks the models that
+covered every task our baseline scored, one column per category in its native
+metric (AUROC, Pearson, or centered Spearman). The rows are ordered by Elo; no
+column averages across metrics.
+
+Disclosure policy -- what the public pages may show:
+  per task   disease, tissue, area, modality, what is predicted, class names, n, metric
+  aggregated the public archives the cohorts sit in, and their licences
+  never      study accessions, dataset_id -> cohort, hub keys, per-sample labels,
+             pairing identifiers or post-treatment responses
+The public tasks are the exception: their labels and responses are published in
+the public data repo, and the pages tag them ``Public``.
+Naming the accession behind ``d002`` would put every label one GEO download
+away, so ``sources`` is collapsed to its archive (NCBI GEO / EMBL-EBI
+ArrayExpress) and ``citation`` is never rendered at all. Submitters can publish
+an optional institution, paper link and an author-submission check; legacy private
+usernames remain hidden.
+
+Failures are surfaced by who owns them: a bad file tells the submitter exactly
+what to fix; an evaluator-side failure says "our side, please retry" and logs
+the traceback rather than blaming the submission.
+
+A page load is ONE fetch: ``_init`` pulls the registry, the boards and the
+persisted results once and threads that state into every page, rather than each
+page fetching for itself. The state stays in the session, so a click on a pill
+re-renders the view from it, with no reload and no new fetch.
+"""
+
+import os
+import traceback
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+import gradio as gr
+import pandas as pd
+from boards import (
+    ALL,
+    PUBLIC,
+    Board,
+    area_choices,
+    board_view,
+    build_boards,
+    category_choices,
+    modality_choices,
+    view_board,
+    without_public,
+)
+from evaluator import (
+    EMBEDDING,
+    EvaluatorError,
+    SubmissionError,
+    _norm_id,
+    fetch_manifest,
+    fetch_public_task_ids,
+    fetch_tasks_registry,
+    manifest_ids,
+    score_all,
+    scoreable_tasks,
+)
+from leaderboard import RESERVED_COLUMNS, source_repositories
+from render import (
+    BOARD_SUB,
+    CREDIT,
+    VERSION_PARAM,
+    cta_html,
+    evaluation_confirmation,
+    evaluation_status,
+    hero_html,
+    history_html,
+    nav_html,
+    render_tasks,
+    render_view,
+)
+from results import (
+    BASELINE_TAG,
+    HVG_TAG,
+    INSTITUTION,
+    IS_AUTHOR_SUBMISSION,
+    OWNER,
+    PAPER_LINK,
+    RESULT_COLUMNS,
+    SUBMISSION_ID,
+    append_results,
+    append_submission,
+    archive_submission,
+    fetch_hvg_reference,
+    hvg_name,
+    owner_of,
+    read_results,
+    task_rows,
+    version_rows,
+)
+from submit_api import (
+    ERROR,
+    MAX_FILE_SIZE,
+    PUBLISHED,
+    REFUSED,
+    SUBMISSIONS,
+    SUBMISSIONS_PER_DAY,
+    SUBMITTED_AT,
+    recent_submissions,
+    reply,
+    route,
+)
+from versions import CURRENT, VERSIONS, Version
+
+HERE = Path(__file__).parent
+PAGES_DIR = HERE / "pages"
+CSS_PATH = str(HERE / "primo.css")
+ALLOWED_PATHS = [str(HERE / "assets")]
+SOCIAL_PREVIEW_URL = (
+    "https://huggingface.co/spaces/PRIMOmics/primo-eval/resolve/main/"
+    "assets/primo-social-preview.png"
+)
+PAGE_HEAD = f"""
+<meta property="og:title" content="PRIMO Benchmark" />
+<meta property="og:description" content="A blind benchmark for omics foundation models." />
+<meta property="og:image" content="{SOCIAL_PREVIEW_URL}" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content="PRIMO Benchmark" />
+<meta name="twitter:description" content="A blind benchmark for omics foundation models." />
+<meta name="twitter:image" content="{SOCIAL_PREVIEW_URL}" />
+"""
+
+TOKEN = os.environ.get("HF_TOKEN")
+TAB_IDS = ("leaderboard", "tasks", "submit", "contribute", "method")
+LEGACY_TABS = {"boards": "leaderboard", "board": "leaderboard"}
+DEFAULT_MODALITY = "bulk-rna"
+SHOW = "show"
+HIDE = "hide"
+TOGGLE_CHOICES = [("Show", SHOW), ("Hide", HIDE)]
+
+THEME = gr.themes.Base()
+
+VIEW_URL_JS = """
+(modality, area, task, hvg, pub) => {
+  const url = new URL(window.location.href);
+  const values = { modality, area, task, hvg, public: pub };
+  const defaults = {
+    modality: "bulk-rna", area: "all", task: "all", hvg: "show", public: "show",
+  };
+  for (const [key, value] of Object.entries(values)) {
+    if (!value || value === defaults[key]) url.searchParams.delete(key);
+    else url.searchParams.set(key, value);
+  }
+  url.searchParams.delete("board");
+  window.history.replaceState(null, "", url);
+}
+"""
+
+SUBMIT_HEAD = (
+    '<div class="pm-head"><div><h1>Submit a model</h1>'
+    "<p>One model, one modality. Partial coverage is fine within that modality. "
+    "You are ranked on every board you cover in full.</p></div></div>"
+)
+PAGE_HEADS = {
+    "contribute": (
+        '<div class="pm-head"><div><h1>Contribute</h1>'
+        "<p>What PRIMO is missing, and how to add it.</p></div></div>"
+    ),
+    "method": (
+        '<div class="pm-head"><div><h1>Method</h1>'
+        "<p>How a model is scored, and what the pages show.</p></div></div>"
+    ),
+}
+
+MODALITY_CHOICES = [
+    ("Bulk RNAseq", "bulk-rna"),
+    ("Single-cell RNAseq", "single-cell-rna"),
+]
+
+TABLE_SORT_JS = """
+() => {
+  if (window.pmTableSortBound) return;
+  window.pmTableSortBound = true;
+
+  const value = (cell) => {
+    const text = cell.dataset.sortValue || cell.textContent.trim();
+    if (!text || text.toLowerCase() === "n/a") return { missing: true, text };
+    const number = Number(text.replaceAll(",", ""));
+    return Number.isFinite(number) ? { missing: false, number, text } : { missing: false, text };
+  };
+
+  const sort = (header) => {
+    const table = header.closest("table.pm-table");
+    const body = table?.tBodies[0];
+    if (!body) return;
+    const index = Number(header.dataset.sortIndex);
+    const direction = header.dataset.sortDirection === "asc" ? -1 : 1;
+    const rows = Array.from(body.rows);
+
+    rows.sort((left, right) => {
+      const a = value(left.cells[index]);
+      const b = value(right.cells[index]);
+      if (a.missing || b.missing) return a.missing === b.missing ? 0 : a.missing ? 1 : -1;
+      if (a.number !== undefined && b.number !== undefined) return direction * (a.number - b.number);
+      return direction * a.text.localeCompare(b.text, undefined, { numeric: true });
+    });
+    rows.forEach((row) => body.append(row));
+    table.querySelectorAll("th.pm-sort").forEach((cell) => {
+      cell.dataset.sortDirection = "";
+      cell.setAttribute("aria-sort", "none");
+    });
+    header.dataset.sortDirection = direction === 1 ? "asc" : "desc";
+    table.dataset.sorted = index === 0 && direction === 1 ? "" : "true";
+    header.setAttribute("aria-sort", direction === 1 ? "ascending" : "descending");
+  };
+
+  document.addEventListener("click", (event) => {
+    const header = event.target.closest("th.pm-sort");
+    if (header) sort(header);
+  });
+  document.addEventListener("click", (event) => {
+    if (!event.target.closest("#pm-cite-btn")) return;
+    document.querySelector("#pm-cite-dialog")?.showModal();
+  });
+  document.addEventListener("click", (event) => {
+    const evaluateButton = event.target.closest(
+      "#pm-evaluate button, button#pm-evaluate"
+    );
+    if (!evaluateButton) return;
+    if (evaluateButton.dataset.confirmed === "true") {
+      delete evaluateButton.dataset.confirmed;
+      return;
+    }
+
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    const dialog = document.querySelector("#pm-evaluation-confirmation");
+    if (!dialog) return;
+    dialog.returnValue = "";
+    dialog.addEventListener("close", () => {
+      if (dialog.returnValue !== "confirm") return;
+      evaluateButton.dataset.confirmed = "true";
+      evaluateButton.click();
+    }, { once: true });
+    dialog.showModal();
+  }, true);
+  document.addEventListener("keydown", (event) => {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    const header = event.target.closest("th.pm-sort");
+    if (!header) return;
+    event.preventDefault();
+    sort(header);
+  });
+}
+"""
+
+
+def _page_text(name: str) -> str:
+    """One ``pages/<tab>.md`` per prose tab, named after the tab it fills.
+
+    Editing the site's words never means touching Python. The data pages (Boards,
+    Board, Tasks) are generated markup instead.
+    """
+    return (PAGES_DIR / f"{name}.md").read_text()
+
+
+def _download_help(modality: str | None) -> str:
+    """Show the quickstart command for the selected modality."""
+    if not modality:
+        return "Select a modality to get its download command."
+    return (
+        f"```bash\npython quickstart.py --modality {modality} "
+        "--out submission.parquet\n```"
+    )
+
+
+def _registry_by_id(version: Version) -> dict[str, dict]:
+    """The scoreable tasks of ``version`` by task_id, flagged ``public`` if so.
+
+    ``PRIMO_FIXTURE=1`` swaps the token-gated fetch for the test registry, so the
+    app runs offline for local smoke-testing.
+    """
+    if os.environ.get("PRIMO_FIXTURE"):
+        from conftest import REGISTRY
+
+        return {task_id: dict(task) for task_id, task in REGISTRY.items()}
+    datasets = manifest_ids(fetch_manifest(TOKEN, version.data))
+    registry = scoreable_tasks(fetch_tasks_registry(TOKEN, version.labels), datasets)
+    by_id = {_norm_id(task["task_id"]): task for task in registry}
+    public = fetch_public_task_ids(TOKEN, version.data)
+    return {
+        task_id: {**task, PUBLIC: task_id in public} for task_id, task in by_id.items()
+    }
+
+
+PageState = tuple[dict[str, dict], list[Board], pd.DataFrame, Version]
+
+
+def _page_state(version: Version = CURRENT) -> PageState:
+    """Registry, boards and results of ``version`` -- one fetch per render.
+
+    A failed fetch yields empty structures so the page renders a "come back
+    later" state instead of a stack trace. Every page is built from one of these,
+    threaded through rather than refetched, so a page load is one round trip.
+    """
+    try:
+        by_id = _registry_by_id(version)
+        rows = version_rows(read_results(TOKEN), version.number)
+        return by_id, build_boards(by_id), rows, version
+    except Exception:  # noqa: BLE001
+        traceback.print_exc()
+        return {}, [], pd.DataFrame(columns=RESULT_COLUMNS), version
+
+
+def _about_text(by_id: dict[str, dict]) -> str:
+    """Methodology + the archives the cohorts live in, never their accessions.
+
+    The placeholder is substituted, not ``.format``-ed: a page of prose is free
+    to contain a brace, and a stray one must not blow up the tab. An unreachable
+    registry leaves ``by_id`` empty and the sentence falls back to a generic one.
+    """
+    repositories = source_repositories(list(by_id.values()))
+    return _page_text("about").replace(
+        "{repositories}", " and ".join(repositories) or "public archives"
+    )
+
+
+def _summary(result: dict, model_name: str) -> str:
+    lines = [
+        f"**{model_name}**: covered {result['n_datasets_scored']}/"
+        f"{result['n_datasets_total']} datasets",
+        "",
+    ]
+    for category, stats in sorted(result["categories"].items()):
+        lines.append(f"- **{category}** ({stats['metric']}) = {stats['mean']:.3f}")
+    if result["full_coverage"]:
+        lines.append("\n✅ **full coverage.** You are ranked on every board.")
+    else:
+        lines.append(
+            "\n⚠️ **partial coverage.** You are ranked on the boards whose scored "
+            "tasks you covered in full, and your scores always appear in each "
+            "board's **per-task** table."
+        )
+        if result["missing"]:
+            lines.append(f"- missing from file: {result['missing']}")
+        if result["incomplete"]:
+            lines.append(f"- could not score: {result['incomplete']}")
+    return "\n".join(lines)
+
+
+def _results_frame() -> pd.DataFrame:
+    """Every published row, or an empty frame if the fetch fails.
+
+    A Hugging Face hiccup must not block a submission, so an empty frame leaves
+    the name free rather than raising: fail-open on the ownership check and
+    on the limit of submissions per day.
+    """
+    try:
+        return read_results(TOKEN)
+    except Exception:  # noqa: BLE001
+        traceback.print_exc()
+        return pd.DataFrame(columns=RESULT_COLUMNS)
+
+
+def _claimed_by(df: pd.DataFrame, model: str) -> str:
+    """Who already owns this model name, or ``""``."""
+    return owner_of(df, model)
+
+
+def _score_with_hvg(submission_path: str, modality: str) -> dict | None:
+    """Score the submission concatenated with the HVG features, or None on failure.
+
+    The plain scoring already validated the file, so a failure here is ours: it
+    is logged and the plain entry is saved alone rather than blocked.
+    """
+    try:
+        return score_all(
+            submission_path,
+            TOKEN,
+            modality=modality,
+            representation=EMBEDDING,
+            reference=fetch_hvg_reference(TOKEN),
+        )
+    except Exception:  # noqa: BLE001
+        traceback.print_exc()
+        return None
+
+
+def run_submission(
+    submission_path: str | None,
+    modality: str | None,
+    model_name: str,
+    institution: str,
+    is_author_submission: bool,
+    email: str,
+    paper_link: str,
+    hf_model_link: str,
+    notes: str,
+    username: str | None,
+) -> dict:
+    """Check, score and save one submission, for the web form and ``/submit``.
+
+    The reply holds the ``status``, ``message`` and ``submission_id`` that
+    ``primo submit`` reads.
+    """
+
+    def _refuse(message: str) -> dict:
+        return reply(REFUSED, message)
+
+    if not username:
+        return _refuse("Please sign in with Hugging Face to submit.")
+    if not modality:
+        return _refuse("Please select a modality.")
+    if not submission_path:
+        return _refuse("Please upload a submission file.")
+    if not model_name or not model_name.strip():
+        return _refuse("Please enter a model name.")
+    if not email or not email.strip():
+        return _refuse("Please enter a contact email.")
+    model = model_name.strip()
+    if BASELINE_TAG in model.lower():
+        return _refuse(
+            f"`{BASELINE_TAG}` is reserved for our reference submissions. Please "
+            "pick another model name."
+        )
+    if HVG_TAG.lower() in model.lower():
+        return _refuse(
+            f"`{HVG_TAG}` is reserved for the entry we derive from every "
+            "submission. Please pick another model name."
+        )
+    if model in RESERVED_COLUMNS:
+        return _refuse(
+            f"`{model}` is a column of the per-task table. Please pick another "
+            "model name."
+        )
+    published = _results_frame()
+    claimed = _claimed_by(published, model)
+    if claimed and claimed != username:
+        return _refuse(
+            f"The model name `{model}` is already submitted by another HF account. "
+            "Resubmission of the same model is allowed only from the same HF account. "
+            "Please pick another name."
+        )
+    if (
+        recent_submissions(published, username, datetime.now(timezone.utc))
+        >= SUBMISSIONS_PER_DAY
+    ):
+        return _refuse(
+            f"An account can publish {SUBMISSIONS_PER_DAY} submissions in 24 "
+            "hours. Please try again later."
+        )
+    try:
+        result = score_all(
+            submission_path, TOKEN, modality=modality, representation=EMBEDDING
+        )
+    except SubmissionError as error:
+        return _refuse(f"❌ {error}")
+    except EvaluatorError as error:
+        traceback.print_exc()
+        return reply(
+            ERROR,
+            "⚠️ We couldn't evaluate your submission. This is on our side, not your "
+            f"file. Please try again in a moment.\n\n`{error}`",
+        )
+    except Exception as error:  # noqa: BLE001
+        traceback.print_exc()
+        return reply(ERROR, f"⚠️ Unexpected evaluation error (our side): {error}")
+
+    summary = _summary(result, model)
+    now = datetime.now(timezone.utc)
+    submitted_at = now.strftime(SUBMITTED_AT)
+    submission_id = f"{now.strftime('%Y%m%dT%H%M%S.%fZ')}-{uuid4().hex}"
+    credits = {
+        OWNER: username,
+        INSTITUTION: (institution or "").strip(),
+        IS_AUTHOR_SUBMISSION: bool(is_author_submission),
+        PAPER_LINK: (paper_link or "").strip(),
+    }
+    rows = task_rows(model, result, submitted_at, submission_id, credits)
+    if not rows:
+        summary += (
+            "\n\n⚠️ No valid scores were produced, so the model was not added to "
+            "any board."
+        )
+        return _refuse(summary)
+
+    hvg_result = _score_with_hvg(submission_path, modality)
+    hvg_rows = (
+        []
+        if hvg_result is None
+        else task_rows(
+            hvg_name(model), hvg_result, submitted_at, submission_id, credits
+        )
+    )
+    if hvg_result is not None:
+        summary += "\n\n" + _summary(hvg_result, hvg_name(model))
+    if not hvg_rows:
+        summary += (
+            f"\n\n⚠️ The `{hvg_name(model)}` entry could not be scored (our side), "
+            "so only the plain entry is saved; an earlier "
+            f"`{hvg_name(model)}` entry may still show older scores."
+        )
+    rows += hvg_rows
+
+    meta = {
+        "model_name": model,
+        "submitted_at": submitted_at,
+        SUBMISSION_ID: submission_id,
+        "email": email.strip(),
+        **credits,
+        "hf_model_link": (hf_model_link or "").strip(),
+        "notes": (notes or "").strip(),
+    }
+    try:
+        archive_submission(
+            submission_path, model, submission_id, modality, submitted_at, TOKEN
+        )
+    except Exception as error:  # noqa: BLE001
+        traceback.print_exc()
+        summary += f"\n\n⚠️ scored, but the embedding archive was not saved: {error}"
+        return reply(ERROR, summary)
+    try:
+        append_results(rows, TOKEN)
+    except Exception as error:  # noqa: BLE001
+        traceback.print_exc()
+        summary += f"\n\n⚠️ archived, but the leaderboard was not saved: {error}"
+        return reply(ERROR, summary, submission_id)
+
+    summary += f"\n\n✅ **{model} is now shown on the relevant boards.**"
+    if hvg_rows:
+        summary += f" So is **{hvg_name(model)}**."
+    try:
+        append_submission(meta, TOKEN)
+    except Exception as error:  # noqa: BLE001
+        traceback.print_exc()
+        summary += f"\n\n⚠️ Contact metadata was not saved: {error}"
+    return reply(PUBLISHED, summary, submission_id)
+
+
+def evaluate(
+    submission_path: str,
+    modality: str | None,
+    model_name: str,
+    institution: str,
+    is_author_submission: bool,
+    email: str,
+    paper_link: str,
+    hf_model_link: str,
+    notes: str,
+    profile: gr.OAuthProfile | None,
+):
+    """The web form: the shared submission path, then the page's answer."""
+    return run_submission(
+        submission_path,
+        modality,
+        model_name,
+        institution,
+        is_author_submission,
+        email,
+        paper_link,
+        hf_model_link,
+        notes,
+        None if profile is None else profile.username,
+    )["message"]
+
+
+def _landing_tab(params: dict) -> str:
+    """Which page a visitor lands on: ``?tab=``, old board links included.
+
+    An unknown ``?tab=`` falls through to the leaderboard rather than selecting
+    nothing, which would render the Space with every panel collapsed.
+    """
+    tab = params.get("tab")
+    tab = LEGACY_TABS.get(tab, tab)
+    return tab if tab in TAB_IDS else "leaderboard"
+
+
+def _initial_view(
+    params: dict, by_id: dict[str, dict], boards: list[Board]
+) -> tuple[str, str, str]:
+    """The pills a visitor lands on: an old ``?board=``, else the query, else Bulk."""
+    old = next((b for b in boards if b.slug == params.get("board")), None)
+    if old is not None:
+        return board_view(old, by_id)
+    modalities = [slug for _, slug in modality_choices(by_id)]
+    modality = params.get("modality")
+    if modality not in modalities:
+        modality = (
+            DEFAULT_MODALITY
+            if DEFAULT_MODALITY in modalities or not modalities
+            else modalities[0]
+        )
+    areas = [slug for _, slug in area_choices(by_id, modality)]
+    categories = [slug for _, slug in category_choices(by_id, modality)]
+    area = params.get("area") if params.get("area") in areas else ALL
+    category = params.get("task") if params.get("task") in categories else ALL
+    return modality, area, category
+
+
+def _view_name(by_id: dict[str, dict], modality: str, area: str, category: str) -> str:
+    """The view as its pills read, ``Bulk RNAseq · Oncology · All tasks``."""
+    modalities = {slug: name for name, slug in modality_choices(by_id)}
+    areas = {slug: name for name, slug in area_choices(by_id, modality)}
+    categories = {slug: name for name, slug in category_choices(by_id, modality)}
+    return " · ".join(
+        (
+            modalities.get(modality, modality),
+            "All areas" if area == ALL else areas.get(area, area),
+            "All tasks" if category == ALL else categories.get(category, category),
+        )
+    )
+
+
+def _render_view(
+    state: PageState, modality: str, area: str, category: str, hvg: str, public: str
+) -> str:
+    """The tables of the view the pills select, on the version on screen.
+
+    A pill clicked before the page has loaded has no state yet, and changes nothing.
+    """
+    if state is None:
+        return gr.skip()
+    by_id, _, df, _ = state
+    board = view_board(by_id, modality, area, category)
+    if public == HIDE:
+        board = without_public(board, by_id)
+    name = _view_name(by_id, modality, area, category)
+    return render_view(board, df, by_id, name, hvg != HIDE)
+
+
+def _on_modality(state: PageState, modality: str, hvg: str, public: str):
+    """A new modality brings its own area and task pills, both back on All."""
+    by_id = state[0]
+    return (
+        gr.Radio(choices=area_choices(by_id, modality), value=ALL),
+        gr.Radio(choices=category_choices(by_id, modality), value=ALL),
+        _render_view(state, modality, ALL, ALL, hvg, public),
+    )
+
+
+def _viewed_version(params: dict) -> Version:
+    """The version a visitor asked for; Submit and unknown numbers get the current."""
+    if params.get("tab") == "submit":
+        return CURRENT
+    number = params.get(VERSION_PARAM)
+    return next((listed for listed in VERSIONS if listed.number == number), CURRENT)
+
+
+def _init(request: gr.Request):
+    """Render every page from one fetch, on the tab and the view the query asks.
+
+    The fetched state is returned too, so a click on a pill re-renders the view
+    without a second round trip.
+    """
+    params = dict(request.query_params) if request else {}
+    state = _page_state(_viewed_version(params))
+    by_id, boards, df, version = state
+    tab = _landing_tab(params)
+    modality, area, category = _initial_view(params, by_id, boards)
+    hvg = HIDE if params.get("hvg") == HIDE else SHOW
+    public = HIDE if params.get("public") == HIDE else SHOW
+    return (
+        gr.Tabs(selected=tab),
+        nav_html(tab, version),
+        hero_html(boards, df, version),
+        _render_view(state, modality, area, category, hvg, public),
+        gr.Radio(choices=modality_choices(by_id), value=modality),
+        gr.Radio(choices=area_choices(by_id, modality), value=area),
+        gr.Radio(choices=category_choices(by_id, modality), value=category),
+        gr.Radio(value=hvg),
+        gr.Radio(value=public, visible=any(t.get(PUBLIC) for t in by_id.values())),
+        state,
+        render_tasks(by_id),
+        _about_text(by_id),
+        history_html(df, version),
+        cta_html(boards, version),
+    )
+
+
+def build_demo() -> gr.Blocks:
+    with gr.Blocks(
+        title="PRIMO Benchmark",
+        theme=THEME,
+        head=PAGE_HEAD,
+        css_paths=[CSS_PATH],
+        js=TABLE_SORT_JS,
+        fill_width=True,
+    ) as demo:
+        page_state = gr.State(None)
+        with gr.Column(elem_id="pm-site"):
+            nav = gr.HTML(padding=False)
+            with gr.Tabs(elem_id="pm-pages") as pages:
+                with gr.Tab("Leaderboard", id="leaderboard"):
+                    hero = gr.HTML(padding=False)
+                    gr.HTML(BOARD_SUB, padding=False)
+                    with gr.Row(elem_id="pm-controls"):
+                        modality_f = gr.Radio(
+                            label="Modality", elem_classes=["pm-seg", "pm-seg--main"]
+                        )
+                        area_f = gr.Radio(
+                            label="Therapeutic area",
+                            elem_classes=["pm-seg", "pm-seg--line"],
+                        )
+                        task_f = gr.Radio(
+                            label="Task", elem_classes=["pm-seg", "pm-seg--line"]
+                        )
+                        hvg_f = gr.Radio(
+                            TOGGLE_CHOICES,
+                            value=SHOW,
+                            label="+ HVG models",
+                            elem_classes=["pm-seg", "pm-seg--minor"],
+                        )
+                        public_f = gr.Radio(
+                            TOGGLE_CHOICES,
+                            value=SHOW,
+                            label="Public tasks",
+                            visible=False,
+                            elem_classes=["pm-seg", "pm-seg--minor"],
+                        )
+                    board_html = gr.HTML(padding=False)
+                    history = gr.HTML(padding=False)
+                    cta = gr.HTML(padding=False)
+                with gr.Tab("Tasks", id="tasks"):
+                    tasks_html = gr.HTML(padding=False)
+                with gr.Tab("Submit", id="submit"):
+                    gr.HTML(SUBMIT_HEAD, padding=False)
+                    with gr.Column(elem_classes=["pm-body"]):
+                        with gr.Row(elem_id="pm-submit"):
+                            with gr.Column(scale=3):
+                                gr.Markdown(
+                                    _page_text("submit"),
+                                    elem_classes=["pm-prose", "pm-submit-text"],
+                                )
+                            with gr.Column(scale=2, elem_id="pm-form"):
+                                gr.LoginButton()
+                                modality_in = gr.Radio(
+                                    MODALITY_CHOICES,
+                                    label="Modality",
+                                    info="One model submission covers one modality.",
+                                    elem_classes=["pm-seg", "pm-seg--form"],
+                                )
+                                download_md = gr.Markdown(
+                                    _download_help(None), elem_classes=["pm-hint"]
+                                )
+                                model_tb = gr.Textbox(
+                                    label="Model name",
+                                    placeholder="e.g. my-model-v1",
+                                    info="Shown on the leaderboard.",
+                                )
+                                institution_tb = gr.Textbox(
+                                    label="Institution (optional)",
+                                    placeholder="e.g. Example University",
+                                    info="Shown on the leaderboard.",
+                                )
+                                author_submission_cb = gr.Checkbox(
+                                    label="Submitted by the model's authors",
+                                    info="Adds an Authors check next to the model name.",
+                                )
+                                email_tb = gr.Textbox(
+                                    label="Email address",
+                                    placeholder="Your contact email",
+                                    info="Contact for this submission, kept private.",
+                                )
+                                notes_tb = gr.Textbox(
+                                    label="Training data / notes (optional)",
+                                    placeholder="e.g. pretrained on atlas X",
+                                    info="About the model or its training data.",
+                                )
+                                paper_tb = gr.Textbox(
+                                    label="Paper link (optional)",
+                                    placeholder="https://arxiv.org/abs/...",
+                                    info="Links the model name on the leaderboard.",
+                                )
+                                hf_tb = gr.Textbox(
+                                    label="Hugging Face model link (optional)",
+                                    placeholder="https://huggingface.co/...",
+                                )
+                                file_in = gr.File(
+                                    label="Submission (.csv / .tsv / .parquet / .npz)",
+                                    type="filepath",
+                                )
+                                run_btn = gr.Button(
+                                    "Evaluate",
+                                    elem_id="pm-evaluate",
+                                    elem_classes=[
+                                        "pm-btn",
+                                        "pm-btn--primary",
+                                        "pm-btn--block",
+                                    ],
+                                )
+                                status_html = gr.HTML(
+                                    evaluation_status(), visible=False
+                                )
+                                gr.HTML(evaluation_confirmation())
+                        result_md = gr.Markdown()
+                with gr.Tab("Contribute", id="contribute"):
+                    gr.HTML(PAGE_HEADS["contribute"], padding=False)
+                    with gr.Column(elem_classes=["pm-body", "pm-prose"]):
+                        gr.Markdown(_page_text("contribute"))
+                with gr.Tab("Method", id="method"):
+                    gr.HTML(PAGE_HEADS["method"], padding=False)
+                    with gr.Column(elem_classes=["pm-body", "pm-prose"]):
+                        about_md = gr.Markdown()
+            gr.HTML(CREDIT, padding=False)
+
+        evaluation_event = run_btn.click(
+            lambda: gr.update(visible=True),
+            None,
+            status_html,
+            show_progress="hidden",
+        ).then(
+            evaluate,
+            [
+                file_in,
+                modality_in,
+                model_tb,
+                institution_tb,
+                author_submission_cb,
+                email_tb,
+                paper_tb,
+                hf_tb,
+                notes_tb,
+            ],
+            result_md,
+            concurrency_id=SUBMISSIONS,
+        )
+        gr.api(route(run_submission), api_name="submit", concurrency_id=SUBMISSIONS)
+        evaluation_event.then(
+            lambda: gr.update(visible=False),
+            None,
+            status_html,
+            show_progress="hidden",
+        )
+        modality_in.change(_download_help, modality_in, download_md)
+
+        pills = [modality_f, area_f, task_f, hvg_f, public_f]
+        modality_f.input(
+            _on_modality,
+            [page_state, modality_f, hvg_f, public_f],
+            [area_f, task_f, board_html],
+            show_progress="hidden",
+        ).then(None, pills, None, js=VIEW_URL_JS)
+        for pill in pills[1:]:
+            pill.input(
+                _render_view,
+                [page_state, *pills],
+                board_html,
+                show_progress="hidden",
+            ).then(None, pills, None, js=VIEW_URL_JS)
+        demo.load(
+            _init,
+            None,
+            [
+                pages,
+                nav,
+                hero,
+                board_html,
+                *pills,
+                page_state,
+                tasks_html,
+                about_md,
+                history,
+                cta,
+            ],
+        )
+    return demo
+
+
+if __name__ == "__main__":
+    build_demo().launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        ssr_mode=False,
+        allowed_paths=ALLOWED_PATHS,
+        max_file_size=MAX_FILE_SIZE,
+    )

boards.py

@@ -0,0 +1,375 @@
+"""The slices of PRIMO a visitor can rank models on: registry tasks -> boards.
+
+A *board* is a self-contained leaderboard over a subset of the registry -- every
+task of a modality, of a therapeutic area, or of a task family. Coverage is
+judged INSIDE a board, so a model that covered every Oncology task is ranked
+on the Oncology board even though it skipped Infectious diseases. Each board is
+a real leaderboard, not a view filter.
+
+Modality stays the wall for every board, so models from different omics layers
+are never ranked together. The leaderboard page picks a board with three pills:
+modality, therapeutic area and task family. ``view_board`` builds the board of
+any such view, area and family crossed included.
+
+``OPEN_BOARDS`` names the slices PRIMO does NOT cover, so the page states its own
+gaps instead of implying the registry is the whole territory. They are a
+hand-written constant, not a roadmap: a slice belongs here when a contributor
+could plausibly bring it, and it disappears on its own the day the registry
+covers it.
+
+Modalities and therapeutic areas get open slices; task categories deliberately do
+not. A category is an enum whose members are each pinned to a single metric, so
+naming an open one ("biomarker discovery") would advertise a scoring rule that
+does not exist. Modalities and areas only need a cohort.
+
+Pure functions over registry dicts -- no Gradio, no network, no HTML.
+"""
+
+import re
+from dataclasses import dataclass, replace
+
+from evaluator import _norm_id
+
+METRIC_LABEL = {
+    "auroc": "AUROC",
+    "pearson": "Pearson",
+    "residual_spearman": "Residual Spearman score",
+    "centered_spearman": "Centered Spearman score",
+}
+MODALITY_LABEL = {
+    "bulk RNA": "Bulk RNAseq",
+    "Single Cell RNA": "Single-cell RNAseq",
+    "single-cell RNA": "Single-cell RNAseq",
+}
+
+MODALITY_GROUP = "Per modality"
+AREA_GROUP = "Per therapeutic areas"
+CATEGORY_GROUP = "Task Category"
+OTHER_AREA = "Other"
+PUBLIC = "public"
+
+CODE_LENGTH = 3
+FALLBACK_CODE = "n/a"
+DISPLAY_LABEL = {"perturbation_prediction": "Perturbation response"}
+
+CATEGORY_BLURB = {
+    "treatment_outcome": "Will this patient respond to the drug?",
+    "clinical_scores": "How severe is this patient's disease?",
+    "prognosis": "How will this patient's disease turn out?",
+    "endotype": "Which molecular subtype is this patient?",
+    "perturbation_prediction": "How will treatment change this patient's expression?",
+}
+
+MAX_LISTED = 3
+
+
+def label(value: str) -> str:
+    """``treatment_outcome`` -> ``Treatment outcome``; leaves free text alone."""
+    return DISPLAY_LABEL.get(value, value.replace("_", " ").capitalize())
+
+
+def metric_label(metric: str) -> str:
+    return METRIC_LABEL.get(metric, metric)
+
+
+def modality_label(modality: str) -> str:
+    """Return the visitor-facing label for a stored modality identifier."""
+    return MODALITY_LABEL.get(modality, modality)
+
+
+def short_code(name: str) -> str:
+    """The board's letter tag, standing in for what used to be a per-board emoji.
+
+    Derived from the name rather than looked up, because a lookup table is what
+    breaks: spatial transcriptomics or metabolomics would land on a shrug the day
+    somebody adds them. Colour carries the group; these letters only carry the
+    board.
+    """
+    letters = re.sub(r"[^a-z]", "", name.lower())
+    return letters[:CODE_LENGTH].upper() or FALLBACK_CODE
+
+
+def slugify(*parts: str) -> str:
+    """URL-safe key for a board, stable enough to paste into a link."""
+    joined = "-".join(str(p) for p in parts)
+    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", joined.lower())).strip("-")
+
+
+def distinct(tasks, key: str) -> list[str]:
+    """Distinct non-empty values of ``key`` across registry tasks, case-insensitive."""
+    return sorted({str(t[key]) for t in tasks if t.get(key)}, key=str.lower)
+
+
+def distinct_listed(tasks, key: str) -> list[str]:
+    """Distinct values of a list-valued ``key`` (a cohort can span several diseases)."""
+    values: set[str] = set()
+    for task in tasks:
+        values.update(str(value) for value in task.get(key) or [])
+    return sorted(values, key=str.lower)
+
+
+@dataclass(frozen=True)
+class Board:
+    """One enterable leaderboard: a named task set plus the numbers on its card."""
+
+    slug: str
+    group: str
+    name: str
+    code: str
+    blurb: str
+    modality: str
+    task_ids: frozenset[str]
+    n_cohorts: int
+    n_patients: int
+    n_diseases: int
+
+    @property
+    def n_tasks(self) -> int:
+        return len(self.task_ids)
+
+
+def _join(values: list[str]) -> str:
+    """``a, b and c``, truncated -- card blurbs must not wrap forever.
+
+    A truncated list drops the "and": ``a, b and c…`` reads as an ellipsis stuck
+    to ``c``, where ``a, b, c…`` reads as the list continuing.
+    """
+    shown = values[:MAX_LISTED]
+    if not shown:
+        return "n/a"
+    if len(values) > MAX_LISTED:
+        return f"{', '.join(shown)}…"
+    if len(shown) == 1:
+        return shown[0]
+    return f"{', '.join(shown[:-1])} and {shown[-1]}"
+
+
+def _cohort_stats(tasks: list[dict]) -> tuple[int, int, int]:
+    """Cohorts, patients and diseases behind a task set.
+
+    Counted per COHORT, not per task and not per dataset. Three clinical scores
+    read off the same biopsies are one cohort, and so are the two treatment arms
+    and the transfer split cut from one anti-TNF trial -- summing datasets would
+    advertise those patients twice. Entries on one cohort can differ in
+    ``n_samples`` (labels get dropped, an arm is a subset), so the widest one
+    stands for it.
+
+    A registry written before ``cohort_id`` existed falls back to ``dataset_id``,
+    which is the old behaviour rather than a crash.
+    """
+    patients_by_cohort: dict[str, int] = {}
+    diseases: set[str] = set()
+    for task in tasks:
+        cohort = str(task.get("cohort_id") or _norm_id(task.get("dataset_id", "")))
+        n_subjects = int(task.get("n_subjects") or task.get("n_samples") or 0)
+        patients_by_cohort[cohort] = max(patients_by_cohort.get(cohort, 0), n_subjects)
+        diseases.update(str(d) for d in task.get("diseases") or [])
+    return (
+        len(patients_by_cohort),
+        sum(patients_by_cohort.values()),
+        len(diseases),
+    )
+
+
+def _blurb(group: str, name: str, tasks: list[dict]) -> str:
+    if group == MODALITY_GROUP:
+        display = modality_label(name)
+        return f"Every PRIMO task, scored from {display[:1].lower()}{display[1:]} profiles."
+    if group == CATEGORY_GROUP:
+        return CATEGORY_BLURB.get(name, label(name))
+    families = [label(c) for c in distinct(tasks, "category")]
+    return f"{_join(families)} across {_join(distinct_listed(tasks, 'diseases'))}."
+
+
+def _board(group: str, name: str, modality: str, tasks: list[dict]) -> Board:
+    """Build one board from a task slice."""
+    n_cohorts, n_patients, n_diseases = _cohort_stats(tasks)
+    display = modality_label(name) if group == MODALITY_GROUP else label(name)
+    return Board(
+        slug=slugify(modality) if group == MODALITY_GROUP else slugify(name, modality),
+        group=group,
+        name=display,
+        code=short_code(display),
+        blurb=_blurb(group, name, tasks),
+        modality=modality,
+        task_ids=frozenset(_norm_id(t["task_id"]) for t in tasks),
+        n_cohorts=n_cohorts,
+        n_patients=n_patients,
+        n_diseases=n_diseases,
+    )
+
+
+def without_public(board: Board, by_id: dict[str, dict]) -> Board:
+    """The same board restricted to its private tasks, card numbers recounted.
+
+    Parameters
+    ----------
+    board : Board
+        Board built from ``by_id``.
+    by_id : dict[str, dict]
+        Task registry keyed by task id, public tasks flagged.
+
+    Returns
+    -------
+    Board
+        The board with the same slug and name; its task set may be empty.
+    """
+    private = frozenset(t for t in board.task_ids if not by_id[t].get(PUBLIC))
+    n_cohorts, n_patients, n_diseases = _cohort_stats([by_id[t] for t in private])
+    return replace(
+        board,
+        task_ids=private,
+        n_cohorts=n_cohorts,
+        n_patients=n_patients,
+        n_diseases=n_diseases,
+    )
+
+
+def build_boards(by_id: dict[str, dict]) -> list[Board]:
+    """Every board the registry supports, modality boards first.
+
+    A facet value that yields no task simply yields no card, so a registry
+    written before therapeutic areas existed degrades to modality boards only
+    instead of breaking the page.
+
+    The "Other" area gets no board: it mixes unrelated diseases, so its ranking
+    would mean nothing. Its tasks are still ranked on the modality and category
+    boards.
+    """
+    boards: list[Board] = []
+    for modality in distinct(by_id.values(), "modality"):
+        within = [t for t in by_id.values() if str(t.get("modality")) == modality]
+        boards.append(_board(MODALITY_GROUP, modality, modality, within))
+        for area in distinct(within, "therapeutic_area"):
+            if area == OTHER_AREA:
+                continue
+            tasks = [t for t in within if str(t.get("therapeutic_area")) == area]
+            boards.append(_board(AREA_GROUP, area, modality, tasks))
+        for category in distinct(within, "category"):
+            tasks = [t for t in within if str(t.get("category")) == category]
+            boards.append(_board(CATEGORY_GROUP, category, modality, tasks))
+    return boards
+
+
+@dataclass(frozen=True)
+class OpenBoard:
+    """A slice nobody can be ranked on yet: a stated gap, not a leaderboard.
+
+    Deliberately not a ``Board``: it has no tasks, no cohorts and no patients, and
+    zeroing those fields would print "0 patients" where the page invites a cohort.
+    """
+
+    group: str
+    name: str
+    blurb: str
+
+
+OPEN_BOARDS: tuple[OpenBoard, ...] = (
+    OpenBoard(
+        MODALITY_GROUP,
+        "Single-cell RNAseq",
+        "Dissociated tissue, labelled at the patient level. No cohort yet.",
+    ),
+    OpenBoard(
+        MODALITY_GROUP,
+        "Proteomics",
+        "Plasma or tissue proteins paired with clinical follow-up. No cohort yet.",
+    ),
+    OpenBoard(
+        MODALITY_GROUP,
+        "Spatial transcriptomics",
+        "Expression kept in place in the tissue, with patient outcomes. No cohort yet.",
+    ),
+    OpenBoard(
+        AREA_GROUP,
+        "Neuroscience",
+        "Neurodegenerative cohorts, such as Alzheimer's or Parkinson's. No cohort yet.",
+    ),
+    OpenBoard(
+        AREA_GROUP,
+        "Cardiovascular",
+        "Heart or vessel disease with outcomes or treatment response. No cohort yet.",
+    ),
+)
+
+
+def in_group(boards: list[Board], group: str) -> list[Board]:
+    """The boards of one group, biggest first."""
+    return sorted(
+        (b for b in boards if b.group == group), key=lambda b: (-b.n_tasks, b.name)
+    )
+
+
+def open_in_group(boards: list[Board], group: str) -> list[OpenBoard]:
+    """Open slices of one group, minus any slice the registry has since covered.
+
+    The day a single-cell cohort lands, its board is built from the registry and
+    the matching open slice drops out with no edit here.
+    """
+    covered = {board.name.lower() for board in in_group(boards, group)}
+    return [
+        board
+        for board in OPEN_BOARDS
+        if board.group == group and board.name.lower() not in covered
+    ]
+
+
+ALL = "all"
+
+
+def _within(by_id: dict[str, dict], modality: str) -> list[dict]:
+    """The tasks of the modality whose slug is ``modality``."""
+    return [t for t in by_id.values() if slugify(str(t.get("modality"))) == modality]
+
+
+def modality_choices(by_id: dict[str, dict]) -> list[tuple[str, str]]:
+    """One ``(label, slug)`` pill per modality of the registry."""
+    choices = {
+        slugify(m): modality_label(m) for m in distinct(by_id.values(), "modality")
+    }
+    return [(name, slug) for slug, name in choices.items()]
+
+
+def area_choices(by_id: dict[str, dict], modality: str) -> list[tuple[str, str]]:
+    """The therapeutic-area pills of a modality, "All" first and no "Other"."""
+    areas = distinct(_within(by_id, modality), "therapeutic_area")
+    return [("All", ALL)] + [(a, slugify(a)) for a in areas if a != OTHER_AREA]
+
+
+def category_choices(by_id: dict[str, dict], modality: str) -> list[tuple[str, str]]:
+    """The task-category pills of a modality, "All" first."""
+    categories = distinct(_within(by_id, modality), "category")
+    return [("All", ALL)] + [(label(c), slugify(c)) for c in categories]
+
+
+def view_board(
+    by_id: dict[str, dict], modality: str, area: str, category: str
+) -> Board:
+    """The board of one view: a modality's tasks, narrowed by area and category."""
+    within = _within(by_id, modality)
+    tasks = [
+        t
+        for t in within
+        if area in (ALL, slugify(str(t.get("therapeutic_area"))))
+        and category in (ALL, slugify(str(t.get("category"))))
+    ]
+    raw_modality = str(within[0]["modality"]) if within else modality
+    if area == ALL and category == ALL:
+        return _board(MODALITY_GROUP, raw_modality, raw_modality, tasks)
+    if category == ALL:
+        name = str(tasks[0]["therapeutic_area"]) if tasks else area
+        return _board(AREA_GROUP, name, raw_modality, tasks)
+    name = str(tasks[0]["category"]) if tasks else category
+    return _board(CATEGORY_GROUP, name, raw_modality, tasks)
+
+
+def board_view(board: Board, by_id: dict[str, dict]) -> tuple[str, str, str]:
+    """The ``(modality, area, category)`` pills that show an old ``?board=`` link."""
+    task = next((by_id[t] for t in sorted(board.task_ids) if t in by_id), {})
+    area = ALL
+    category = ALL
+    if board.group == AREA_GROUP and task:
+        area = slugify(str(task.get("therapeutic_area")))
+    if board.group == CATEGORY_GROUP and task:
+        category = slugify(str(task.get("category")))
+    return slugify(board.modality), area, category

evaluator.py

@@ -0,0 +1,1725 @@
+"""Standalone probe for the PRIMO public benchmark.
+
+Loads one embedding submission for one modality (rows keyed by
+``dataset_id`` + ``sample_id``), then scores each TASK = (dataset, target): a
+dataset is embedded once and reused across all its tasks. Per task it fits a
+fixed probe—linear for scalar targets and multi-output ridge for response
+matrices—over repeated frozen CV folds or a fixed transfer split. Binary tasks with
+fewer than 30 subjects use leave-pair-out over subject pairs instead. Turning those
+predictions into scores + leaderboard aggregates is the job of ``scoring.py``;
+this module only reads data and runs the probe.
+
+Failures are split by who caused them: a bad submission raises/records a
+``SubmissionError`` (the submitter fixes it); anything on our side, such as a
+failed Hugging Face fetch or an unexpected bug, raises ``EvaluatorError`` so it
+is never silently charged against the submitter.
+
+Reads the public ``datasets.yaml`` manifest (what the submitter embeds) plus the
+private ``tasks.yaml`` registry, each task's private ``labels.csv``, and hidden
+perturbation ``targets.npz`` matrices where applicable. Each read is at the commit
+that ``versions.py`` pins for the current board version, unless a caller passes
+another ``revision``. It imports only ``scoring.py``, ``versions.py`` and the
+packages of ``requirements.txt``, so it runs unchanged inside a public Hugging Face
+Space.
+
+Deps: numpy, pandas, joblib, scikit-learn, pyyaml. ``huggingface_hub`` is used
+only by the fetch helpers / CLI, imported lazily.
+"""
+
+import argparse
+import hashlib
+import itertools
+import json
+import logging
+import os
+import time
+import zipfile
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import yaml
+from joblib import Parallel, cpu_count, delayed, parallel_backend
+from scoring import (
+    METRICS,
+    TaskScore,
+    category_means,
+    compute_residual_sample_spearman,
+    compute_target_centered_sample_spearman,
+)
+from sklearn.linear_model import LogisticRegressionCV, Ridge
+from sklearn.model_selection import GroupKFold, StratifiedGroupKFold
+from sklearn.preprocessing import StandardScaler
+from versions import CURRENT
+
+SAMPLE_ID = "sample_id"
+SUBJECT_ID = "subject_id"
+DATASET_ID = "dataset_id"
+TASK_ID = "task_id"
+LABEL = "label"
+FOLD = "fold"
+FOLD_PREFIX = f"{FOLD}_"
+SPLIT = "split"
+SPLIT_TRAIN = "train"
+SPLIT_TEST = "test"
+PAIR_ID = "pair_id"
+CONTROL_ID = "control_id"
+PERTURBED_ID = "perturbed_id"
+PAIRING = "pairing"
+PAIRED = "paired"
+CARTESIAN = "cartesian"
+PERTURBATION = "perturbation"
+RESIDUAL_SPEARMAN = "residual_spearman"
+CENTERED_SPEARMAN = "centered_spearman"
+ORG = "PRIMOmics"
+PUBLIC_REPO = f"{ORG}/primo"
+LABELS_REPO = f"{ORG}/primo-labels"
+RESULTS_REPO = f"{ORG}/primo-results"
+MANIFEST_FILENAME = "datasets.yaml"
+PUBLIC_TASKS_MANIFEST = "public_tasks/manifest.yaml"
+TASKS_FILENAME = "tasks.yaml"
+LABELS_FILENAME = "labels.csv"
+TARGETS_FILENAME = "targets.npz"
+MODALITIES = {"bulk-rna": "bulk RNA", "single-cell-rna": "Single Cell RNA"}
+
+RIDGE_ALPHAS = np.logspace(-6.0, 6.0, 25)
+PERTURBATION_TEST_Z_CLIP = 20.0
+LOGREG_CS = np.logspace(-6.0, 6.0, 13)
+INNER_CV = 5
+INNER_CV_JOBS = 4
+OUTER_CV_JOBS = min(10, cpu_count())
+OUTER_PARALLEL_MIN_SAMPLES = 30
+LOGREG_TOL = 1e-3
+MAX_ITER = 5000
+RANDOM_STATE = 0
+MIN_CV_SUBJECTS = 30
+CHECKPOINT_PROTOCOL = "grouped-inner-cv-spectral-ridge-v2"
+
+EMBEDDING = "embedding"
+GENE_SPACE = "gene_space"
+REPRESENTATIONS = (EMBEDDING, GENE_SPACE)
+
+FETCH_ATTEMPTS = 3
+FETCH_BACKOFF = 1.0
+
+NPZ_ID_KEYS = ("sample_ids", "sample_id", "ids")
+NPZ_EMB_KEYS = ("embeddings", "embedding", "emb", "X")
+NPZ_DSID_KEYS = ("dataset_ids", "dataset_id")
+NOT_NPZ = "not a .npz archive: save it with np.savez, or use .csv/.parquet"
+
+
+class SubmissionError(ValueError):
+    """A submission the evaluator cannot score (bad format, missing samples...)."""
+
+
+class EvaluatorError(RuntimeError):
+    """A failure on our side (data fetch, unexpected bug), not the submitter's.
+
+    Raised instead of being recorded as a per-dataset skip, so a transient
+    Hugging Face hiccup or an evaluator bug never silently costs a submitter
+    their coverage.
+    """
+
+
+@dataclass
+class TaskOutcome:
+    """What happened to one scoreable task: scored / missing / invalid."""
+
+    task_id: str
+    dataset_id: str
+    status: str
+    score: TaskScore | None = None
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class PerturbationTargets:
+    """Hidden response vectors and their aligned gene identifiers."""
+
+    delta: np.ndarray
+    gene_ids: np.ndarray
+
+
+@dataclass(frozen=True)
+class _PendingTask:
+    """Fetched task inputs awaiting either individual or compatible batch scoring."""
+
+    position: int
+    task: dict
+    emb: pd.DataFrame
+    labels: pd.DataFrame
+    targets: PerturbationTargets | None
+    fingerprint: str
+
+
+def _digest_file(digest: "hashlib._Hash", path: str | Path) -> None:
+    """Feed a file's bytes into ``digest`` in chunks."""
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+
+
+class _TaskCheckpoints:
+    """Persist completed task outcomes under one submission-scoped directory."""
+
+    def __init__(
+        self,
+        directory: str | Path,
+        submission: str | Path,
+        modality: str | None,
+        representation: str,
+        reference: str | Path | None = None,
+    ) -> None:
+        digest = hashlib.sha256()
+        _digest_file(digest, submission)
+        digest.update(f"{CHECKPOINT_PROTOCOL}\0{modality}\0{representation}".encode())
+        if reference is not None:
+            digest.update(b"\0reference\0")
+            _digest_file(digest, reference)
+        digest.update(
+            json.dumps(
+                {
+                    "ridge_alphas": RIDGE_ALPHAS.tolist(),
+                    "logreg_cs": LOGREG_CS.tolist(),
+                    "inner_cv": INNER_CV,
+                    "logreg_tol": LOGREG_TOL,
+                    "max_iter": MAX_ITER,
+                    "min_cv_subjects": MIN_CV_SUBJECTS,
+                    "random_state": RANDOM_STATE,
+                },
+                sort_keys=True,
+            ).encode()
+        )
+        self.directory = Path(directory) / digest.hexdigest()
+        self.directory.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, task_id: str) -> Path:
+        safe_id = hashlib.sha256(task_id.encode()).hexdigest()[:16]
+        return self.directory / f"task-{safe_id}.json"
+
+    def load(self, task_id: str, fingerprint: str) -> TaskOutcome | None:
+        path = self._path(task_id)
+        if not path.exists():
+            return None
+        try:
+            payload = json.loads(path.read_text())
+            if payload["fingerprint"] != fingerprint:
+                return None
+            raw_score = payload.get("score")
+            score = None
+            if raw_score is not None:
+                raw_score["repeat_scores"] = tuple(raw_score["repeat_scores"])
+                score = TaskScore(**raw_score)
+            return TaskOutcome(
+                task_id=payload["task_id"],
+                dataset_id=payload["dataset_id"],
+                status=payload["status"],
+                score=score,
+                reason=payload.get("reason"),
+            )
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+            logging.warning("ignoring invalid task checkpoint: %s", path)
+            return None
+
+    def save(self, outcome: TaskOutcome, fingerprint: str) -> None:
+        path = self._path(outcome.task_id)
+        score = None
+        if outcome.score is not None:
+            score = {
+                "task_id": outcome.score.task_id,
+                "dataset_id": outcome.score.dataset_id,
+                "category": outcome.score.category,
+                "metric": outcome.score.metric,
+                "score": outcome.score.score,
+                "n_samples": outcome.score.n_samples,
+                "repeat_scores": list(outcome.score.repeat_scores),
+                "diagnostics": outcome.score.diagnostics,
+            }
+        payload = {
+            "fingerprint": fingerprint,
+            "task_id": outcome.task_id,
+            "dataset_id": outcome.dataset_id,
+            "status": outcome.status,
+            "score": score,
+            "reason": outcome.reason,
+        }
+        temporary = path.with_suffix(".tmp")
+        temporary.write_text(json.dumps(payload, sort_keys=True) + "\n")
+        temporary.replace(path)
+
+
+def _task_fingerprint(
+    task: dict,
+    labels: pd.DataFrame,
+    targets: PerturbationTargets | None,
+) -> str:
+    """Fingerprint every private input that can affect a task checkpoint."""
+    digest = hashlib.sha256(
+        json.dumps(task, sort_keys=True, separators=(",", ":")).encode()
+    )
+    digest.update(json.dumps(list(labels.columns)).encode())
+    digest.update(json.dumps([str(dtype) for dtype in labels.dtypes]).encode())
+    digest.update(pd.util.hash_pandas_object(labels, index=True).values.tobytes())
+    if targets is not None:
+        digest.update(targets.delta.tobytes())
+        digest.update(targets.gene_ids.astype(str).tobytes())
+    return digest.hexdigest()
+
+
+def _regression_geometry(labels: pd.DataFrame) -> str:
+    """Identify tasks whose design matrices and evaluation splits are identical."""
+    columns = [SAMPLE_ID, SUBJECT_ID, *_fold_columns(labels)]
+    if SPLIT in labels:
+        columns.append(SPLIT)
+    frame = labels[columns]
+    digest = hashlib.sha256(json.dumps(columns).encode())
+    digest.update(pd.util.hash_pandas_object(frame, index=True).values.tobytes())
+    return digest.hexdigest()
+
+
+def _outcome_from_score(task: dict, score: TaskScore) -> TaskOutcome:
+    """Map a completed score to the public scored/invalid outcome contract."""
+    task_id = _norm_id(task[TASK_ID])
+    dataset_id = _norm_id(task[DATASET_ID])
+    if not np.isfinite(score.score):
+        return TaskOutcome(
+            task_id,
+            dataset_id,
+            "invalid",
+            reason="degenerate score (constant predictions)",
+        )
+    return TaskOutcome(task_id, dataset_id, "scored", score=score)
+
+
+def _norm_id(value: object) -> str:
+    """Normalise an id so int/str/float spellings of the same id join."""
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value).strip()
+
+
+def load_tasks_registry(path: str | Path) -> list[dict]:
+    """Read the private ``tasks.yaml`` registry (one entry per task)."""
+    with open(path) as handle:
+        data = yaml.safe_load(handle)
+    tasks = data.get("tasks", []) if isinstance(data, dict) else (data or [])
+    ids = [_norm_id(t[TASK_ID]) for t in tasks]
+    if len(set(ids)) != len(ids):
+        raise EvaluatorError(f"duplicate task_id in the registry: {ids}")
+    return tasks
+
+
+def _fold_columns(labels: pd.DataFrame) -> list[str]:
+    """Return the ordered external-CV fold columns in private labels."""
+    repeated = [column for column in labels if column.startswith(FOLD_PREFIX)]
+    invalid = [
+        column for column in repeated if not column.removeprefix(FOLD_PREFIX).isdigit()
+    ]
+    if invalid:
+        raise EvaluatorError(f"labels.csv has invalid repeat-fold columns: {invalid}")
+    first = [FOLD] if FOLD in labels.columns else []
+    return [
+        *first,
+        *sorted(repeated, key=lambda column: int(column.removeprefix(FOLD_PREFIX))),
+    ]
+
+
+def load_labels(path: str | Path) -> pd.DataFrame:
+    """Read private labels with repeated CV folds or one transfer split."""
+    df = pd.read_csv(path)
+    is_perturbation = PAIR_ID in df.columns
+    required = (
+        {SAMPLE_ID, SUBJECT_ID, PAIR_ID}
+        if is_perturbation
+        else {SAMPLE_ID, SUBJECT_ID, LABEL}
+    )
+    missing = required - set(df.columns)
+    if missing:
+        raise EvaluatorError(f"labels.csv missing columns: {sorted(missing)}")
+    _subject_groups(df)
+    has_folds = bool(_fold_columns(df))
+    has_split = SPLIT in df.columns
+    pairing_values = (
+        set(df[PAIRING].astype(str)) if is_perturbation and PAIRING in df else set()
+    )
+    is_cartesian = pairing_values == {CARTESIAN}
+    if sum((has_folds, has_split, is_cartesian)) != 1:
+        raise EvaluatorError(
+            "labels.csv needs exactly one evaluation assignment: folds, transfer "
+            "split, or Cartesian pairing."
+        )
+    if is_cartesian:
+        missing = {CONTROL_ID, PERTURBED_ID, PAIRING} - set(df.columns)
+        if missing:
+            raise EvaluatorError(
+                f"Cartesian labels.csv missing columns: {sorted(missing)}"
+            )
+    return df
+
+
+def load_targets(path: str | Path) -> PerturbationTargets:
+    """Read and validate one task's hidden perturbation responses."""
+    with np.load(path, allow_pickle=False) as data:
+        missing = {"delta", "gene_ids"} - set(data.files)
+        if missing:
+            raise EvaluatorError(f"targets.npz missing arrays: {sorted(missing)}")
+        delta = np.asarray(data["delta"], dtype=float)
+        gene_ids = np.asarray(data["gene_ids"]).astype(str)
+    if delta.ndim != 2:
+        raise EvaluatorError(f"targets delta must be 2D, got shape {delta.shape}")
+    if gene_ids.ndim != 1 or len(gene_ids) != delta.shape[1]:
+        raise EvaluatorError("targets gene_ids must align with delta columns")
+    if not np.isfinite(delta).all():
+        raise EvaluatorError("targets delta contains NaN or inf values")
+    return PerturbationTargets(delta=delta, gene_ids=gene_ids)
+
+
+def load_submission(path: str | Path) -> dict[str, pd.DataFrame]:
+    """Load a multi-dataset submission into ``{dataset_id: raw_block_frame}``."""
+    ext = Path(path).suffix.lower()
+    if ext == ".npz":
+        frame = _npz_to_frame(path)
+    elif ext in (".parquet", ".pq"):
+        frame = pd.read_parquet(path)
+    elif ext in (".tsv", ".txt"):
+        frame = pd.read_csv(path, sep="\t")
+    elif ext == ".csv":
+        frame = pd.read_csv(path)
+    else:
+        raise SubmissionError(
+            f"unsupported submission type '{ext}'. Use .csv/.tsv/.parquet/.npz"
+        )
+    return _split_by_dataset(frame)
+
+
+def _npz_to_frame(path: str | Path) -> pd.DataFrame:
+    try:
+        data = np.load(path, allow_pickle=False)
+    except (ValueError, EOFError, zipfile.BadZipFile) as err:
+        raise SubmissionError(NOT_NPZ) from err
+    if not isinstance(data, np.lib.npyio.NpzFile):
+        raise SubmissionError(NOT_NPZ)
+    ds_key = next((k for k in NPZ_DSID_KEYS if k in data), None)
+    id_key = next((k for k in NPZ_ID_KEYS if k in data), None)
+    emb_key = next((k for k in NPZ_EMB_KEYS if k in data), None)
+    if ds_key is None or id_key is None or emb_key is None:
+        raise SubmissionError(
+            f".npz needs a dataset-id array {NPZ_DSID_KEYS}, a sample-id array "
+            f"{NPZ_ID_KEYS}, and an embedding array {NPZ_EMB_KEYS}; "
+            f"found {list(data.keys())}"
+        )
+    try:
+        emb = np.asarray(data[emb_key])
+        sample_ids = np.asarray(data[id_key])
+        dataset_ids = np.asarray(data[ds_key])
+    except (ValueError, zipfile.BadZipFile) as err:
+        raise SubmissionError(
+            f"cannot read the .npz arrays ({err}). Save ids as text, e.g. "
+            "np.asarray(ids, dtype=str), or use .csv/.parquet"
+        ) from err
+    if emb.ndim != 2:
+        raise SubmissionError(f"embeddings must be 2D, got shape {emb.shape}")
+    frame = pd.DataFrame(emb)
+    frame.insert(0, SAMPLE_ID, sample_ids)
+    frame.insert(0, DATASET_ID, dataset_ids)
+    return frame
+
+
+def _split_by_dataset(frame: pd.DataFrame) -> dict[str, pd.DataFrame]:
+    """Group a submission by ``dataset_id`` into per-dataset blocks (raw frames)."""
+    lower = {str(c).lower(): c for c in frame.columns}
+    if DATASET_ID not in lower:
+        raise SubmissionError(
+            f"submission needs a '{DATASET_ID}' column; found {list(frame.columns)}"
+        )
+    ds_col = lower[DATASET_ID]
+    blocks: dict[str, pd.DataFrame] = {}
+    for raw_ds, group in frame.groupby(ds_col, sort=False):
+        dataset_id = _norm_id(raw_ds)
+        if dataset_id in blocks:
+            raise SubmissionError(
+                f"dataset_id '{dataset_id}' appears under multiple spellings"
+            )
+        blocks[dataset_id] = group.drop(columns=[ds_col]).dropna(axis=1, how="all")
+    if not blocks:
+        raise SubmissionError("empty submission")
+    return blocks
+
+
+def _to_embedding_frame(frame: pd.DataFrame) -> pd.DataFrame:
+    lower = {str(c).lower(): c for c in frame.columns}
+    if SAMPLE_ID not in lower:
+        raise SubmissionError(
+            f"submission needs a '{SAMPLE_ID}' column; found {list(frame.columns)}"
+        )
+    id_col = lower[SAMPLE_ID]
+    ids = [_norm_id(v) for v in frame[id_col]]
+    emb = frame.drop(columns=[id_col])
+    non_numeric = [c for c in emb.columns if not pd.api.types.is_numeric_dtype(emb[c])]
+    if non_numeric:
+        raise SubmissionError(
+            f"embedding columns must be numeric; non-numeric: {non_numeric[:5]}"
+        )
+    if emb.shape[1] == 0:
+        raise SubmissionError("submission has no embedding columns")
+    out = emb.astype(float)
+    out.index = ids
+    if out.index.has_duplicates:
+        dups = out.index[out.index.duplicated()].unique().tolist()
+        raise SubmissionError(f"duplicate sample_ids in submission: {dups[:5]}")
+    return out
+
+
+def _l2_normalize_rows(emb: pd.DataFrame) -> pd.DataFrame:
+    """Put every sample on the unit sphere; an embedding dimension has no unit."""
+    norms = np.linalg.norm(emb.to_numpy(dtype=float), axis=1, keepdims=True)
+    return pd.DataFrame(
+        emb.to_numpy(dtype=float) / np.where(norms == 0.0, 1.0, norms),
+        index=emb.index,
+        columns=emb.columns,
+    )
+
+
+def _load_reference(path: str | Path) -> dict[str, pd.DataFrame]:
+    """Read the gene-space reference concatenated to submissions, by dataset.
+
+    The reference is ours, so any defect in it is an ``EvaluatorError``.
+    """
+    try:
+        return {
+            dataset_id: _to_embedding_frame(block)
+            for dataset_id, block in load_submission(path).items()
+        }
+    except (OSError, ValueError) as error:
+        message = f"could not load the reference features: {error}"
+        raise EvaluatorError(message) from error
+
+
+def _concat_reference(emb: pd.DataFrame, reference: pd.DataFrame) -> pd.DataFrame:
+    """Append the reference columns to each sample, then L2-normalize the row.
+
+    Samples absent from either side are dropped, so a labelled sample the
+    submission lacks still fails ``_align`` exactly as without a reference. One
+    the reference lacks is caught first by ``_check_reference_covers``.
+    """
+    joined = emb.add_prefix("model_").join(
+        reference.add_prefix("reference_"), how="inner"
+    )
+    return _l2_normalize_rows(joined)
+
+
+def _check_reference_covers(
+    labels: pd.DataFrame, reference: pd.DataFrame, task_id: str
+) -> None:
+    """Raise if the reference lacks a labelled sample: that defect is ours."""
+    lab_ids = [_norm_id(v) for v in labels[SAMPLE_ID]]
+    present = set(reference.index)
+    missing = [s for s in lab_ids if s not in present]
+    if missing:
+        raise EvaluatorError(
+            f"reference features lack {len(missing)}/{len(lab_ids)} labelled "
+            f"samples of {task_id}, e.g. {missing[:5]}"
+        )
+
+
+def _align(labels: pd.DataFrame, emb: pd.DataFrame) -> np.ndarray:
+    """Return the embedding matrix in labels order, or raise if a sample is missing."""
+    lab_ids = [_norm_id(v) for v in labels[SAMPLE_ID]]
+    present = set(emb.index)
+    missing = [s for s in lab_ids if s not in present]
+    if missing:
+        raise SubmissionError(
+            f"{len(missing)}/{len(lab_ids)} labelled samples missing from "
+            f"submission, e.g. {missing[:5]}"
+        )
+    matrix = emb.loc[lab_ids].to_numpy(dtype=float)
+    if not np.isfinite(matrix).all():
+        raise SubmissionError("submission contains NaN or inf values")
+    return matrix
+
+
+def _subject_groups(labels: pd.DataFrame) -> np.ndarray:
+    """Return normalized private subject ids, rejecting unusable metadata."""
+    if SUBJECT_ID not in labels:
+        raise EvaluatorError(f"labels.csv missing columns: ['{SUBJECT_ID}']")
+    if labels[SUBJECT_ID].isna().any():
+        raise EvaluatorError("labels.csv has missing subject_id values")
+    groups = np.array([_norm_id(value) for value in labels[SUBJECT_ID]])
+    if np.any(groups == ""):
+        raise EvaluatorError("labels.csv has empty subject_id values")
+    return groups
+
+
+def _group_inner_cv(groups_train: np.ndarray) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Subject-grouped inner folds for ridge penalty selection."""
+    n_groups = len(np.unique(groups_train))
+    n_splits = min(INNER_CV, n_groups)
+    if n_splits < 2:
+        raise SubmissionError("an outer training fold has fewer than two subjects")
+    splitter = GroupKFold(n_splits=n_splits)
+    rows = np.zeros(len(groups_train))
+    return list(splitter.split(rows, groups=groups_train))
+
+
+def _ridge_fold_losses(
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_test: np.ndarray,
+    y_test: np.ndarray,
+) -> np.ndarray:
+    """Return validation MSE for every alpha from one exact SVD."""
+    return np.mean(_ridge_fold_target_losses(x_train, y_train, x_test, y_test), axis=1)
+
+
+def _ridge_fold_target_losses(
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_test: np.ndarray,
+    y_test: np.ndarray,
+) -> np.ndarray:
+    """Return per-target validation MSE while sharing one factorization."""
+    y_train = np.asarray(y_train)
+    y_test = np.asarray(y_test)
+    if y_train.ndim == 1:
+        y_train = y_train[:, None]
+        y_test = y_test[:, None]
+    x_offset = np.mean(x_train, axis=0)
+    y_offset = np.mean(y_train, axis=0)
+    x_centered = x_train - x_offset
+    y_centered = y_train - y_offset
+    u, singular_values, vt = np.linalg.svd(x_centered, full_matrices=False)
+    projected_x = (x_test - x_offset) @ vt.T
+    projected_y = u.T @ y_centered
+    shrinkage = singular_values[:, None] / (
+        singular_values[:, None] ** 2 + RIDGE_ALPHAS[None, :]
+    )
+    losses = []
+    for index in range(len(RIDGE_ALPHAS)):
+        predictions = projected_x @ (shrinkage[:, index, None] * projected_y) + y_offset
+        losses.append(np.mean((predictions - y_test) ** 2, axis=0))
+    return np.asarray(losses)
+
+
+def _ridge_alpha(matrix: np.ndarray, target: np.ndarray, groups: np.ndarray) -> float:
+    """Select the grouped-CV ridge penalty without refitting for every alpha."""
+    losses = [
+        _ridge_fold_losses(matrix[train], target[train], matrix[test], target[test])
+        for train, test in _group_inner_cv(groups)
+    ]
+    return float(RIDGE_ALPHAS[np.argmin(np.mean(losses, axis=0))])
+
+
+def _ridge_alphas_by_target(
+    matrix: np.ndarray, targets: np.ndarray, groups: np.ndarray
+) -> np.ndarray:
+    """Select independent penalties while sharing each fold's factorization."""
+    losses = [
+        _ridge_fold_target_losses(
+            matrix[train], targets[train], matrix[test], targets[test]
+        )
+        for train, test in _group_inner_cv(groups)
+    ]
+    mean_losses = np.mean(losses, axis=0)
+    return RIDGE_ALPHAS[np.argmin(mean_losses, axis=0)]
+
+
+def _ridge_predict(
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_test: np.ndarray,
+    groups_train: np.ndarray,
+) -> np.ndarray:
+    """Fit ridge with an exact grouped-CV spectral alpha search."""
+    alpha = _ridge_alpha(x_train, y_train, groups_train)
+    return Ridge(alpha=alpha).fit(x_train, y_train).predict(x_test)
+
+
+def _ridge_predict_by_target(
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_test: np.ndarray,
+    groups_train: np.ndarray,
+) -> np.ndarray:
+    """Fit independent targets while reusing their spectral CV decompositions."""
+    alphas = _ridge_alphas_by_target(x_train, y_train, groups_train)
+    return Ridge(alpha=alphas).fit(x_train, y_train).predict(x_test)
+
+
+def _relabelled_groups(groups: np.ndarray, seed: int) -> np.ndarray:
+    """Reorder group tie-breaks without shuffling label counts between groups."""
+    unique, codes = np.unique(groups, return_inverse=True)
+    return np.random.default_rng(seed).permutation(len(unique))[codes]
+
+
+def _inner_cv(
+    y_train: np.ndarray, groups_train: np.ndarray
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Stratified subject-grouped folds for logistic penalty selection."""
+    classes = np.unique(y_train)
+    support = min(len(np.unique(groups_train[y_train == label])) for label in classes)
+    n_splits = min(INNER_CV, support)
+    if n_splits < 2:
+        raise SubmissionError(
+            "an outer training fold has fewer than two subjects in a class"
+        )
+    rows = np.zeros(len(y_train))
+    relabelled_groups = _relabelled_groups(groups_train, RANDOM_STATE)
+    splitter = StratifiedGroupKFold(n_splits=n_splits)
+    splits = list(splitter.split(rows, y_train, relabelled_groups))
+    expected_classes = set(classes)
+    if not all(
+        set(np.unique(y_train[train])) == expected_classes
+        and set(np.unique(y_train[test])) == expected_classes
+        for train, test in splits
+    ):
+        raise SubmissionError(
+            "could not construct inner subject-grouped folds with every class"
+        )
+    return splits
+
+
+def fit_predict(
+    task_type: str,
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_test: np.ndarray,
+    classes: np.ndarray,
+    groups_train: np.ndarray,
+    inner_cv_jobs: int = INNER_CV_JOBS,
+    logreg_tol: float | None = None,
+) -> np.ndarray:
+    """Fit the fixed linear probe on train, return predictions for test."""
+    scaler = StandardScaler().fit(x_train)
+    x_train = scaler.transform(x_train)
+    x_test = scaler.transform(x_test)
+    logreg_tol = LOGREG_TOL if logreg_tol is None else logreg_tol
+    if task_type == "classification":
+        if len(np.unique(y_train)) < 2:
+            raise SubmissionError("a training fold has a single class")
+        scoring = "roc_auc" if len(classes) == 2 else "roc_auc_ovr_weighted"
+        clf = LogisticRegressionCV(
+            Cs=LOGREG_CS,
+            cv=_inner_cv(y_train, groups_train),
+            scoring=scoring,
+            solver="lbfgs",
+            max_iter=MAX_ITER,
+            n_jobs=inner_cv_jobs,
+            random_state=RANDOM_STATE,
+            tol=logreg_tol,
+        ).fit(x_train, y_train)
+        proba = clf.predict_proba(x_test)
+        col = {c: i for i, c in enumerate(clf.classes_)}
+        out = np.zeros((x_test.shape[0], len(classes)))
+        for j, c in enumerate(classes):
+            if c in col:
+                out[:, j] = proba[:, col[c]]
+        return out
+    return _ridge_predict(x_train, y_train, x_test, groups_train)
+
+
+def _fold_score(
+    metric: str,
+    task_type: str,
+    y: np.ndarray,
+    folds: np.ndarray,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+    groups: np.ndarray,
+    inner_cv_jobs: int = INNER_CV_JOBS,
+    logreg_tol: float | None = None,
+) -> float:
+    """Return the mean native metric across one external CV partition."""
+    scores = []
+    for fold in sorted(np.unique(folds)):
+        test = folds == fold
+        predictions = fit_predict(
+            task_type,
+            matrix[~test],
+            y[~test],
+            matrix[test],
+            classes,
+            groups[~test],
+            inner_cv_jobs,
+            logreg_tol,
+        )
+        try:
+            scores.append(METRICS[metric](y[test], predictions, classes))
+        except ValueError as error:
+            raise SubmissionError(
+                f"CV fold {fold} is not scoreable: {error}"
+            ) from error
+    if not np.isfinite(scores).all():
+        raise SubmissionError("a CV fold produced a non-finite score")
+    return float(np.mean(scores))
+
+
+def _parallel_fold_score(
+    metric: str,
+    task_type: str,
+    y: np.ndarray,
+    folds: np.ndarray,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+    groups: np.ndarray,
+    logreg_tol: float,
+) -> float:
+    """Score one repeat in an outer worker without nested inner processes."""
+    return _fold_score(
+        metric,
+        task_type,
+        y,
+        folds,
+        matrix,
+        classes,
+        groups,
+        inner_cv_jobs=1,
+        logreg_tol=logreg_tol,
+    )
+
+
+def _repeated_cv_scores(
+    metric: str,
+    task_type: str,
+    y: np.ndarray,
+    labels: pd.DataFrame,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+) -> tuple[float, ...]:
+    """Return one mean fold metric for every external CV repeat."""
+    groups = _subject_groups(labels)
+    columns = _fold_columns(labels)
+    workers = min(OUTER_CV_JOBS, len(columns))
+    if workers == 1:
+        scores = [
+            _fold_score(
+                metric,
+                task_type,
+                y,
+                labels[column].to_numpy(),
+                matrix,
+                classes,
+                groups,
+            )
+            for column in columns
+        ]
+    else:
+        with parallel_backend("loky", inner_max_num_threads=1):
+            scores = Parallel(n_jobs=workers)(
+                delayed(_parallel_fold_score)(
+                    metric,
+                    task_type,
+                    y,
+                    labels[column].to_numpy(),
+                    matrix,
+                    classes,
+                    groups,
+                    LOGREG_TOL,
+                )
+                for column in columns
+            )
+    return tuple(float(score) for score in scores)
+
+
+def _repeated_cv_score(
+    metric: str,
+    task_type: str,
+    y: np.ndarray,
+    labels: pd.DataFrame,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+) -> float:
+    """Return the aggregate repeated-CV score for legacy callers."""
+    return float(
+        np.mean(_repeated_cv_scores(metric, task_type, y, labels, matrix, classes))
+    )
+
+
+def _regression_fold_scores(
+    metrics: tuple[str, ...],
+    targets: np.ndarray,
+    folds: np.ndarray,
+    matrix: np.ndarray,
+    groups: np.ndarray,
+) -> tuple[float, ...]:
+    """Score compatible regression targets with shared ridge factorizations."""
+    fold_scores: list[list[float]] = [[] for _ in metrics]
+    for fold in sorted(np.unique(folds)):
+        test = folds == fold
+        scaler = StandardScaler().fit(matrix[~test])
+        x_train = scaler.transform(matrix[~test])
+        x_test = scaler.transform(matrix[test])
+        predictions = _ridge_predict_by_target(
+            x_train, targets[~test], x_test, groups[~test]
+        )
+        for index, metric in enumerate(metrics):
+            fold_scores[index].append(
+                METRICS[metric](targets[test, index], predictions[:, index], None)
+            )
+    if not all(np.isfinite(scores).all() for scores in fold_scores):
+        raise SubmissionError("a CV fold produced a non-finite score")
+    return tuple(float(np.mean(scores)) for scores in fold_scores)
+
+
+def _repeated_regression_scores(
+    metrics: tuple[str, ...],
+    targets: np.ndarray,
+    labels: pd.DataFrame,
+    matrix: np.ndarray,
+) -> tuple[tuple[float, ...], ...]:
+    """Return repeat scores per target for compatible regression tasks."""
+    groups = _subject_groups(labels)
+    columns = _fold_columns(labels)
+    workers = min(OUTER_CV_JOBS, len(columns))
+    if workers == 1:
+        by_repeat = [
+            _regression_fold_scores(
+                metrics, targets, labels[column].to_numpy(), matrix, groups
+            )
+            for column in columns
+        ]
+    else:
+        with parallel_backend("loky", inner_max_num_threads=1):
+            by_repeat = Parallel(n_jobs=workers)(
+                delayed(_regression_fold_scores)(
+                    metrics,
+                    targets,
+                    labels[column].to_numpy(),
+                    matrix,
+                    groups,
+                )
+                for column in columns
+            )
+    return tuple(
+        tuple(float(scores[index]) for scores in by_repeat)
+        for index in range(len(metrics))
+    )
+
+
+def _score_regression_group(
+    tasks: list[dict], labels_by_task: list[pd.DataFrame], emb: pd.DataFrame
+) -> list[TaskScore]:
+    """Score regression tasks that have identical samples and assignments."""
+    labels = labels_by_task[0]
+    matrix = _align(labels, emb)
+    targets = np.column_stack([frame[LABEL].to_numpy() for frame in labels_by_task])
+    metrics = tuple(str(task["metric"]) for task in tasks)
+    unknown = set(metrics) - set(METRICS)
+    if unknown:
+        raise EvaluatorError(f"unknown metric(s) for regression tasks: {unknown}")
+    if SPLIT in labels:
+        split = labels[SPLIT].to_numpy()
+        train, test = split == SPLIT_TRAIN, split == SPLIT_TEST
+        if not train.any() or not test.any():
+            raise EvaluatorError("transfer labels.csv has an empty train or test side")
+        scaler = StandardScaler().fit(matrix[train])
+        predictions = _ridge_predict_by_target(
+            scaler.transform(matrix[train]),
+            targets[train],
+            scaler.transform(matrix[test]),
+            _subject_groups(labels)[train],
+        )
+        repeat_scores = tuple(
+            (METRICS[metric](targets[test, index], predictions[:, index], None),)
+            for index, metric in enumerate(metrics)
+        )
+        n_samples = int(test.sum())
+    else:
+        repeat_scores = _repeated_regression_scores(metrics, targets, labels, matrix)
+        n_samples = len(labels)
+    return [
+        TaskScore(
+            task_id=_norm_id(task[TASK_ID]),
+            dataset_id=_norm_id(task[DATASET_ID]),
+            category=str(task["category"]),
+            metric=metrics[index],
+            score=float(np.mean(repeat_scores[index])),
+            n_samples=n_samples,
+            repeat_scores=repeat_scores[index],
+        )
+        for index, task in enumerate(tasks)
+    ]
+
+
+def _uses_leave_pair_out(metric: str, y: np.ndarray, groups: np.ndarray) -> bool:
+    """Is this a binary AUROC task with fewer than ``MIN_CV_SUBJECTS`` subjects?
+
+    Paired tasks, where a subject carries both labels, stay on CV.
+    """
+    return (
+        metric == "auroc"
+        and len(np.unique(y)) == 2
+        and len(np.unique(groups)) < MIN_CV_SUBJECTS
+        and pd.Series(y).groupby(groups).nunique().max() == 1
+    )
+
+
+def _subject_labels(y: np.ndarray, subjects: np.ndarray) -> pd.Series:
+    """Return one label per subject, indexed by subject id."""
+    per_subject = pd.Series(y).groupby(subjects)
+    if (per_subject.nunique() > 1).any():
+        raise EvaluatorError("a subject carries more than one label")
+    return per_subject.first()
+
+
+def _ranked_pairs(scores: np.ndarray, is_positive: np.ndarray) -> tuple[float, int]:
+    """Count correctly ordered positive-negative sample pairs, ties as half."""
+    gaps = scores[is_positive][:, None] - scores[~is_positive][None, :]
+    if not np.isfinite(gaps).all():
+        raise SubmissionError("a leave-pair-out fit produced a non-finite score")
+    return float((gaps > 0).sum() + 0.5 * (gaps == 0).sum()), int(gaps.size)
+
+
+def _pair_ranks(
+    y: np.ndarray,
+    subjects: np.ndarray,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+    pair: tuple[str, str],
+) -> tuple[float, int]:
+    """Fit without one subject pair, then count its sample pairs ranked right."""
+    positive, negative = pair
+    held_out = np.isin(subjects, [positive, negative])
+    scores = fit_predict(
+        "classification",
+        matrix[~held_out],
+        y[~held_out],
+        matrix[held_out],
+        classes,
+        subjects[~held_out],
+        inner_cv_jobs=1,
+    )[:, 1]
+    return _ranked_pairs(scores, subjects[held_out] == positive)
+
+
+def _leave_pair_out_score(
+    y: np.ndarray, subjects: np.ndarray, matrix: np.ndarray, classes: np.ndarray
+) -> float:
+    """Fraction of sample pairs ranked right, each subject pair held out once."""
+    per_subject = _subject_labels(y, subjects)
+    pairs = list(
+        itertools.product(
+            per_subject.index[per_subject == classes[1]],
+            per_subject.index[per_subject == classes[0]],
+        )
+    )
+    workers = min(OUTER_CV_JOBS, len(pairs))
+    if workers == 1:
+        counts = [_pair_ranks(y, subjects, matrix, classes, pair) for pair in pairs]
+    else:
+        with parallel_backend("loky", inner_max_num_threads=1):
+            counts = Parallel(n_jobs=workers)(
+                delayed(_pair_ranks)(y, subjects, matrix, classes, pair)
+                for pair in pairs
+            )
+    correct = sum(pair_correct for pair_correct, _ in counts)
+    total = sum(pair_total for _, pair_total in counts)
+    return correct / total
+
+
+def _transfer_predict(
+    task_type: str,
+    y: np.ndarray,
+    split: np.ndarray,
+    matrix: np.ndarray,
+    classes: np.ndarray,
+    groups: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Fit once on the train cohort, predict the test cohort (no pooling)."""
+    train, test = split == SPLIT_TRAIN, split == SPLIT_TEST
+    if not train.any() or not test.any():
+        raise EvaluatorError("transfer labels.csv has an empty train or test side")
+    preds = fit_predict(
+        task_type,
+        matrix[train],
+        y[train],
+        matrix[test],
+        classes,
+        groups[train],
+    )
+    return y[test], preds
+
+
+def _select_degs(delta_train: np.ndarray, n_top: int) -> np.ndarray:
+    """Select the strongest mean absolute responses using training rows only."""
+    n_keep = min(int(n_top), delta_train.shape[1])
+    if n_keep <= 0:
+        raise EvaluatorError("perturbation task has no response genes to select")
+    effect = np.abs(np.mean(delta_train, axis=0))
+    return np.argsort(effect, kind="stable")[-n_keep:]
+
+
+def _mean_scores(scores: list[float]) -> float:
+    """Average finite fold scores."""
+    finite = np.asarray(scores)[np.isfinite(scores)]
+    return float(np.mean(finite)) if len(finite) else float("nan")
+
+
+def _perturbation_fold(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    groups: np.ndarray,
+    train: np.ndarray,
+    test: np.ndarray,
+    n_top: int,
+    target_centered: bool,
+) -> float:
+    """Fit and score one leakage-safe perturbation fold."""
+    if not train.any() or not test.any():
+        raise EvaluatorError("perturbation fold has an empty train or test side")
+    genes = _select_degs(delta[train], n_top)
+    y_train = delta[train][:, genes]
+    y_test = delta[test][:, genes]
+    scaler = StandardScaler().fit(matrix[train])
+    x_train = scaler.transform(matrix[train])
+    x_test = np.clip(
+        scaler.transform(matrix[test]),
+        -PERTURBATION_TEST_Z_CLIP,
+        PERTURBATION_TEST_Z_CLIP,
+    )
+    predictions = _ridge_predict(x_train, y_train, x_test, groups[train])
+    if target_centered:
+        correlation = compute_target_centered_sample_spearman(y_test, predictions)
+    else:
+        training_mean = np.mean(y_train, axis=0)
+        correlation = compute_residual_sample_spearman(
+            y_test, predictions, training_mean
+        )
+    if not np.isfinite(correlation):
+        raise SubmissionError("a perturbation fold has a degenerate Spearman score")
+    return float(np.clip(correlation, -1.0, 1.0))
+
+
+def _perturbation_repeat(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    groups: np.ndarray,
+    partitions: list[tuple[np.ndarray, np.ndarray]],
+    n_top: int,
+) -> float:
+    """Score every fold in one perturbation repeat."""
+    return _mean_scores(
+        [
+            _perturbation_fold(matrix, delta, groups, train, test, n_top, False)
+            for train, test in partitions
+        ]
+    )
+
+
+def _parallel_perturbation_repeats(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    groups: np.ndarray,
+    repeats: list[list[tuple[np.ndarray, np.ndarray]]],
+    n_top: int,
+) -> tuple[float, ...]:
+    """Score independent perturbation repeats across available workers."""
+    workers = (
+        min(OUTER_CV_JOBS, len(repeats))
+        if len(matrix) >= OUTER_PARALLEL_MIN_SAMPLES
+        else 1
+    )
+    if workers == 1:
+        scores = [
+            _perturbation_repeat(matrix, delta, groups, folds, n_top)
+            for folds in repeats
+        ]
+    else:
+        with parallel_backend("loky", inner_max_num_threads=1):
+            scores = Parallel(n_jobs=workers)(
+                delayed(_perturbation_repeat)(matrix, delta, groups, folds, n_top)
+                for folds in repeats
+            )
+    return tuple(float(score) for score in scores)
+
+
+def _paired_perturbation_scores(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    labels: pd.DataFrame,
+    n_top: int,
+) -> tuple[float, ...]:
+    """Score each frozen subject-grouped CV partition the labels carry."""
+    groups = _subject_groups(labels)
+    repeats = []
+    for column in _fold_columns(labels):
+        folds = labels[column].to_numpy()
+        repeats.append(
+            [(folds != fold, folds == fold) for fold in sorted(np.unique(folds))]
+        )
+    return _parallel_perturbation_repeats(matrix, delta, groups, repeats, n_top)
+
+
+def _transfer_perturbation_scores(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    labels: pd.DataFrame,
+    n_top: int,
+    target_centered: bool,
+) -> tuple[tuple[float, ...], int]:
+    """Train every response-decoding component on the source disease only."""
+    groups = _subject_groups(labels)
+    split = labels[SPLIT].astype(str).to_numpy()
+    train, test = split == SPLIT_TRAIN, split == SPLIT_TEST
+    metrics = _perturbation_fold(
+        matrix, delta, groups, train, test, n_top, target_centered
+    )
+    return (metrics,), int(test.sum())
+
+
+def _cartesian_partitions(
+    control_ids: np.ndarray, perturbed_ids: np.ndarray
+) -> list[list[tuple[np.ndarray, np.ndarray]]]:
+    """Build six 3-fold specimen-isolated partitions for a 3x3 response grid."""
+    controls = np.unique(control_ids)
+    perturbed = np.unique(perturbed_ids)
+    if len(controls) != 3 or len(perturbed) != 3:
+        raise EvaluatorError(
+            "Cartesian perturbation evaluation requires exactly three controls "
+            "and three perturbed specimens."
+        )
+    repeats = []
+    for assignment in itertools.permutations(perturbed):
+        folds = []
+        for control_id, perturbed_id in zip(controls, assignment):
+            test = (control_ids == control_id) & (perturbed_ids == perturbed_id)
+            train = (control_ids != control_id) & (perturbed_ids != perturbed_id)
+            if test.sum() != 1 or train.sum() != 4:
+                raise EvaluatorError("Cartesian labels do not form a complete 3x3 grid")
+            folds.append((train, test))
+        repeats.append(folds)
+    return repeats
+
+
+def _cartesian_perturbation_scores(
+    matrix: np.ndarray,
+    delta: np.ndarray,
+    labels: pd.DataFrame,
+    n_top: int,
+) -> tuple[float, ...]:
+    """Evaluate all control-to-perturbed permutations without specimen leakage."""
+    groups = _subject_groups(labels)
+    repeats = _cartesian_partitions(
+        labels[CONTROL_ID].astype(str).to_numpy(),
+        labels[PERTURBED_ID].astype(str).to_numpy(),
+    )
+    return _parallel_perturbation_repeats(matrix, delta, groups, repeats, n_top)
+
+
+def _score_perturbation_task(
+    task: dict,
+    labels: pd.DataFrame,
+    emb: pd.DataFrame,
+    targets: PerturbationTargets,
+) -> TaskScore:
+    """Decode one hidden response matrix from submitted baseline embeddings."""
+    if len(labels) != len(targets.delta):
+        raise EvaluatorError("labels.csv and targets.npz have different row counts")
+    matrix = _align(labels, emb)
+    n_top = int(task.get("n_top_de_genes", 0))
+    pairing = str(task.get(PAIRING, labels.get(PAIRING, pd.Series([PAIRED])).iloc[0]))
+    if SPLIT in labels:
+        repeat_scores, n_samples = _transfer_perturbation_scores(
+            matrix,
+            targets.delta,
+            labels,
+            n_top,
+            bool(task.get("target_centered", False)),
+        )
+    elif pairing == CARTESIAN:
+        repeat_scores = _cartesian_perturbation_scores(
+            matrix, targets.delta, labels, n_top
+        )
+        n_samples = len(labels)
+    else:
+        repeat_scores = _paired_perturbation_scores(
+            matrix, targets.delta, labels, n_top
+        )
+        n_samples = len(labels)
+    return TaskScore(
+        task_id=_norm_id(task[TASK_ID]),
+        dataset_id=_norm_id(task[DATASET_ID]),
+        category=str(task["category"]),
+        metric=str(task.get("metric", RESIDUAL_SPEARMAN)),
+        score=float(np.mean(repeat_scores)),
+        n_samples=n_samples,
+        repeat_scores=repeat_scores,
+    )
+
+
+def score_task(
+    task: dict,
+    labels: pd.DataFrame,
+    emb: pd.DataFrame,
+    targets: PerturbationTargets | None = None,
+) -> TaskScore:
+    """Score one task: repeated fold-wise CV, leave-pair-out, or a transfer split.
+
+    Private biology (disease, tissue, and target names) never leaks in.
+    """
+    metric = task["metric"]
+    if task.get("task_type") == PERTURBATION:
+        if metric not in {CENTERED_SPEARMAN, RESIDUAL_SPEARMAN}:
+            raise EvaluatorError(
+                f"perturbation task {task.get(TASK_ID)} needs metric "
+                f"'{CENTERED_SPEARMAN}'"
+            )
+        if targets is None:
+            raise EvaluatorError("perturbation task is missing targets.npz")
+        return _score_perturbation_task(task, labels, emb, targets)
+    if metric not in METRICS:
+        raise EvaluatorError(f"unknown metric '{metric}' for task {task.get(TASK_ID)}")
+    task_type = task["task_type"]
+    matrix = _align(labels, emb)
+    y = labels[LABEL].to_numpy()
+    y_eval = y
+    classes = np.unique(y) if task_type == "classification" else np.array([])
+    groups = _subject_groups(labels)
+
+    if SPLIT in labels.columns:
+        y_eval, preds = _transfer_predict(
+            task_type,
+            y,
+            labels[SPLIT].to_numpy(),
+            matrix,
+            classes,
+            groups,
+        )
+        try:
+            score = METRICS[metric](y_eval, preds, classes)
+        except ValueError as error:
+            raise SubmissionError(f"transfer task not scoreable: {error}") from error
+        repeat_scores = (score,)
+    elif _uses_leave_pair_out(metric, y, groups):
+        score = _leave_pair_out_score(y, groups, matrix, classes)
+        repeat_scores = (score,)
+    else:
+        repeat_scores = _repeated_cv_scores(
+            task_type=task_type,
+            metric=metric,
+            y=y,
+            labels=labels,
+            matrix=matrix,
+            classes=classes,
+        )
+        score = float(np.mean(repeat_scores))
+
+    return TaskScore(
+        task_id=_norm_id(task[TASK_ID]),
+        dataset_id=_norm_id(task[DATASET_ID]),
+        category=str(task["category"]),
+        metric=metric,
+        score=score,
+        n_samples=int(len(y_eval)),
+        repeat_scores=repeat_scores,
+    )
+
+
+def fetch_manifest(
+    token: str | None = None, revision: str = CURRENT.data
+) -> list[dict]:
+    """Download the public ``datasets.yaml`` registry of opaque dataset ids."""
+    from huggingface_hub import hf_hub_download
+
+    path = hf_hub_download(
+        PUBLIC_REPO,
+        MANIFEST_FILENAME,
+        repo_type="dataset",
+        token=token,
+        revision=revision,
+    )
+    with open(path) as handle:
+        data = yaml.safe_load(handle)
+    if isinstance(data, dict):
+        return data.get("datasets", [])
+    return data or []
+
+
+def public_task_ids_from_manifest(path: str | Path) -> set[str]:
+    """Read the task ids of the published public-task manifest."""
+    with open(path) as handle:
+        return {_norm_id(entry[TASK_ID]) for entry in yaml.safe_load(handle)["tasks"]}
+
+
+def fetch_public_task_ids(
+    token: str | None = None, revision: str = CURRENT.data
+) -> set[str]:
+    """Download the public task ids; none until published or if the fetch fails.
+
+    Losing the Public tags beats blanking every page over a Hub hiccup.
+    """
+    from huggingface_hub import hf_hub_download
+    from huggingface_hub.utils import EntryNotFoundError
+
+    try:
+        path = hf_hub_download(
+            PUBLIC_REPO,
+            PUBLIC_TASKS_MANIFEST,
+            repo_type="dataset",
+            token=token,
+            revision=revision,
+        )
+        return public_task_ids_from_manifest(path)
+    except EntryNotFoundError:
+        return set()
+    except Exception:  # noqa: BLE001
+        logging.warning("public task manifest unreadable; no task tagged public")
+        return set()
+
+
+def manifest_ids(manifest: list[dict], modality: str | None = None) -> set[str]:
+    """Return manifest dataset ids, optionally for one modality."""
+    return {
+        _norm_id(entry["id"])
+        for entry in manifest
+        if modality is None or entry.get("modality") == modality
+    }
+
+
+def scoreable_tasks(tasks: list[dict], valid_ids: set[str]) -> list[dict]:
+    """Registry tasks whose dataset is in the public manifest; orphans are skipped.
+
+    Shared by ``score_all`` and the leaderboard so both agree on what full
+    coverage means. An orphan (a task on a dataset not yet published) is logged
+    and dropped rather than making full coverage unreachable for everyone.
+    """
+    kept, orphans = [], []
+    for task in tasks:
+        if _norm_id(task[DATASET_ID]) in valid_ids:
+            kept.append(task)
+        else:
+            orphans.append(_norm_id(task[TASK_ID]))
+    if orphans:
+        logging.warning("skipping tasks on unpublished datasets: %s", orphans)
+    return kept
+
+
+def fetch_tasks_registry(
+    token: str | None = None, revision: str = CURRENT.labels
+) -> list[dict]:
+    """Download the private ``tasks.yaml`` registry from the labels repo."""
+    from huggingface_hub import hf_hub_download
+
+    path = hf_hub_download(
+        LABELS_REPO, TASKS_FILENAME, repo_type="dataset", token=token, revision=revision
+    )
+    return load_tasks_registry(path)
+
+
+def fetch_task_labels(
+    task_id: str, token: str | None = None, revision: str = CURRENT.labels
+) -> pd.DataFrame:
+    """Download a task's private ``labels.csv`` from the labels repo."""
+    from huggingface_hub import hf_hub_download
+
+    path = hf_hub_download(
+        LABELS_REPO,
+        f"{task_id}/{LABELS_FILENAME}",
+        repo_type="dataset",
+        token=token,
+        revision=revision,
+    )
+    return load_labels(path)
+
+
+def fetch_task_targets(
+    task_id: str, token: str | None = None, revision: str = CURRENT.labels
+) -> PerturbationTargets:
+    """Download a task's private compressed response matrix."""
+    from huggingface_hub import hf_hub_download
+
+    path = hf_hub_download(
+        LABELS_REPO,
+        f"{task_id}/{TARGETS_FILENAME}",
+        repo_type="dataset",
+        token=token,
+        revision=revision,
+    )
+    return load_targets(path)
+
+
+def _retry(fn):
+    """Call ``fn``, retrying transient failures with linear backoff."""
+    last: Exception | None = None
+    for attempt in range(FETCH_ATTEMPTS):
+        try:
+            return fn()
+        except Exception as error:  # noqa: BLE001
+            last = error
+            if attempt < FETCH_ATTEMPTS - 1:
+                time.sleep(FETCH_BACKOFF * (attempt + 1))
+    raise last
+
+
+def score_all(
+    path: str | Path,
+    token: str | None = None,
+    *,
+    modality: str | None = None,
+    representation: str = EMBEDDING,
+    datasets: list[dict] | None = None,
+    tasks: list[dict] | None = None,
+    fetch_labels=None,
+    fetch_targets=None,
+    checkpoint_dir: str | Path | None = None,
+    reference: str | Path | None = None,
+) -> dict:
+    """Score a submission per task and roll it up into a blind result.
+
+    Unknown dataset ids and bad files raise/record a ``SubmissionError``; a
+    failed fetch or internal error raises ``EvaluatorError`` (our side, not the
+    submitter's). A dataset is embedded once and reused across all its tasks.
+
+    ``EMBEDDING`` columns are put on the unit sphere first, ``GENE_SPACE`` ones
+    keep their scale. A ``reference`` file (same layout as a submission, gene
+    space) is then appended to every sample and the concatenated row put back
+    on the unit sphere.
+    """
+    if representation not in REPRESENTATIONS:
+        raise SubmissionError(
+            f"unknown representation '{representation}'; expected one of "
+            f"{list(REPRESENTATIONS)}"
+        )
+    blocks = load_submission(path)
+    if datasets is None:
+        try:
+            datasets = fetch_manifest(token)
+        except Exception as error:  # noqa: BLE001
+            raise EvaluatorError(
+                f"could not load the dataset manifest: {error}"
+            ) from error
+    if modality is not None and modality not in MODALITIES:
+        raise SubmissionError(f"unknown or unavailable modality: {modality}")
+    all_ids = manifest_ids(datasets)
+    valid = manifest_ids(datasets, MODALITIES.get(modality))
+    if modality is not None and not valid:
+        raise SubmissionError(f"unknown or unavailable modality: {modality}")
+
+    unknown = sorted(set(blocks) - all_ids)
+    if unknown:
+        raise SubmissionError(f"unknown dataset_id(s) not in the benchmark: {unknown}")
+    wrong_modality = sorted(set(blocks) - valid)
+    if wrong_modality:
+        raise SubmissionError(
+            f"dataset_id(s) outside the selected modality: {wrong_modality}"
+        )
+
+    if tasks is None:
+        try:
+            tasks = fetch_tasks_registry(token)
+        except Exception as error:  # noqa: BLE001
+            raise EvaluatorError(
+                f"could not load the task registry: {error}"
+            ) from error
+    fetch_labels = fetch_labels or fetch_task_labels
+    fetch_targets = fetch_targets or fetch_task_targets
+    checkpoints = (
+        _TaskCheckpoints(checkpoint_dir, path, modality, representation, reference)
+        if checkpoint_dir is not None
+        else None
+    )
+    reference_by_ds = _load_reference(reference) if reference is not None else None
+
+    emb_by_ds, block_error = {}, {}
+    for dataset_id, block in blocks.items():
+        try:
+            frame = _to_embedding_frame(block)
+            if representation == EMBEDDING:
+                frame = _l2_normalize_rows(frame)
+            if reference_by_ds is not None:
+                if dataset_id not in reference_by_ds:
+                    raise EvaluatorError(
+                        f"reference features lack dataset {dataset_id}"
+                    )
+                frame = _concat_reference(frame, reference_by_ds[dataset_id])
+            emb_by_ds[dataset_id] = frame
+        except SubmissionError as error:
+            block_error[dataset_id] = str(error)
+
+    selected_tasks = [
+        task
+        for task in scoreable_tasks(tasks, all_ids)
+        if _norm_id(task[DATASET_ID]) in valid
+    ]
+    outcomes: list[TaskOutcome | None] = [None] * len(selected_tasks)
+    pending: list[_PendingTask] = []
+    for position, task in enumerate(selected_tasks):
+        task_id = _norm_id(task[TASK_ID])
+        dataset_id = _norm_id(task[DATASET_ID])
+        emb = emb_by_ds.get(dataset_id)
+        error = block_error.get(dataset_id)
+        if emb is None and error is None:
+            outcomes[position] = TaskOutcome(task_id, dataset_id, "missing")
+            continue
+        if error is not None:
+            outcomes[position] = TaskOutcome(
+                task_id, dataset_id, "invalid", reason=error
+            )
+            continue
+        try:
+            labels = _retry(lambda: fetch_labels(task_id, token))
+        except Exception as fetch_error:  # noqa: BLE001
+            raise EvaluatorError(
+                f"could not load evaluation data for a task: {fetch_error}"
+            ) from fetch_error
+        if reference_by_ds is not None:
+            _check_reference_covers(labels, reference_by_ds[dataset_id], task_id)
+        targets = None
+        if task.get("task_type") == PERTURBATION:
+            try:
+                targets = _retry(lambda: fetch_targets(task_id, token))
+            except Exception as fetch_error:  # noqa: BLE001
+                raise EvaluatorError(
+                    f"could not load perturbation targets for a task: {fetch_error}"
+                ) from fetch_error
+        fingerprint = _task_fingerprint(task, labels, targets)
+        restored = (
+            checkpoints.load(task_id, fingerprint) if checkpoints is not None else None
+        )
+        if restored is not None:
+            outcomes[position] = restored
+            continue
+        pending.append(_PendingTask(position, task, emb, labels, targets, fingerprint))
+
+    groups: dict[tuple[str, str], list[_PendingTask]] = defaultdict(list)
+    for item in pending:
+        if item.task.get("task_type") == "regression":
+            key = (_norm_id(item.task[DATASET_ID]), _regression_geometry(item.labels))
+        else:
+            key = ("individual", _norm_id(item.task[TASK_ID]))
+        groups[key].append(item)
+
+    for items in groups.values():
+        scores = None
+        if len(items) > 1 and all(
+            item.task.get("task_type") == "regression" for item in items
+        ):
+            try:
+                scores = _score_regression_group(
+                    [item.task for item in items],
+                    [item.labels for item in items],
+                    items[0].emb,
+                )
+            except SubmissionError:
+                scores = None
+        for index, item in enumerate(items):
+            try:
+                score = (
+                    scores[index]
+                    if scores is not None
+                    else score_task(item.task, item.labels, item.emb, item.targets)
+                )
+                outcome = _outcome_from_score(item.task, score)
+            except SubmissionError as scoring_error:
+                outcome = TaskOutcome(
+                    _norm_id(item.task[TASK_ID]),
+                    _norm_id(item.task[DATASET_ID]),
+                    "invalid",
+                    reason=str(scoring_error),
+                )
+            outcomes[item.position] = outcome
+            if checkpoints is not None:
+                checkpoints.save(outcome, item.fingerprint)
+
+    if any(outcome is None for outcome in outcomes):
+        raise EvaluatorError("internal error: a task produced no outcome")
+    return _summarize([outcome for outcome in outcomes if outcome is not None])
+
+
+def _summarize(outcomes: list[TaskOutcome]) -> dict:
+    """Combine per-task outcomes into blind per-category numbers + coverage."""
+    scored = [o.score for o in outcomes if o.status == "scored"]
+    dataset_status = _dataset_status(outcomes)
+    n_scored, n_total = len(scored), len(outcomes)
+    n_ds_scored = sum(1 for status in dataset_status.values() if status == "scored")
+    return {
+        "per_task": scored,
+        "categories": category_means(scored),
+        "invalid": [
+            {"task_id": o.task_id, "dataset_id": o.dataset_id, "reason": o.reason}
+            for o in outcomes
+            if o.status == "invalid"
+        ],
+        "missing": sorted({o.dataset_id for o in outcomes if o.status == "missing"}),
+        "incomplete": sorted(
+            ds for ds, status in dataset_status.items() if status == "incomplete"
+        ),
+        "coverage": n_scored / n_total if n_total else 0.0,
+        "n_scored": n_scored,
+        "n_total": n_total,
+        "full_coverage": n_total > 0 and n_scored == n_total,
+        "n_datasets_scored": n_ds_scored,
+        "n_datasets_total": len(dataset_status),
+    }
+
+
+def _dataset_status(outcomes: list[TaskOutcome]) -> dict[str, str]:
+    """Blind per-dataset STATUS only (no score): scored / missing / incomplete."""
+    statuses: dict[str, set[str]] = defaultdict(set)
+    for outcome in outcomes:
+        statuses[outcome.dataset_id].add(outcome.status)
+    out = {}
+    for dataset_id in sorted(statuses):
+        seen = statuses[dataset_id]
+        if seen == {"missing"}:
+            out[dataset_id] = "missing"
+        elif seen == {"scored"}:
+            out[dataset_id] = "scored"
+        else:
+            out[dataset_id] = "incomplete"
+    return out
+
+
+def _cli() -> None:
+    parser = argparse.ArgumentParser(description="Score a PRIMO submission locally.")
+    parser.add_argument("--submission", required=True, help="CSV/TSV/Parquet/NPZ file")
+    parser.add_argument("--modality", required=True, choices=MODALITIES)
+    parser.add_argument(
+        "--representation",
+        default=EMBEDDING,
+        choices=REPRESENTATIONS,
+        help="what the columns are: learned embedding dims, or gene-space values",
+    )
+    parser.add_argument("--token", default=None, help="HF token (else env HF_TOKEN)")
+    parser.add_argument(
+        "--checkpoint-dir",
+        default=None,
+        help="resume completed tasks from this directory",
+    )
+    parser.add_argument(
+        "--reference",
+        default=None,
+        help="gene-space features to concatenate to every sample before scoring",
+    )
+    args = parser.parse_args()
+
+    token = args.token or os.environ.get("HF_TOKEN")
+    result = score_all(
+        args.submission,
+        token,
+        modality=args.modality,
+        representation=args.representation,
+        checkpoint_dir=args.checkpoint_dir,
+        reference=args.reference,
+    )
+    print(
+        f"scored     : {result['n_datasets_scored']}/{result['n_datasets_total']} "
+        f"datasets, {result['n_scored']}/{result['n_total']} tasks  "
+        f"(full_coverage={result['full_coverage']})"
+    )
+    for category, stats in sorted(result["categories"].items()):
+        print(
+            f"  {category:20s} {stats['metric']} = {stats['mean']:.4f} "
+            f"(n={stats['n_tasks']})"
+        )
+    for bad in result["invalid"]:
+        print(f"  INVALID [{bad['dataset_id']}]: {bad['reason']}")
+    if result["missing"]:
+        print(f"  missing    : {result['missing']}")
+    if result["incomplete"]:
+        print(f"  incomplete : {result['incomplete']}")
+
+
+if __name__ == "__main__":
+    _cli()

example_submission.csv

@@ -0,0 +1,5 @@
+dataset_id,sample_id,e0,e1,e2
+d002,SAMPLE_A,0.121,-0.443,0.982
+d002,SAMPLE_B,-0.075,0.310,0.044
+d003,SAMPLE_C,0.512,0.028,-0.157
+d003,SAMPLE_D,-0.301,-0.119,0.663

leaderboard.py

@@ -0,0 +1,643 @@
+"""Table building for the PRIMO front-end: persisted results + registry -> frames.
+
+Kept apart from Gradio and from any I/O so it unit-tests without a network
+(``app.py`` fetches and renders, ``boards.py`` decides what a board *is*).
+
+``ranked_table`` lists only models that covered EVERY task the Elo anchor
+scored, so a partial run cannot win by skipping the hard cohorts.
+``per_task_table`` keeps partial submissions and is never a ranking.
+
+Our baselines rank where their score puts them: pinning one to the bottom would
+hide a foundation model losing to an information-rich expression baseline. Task
+metadata is read defensively, so an old registry yields blank cells rather than
+a broken page.
+"""
+
+import json
+import math
+
+import numpy as np
+import pandas as pd
+from boards import (
+    PUBLIC,
+    Board,
+    label,
+    metric_label,
+    modality_label,
+)
+from evaluator import _norm_id
+from results import (
+    INSTITUTION,
+    IS_AUTHOR_SUBMISSION,
+    IS_BASELINE,
+    MODEL_NAME,
+    PAPER_LINK,
+    SUBMISSION_ID,
+    display_name,
+    split_hvg_name,
+    with_author_submission_flag,
+    with_baseline_flag,
+    with_institution,
+    with_paper_link,
+    with_submission_id,
+)
+from scipy.optimize import minimize
+from scipy.special import expit
+from scoring import TaskScore, category_means, sort_key
+
+EMPTY_RANKED_COLUMNS = ["Model"]
+EMPTY_PER_TASK_COLUMNS = ["Task"]
+SCORE_DECIMALS = 3
+ELO_START = 1000.0
+ELO_SCALE = 400 / math.log(10)
+ELO_REGULARIZATION = 0.1
+ELO_ANCHOR_MODEL = "HVG-1200-genes"
+
+
+class ModelCell(str):
+    """String-compatible model label with paper-link and chip metadata.
+
+    ``is_hvg`` marks a ``<model> + HVG`` entry, whose label is the parent name.
+    ``is_baseline`` marks one of our baselines, whose label keeps its
+    ``(baseline)`` tag so it never merges with a model of the same name. The page
+    shows both flags as chips.
+    """
+
+    paper_link: str
+    is_author_submission: bool
+    is_hvg: bool
+    is_baseline: bool
+
+    def __new__(
+        cls,
+        label: str,
+        paper_link: str,
+        is_author_submission: bool,
+        is_hvg: bool = False,
+        is_baseline: bool = False,
+    ) -> "ModelCell":
+        cell = super().__new__(cls, label)
+        cell.paper_link = paper_link
+        cell.is_author_submission = is_author_submission
+        cell.is_hvg = is_hvg
+        cell.is_baseline = is_baseline
+        return cell
+
+
+class TaskCell(str):
+    """String-compatible task title flagged when its labels are public."""
+
+    is_public: bool
+
+    def __new__(cls, title: str, is_public: bool) -> "TaskCell":
+        cell = super().__new__(cls, title)
+        cell.is_public = is_public
+        return cell
+
+
+def _task_cell(task: dict) -> TaskCell:
+    """The task's title, or its id when it has none."""
+    return TaskCell(
+        str(task.get("title") or task.get("task_id", "")), bool(task.get(PUBLIC))
+    )
+
+
+def _round(value: float | None) -> float | None:
+    """Round for display; anything non-finite becomes a blank cell, not ``-inf``."""
+    if value is None or not math.isfinite(value):
+        return None
+    return round(value, SCORE_DECIMALS)
+
+
+def _ordered(df: pd.DataFrame) -> pd.DataFrame:
+    """Normalise the credit columns and add the tiebreak key rows are ordered by.
+
+    ``_submission_key`` falls back to the timestamp for rows written before
+    ``submission_id`` existed, so legacy rows still order deterministically.
+    """
+    flagged = with_submission_id(
+        with_paper_link(
+            with_author_submission_flag(with_institution(with_baseline_flag(df)))
+        )
+    )
+    if flagged.empty:
+        return flagged
+    key = flagged[SUBMISSION_ID].mask(
+        flagged[SUBMISSION_ID] == "", "legacy:" + flagged["submitted_at"].astype(str)
+    )
+    return flagged.assign(
+        _submission_key=key, _task=flagged["task_id"].map(_norm_id)
+    ).sort_values(["submitted_at", "_submission_key"])
+
+
+def latest_only(df: pd.DataFrame) -> pd.DataFrame:
+    """Keeps the most recent result for each ``(name, is_baseline, task)`` slot.
+
+    An entry is the accumulated set of its slots, not one submission: a later
+    submission fills the tasks it covers and leaves the rest standing.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Persisted result rows.
+
+    Returns
+    -------
+    pd.DataFrame
+        One row per slot, credit columns normalised.
+    """
+    ordered = _ordered(df)
+    if ordered.empty:
+        return ordered
+    return (
+        ordered.groupby([MODEL_NAME, IS_BASELINE, "_task"], as_index=False)
+        .tail(1)
+        .drop(columns=["_submission_key", "_task"])
+    )
+
+
+def submission_counts(df: pd.DataFrame) -> dict[tuple[str, bool], int]:
+    """Counts how many times each entry's most-rewritten task was submitted.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Persisted result rows.
+
+    Returns
+    -------
+    dict[tuple[str, bool], int]
+        Count keyed by ``(model_name, is_baseline)``.
+    """
+    flagged = with_baseline_flag(df)
+    if flagged.empty:
+        return {}
+    per_task = (
+        flagged.assign(_task=flagged["task_id"].map(_norm_id))
+        .groupby([MODEL_NAME, IS_BASELINE, "_task"])
+        .size()
+    )
+    return {
+        (str(model), bool(is_baseline)): int(count)
+        for (model, is_baseline), count in per_task.groupby(
+            level=[MODEL_NAME, IS_BASELINE]
+        )
+        .max()
+        .items()
+    }
+
+
+def scores_from_rows(rows: pd.DataFrame, by_id: dict[str, dict]) -> list[TaskScore]:
+    """Rebuilds one submission's task scores from persisted rows and the registry.
+
+    Parameters
+    ----------
+    rows : pd.DataFrame
+        Result rows of a single entry.
+    by_id : dict[str, dict]
+        Task registry keyed by task id.
+
+    Returns
+    -------
+    list[TaskScore]
+        One score per row, joined by ``task_id``. Retired tasks are dropped.
+    """
+    out = []
+    for _, r in rows.iterrows():
+        task_id = _norm_id(r["task_id"])
+        meta = by_id.get(task_id)
+        if meta is None:
+            continue
+        out.append(
+            TaskScore(
+                task_id=task_id,
+                dataset_id=_norm_id(meta["dataset_id"]),
+                category=str(meta["category"]),
+                metric=str(meta["metric"]),
+                score=float(r["score"]),
+                n_samples=0,
+            )
+        )
+    return out
+
+
+def _board_registry(by_id: dict[str, dict], board: Board) -> dict[str, dict]:
+    return {tid: meta for tid, meta in by_id.items() if tid in board.task_ids}
+
+
+def _stored_repeat_scores(row: pd.Series) -> tuple[float, ...]:
+    """Read finite persisted repeat scores, or return an empty tuple."""
+    raw = row.get("repeat_scores")
+    if isinstance(raw, str) and raw:
+        try:
+            parsed = json.loads(raw)
+            if not isinstance(parsed, list) or any(
+                isinstance(value, bool) or not isinstance(value, (int, float))
+                for value in parsed
+            ):
+                return ()
+            values = tuple(float(value) for value in parsed)
+            if values and all(math.isfinite(value) for value in values):
+                return values
+        except (
+            TypeError,
+            ValueError,
+            OverflowError,
+            RecursionError,
+            json.JSONDecodeError,
+        ):
+            pass
+    return ()
+
+
+def _repeat_scores(row: pd.Series) -> tuple[float, ...]:
+    """Read persisted repeat scores, falling back to one legacy task score."""
+    values = _stored_repeat_scores(row)
+    if values:
+        return values
+    return (float(row["score"]),)
+
+
+def _paired_splits(
+    left: tuple[float, ...], right: tuple[float, ...]
+) -> list[tuple[float, ...]]:
+    """Lines two entries up split by split; the shorter record plays its mean.
+
+    Pairwise, never board-wide: aligning on the longest record on the board
+    would flatten two three-split entries the day a six-split one is published.
+    """
+    splits = max(len(left), len(right))
+    return [
+        column if len(column) == splits else (float(np.mean(column)),) * splits
+        for column in (left, right)
+    ]
+
+
+def _is_anchor(model: str, is_baseline: bool) -> bool:
+    """Is this the Elo anchor? Matched on ``(name, is_baseline)``, not the name."""
+    return is_baseline and model == ELO_ANCHOR_MODEL
+
+
+def _credit_row(rows: pd.DataFrame) -> pd.Series:
+    """The most recent slot carrying an institution or a paper link."""
+    credited = rows[(rows[INSTITUTION] != "") | (rows[PAPER_LINK] != "")]
+    return (credited if not credited.empty else rows).iloc[-1]
+
+
+def _entries(df: pd.DataFrame, by_id: dict[str, dict], board: Board) -> list[dict]:
+    """Rank-ready entries for every model covering the board's scored tasks.
+
+    The anchor decides which tasks count. Without it every finitely-scored task
+    counts and the Elo scale falls back to mean-centred, decided per board.
+    """
+    scoped = _board_registry(by_id, board)
+    latest = latest_only(df)
+    if latest.empty:
+        return []
+    on_board = latest[latest["task_id"].map(_norm_id).isin(list(board.task_ids))]
+    anchor_rows = on_board[
+        [
+            _is_anchor(str(model), bool(flag))
+            for model, flag in zip(on_board[MODEL_NAME], on_board[IS_BASELINE])
+        ]
+    ]
+    ranked_rows = on_board if anchor_rows.empty else anchor_rows
+    scored_tasks = {
+        _norm_id(row["task_id"])
+        for _, row in ranked_rows.iterrows()
+        if math.isfinite(float(row["score"]))
+    }
+    if not scored_tasks:
+        return []
+
+    counts = submission_counts(df)
+    entries = []
+    for (model, is_baseline), rows in latest.groupby([MODEL_NAME, IS_BASELINE]):
+        submitted = rows["submitted_at"].max()
+        credits = _credit_row(rows)
+        task_rows = rows[
+            rows["task_id"].map(_norm_id).isin(list(scored_tasks))
+            & rows["score"].map(lambda score: math.isfinite(float(score)))
+        ]
+        if len(task_rows["task_id"].map(_norm_id).unique()) != len(scored_tasks):
+            continue
+        categories = category_means(scores_from_rows(task_rows, scoped))
+        task_scores = {
+            _norm_id(row["task_id"]): float(row["score"])
+            for _, row in task_rows.iterrows()
+        }
+        repeat_scores = {
+            _norm_id(row["task_id"]): _repeat_scores(row)
+            for _, row in task_rows.iterrows()
+        }
+        entries.append(
+            {
+                "model_name": model,
+                "institution": credits[INSTITUTION],
+                "paper_link": credits[PAPER_LINK],
+                "is_author_submission": bool(credits[IS_AUTHOR_SUBMISSION]),
+                "submission_id": credits[SUBMISSION_ID],
+                "submitted_at": submitted,
+                "n_submissions": counts.get((str(model), bool(is_baseline)), 1),
+                "categories": categories,
+                "rank": sort_key(categories),
+                "is_baseline": bool(is_baseline),
+                "task_scores": task_scores,
+                "repeat_scores": repeat_scores,
+            }
+        )
+    if not entries:
+        return entries
+    shared = set.intersection(*(set(entry["task_scores"]) for entry in entries))
+    _comparison_stats(entries, shared)
+    return sorted(entries, key=lambda entry: (-entry["elo"], -entry["rank"]))
+
+
+def _comparison_stats(entries: list[dict], task_ids: set[str]) -> None:
+    """Add Bradley-Terry Elo and mean rank to ``entries`` in place.
+
+    Battles are played split by split, a pair's splits sharing weight one per
+    task. ``ELO_ANCHOR_MODEL`` is pinned during the fit, not shifted after,
+    because the ridge penalty shrinks toward whichever model is pinned. Entries
+    are keyed by position: two of them can share a name.
+    """
+    if not entries:
+        return
+    indices = list(range(len(entries)))
+    ranks: dict[int, list[float]] = {index: [] for index in indices}
+    battles: list[tuple[int, int, float, float]] = []
+    for task_id in sorted(task_ids):
+        scores = [entry["task_scores"][task_id] for entry in entries]
+        ordered = sorted(
+            indices, key=lambda index: (-scores[index], entries[index]["model_name"])
+        )
+        for index in indices:
+            tied_positions = [
+                rank
+                for rank, other in enumerate(ordered, start=1)
+                if scores[other] == scores[index]
+            ]
+            ranks[index].append(sum(tied_positions) / len(tied_positions))
+        for index in indices:
+            for opponent in indices[index + 1 :]:
+                left, right = _paired_splits(
+                    entries[index]["repeat_scores"][task_id],
+                    entries[opponent]["repeat_scores"][task_id],
+                )
+                for ours, theirs in zip(left, right):
+                    outcome = 1.0 if ours > theirs else (0.5 if ours == theirs else 0.0)
+                    battles.append((index, opponent, outcome, 1 / len(left)))
+
+    anchor = next(
+        (
+            index
+            for index, entry in enumerate(entries)
+            if _is_anchor(entry["model_name"], entry["is_baseline"])
+        ),
+        None,
+    )
+    pinned = len(entries) - 1 if anchor is None else anchor
+    battle_table = np.array(battles, dtype=float).reshape(-1, 4)
+    lefts, rights = battle_table[:, 0].astype(int), battle_table[:, 1].astype(int)
+    weights = battle_table[:, 3]
+    weighted_outcomes = weights * battle_table[:, 2]
+
+    def objective(theta_free: np.ndarray) -> tuple[float, np.ndarray]:
+        theta = np.insert(theta_free, pinned, 0.0)
+        delta = theta[lefts] - theta[rights]
+        loss = np.sum(weights * np.logaddexp(0.0, delta) - weighted_outcomes * delta)
+        error = weights * expit(delta) - weighted_outcomes
+        gradient = np.bincount(lefts, error, len(entries)) - np.bincount(
+            rights, error, len(entries)
+        )
+        loss += ELO_REGULARIZATION * float(np.dot(theta, theta)) / 2
+        gradient += ELO_REGULARIZATION * theta
+        return float(loss), np.delete(gradient, pinned)
+
+    if battles and len(entries) > 1:
+        fit = minimize(
+            objective,
+            np.zeros(len(entries) - 1),
+            jac=True,
+            method="L-BFGS-B",
+        )
+        theta = np.insert(fit.x, pinned, 0.0) if fit.success else np.zeros(len(entries))
+        if anchor is None:
+            theta -= theta.mean()
+        ratings = ELO_START + ELO_SCALE * theta
+    else:
+        ratings = np.full(len(entries), ELO_START)
+    for index, entry in enumerate(entries):
+        entry["elo"] = float(ratings[index])
+        entry["mean_rank"] = (
+            float(np.mean(ranks[index])) if ranks[index] else float("nan")
+        )
+
+
+def ranked_table(
+    df: pd.DataFrame, by_id: dict[str, dict], board: Board
+) -> pd.DataFrame:
+    """Ranks the models that covered every task of ``board`` the anchor scored.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Persisted result rows.
+    by_id : dict[str, dict]
+        Task registry keyed by task id.
+    board : Board
+        Board to rank.
+
+    Returns
+    -------
+    pd.DataFrame
+        One row per ranked model, one column per task category in its native
+        metric. Empty when no model has full coverage.
+    """
+    entries = _entries(df, by_id, board)
+    if not entries:
+        return pd.DataFrame(columns=EMPTY_RANKED_COLUMNS)
+
+    columns = sorted({cat for e in entries for cat in e["categories"]})
+    metric_of: dict[str, str] = {}
+    for entry in entries:
+        for cat, stats in entry["categories"].items():
+            metric_of.setdefault(cat, stats["metric"])
+
+    rows = []
+    for position, entry in enumerate(entries, start=1):
+        categories = entry["categories"]
+        name, is_hvg = split_hvg_name(str(entry["model_name"]))
+        model = ModelCell(
+            display_name(name, entry["is_baseline"]),
+            entry["paper_link"],
+            entry["is_author_submission"],
+            is_hvg,
+            entry["is_baseline"],
+        )
+        row = {
+            "Rank": position,
+            "Model": model,
+            "Institution": entry["institution"] or None,
+            "Elo": round(entry["elo"]),
+            "Mean rank": _round(entry["mean_rank"]),
+            # Blank for baselines and ``+ HVG`` entries: we republish and re-sync
+            # those, so their count measures our release cadence, not anyone tuning.
+            "Submissions count": (
+                None if entry["is_baseline"] or is_hvg else entry["n_submissions"]
+            ),
+        }
+        for cat in columns:
+            header = f"{label(cat)} ({metric_label(metric_of[cat])})"
+            row[header] = _round(categories[cat]["mean"]) if cat in categories else None
+        rows.append(row)
+    table = pd.DataFrame(rows)
+    table["Submissions count"] = table["Submissions count"].astype("Int64")
+    return table
+
+
+RESERVED_COLUMNS = frozenset({"Task", "Family", "Area", "Modality", "Metric", "Best"})
+
+
+def per_task_table(
+    df: pd.DataFrame, by_id: dict[str, dict], board: Board
+) -> pd.DataFrame:
+    """Builds the per-task table: one row per task, one column per model.
+
+    Partial submissions are kept, unlike in ``ranked_table``. Model names become
+    column names, hence ``RESERVED_COLUMNS``: a model called ``Task`` would
+    overwrite every task title.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Persisted result rows.
+    by_id : dict[str, dict]
+        Task registry keyed by task id.
+    board : Board
+        Board whose tasks the table is restricted to.
+
+    Returns
+    -------
+    pd.DataFrame
+        Task rows and model columns ordered by mean over the board, plus a
+        ``Best`` column naming the leading model.
+    """
+    scoped = _board_registry(by_id, board)
+    if df.empty or not scoped:
+        return pd.DataFrame(columns=EMPTY_PER_TASK_COLUMNS)
+
+    scores: dict[tuple[str, str], float] = {}
+    repeat_sd: dict[tuple[str, str], tuple[float, int]] = {}
+    for _, r in latest_only(df).iterrows():
+        task_id = _norm_id(r["task_id"])
+        if task_id in scoped:
+            model = display_name(str(r[MODEL_NAME]), bool(r[IS_BASELINE]))
+            scores[(task_id, model)] = float(r["score"])
+            repeats = _stored_repeat_scores(r)
+            if len(repeats) > 1:
+                repeat_sd[(task_id, model)] = (float(np.std(repeats)), len(repeats))
+    if not scores:
+        return pd.DataFrame(columns=EMPTY_PER_TASK_COLUMNS)
+
+    by_model: dict[str, list[float]] = {}
+    for (_, model), score in scores.items():
+        by_model.setdefault(model, []).append(score)
+    models = sorted(by_model, key=lambda m: -sum(by_model[m]) / len(by_model[m]))
+
+    rows = []
+    displayed_sd: dict[tuple[int, str], tuple[float, int]] = {}
+    families = {str(t.get("category", "")) for t in scoped.values()}
+    areas = {str(t.get("therapeutic_area", "")) for t in scoped.values()}
+    for task_id, task in sorted(scoped.items()):
+        row = {"Task": _task_cell(task)}
+        if len(families) > 1:
+            row["Family"] = label(str(task.get("category", "")))
+        if len(areas) > 1:
+            row["Area"] = str(task.get("therapeutic_area", ""))
+        row["Metric"] = metric_label(str(task.get("metric", "")))
+        present = {m: scores[(task_id, m)] for m in models if (task_id, m) in scores}
+        for model in models:
+            row[model] = _round(present.get(model))
+            if (task_id, model) in repeat_sd:
+                displayed_sd[(len(rows), model)] = repeat_sd[(task_id, model)]
+        row["Best"] = max(present, key=present.get) if present else None
+        rows.append(row)
+    table = pd.DataFrame(rows)
+    table.attrs["repeat_standard_deviations"] = displayed_sd
+    return table
+
+
+TASK_COLUMNS = [
+    "Task",
+    "Predicts",
+    "Family",
+    "Area",
+    "Modality",
+    "Disease",
+    "Tissue",
+    "Patients",
+    "Metric",
+]
+
+
+def tasks_table(tasks: list[dict]) -> pd.DataFrame:
+    """Builds the Tasks page table. Provenance is never a column.
+
+    Parameters
+    ----------
+    tasks : list[dict]
+        Registry tasks.
+
+    Returns
+    -------
+    pd.DataFrame
+        One row per task, sorted by task id, with ``TASK_COLUMNS`` as columns.
+    """
+    if not tasks:
+        return pd.DataFrame(columns=TASK_COLUMNS)
+    rows = []
+    for task in sorted(tasks, key=lambda t: str(t.get("task_id", ""))):
+        rows.append(
+            {
+                "Task": _task_cell(task),
+                "Predicts": str(task.get("description") or ""),
+                "Family": label(str(task.get("category", ""))),
+                "Area": str(task.get("therapeutic_area", "")),
+                "Modality": modality_label(str(task.get("modality", ""))),
+                "Disease": ", ".join(str(d) for d in task.get("diseases") or []),
+                "Tissue": str(task.get("tissue", "")),
+                "Patients": task.get("n_subjects") or task.get("n_samples"),
+                "Metric": metric_label(str(task.get("metric", ""))),
+            }
+        )
+    return pd.DataFrame(rows, columns=TASK_COLUMNS)
+
+
+REPOSITORY_OF_PREFIX = {"GSE": "NCBI GEO", "E-MTAB": "EMBL-EBI ArrayExpress"}
+
+
+def source_repositories(tasks: list[dict]) -> list[str]:
+    """Lists the public archives the cohorts come from, never the accessions.
+
+    An accession like ``GSE000000`` would let anyone download the study and
+    recover the labels. The registry's ``license`` field stays out too: one
+    unvalidated line per dataset, and some cohorts pool three studies under it.
+
+    Parameters
+    ----------
+    tasks : list[dict]
+        Registry tasks, each optionally carrying a ``sources`` list.
+
+    Returns
+    -------
+    list[str]
+        Archive names, sorted.
+    """
+    repositories: set[str] = set()
+    for task in tasks:
+        for source in task.get("sources") or []:
+            for prefix, repository in REPOSITORY_OF_PREFIX.items():
+                if str(source).upper().startswith(prefix):
+                    repositories.add(repository)
+    return sorted(repositories)

pages/about.md

@@ -0,0 +1,123 @@
+## What PRIMO measures
+
+**Can a foundation model turn a patient's omics data into an embedding that
+predicts meaningful outcomes?**
+
+You embed each patient. We fit a fixed probe on top and check whether that
+embedding predicts a real clinical outcome. You never see the labels, so you
+cannot tune to them, and when a score comes out high the credit belongs to the
+*embedding*.
+
+Plenty of benchmarks already score reconstruction. Far fewer ask whether the
+representation is any use in the clinic, and that is the gap PRIMO tries to fill.
+
+## How a submission is scored
+
+1. **You send embeddings, never predictions**: one vector per baseline sample.
+2. **We fit the probe**: ridge for scalar regression, logistic for
+   classification, or multi-output ridge regression for perturbation
+   responses. Learned embedding rows are scaled to unit length first, since an
+   embedding dimension has no unit; gene-space baselines keep their log-normalized row
+   scale. Feature standardisation is fit on each outer training fold, and probe
+   hyperparameters are selected with subject-grouped inner cross-validation.
+3. **Scores always hold out whole subjects.** Most tasks use subject-grouped
+   cross-validation: we average the fold-level metric over frozen partitions,
+   three folds ten times over.
+   Binary tasks with fewer than 30 subjects use leave-pair-out: each
+   positive-negative pair of subjects is held out in turn, the probe is fit on
+   everyone else, and the AUROC is the share of held-out sample pairs ranked
+   correctly. These tasks have one score, so no ±.
+   Transfer tasks use a fixed split instead: train on one source cohort, test
+   on the target cohort. Perturbation tasks decode hidden post-minus-pre
+   expression responses.
+4. **Each task family keeps its own metric.** AUROC, Pearson r and centered
+   Spearman never share a category column.
+
+The probe is identical for everyone, which is what makes the numbers comparable:
+what changes between two rows is the representation behind them. The rows marked
+`(baseline)` are our own submissions. In particular, `HVG-1200-genes` is the
+**HVG-1200 log-normalized linear baseline**: bulk samples use log2(CPM+1), while
+single-cell profiles use per-cell log2(CP10K+1) followed by sample-level mean
+pooling. We retain the 1,200 genes with highest dataset-wide variance, apply
+train-fold standardisation, and fit the same tuned linear probe. Gene selection
+never reads a label, but it is fit over every sample of a dataset. This is an
+information-rich transductive reference, not a naïve raw-count baseline or an
+expected lower bound for a foundation model.
+
+Every submission also gets a second row, **`<model> + HVG`**: the same
+embedding concatenated with the `HVG-1200-genes` features of each sample. The
+embedding is scaled to unit length, the 1,200 log-normalized genes are appended,
+and the concatenated row is scaled to unit length again before the same probe.
+It shows whether a model adds information that expression alone does not carry.
+These rows are shown by default; set **+ HVG models** to **Hide** to hide them,
+which re-ranks the board and refits Elo without them.
+
+Elo orders the rows. Each task family keeps its own column, in its own metric,
+and no column averages across metrics.
+
+**Elo** is pinned to our HVG-1200 log-normalized linear baseline, which sits at
+exactly 1000. It turns every paired repeat into a win, draw, or loss and
+discards the score margin, so a tiny win counts like a large one. A difference
+of only a few Elo points is effectively a tie, not evidence that one
+representation is meaningfully superior. Use mean rank, the family columns, and
+per-task scores to interpret close rows. +400 Elo is a 10-to-1 expected win
+rate. The scale does not move when a new model is submitted, so ratings stay
+comparable over time, but only within one board, since each board is fitted on
+its own tasks.
+
+**Subm.** (submissions count) is the most times any *single* task result of
+that model was resubmitted, not how many files were uploaded. A model that
+covered twenty tasks across twenty submissions reads 1, because each task was
+submitted once; a model that sent the same task five times reads 5. It shows
+n/a for our baselines and the `+ HVG` rows, which we republish ourselves. A
+published result can be corrected, so a 2 or 3 is ordinary; a high number on
+one task is worth a second look.
+
+## How the results are organised
+
+A **board** is a self-contained leaderboard over a slice of the benchmark: the
+whole modality, one therapeutic area, one task family, or an area and a family
+together. Pick it with the pills of the **Leaderboard** page.
+
+A board ranks only the models that covered **all of its tasks**. Skipping
+Infectious diseases therefore costs you nothing on the Oncology board.
+
+**Boards never cross modalities.** An AUROC on bulk RNA and an AUROC on
+single-cell are not measuring the same thing, so we keep them apart.
+
+## What stays hidden
+
+The evaluation only stays honest while the labels stay ours, which prevents tuning
+the model directly on the labels. We still publish the omics data, to compute
+embeddings.
+
+The exception is the tasks tagged **Public**: their labels are downloadable from
+the [PRIMO dataset](https://huggingface.co/datasets/PRIMOmics/primo), so a model
+may have been trained on them.
+
+| Disclosure | What it covers |
+|---|---|
+| **Per task** | disease, tissue, therapeutic area, what is predicted, class names, patient count, metric |
+| **In aggregate** | the public archives the cohorts sit in |
+| **Public tasks** | labels, evaluation folds, post-treatment responses, and the `dataset_id` each is scored on, which can make its source study findable |
+| **Never** | study accessions and, for every other task, which cohort is behind which `dataset_id`, labels, pairing identifiers and post-treatment responses |
+
+Every cohort comes from a published study deposited in {repositories}. We name
+the archive but never the accession, as publishing the study id behind a
+`dataset_id` would make the dataset easy to reconstitute.
+
+## Cite PRIMO
+
+Cite this website and the board version that you used. The **Cite** button, at
+the top of every page, gives the BibTeX entry.
+
+Want to add a cohort, propose a task on the cohorts already here, open a new
+modality or therapeutic area, or work with us on the methodology? The
+**Contribute** tab explains how.
+
+## Links
+
+- 🌐 **Website**: [primomics.org](http://primomics.org/)
+- 📦 **Data**: [PRIMOmics/primo](https://huggingface.co/datasets/PRIMOmics/primo)
+- 📄 **Paper**: [OpenReview](https://openreview.net/forum?id=v2SA8gHwqo)
+- 💬 **Questions**: [karim.elkanbi@scientalab.com](mailto:karim.elkanbi@scientalab.com)

pages/contribute.md

@@ -0,0 +1,56 @@
+PRIMO is an open benchmark, and it is **deliberately incomplete**. The
+**Leaderboard** page shows how far it reaches today, and its last panel names
+a few of the gaps.
+
+PRIMO was started by **Scienta** and **Hugging Face**. The intent is community governance; how
+that actually works is part of what the first partners will define.
+
+## Add a cohort
+
+PRIMO has no shortage of models. What is hard to find is **an omics cohort with
+patient-level clinical labels**, whether that is drug response, a severity score
+or a molecular subtype. If you hold one, or know a group that does, tell us:
+
+- **modality** and roughly how many patients
+- **what is labelled**, and how many patients carry that label
+- **disease and tissue**
+- **licence**, and whether the data can be redistributed
+
+[Propose a cohort](mailto:karim.elkanbi@scientalab.com?subject=PRIMO%20cohort%20proposal&body=Modality%20and%20rough%20patient%20count%3A%0A%0AWhat%20is%20labelled%2C%20and%20how%20many%20patients%20carry%20that%20label%3A%0A%0ADisease%20and%20tissue%3A%0A%0ALicence%2C%20and%20whether%20the%20data%20can%20be%20redistributed%3A%0A)
+
+There is no formal acceptance process yet. We are writing it with the first
+partners, and we would rather admit that than invent rules nobody has agreed to.
+What you will get today is a real answer and a technical conversation.
+
+## Add a task, without bringing any data
+
+This one costs you nothing but an idea. Ask **a better question of the cohorts
+already here**: a label we are not predicting, a transfer split nobody has tried,
+or a metric that would say more than the one we use. Methodology counts here as
+much as data does.
+
+[Propose a task](mailto:karim.elkanbi@scientalab.com?subject=PRIMO%20task%20proposal&body=Task%20I%20would%20add%3A%0A%0AWhich%20cohorts%20already%20in%20PRIMO%20it%20uses%3A%0A%0AWhat%20is%20predicted%2C%20and%20with%20which%20metric%3A%0A%0AWhy%20it%20says%20something%20the%20current%20tasks%20do%20not%3A%0A)
+
+## Add a modality or a therapeutic area
+
+The last panel of the **Leaderboard** page names a few omics layers and clinical
+areas PRIMO does not reach yet. Any other one is welcome too. Read them as gaps
+waiting for someone rather than as a roadmap we are already working through. Opening one takes a single cohort with clinical
+labels, and not a whole atlas.
+
+[Propose a modality or an area](mailto:karim.elkanbi@scientalab.com?subject=PRIMO%20modality%20or%20area%20proposal&body=Modality%20or%20area%20I%20would%20add%3A%0A%0AWhat%20I%20can%20bring%20%28cohort%2C%20labels%2C%20licence%29%3A%0A)
+
+## Become a founding partner
+
+Founding partners shape PRIMO rather than just appear on it: a voice on the
+methodology, co-signature on what we publish, and early access to the results.
+
+[Talk to us about partnership](mailto:karim.elkanbi@scientalab.com?subject=PRIMO%20founding%20partner&body=Organisation%3A%0A%0AWhat%20we%20would%20bring%20to%20PRIMO%3A%0A%0AWhat%20we%20would%20want%20from%20it%3A%0A)
+· [primomics.org](http://primomics.org/)
+
+## Smaller ways in
+
+- **Question the method.** Open a thread in the Space's **Community** tab.
+- **Submit a model.** Baselines are on the leaderboard already; beat them.
+- **Read the paper**: [OpenReview](https://openreview.net/forum?id=v2SA8gHwqo)
+- **Look at the data**: [PRIMOmics/primo](https://huggingface.co/datasets/PRIMOmics/primo)

pages/submit.md

@@ -0,0 +1,60 @@
+### The fastest way in
+
+Two files, both in this [Space's repo](https://huggingface.co/spaces/PRIMOmics/primo-eval/blob/main/quickstart.py):
+
+- 📥 [`quickstart.py`](https://huggingface.co/spaces/PRIMOmics/primo-eval/blob/main/quickstart.py):
+  downloads the selected modality, embeds it, and writes a valid submission.
+  Swap its `embed` function for your model and you are done.
+- 📄 [`example_submission.csv`](https://huggingface.co/spaces/PRIMOmics/primo-eval/blob/main/example_submission.csv):
+  four lines, fake numbers, the exact shape we expect.
+
+```bash
+pip install anndata scikit-learn pandas pyarrow pyyaml huggingface_hub
+python quickstart.py --modality bulk-rna --out submission.parquet
+# or: --modality single-cell-rna
+```
+
+### Or by hand, in three steps
+
+1. **Choose one modality** → use the selector in the form. The quickstart
+   downloads only its datasets from [PRIMOmics/primo](https://huggingface.co/datasets/PRIMOmics/primo).
+2. **Embed that modality** → build **one** file: `dataset_id`, `sample_id`, then one column per embedding dim (`e0`, `e1`, …). CSV / TSV / Parquet, or NPZ.
+3. **Sign in, fill the form, and hit Evaluate.** Add an institution for group submissions, check **Submitted by the model's authors** when applicable, and provide a paper link to make the model name clickable. A fixed task probe scores each hidden task (AUROC, Pearson or centered Spearman), reported per task category in its native metric.
+
+### Example file
+
+```
+dataset_id,sample_id,e0,e1,e2
+d002,S1,0.12,-0.44,0.98
+d003,S1,0.31,0.02,-0.15
+```
+
+For bulk datasets, each H5AD row is one submission sample. For single-cell
+datasets, H5AD rows are cells and `obs["sample_id"]` maps them to opaque
+collection samples. Aggregate the cells however your model requires and submit
+exactly one embedding per unique `sample_id`; the submission schema is unchanged.
+
+### Good to know
+
+Files containing dataset IDs from another modality are rejected. **Partial
+submissions are welcome, and they add up.** Cover fewer datasets and you are still
+scored: you get ranked on every **board** whose scored tasks you covered in
+full, and your numbers still show up in each board's **per-task** table, so
+nothing you send is thrown away.
+
+Results are keyed by **model name and task**. Submit under a name you already
+used and it fills in the tasks it covers, leaving the rest of that model's
+results standing — so you can build coverage up one submission at a time, and the
+same name can hold results for both modalities at once. Submitting a task you
+have already covered replaces that one result, which is how a bad run gets fixed.
+A name belongs to whichever HF user submitted it first; nobody else can write under it.
+
+**Each submission yields two entries.** We also score your embedding
+concatenated with our `HVG-1200-genes` features (your embedding is put on the
+unit sphere, then the concatenated row) and rank it as `<your model> + HVG`,
+under your name and credits. Scoring therefore takes about twice as long. Names containing `+ HVG` are reserved.
+
+**Your first target is the baselines.** We run our own reference submissions on
+log-normalized expression, whole or cut down to its most variable genes, and they
+sit on the boards labelled `(baseline)`. `HVG-1200-genes` is the HVG-1200
+log-normalized linear baseline, not a raw-count baseline.

pages/tasks.md

@@ -0,0 +1,3 @@
+Every scoreable task. Each row is a hidden clinical target or perturbation
+response, scored by the same fixed task probe. The cohorts stay anonymous, but the
+biology is on the table.

primo.css

@@ -0,0 +1,396 @@
+/* PRIMO benchmark platform - Gradio stylesheet.
+   Load with: gr.Blocks(css_paths=["primo.css"])
+   Layout, tokens and type adapted from the STRABLE leaderboard,
+   https://github.com/gblayer/strable-leaderboard
+   Copyright (c) 2026 The STRABLE developers. BSD 3-Clause License:
+   its full text, conditions and disclaimer are in LICENSE-STRABLE. */
+
+/* ---------- tokens: PRIMO marine and coral ---------- */
+:root {
+  --pm-f-display: "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --pm-f-body: "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --pm-f-mono: "IBM Plex Mono", ui-monospace, Menlo, Consolas, monospace;
+  --pm-r-card: 16px;
+  --pm-bg: #EEF0F7; --pm-surface: #F8F9FC; --pm-surface-2: #E2E6F3;
+  --pm-ink: #0D1B62; --pm-ink-2: #2E3A73; --pm-ink-3: #565F8C; --pm-line: #CDD3EA;
+  --pm-head: #0D1B62; --pm-accent: #162DA3; --pm-accent-ink: #FFFFFF; --pm-btn-edge: #162DA3;
+  --pm-accent-2: #3F53B5; --pm-accent-text: #B5532F;
+  --pm-mark: #FD7E56; --pm-mark-muted: #A5ACCB;
+  --pm-panel: #0D1B62; --pm-panel-line: #3F53B5; --pm-panel-ink: #FFFFFF; --pm-panel-ink-2: #BCC3EA;
+  color-scheme: light;
+}
+.dark {
+  --pm-bg: #0A1030; --pm-surface: #111A45; --pm-surface-2: #1A2559;
+  --pm-ink: #E6E9F7; --pm-ink-2: #C2C8E4; --pm-ink-3: #959DC4; --pm-line: #28336B;
+  --pm-head: #C9D0FF; --pm-accent: #3F53B5; --pm-accent-ink: #FFFFFF; --pm-btn-edge: #3F53B5;
+  --pm-accent-2: #9AA8FF; --pm-accent-text: #FD9878;
+  --pm-mark: #FD7E56; --pm-mark-muted: #5A6394;
+  --pm-panel: #162DA3; --pm-panel-line: #3F53B5; --pm-panel-ink: #FFFFFF; --pm-panel-ink-2: #C9D0FF;
+  color-scheme: dark;
+}
+
+/* ---------- Gradio reset: its chrome takes the page tokens ---------- */
+html, body, gradio-app { background: var(--pm-bg) !important; }
+.gradio-container {
+  max-width: 100% !important; padding: 0 !important; background: var(--pm-bg) !important;
+  font-family: var(--pm-f-body) !important; color: var(--pm-ink);
+  -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility;
+  --body-background-fill: var(--pm-bg);
+  --background-fill-primary: var(--pm-surface);
+  --background-fill-secondary: var(--pm-bg);
+  --block-background-fill: var(--pm-surface);
+  --block-border-color: var(--pm-line);
+  --border-color-primary: var(--pm-line);
+  --input-background-fill: var(--pm-bg);
+  --input-border-color: var(--pm-line);
+  --body-text-color: var(--pm-ink);
+  --body-text-color-subdued: var(--pm-ink-3);
+  --block-label-text-color: var(--pm-ink-2);
+  --block-title-text-color: var(--pm-ink-2);
+  --block-info-text-color: var(--pm-ink-3);
+  --link-text-color: var(--pm-ink);
+  --link-text-color-hover: var(--pm-accent-text);
+  --color-accent: var(--pm-accent);
+  --color-accent-soft: var(--pm-surface-2);
+  --checkbox-background-color-selected: var(--pm-accent);
+  --button-primary-background-fill: var(--pm-accent);
+  --button-primary-text-color: var(--pm-accent-ink);
+}
+footer { display: none !important; }
+#pm-pages > .tab-nav, #pm-pages > .tab-wrapper { display: none !important; }
+#pm-pages, #pm-pages > .tabitem { border: 0 !important; padding: 0 !important; background: transparent !important; }
+#pm-pages > .tabitem > .column { gap: 0 !important; }
+#pm-site { max-width: 1440px; margin: 0 auto !important; padding: 0 clamp(16px, 4vw, 40px) 56px !important; gap: 0 !important; }
+#pm-site .html-container, #pm-site .html-container > .prose { padding: 0 !important; }
+#pm-site .prose { font-family: var(--pm-f-body); font-size: 17px; line-height: 1.55; color: var(--pm-ink); }
+#pm-site a { color: inherit; }
+#pm-site :focus-visible { outline: 2px solid var(--pm-accent-2); outline-offset: 2px; }
+#pm-site code { font-family: var(--pm-f-mono); font-size: .92em; background: none; padding: 0; color: var(--pm-ink-2); }
+
+.pm-label { font: 600 12px/1.6 var(--pm-f-body); letter-spacing: .16em; text-transform: uppercase; }
+#pm-site .pm-title { font-family: var(--pm-f-display); font-weight: 700; font-size: 28px; letter-spacing: -.02em; line-height: 1.15; margin: 0; color: var(--pm-ink); text-wrap: balance; }
+
+/* ---------- top bar ---------- */
+.pm-nav { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding-block: 20px; }
+#pm-site .pm-logo { display: flex; align-items: center; gap: 10px; text-decoration: none; color: var(--pm-head); border-radius: 6px; }
+#pm-site .pm-logo img { width: 34px; height: 34px; display: block; margin: 0; }
+.pm-logo b { font: 800 22px/1 var(--pm-f-display); letter-spacing: -.03em; }
+.pm-nav-right { display: flex; flex-wrap: wrap; justify-content: flex-end; align-items: center; gap: 10px 24px; }
+.pm-nav-links { display: flex; gap: 24px; font-size: 16.5px; }
+#pm-site .pm-nav-links a { color: var(--pm-ink-2); text-decoration: none; }
+#pm-site .pm-nav-links a:hover, #pm-site .pm-nav-links a.pm-active { color: var(--pm-ink); text-decoration: underline; text-underline-offset: 4px; }
+@media (max-width: 760px) { .pm-nav-links { display: none; } }
+
+#pm-site .pm-btn {
+  appearance: none; cursor: pointer; text-decoration: none; display: inline-flex; align-items: center; gap: 10px;
+  background: var(--pm-accent); color: var(--pm-accent-ink); border: 2px solid var(--pm-btn-edge); border-radius: 999px;
+  font: 600 14.5px/1.3 var(--pm-f-body); letter-spacing: .01em; padding: 10px 18px; min-height: 44px; white-space: nowrap;
+  transition: transform 120ms ease, filter 120ms ease;
+}
+#pm-site .pm-btn:hover { transform: translateY(-1px); filter: brightness(1.12); }
+#pm-site .pm-btn:active { transform: translateY(1px); }
+#pm-site .pm-btn--outline { background: transparent; color: var(--pm-head); }
+@media (prefers-reduced-motion: reduce) { #pm-site .pm-btn { transition: none; } #pm-site .pm-btn:hover, #pm-site .pm-btn:active { transform: none; } }
+
+/* ---------- hero ---------- */
+.pm-hero { display: grid; grid-template-columns: minmax(0, 1.08fr) minmax(0, .92fr); gap: 28px 44px; align-items: center; padding-block: 14px 8px; }
+#pm-site .pm-eyebrow { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; margin: 0; color: var(--pm-accent-2); }
+.pm-updated { font: 500 13px/1 var(--pm-f-mono); color: var(--pm-ink-3); }
+.pm-ver { font: 600 12.5px/1 var(--pm-f-mono); color: var(--pm-accent-ink); background: var(--pm-accent); padding: 6px 9px; border-radius: 999px; }
+.pm-ver--closed { color: var(--pm-accent-text); background: transparent; box-shadow: inset 0 0 0 1.5px var(--pm-mark); }
+#pm-site .pm-notice { margin: 0 0 8px; padding: 12px 16px; border: 1px solid var(--pm-line); border-left: 3px solid var(--pm-mark); border-radius: 12px; background: var(--pm-surface); font-size: 15px; color: var(--pm-ink-2); }
+#pm-site .pm-notice b { color: var(--pm-ink); }
+#pm-site .pm-notice a { color: var(--pm-ink); text-decoration: underline; text-underline-offset: 3px; }
+#pm-site .pm-ver-link { font-size: 14px; color: var(--pm-ink-2); text-decoration: underline; text-underline-offset: 3px; }
+#pm-site .pm-ver-link:hover { color: var(--pm-ink); }
+#pm-site .pm-hero h1 {
+  font-family: var(--pm-f-display); font-weight: 800; font-size: clamp(58px, 8.6vw, 112px); line-height: .92;
+  letter-spacing: -.03em; margin: 14px 0 10px; color: var(--pm-head);
+}
+#pm-site .pm-expand { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 14px; margin: 0 0 22px; font-size: 20px; color: var(--pm-ink-3); }
+.pm-expand .pm-xp { font-weight: 500; letter-spacing: .01em; color: var(--pm-ink-2); }
+.pm-expand b { color: var(--pm-head); font-weight: 800; }
+#pm-site .pm-lede { font-size: 19.5px; line-height: 1.55; color: var(--pm-ink-2); max-width: 34em; margin: 0 0 22px; }
+#pm-site .pm-lede a { color: var(--pm-ink); text-decoration: underline; text-underline-offset: 3px; }
+#pm-site .pm-stats { display: flex; flex-wrap: wrap; gap: 8px; margin: 0; padding: 0; list-style: none; }
+#pm-site .pm-stats li { margin: 0; font: 500 14px/1 var(--pm-f-mono); color: var(--pm-ink-2); border: 1px solid var(--pm-line); background: var(--pm-surface); padding: 8px 12px; border-radius: 999px; }
+#pm-site .pm-stats li::marker { content: none; }
+.pm-stats b { color: var(--pm-ink); font-weight: 600; }
+.pm-art-wrap { justify-self: end; width: 100%; max-width: 520px; }
+.pm-art { padding: 14px; border: 1px solid var(--pm-line); border-radius: 14px; background: var(--pm-surface); }
+.pm-hero-art { display: block; width: 100%; height: auto; }
+.pm-hero-art text { font-family: var(--pm-f-body); }
+.pm-art-h { fill: var(--pm-ink); font-size: 11.5px; font-weight: 600; }
+.pm-art-c { fill: var(--pm-ink-3); font-size: 9.5px; font-weight: 500; }
+.pm-art-t { fill: var(--pm-ink); font-size: 10.5px; font-weight: 500; }
+.pm-art-patient { fill: var(--pm-mark); }
+.pm-art-a { fill: var(--pm-accent-2); }
+.pm-art-b { fill: var(--pm-accent); }
+.pm-art-box { fill: var(--pm-surface-2); stroke: var(--pm-accent-2); stroke-width: 1.2; }
+.pm-art-edge { stroke: var(--pm-accent-2); stroke-width: .6; opacity: .45; }
+.pm-art-node { fill: var(--pm-accent-2); }
+.pm-art-line { fill: none; stroke: var(--pm-ink-3); stroke-width: 1.2; }
+.pm-art-head { fill: var(--pm-ink-3); }
+.pm-art-pill { fill: var(--pm-surface-2); stroke: var(--pm-line); stroke-width: 1; }
+@media (max-width: 1000px) { .pm-hero { grid-template-columns: 1fr; } .pm-art-wrap { justify-self: start; max-width: 520px; } }
+
+/* ---------- view pills: Gradio radios drawn as segmented pills ---------- */
+#pm-site .pm-board-sub { margin: 40px 0 14px; padding-top: 22px; border-top: 1px solid var(--pm-line); font-size: 14.5px; color: var(--pm-ink-3); }
+#pm-controls { display: block !important; margin: 0 0 20px; }
+#pm-controls > .form {
+  display: flex !important; flex-wrap: wrap !important; align-items: center; gap: 12px 22px !important;
+  width: 100% !important; background: transparent !important; border: 0 !important; box-shadow: none !important; overflow: visible !important;
+}
+#pm-controls fieldset.pm-seg { flex: 0 0 auto !important; width: auto !important; min-width: 0 !important; }
+#pm-controls fieldset.pm-seg--main { order: 1; flex: 1 1 100% !important; }
+#pm-controls fieldset.pm-seg--line { order: 2; flex: 1 1 100% !important; }
+#pm-controls fieldset.pm-seg--minor { order: 3; }
+#pm-controls .pm-seg:not(.pm-seg--minor) [data-testid="block-info"] { flex: none; width: 168px; }
+#pm-site fieldset.pm-seg {
+  display: flex !important; align-items: center; flex-wrap: wrap; gap: 8px; margin: 0 !important;
+  padding: 0 !important; border: 0 !important; background: transparent !important; box-shadow: none !important; overflow: visible !important;
+}
+#pm-site .pm-seg [data-testid="block-info"] {
+  margin: 0 !important; padding: 0 !important; font: 600 12px/1.2 var(--pm-f-body) !important;
+  letter-spacing: .14em; text-transform: uppercase; color: var(--pm-ink-3) !important; background: none !important; border: 0 !important;
+}
+#pm-site .pm-seg .wrap:has(> label) {
+  display: inline-flex !important; flex-wrap: wrap; gap: 3px !important; padding: 3px !important;
+  border: 1px solid var(--pm-line); border-radius: 999px; background: var(--pm-bg);
+}
+#pm-site .pm-seg label {
+  position: relative; display: inline-flex !important; align-items: center; gap: 8px; margin: 0 !important;
+  padding: 8px 12px !important; min-height: 34px; border: 0 !important; border-radius: 999px !important;
+  background: transparent !important; box-shadow: none !important; cursor: pointer; white-space: nowrap;
+  font: 500 13.5px/1 var(--pm-f-mono) !important; color: var(--pm-ink-2) !important;
+}
+#pm-site .pm-seg label:hover { color: var(--pm-ink) !important; background: var(--pm-surface-2) !important; }
+#pm-site .pm-seg label.selected, #pm-site .pm-seg label:has(input:checked) { background: var(--pm-ink) !important; color: var(--pm-bg) !important; }
+#pm-site .pm-seg input[type="radio"] { position: absolute; opacity: 0; width: 1px; height: 1px; margin: 0; pointer-events: none; }
+#pm-site .pm-seg label > span { margin: 0 !important; color: inherit !important; font: inherit !important; }
+#pm-site .pm-seg--main label { font-size: 16px !important; font-weight: 600 !important; padding: 12px 20px !important; min-height: 46px; }
+#pm-site .pm-seg--main [data-testid="block-info"] { color: var(--pm-ink) !important; }
+#pm-site .pm-seg--minor label { font-size: 12.5px !important; padding: 6px 10px !important; min-height: 28px; }
+#pm-site .pm-seg--minor [data-testid="block-info"] { font-style: italic !important; }
+
+/* ---------- tables ---------- */
+.pm-card { background: var(--pm-surface); border: 1px solid var(--pm-line); border-radius: var(--pm-r-card); min-width: 0; }
+.pm-tbl-wrap { overflow: auto; border-radius: 0 0 var(--pm-r-card) var(--pm-r-card); }
+.pm-card-head {
+  display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 6px 18px;
+  padding: 14px 14px 12px; border-bottom: 1px solid var(--pm-line); border-radius: var(--pm-r-card) var(--pm-r-card) 0 0; background: var(--pm-bg);
+}
+.pm-view { font: 700 12.5px/1.3 var(--pm-f-body); letter-spacing: .14em; text-transform: uppercase; color: var(--pm-ink-2); }
+.pm-view-n { font: 500 13.5px/1.3 var(--pm-f-mono); color: var(--pm-ink-3); }
+.pm-view-n b { font-weight: 700; color: var(--pm-ink); }
+.pm-view-n b:first-child { color: var(--pm-accent-text); font-size: 15px; }
+.pm-table-wrap { width: 100%; overflow-x: auto; border: 1px solid var(--pm-line); border-radius: var(--pm-r-card); background: var(--pm-surface); }
+#pm-site table.pm-table {
+  width: 100%; margin: 0; border: 0; border-collapse: collapse; table-layout: auto;
+  font-family: var(--pm-f-body); font-size: 14.5px; font-variant-numeric: tabular-nums; background: transparent;
+}
+#pm-site .pm-table td.pm-num, #pm-site .pm-table td.pm-metric, #pm-site .pm-ranked td.pm-name { font-family: var(--pm-f-mono); font-size: 14px; }
+#pm-site .pm-table th {
+  padding: 16px 8px 11px; border: 0; border-bottom: 1px solid var(--pm-line); background: var(--pm-surface);
+  font: 700 11.5px/1.2 var(--pm-f-body); letter-spacing: .1em; text-transform: uppercase; color: var(--pm-ink-2);
+  text-align: left; vertical-align: bottom; white-space: nowrap;
+}
+#pm-site .pm-table th small { display: block; margin-top: 3px; font: 500 12px/1.2 var(--pm-f-body); letter-spacing: .02em; text-transform: none; color: var(--pm-ink-3); }
+#pm-site .pm-table td { padding: 11px 8px; border: 0; border-bottom: 1px solid var(--pm-line); vertical-align: middle; color: var(--pm-ink-2); background: transparent; }
+#pm-site .pm-table tr { border: 0; background: transparent; }
+#pm-site .pm-table tbody tr:last-child td { border-bottom: 0; }
+#pm-site .pm-table tbody tr:hover td { background: var(--pm-surface-2); }
+#pm-site .pm-table th.pm-sort { cursor: pointer; user-select: none; }
+#pm-site .pm-table th.pm-sort:hover { color: var(--pm-ink); }
+#pm-site .pm-table th.pm-sort[data-sort-direction="asc"]::after { content: " ↑"; color: var(--pm-mark); }
+#pm-site .pm-table th.pm-sort[data-sort-direction="desc"]::after { content: " ↓"; color: var(--pm-mark); }
+#pm-site .pm-table .pm-r, #pm-site .pm-table td.pm-num { text-align: right; }
+#pm-site .pm-table td.pm-num { color: var(--pm-ink-2); }
+#pm-site .pm-table td.pm-key { color: var(--pm-ink); font-weight: 600; }
+#pm-site .pm-table td.pm-best, #pm-site .pm-table td[style*="font-weight:700"] { color: var(--pm-ink); font-weight: 700; }
+#pm-site .pm-table .pm-dim, #pm-site .pm-table .pm-num--dim { color: var(--pm-mark-muted); }
+#pm-site .pm-table td.pm-strong { font-family: var(--pm-f-body); color: var(--pm-ink); }
+#pm-site .pm-table td.pm-name { font-weight: 600; color: var(--pm-ink); }
+#pm-site .pm-table td.pm-metric { font-size: 12px; color: var(--pm-ink-3); }
+
+/* the ranking: one line per model, the top three framed as on STRABLE */
+#pm-site .pm-ranked td { white-space: nowrap; }
+#pm-site .pm-ranked th { white-space: normal; }
+#pm-site .pm-ranked th small { white-space: nowrap; }
+#pm-site .pm-ranked th:first-child, #pm-site .pm-ranked td:first-child { padding-left: 14px; }
+#pm-site .pm-ranked th:last-child, #pm-site .pm-ranked td:last-child { padding-right: 14px; }
+#pm-site .pm-ranked tr.pm-top td:first-child { border-left: 2px solid var(--pm-mark); }
+#pm-site .pm-ranked tr.pm-top td:last-child { border-right: 2px solid var(--pm-mark); }
+#pm-site .pm-ranked tr.pm-top-first td { border-top: 2px solid var(--pm-mark); }
+#pm-site .pm-ranked tr.pm-top-last td { border-bottom: 2px solid var(--pm-mark); }
+#pm-site .pm-ranked[data-sorted="true"] tr.pm-top td { border-left: 0; border-right: 0; border-top: 0; border-bottom: 1px solid var(--pm-line); }
+#pm-site .pm-ranked .pm-rank { width: 1%; font: 700 14px/1 var(--pm-f-body); letter-spacing: .03em; color: var(--pm-ink-3); }
+#pm-site .pm-ranked .pm-inst { font-family: var(--pm-f-body); font-size: 14.5px; max-width: 9.5em; overflow: hidden; text-overflow: ellipsis; }
+.pm-pipe { display: flex; align-items: center; gap: 6px; min-width: 0; }
+.pm-lrn { color: var(--pm-ink); font-weight: 600; white-space: nowrap; }
+#pm-site .pm-model-link { color: var(--pm-ink); text-decoration: underline; text-decoration-color: var(--pm-line); text-underline-offset: 4px; }
+#pm-site .pm-model-link:hover { text-decoration-color: var(--pm-ink); }
+.pm-leader { flex: 1 1 12px; min-width: 12px; align-self: center; border-bottom: 2px dotted var(--pm-line); transform: translateY(3px); }
+.pm-tag { flex: none; font: 600 9.5px/1 var(--pm-f-mono); letter-spacing: .08em; text-transform: uppercase; color: var(--pm-ink-3); border: 1px solid var(--pm-line); padding: 3px 4px; border-radius: 999px; white-space: nowrap; }
+.pm-tag--hvg { color: var(--pm-accent-2); border-color: var(--pm-accent-2); }
+.pm-tag--author { color: var(--pm-accent-text); border-color: var(--pm-accent-text); }
+.pm-tag--base { color: var(--pm-ink-2); border-style: dashed; border-color: var(--pm-ink-3); }
+#pm-site .pm-note { margin: 12px 0 0; font-size: 13px; color: var(--pm-ink-3); max-width: 64em; }
+#pm-site .pm-empty { margin: 0; padding: 22px 18px; font-size: 15px; color: var(--pm-ink-2); }
+
+/* the window of the Cite button, in the top bar */
+#pm-cite-dialog { width: min(640px, calc(100vw - 32px)); }
+#pm-cite-dialog b { color: var(--pm-ink); }
+#pm-cite-dialog pre { margin: 14px 0 0; overflow-x: auto; font: 12.5px/1.55 var(--pm-f-mono); white-space: pre; }
+
+/* the per-task scores, folded under the ranking */
+#pm-site .pm-more { margin-top: 36px; }
+#pm-site .pm-more > summary { display: flex; align-items: baseline; gap: 14px; cursor: pointer; list-style: none; }
+#pm-site .pm-more > summary::-webkit-details-marker { display: none; }
+#pm-site .pm-more > summary::before { content: "+"; width: 1em; font: 600 24px/1 var(--pm-f-mono); color: var(--pm-mark); }
+#pm-site .pm-more[open] > summary::before { content: "−"; }
+.pm-more-n { font: 500 13.5px/1 var(--pm-f-mono); color: var(--pm-ink-3); }
+#pm-site .pm-more > .pm-note { margin: 8px 0 14px; }
+#pm-site .pm-more .pm-table td { white-space: nowrap; padding: 9px 10px; font-size: 13.5px; }
+#pm-site .pm-more .pm-table th { padding: 14px 10px 10px; font-size: 11.5px; }
+#pm-site .pm-more .pm-table th:first-child, #pm-site .pm-more .pm-table td:first-child { position: sticky; left: 0; z-index: 1; background: var(--pm-surface); }
+#pm-site .pm-more .pm-table tbody tr:hover td:first-child { background: var(--pm-surface-2); }
+#pm-site .pm-more .pm-task-text { display: inline-block; max-width: 30em; overflow: hidden; text-overflow: ellipsis; vertical-align: bottom; }
+#pm-site .pm-table .pm-sd { display: inline; margin-left: 4px; font-size: 11px; color: var(--pm-ink-3); }
+
+/* tooltips */
+.pm-score-guide, .pm-task-guide { position: relative; display: inline-block; cursor: help; }
+.pm-score-guide::after, .pm-task-guide::after {
+  content: attr(data-tooltip); position: absolute; z-index: 10; bottom: calc(100% + 7px); width: max-content;
+  max-width: min(300px, 70vw); padding: 8px 12px; border-radius: 10px; background: var(--pm-ink); color: var(--pm-bg);
+  font: 400 13px/1.45 var(--pm-f-body); text-align: left; white-space: normal; letter-spacing: 0; text-transform: none;
+  opacity: 0; pointer-events: none; transform: translateY(3px); transition: opacity .12s ease, transform .12s ease;
+}
+.pm-score-guide::after { right: 0; }
+.pm-task-guide::after { left: 0; width: min(360px, 72vw); }
+.pm-score-guide:hover::after, .pm-score-guide:focus::after, .pm-task-guide:hover::after, .pm-task-guide:focus::after { opacity: 1; transform: translateY(0); }
+.pm-table tbody tr:first-child .pm-task-guide::after, .pm-table tbody tr:first-child .pm-score-guide::after { top: calc(100% + 7px); bottom: auto; }
+.pm-public-chip { display: inline-flex; margin-left: 6px; font: 600 10px/1 var(--pm-f-mono); letter-spacing: .1em; text-transform: uppercase; color: var(--pm-accent-2); border: 1px solid var(--pm-accent-2); padding: 3px 5px; border-radius: 999px; white-space: nowrap; vertical-align: 1px; }
+
+/* ---------- version history ---------- */
+.pm-history { margin-top: 44px; display: grid; gap: 14px; }
+#pm-site .pm-history-sub { margin: 6px 0 0; color: var(--pm-ink-3); font-size: 14.5px; }
+.pm-history-sub span { font-family: var(--pm-f-mono); color: var(--pm-ink-2); }
+#pm-site .pm-history-sub a { color: var(--pm-ink-2); text-decoration: underline; text-underline-offset: 3px; }
+#pm-site .pm-history ol { list-style: none; margin: 0; padding: 0; display: grid; border: 1px solid var(--pm-line); border-radius: var(--pm-r-card); background: var(--pm-surface); }
+#pm-site .pm-history li { display: grid; grid-template-columns: 84px minmax(0, 1fr) auto; align-items: baseline; gap: 12px; margin: 0; padding: 13px 16px; border-bottom: 1px solid var(--pm-line); font-size: 16px; color: var(--pm-ink-2); }
+#pm-site .pm-history li.pm-on { box-shadow: inset 3px 0 0 var(--pm-mark); }
+#pm-site .pm-history li p { margin: 0; }
+#pm-site .pm-history .pm-ver-meta { margin: 0 0 4px; font: 500 13px/1.5 var(--pm-f-mono); color: var(--pm-ink-3); }
+#pm-site .pm-history li > a { font-size: 14.5px; color: var(--pm-ink); text-decoration: underline; text-underline-offset: 3px; white-space: nowrap; }
+.pm-chip { display: inline-flex; margin-right: 4px; padding: 2px 7px; border-radius: 999px; font: 600 10.5px/1.4 var(--pm-f-mono); letter-spacing: .08em; text-transform: uppercase; }
+.pm-chip--current { color: var(--pm-accent-ink); background: var(--pm-accent); }
+.pm-chip--closed { color: var(--pm-ink-2); box-shadow: inset 0 0 0 1px var(--pm-ink-3); }
+#pm-site .pm-history li::marker { content: none; }
+#pm-site .pm-history li:last-child { border-bottom: 0; }
+.pm-history li b { font: 600 14px/1.7 var(--pm-f-mono); color: var(--pm-ink); }
+
+/* ---------- closing panel and credit ---------- */
+.pm-ask { margin-top: 44px; display: grid; grid-template-columns: minmax(0, .9fr) minmax(0, 1.1fr); gap: 16px 44px; padding: 22px 28px; border-radius: var(--pm-r-card); background: var(--pm-panel); color: var(--pm-panel-ink); border: 1px solid var(--pm-panel-line); }
+@media (max-width: 860px) { .pm-ask { grid-template-columns: 1fr; padding: 24px 18px; } }
+#pm-site .pm-ask .pm-label { color: var(--pm-panel-ink-2); margin: 0; }
+#pm-site .pm-ask h2 { font-family: var(--pm-f-display); font-weight: 700; font-size: clamp(24px, 2.6vw, 32px); letter-spacing: -.02em; line-height: 1.1; margin: 10px 0 0; color: var(--pm-panel-ink); text-wrap: balance; }
+.pm-ask-go { display: grid; gap: 14px; align-content: center; justify-items: start; min-width: 0; }
+#pm-site .pm-ask-go p { margin: 0; color: var(--pm-panel-ink-2); max-width: 34em; }
+#pm-site .pm-ask .pm-btn { background: var(--pm-panel-ink); color: var(--pm-panel); border-color: var(--pm-panel-ink); }
+
+#pm-site .pm-credit { margin: 32px 0 0; text-align: center; font-size: 13.5px; color: var(--pm-ink-3); }
+#pm-site .pm-credit a { color: var(--pm-ink-2); text-decoration: underline; text-underline-offset: 3px; }
+
+/* ---------- other pages: Tasks, Submit, Contribute, Method ---------- */
+.pm-head { display: flex; align-items: flex-end; justify-content: space-between; gap: 24px; padding: 18px 0 22px; border-bottom: 1px solid var(--pm-line); }
+#pm-site .pm-head h1 { margin: 0; font-family: var(--pm-f-display); font-weight: 800; font-size: clamp(40px, 5vw, 64px); line-height: .95; letter-spacing: -.03em; color: var(--pm-head); }
+#pm-site .pm-head p { margin: 12px 0 0; font-size: 17px; color: var(--pm-ink-2); max-width: 46em; }
+#pm-site .pm-body { padding: 24px 0 0 !important; }
+.pm-prose { max-width: 860px; }
+#pm-site .pm-prose :where(h1, h2, h3) { font-family: var(--pm-f-display); font-weight: 700; letter-spacing: -.02em; color: var(--pm-ink); }
+#pm-site .pm-prose a { color: var(--pm-ink); text-decoration: underline; text-underline-offset: 3px; }
+#pm-site .pm-caption { margin: 14px 0 0; font-size: 14px; color: var(--pm-ink-3); }
+.pm-over { margin: 0; font: 600 12px/1.4 var(--pm-f-body); letter-spacing: .14em; text-transform: uppercase; color: var(--pm-ink-3); }
+.pm-badge { display: inline-flex; align-items: center; padding: 3px 6px; border: 1px solid var(--pm-line); border-radius: 999px; font: 500 12px/1 var(--pm-f-mono); white-space: nowrap; }
+
+/* submit page: the steps on the left, the form on the right */
+#pm-submit { display: grid !important; grid-template-columns: minmax(0, 1fr) minmax(340px, 460px); gap: 28px 56px !important; align-items: start; }
+#pm-submit > .column { width: auto !important; min-width: 0 !important; }
+@media (max-width: 1000px) { #pm-submit { grid-template-columns: minmax(0, 1fr); } }
+#pm-site .pm-submit-text { max-width: 68ch; }
+#pm-site .pm-prose .prose { font-size: 16.5px; line-height: 1.6; color: var(--pm-ink-2); }
+#pm-site .pm-prose .prose strong { color: var(--pm-ink); }
+#pm-site .pm-prose .prose h3 { margin: 34px 0 10px; font: 700 22px/1.2 var(--pm-f-display); letter-spacing: -.01em; color: var(--pm-ink); }
+#pm-site .pm-prose .prose > h3:first-child { margin-top: 4px; }
+#pm-site .pm-prose .prose p { margin: 0 0 14px; }
+#pm-site .pm-submit-text ul { display: grid; gap: 8px; margin: 10px 0 16px; padding: 0; list-style: none; }
+#pm-site .pm-submit-text ul > li { margin: 0; padding: 0; }
+#pm-site .pm-submit-text ul > li::marker { content: none; }
+#pm-site .pm-prose ol { margin: 10px 0 16px; padding-left: 1.4em; }
+#pm-site .pm-prose ol > li { margin: 0 0 10px; padding-left: 4px; }
+#pm-site .prose :not(pre) > code { padding: 1px 6px; border: 0; border-radius: 6px; background: var(--pm-surface-2); box-shadow: none; color: var(--pm-ink); font-size: .86em; }
+#pm-site .prose .code_wrap, #pm-site .prose pre { background: var(--pm-surface) !important; }
+#pm-site .prose pre { margin: 12px 0 18px; padding: 14px 16px !important; border: 1px solid var(--pm-line); border-radius: 12px; }
+#pm-site .prose pre code { padding: 0; background: transparent; color: var(--pm-ink-2); font-size: 13px; line-height: 1.6; }
+#pm-site .prose hr { margin: 28px 0; border: 0; border-top: 1px solid var(--pm-line); }
+
+#pm-form { display: flex; flex-direction: column; gap: 2px !important; padding: 22px !important; background: var(--pm-surface); border: 1px solid var(--pm-line); border-radius: var(--pm-r-card); }
+#pm-form .form { background: transparent !important; border: 0 !important; box-shadow: none !important; gap: 4px !important; }
+#pm-form .block { padding: 10px 0 !important; border: 0 !important; background: transparent !important; box-shadow: none !important; }
+#pm-form [data-testid="block-info"], #pm-site #pm-form .pm-seg--form [data-testid="block-info"] {
+  display: block; margin: 0 0 2px !important; font: 600 15px/1.35 var(--pm-f-body) !important;
+  letter-spacing: 0 !important; text-transform: none !important; color: var(--pm-ink) !important;
+}
+#pm-form [data-testid="block-info"] + div .prose, #pm-form [data-testid="block-info"] + div .prose p {
+  margin: 0 0 8px !important; font-size: 13.5px !important; line-height: 1.4 !important; color: var(--pm-ink-3) !important;
+}
+#pm-site #pm-form fieldset.pm-seg--form { display: block !important; }
+#pm-site #pm-form .pm-hint .prose p { margin: 0; font-size: 13.5px; color: var(--pm-ink-3); }
+#pm-site #pm-form .pm-hint .prose pre { margin: 0; }
+#pm-form input[type="text"], #pm-form textarea {
+  border: 1px solid var(--pm-line) !important; border-radius: 10px !important; background: var(--pm-bg) !important;
+  box-shadow: none !important; font-family: var(--pm-f-body) !important; font-size: 15px !important; color: var(--pm-ink) !important;
+  scrollbar-width: none;
+}
+#pm-form textarea::-webkit-scrollbar { display: none; }
+#pm-form input[type="text"]:focus, #pm-form textarea:focus { outline: 2px solid var(--pm-accent-2); outline-offset: 0; }
+#pm-form input[type="checkbox"] { accent-color: var(--pm-accent); }
+#pm-site #pm-form button.huggingface {
+  width: 100%; justify-content: center; min-height: 46px; margin-bottom: 6px; border: 1px solid var(--pm-line) !important;
+  border-radius: 999px !important; background: var(--pm-bg) !important; box-shadow: none !important;
+  font: 600 15px/1.3 var(--pm-f-body) !important; color: var(--pm-ink) !important;
+}
+#pm-site #pm-form button.huggingface:hover { background: var(--pm-surface-2) !important; }
+#pm-form .block:has(input[type="file"]) { margin-top: 6px; padding: 14px !important; border: 2px dashed var(--pm-line) !important; border-radius: 14px !important; background: var(--pm-bg) !important; }
+#pm-form [data-testid="block-label"] {
+  position: static !important; display: inline-flex; align-items: center; gap: 6px; margin: 0 0 6px !important; padding: 0 !important;
+  border: 0 !important; background: none !important; box-shadow: none !important;
+  font: 600 15px/1.35 var(--pm-f-body) !important; color: var(--pm-ink) !important;
+}
+#pm-form .block:has(input[type="file"]) button:has(input[type="file"]) { height: 120px !important; min-height: 0 !important; color: var(--pm-ink-3); }
+#pm-form label:has(input[type="checkbox"]) > span { font: 600 15px/1.35 var(--pm-f-body) !important; color: var(--pm-ink) !important; }
+#pm-form label:has(input[type="checkbox"]) + div .prose, #pm-form label:has(input[type="checkbox"]) + div .prose p {
+  margin: 2px 0 0 !important; font-size: 13.5px !important; line-height: 1.4 !important; color: var(--pm-ink-3) !important;
+}
+#pm-site #pm-evaluate { width: 100%; justify-content: center; min-height: 46px; margin-top: 10px; border-radius: 999px !important; border: 2px solid var(--pm-btn-edge) !important; background: var(--pm-accent) !important; color: var(--pm-accent-ink) !important; font: 600 15px/1.3 var(--pm-f-body) !important; }
+#pm-site #pm-evaluate:hover { filter: brightness(1.12); }
+
+/* the windows: evaluation confirmation and Cite */
+.pm-dialog { width: min(440px, calc(100vw - 32px)); padding: 0; border: 1px solid var(--pm-line); border-radius: var(--pm-r-card); background: var(--pm-surface); color: var(--pm-ink); box-shadow: 0 24px 64px rgb(19 39 63 / .24); }
+#pm-site .pm-dialog { margin: auto !important; }
+.pm-dialog::backdrop { background: rgb(19 39 63 / .45); }
+.pm-dialog-surface { padding: 24px; }
+.pm-dialog h2 { margin: 8px 0 0; font: 700 1.35rem/1.2 var(--pm-f-display); letter-spacing: -.02em; color: var(--pm-ink); }
+.pm-dialog-surface > p:not(.pm-over) { margin: 12px 0 0; font-size: 15px; line-height: 1.6; color: var(--pm-ink-2); }
+.pm-dialog-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 24px; }
+.pm-dialog .pm-btn { appearance: none; cursor: pointer; border-radius: 999px; padding: 9px 16px; font: 600 14px/1.2 var(--pm-f-body); border: 2px solid var(--pm-btn-edge); }
+.pm-dialog .pm-btn--primary { background: var(--pm-accent); color: var(--pm-accent-ink); }
+.pm-dialog .pm-btn--outline { background: transparent; color: var(--pm-head); }
+.pm-evaluation-status { display: flex; align-items: center; gap: 10px; font-size: 14px; line-height: 1.45; color: var(--pm-ink-2); }
+.pm-spinner { width: 18px; height: 18px; flex: none; animation: pm-spin .8s linear infinite; }
+.pm-spinner circle, .pm-spinner path { fill: none; stroke-width: 3; }
+.pm-spinner circle { stroke: var(--pm-line); }
+.pm-spinner path { stroke: var(--pm-mark); stroke-linecap: round; }
+@keyframes pm-spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) { .pm-spinner { animation-duration: 1.6s; } }

quickstart.py

@@ -0,0 +1,164 @@
+"""Produce a valid PRIMO submission in one command, then swap in your own model.
+
+Downloads one modality's public datasets, at the data commit that the
+leaderboard scores, and writes the file the Submit tab expects. The embedding
+here is deliberately dumb: bulk data uses log2(CPM+1); single-cell data uses
+per-cell log2(CP10K+1), mean pooling by collection sample, then PCA. Replace
+``embed`` with your encoder and nothing else changes.
+
+    pip install anndata scikit-learn pandas pyarrow pyyaml huggingface_hub
+    python quickstart.py --modality bulk-rna --out submission.parquet
+
+Standalone on purpose: no import from this Space, so it keeps working if you
+copy the file into your own project. For the same reason, ``DATA_REVISION``
+repeats the data commit of ``versions.yaml``.
+"""
+
+import argparse
+from pathlib import Path
+
+import anndata as ad
+import numpy as np
+import pandas as pd
+import yaml
+from huggingface_hub import hf_hub_download, snapshot_download
+from sklearn.decomposition import PCA
+
+PUBLIC_REPO = "PRIMOmics/primo"
+DATA_REVISION = "0f452b2fc84e544fb1a1fc5bd42017482e07b43c"
+MANIFEST_FILENAME = "datasets.yaml"
+MODALITIES = {"bulk-rna": "bulk RNA", "single-cell-rna": "Single Cell RNA"}
+
+DATASET_ID = "dataset_id"
+SAMPLE_ID = "sample_id"
+
+TARGET_SUM = 1_000_000
+SINGLE_CELL_TARGET_SUM = 10_000
+N_COMPONENTS = 50
+RANDOM_STATE = 0
+
+
+def prediction_ids(adata: ad.AnnData, cells: bool) -> np.ndarray:
+    """Opaque collection-sample ids required in the submission."""
+    if cells:
+        return pd.unique(adata.obs[SAMPLE_ID].astype(str)).astype(str)
+    return adata.obs_names.astype(str).to_numpy()
+
+
+def _log_normalize(x, target_sum: int) -> np.ndarray:
+    """Return dense log2 counts-per-target expression."""
+    x = x.toarray() if hasattr(x, "toarray") else np.asarray(x)
+    totals = x.sum(axis=1, keepdims=True)
+    return np.log2(x / np.where(totals == 0, 1, totals) * target_sum + 1)
+
+
+def _sample_expression(adata: ad.AnnData, cells: bool) -> tuple[np.ndarray, np.ndarray]:
+    """Normalize expression and mean-pool cells into collection samples."""
+    ids = prediction_ids(adata, cells)
+    if not cells:
+        return ids, _log_normalize(adata.X, TARGET_SUM)
+    samples = adata.obs[SAMPLE_ID].astype(str).to_numpy()
+    pooled = [
+        _log_normalize(adata.X[samples == sample_id], SINGLE_CELL_TARGET_SUM).mean(0)
+        for sample_id in ids
+    ]
+    return ids, np.asarray(pooled)
+
+
+def embed(adata: ad.AnnData, cells: bool) -> np.ndarray:
+    """One dataset's expression -> one vector per collection sample. Replace me.
+
+    ``cells`` is true when the rows of ``adata`` are cells, which
+    ``obs["sample_id"]`` maps to collection samples.
+
+    ``X`` holds raw counts unless ``adata.uns["input_normalization"]`` names another
+    scale (FPKM, microarray intensities or author-normalised counts). The
+    log2(CPM + 1) below accepts any non-negative scale.
+
+    Whatever you return, the contract is one finite row per id returned by
+    ``prediction_ids``. The embedding width may differ between datasets.
+    """
+    _, x = _sample_expression(adata, cells)
+    k = min(N_COMPONENTS, x.shape[0] - 1, x.shape[1])
+    return PCA(n_components=k, random_state=RANDOM_STATE).fit_transform(x)
+
+
+def download(modality: str, token: str | None) -> Path:
+    """Download the manifest and expression files for one modality."""
+    manifest = Path(
+        hf_hub_download(
+            PUBLIC_REPO,
+            MANIFEST_FILENAME,
+            repo_type="dataset",
+            token=token,
+            revision=DATA_REVISION,
+        )
+    )
+    paths = [
+        MANIFEST_FILENAME,
+        *[str(entry["path"]) for entry in datasets(manifest, modality)],
+    ]
+    return Path(
+        snapshot_download(
+            PUBLIC_REPO,
+            repo_type="dataset",
+            token=token,
+            revision=DATA_REVISION,
+            allow_patterns=paths,
+        )
+    )
+
+
+def datasets(manifest_path: Path, modality: str) -> list[dict]:
+    """Manifest entries for one modality."""
+    manifest = yaml.safe_load(manifest_path.read_text())
+    entries = manifest.get("datasets", []) if isinstance(manifest, dict) else manifest
+    return [entry for entry in entries if entry["modality"] == modality]
+
+
+def build(root: Path, modality: str) -> pd.DataFrame:
+    """Embed one modality into the frame the Submit tab expects.
+
+    Datasets of different widths stack into one table; the extra columns of a
+    narrower dataset stay empty and the evaluator drops them per dataset, so each
+    dataset keeps its own embedding size.
+    """
+    blocks = []
+    for entry in datasets(root / MANIFEST_FILENAME, modality):
+        dataset_id = str(entry["id"])
+        adata = ad.read_h5ad(root / entry["path"])
+        cells = entry.get("observation_level") == "cell"
+        sample_ids = prediction_ids(adata, cells)
+        vectors = embed(adata, cells)
+        print(
+            f"{dataset_id}: {adata.n_obs} observations, {len(sample_ids)} samples, "
+            f"{entry.get('input_normalization', 'raw counts')} "
+            f"-> {vectors.shape[1]} dims"
+        )
+        block = pd.DataFrame(
+            vectors, columns=[f"e{i}" for i in range(vectors.shape[1])]
+        )
+        block.insert(0, SAMPLE_ID, sample_ids)
+        block.insert(0, DATASET_ID, dataset_id)
+        blocks.append(block)
+    return pd.concat(blocks, ignore_index=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--modality", required=True, choices=MODALITIES)
+    parser.add_argument("--out", type=Path, default=Path("submission.parquet"))
+    parser.add_argument("--token", default=None, help="HF token, if you need one.")
+    args = parser.parse_args()
+
+    modality = MODALITIES[args.modality]
+    submission = build(download(modality, args.token), modality)
+    if args.out.suffix == ".csv":
+        submission.to_csv(args.out, index=False)
+    else:
+        submission.to_parquet(args.out, index=False)
+    print(f"\nWrote {args.out}: {len(submission)} rows. Upload it on the Submit tab.")
+
+
+if __name__ == "__main__":
+    main()

render.py

@@ -0,0 +1,873 @@
+"""The PRIMO pages, rendered as ``pm-*`` markup for ``gr.HTML`` blocks.
+
+Gradio has no card or rich-table component, so every page here is a string of
+HTML styled entirely by ``primo.css`` -- the top bar, the hero, the leaderboard
+tables, the release notes and the tasks table. The functions are pure: they take
+the data the app already fetched (``Board`` objects, the results ``DataFrame``,
+the registry) and return a string, so they unit-test without Gradio or a network.
+
+Two rules hold everywhere:
+
+* Every string that comes from the registry or from a submission goes through
+  ``html.escape`` -- board names, blurbs, disease names and, above all, the
+  user-chosen model names that become table cells and column headers.
+* New submissions can carry a public institution, author-submission check and paper
+  link. Private legacy ``hf_username`` values stay hidden. Public strings and
+  links are validated and escaped before rendering.
+
+Pages are reload-based ``<a href="?tab=name">`` links in the top bar; the
+leaderboard view is picked with Gradio pills in ``app.py``. On a closed board
+version, every link adds ``&version=<number>`` so the visitor stays on it, except
+Submit: a submission always goes to the current version.
+"""
+
+import math
+import numbers
+import re
+from html import escape
+from itertools import pairwise
+from urllib.parse import urlparse
+
+import pandas as pd
+from boards import (
+    AREA_GROUP,
+    CATEGORY_GROUP,
+    MODALITY_GROUP,
+    Board,
+    in_group,
+    open_in_group,
+)
+from leaderboard import (
+    ELO_ANCHOR_MODEL,
+    ModelCell,
+    TaskCell,
+    per_task_table,
+    ranked_table,
+    tasks_table,
+)
+from results import (
+    BASELINE_TAG,
+    IS_BASELINE,
+    MODEL_NAME,
+    split_hvg_name,
+    with_baseline_flag,
+    without_hvg,
+)
+from versions import CURRENT, VERSIONS, Version
+
+SECTIONS = (MODALITY_GROUP, AREA_GROUP, CATEGORY_GROUP)
+VERSION_PARAM = "version"
+NAME_COLUMNS = frozenset({"Model", "Best"})
+STRONG_COLUMNS = frozenset({"Task"})
+METRIC_COLUMNS = frozenset({"Metric"})
+RIGHT_COLUMNS = frozenset({"Rank", "Patients", "Submissions count"})
+METRIC_GUIDES = {
+    "AUROC": "Range: 0 to 1 · Random predictor: 0.5",
+    "Pearson": "Range: -1 to 1 · Random predictor: 0 (expected)",
+    "Residual Spearman score": "Range: -1 to 1 · Random predictor: 0 (expected)",
+    "Centered Spearman score": "Range: -1 to 1 · Random predictor: 0 (expected)",
+}
+PUBLIC_CHIP = (
+    ' <span class="pm-public-chip" title="Labels downloadable from the PRIMO '
+    'dataset" aria-label="Public labels">Public</span>'
+)
+BASELINE_CHIP = (
+    '<span class="pm-tag pm-tag--base" title="Our reference model">Baseline</span>'
+)
+
+
+def evaluation_confirmation() -> str:
+    """Render the confirmation shown before a model evaluation starts."""
+    return (
+        '<dialog id="pm-evaluation-confirmation" class="pm-dialog" '
+        'aria-labelledby="pm-evaluation-confirmation-title">'
+        '<form method="dialog" class="pm-dialog-surface">'
+        '<p class="pm-over">Confirm submission</p>'
+        '<h2 id="pm-evaluation-confirmation-title">'
+        "Evaluate and submit this model?</h2>"
+        "<p>Evaluation can take several minutes. If it succeeds, this submission "
+        "will update the public leaderboards.</p>"
+        '<div class="pm-dialog-actions">'
+        '<button class="pm-btn pm-btn--outline" value="cancel">Cancel</button>'
+        '<button class="pm-btn pm-btn--primary" value="confirm">'
+        "Evaluate model</button>"
+        "</div></form></dialog>"
+    )
+
+
+def evaluation_status() -> str:
+    """Render the progress message shown while an evaluation runs."""
+    return (
+        '<div class="pm-evaluation-status" role="status" aria-live="polite">'
+        '<svg class="pm-spinner" aria-hidden="true" viewBox="0 0 24 24">'
+        '<circle cx="12" cy="12" r="9"></circle>'
+        '<path d="M12 3a9 9 0 0 1 9 9"></path></svg>'
+        "<span>Your embeddings are being evaluated... This can take a few "
+        "minutes.</span></div>"
+    )
+
+
+def _href(query: str, version: Version = CURRENT) -> str:
+    """A reload link that stays on ``version``; the current one needs no tag."""
+    if version != CURRENT:
+        query = f"{query}&{VERSION_PARAM}={version.number}"
+    return escape(f"?{query}")
+
+
+def _number(version: Version) -> tuple[int, ...]:
+    """The version number as integers, so ``0.10`` comes after ``0.9``."""
+    return tuple(int(part) for part in version.number.split("."))
+
+
+def _closed_on(version: Version) -> str:
+    """The day the version after ``version`` opened."""
+    later = [listed for listed in VERSIONS if _number(listed) > _number(version)]
+    return min(later, key=_number).opened
+
+
+# ------------------------------------------------------------- html tables
+def _fmt_value(value, is_score: bool) -> str | None:
+    """Display text for one cell; ``None`` marks a blank (``n/a``) cell."""
+    try:
+        if pd.isna(value):
+            return None
+    except (TypeError, ValueError):
+        pass
+    if isinstance(value, str):
+        return value
+    if isinstance(value, numbers.Integral):
+        return str(int(value))
+    if isinstance(value, numbers.Real):
+        if not math.isfinite(float(value)):
+            return None
+        return f"{float(value):.3f}" if is_score else str(value)
+    return str(value)
+
+
+def _model_cell_html(cell: ModelCell) -> str:
+    """One model on one line: its name, its chips, then a dotted leader.
+
+    Only escaped HTTP(S) paper links become links.
+    """
+    label = escape(str(cell).removesuffix(f" {BASELINE_TAG}"))
+    parsed = urlparse(cell.paper_link)
+    if parsed.scheme in {"http", "https"} and parsed.netloc:
+        url = escape(cell.paper_link, quote=True)
+        label = (
+            f'<a class="pm-model-link" href="{url}" target="_blank" '
+            f'rel="noopener noreferrer">{label}</a>'
+        )
+    chips = []
+    if cell.is_hvg:
+        chips.append(
+            '<span class="pm-tag pm-tag--hvg" title="Concatenated with the HVG-1200 '
+            'baseline features" aria-label="Concatenated with the HVG-1200 baseline '
+            'features">+ HVG</span>'
+        )
+    if cell.is_baseline:
+        chips.append(BASELINE_CHIP)
+    if cell.is_author_submission:
+        chips.append(
+            '<span class="pm-tag pm-tag--author" title="Submitted by the model '
+            'authors" aria-label="Submitted by the model authors">✓ Authors</span>'
+        )
+    return (
+        f'<div class="pm-pipe"><span class="pm-lrn">{label}</span>'
+        f'{"".join(chips)}<span class="pm-leader"></span></div>'
+    )
+
+
+def _with_baseline_chip(name: str) -> str:
+    """The escaped name, its ``(baseline)`` tag shown as the Baseline chip."""
+    if not name.endswith(f" {BASELINE_TAG}"):
+        return escape(name)
+    return f"{escape(name.removesuffix(f' {BASELINE_TAG}'))} {BASELINE_CHIP}"
+
+
+def _score_columns(df: pd.DataFrame) -> list[str]:
+    """Numeric columns to format and bold -- ``Rank`` is an index, not a score."""
+    return [c for c in df.select_dtypes("number").columns if c not in RIGHT_COLUMNS]
+
+
+def _score_guide(col: str, row: pd.Series) -> str | None:
+    """Return metric context for a native score cell, when identifiable."""
+    metric = next((name for name in METRIC_GUIDES if f"({name})" in col), None)
+    if metric is None and col not in {"Elo", "Mean rank"}:
+        metric = str(row.get("Metric", ""))
+    return METRIC_GUIDES.get(metric) if metric is not None else None
+
+
+def _bold_cells(df: pd.DataFrame, score_cols: list[str], axis: int) -> set:
+    """Which ``(row, col)`` cells hold the best value.
+
+    ``axis=0`` bolds the best model per column (the ranked table, read down);
+    ``axis=1`` bolds the best model per row (the per-task table, read across).
+    """
+    bold = set()
+    if not score_cols:
+        return bold
+    if axis == 0:
+        for col in score_cols:
+            best = (
+                df[col].min(skipna=True)
+                if col == "Mean rank"
+                else df[col].max(skipna=True)
+            )
+            if pd.notna(best):
+                for idx, value in df[col].items():
+                    if pd.notna(value) and value == best:
+                        bold.add((idx, col))
+    else:
+        for idx, row in df.iterrows():
+            present = {c: row[c] for c in score_cols if pd.notna(row[c])}
+            if present:
+                best = max(present.values())
+                bold.update((idx, c) for c, v in present.items() if v == best)
+    return bold
+
+
+def _cell_class(col: str, is_score: bool, blank: bool) -> str:
+    if col in NAME_COLUMNS:
+        return "pm-name"
+    if col in STRONG_COLUMNS:
+        return "pm-strong"
+    if col in METRIC_COLUMNS:
+        return "pm-metric"
+    if is_score or col in RIGHT_COLUMNS:
+        return "pm-num pm-num--dim" if blank else "pm-num"
+    return ""
+
+
+def _task_tooltip(task: dict) -> str:
+    """Build the expanded clinical context shown for a task name."""
+    description = str(task.get("description") or "").strip().rstrip(".")
+    diseases = (
+        ", ".join(str(d) for d in task.get("diseases") or []) or "the listed cohort"
+    )
+    patients = task.get("n_subjects") or task.get("n_samples")
+    patient_text = (
+        f"{patients:,} patients"
+        if isinstance(patients, int)
+        else "an unspecified number of patients"
+    )
+    n_samples = task.get("n_samples")
+    if (
+        isinstance(n_samples, int)
+        and isinstance(patients, int)
+        and n_samples != patients
+    ):
+        patient_text += f" ({n_samples:,} collection samples)"
+    modality = str(task.get("modality") or "omics")
+    tissue = str(task.get("tissue") or "unspecified tissue")
+    target = str(task.get("target") or task.get("title") or "the task target")
+    return (
+        f"{description}. Patients: {patient_text} with {diseases}; "
+        f"input data: {modality} profiles from {tissue.lower()}; "
+        f"outcome: {target}."
+    )
+
+
+def _df_to_table(
+    df: pd.DataFrame,
+    bold_axis: int | None,
+    empty: str,
+    task_guides: dict[str, dict] | None = None,
+) -> str:
+    """Render a DataFrame as a ``pm-table``, escaping every header and cell."""
+    if df.empty:
+        return f'<p class="pm-caption">{escape(empty)}</p>'
+    repeat_sd = df.attrs.get("repeat_standard_deviations", {})
+    df = df.copy(deep=False)
+    df.attrs = {}
+    score_cols = _score_columns(df)
+    bold = _bold_cells(df, score_cols, bold_axis) if bold_axis is not None else set()
+
+    head = []
+    for index, col in enumerate(df.columns):
+        name = _with_baseline_chip(str(col))
+        align = (
+            ' style="text-align:right"'
+            if col in score_cols or col in RIGHT_COLUMNS
+            else ""
+        )
+        head.append(
+            f'<th class="pm-sort" data-sort-index="{index}" tabindex="0" '
+            f'role="button" aria-sort="none" title="Sort by {escape(str(col))}"'
+            f"{align}>{name}</th>"
+        )
+    body = []
+    for idx, row in df.iterrows():
+        cells = []
+        for col in df.columns:
+            is_score = col in score_cols
+            text = _fmt_value(row[col], is_score)
+            cls = _cell_class(col, is_score, text is None)
+            weight = ' style="font-weight:700"' if (idx, col) in bold else ""
+            guide = (
+                _score_guide(str(col), row) if is_score and text is not None else None
+            )
+            shown = (
+                _model_cell_html(row[col])
+                if isinstance(row[col], ModelCell)
+                else "n/a"
+                if text is None
+                else _with_baseline_chip(text)
+                if col in NAME_COLUMNS
+                else escape(text)
+            )
+            standard_deviation = repeat_sd.get((idx, col))
+            uncertainty = ""
+            if standard_deviation and text is not None:
+                deviation, repeats = standard_deviation
+                sd_text = f"{deviation:.3f}"
+                uncertainty = (
+                    f" Standard deviation across {repeats} repeats: {sd_text}."
+                )
+                shown += f'<span class="pm-sd" aria-hidden="true"> ± {sd_text}</span>'
+            if guide:
+                escaped_guide = escape(guide, quote=True)
+                score_label = escape(f"Score {text}.{uncertainty} {guide}", quote=True)
+                shown = (
+                    '<span class="pm-score-guide" tabindex="0" '
+                    f'aria-label="{score_label}" '
+                    f'data-tooltip="{escaped_guide}">{shown}</span>'
+                )
+            if task_guides and col == "Task" and text is not None:
+                task = next(
+                    (
+                        candidate
+                        for candidate in task_guides.values()
+                        if candidate.get("title") == text
+                    ),
+                    None,
+                )
+                if task:
+                    tooltip = _task_tooltip(task)
+                    escaped_tooltip = escape(tooltip, quote=True)
+                    task_label = escape(f"{text}. {tooltip}", quote=True)
+                    shown = (
+                        '<span class="pm-task-guide" tabindex="0" '
+                        f'aria-label="{task_label}" data-tooltip="{escaped_tooltip}">'
+                        f'<span class="pm-task-text">{shown}</span></span>'
+                    )
+            if isinstance(row[col], TaskCell) and row[col].is_public:
+                shown += PUBLIC_CHIP
+            sort_value = (
+                f' data-sort-value="{escape(text, quote=True)}"'
+                if is_score and text is not None
+                else ""
+            )
+            cells.append(f'<td class="{cls}"{sort_value}{weight}>{shown}</td>')
+        body.append(f"<tr>{''.join(cells)}</tr>")
+    return (
+        '<div class="pm-table-wrap"><table class="pm-table" style="table-layout:auto">'
+        f"<thead><tr>{''.join(head)}</tr></thead>"
+        f"<tbody>{''.join(body)}</tbody></table></div>"
+    )
+
+
+# ------------------------------------------------------------------- tasks
+def render_tasks(by_id: dict[str, dict]) -> str:
+    """The Tasks page: one scannable row per target. Provenance is never shown."""
+    df = tasks_table(list(by_id.values()))
+    table = _df_to_table(
+        df,
+        bold_axis=None,
+        empty="The task registry is unavailable right now.",
+        task_guides=by_id,
+    )
+    return (
+        '<div class="pm-head"><div><h1>Tasks</h1>'
+        f"<p>{len(df)} targets. One fixed task probe reads each "
+        "one out of your embedding; the cohorts stay anonymous, the biology does "
+        "not.</p></div></div>"
+        f'<div class="pm-body">{table}</div>'
+    )
+
+
+# ------------------------------------------------------------- leaderboard
+SPACE_URL = "https://huggingface.co/spaces/PRIMOmics/primo-eval"
+DATA_URL = "https://huggingface.co/datasets/PRIMOmics/primo"
+PAPER_URL = "https://openreview.net/forum?id=v2SA8gHwqo"
+
+NAV_TABS = (
+    ("leaderboard", "Leaderboard"),
+    ("tasks", "Tasks"),
+    ("method", "Method"),
+    ("contribute", "Contribute"),
+)
+LEDE = (
+    "PRIMO ranks omics foundation models on real "
+    '<a target="_self" href="{tasks}">clinical tasks</a>. Your model turns each '
+    "patient's omics profile into an embedding. One fixed probe, the same for every "
+    "model, then predicts hidden outcomes such as treatment response or prognosis, "
+    "so the score measures the embedding."
+)
+RANKED_NOTE = (
+    '<p class="pm-note">We score zero-shot representations, so a score is not the '
+    "best a model can reach. Only models that covered every task scored by the "
+    f"<code>{ELO_ANCHOR_MODEL}</code> baseline are ranked. <code>+ HVG</code> rows "
+    "concatenate a model with the baseline's features.</p>"
+)
+N_TOP = 3
+ORDINAL_SUFFIXES = {1: "st", 2: "nd", 3: "rd"}
+NOT_SCORES = frozenset({"Rank", "Submissions count"})
+RANKED_LABELS = {"Submissions count": "Subm."}
+RANKED_NOTES = {"Model": "paper linked when given"}
+RANKED_HINTS = {
+    "Elo": f"The {ELO_ANCHOR_MODEL} baseline sits at 1000.",
+    "Mean rank": "Lower is better.",
+    "Submissions count": (
+        "Submissions: the most times one task of this model was submitted."
+    ),
+}
+SHORT_METRICS = {
+    "Centered Spearman score": "centered Spearman",
+    "Residual Spearman score": "residual Spearman",
+}
+CATEGORY_HEADER = re.compile(r"^(?P<name>.+) \((?P<metric>[^()]+)\)$")
+STRABLE_URL = "https://gblayer.github.io/strable-leaderboard/"
+BOARD_SUB = (
+    '<p class="pm-board-sub">Models are ranked by Elo over the tasks of the view, '
+    f"anchored on the {ELO_ANCHOR_MODEL} baseline at 1000. Task columns show the "
+    "mean score, each in its own metric.</p>"
+)
+ART_GENES = (0.55, 0.9, 0.4, 0.75, 0.35, 0.95, 0.5, 0.8, 0.45, 0.7, 0.3, 0.85, 0.6, 0.4)
+ART_EMBEDDING = (0.7, 1.0, 0.6, 0.9, 0.75, 0.95)
+ART_LAYERS = ((4, 132), (5, 150), (3, 168))
+ART_TASKS = ("Treatment response", "Prognosis", "Disease severity", "Molecular subtype")
+CREDIT = (
+    '<p class="pm-credit">Design inspired by the '
+    f'<a href="{STRABLE_URL}" target="_blank" rel="noopener noreferrer">STRABLE '
+    "leaderboard</a>.</p>"
+)
+
+
+def _art_text(x: float, y: float, text: str, cls: str, anchor: str = "middle") -> str:
+    return f'<text class="{cls}" x="{x}" y="{y}" text-anchor="{anchor}">{text}</text>'
+
+
+def _art_arrow(x1: float, x2: float, y: float) -> str:
+    return (
+        f'<line class="pm-art-line" x1="{x1}" y1="{y}" x2="{x2 - 6}" y2="{y}"></line>'
+        f'<path class="pm-art-head" d="M{x2 - 7} {y - 4} L{x2} {y} L{x2 - 7} {y + 4} Z">'
+        "</path>"
+    )
+
+
+def _hero_art() -> str:
+    """The hero figure: a patient's omics, a model, one embedding, many tasks."""
+    parts = [
+        _art_text(58, 22, "Patient omics", "pm-art-h"),
+        _art_text(162, 22, "Your model", "pm-art-h"),
+        _art_text(254, 22, "Embedding", "pm-art-h"),
+        _art_text(351, 22, "Clinical tasks", "pm-art-h"),
+        '<circle class="pm-art-patient" cx="58" cy="44" r="8"></circle>',
+        '<path class="pm-art-patient" d="M45 66 Q58 50 71 66 Z"></path>',
+    ]
+    parts += [
+        f'<rect class="pm-art-{"b" if index % 3 == 0 else "a"}" x="47" '
+        f'y="{74 + index * 11}" width="22" height="9" rx="1.5" opacity="{level}"></rect>'
+        for index, level in enumerate(ART_GENES)
+    ]
+    parts += [
+        _art_text(58, 246, "gene expression", "pm-art-c"),
+        _art_arrow(78, 112, 150),
+        '<rect class="pm-art-box" x="114" y="112" width="96" height="76" rx="14"></rect>',
+    ]
+    nodes = [
+        [(162 + (k - (count - 1) / 2) * 16, y) for k in range(count)]
+        for count, y in ART_LAYERS
+    ]
+    parts += [
+        f'<line class="pm-art-edge" x1="{x1}" y1="{y1}" x2="{x2}" y2="{y2}"></line>'
+        for upper, lower in pairwise(nodes)
+        for x1, y1 in upper
+        for x2, y2 in lower
+    ]
+    parts += [
+        f'<circle class="pm-art-node" cx="{x}" cy="{y}" r="3.2"></circle>'
+        for layer in nodes
+        for x, y in layer
+    ]
+    parts += [
+        _art_text(162, 204, "omics foundation model", "pm-art-c"),
+        _art_arrow(212, 244, 150),
+    ]
+    parts += [
+        f'<rect class="pm-art-{"a" if index % 2 else "b"}" x="246" y="{100 + index * 17}" '
+        f'width="16" height="14" rx="2" opacity="{level}"></rect>'
+        for index, level in enumerate(ART_EMBEDDING)
+    ]
+    parts += [
+        _art_text(254, 218, "sample", "pm-art-c"),
+        _art_text(254, 230, "representation", "pm-art-c"),
+    ]
+    for index, task in enumerate(ART_TASKS):
+        y = 74 + index * 44
+        parts += [
+            f'<path class="pm-art-line" d="M268 150 C 278 150, 278 {y}, 288 {y}"></path>',
+            f'<rect class="pm-art-pill" x="290" y="{y - 14}" width="122" height="28" '
+            'rx="14"></rect>',
+            _art_text(302, y + 4, task, "pm-art-t", anchor="start"),
+        ]
+    return (
+        '<div class="pm-art"><svg class="pm-hero-art" viewBox="0 0 420 268" '
+        'role="img" aria-labelledby="pm-art-title"><title id="pm-art-title">A patient\'s '
+        "omics profile goes through your model, which returns one embedding per "
+        "sample. The same fixed probe then scores that embedding on clinical tasks."
+        f"</title>{''.join(parts)}</svg></div>"
+    )
+
+
+def updated_on(df: pd.DataFrame) -> str:
+    """The day of the latest stored result, or ``""`` when there is none."""
+    if df.empty or "submitted_at" not in df:
+        return ""
+    return str(df["submitted_at"].astype(str).max())[:10]
+
+
+def _model_count(df: pd.DataFrame) -> int:
+    """Submitted models, a ``+ HVG`` entry counted with its parent, baselines out."""
+    flagged = with_baseline_flag(df)
+    if flagged.empty:
+        return 0
+    return len(
+        {
+            split_hvg_name(str(model))[0]
+            for model, is_baseline in zip(flagged[MODEL_NAME], flagged[IS_BASELINE])
+            if not is_baseline
+        }
+    )
+
+
+def version_notice(version: Version) -> str:
+    """On a closed version, a banner that says so and links to the current one."""
+    if version == CURRENT:
+        return ""
+    return (
+        '<div class="pm-notice" role="status">'
+        f"<b>Version v{escape(version.number)} is closed.</b> "
+        f"Its scores, from {escape(version.opened)} to "
+        f"{escape(_closed_on(version))}, are kept read-only. "
+        f'<a target="_self" href="{_href("tab=leaderboard")}">'
+        f"Go to the current version, v{escape(CURRENT.number)}</a></div>"
+    )
+
+
+def _cite_dialog(version: Version) -> str:
+    """The window of the Cite button: how to cite PRIMO and the version on screen."""
+    bibtex = (
+        "@misc{primo2026,\n"
+        "  title        = {{PRIMO}: Patient Representations in Multi-Omics},\n"
+        "  author       = {{PRIMO contributors}},\n"
+        "  year         = {2026},\n"
+        f"  note         = {{Leaderboard version {version.number}}},\n"
+        f"  howpublished = {{\\url{{{SPACE_URL}}}}}\n"
+        "}"
+    )
+    return (
+        '<dialog id="pm-cite-dialog" class="pm-dialog" aria-labelledby="pm-cite-title">'
+        '<form method="dialog" class="pm-dialog-surface">'
+        '<h2 id="pm-cite-title">Cite PRIMO</h2>'
+        "<p><b>Evaluating a model on PRIMO?</b> Please cite PRIMO and give the board "
+        "version you used, for example "
+        f"<code>PRIMO leaderboard v{escape(version.number)}</code>.</p>"
+        f"<pre>{escape(bibtex)}</pre>"
+        '<div class="pm-dialog-actions">'
+        '<button class="pm-btn pm-btn--outline" value="close">Close</button>'
+        "</div></form></dialog>"
+    )
+
+
+def nav_html(active_tab: str, version: Version = CURRENT) -> str:
+    """The top bar: the PRIMO mark, the pages, the data, the paper, Submit and Cite.
+
+    On a closed version, every page link keeps it, except Submit, Cite names it,
+    and a banner under the bar says the version is closed.
+    """
+    links = [
+        f'<a class="{"pm-active" if tab == active_tab else ""}" target="_self" '
+        f'href="{_href(f"tab={tab}", version)}">{name}</a>'
+        for tab, name in NAV_TABS
+    ]
+    links += [
+        f'<a href="{url}" target="_blank" rel="noopener noreferrer">{name}</a>'
+        for url, name in ((DATA_URL, "Data"), (PAPER_URL, "Paper"))
+    ]
+    return (
+        '<header class="pm-nav"><a class="pm-logo" target="_self" '
+        f'href="{_href("tab=leaderboard", version)}" aria-label="PRIMO leaderboard">'
+        '<img src="/gradio_api/file=assets/primo-mark.webp" alt="">'
+        "<b>PRIMO</b></a>"
+        '<div class="pm-nav-right">'
+        f'<nav class="pm-nav-links" aria-label="Main">{"".join(links)}</nav>'
+        '<a class="pm-btn" target="_self" href="?tab=submit">Submit a model</a>'
+        '<button type="button" class="pm-btn pm-btn--outline" id="pm-cite-btn" '
+        'aria-haspopup="dialog" aria-controls="pm-cite-dialog">Cite</button>'
+        f"</div></header>{_cite_dialog(version)}{version_notice(version)}"
+    )
+
+
+def hero_html(boards: list[Board], df: pd.DataFrame, version: Version = CURRENT) -> str:
+    """The title block: version, PRIMO, what it is, its size, and the visual."""
+    layers = in_group(boards, MODALITY_GROUP)
+    stats = (
+        (sum(b.n_tasks for b in layers), "tasks"),
+        (sum(b.n_cohorts for b in layers), "cohorts"),
+        (sum(b.n_patients for b in layers), "patients"),
+        (len(layers), "modalities"),
+        (_model_count(df), "models"),
+    )
+    chips = "".join(f"<li><b>{n:,}</b> {name}</li>" for n, name in stats)
+    updated = updated_on(df)
+    stamp = (
+        f'<span class="pm-updated">Updated {escape(updated)}</span>' if updated else ""
+    )
+    badge = f'<span class="pm-ver">v{escape(version.number)}</span>'
+    if version != CURRENT:
+        badge = (
+            f'<span class="pm-ver pm-ver--closed">v{escape(version.number)} '
+            "· closed</span>"
+        )
+    return (
+        '<section class="pm-hero" aria-labelledby="pm-hero-title"><div>'
+        '<p class="pm-eyebrow"><span class="pm-label">Leaderboard</span>'
+        f'{badge}<a class="pm-ver-link" href="#pm-history">Release notes</a>'
+        f"{stamp}</p>"
+        '<h1 id="pm-hero-title">PRIMO</h1>'
+        '<p class="pm-expand"><span class="pm-xp"><b>P</b>atient <b>R</b>epresentations '
+        "<b>i</b>n <b>M</b>ulti-<b>O</b>mics</span></p>"
+        f'<p class="pm-lede">{LEDE.format(tasks=_href("tab=tasks", version))}</p>'
+        f'<ul class="pm-stats">{chips}</ul></div>'
+        f'<div class="pm-art-wrap">{_hero_art()}</div>'
+        "</section>"
+    )
+
+
+def _ordinal(rank: int) -> str:
+    """``1`` -> ``1st``, ``12`` -> ``12th``."""
+    suffix = "th" if 10 <= rank % 100 <= 20 else ORDINAL_SUFFIXES.get(rank % 10, "th")
+    return f"{rank}{suffix}"
+
+
+def _ranked_header(index: int, col: str, numeric: bool) -> str:
+    match = CATEGORY_HEADER.match(col)
+    if match:
+        name = match["name"]
+        note = SHORT_METRICS.get(match["metric"], match["metric"])
+    else:
+        name, note = RANKED_LABELS.get(col, col), RANKED_NOTES.get(col, "")
+    align = " pm-r" if numeric else ""
+    small = f"<small>{escape(note)}</small>" if note else ""
+    hint = escape(
+        f"Sort by {name.rstrip('.')}. {RANKED_HINTS.get(col, '')}".strip(), quote=True
+    )
+    return (
+        f'<th class="pm-sort{align}" data-sort-index="{index}" tabindex="0" '
+        f'role="button" aria-sort="none" title="{hint}">{escape(name)}{small}</th>'
+    )
+
+
+def _ranked_cell(
+    table: pd.DataFrame, idx, col: str, bold: set, scores: list, numeric: set
+) -> str:
+    """One cell of the ranked table, on one line."""
+    value = table.at[idx, col]
+    if col == "Rank":
+        return (
+            f'<td class="pm-rank" data-sort-value="{int(value)}">'
+            f"{_ordinal(int(value))}</td>"
+        )
+    if isinstance(value, ModelCell):
+        return (
+            f'<td class="pm-name" data-sort-value="{escape(str(value), quote=True)}">'
+            f"{_model_cell_html(value)}</td>"
+        )
+    is_score = col in scores
+    text = _fmt_value(value, is_score)
+    if col not in numeric:
+        shown = "n/a" if text is None else escape(text)
+        dim = " pm-dim" if text is None else ""
+        return f'<td class="pm-inst{dim}">{shown}</td>'
+    if text is None:
+        return '<td class="pm-num pm-dim">n/a</td>'
+    shown = escape(text)
+    guide = _score_guide(col, table.loc[idx]) if is_score else None
+    if guide:
+        label = escape(f"Score {text}. {guide}", quote=True)
+        shown = (
+            f'<span class="pm-score-guide" tabindex="0" aria-label="{label}" '
+            f'data-tooltip="{escape(guide, quote=True)}">{shown}</span>'
+        )
+    cls = "pm-num"
+    if col == "Elo":
+        cls += " pm-key"
+    if (idx, col) in bold:
+        cls += " pm-best"
+    return (
+        f'<td class="{cls}" data-sort-value="{escape(text, quote=True)}">{shown}</td>'
+    )
+
+
+def _count(n: int, noun: str) -> str:
+    """``<b>1</b> task``, ``<b>6</b> tasks``."""
+    return f"<b>{n:,}</b> {noun}{'' if n == 1 else 's'}"
+
+
+def _view_head(board: Board, view_name: str) -> str:
+    """The head of the ranking card: the view, then how many tasks it holds."""
+    counts = " · ".join(
+        (
+            _count(board.n_tasks, "task"),
+            _count(board.n_cohorts, "cohort"),
+            _count(board.n_patients, "patient"),
+        )
+    )
+    return (
+        f'<div class="pm-card-head"><span class="pm-view">{escape(view_name)}</span>'
+        f'<span class="pm-view-n">{counts}</span></div>'
+    )
+
+
+def _ranked_html(table: pd.DataFrame) -> str:
+    """The ranked table: one line per model, the top three framed."""
+    if table.empty:
+        return (
+            '<p class="pm-empty">No model has covered every scored task of this view '
+            "yet. Be the first to submit.</p>"
+        )
+    numeric = set(table.select_dtypes("number").columns)
+    scores = [c for c in table.columns if c in numeric and c not in NOT_SCORES]
+    bold = _bold_cells(table, scores, axis=0)
+    head = "".join(
+        _ranked_header(index, str(col), col in numeric)
+        for index, col in enumerate(table.columns)
+    )
+    n_top = min(N_TOP, len(table))
+    body = []
+    for position, idx in enumerate(table.index):
+        classes = []
+        if position < n_top:
+            classes.append("pm-top")
+        if position == 0:
+            classes.append("pm-top-first")
+        if position == n_top - 1:
+            classes.append("pm-top-last")
+        cells = "".join(
+            _ranked_cell(table, idx, str(col), bold, scores, numeric)
+            for col in table.columns
+        )
+        body.append(f'<tr class="{" ".join(classes)}">{cells}</tr>')
+    return (
+        '<div class="pm-tbl-wrap"><table class="pm-table pm-ranked">'
+        f"<thead><tr>{head}</tr></thead><tbody>{''.join(body)}</tbody>"
+        "</table></div>"
+    )
+
+
+def _per_task_details(per_task: pd.DataFrame, by_id: dict, board: Board) -> str:
+    """The per-task scores, folded under the ranking."""
+    table = _df_to_table(
+        per_task,
+        bold_axis=1,
+        empty="No submission has scored on this view yet.",
+        task_guides=by_id,
+    )
+    return (
+        '<details class="pm-more"><summary><span class="pm-title">Scores per task'
+        f'</span><span class="pm-more-n">{board.n_tasks} tasks</span></summary>'
+        '<p class="pm-note">Every submission, partial ones included. Read across a '
+        "row. Scores show mean ± SD when repeat-level results are available.</p>"
+        f"{table}</details>"
+    )
+
+
+def render_view(
+    board: Board,
+    df: pd.DataFrame,
+    by_id: dict[str, dict],
+    view_name: str,
+    show_hvg: bool,
+) -> str:
+    """One view: its size, its ranking, then its per-task scores."""
+    rows = df if show_hvg else without_hvg(df)
+    head = _view_head(board, view_name)
+    if not by_id:
+        return (
+            f'<div class="pm-card">{head}<p class="pm-empty">The task registry could '
+            "not be loaded. Please retry in a moment.</p></div>"
+        )
+    if not board.task_ids:
+        return (
+            f'<div class="pm-card">{head}<p class="pm-empty">No task in this view '
+            "yet. Pick another therapeutic area or task.</p></div>"
+        )
+    ranked = _ranked_html(ranked_table(rows, by_id, board))
+    return (
+        f'<div class="pm-card">{head}{ranked}</div>'
+        + RANKED_NOTE
+        + _per_task_details(per_task_table(rows, by_id, board), by_id, board)
+    )
+
+
+def history_html(df: pd.DataFrame, version: Version = CURRENT) -> str:
+    """The release notes: every board version, what changed, and its board.
+
+    A version other than the one on screen links to its board, so a closed
+    version stays one click away now that no menu lists them.
+    """
+    cite = ", ".join(
+        part
+        for part in (f"PRIMO leaderboard v{version.number}", updated_on(df), SPACE_URL)
+        if part
+    )
+    items = []
+    for listed in VERSIONS:
+        state = "current" if listed == CURRENT else "closed"
+        span = (
+            f"since {listed.opened}"
+            if listed == CURRENT
+            else f"{listed.opened} to {_closed_on(listed)}"
+        )
+        link = (
+            ""
+            if listed == version
+            else f'<a target="_self" href="{_href("tab=leaderboard", listed)}">'
+            "View this board</a>"
+        )
+        items.append(
+            f'<li class="{"pm-on" if listed == version else ""}">'
+            f"<b>v{escape(listed.number)}</b><div>"
+            f'<p class="pm-ver-meta"><span class="pm-chip pm-chip--{state}">{state}'
+            f"</span> {escape(span)} · release {escape(listed.release)}</p>"
+            f"<p>{escape(listed.notes)}</p></div>{link}</li>"
+        )
+    return (
+        '<section class="pm-history" id="pm-history" '
+        'aria-labelledby="pm-history-title"><div>'
+        '<h2 class="pm-title" id="pm-history-title">Release notes</h2>'
+        '<p class="pm-history-sub">What changed in each board version. A closed '
+        "version keeps its board, read-only. To cite a rank: "
+        f"<span>{escape(cite)}</span>.</p></div><ol>{''.join(items)}</ol></section>"
+    )
+
+
+def cta_html(boards: list[Board], version: Version = CURRENT) -> str:
+    """The closing panel: an open call for cohorts, with examples of what is missing."""
+    gaps = [b.name for group in SECTIONS for b in open_in_group(boards, group)]
+    missing = ""
+    if gaps:
+        listed = gaps[0] if len(gaps) == 1 else f"{', '.join(gaps[:-1])} and {gaps[-1]}"
+        missing = f"Still missing, for example: {listed}. "
+    return (
+        '<section class="pm-ask" aria-labelledby="pm-ask-title"><div>'
+        '<p class="pm-label">Help us grow PRIMO</p>'
+        '<h2 id="pm-ask-title">Which cohort should PRIMO cover next?</h2></div>'
+        '<div class="pm-ask-go"><p>PRIMO is open to any omics layer and any disease '
+        f"area. {escape(missing)}Bring a cohort, or propose a task on the cohorts "
+        "already here.</p>"
+        f'<a class="pm-btn" target="_self" href="{_href("tab=contribute", version)}">'
+        "Contribute</a>"
+        "</div></section>"
+    )

requirements.txt

@@ -0,0 +1,9 @@
+numpy==2.5.4
+pandas==2.3.3
+pyarrow
+joblib==1.6.0
+scikit-learn==1.9.1
+scipy==1.18.1
+pyyaml
+huggingface_hub<1.0
+audioop-lts; python_version >= "3.13"

rescore.py

@@ -0,0 +1,465 @@
+"""Rescore the live entries of a board version into the current version.
+
+A new board version opens with an empty board, as its harness has scored nothing
+yet. This maintainer tool fills it from the archived embedding files, so nobody
+has to submit again. An entry is live when it holds the latest row of a slot of
+the old version, on a task that still exists.
+
+- Each live submission is scored again, plain and ``+ HVG``, at the current pins.
+  Its rows keep the model name, submission id, credits and the archive's
+  ``submitted_at``, and carry the current version.
+- The ``HVG-1200-genes`` baseline is scored again from the reference features,
+  which are its submission.
+- An entry keeps its task set: the tasks its old rows covered that still exist,
+  plus the tasks the new version adds. ``--all-tasks`` scores every task the file
+  covers instead.
+- The datasets the current manifest no longer lists are dropped from the file,
+  because ``score_all`` would refuse the whole file.
+- A submission is scored again only on the tasks where the current version holds
+  no row of its entry from the same time or later. A second run after the deploy
+  then only picks up the submissions made in between.
+- An archive whose manifest records no representation is read as an embedding,
+  as the Space scored it.
+- An entry that fails, or that gets no score on a task it held, stops the run
+  before anything is published, with or without ``--all-tasks``. To publish the
+  others, rerun with ``--models`` and the entries to keep.
+
+``--from legacy`` reads the rows written before versions existed.
+
+    HF_TOKEN=... python rescore.py --from 0.1 --dry-run
+    HF_TOKEN=... python rescore.py --from 0.1 --checkpoint-dir ckpt --out rows.csv
+    HF_TOKEN=... python rescore.py --from 0.1 --checkpoint-dir ckpt --publish
+"""
+
+import argparse
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pandas as pd
+from evaluator import (
+    DATASET_ID,
+    EMBEDDING,
+    GENE_SPACE,
+    RESULTS_REPO,
+    TASK_ID,
+    EvaluatorError,
+    SubmissionError,
+    _norm_id,
+    fetch_manifest,
+    fetch_tasks_registry,
+    load_submission,
+    manifest_ids,
+    score_all,
+    scoreable_tasks,
+)
+from leaderboard import latest_only
+from results import (
+    ARCHIVE_DIR,
+    ARCHIVE_MANIFEST,
+    HVG_REFERENCE_MODEL,
+    HVG_TAG,
+    INSTITUTION,
+    IS_AUTHOR_SUBMISSION,
+    IS_BASELINE,
+    MODEL_NAME,
+    OWNER,
+    PAPER_LINK,
+    SUBMISSION_ID,
+    append_results,
+    archive_paths,
+    fetch_hvg_reference,
+    hvg_name,
+    read_results,
+    task_rows,
+    version_rows,
+    with_baseline_flag,
+    with_owner,
+)
+from versions import CURRENT, VERSIONS
+
+LEGACY = "legacy"
+CREDITS = (OWNER, INSTITUTION, IS_AUTHOR_SUBMISSION, PAPER_LINK)
+
+
+@dataclass(frozen=True)
+class Carry:
+    """One live entry to score again: an archived file, or the HVG baseline.
+
+    ``archive`` is the file's path in the results repo, or None for the baseline,
+    whose file is the reference. ``task_ids`` None means every task of the file.
+    ``held`` are the tasks its old rows covered: each one must score again.
+    """
+
+    model_name: str
+    is_baseline: bool
+    submission_id: str
+    submitted_at: str
+    modality: str | None
+    representation: str
+    archive: str | None
+    task_ids: frozenset[str] | None
+    held: frozenset[str]
+    credits: dict = field(default_factory=dict, compare=False)
+
+
+def representation_of(manifest: dict) -> str:
+    """How to read an archive: as its manifest says, else as an embedding."""
+    return manifest.get("representation", EMBEDDING)
+
+
+def _slots(rows: pd.DataFrame) -> list[tuple[str, bool, str]]:
+    """The ``(model, is_baseline, task)`` slot of each row."""
+    return [
+        (str(model), bool(is_baseline), _norm_id(task_id))
+        for model, is_baseline, task_id in zip(
+            rows[MODEL_NAME], rows[IS_BASELINE], rows[TASK_ID]
+        )
+    ]
+
+
+def _newest(rows: pd.DataFrame) -> dict[tuple[str, bool, str], str]:
+    """The newest ``submitted_at`` of each slot of ``rows``."""
+    flagged = with_baseline_flag(rows)
+    newest = {}
+    for slot, date in zip(_slots(flagged), flagged["submitted_at"].astype(str)):
+        newest[slot] = max(newest.get(slot, ""), date)
+    return newest
+
+
+def _open_rows(
+    rows: pd.DataFrame, newest: dict, since: str | None = None
+) -> pd.DataFrame:
+    """The ``rows`` whose slot holds no row from ``since`` or later in ``newest``.
+
+    Without ``since``, each row is compared with its own date.
+    """
+    dates = rows["submitted_at"].astype(str) if since is None else [since] * len(rows)
+    keep = [newest.get(slot, "") < date for slot, date in zip(_slots(rows), dates)]
+    return rows[pd.Series(keep, index=rows.index, dtype=bool)]
+
+
+def _task_set(
+    held: frozenset[str], added: set[str], all_tasks: bool
+) -> frozenset[str] | None:
+    """The held tasks plus the added ones, or None for every task."""
+    if all_tasks:
+        return None
+    return held | frozenset(added)
+
+
+def carried(
+    old: pd.DataFrame,
+    new: pd.DataFrame,
+    manifests: list[dict],
+    task_ids: set[str],
+    added: set[str],
+    all_tasks: bool = False,
+) -> tuple[list[Carry], list[str]]:
+    """The live entries of ``old`` to score into ``new``, and those with no archive."""
+    latest = with_owner(latest_only(old))
+    if latest.empty:
+        return [], []
+    live = latest[latest[TASK_ID].map(_norm_id).isin(task_ids)]
+    plain = live[
+        ~live[IS_BASELINE] & ~live[MODEL_NAME].astype(str).str.endswith(HVG_TAG)
+    ]
+    newest = _newest(new)
+    carries = []
+    for manifest in manifests:
+        model, submission_id = manifest["model_name"], manifest["submission_id"]
+        rows = plain[
+            (plain[SUBMISSION_ID] == submission_id) & (plain[MODEL_NAME] == model)
+        ]
+        rows = _open_rows(rows, newest, manifest["submitted_at"])
+        if rows.empty:
+            continue
+        parent = rows.iloc[-1]
+        held = frozenset(rows[TASK_ID].map(_norm_id))
+        carries.append(
+            Carry(
+                model_name=model,
+                is_baseline=False,
+                submission_id=submission_id,
+                submitted_at=manifest["submitted_at"],
+                modality=manifest["modality"],
+                representation=representation_of(manifest),
+                archive=archive_paths(submission_id, manifest["source_format"])[0],
+                task_ids=_task_set(held, added, all_tasks),
+                held=held,
+                credits={key: parent[key] for key in CREDITS},
+            )
+        )
+    archived = {(m["model_name"], m["submission_id"]) for m in manifests}
+    orphans = sorted(
+        {
+            row[MODEL_NAME]
+            for slot, (_, row) in zip(_slots(plain), plain.iterrows())
+            if (row[MODEL_NAME], row[SUBMISSION_ID]) not in archived
+            and newest.get(slot, "") < str(row["submitted_at"])
+        }
+    )
+    baseline = live[live[IS_BASELINE] & (live[MODEL_NAME] == HVG_REFERENCE_MODEL)]
+    if not baseline.empty:
+        since = str(baseline["submitted_at"].astype(str).max())
+        baseline = _open_rows(baseline, newest)
+        if not baseline.empty:
+            held = frozenset(baseline[TASK_ID].map(_norm_id))
+            carries.append(
+                Carry(
+                    model_name=HVG_REFERENCE_MODEL,
+                    is_baseline=True,
+                    submission_id="",
+                    submitted_at=since,
+                    modality=None,
+                    representation=GENE_SPACE,
+                    archive=None,
+                    task_ids=_task_set(held, added, all_tasks),
+                    held=held,
+                )
+            )
+    return carries, orphans
+
+
+def without_retired(path: Path, valid: set[str], out: Path) -> tuple[Path, list[str]]:
+    """The file without the datasets ``valid`` no longer lists, and their ids.
+
+    The file is rewritten to ``out`` only when a dataset has to go.
+    """
+    blocks = load_submission(path)
+    retired = sorted(set(blocks) - valid)
+    if not retired:
+        return path, []
+    kept = [
+        block.assign(**{DATASET_ID: dataset_id})
+        for dataset_id, block in blocks.items()
+        if dataset_id in valid
+    ]
+    if not kept:
+        raise SubmissionError(f"no dataset of the file is still listed: {retired}")
+    frame = pd.concat(kept, ignore_index=True)
+    frame.columns = frame.columns.map(str)
+    frame.to_parquet(out, index=False)
+    return out, retired
+
+
+def rescore(
+    carry: Carry,
+    source: Path,
+    reference: Path,
+    datasets: list[dict],
+    registry: list[dict],
+    workdir: Path,
+    token: str | None,
+    checkpoint_dir: Path | None = None,
+) -> list[dict]:
+    """The rows of ``carry`` in the current version, plain and ``+ HVG``."""
+    name = carry.submission_id or carry.model_name
+    path, retired = without_retired(
+        source, manifest_ids(datasets), workdir / f"{name}.parquet"
+    )
+    if retired:
+        logging.warning(
+            "%s: dropped the retired datasets %s", carry.model_name, retired
+        )
+    tasks = [
+        task
+        for task in registry
+        if carry.task_ids is None or _norm_id(task[TASK_ID]) in carry.task_ids
+    ]
+
+    def _rows(model: str, features: Path | None) -> list[dict]:
+        result = score_all(
+            path,
+            token,
+            modality=carry.modality,
+            representation=carry.representation,
+            datasets=datasets,
+            tasks=tasks,
+            checkpoint_dir=checkpoint_dir,
+            reference=features,
+        )
+        for invalid in result["invalid"]:
+            logging.warning(
+                "%s: no score on %s: %s", model, invalid[TASK_ID], invalid["reason"]
+            )
+        return task_rows(
+            model, result, carry.submitted_at, carry.submission_id, carry.credits
+        )
+
+    if carry.is_baseline:
+        return [{**row, IS_BASELINE: True} for row in _rows(carry.model_name, None)]
+    return _rows(carry.model_name, None) + _rows(hvg_name(carry.model_name), reference)
+
+
+def lost_tasks(carry: Carry, rows: list[dict]) -> list[str]:
+    """The tasks ``carry`` held that one of its entries got no row for."""
+    names = [carry.model_name]
+    if not carry.is_baseline:
+        names.append(hvg_name(carry.model_name))
+    lost = set()
+    for name in names:
+        lost |= carry.held - {row[TASK_ID] for row in rows if row[MODEL_NAME] == name}
+    return sorted(lost)
+
+
+def _score_carries(
+    carries: list[Carry],
+    reference: Path,
+    datasets: list[dict],
+    registry: list[dict],
+    token: str | None,
+    checkpoint_dir: Path | None,
+) -> tuple[list[dict], list[str]]:
+    """The rows of every carry, and one line per carry that failed."""
+    rows, failures = [], []
+    with TemporaryDirectory() as workdir:
+        for carry in carries:
+            source = (
+                reference if carry.archive is None else _download(carry.archive, token)
+            )
+            try:
+                scored = rescore(
+                    carry,
+                    source,
+                    reference,
+                    datasets,
+                    registry,
+                    Path(workdir),
+                    token,
+                    checkpoint_dir,
+                )
+            except (SubmissionError, EvaluatorError) as error:
+                failures.append(f"{carry.model_name}: {error}")
+                continue
+            lost = lost_tasks(carry, scored)
+            if lost:
+                failures.append(f"{carry.model_name}: no score on held tasks {lost}")
+            logging.info("%s: %d rows", carry.model_name, len(scored))
+            rows += scored
+    return rows, failures
+
+
+def _manifests(token: str | None) -> list[dict]:
+    """Every archived submission manifest in the private results dataset."""
+    from huggingface_hub import HfApi
+
+    files = HfApi(token=token).list_repo_files(RESULTS_REPO, repo_type="dataset")
+    return [
+        json.loads(_download(path, token).read_text())
+        for path in files
+        if path.startswith(f"{ARCHIVE_DIR}/") and path.endswith(f"/{ARCHIVE_MANIFEST}")
+    ]
+
+
+def _download(path_in_repo: str, token: str | None) -> Path:
+    """One file of the private results dataset, at its latest commit."""
+    from huggingface_hub import hf_hub_download
+
+    return Path(
+        hf_hub_download(RESULTS_REPO, path_in_repo, repo_type="dataset", token=token)
+    )
+
+
+def _task_ids(registry: list[dict], datasets: list[dict]) -> set[str]:
+    """The ids of the tasks of ``registry`` on the datasets the manifest lists."""
+    return {
+        _norm_id(task[TASK_ID])
+        for task in scoreable_tasks(registry, manifest_ids(datasets))
+    }
+
+
+def _describe(carry: Carry) -> str:
+    tasks = "every task" if carry.task_ids is None else f"{len(carry.task_ids)} tasks"
+    kind = "baseline" if carry.is_baseline else carry.modality
+    return f"{carry.model_name} ({kind}, {carry.representation}): {tasks}"
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--from",
+        dest="source",
+        required=True,
+        help=f"the version to rescore, or '{LEGACY}' for rows without one",
+    )
+    parser.add_argument("--models", nargs="+", default=None, help="only these models")
+    parser.add_argument(
+        "--all-tasks", action="store_true", help="score every task each file covers"
+    )
+    parser.add_argument("--checkpoint-dir", type=Path, default=None)
+    parser.add_argument("--out", type=Path, default=None, help="write the rows here")
+    parser.add_argument("--dry-run", action="store_true", help="list, score nothing")
+    parser.add_argument(
+        "--publish", action="store_true", help="append the rows to the leaderboard"
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """CLI entry point."""
+    args = _parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    token = os.environ.get("HF_TOKEN")
+    if args.publish and not token:
+        raise SystemExit("--publish needs write access: set HF_TOKEN.")
+    if args.source == CURRENT.number:
+        raise SystemExit(f"{CURRENT.number} is the current version: pick an older one.")
+    old_version = next((v for v in VERSIONS if v.number == args.source), None)
+    if args.source != LEGACY and old_version is None:
+        raise SystemExit(f"unknown version {args.source}")
+
+    datasets = fetch_manifest(token)
+    registry = fetch_tasks_registry(token)
+    task_ids = _task_ids(registry, datasets)
+    old_ids = (
+        task_ids
+        if old_version is None
+        else _task_ids(
+            fetch_tasks_registry(token, old_version.labels),
+            fetch_manifest(token, old_version.data),
+        )
+    )
+    results = read_results(token)
+    carries, orphans = carried(
+        version_rows(results, "" if old_version is None else old_version.number),
+        version_rows(results, CURRENT.number),
+        _manifests(token),
+        task_ids,
+        task_ids - old_ids,
+        args.all_tasks,
+    )
+    carries = [c for c in carries if args.models is None or c.model_name in args.models]
+    logging.info("%d entries to rescore into %s:", len(carries), CURRENT.number)
+    for carry in carries:
+        logging.info("  %s", _describe(carry))
+    if orphans:
+        logging.warning("no archive, so not carried over: %s", orphans)
+    if args.dry_run:
+        return
+
+    rows, failures = _score_carries(
+        carries,
+        fetch_hvg_reference(token),
+        datasets,
+        registry,
+        token,
+        args.checkpoint_dir,
+    )
+    if args.out is not None:
+        pd.DataFrame(rows).to_csv(args.out, index=False)
+    if failures:
+        raise SystemExit(
+            f"Failed entries: {len(failures)}, so nothing is published. Fix them, or "
+            "rerun with --models and the entries to keep:\n" + "\n".join(failures)
+        )
+    if args.publish:
+        append_results(rows, token)
+        logging.info("published %d rows into version %s", len(rows), CURRENT.number)
+
+
+if __name__ == "__main__":
+    main()

results.py

@@ -0,0 +1,458 @@
+"""Persisted leaderboard rows: the results-CSV schema and its Hugging Face IO.
+
+Kept out of ``app.py`` so the schema has one owner and so the baseline publisher
+can append rows without importing Gradio. ``huggingface_hub`` is imported lazily,
+so the unit tests touch no network.
+
+``is_baseline`` marks a reference submission we produced ourselves (log-normalized
+expression, whole or cut to its most variable genes) rather than a model somebody
+sent us. Baselines are ranked in place, never pinned: the point of showing them is
+that a foundation model can lose to an information-rich expression baseline, and
+a row pushed to the bottom of the table would hide exactly that.
+
+``hf_username`` privately records who submitted a name, because the board keeps
+each name's LATEST rows: without an owner, anyone could supersede another team's
+ranked entry by sending a one-task file under their model name. The Submit form
+refuses a name somebody else already claimed. New submissions separately store
+an optional public ``institution``, an author-submission flag and a paper link;
+legacy owners remain private. Historical ``team`` values are read as institutions.
+
+Rows written before these columns existed carry no column at all, so every
+reader normalises the baseline flag, ownership, public credits and submission
+identity. Missing legacy public-credit values remain private.
+
+Each row records the board ``version`` whose harness scored it, which is always
+the current version of this code. A board shows only the rows of its version.
+Rows written before versions existed carry none and are shown on no board.
+
+Every submission is also scored concatenated with our ``HVG-1200-genes``
+baseline features and stored as a second entry, ``<model> + HVG``, sharing the
+parent's owner, credits and submission id. It shows what a model adds on top of
+plain expression. The features live privately at ``HVG_REFERENCE_FILE``, next
+to the results. They are read at the commit the board version pins, so a new
+upload is used only once a release pins it.
+
+The Space and ``rescore.py`` both append to the same CSV files. An append reads
+a file at the latest commit, adds its rows, and uploads the whole file on top of
+that commit only. If another write lands in between, the Hub refuses the upload,
+and the append reads the file again, up to ``WRITE_ATTEMPTS`` times. So two
+appends that cross never lose a row.
+"""
+
+import hashlib
+import io
+import json
+from collections.abc import Callable
+from http import HTTPStatus
+from pathlib import Path
+
+import pandas as pd
+from evaluator import EMBEDDING, RESULTS_REPO, EvaluatorError, load_submission
+from versions import CURRENT
+
+RESULTS_FILE = "task_results.csv"
+SUBMISSIONS_FILE = "submissions.csv"
+
+MODEL_NAME = "model_name"
+IS_BASELINE = "is_baseline"
+OWNER = "hf_username"
+INSTITUTION = "institution"
+LEGACY_TEAM = "team"
+IS_AUTHOR_SUBMISSION = "is_author_submission"
+PAPER_LINK = "paper_link"
+SUBMISSION_ID = "submission_id"
+VERSION = "version"
+
+RESULT_COLUMNS = [
+    MODEL_NAME,
+    "task_id",
+    "score",
+    "repeat_scores",
+    "diagnostics",
+    "submitted_at",
+    IS_BASELINE,
+    OWNER,
+    INSTITUTION,
+    IS_AUTHOR_SUBMISSION,
+    PAPER_LINK,
+    SUBMISSION_ID,
+    VERSION,
+]
+SUBMISSION_COLUMNS = [
+    MODEL_NAME,
+    "submitted_at",
+    OWNER,
+    INSTITUTION,
+    IS_AUTHOR_SUBMISSION,
+    SUBMISSION_ID,
+    "email",
+    PAPER_LINK,
+    "hf_model_link",
+    "notes",
+]
+
+TRUTHY = ("true", "1")
+BASELINE_TAG = "(baseline)"
+HVG_TAG = "+ HVG"
+HVG_REFERENCE_MODEL = "HVG-1200-genes"
+HVG_REFERENCE_FILE = f"baselines/{HVG_REFERENCE_MODEL}/submission.parquet"
+ARCHIVE_DIR = "models"
+ARCHIVE_MANIFEST = "manifest.json"
+WRITE_ATTEMPTS = 3
+
+
+def with_baseline_flag(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a boolean ``is_baseline`` column, whatever the CSV held.
+
+    Read back from CSV the column can be bool, the strings ``True``/``False``, or
+    absent on rows written before baselines existed; all of those must collapse
+    to a real boolean before anything ranks on it.
+    """
+    if IS_BASELINE not in df.columns:
+        return df.assign(**{IS_BASELINE: False})
+    flags = df[IS_BASELINE].astype(str).str.strip().str.lower().isin(TRUTHY)
+    return df.assign(**{IS_BASELINE: flags})
+
+
+def with_owner(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a string ``hf_username`` column; an absent one means unclaimed."""
+    return _with_text_column(df, OWNER)
+
+
+def with_institution(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee an institution, falling back to the former ``team`` field."""
+    normalized = _with_text_column(df, INSTITUTION)
+    if LEGACY_TEAM not in normalized.columns:
+        return normalized
+    legacy = _with_text_column(normalized, LEGACY_TEAM)[LEGACY_TEAM]
+    values = normalized[INSTITUTION].mask(normalized[INSTITUTION] == "", legacy)
+    return normalized.assign(**{INSTITUTION: values})
+
+
+def with_submission_id(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a submission id; legacy rows fall back to their timestamp."""
+    return _with_text_column(df, SUBMISSION_ID)
+
+
+def with_version(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a board-version column; legacy rows have the empty version."""
+    return _with_text_column(df, VERSION)
+
+
+def version_rows(df: pd.DataFrame, number: str) -> pd.DataFrame:
+    """The rows that board version ``number`` scored."""
+    versioned = with_version(df)
+    return versioned[versioned[VERSION] == number]
+
+
+def with_paper_link(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a public paper-link column; legacy rows have no public link."""
+    return _with_text_column(df, PAPER_LINK)
+
+
+def with_author_submission_flag(df: pd.DataFrame) -> pd.DataFrame:
+    """Guarantee a boolean author-submission flag; legacy rows are unverified."""
+    if IS_AUTHOR_SUBMISSION not in df.columns:
+        return df.assign(**{IS_AUTHOR_SUBMISSION: False})
+    flags = df[IS_AUTHOR_SUBMISSION].astype(str).str.strip().str.lower().isin(TRUTHY)
+    return df.assign(**{IS_AUTHOR_SUBMISSION: flags})
+
+
+def _with_text_column(df: pd.DataFrame, column: str) -> pd.DataFrame:
+    """Normalize a nullable CSV text column without stringifying missing values."""
+    if column not in df.columns:
+        return df.assign(**{column: ""})
+    values = df[column].map(lambda value: "" if pd.isna(value) else str(value).strip())
+    return df.assign(**{column: values})
+
+
+def owner_of(df: pd.DataFrame, model: str) -> str:
+    """Who claimed this submitted model name, or ``""`` if it is free.
+
+    Baselines are ignored: they live in their own namespace (``is_baseline``), so
+    publishing a baseline never reserves its name for user submissions.
+    """
+    if df.empty:
+        return ""
+    claimed = with_owner(with_baseline_flag(df))
+    rows = claimed[
+        (claimed[MODEL_NAME] == model) & ~claimed[IS_BASELINE] & (claimed[OWNER] != "")
+    ]
+    return "" if rows.empty else str(rows.iloc[-1][OWNER])
+
+
+def display_name(model: str, is_baseline: bool) -> str:
+    """Leaderboard label: a baseline says so, in the one column everybody reads."""
+    return f"{model} {BASELINE_TAG}" if is_baseline else model
+
+
+def hvg_name(model: str) -> str:
+    """Name of the entry scoring ``model`` concatenated with the HVG features."""
+    return f"{model} {HVG_TAG}"
+
+
+def split_hvg_name(model: str) -> tuple[str, bool]:
+    """Split ``<model> + HVG`` into the parent name and whether it is one."""
+    suffix = f" {HVG_TAG}"
+    if model.endswith(suffix):
+        return model.removesuffix(suffix), True
+    return model, False
+
+
+def without_hvg(df: pd.DataFrame) -> pd.DataFrame:
+    """Drop the rows of every ``<model> + HVG`` entry."""
+    return df[~df[MODEL_NAME].astype(str).str.endswith(f" {HVG_TAG}")]
+
+
+def fetch_hvg_reference(token: str | None, revision: str = CURRENT.reference) -> Path:
+    """Local path to the HVG-1200 features every submission is concatenated with."""
+    from huggingface_hub import hf_hub_download
+
+    return Path(
+        hf_hub_download(
+            RESULTS_REPO,
+            HVG_REFERENCE_FILE,
+            repo_type="dataset",
+            token=token,
+            revision=revision,
+        )
+    )
+
+
+def upload_hvg_reference(path: str | Path, token: str | None) -> str:
+    """Replace the HVG-1200 features; return the commit that holds them, to pin."""
+    from huggingface_hub import HfApi
+
+    return (
+        HfApi(token=token)
+        .upload_file(
+            path_or_fileobj=str(path),
+            path_in_repo=HVG_REFERENCE_FILE,
+            repo_id=RESULTS_REPO,
+            repo_type="dataset",
+            commit_message="Update HVG-1200 reference features",
+        )
+        .oid
+    )
+
+
+def task_rows(
+    model: str, result: dict, submitted_at: str, submission_id: str, credits: dict
+) -> list[dict]:
+    """One row per task scored in ``result``, credited and tagged with this version."""
+    return [
+        {
+            MODEL_NAME: model,
+            "task_id": task.task_id,
+            "score": round(float(task.score), 4),
+            "repeat_scores": json.dumps(
+                [round(float(value), 4) for value in task.repeat_scores]
+            ),
+            "diagnostics": json.dumps(
+                {key: round(float(value), 4) for key, value in task.diagnostics.items()}
+            ),
+            "submitted_at": submitted_at,
+            IS_BASELINE: False,
+            SUBMISSION_ID: submission_id,
+            VERSION: CURRENT.number,
+            **credits,
+        }
+        for task in result["per_task"]
+    ]
+
+
+def read_csv(
+    filename: str, columns: list[str], token: str | None, revision: str | None = None
+) -> pd.DataFrame:
+    """One CSV of the private results dataset, at ``revision`` or the latest commit.
+
+    An absent file is an empty table.
+    """
+    from huggingface_hub import hf_hub_download
+    from huggingface_hub.utils import EntryNotFoundError, RepositoryNotFoundError
+
+    try:
+        path = hf_hub_download(
+            RESULTS_REPO, filename, repo_type="dataset", token=token, revision=revision
+        )
+    except (RepositoryNotFoundError, EntryNotFoundError):
+        return pd.DataFrame(columns=columns)
+    return pd.read_csv(path, dtype={VERSION: str})
+
+
+def upload_csv(
+    filename: str, df: pd.DataFrame, token: str | None, parent_commit: str
+) -> None:
+    """Overwrite one CSV, unless a commit landed on top of ``parent_commit``."""
+    from huggingface_hub import HfApi
+
+    buffer = io.BytesIO()
+    df.to_csv(buffer, index=False)
+    buffer.seek(0)
+    HfApi(token=token).upload_file(
+        path_or_fileobj=buffer,
+        path_in_repo=filename,
+        repo_id=RESULTS_REPO,
+        repo_type="dataset",
+        parent_commit=parent_commit,
+    )
+
+
+def _append_csv(
+    filename: str, extended: Callable[[str], pd.DataFrame], token: str | None
+) -> None:
+    """Upload ``extended(head)``: the CSV read at commit ``head``, plus new rows.
+
+    When another write lands first, read the CSV again at the new head.
+    """
+    from huggingface_hub import HfApi
+    from huggingface_hub.utils import HfHubHTTPError
+
+    api = HfApi(token=token)
+    api.create_repo(RESULTS_REPO, repo_type="dataset", private=True, exist_ok=True)
+    for _ in range(WRITE_ATTEMPTS):
+        head = api.dataset_info(RESULTS_REPO).sha
+        try:
+            upload_csv(filename, extended(head), token, head)
+            return
+        except HfHubHTTPError as error:
+            if error.response.status_code != HTTPStatus.PRECONDITION_FAILED:
+                raise
+    raise EvaluatorError(
+        f"another write changed {filename} during each of {WRITE_ATTEMPTS} "
+        "attempts, so these rows were not saved: try again"
+    )
+
+
+def archive_paths(submission_id: str, source_format: str) -> tuple[str, str]:
+    """Where a submission's file and its manifest are archived in the results repo."""
+    prefix = f"{ARCHIVE_DIR}/{submission_id}"
+    return (
+        f"{prefix}/submission{source_format or '.bin'}",
+        f"{prefix}/{ARCHIVE_MANIFEST}",
+    )
+
+
+def _embedding_manifest(
+    path: str | Path,
+    model_name: str,
+    submission_id: str,
+    modality: str,
+    submitted_at: str,
+    representation: str = EMBEDDING,
+) -> tuple[dict, bytes]:
+    """Build a privacy-preserving manifest for an embedding submission."""
+    source = Path(path)
+    digest = hashlib.sha256()
+    with source.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    blocks = load_submission(source)
+    frame = pd.concat(
+        [block.assign(dataset_id=dataset_id) for dataset_id, block in blocks.items()],
+        ignore_index=True,
+    )
+    counts = frame["dataset_id"].value_counts().sort_index().to_dict()
+    embedding_columns = [
+        column for column in frame.columns if column not in {"dataset_id", "sample_id"}
+    ]
+    manifest = {
+        "model_name": model_name,
+        "submission_id": submission_id,
+        "submitted_at": submitted_at,
+        "modality": modality,
+        "representation": representation,
+        "source_format": source.suffix.lower(),
+        "sha256": digest.hexdigest(),
+        "size_bytes": source.stat().st_size,
+        "n_rows": len(frame),
+        "embedding_dimension": len(embedding_columns),
+        "dataset_row_counts": {str(key): int(value) for key, value in counts.items()},
+    }
+    return manifest, json.dumps(manifest, indent=2).encode()
+
+
+def archive_submission(
+    path: str | Path,
+    model_name: str,
+    submission_id: str,
+    modality: str,
+    submitted_at: str,
+    token: str | None,
+    representation: str = EMBEDDING,
+) -> None:
+    """Archive an embedding file and its manifest in the private results dataset."""
+    from huggingface_hub import CommitOperationAdd, HfApi
+
+    source = Path(path)
+    _, manifest_bytes = _embedding_manifest(
+        source, model_name, submission_id, modality, submitted_at, representation
+    )
+    file_path, manifest_path = archive_paths(submission_id, source.suffix.lower())
+    HfApi(token=token).create_commit(
+        repo_id=RESULTS_REPO,
+        repo_type="dataset",
+        operations=[
+            CommitOperationAdd(path_in_repo=file_path, path_or_fileobj=source),
+            CommitOperationAdd(
+                path_in_repo=manifest_path, path_or_fileobj=manifest_bytes
+            ),
+        ],
+        commit_message=f"Archive embedding submission {submission_id}",
+    )
+
+
+def read_results(token: str | None, revision: str | None = None) -> pd.DataFrame:
+    """Every persisted task score, with baseline, credit and version normalised."""
+    return with_version(
+        with_submission_id(
+            with_paper_link(
+                with_author_submission_flag(
+                    with_institution(
+                        with_owner(
+                            with_baseline_flag(
+                                read_csv(RESULTS_FILE, RESULT_COLUMNS, token, revision)
+                            )
+                        )
+                    )
+                )
+            )
+        )
+    )
+
+
+def append_results(rows: list[dict], token: str | None) -> None:
+    """Append scored rows to the leaderboard, keeping the history intact."""
+    if not rows:
+        return
+
+    def extended(head: str) -> pd.DataFrame:
+        df = pd.concat(
+            [read_results(token, head), pd.DataFrame(rows)], ignore_index=True
+        )
+        return with_version(
+            with_submission_id(
+                with_paper_link(
+                    with_author_submission_flag(
+                        with_institution(with_owner(with_baseline_flag(df)))
+                    )
+                )
+            )
+        )
+
+    _append_csv(RESULTS_FILE, extended, token)
+
+
+def append_submission(meta: dict, token: str | None) -> None:
+    """Persist private contact metadata with matching public-credit fields."""
+
+    def extended(head: str) -> pd.DataFrame:
+        return pd.concat(
+            [
+                read_csv(SUBMISSIONS_FILE, SUBMISSION_COLUMNS, token, head),
+                pd.DataFrame([meta]),
+            ],
+            ignore_index=True,
+        )
+
+    _append_csv(SUBMISSIONS_FILE, extended, token)

scoring.py

@@ -0,0 +1,171 @@
+"""Scoring policy for the PRIMO benchmark: predictions -> per-category numbers.
+
+Everything that turns a model's fold-wise cross-validation scores into leaderboard
+numbers lives here, kept apart from the probe and from any I/O so it stays easy
+to change as the benchmark grows.
+
+The scoring unit is a task = (dataset, target). Tasks are grouped by their
+``category`` (including treatment outcome, clinical scores, endotype, and
+perturbation response). A category uses a SINGLE metric (enforced in the registry),
+so its leaderboard number is a plain mean of that metric -- AUROC, Pearson and
+centered Spearman are never averaged together inside a category column.
+
+``sort_key`` is the one place they are averaged, to give the board a single
+order. It is shown as the ``Mean`` column, labelled as a cross-metric average so
+nobody reads it as a metric in its own right; the per-category columns remain
+the numbers to compare on.
+
+Pure numpy / sklearn-metrics -- no huggingface, no file I/O, so it unit-tests
+without a network and is safe to rework mid-project.
+"""
+
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import numpy as np
+from sklearn.metrics import roc_auc_score
+
+
+def compute_auroc(
+    y_true: np.ndarray, y_pred: np.ndarray, classes: np.ndarray | None = None
+) -> float:
+    """AUROC from class probabilities (``y_pred`` is an ``(n, n_classes)`` matrix).
+
+    ``classes`` names the columns of ``y_pred``. It matters whenever ``y_true``
+    holds fewer classes than the task does -- a transfer split whose test cohort
+    misses one. The columns of the absent classes are dropped and the rest
+    renormalized, so the score never reads a column belonging to another class,
+    and never trips sklearn's sum-to-one check.
+    """
+    classes = np.unique(y_true) if classes is None else np.asarray(classes)
+    present = np.isin(classes, np.unique(y_true))
+    scores = np.asarray(y_pred)[:, present]
+    totals = scores.sum(axis=1, keepdims=True)
+    if not (totals > 0).all():
+        raise ValueError(
+            "some samples carry no probability on any class present in y_true"
+        )
+    scores = scores / totals
+    kept = classes[present]
+    if len(kept) == 2:
+        return float(roc_auc_score(y_true, scores[:, 1]))
+    return float(
+        roc_auc_score(
+            y_true, scores, multi_class="ovr", average="weighted", labels=kept
+        )
+    )
+
+
+def compute_pearson(
+    y_true: np.ndarray, y_pred: np.ndarray, classes: np.ndarray | None = None
+) -> float:
+    """Pearson r between predictions and targets; NaN if either is constant."""
+    if np.std(y_pred) == 0 or np.std(y_true) == 0:
+        return float("nan")
+    return float(np.corrcoef(y_pred, y_true)[0, 1])
+
+
+def _average_ranks(values: np.ndarray) -> np.ndarray:
+    """Return stable, one-based average ranks with deterministic tie handling."""
+    values = np.asarray(values)
+    order = np.argsort(values, kind="stable")
+    sorted_values = values[order]
+    sorted_ranks = np.empty(len(values), dtype=float)
+    start = 0
+    while start < len(values):
+        stop = start + 1
+        while stop < len(values) and sorted_values[stop] == sorted_values[start]:
+            stop += 1
+        sorted_ranks[start:stop] = 0.5 * (start + stop - 1) + 1.0
+        start = stop
+    ranks = np.empty(len(values), dtype=float)
+    ranks[order] = sorted_ranks
+    return ranks
+
+
+def _mean_sample_spearman(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Return mean row-wise rank correlation, scoring degenerate rows at zero."""
+    correlations = []
+    for truth, prediction in zip(y_true, y_pred):
+        correlation = compute_pearson(_average_ranks(truth), _average_ranks(prediction))
+        correlations.append(correlation if np.isfinite(correlation) else 0.0)
+    return float(np.mean(correlations)) if correlations else float("nan")
+
+
+def compute_residual_sample_spearman(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    training_mean: np.ndarray,
+) -> float:
+    """Mean sample-wise Spearman beyond the training-fold mean response."""
+    return _mean_sample_spearman(y_true - training_mean, y_pred - training_mean)
+
+
+def compute_target_centered_sample_spearman(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+) -> float:
+    """Mean sample-wise Spearman after removing each target-cohort gene mean."""
+    truth_centered = y_true - np.mean(y_true, axis=0)
+    prediction_centered = y_pred - np.mean(y_pred, axis=0)
+    return _mean_sample_spearman(truth_centered, prediction_centered)
+
+
+METRICS: dict[str, Callable[[np.ndarray, np.ndarray, np.ndarray | None], float]] = {
+    "auroc": compute_auroc,
+    "pearson": compute_pearson,
+}
+
+
+@dataclass(frozen=True)
+class TaskScore:
+    """One task's result: a raw metric plus the category it is grouped under."""
+
+    task_id: str
+    dataset_id: str
+    category: str
+    metric: str
+    score: float
+    n_samples: int
+    repeat_scores: tuple[float, ...] = ()
+    diagnostics: dict[str, float] = field(default_factory=dict)
+
+
+def category_means(scores: list[TaskScore]) -> dict[str, dict]:
+    """Mean of the native metric per task category.
+
+    A category uses one metric, so this is a plain mean of that metric -- never a
+    mix of native metrics. Degenerate (non-finite) task scores are dropped from
+    the mean. Returns ``{category: {metric, mean, n_tasks}}`` for the categories
+    present in ``scores``.
+    """
+    by_category: dict[str, list[TaskScore]] = defaultdict(list)
+    for score in scores:
+        by_category[score.category].append(score)
+    out = {}
+    for category, items in by_category.items():
+        finite = [s.score for s in items if np.isfinite(s.score)]
+        out[category] = {
+            "metric": items[0].metric,
+            "mean": float(np.mean(finite)) if finite else float("nan"),
+            "n_tasks": len(items),
+        }
+    return out
+
+
+def sort_key(categories: dict[str, dict]) -> float:
+    """Leaderboard ranking key: mean of the per-category means.
+
+    Orders the rows, and is shown as the ``Mean`` column on boards holding more
+    than one category. It does average across native metrics, a
+    deliberate compromise for a single order; swap for a per-category-normalized
+    mean if the ranking needs to be metric-fair.
+
+    An entry with nothing finite to average sorts LAST, not at zero: a constant
+    embedding scores NaN on every Pearson task, and zero would float it above a
+    model that merely correlates negatively -- ranking "no score" over "a bad
+    score". Nothing finite means nothing to show, so the table renders it blank.
+    """
+    means = [c["mean"] for c in categories.values() if np.isfinite(c["mean"])]
+    return float(np.mean(means)) if means else float("-inf")

submit_api.py

@@ -0,0 +1,123 @@
+"""The ``/submit`` endpoint that ``primo submit`` calls.
+
+The web form and the endpoint share one path: both call ``run_submission`` in
+``app.py``, so the same checks, scores and records apply to both. The endpoint
+reads the caller's Hugging Face token only to learn the account name, with
+``whoami``. It never stores the token, logs it or puts it in a message. Only a
+non-empty string reaches ``whoami``: for any other value, such as ``""``, ``None``
+or ``True``, ``whoami`` falls back to the token of the Space itself. A 401 or a
+403 from ``whoami`` means a bad token, which the caller fixes. Any other failure,
+such as a timeout or a 5xx, is on our side.
+
+Gradio checks that a file comes from an upload only when its payload carries the
+``gradio.FileData`` marker, which ``gradio_client.handle_file`` adds. Without the
+marker, a caller could send the path of any file of the Space, so the endpoint
+refuses such a payload.
+
+An account can publish ``SUBMISSIONS_PER_DAY`` submissions in 24 hours, through
+the form and the endpoint together. A file can weigh ``MAX_FILE_SIZE`` at most.
+The form and the endpoint share the ``SUBMISSIONS`` queue, so one submission runs
+at a time.
+"""
+
+import logging
+from collections.abc import Callable
+from datetime import datetime, timedelta
+from http import HTTPStatus
+
+import pandas as pd
+from results import (
+    IS_BASELINE,
+    OWNER,
+    SUBMISSION_ID,
+    with_baseline_flag,
+    with_owner,
+    with_submission_id,
+)
+
+PUBLISHED = "published"
+REFUSED = "refused"
+ERROR = "error"
+SUBMISSIONS = "submissions"
+SUBMISSIONS_PER_DAY = 4
+MAX_FILE_SIZE = 500_000_000
+SUBMITTED_AT = "%Y-%m-%d %H:%M:%S.%f"
+FILE_DATA = "gradio.FileData"
+
+
+def reply(status: str, message: str, submission_id: str = "") -> dict:
+    """The answer to one submission, as ``primo submit`` reads it."""
+    return {"status": status, "message": message, "submission_id": submission_id}
+
+
+def recent_submissions(df: pd.DataFrame, owner: str, now: datetime) -> int:
+    """How many submissions ``owner`` published in the 24 hours before ``now``."""
+    since = (now - timedelta(days=1)).strftime(SUBMITTED_AT)
+    rows = with_submission_id(with_owner(with_baseline_flag(df)))
+    recent = rows[
+        (rows[OWNER] == owner)
+        & ~rows[IS_BASELINE]
+        & (rows["submitted_at"].astype(str) >= since)
+    ]
+    return int(recent[SUBMISSION_ID].nunique())
+
+
+def route(core: Callable[..., dict]) -> Callable[..., dict]:
+    """The ``/submit`` endpoint, which checks, scores and saves through ``core``."""
+
+    def submit(
+        submission_path: dict,
+        modality: str,
+        model_name: str,
+        institution: str,
+        is_author_submission: bool,
+        email: str,
+        paper_link: str,
+        hf_model_link: str,
+        notes: str,
+        token: str,
+    ) -> dict:
+        """Score one submission file that ``primo submit`` sends."""
+        from huggingface_hub import HfApi
+
+        meta = (
+            submission_path.get("meta") if isinstance(submission_path, dict) else None
+        )
+        if not isinstance(meta, dict) or meta.get("_type") != FILE_DATA:
+            return reply(
+                REFUSED, "Send the submission file with gradio_client.handle_file."
+            )
+        if not isinstance(token, str) or not token.strip():
+            return reply(REFUSED, "Send a Hugging Face token: run `hf auth login`.")
+        try:
+            username = HfApi().whoami(token=token.strip())["name"]
+        except Exception as error:  # noqa: BLE001
+            status = getattr(getattr(error, "response", None), "status_code", None)
+            if status in (HTTPStatus.UNAUTHORIZED, HTTPStatus.FORBIDDEN):
+                return reply(
+                    REFUSED,
+                    "Hugging Face refused the token. Log in again with "
+                    "`hf auth login`.",
+                )
+            logging.warning(
+                "whoami failed: %s, status %s", type(error).__name__, status
+            )
+            return reply(
+                ERROR,
+                "⚠️ We could not check the token with Hugging Face. This is on our "
+                "side, not your token. Please try again in a moment.",
+            )
+        return core(
+            submission_path["path"],
+            modality,
+            model_name,
+            institution,
+            is_author_submission,
+            email,
+            paper_link,
+            hf_model_link,
+            notes,
+            username,
+        )
+
+    return submit

versions.py

@@ -0,0 +1,57 @@
+"""Board versions: the Hub commits that each version of the leaderboard reads.
+
+A board version is a minor release of primo-eval: version ``0.1`` is scored by the
+``v0.1.x`` releases. It pins the commit of every Hub repo that a score reads, so a
+push to one of these repos changes no score until a release opens a new version.
+
+``versions.yaml`` lists every version. ``current`` is the version this code scores
+and shows by default. Each version names its release tag, the day it opened, and
+three commits: ``data`` of the public data repo, ``labels`` of the private labels
+repo, and ``reference`` of the results repo, which holds the HVG features. Its
+``notes`` say in one line what changed: the board shows them to every visitor.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+VERSIONS_FILE = Path(__file__).parent / "versions.yaml"
+
+
+@dataclass(frozen=True)
+class Version:
+    """One board version, the Hub commits its scores read, and what changed."""
+
+    number: str
+    release: str
+    opened: str
+    data: str
+    labels: str
+    reference: str
+    notes: str = ""
+
+
+def _quoted(entry: dict, path: Path) -> dict:
+    """Refuse the values that YAML reads as numbers or dates, such as ``0.10``."""
+    unquoted = sorted(key for key, value in entry.items() if not isinstance(value, str))
+    if unquoted:
+        raise ValueError(f"quote the values of {unquoted} in {path}")
+    return entry
+
+
+def load_versions(path: str | Path) -> tuple[Version, list[Version]]:
+    """The current version and every version listed in ``path``."""
+    path = Path(path)
+    raw = yaml.safe_load(path.read_text())
+    current = _quoted({"current": raw["current"]}, path)["current"]
+    versions = [Version(**_quoted(entry, path)) for entry in raw["versions"]]
+    numbers = [version.number for version in versions]
+    if len(set(numbers)) != len(numbers):
+        raise ValueError(f"a version is listed twice in {path}: {numbers}")
+    if current not in numbers:
+        raise ValueError(f"the current version {current} is not listed in {path}")
+    return versions[numbers.index(current)], versions
+
+
+CURRENT, VERSIONS = load_versions(VERSIONS_FILE)

versions.yaml

@@ -0,0 +1,9 @@
+current: "0.1"
+versions:
+  - number: "0.1"
+    release: "v0.1.0"
+    opened: "2026-10-19"
+    data: "0f452b2fc84e544fb1a1fc5bd42017482e07b43c"
+    labels: "b5cd56fc5cec748fba5db6280477167a45d5cc1a"
+    reference: "6f3e0b3e9413591ffbf34fc51cf9f0a51c6ab399"
+    notes: "First board version: 70 tasks on bulk and single-cell RNAseq. Its scores are the reference for the later versions."