Add Gradio app for PhySH discipline and concept classification

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+# Weights are pulled from the model repo at runtime — don't commit copies here.
+*.pt

DEPLOY.md

@@ -0,0 +1,58 @@
+# Deploying this to a Space
+
+## 1. Create the Space
+
+On huggingface.co → **New** → **Space**:
+
+- Owner `LukeFP`, name `physh-topic-classifier`
+- SDK **Gradio**, hardware **CPU basic** (free) — EmbeddingGemma-300m runs on
+  CPU in roughly a second per abstract, so a GPU buys little here
+- Visibility public or private, your call
+
+## 2. Add the token secret
+
+`google/embeddinggemma-300m` is gated. Accept the Gemma license while signed in,
+create a **read** token, then in the Space: Settings → *Variables and secrets* →
+**New secret**, name `HF_TOKEN`, value the token.
+
+If the model repo is private too, the same token covers it.
+
+## 3. Push
+
+```bash
+cd /Users/firstprinciplesextralaptop2/code/2026.7/physh-topic-classifier-space
+
+git init
+git remote add origin https://huggingface.co/spaces/LukeFP/physh-topic-classifier
+git add app.py requirements.txt README.md .gitignore DEPLOY.md test_local.py
+git commit -m "Gradio app for PhySH discipline + concept classification"
+git push origin main
+```
+
+If the Space was created with a README already, `git pull --rebase origin main`
+first — the frontmatter in this README is the one you want to keep, since it
+carries the `sdk_version` and `app_file` settings.
+
+The build takes a few minutes, mostly `pip install torch`.
+
+## 4. Check it
+
+Open the Space and run one of the built-in examples. Things to look at:
+
+- **Predictions look like noise / nothing clears the threshold.** Almost
+  certainly the embedding prompt. Open *Advanced* and try the other two formats;
+  the one matching your training pipeline will give confident, coherent labels.
+  Once you know which, set `DEFAULT_PROMPT` at the top of `app.py`.
+- **Error mentioning gated repo or 401.** `HF_TOKEN` is missing, wrong, or the
+  account behind it hasn't accepted the Gemma license.
+- **First request is slow.** Expected — EmbeddingGemma loads lazily on first use
+  so the Space boots fast. It's cached after that.
+
+## Local smoke test
+
+Runs the real checkpoints through the full chain with a stubbed embedder, so it
+needs no token and no download:
+
+```bash
+python test_local.py
+```

README.md

@@ -8,6 +8,81 @@ sdk_version: 6.28.0
 python_version: '3.12'
 app_file: app.py
 pinned: false
