Download app/math_skills.py from wzender/mathly: direct link, hf CLI and curl.
- Browser
- Download file 13.9 kB
-
https://huggingface.co/spaces/wzender/mathly/resolve/main/app/math_skills.py
- Command line
-
hf download hf://spaces/wzender/mathly/app/math_skills.py
-
curl -L -o math_skills.py https://huggingface.co/spaces/wzender/mathly/resolve/main/app/math_skills.py
13.9 kB
| """The 9th-grade algebra skill graph for the math path (`math_algebra9.json`). | |
| Each skill names its prerequisites and either one `sample` question or a list of multiple-choice `questions`. | |
| Choice samples identify mistakes; open-ended samples name their type and revision and accept a photographed answer. | |
| A mistake sends the student back to the skill it comes from (`back`), or keeps them on the same skill (`null`). | |
| The units follow the Ministry of Education's 9th-grade teaching schedule for 2026/27 (`docs/prisa_9A.md`). | |
| A unit has at most six skills: a longer one is split in two (讟讻谞讬拽讛 讗诇讙讘专讬转 1 and 2), and a split-off unit names | |
| the one it came from (`from`) so classes that chose it keep their content. `month` is when the schedule teaches a skill. | |
| The questions are written for the app, and every skill, link and mistake still needs a teacher's review. | |
| `problems` is run by the tests and on loading: a broken graph is refused before a student meets it. | |
| A skill may have a worked example (`example`: a question of its own, `steps` of {do, why}, and the `answer`) that the | |
| student can open when stuck. The examples are written in advance and reviewed by a teacher: students never call the AI. | |
| A unit may end with a summarizing quiz (`quiz`): open-ended questions answered on paper and photographed, a time limit | |
| in minutes, and points per question that add up to 100. Its questions are graded only after the quiz is handed in. | |
| """ | |
| from __future__ import annotations | |
| import json | |
| import re | |
| import hashlib | |
| import copy | |
| from functools import cache | |
| from pathlib import Path | |
| GRAPH = Path(__file__).with_name("math_algebra9.json") | |
| def question_version(sample: dict) -> str: | |
| """Bind attempts to the complete prompt, including its diagram and revision.""" | |
| return hashlib.sha256(json.dumps(sample, ensure_ascii=False, sort_keys=True, | |
| separators=(",", ":")).encode()).hexdigest() | |
| def questions(skill: dict) -> list[dict]: | |
| """A skill's questions: its list of questions, or its one sample.""" | |
| return skill["questions"] if "questions" in skill else [skill["sample"]] | |
| FIGURE_POINT = re.compile(r"([A-Za-z_][\w']*)=(-?[\d.]+),(-?[\d.]+)(?:@(n|s|e|w|ne|nw|se|sw))?") | |
| FIGURE_NAMES = {"poly": None, "line": 2, "dash": 2, "dot": None, "len": 2, "lenx": 2, "ang": 3, "ang2": 3, "ang3": 3, | |
| "right": 3, "tick": 2, "par": 2} # how many point names an operation starts with (None: all of them) | |
| def figure_problems(where: str, figure) -> list[str]: | |
| """A figure (drawn by `figure` in static/math.js) may only name points it places and operations it knows.""" | |
| if not isinstance(figure, str) or not figure.strip(): | |
| return [f"{where}: figure must be text"] | |
| points, out = set(), [] | |
| statements = [s.strip() for s in figure.split(";") if s.strip()] | |
| for st in statements: | |
| if m := FIGURE_POINT.fullmatch(st): | |
| points.add(m[1]) | |
| for st in statements: | |
| if FIGURE_POINT.fullmatch(st) or st == "grid": | |
| continue | |
| op, *args = st.split() | |
| if op == "note": | |
| if not args: | |
| out.append(f"{where}: figure note needs words") | |
| continue | |
| if op == "text": | |
| if not args or not re.fullmatch(r"-?[\d.]+,-?[\d.]+", args[0]) or len(args) < 2: | |
| out.append(f"{where}: figure text needs x,y and words: {st}") | |
| continue | |
| if op not in FIGURE_NAMES: | |
| out.append(f"{where}: unknown figure operation {op}") | |
| continue | |
| names = args if FIGURE_NAMES[op] is None else args[:FIGURE_NAMES[op]] | |
| if len(names) < (FIGURE_NAMES[op] or 1): | |
| out.append(f"{where}: figure {op} needs more points: {st}") | |
| out += [f"{where}: figure names unknown point {n}" for n in names if n not in points] | |
| if op in ("tick", "par") and len(args) > 2 and not args[2].isdigit(): | |
| out.append(f"{where}: figure {op} count must be a number: {st}") | |
| if not points: | |
| out.append(f"{where}: figure has no points") | |
| return out | |
| def sample_problems(where: str, sid: str, sample: dict, listed: bool, mistakes: dict, below: dict) -> list[str]: | |
| if "figure" in sample and (bad := figure_problems(where, sample["figure"])): | |
| return bad | |
| kind = sample.get("type", "multiple-choice") | |
| if kind not in ("open-ended", "multiple-choice"): | |
| return [f"{where}: unknown question type {kind}"] | |
| if kind == "open-ended": | |
| if listed: | |
| return [f"{where}: a question list holds multiple-choice questions only"] | |
| out = [] | |
| if "choices" in sample: | |
| out.append(f"{where}: open-ended questions cannot have choices") | |
| if not isinstance(sample.get("question"), str) or not sample["question"].strip(): | |
| out.append(f"{where}: question text is required") | |
| if type(sample.get("version")) is not int or sample["version"] < 1: | |
| out.append(f"{where}: positive question version is required") | |
| return out | |
| out = [] | |
| choices = sample.get("choices", []) | |
| if sum(bool(c.get("correct")) for c in choices) != 1: | |
| out.append(f"{where}: needs exactly one correct choice") | |
| if len({c["text"] for c in choices}) != len(choices): | |
| out.append(f"{where}: two choices read the same") | |
| for c in choices: | |
| m = c.get("mistake") | |
| if c.get("correct"): | |
| continue | |
| if m not in mistakes: | |
| out.append(f"{where}: unknown mistake {m}") | |
| elif (back := mistakes[m]["back"]) and back != sid and back not in below[sid]: | |
| out.append(f"{where}: mistake {m} sends back to {back}, which is not before it") | |
| return out | |
| def example_problems(skill: dict) -> list[str]: | |
| """A skill's worked example, if it has one: a question of its own solved in steps (what to do, and why), and the | |
| answer. It must not be one of the skill's practice questions, or it would hand the student that question's answer.""" | |
| example = skill.get("example") | |
| if example is None: | |
| return [] | |
| where = f"{skill['id']} example" | |
| if not isinstance(example, dict): | |
| return [f"{where}: must be an object"] | |
| text = lambda value: isinstance(value, str) and bool(value.strip()) | |
| out = [] | |
| if not text(example.get("question")): | |
| out.append(f"{where}: question text is required") | |
| if not text(example.get("answer")): | |
| out.append(f"{where}: an answer is required") | |
| steps = example.get("steps") | |
| if not isinstance(steps, list) or not steps: | |
| out.append(f"{where}: needs at least one step") | |
| else: | |
| out += [f"{where} step {n}: needs what to do (do) and why (why)" for n, step in enumerate(steps, 1) | |
| if not isinstance(step, dict) or not text(step.get("do")) or not text(step.get("why"))] | |
| squash = lambda value: " ".join(str(value).split()) | |
| if text(example.get("question")) and squash(example["question"]) in {squash(q.get("question", "")) for q in questions(skill)}: | |
| out.append(f"{where}: repeats one of the skill's practice questions") | |
| return out | |
| def skills_without_example(graph: dict) -> list[str]: | |
| """The skills with multiple-choice questions that have no worked example yet (the coverage still to write).""" | |
| return [s["id"] for s in graph["skills"] | |
| if "example" not in s and all(q.get("type", "multiple-choice") == "multiple-choice" for q in questions(s))] | |
| MAX_QUIZ_SKILLS = 3 | |
| def quiz_problems(unit: dict, unit_skills: set[str] | None = None) -> list[str]: | |
| """A unit's summarizing quiz: a time limit, and open-ended questions whose points add up to 100, each naming the | |
| 1 to 3 skills of its unit it tests (`unit_skills`: the unit's skill ids; None skips that check).""" | |
| quiz, where = unit["quiz"], f"{unit['id']} quiz" | |
| if not isinstance(quiz, dict): | |
| return [f"{where}: must be an object"] | |
| out = [] | |
| if type(quiz.get("minutes")) is not int or not 5 <= quiz["minutes"] <= 120: | |
| out.append(f"{where}: minutes must be a whole number from 5 to 120") | |
| qs = quiz.get("questions") | |
| if not isinstance(qs, list) or not qs: | |
| return out + [f"{where}: needs questions"] | |
| for n, q in enumerate(qs, 1): | |
| at = f"{where} question {n}" | |
| if not isinstance(q, dict) or not isinstance(q.get("question"), str) or not q["question"].strip(): | |
| out.append(f"{at}: question text is required") | |
| continue | |
| if type(q.get("points")) is not int or q["points"] <= 0: | |
| out.append(f"{at}: points must be a positive whole number") | |
| if "choices" in q: | |
| out.append(f"{at}: a quiz question is open-ended") | |
| if "figure" in q: | |
| out += figure_problems(at, q["figure"]) | |
| if unit_skills is not None: | |
| tags = q.get("skills") | |
| if not isinstance(tags, list) or not 1 <= len(tags) <= MAX_QUIZ_SKILLS or len(set(tags)) != len(tags): | |
| out.append(f"{at}: skills must name 1 to {MAX_QUIZ_SKILLS} different skills") | |
| else: | |
| out += [f"{at}: skill {t} is not a skill of unit {unit['id']}" for t in tags if t not in unit_skills] | |
| if not out and sum(q["points"] for q in qs) != 100: | |
| out.append(f"{where}: points add up to {sum(q['points'] for q in qs)}, not 100") | |
| return out | |
| def quiz_snapshot(unit: dict, index: int) -> dict: | |
| """What an answer to quiz question `index` is graded against, and what its version is computed from.""" | |
| # the skill tags say what a question tests, not what it asks: changing them must not make open sittings stale | |
| q = {k: v for k, v in unit["quiz"]["questions"][index].items() if k != "skills"} | |
| return {"name": f"讘讜讞谉 诪住讻诐: {unit['name']} 路 砖讗诇讛 {index + 1}", **q, "type": "open-ended"} | |
| def problems(graph: dict) -> list[str]: | |
| """What is wrong with a graph: unknown units, skills or mistakes, a cycle, a link implied by another, | |
| a question without exactly one right answer, or a mistake that sends the student to a skill that is not before it.""" | |
| units = {u["id"] for u in graph["units"]} | |
| skills = {s["id"]: s for s in graph["skills"]} | |
| mistakes = graph["mistakes"] | |
| out = [f"{u['id']}: subject is required" for u in graph["units"] if not str(u.get("subject") or "").strip()] | |
| out += [p for u in graph["units"] if "quiz" in u | |
| for p in quiz_problems(u, {s["id"] for s in graph["skills"] if s.get("unit") == u["id"]})] | |
| out += [f"{s['id']}: unknown unit {s['unit']}" for s in skills.values() if s["unit"] not in units] | |
| out += [f"{s['id']}: unknown prerequisite {p}" for s in skills.values() for p in s["prereqs"] if p not in skills] | |
| if out: | |
| return out | |
| below: dict[str, set[str]] = {} | |
| def ancestors(sid: str, path: tuple[str, ...] = ()) -> set[str]: | |
| if sid in path: | |
| raise ValueError(" -> ".join(path + (sid,))) | |
| if sid not in below: | |
| below[sid] = {a for p in skills[sid]["prereqs"] for a in (p, *ancestors(p, path + (sid,)))} | |
| return below[sid] | |
| try: | |
| for sid in skills: | |
| ancestors(sid) | |
| except ValueError as cycle: | |
| return [f"cycle: {cycle}"] | |
| for s in skills.values(): | |
| out += [f"{s['id']}: {p} is implied by {q}" for p in s["prereqs"] for q in s["prereqs"] if p != q and p in below[q]] | |
| if ("questions" in s) == ("sample" in s): | |
| out.append(f"{s['id']}: needs a sample or a list of questions, not both") | |
| continue | |
| listed = "questions" in s | |
| if listed and (not isinstance(s["questions"], list) or not s["questions"]): | |
| out.append(f"{s['id']}: the question list is empty") | |
| continue | |
| for n, sample in enumerate(questions(s), 1): | |
| out += sample_problems(f"{s['id']} question {n}" if listed else s["id"], s["id"], sample, listed, | |
| mistakes, below) | |
| out += example_problems(s) | |
| out += [f"mistake {k}: unknown skill {m['back']}" for k, m in mistakes.items() if m["back"] and m["back"] not in skills] | |
| return out | |
| def algebra9() -> dict: | |
| graph = json.loads(GRAPH.read_text(encoding="utf-8")) | |
| if found := problems(graph): | |
| raise ValueError(f"{GRAPH.name}: " + "; ".join(found)) | |
| return graph | |
| def algebra9_unit(unit_id: str) -> dict: | |
| return next(u for u in algebra9()["units"] if u["id"] == unit_id) | |
| def practice_graph(answer_scans_enabled: bool, open_ended_locked: bool = False) -> dict: | |
| """Keep practice usable during a scan rollout or rollback. | |
| Public responses never expose fallback choices for an open-ended question. | |
| The original choice sample is served when authenticated storage is disabled. | |
| A locked open-ended question is shown but cannot be answered, so it is never graded. | |
| """ | |
| graph = copy.deepcopy(algebra9()) | |
| subject = {unit["id"]: unit["subject"] for unit in graph["units"]} | |
| for unit in graph["units"]: | |
| if "quiz" in unit: # photographed and graded: only with answer storage and open-ended grading on | |
| unit["quiz"]["locked"] = not answer_scans_enabled or open_ended_locked | |
| for i, q in enumerate(unit["quiz"]["questions"]): | |
| q["question_version"] = question_version(quiz_snapshot(algebra9_unit(unit["id"]), i)) | |
| for skill in graph["skills"]: | |
| skill["subject"] = subject[skill["unit"]] # a subunit belongs to its unit's subject | |
| fallback = skill.pop("fallback_sample", None) | |
| if not answer_scans_enabled and fallback is not None: | |
| skill["sample"] = fallback | |
| if "sample" in skill: # identifies an open-ended question's uploaded answers | |
| skill["question_version"] = question_version(skill["sample"]) | |
| if open_ended_locked and skill["sample"].get("type") == "open-ended": | |
| skill["locked"] = True | |
| return graph | |