[ethanzhoucool]

Summary

POST /v1/explain/all-levels is the endpoint the web UI calls on every run. Its docstring gives the reason it exists: "The parse and analysis passes are the expensive part and are level-independent." But it called explain() once per level, so every request parsed and analysed the snippet three times.

That also caused a correctness bug. Each pass created a fresh IR with new node ids. The response's shared analysis block came from the ELI5 pass, so the BEGINNER and DEVELOPER lines/annotations/concepts carried nodeIds that matched nothing in analysis. For def add(a, b): ... on main:

eli5      analysis.functions[0].nodeId = 2   line 1 nodeId = 2
beginner  analysis.functions[0].nodeId = 2   line 1 nodeId = 10
developer analysis.functions[0].nodeId = 2   line 1 nodeId = 18

Changes

• core.py: new Explanation.at_level(level). It re-runs only the narration (annotate, summarize, line_view) over the existing parse and analysis, for another audience. LLM enrichment is level-specific and is not carried over (all-levels never enriched anyway).
• api/main.py: explain_all_levels calls explain() once and uses at_level() for the other two levels. The response shape and key order are unchanged.

Testing

• pytest on Python 3.13, 3.12 and 3.11: 152 passed, 3 skipped. ruff is clean, and mypy reports the same 26 errors as before.

• Same output: I dumped the full all-levels JSON on main and on this branch for the 5 bundled web samples, a detection case, a syntax-error case and a 60 KB slice of stdlib code. With nodeId/nodeIds stripped, the two dumps are byte-for-byte identical (1.5 MB each).

• Speed (endpoint through TestClient, Python 3.13, median):

  input	main	this PR
  Python web sample (1.2 KB, 30 runs)	17.9 ms	12.5 ms
  195 KB of stdlib Python (5 runs)	1112 ms	558 ms

• New tests. All fail on main:

  • test_all_levels_parses_once counts adapter parse calls;
  • test_all_levels_node_ids_match_the_shared_analysis;
  • test_at_level_matches_a_fresh_explanation, one per level: summary and line text/kind match a fresh explain() at that level.

---

Generated by Claude Code