+license: apache-2.0
+models:
+  - LukeFP/physh_topic_supervised_classifier
+  - google/embeddinggemma-300m
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PhySH Topic Classifier
+
+Paste a physics title and abstract; get back its [PhySH](https://physh.org)
+**disciplines** and **top-level research-area concepts**.
+
+## How it works
+
+```
+text ──EmbeddingGemma-300m──> 768-d vector
+          │
+          ├──> discipline head   768 → 1024 → 512 → 18    sigmoid
+          │                                    │
+          └──> concept head  [768 + 18] → 1024 → 512 → 186 sigmoid
+                                   ▲
+                       discipline probabilities
+```
+
+Both heads are multi-label MLPs with ReLU and dropout 0.3, trained on
+EmbeddingGemma vectors. The concept head is *conditioned* on the discipline
+head's output: its 786-dimensional input is the text embedding concatenated with
+the 18 discipline probabilities (the checkpoint records `use_logits: False`, so
+probabilities rather than logits are what it expects).
+
+Weights live in
+[`LukeFP/physh_topic_supervised_classifier`](https://huggingface.co/LukeFP/physh_topic_supervised_classifier)
+and are downloaded at startup, so retraining only requires a push to that repo —
+no change here.
+
+| Head | micro-F1 | macro-F1 | avg labels/sample |
+|---|---|---|---|
+| Discipline (18) | 0.799 | 0.683 | 1.41 |
+| Concept (186) | 0.641 | 0.423 | 2.12 |
+
+## Setup
+
+`google/embeddinggemma-300m` is a gated repo. Accept the Gemma license on the
+model page, then add a read token as a Space secret named `HF_TOKEN`
+(Settings → Variables and secrets). Without it the Space boots but the first
+classification fails.
+
+### Prompt format
+
+EmbeddingGemma prepends a task-specific prefix, and the prefix used here must
+match the one used to build the training embeddings — a mismatch degrades
+accuracy quietly instead of erroring. The default is the document prompt
+(`title: none | text: …`); the Advanced panel lets you switch and compare.
+
+## Running locally
+
+```bash
+pip install -r requirements.txt
+export HF_TOKEN=hf_...
+python app.py
+```
+
+Set `PHYSH_WEIGHTS_DIR=/path/to/physh_topic_supervised_classifier` to load the
+`.pt` files from a local clone instead of the Hub.
+
+## API
+
+Gradio exposes the Space as an API, which is the practical route for batch
+labelling:
+
+```python
+from gradio_client import Client
+
+client = Client("LukeFP/physh-topic-classifier")
+disciplines, concepts, summary = client.predict(
+    "Title and abstract…", 0.5, "document — title: none | text: {}", 8,
+    api_name="/classify",
+)
+```

app.py

@@ -0,0 +1,233 @@
+"""
+PhySH topic classifier — Gradio Space.
+
+Pipeline:  text ──EmbeddingGemma-300m──> 768-d vector
+                      │
+                      ├──> discipline head (768 → 1024 → 512 → 18), sigmoid
+                      │
+                      └──> concept head ([768 + 18] → 1024 → 512 → 186), sigmoid
+                           conditioned on the discipline *probabilities*
+                           (the checkpoint records use_logits = False)
+
+Both heads are multi-label: each output is an independent sigmoid, so a text can
+carry several disciplines and several concepts.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+
+import gradio as gr
+import torch
+import torch.nn as nn
+from huggingface_hub import hf_hub_download
+
+# --------------------------------------------------------------------------- #
+# Config
+# --------------------------------------------------------------------------- #
+
+MODEL_REPO = "LukeFP/physh_topic_supervised_classifier"
+DISCIPLINE_CKPT = "discipline_classifier_gemma_20260130_140842.pt"
+CONCEPT_CKPT = "concept_conditioned_gemma_20260130_140842.pt"
+EMBED_MODEL = "google/embeddinggemma-300m"
+
+# google/embeddinggemma-300m is a gated repo: set HF_TOKEN as a Space secret,
+# using a token from an account that has accepted the Gemma license.
+HF_TOKEN = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+
+# Set to a local directory to load the .pt files from disk instead of the Hub.
+LOCAL_WEIGHTS_DIR = os.environ.get("PHYSH_WEIGHTS_DIR")
+
+# EmbeddingGemma expects a task-specific prefix, and the prefix used at inference
+# must match the one used to build the training embeddings — a mismatch degrades
+# accuracy silently rather than erroring. Pick the one your training script used.
+PROMPT_TEMPLATES = {
+    "document — title: none | text: {}": "title: none | text: {}",
+    "classification — task: classification | query: {}": "task: classification | query: {}",
+    "none — raw text": "{}",
+}
+DEFAULT_PROMPT = "document — title: none | text: {}"
+
+# --------------------------------------------------------------------------- #
+# Model
+# --------------------------------------------------------------------------- #
+
+
+class MLPClassifier(nn.Module):
+    """Linear/ReLU/Dropout stack. Layer indices line up with the checkpoints'
+    `network.0`, `network.3`, `network.6` keys."""
+
+    def __init__(self, input_dim: int, hidden_layers: list[int], output_dim: int, dropout: float):
+        super().__init__()
+        layers: list[nn.Module] = []
+        prev = input_dim
+        for width in hidden_layers:
+            layers += [nn.Linear(prev, width), nn.ReLU(), nn.Dropout(dropout)]
+            prev = width
+        layers.append(nn.Linear(prev, output_dim))
+        self.network = nn.Sequential(*layers)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.network(x)
+
+
+def _weights_path(filename: str) -> str:
+    if LOCAL_WEIGHTS_DIR:
+        return os.path.join(LOCAL_WEIGHTS_DIR, filename)
+    return hf_hub_download(MODEL_REPO, filename, token=HF_TOKEN)
+
+
+def load_head(filename: str) -> tuple[MLPClassifier, dict]:
+    ckpt = torch.load(_weights_path(filename), map_location="cpu", weights_only=False)
+    cfg = ckpt["model_config"]
+    # The discipline head records `input_dim`; the concept head records the two
+    # halves of its input separately.
+    input_dim = cfg.get("input_dim") or cfg["embedding_dim"] + cfg["discipline_dim"]
+    model = MLPClassifier(input_dim, cfg["hidden_layers"], cfg["output_dim"], cfg["dropout"])
+    model.load_state_dict(ckpt["model_state_dict"])
+    model.eval()
+    return model, ckpt
+
+
+DISCIPLINE_MODEL, DISCIPLINE_CKPT_DATA = load_head(DISCIPLINE_CKPT)
+CONCEPT_MODEL, CONCEPT_CKPT_DATA = load_head(CONCEPT_CKPT)
+
+DISCIPLINE_LABELS = [d["label"] for d in DISCIPLINE_CKPT_DATA["class_labels"]]
+CONCEPT_LABELS = [c["label"] for c in CONCEPT_CKPT_DATA["class_labels"]]
+
+# The concept head was conditioned on the discipline vector in a specific order.
+# Remap if the two checkpoints ever drift apart.
+_CONDITION_ORDER = [d["discipline_id"] for d in CONCEPT_CKPT_DATA["discipline_labels"]]
+_HEAD_ORDER = [d["discipline_id"] for d in DISCIPLINE_CKPT_DATA["class_labels"]]
+_REMAP = torch.tensor([_HEAD_ORDER.index(i) for i in _CONDITION_ORDER], dtype=torch.long)
+
+
+@functools.lru_cache(maxsize=1)
+def get_embedder():
+    """Loaded on first request rather than at import, so the Space boots quickly
+    and a missing token surfaces as a readable error instead of a crashed app."""
+    from sentence_transformers import SentenceTransformer
+
+    return SentenceTransformer(EMBED_MODEL, token=HF_TOKEN)
+
+
+# --------------------------------------------------------------------------- #
+# Inference
+# --------------------------------------------------------------------------- #
+
+
+@torch.inference_mode()
+def classify(text: str, threshold: float, prompt_choice: str, top_k: int):
+    text = (text or "").strip()
+    if not text:
+        return {}, {}, "Paste some text — a title and abstract work best."
+
+    prompt = PROMPT_TEMPLATES.get(prompt_choice, PROMPT_TEMPLATES[DEFAULT_PROMPT])
+    # prompt="" stops sentence-transformers from also applying the model's own
+    # default prefix on top of the one built here.
+    vector = get_embedder().encode(prompt.format(text), prompt="", convert_to_numpy=True)
+    embedding = torch.as_tensor(vector, dtype=torch.float32).unsqueeze(0)
+
+    discipline_probs = torch.sigmoid(DISCIPLINE_MODEL(embedding))[0]
+    conditioned = torch.cat([embedding, discipline_probs[_REMAP].unsqueeze(0)], dim=1)
+    concept_probs = torch.sigmoid(CONCEPT_MODEL(conditioned))[0]
+
+    disciplines = {DISCIPLINE_LABELS[i]: float(p) for i, p in enumerate(discipline_probs)}
+    concepts = {CONCEPT_LABELS[i]: float(p) for i, p in enumerate(concept_probs)}
+
+    summary = _summarize(disciplines, concepts, threshold)
+    return (
+        dict(sorted(disciplines.items(), key=lambda kv: -kv[1])[:top_k]),
+        dict(sorted(concepts.items(), key=lambda kv: -kv[1])[:top_k]),
+        summary,
+    )
+
+
+def _summarize(disciplines: dict, concepts: dict, threshold: float) -> str:
+    def above(scores):
+        hits = sorted((kv for kv in scores.items() if kv[1] >= threshold), key=lambda kv: -kv[1])
+        return [f"**{name}** ({score:.2f})" for name, score in hits]
+
+    d_hits, c_hits = above(disciplines), above(concepts)
+    lines = [f"### Above threshold ({threshold:.2f})", ""]
+    lines.append("**Disciplines** — " + (", ".join(d_hits) if d_hits else "_none_"))
+    lines.append("")
+    lines.append("**Concepts** — " + (", ".join(c_hits) if c_hits else "_none_"))
+    if not d_hits and not c_hits:
+        lines += ["", "_Nothing cleared the threshold. Lower it, or check that the "
+                  "prompt format under Advanced matches your training setup._"]
+    return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# UI
+# --------------------------------------------------------------------------- #
+
+EXAMPLES = [
+    "We report the observation of a superconducting dome in magic-angle twisted "
+    "bilayer graphene. Transport measurements below 1.7 K reveal a zero-resistance "
+    "state whose critical temperature is tuned continuously by electrostatic gating, "
+    "and the phase diagram closely tracks the filling of the flat moire bands.",
+    "We present a measurement of the cosmic microwave background lensing power "
+    "spectrum from four seasons of data. The reconstruction achieves a 40-sigma "
+    "detection and, combined with baryon acoustic oscillation data, constrains the "
+    "sum of the neutrino masses.",
+    "A variational quantum eigensolver is used to compute ground-state energies of "
+    "small molecular Hamiltonians on a superconducting processor. We introduce an "
+    "error-mitigation scheme based on zero-noise extrapolation and show that it "
+    "recovers chemical accuracy for LiH.",
+]
+
+with gr.Blocks(title="PhySH Topic Classifier") as demo:
+    gr.Markdown(
+        "# PhySH Topic Classifier\n"
+        "Paste a physics title and abstract to get its **PhySH disciplines** and "
+        "**top-level research-area concepts**. Both heads are multi-label, so several "
+        "labels can fire at once.\n\n"
+        f"Heads: [`{MODEL_REPO}`](https://huggingface.co/{MODEL_REPO}) · "
+        f"Embeddings: [`{EMBED_MODEL}`](https://huggingface.co/{EMBED_MODEL})"
+    )
+
+    with gr.Row():
+        with gr.Column(scale=3):
+            text_input = gr.Textbox(
+                label="Title + abstract",
+                placeholder="Paste a paper title and abstract…",
+                lines=12,
+            )
+            with gr.Row():
+                submit = gr.Button("Classify", variant="primary")
+                clear = gr.ClearButton(text_input, value="Clear")
+            gr.Examples(examples=[[e] for e in EXAMPLES], inputs=[text_input], label="Try one")
+
+        with gr.Column(scale=2):
+            discipline_out = gr.Label(label="Disciplines (18)", num_top_classes=8)
+            concept_out = gr.Label(label="Concepts (186)", num_top_classes=8)
+
+    summary_out = gr.Markdown()
+
+    with gr.Accordion("Advanced", open=False):
+        threshold = gr.Slider(0.05, 0.95, value=0.5, step=0.05, label="Decision threshold")
+        top_k = gr.Slider(3, 20, value=8, step=1, label="How many labels to show")
+        prompt_choice = gr.Radio(
+            choices=list(PROMPT_TEMPLATES),
+            value=DEFAULT_PROMPT,
+            label="EmbeddingGemma prompt format",
+            info="Must match the prefix used to build the training embeddings. "
+                 "If predictions look like noise, try the other options.",
+        )
+        gr.Markdown(
+            f"Validation at training time — disciplines: micro-F1 "
+            f"{DISCIPLINE_CKPT_DATA['metrics']['micro_f1']:.3f}, concepts: micro-F1 "
+            f"{CONCEPT_CKPT_DATA['metrics']['micro_f1']:.3f}."
+        )
+
+    inputs = [text_input, threshold, prompt_choice, top_k]
+    outputs = [discipline_out, concept_out, summary_out]
+    submit.click(classify, inputs=inputs, outputs=outputs, api_name="classify")
+    text_input.submit(classify, inputs=inputs, outputs=outputs)
+
+if __name__ == "__main__":
+    # Gradio 6 takes the theme on launch(), not on the Blocks constructor.
+    demo.launch(theme=gr.themes.Soft())

requirements.txt

@@ -0,0 +1,13 @@
+gradio==6.28.0
+
+# EmbeddingGemma needs sentence-transformers >= 5.0 / transformers >= 4.56,
+# and does not support float16 activations (float32 on CPU is the default here).
+sentence-transformers>=5.0
+transformers>=4.56
+huggingface_hub>=0.34
+
+# PyPI's torch wheel bundles CUDA (~3 GB) and is wasted on a CPU Space. If build
+# times or disk become a problem, replace the line below with these two:
+#   --extra-index-url https://download.pytorch.org/whl/cpu
+#   torch>=2.4
+torch>=2.4

test_local.py

@@ -0,0 +1,42 @@
+"""Smoke test: loads the real checkpoints, stubs out EmbeddingGemma, and runs the
+full chain. Run with PHYSH_WEIGHTS_DIR pointing at the cloned model repo."""
+import os, sys, numpy as np, torch
+
+os.environ.setdefault(
+    "PHYSH_WEIGHTS_DIR",
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "physh_topic_supervised_classifier"),
+)
+import app
+
+class FakeEmbedder:
+    def encode(self, text, prompt=None, convert_to_numpy=True):
+        rng = np.random.default_rng(abs(hash(text)) % (2**32))
+        v = rng.normal(size=768).astype("float32")
+        return v / np.linalg.norm(v)  # EmbeddingGemma returns L2-normalised vectors
+
+app.get_embedder.cache_clear()
+app.get_embedder = lambda: FakeEmbedder()
+
+print("disciplines:", len(app.DISCIPLINE_LABELS), "concepts:", len(app.CONCEPT_LABELS))
+print("remap is identity:", torch.equal(app._REMAP, torch.arange(18)))
+print("discipline net:", app.DISCIPLINE_MODEL.network)
+print("concept  in_features:", app.CONCEPT_MODEL.network[0].in_features)
+
+d, c, summary = app.classify(app.EXAMPLES[0], 0.5, app.DEFAULT_PROMPT, 8)
+assert len(d) == 8 and len(c) == 8, (len(d), len(c))
+assert all(0.0 <= v <= 1.0 for v in {**d, **c}.values())
+print("\ntop disciplines:", [f"{k} {v:.3f}" for k, v in d.items()][:4])
+print("top concepts:   ", [f"{k} {v:.3f}" for k, v in c.items()][:4])
+print("\n--- summary ---\n" + summary)
+
+# determinism (dropout must be off) and empty input
+d2, _, _ = app.classify(app.EXAMPLES[0], 0.5, app.DEFAULT_PROMPT, 8)
+assert d == d2, "eval() mode not applied — outputs are not deterministic"
+empty = app.classify("   ", 0.5, app.DEFAULT_PROMPT, 8)
+assert empty[0] == {} and "Paste" in empty[2]
+for p in app.PROMPT_TEMPLATES:
+    app.classify("test abstract", 0.5, p, 5)
+print("\nOK: deterministic, empty input handled, all 3 prompt formats run.")
+
+app.demo  # Blocks built at import; confirm the UI graph is constructed
+print("gradio Blocks built OK")