Design patterns: Context, EvaluationParameters and ParsedQuantity dataclasses, graph helpers

[m-messer]

Problem

This is the design-patterns follow-up deferred from #281, and it's stacked on that PR. After the restructure, the contexts were still plain dicts of functions. The evaluation parameters were a FrozenValuesDictionary read by string keys, and parsed quantities were a QuantityDict. Because of this, neither mypy nor a reader could see which fields exist. The graph builders also repeated the same setup code, and parse_reserved_expressions repeated its learner/task error handling three times.

Changes

Behaviour is unchanged. Feedback strings, tags, graph shapes and raised exceptions are all the same as before.

• outcome_graph helper (app/context/graph_helpers.py): creates a graph with its end node and evaluation node. It is used in the generic, WHERE and physical-quantity order graphs. In order.py the graph now gets its real label instead of None.
• check_equality (app/context/symbolic/comparison.py): the simplification retries are now straight-line code with early returns.
• Context dataclass (app/context/base.py): a frozen dataclass replaces the context dicts. select_context(params) replaces determine_context. The context is passed explicitly instead of being deep-copied into parameters["context"].
• ParsedQuantity dataclass (app/context/physical_quantity/parsing.py): replaces QuantityDict.
• EvaluationParameters dataclass (app/evaluation_parameters.py): replaces FrozenValuesDictionary, and app/frozen_dict.py is removed. GraphTemplate and Context.feedback_procedure_generator now take it. Parameters stays for the raw request parameters. A criterion given twice still fails with Cannot parse criteria: …, now through an explicit check.
• _report helper (app/evaluation.py): the learner → feedback / task → raise choice in parse_reserved_expressions is now in one helper. A task parse error still raises without a tag, as before.
• Rename: parameters_dict → parameters in the symbolic context.
• Docs: the Context and evaluation-flow sections of app/docs/dev.md are updated.

Checklist

• Tests added/updated (n/a, no behaviour change)
• Docs updated (app/docs.md) if user-facing behaviour changed (n/a, no behaviour change; app/docs/dev.md updated)

Testing

• pytest app/tests: 1217 passed, 2 skipped, 1 failed. The failure is the known test_radians_to_frequency.
• mypy app: no issues.
• After each commit, evaluation_function(..., include_test_data=True) output for 15 symbolic and physical-quantity cases was byte-identical to the output before it (with PYTHONHASHSEED=0). For the _report commit, the raised exceptions (args, cause, suppressed context) for bad responses and answers were also compared and matched.

🤖 Generated with Claude Code