docs: EP review phase 2 — formal Bayesian documentation of autofit/graphical

[Jammy2211]

Overview

Phase 2 of the EP framework review (umbrella: PyAutoMind/research/graphical_ep/ep_framework_review.md; Phase 1 audit: #1332). Package-level documentation stating the exact Bayesian machinery autofit/graphical implements, in formal equations, written so an AI agent (or human) can verify code against the stated math line-by-line.

Autonomy: launched --auto, effective level supervised (docs cap). Plan below per the contract; the run proceeds through implementation and parks at ship sign-off with a batched question. No Heart YELLOW acknowledgement was given at launch.

Plan

• autofit/graphical/README.md (new): the formal specification — factor-graph model, mean-field approximating family, the EP step (cavity → tilted → moment-matching KL projection → damped division as natural-parameter EMA), evidence decomposition, convergence criteria, exact conjugate updates, deterministic-variable mechanisms — each equation anchored to the implementing class/method (EPMeanField.factor_approximation, MeanField.update_factor_mean_field, AbstractMessage.project, …). Public and self-contained (no personal-repo references).
• Targeted docstring upgrades at the load-bearing statistical points:
  • MeanField.update_factor_mean_field — the damped-update equation, delta semantics (scalar / per-factor / per-variable MeanField), and the invalid-projection fallback.
  • FactorApproximation.project_mean_field — fix the Phase 1 F5 docstring error ((qᶠₐ)ᵟ (qᶠₐ)¹⁻ᵟ → (qᶠₐ)ᵟ (qₐ)¹⁻ᵟ).
  • TransformedMessage._transform / _inverse_transform + composed_transform.py module docstring — the asymmetric reversal convention and a worked UniformPrior example (folds in bug/priors/11, per its Phase 0 verdict).
  • MessageInterface.kl — state the direction contract m.kl(other) ≡ KL(m ‖ other), note the known Gamma/Beta deviation tracked in research: EP review phase 1 — statistics audit of autofit/graphical #1332 (F2) pending its fix.
  • AbstractMessage.project — the importance-weighted sufficient-statistics moment-matching equations.
• Convention statement: document the current constant-dropping behaviour of log_prior_from_value per family factually, marked as pending unification under Priors & messages: 9 confirmed bugs — guidance wanted on 5 decisions #1331 decision 4 (the docs do not pre-empt that decision).
• Verification: full test_autofit/graphical/ + test_autofit/messages/ suites (docstring-only changes must not alter behaviour); README proofread against source anchors.

Detailed implementation plan

Affected Repositories

• PyAutoFit (only) — docs/docstrings; no behaviour changes.

Branch / worktree

• Branch: feature/ep-graphical-docs; worktree ~/Code/PyAutoLabs-wt/ep-graphical-docs.
• PyAutoFit is unclaimed at launch (previous aggregator-output-contracts claim released).

Files

• autofit/graphical/README.md (new)
• autofit/graphical/mean_field.py (docstrings: update_factor_mean_field, FactorApproximation, F5 fix)
• autofit/messages/composed_transform.py (module + _transform/_inverse_transform docstrings)
• autofit/messages/interface.py (KL contract on kl)
• autofit/messages/abstract.py (project docstring)

Out of scope (later phases)

• Integration tests + end-to-end examples (Phase 3, autofit_workspace / autofit_workspace_test).
• Any behaviour change, including the F1–F9 and Priors & messages: 9 confirmed bugs — guidance wanted on 5 decisions #1331 fixes.
• Sphinx docs/ pages (follow-up via the docs-audit tooling once the README stabilises).

[Jammy2211]

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

Phase 2 implementation is complete in worktree ep-graphical-docs (branch feature/ep-graphical-docs, based on main @ 0f26ff2d8). Awaiting your go-ahead to commit/push/open the PR.

What was done

 autofit/graphical/README.md            | new — the formal specification
 autofit/graphical/mean_field.py        | 54 +++++++++-
 autofit/messages/abstract.py           | 23 ++++-
 autofit/messages/composed_transform.py | 68 ++++++++++-
 3 files changed, 134 insertions(+), 11 deletions(-)

• autofit/graphical/README.md — the full mathematical specification, equations numbered and each anchored to its implementing class/method: model (factor graph), approximating family (per-factor per-variable exponential-family messages), the EP step (cavity η-sums → tilted distribution → moment-matching projection → damped division as natural-parameter EMA), the three factor-optimiser paths (sampling / Laplace / exact-conjugate), convergence (KL criterion + direction contract), evidence decomposition (with an audit note that Eq. 15 shouldn't be used for model comparison until research: EP review phase 1 — statistics audit of autofit/graphical #1332-F7 lands), deterministic-variable mechanisms (all three, flagged as a Phase 5 reconciliation item), parallel-EP semantics, and references (Minka 2001, Vehtari+ 2020, Seeger 2005).
• mean_field.py — full equation docstring on update_factor_mean_field (damped update, delta semantics, invalid-projection fallback); KL direction contract on MeanField.kl; fixed the F5 docstring error in FactorApproximation ((qᶠₐ)ᵟ (qᶠₐ)¹⁻ᵟ → (qᶠₐ)ᵟ (qₐ)¹⁻ᵟ).
• composed_transform.py — module docstring stating the transform composition-order convention (innermost-first storage; _transform reverses, _inverse_transform forward) with the worked UniformPrior(0, 2).value_for(0.5) trace; direction notes on both methods; validity condition documented on TransformedMessage.kl (shared transform stack required — no check performed). This delivers the cheap half of bug/priors/11 per its Phase 0 verdict.
• abstract.py — moment-matching equations on AbstractMessage.project (inclusive-KL projection, importance-weighted moment estimation, log_norm provenance).

Verification

• pytest test_autofit/graphical/ test_autofit/messages/ -x: 200 passed (docstring-only diff; no behaviour change possible beyond import-time).
• One error caught and fixed during self-review: my first draft of the composition-order convention said "outermost-first"; the stack is innermost-first (verified against the UniformPrior flattening in TransformedMessage.__init__).

The question

Approve ship? On approval the run proceeds through ship_library: commit, push feature/ep-graphical-docs, open the PR (docs-only, no API changes, no downstream workspace impact), and stop at PR-open per the contract. If you'd like changes to the README's content or placement (e.g. prefer it in Sphinx docs/ instead of an in-package README), say so and I'll amend before shipping.

[Jammy2211]

Library PR created: #1334 (feature/ep-graphical-docs @ 07072db45, pending-release).

Gate: full-suite tests 1422 passed / 14 skipped · smoke n/a (docs-only) · ship sign-off human-approved · Heart YELLOW acknowledged in-session (10 pre-existing organism-staleness reasons, none touching this diff).

Workspace impact: (iii) none — ## API Changes: None; no public symbol changed, so no workspace scripts are affected and no migration or new demos are needed. Run ends at PR-open per the autonomy contract; merge is yours. Phase 3 (integration tests + end-to-end examples in autofit_workspace/autofit_workspace_test) is the umbrella's next phase and can launch independently of this merge.