fix(autofit): resolve sample parameter-path KeyError under release profile

[Jammy2211]

Overview

Nine workspace scripts fail under the release-fidelity profile (PyAutoHeart run 28784914443, issue PyAutoHeart#27) with a KeyError raised in autofit/non_linear/samples/sample.py::parameter_lists_for_paths: a loaded sample's stored kwargs keys no longer align with the current model's paths. This is a high-severity, ecosystem-scope runtime regression whose fix belongs in the PyAutoFit resolution contract — not in the user-facing workspace scripts.

Plan

• Reproduce the KeyError on clean main for a representative subset (single, multi-analysis, chained, list-profile, multi-dataset) to confirm the cluster is still live.
• Trace model-path construction vs. stored sample kwargs through Sample / Samples / result-loading to classify the mismatch (path alias, collection/list index, or genuinely retired stored-key format).
• Fix the PyAutoFit path-resolution contract so valid current-model paths resolve against stored samples; a single general fix, split into more than one PR only if sub-causes diverge.
• Add focused regression tests in test_autofit/non_linear/samples/test_samples.py covering the represented path categories.
• Ship the PyAutoFit PR (pending-release); a separate Phase 2 re-validates the 9 scripts under the release profile and edits only scripts using a genuinely retired API.

Detailed implementation plan

Affected Repositories

• PyAutoFit (primary — library fix)
• autogalaxy_workspace, autolens_workspace (downstream verification only, Phase 2)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoFit	main	clean
./autogalaxy_workspace	main	dirty (generated outputs; irrelevant to library phase)
./autolens_workspace	main	dirty (generated outputs; irrelevant to library phase)

Suggested branch: feature/samples-parameter-paths
Worktree: ~/Code/PyAutoLabs-wt/samples-parameter-paths/

Implementation Steps

1. Reproduce on clean main under the release profile for 1–2 representative scripts (via the vitals faculty) — confirm the KeyError still fires before fixing.
2. Root-cause in autofit/non_linear/samples/sample.py: parameter_lists_for_paths (line 104), is_path_kwargs (line 119), subsample (line 130); and how Samples builds all_paths / all_names and how directory/database loading repopulates kwargs.
3. Fix at the resolution boundary so valid current-model paths resolve against stored sample kwargs. Do not catch/mask the error or weaken workspace scripts.
4. Add regression tests in test_autofit/non_linear/samples/test_samples.py covering single, multi-analysis, chained, list-profile, and multi-dataset path shapes.
5. Run python -m pytest test_autofit/; note any public-API change for downstream consumers.

Key Files

• autofit/non_linear/samples/sample.py — the KeyError locus and path/kwargs resolution.
• autofit/non_linear/samples/* (Samples container + directory/database loaders) — where stored kwargs are repopulated.
• test_autofit/non_linear/samples/test_samples.py — regression coverage.

Fix locus / guardrails (from the Bug Agent BugDecision)

• severity=high · scope=ecosystem · type=runtime-error · owner=autofit
• Fix locus: library source (general fix) — resolving the contract clears the whole class.
• Strategy: split-into-phases (prefer small shippable PRs); workflow: combined (library ships first).
• Do NOT edit workspace scripts to mask it (no injected env-vars / hard-coded paths / os.environ mutation / silent guards).
• Validate via the vitals faculty after patching (lib-tests, then workspace/integration), targeting pyauto-heart GREEN/YELLOW before ship.

Original Prompt

Click to expand starting prompt

Fix release result/sample parameter-path regressions

Context

PyAutoHeart release validation run 28784914443 exposed a family of workspace
failures. Against current main, nine scripts converge on
PyAutoFit/autofit/non_linear/samples/sample.py::parameter_lists_for_paths
raising KeyError for model paths that no longer match stored sample kwargs.

Primary repository: @PyAutoFit. Downstream verification repositories:
@autogalaxy_workspace and @autolens_workspace.

Scripts

• autogalaxy_workspace/scripts/imaging/features/pixelization/galaxy_reconstruction.py
• autogalaxy_workspace/scripts/imaging/features/shapelets/modeling.py
• autogalaxy_workspace/scripts/multi/features/imaging_and_interferometer/modeling.py
• autolens_workspace/scripts/group/features/advanced/mass_stellar_dark/chaining.py
• autolens_workspace/scripts/guides/modeling/advanced/hierarchical.py
• autolens_workspace/scripts/imaging/features/advanced/shapelets/modeling.py
• autolens_workspace/scripts/interferometer/features/subhalo/detect/start_here.py
• autolens_workspace/scripts/interferometer/features/extra_galaxies/slam.py
• autolens_workspace/scripts/multi/features/imaging_and_interferometer/modeling.py

Required work

1. Reproduce from clean task worktrees with the release profile and current library
   sources; distinguish stale cached output from newly written samples.
2. Trace model path construction, stored kwargs, path aliases, and collection/list
   indices through Samples, Sample, and result loading.
3. Fix the owning PyAutoFit contract if valid current-model paths cannot resolve.
   Do not weaken workspace scripts or silently ignore missing parameters.
4. Add focused PyAutoFit regression tests covering single, multi-analysis, chained,
   list-profile, and multi-dataset paths represented above.
5. Run PyAutoFit pytest, then rerun all nine scripts under their release profiles.

Preserve tutorial prose and make workspace edits only where a script genuinely uses a
retired API rather than exposing a library defect.

---

🤖 Filed via /bug → Bug Agent → /start_dev. Source: PyAutoHeart#27 release-fidelity validation.

[Jammy2211]

Root-cause investigation — findings so far (Opus session)

Locus confirmed: autofit/non_linear/samples/sample.py::parameter_lists_for_paths raises KeyError when none of a model parameter's all_paths alias keys are present in the loaded sample's kwargs.

Machinery mapped:

• CSV headers are written from model.joined_paths → unique_prior_paths (raw paths, incl. the tuple-prior name, e.g. ellipses.0.centre.centre_0) — set by e333ab436 (Oct 2023).
• Lookup uses self.paths = model.all_paths (raw). self.names = all_names applies TuplePathModifier (collapses the tuple name), but is only used when sample.is_path_kwargs is False.
• Since 745117bd7 (May 2026), Sample.__init__ converts every string key to a tuple, so is_path_kwargs is effectively always True → lookup always uses raw all_paths. All call sites (interface.py:95, summary.py:67, samples.py:76/215/324) use the same guarded pattern.

What I ruled out on current main (all PASS, no KeyError):

• Fresh CSV write→read round-trip (collection of profiles).
• Database serialize (Sample.dict(), tuple→dotted) → deserialize round-trip.
• Mixed top-level dotless scalar (dummy_0) + nested collection + tuple priors — the exact shape 745117bd7 fixed.
• Tuple-prior-inside-collection (ellipses.N.centre.centre_0).
• Model dict()→from_dict() JSON round-trip: joined_paths and all_paths are identical before/after; original header keys all resolve against the reloaded model's all_paths.

Conclusion: the 745117bd7 fix (already in main at the 2026-07-06 release run) covers the generic cases; the release KeyError needs a write-model ≠ read-model path divergence specific to these scripts' flows (chaining / prior-passing / aggregator reconstruction), which does not surface in generic round-trips. The failing calls are ordinary result access — result.info, result.max_log_likelihood_instance, result.samples (e.g. autogalaxy_workspace/.../shapelets/modeling.py:284-298).

Needed next input: a real traceback from one failing script (the reproduction the BugDecision delegates to the vitals faculty). Two caveats worth flagging per triage discipline:

1. The cluster is dated 2026-07-06; several prompt scripts note they "passed in a stateful local checkout." Given generic round-trips pass on clean main, a clean-main reproduction of ≥1 script should be confirmed before committing to a library fix — the class may be narrower than 9 scripts, or partially aged-out.
2. If confirmed, the fix stays a general PyAutoFit path-resolution fix; no workspace-script edits to mask it.

[Jammy2211]

Reproduction on clean main — shapelets leg does NOT reproduce

Ran autogalaxy_workspace/scripts/imaging/features/shapelets/modeling.py (one of the 9) against the current installed stack (2026.7.6.649), then forced the true from-disk reload path that the release run exercises:

1. Full script, in-memory result access (result.info, result.max_log_likelihood_instance, result.samples, corner_cornerpy): exit 0, no KeyError. Model is a 125-prior Basis of shapelet components, each with tuple priors (centre, ell_comps) inside a profile_list collection — the exact ...profile_list.0.centre.centre_0 shape.
2. From-disk reconstruction (model rebuilt from model.json, samples loaded from samples.csv, then parameter_lists_for_paths(model.all_paths)): model 125 priors, samples 125 columns, 0 kwargs keys missing from all_paths, returns 125 values — no KeyError.

Interpretation: the 745117bd7 fix (May 2026) was already in main at the 2026-07-06 release run, and every current-main path I can exercise (synthetic round-trips + this real script, in-memory and from-disk) is path-consistent. The most likely explanation for the release-run failure is stale cached output (a samples.csv written by a pre-745117bd7 stack, whose collapsed/dotless keys don't resolve against current raw all_paths) — which the prompt itself flags: "distinguish stale cached output from newly written samples." This is a CI-hygiene artifact, not a current-main library defect, at least for this leg.

Recommendation: before committing a speculative library fix, re-validate the cluster with a clean-output CI re-run (fresh output/, current wheels). If a leg still fails from genuinely-fresh samples, capture that traceback and reopen the fix with the exact divergence. Verifying a second (multi-analysis) leg now.

[Jammy2211]

Second leg confirms: cluster does not reproduce on current main

autogalaxy_workspace/scripts/multi/features/imaging_and_interferometer/modeling.py (multi-analysis — the flavour most likely to diverge write-model vs read-model):

• Full script: exit 0, no KeyError (returns a ModelInstance).
• From-disk reload (model from model.json, samples from samples.csv): prior_count 22, 22 sample columns, 0 missing keys, parameter_lists_for_paths returns 22 values — no KeyError.

Verdict

Two structurally different legs (single-search 125-prior shapelets Basis; multi-analysis 22-prior) both pass on current main, in-memory and via the true from-disk reconstruction. Together with the synthetic round-trips and the presence of the 745117bd7 fix at release time, this indicates the 2026-07-06 KeyError cluster was not a current-main library defect — most consistent with stale cached output/ in the release run (pre-fix samples.csv keys not resolving against current raw all_paths).

Recommendation

• Do not land a speculative library fix. There is no reproducing defect, and a defensive guard in parameter_lists_for_paths would mask rather than fix.
• Re-validate the cluster with a clean-output/ CI re-run on current wheels. If any leg still fails from genuinely-fresh samples, capture that traceback and this issue can be reopened against the exact divergence.
• The sibling health_fixes/ prompts derived from the same 2026-07-06 run may likewise have aged out — worth a clean-output re-validation before working them.

Proposing to park this issue pending that clean CI re-validation rather than fix-and-ship.

[Jammy2211]

Status: PARKED (issue kept open). No reproduction on current main after a two-leg + synthetic investigation, so no library fix is being written. Task moved to PyAutoMind/planned.md (status: parked), worktree torn down, prompt returned to bug/health_fixes/. Unblock condition: a clean-output/ CI re-run on current wheels — if a leg still fails from genuinely-fresh samples, capture that traceback and reopen against the exact divergence.