docs/test: EP review phase 3 — step-by-step EP example + integration tests

[Jammy2211]

Overview

Phase 3 of the EP framework review (umbrella: PyAutoMind/research/graphical_ep/ep_framework_review.md; audit PyAutoFit#1332; formal spec PyAutoFit#1334). End-to-end examples and thicker integration coverage for the EP framework.

Autonomy: --auto, effective level supervised; plan approved by user in-session at launch. No Heart acknowledgement given at launch. Run parks at ship sign-off.

Plan (approved)

autofit_workspace (branch feature/ep-examples-tests):

• New scripts/features/expectation_propagation.py — step-by-step low-level EP walkthrough in the likelihood_function.py mould: simulate 3 shared-centre 1D Gaussians, build the factor graph explicitly, construct the EPMeanField, dissect one EP update cell-by-cell (cavity messages/natural parameters → tilted fit via LaplaceOptimiser → moment-matched projection → damped division → before/after message comparison → per-variable KL → evidence pieces), then the full EPOptimiser loop and the convergence/damping knobs. Each step quotes the governing equation from autofit/graphical/README.md (PyAutoFit#1334).
• Cross-reference from scripts/features/graphical_models.py's closing EP section.

autofit_workspace_test (same branch):

• scripts/graphical/ep_parity.py — EP vs joint-fit parity on the shared-centre toy (shared-parameter posterior mean/σ within tolerance; truth within 3σ).
• scripts/graphical/ep_deterministic.py — low-level factor_out deterministic-variable API through an EP fit (Phase 5 groundwork).
• scripts/graphical/ep_exact.py — ExactFactorFit conjugate path: analytic update == moment-matched sampled result.
• Fast settings throughout; not added to smoke_tests.txt.

Ship via ship_workspace; no library-first gate (exercises released EP APIs only; PyAutoFit#1334 is docs-only).

[Jammy2211]

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

Phase 3 implementation is complete in worktree ep-examples-tests (branch feature/ep-examples-tests in both repos). One approval covers both the diff and the Heart YELLOW acknowledgement below.

Diff

autofit_workspace (2 files):

• scripts/features/expectation_propagation.py (new, ~320 lines) — the step-by-step low-level EP walkthrough. Validated end-to-end: on gaussian_x1_{0,1,2} (shared true centre 50, priors deliberately offset to 35) the dissected first update moves the shared centre 35 → 48.5±10.0 and the damped (δ=0.7) global update lands 47.7±11.6; the full loop converges to 49.96 ± 0.12 with all per-dataset parameters recovered. Each cell cites its equation in autofit/graphical/README.md (PyAutoFit#1334).
• scripts/features/graphical_models.py — closing EP section now cross-references the new script.

autofit_workspace_test (3 new scripts, all verified exit-0/PASS):

• scripts/graphical/ep_parity.py (~19s, stable over 4 runs) — EP vs joint Dynesty fit parity + truth recovery on the shared-centre toy.
• scripts/graphical/ep_deterministic.py (~6s) — the low-level factor_out deterministic-variable API through an EP fit (x+y → 2.999 vs observed 3.0; z variance 8.0 → 0.01). First integration exercise of this API; Phase 5 groundwork.
• scripts/graphical/ep_exact.py (~4s) — ExactFactorFit conjugate path matches the analytic two-Gaussian product to identical digits.

Development surfaced a new audit finding (F10, posted to PyAutoFit#1332): undamped Laplace-only EP collapses all sigmas to ~1e-15 over repeated cycles with no guardrail (the corresponding unit test is disabled in the suite). The scripts document and work around it; the finding feeds the fix batch and Phase 4 diagnostics.

No output/binary leaks (git status shows exactly the 5 intended files). Not added to smoke_tests.txt.

Heart

YELLOW, same 10-reason set as the Phase 2 ship (workspace validation 5 pre-existing failures; 58 stale parked scripts; assistant pinned behind; install verification not run; no release validation; 63 timing regressions; 4 old open PRs). None caused by this change. Acknowledgement requested as part of this sign-off.

On approval

ship_workspace proceeds: commit + push both repos, open both PRs (pending-release), library-first gate n/a (no unreleased library dependency), stop at PR-open. Merge stays yours.