"""Mathematical Sight-Reading Framework (MSRF): a Gradio drill app. Learner reads a naked formula, answers in three parts, and a judge model (via the learner's own OpenRouter key) scores it against a hidden reference sight-read. Progress, key and model choice live in the browser (BrowserState); nothing is stored on the server. """ import json import os import tempfile import time import gradio as gr import bank import engine import judge DEFAULT_MODEL = os.environ.get("JUDGE_MODEL", "anthropic/claude-sonnet-4.5") DEFAULT_CHOICES = [ m.strip() for m in os.environ.get( "JUDGE_MODELS", "anthropic/claude-sonnet-4.5,anthropic/claude-haiku-4.5,google/gemini-2.5-pro,openai/gpt-5-mini", ).split(",") if m.strip() ] if DEFAULT_MODEL not in DEFAULT_CHOICES: DEFAULT_CHOICES.insert(0, DEFAULT_MODEL) ON_SPACE = bool(os.environ.get("SPACE_ID")) # BrowserState encrypts what it keeps in localStorage. Without a fixed secret Gradio # invents a new random one every time the server starts, so after a Space restarts or # sleeps the browser can no longer decrypt the saved key and progress and silently # loses them. The secret is sent to the browser to do the encrypting, so this is # obfuscation, not protection; the key is only as safe as your browser profile, as in # any localStorage client. Override with the MSRF_STATE_SECRET Space variable if wanted. STATE_SECRET = os.environ.get("MSRF_STATE_SECRET", "msrf-browser-state-v1") LATEX = [ {"left": "$$", "right": "$$", "display": True}, {"left": "$", "right": "$", "display": False}, {"left": "\\(", "right": "\\)", "display": False}, {"left": "\\[", "right": "\\]", "display": True}, ] INTRO = """\ Read the formula like sheet music: decode the symbols, say what the machinery does, then ground it. Write in LaTeX with `$...$` if you like. A judge model scores you on **Precision** (0-10), **Concept** (Superficial / Competent / Exemplary) and **Transfer** (A / B / C). """ KEY_NOTE = """\ **About your key.** It is stored only in this browser (localStorage). To call OpenRouter it passes through this Space's server in memory for the length of the request; it is not logged or saved. The source is public in the Space's *Files* tab, so you can check. Use a key with a spend limit. """ # ----------------------------------------------------------------- drill --- def _formula_md(f): return f"**{bank.TIER_NAMES[f['tier']]}**\n\n$$\n{f['latex']}\n$$" def _tier_md(p): n = len(p["history"]) return f"Your level: **{bank.TIER_NAMES[p['tier']]}** · drills done: {n}" def serve_next(progress, last_id=None): p = engine.normalize(progress) f = engine.choose_next(p, bank.BANK, exclude=last_id) return _formula_md(f), _tier_md(p), f["id"], 0, "", "", "", "", "" def hint(current, hints): if not current: return hints, gr.skip() level = min((hints or 0) + 1, 2) f = bank.BY_ID[current] lines = [f"**Hint 1 (types):** {f['hint_types']}"] if level >= 2: lines.append(f"**Hint 2 (mechanics):** {f['hint_mech']}") return level, "\n\n".join(lines) + f"\n\n*Each hint costs 0.1 of your composite score.*" def _result_md(f, r, comp, tier_before, tier_after, hints): out = [ f"### Scores\n\n| Precision | Concept | Transfer | Composite |\n|:-:|:-:|:-:|:-:|\n" f"| **{r['precision']}/10** | **{r['concept']}** | **{r['transfer']}** | {comp:.0%}" + (f" (−{hints * 10}% for hints)" if hints else "") + " |", f"**This was:** {f['name']}.", ] if tier_after > tier_before: out.append(f"**Level up** → {bank.TIER_NAMES[tier_after]}") elif tier_after < tier_before: out.append(f"**Stepping back** → {bank.TIER_NAMES[tier_after]}") out.append(f"#### Precision\n{r['precision_evidence']}") out.append(f"#### Concept\n{r['concept_evidence']}") dom = ", ".join(r["domains"]) if r["domains"] else "none credited" out.append(f"#### Transfer\nDomains credited: {dom}. \n{r['transfer_evidence']}") if r["missed"]: out.append("#### Delta: what was missed\n" + "\n".join(f"- {m}" for m in r["missed"])) if r["exemplary"]: out.append("#### Exemplary sight-read\n" + r["exemplary"]) return "\n\n".join(out) def evaluate(p1, p2, p3, current, hints, progress, key, model): if not current: return "Press **New formula** to get a drill first.", current, progress if len((p1 or "").strip() + (p2 or "").strip() + (p3 or "").strip()) < 20: return "Write a little more in the three parts before evaluating.", current, progress if not (key or "").strip(): return "Add your OpenRouter API key in **Settings** first.", current, progress f = bank.BY_ID[current] try: r = judge.call_judge(key.strip(), (model or DEFAULT_MODEL).strip(), f, p1, p2, p3) except judge.JudgeError as e: return f"**Judge error:** {e}\n\nNothing was recorded. Try again or pick another model.", current, progress p = engine.normalize(progress) tier_before = p["tier"] p = engine.record_attempt(p, f, r, hints or 0, now=int(time.time())) comp = p["history"][-1]["composite"] return _result_md(f, r, comp, tier_before, p["tier"], hints or 0), None, p # -------------------------------------------------------------- progress --- TAG_HEADERS = ["Notation family", "Attempts", "Mean precision", "Mean concept (0-2)", "Mean transfer (0-2)"] RECENT_HEADERS = ["Formula", "Tier", "Precision", "Concept", "Transfer", "Hints", "Composite"] def progress_views(progress): p = engine.normalize(progress) h = p["history"] if not h: return "No drills yet.", [], [], "" mean = sum(x["composite"] for x in h) / len(h) summary = f"Level **{p['tier']}** · {len(h)} drills · mean composite {mean:.0%}" recent = [ [bank.BY_ID[x["id"]]["name"] if x["id"] in bank.BY_ID else x["id"], x["tier"], x["precision"], x["concept"], x["transfer"], x["hints"], f"{x['composite']:.0%}"] for x in reversed(h[-15:]) ] due = engine.due_cards(p, bank.BANK) due_md = "**Due for review:** " + (", ".join(bank.BY_ID[c]["name"] for c in due) if due else "nothing yet") return summary, engine.stats_by_tag(p, bank.BANK), recent, due_md def export_progress(progress): path = os.path.join(tempfile.mkdtemp(), "msrf-progress.json") with open(path, "w") as fh: json.dump(engine.normalize(progress), fh, indent=1) return path def import_progress(file): if not file: return gr.skip(), "No file chosen." try: with open(file) as fh: raw = json.load(fh) except (OSError, ValueError): return gr.skip(), "That file isn't valid JSON." p = engine.normalize(raw) if not p["history"] and not p["cards"]: return gr.skip(), "No usable progress found in that file." return p, f"Imported {len(p['history'])} drills." def refresh_models(current_model): ids = judge.list_models() if not ids: return gr.update(), "Couldn't reach OpenRouter's model list. Type a model id directly instead." choices = ids if current_model in ids else [current_model] + ids return gr.update(choices=choices, value=current_model), f"{len(ids)} models loaded." def greet(profile: gr.OAuthProfile | None): return f"Signed in as **{profile.username}**" if profile else "" # -------------------------------------------------------------------- ui --- with gr.Blocks(title="Mathematical Sight-Reading") as demo: prog_state = gr.BrowserState(engine.new_progress(), storage_key="msrf_progress", secret=STATE_SECRET) key_state = gr.BrowserState("", storage_key="msrf_openrouter_key", secret=STATE_SECRET) model_state = gr.BrowserState(DEFAULT_MODEL, storage_key="msrf_judge_model", secret=STATE_SECRET) current = gr.State(None) hints = gr.State(0) with gr.Row(): gr.Markdown("# 🎼 Mathematical Sight-Reading") with gr.Column(scale=0, min_width=220): if ON_SPACE: # OAuth is only available on Spaces (locally it needs an HF token) gr.LoginButton(size="sm") greet_md = gr.Markdown() with gr.Tab("Drill"): gr.Markdown(INTRO) tier_md = gr.Markdown() formula_md = gr.Markdown(latex_delimiters=LATEX, elem_id="formula") with gr.Row(): next_btn = gr.Button("New formula", variant="secondary") hint_btn = gr.Button("Hint", variant="secondary") hint_md = gr.Markdown(latex_delimiters=LATEX) p1 = gr.Textbox(label="1. Formal sight-reading (types, inputs/outputs, scopes, conditions)", lines=4) p2 = gr.Textbox(label="2. Concept & mechanics (what is it doing? what happens at limits?)", lines=4) p3 = gr.Textbox(label="3. Application & metaphor (aim for two or more fields)", lines=4) eval_btn = gr.Button("Evaluate", variant="primary") result_md = gr.Markdown(latex_delimiters=LATEX) with gr.Tab("Progress"): summary_md = gr.Markdown() due_md = gr.Markdown() gr.Markdown("#### Weakest notation families first") tag_df = gr.Dataframe(headers=TAG_HEADERS, interactive=False) gr.Markdown("#### Recent drills") recent_df = gr.Dataframe(headers=RECENT_HEADERS, interactive=False) with gr.Row(): export_btn = gr.Button("Export progress") export_file = gr.File(label="Your progress file", interactive=False) import_btn = gr.UploadButton("Import progress", file_types=[".json"]) import_msg = gr.Markdown() with gr.Tab("Settings"): gr.Markdown(KEY_NOTE) key_box = gr.Textbox(label="OpenRouter API key", type="password", placeholder="sk-or-...") model_dd = gr.Dropdown( label="Judge model (OpenRouter id)", choices=DEFAULT_CHOICES, value=DEFAULT_MODEL, allow_custom_value=True, info="A stronger judge grades Tier 3-4 index work more reliably; a cheaper one is fine for Tier 1-2.", ) with gr.Row(): refresh_btn = gr.Button("Load current OpenRouter model list") models_msg = gr.Markdown() drill_out = [formula_md, tier_md, current, hints, hint_md, result_md, p1, p2, p3] views = [summary_md, tag_df, recent_df, due_md] def init(progress, key, model): p = engine.normalize(progress) return (key or "", model or DEFAULT_MODEL, p) + serve_next(p) + progress_views(p) demo.load(init, [prog_state, key_state, model_state], [key_box, model_dd, prog_state] + drill_out + views) if ON_SPACE: demo.load(greet, None, greet_md) next_btn.click(serve_next, [prog_state, current], drill_out) hint_btn.click(hint, [current, hints], [hints, hint_md]) eval_btn.click( evaluate, [p1, p2, p3, current, hints, prog_state, key_state, model_state], [result_md, current, prog_state] ).then(progress_views, prog_state, views) key_box.change(lambda k: k, key_box, key_state) model_dd.change(lambda m: m, model_dd, model_state) refresh_btn.click(refresh_models, model_dd, [model_dd, models_msg]) export_btn.click(export_progress, prog_state, export_file) import_btn.upload(import_progress, import_btn, [prog_state, import_msg]).then(progress_views, prog_state, views) if __name__ == "__main__": demo.launch(theme=gr.themes.Soft())