[m-messer]

Problem

The static process graphs in app/docs/process_graphs/ show which functions evaluation_function calls, but not the order of the calls, the values passed between them, or how each criterion becomes a criteria graph and is evaluated. That makes the evaluation hard to follow for anyone new to the code.

Changes

• scripts/generate_process_animation.py (new): records the same examples as the static figures and writes a self-contained page to build/process_animation.html. The build/ folder is git-ignored. Run it with python -m scripts.generate_process_animation.
  • The calls graph grows in call order. It has play, step and scrub controls, a call depth from 1 to 5, and zoom.
  • The side panel shows:
    • the current stage and how long it took;
    • each call's docstring, source location, arguments and return value, or the exception it raised;
    • the parameters the context added;
    • the forms the response took.
  • An optional criteria view shows how each criterion is chosen: it is parsed, its parse label selects a template, and the template builds the criteria graph. It then shows the path each criteria graph took, and which criterion produced each tag of the result.
  • Clicking a node, or a tag or criterion link in the panel, moves to the step that makes that node current.
  • "Hide internals" (on by default) leaves out dunder calls. A legend explains the colours and edges. Panel sections can be collapsed, and the settings persist in localStorage.
  • Besides the three documented examples, there are three that only the animation uses: an incorrect response, syntactical_comparison (two criteria), and a criterion that falls back to the context's default template.
  • The page is about 4.7 MB, because the 20 graphviz layouts for each example are gzipped and unpacked in the browser.
• scripts/generate_process_graphs.py:
  • Values: readable summaries of contexts, EvaluationResult and large dicts, and parse trees drawn with connectors.
  • Calls: the exception a call raised, captured with sys.monitoring PY_UNWIND, plus each call's docstring and source location.
  • Recording: the parameter, feedback and timing events, and an option for calls_to_dot to hide internal calls.
  • Static SVGs: they are byte-identical to before.

Notes

• Timings: they are measured while every call is being recorded, so they are much longer than in a normal evaluation. The page says so.
• Exception messages: these, and any other recorded values, appear only in the locally built page. Nothing is logged.
• Graph regeneration: this PR changes scripts/generate_process_graphs.py, so the documentation graphs workflow from Regenerate the documentation graphs on pull requests #318 will run on it. It should find no SVG changes.

Checklist

• Tests added/updated: not applicable, since only the generator scripts change. The existing suite passes (1240 passed, 2 skipped, 1 xfailed). The page was checked in headless Chrome:
  • no JS errors;
  • with internals shown and the criteria graph off, the depth 2 final frame matches process_symbolic_calls.svg;
  • each example ends with the expected result;
  • light and dark themes, and phone width.
• Docs updated (app/docs.md) if user-facing behaviour changed: not applicable, since there is no user-facing change.

🤖 Generated with Claude Code