SoulFireMage's picture
Fix: stable BrowserState secret so key and progress survive Space restarts
6a520f8 verified
Raw History Blame Contribute Delete
11.4 kB
"""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())