mathly / app /math_skills.py
3v324v23's picture
Add tests for student task list and quiz modes functionality
0ba5932
Raw History Blame Contribute Delete
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
@cache
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