feat: EP review phase 4 — diagnostics & monitoring for EP fits

[Jammy2211]

Overview

Phase 4 of the EP framework review (umbrella: PyAutoMind/research/graphical_ep/ep_framework_review.md; audit #1332). EP fits currently emit one evidence/KL plot (graph.png) and a text graph.results; there is no machine-readable fit log, no record of how the mean field evolved, no per-factor status accounting, no guard against the F10 sigma-collapse pathology, and no post-fit summary helpers. This adds all of those, additively (no behaviour change to the fitting itself).

Autonomy: --auto, effective level supervised (feature cap). Plan below per contract; run parks at ship sign-off.
Coexistence note: PyAutoFit is also claimed by the parked ep-graphical-docs task (PR #1334, docs-only). This task's files (expectation_propagation/, new diagnostics module, test_autofit/graphical/) are disjoint from that diff (README, mean_field.py, composed_transform.py, abstract.py docstrings); disjointness is re-verified before ship. Human directed both to proceed in parallel.

Plan

New autofit/graphical/expectation_propagation/diagnostics.py:

• MeanFieldSnapshot recording per factor-step: step index, factor name, status (success/updated/flag), factor log-evidence, factor KL, and per-variable (mean, std) of the global mean field (arrays summarised as mean-of-means / max-std).
• EPDiagnostics collector — accumulates snapshots during a run; writers for:
  • ep_history.csv — step, factor, success, flag, log_evidence, kl_divergence;
  • mean_field_history.csv — step, variable, mean, std;
• mean_field_summary(mean_field) — post-fit text table (variable, mean, std) usable at the end of any example.
• check_sigma_collapse(...) — the F10 guard: flags variables whose std shrinks monotonically below a floor across steps; returned as warnings, logged at run end, and appended to the results text.

visualise.py upgrades:

• Enable the (currently commented-out) per-factor evidence/KL curves as graph_factors.png.
• New mean_field_evolution.png — per-variable mean ± std band vs step, from the diagnostics collector.

optimiser.py wiring:

• EPOptimiser instantiates EPDiagnostics when paths is set; snapshot after each factor update (cheap float extraction); CSVs written at output_interval; final summary + collapse warnings emitted at run end.
• Fix F3 while here: guard the unconditional self.visualiser() / _output_results at the end of ParallelEPOptimiser.run (crash when paths=None) — one-line, same file, in scope as the wiring touches these call sites.

Tests (test_autofit/graphical/functionality/test_diagnostics.py, numpy-only):

• Tiny exact-conjugate graph run via EPOptimiser with paths at tmp_path → CSVs exist, expected columns, row counts match steps×factors; summary text contains all variables.
• check_sigma_collapse fires on a synthetic collapsing history, silent on a healthy one.
• ParallelEPOptimiser completion with paths=None no longer raises (F3).

Out of scope: wiring diagnostics calls into workspace examples (follow-up on the parked Phase 3 branch or later); richer aggregated posterior views (graphical_scoping.md limitation 3 — the CSV/plot layer here is its foundation).

[Jammy2211]

Ship sign-off requested (supervised checkpoint — run parked)

Phase 4 implementation is complete in worktree ep-diagnostics (branch feature/ep-diagnostics). One approval covers the diff and the Heart YELLOW acknowledgement.

Diff (6 files; all additive, no behaviour change to fitting)

• expectation_propagation/diagnostics.py (new) — EPDiagnostics collector (one snapshot per factor update: status/flag, global log-evidence, KL step size, every variable's mean/std); CSV writers (ep_history.csv, mean_field_history.csv, overwritten live so a running fit can be watched); mean_field_evolution.png (per-variable mean ± std band vs update); mean_field_summary() post-fit table; check_sigma_collapse() — the F10 guard (floor + monotone-shrink detection, warnings logged and written to ep_diagnostics.results).
• optimiser.py — EPOptimiser/ParallelEPOptimiser snapshot each update and emit the artifacts at output_interval + run end; F3 fixed (parallel end-of-run visualiser()/_output_results now guarded for paths=None).
• visualise.py — new graph_factors.png: per-factor evidence/KL curves (previously dead commented-out code), so one misbehaving factor is visible instead of averaged away.
• Exports — EPDiagnostics, mean_field_summary, check_sigma_collapse from autofit.graphical (additive public API).
• test_autofit/graphical/functionality/test_diagnostics.py (new) — 7 tests: snapshot schema, CSV/plot/results artifacts, summary content, collapse detector (floor + monotone + healthy-negative), F3 guards.

Verification

• Live smoke on an exact-conjugate graph: posterior matches analytic to machine precision; all 5 new artifacts written; collapse detector silent on a healthy run.
• Test development caught a real bug in the first cut (crash on TransformedMessage/UniformPrior variables — no .std attribute); fixed by deriving std from variance inside the module, keeping the branch disjoint from PR docs: formal Bayesian specification of autofit.graphical (EP review phase 2) #1334's files. The failing case (test_other_priors.py::test_trivial) now passes.
• Full suite: 1429 passed / 14 skipped (baseline 1422 + 7 new).
• Disjointness with the parked ep-graphical-docs branch re-verified: zero file overlap (that diff: README, mean_field.py, messages/abstract.py, composed_transform.py; this diff: expectation_propagation/*, exports, tests).

Heart

YELLOW, same 10 pre-existing organism-staleness reasons as the Phase 2/3 sign-offs; none touch this diff. Acknowledgement requested as part of this approval.

On approval

ship_library proceeds: commit, push, PR at pending-release with ## API Changes (Added: the three exported functions/classes; no removals/migrations), workspace-impact analysis (expected: option i — small follow-up wiring mean_field_summary calls into the Phase 3 example), stop at PR-open.

[Jammy2211]

Shipped at PR-open (human-approved 2026-07-10) — #1349

PR #1349 open (pending-release). Branch was merged with current main (post #1345/#1348/#1334) before validation: full suite 1457 passed / 14 skipped — so the diagnostics module is certified against this week's priors/messages fix batch and the merged docs spec, not the 07-08 snapshot. Heart YELLOW within the live 6-reason ack. Merge stays human. Post-merge follow-up (option i, small): wire mean_field_summary() into the Phase-3 walkthrough (autofit_workspace#82).

[Jammy2211]

Merged — 1a06bbc14 via #1349. Follow-up (wire mean_field_summary() into the Phase-3 walkthrough) queued as a Mind prompt. Closing.