docs(aggregator): add module-level docstrings to aggregator package

Add module-level docstrings to all ten aggregator modules explaining the
purpose of each module, the two public objects it exposes (a free helper
function and an Agg class), and how they relate to the broader PyAutoFit
database / aggregator workflow.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

autogalaxy/aggregator/agg_util.py

@@ -1,3 +1,24 @@
+"""
+Shared utility functions for the **PyAutoGalaxy** aggregator interface.
+
+This module provides low-level helpers used by all dataset-specific aggregator classes
+(`ImagingAgg`, `FitImagingAgg`, `GalaxiesAgg`, etc.).  They centralise the logic that
+is repeated across every aggregator module so that the higher-level classes stay concise.
+
+Key functions
+-------------
+- `instance_list_from` — Converts a ``PyAutoFit`` ``Fit`` into the correct list of model
+  instances, handling both single-analysis fits and multi-analysis ``FactorGraphModel``
+  fits.
+- `mask_header_from` — Loads a ``Mask2D`` and its FITS header from a stored dataset file.
+  Used whenever a dataset must be reconstructed from the database.
+- `adapt_images_from` — Reconstructs ``AdaptImages`` objects from files stored during the
+  model-fit.  Needed so that adaptive features (e.g. an ``Hilbert`` image-mesh) reproduce
+  the same behaviour on a local machine as on the HPC cluster where the fit was run.
+- `mesh_grids_of_planes_list_from` — Loads the pre-computed image-plane mesh grids that
+  were saved during the fit, removing any stochastic variation when inspecting results
+  offline.
+"""
 from __future__ import annotations
 import numpy as np
 from typing import List, Optional

autogalaxy/aggregator/dataset_model.py

@@ -1,3 +1,15 @@
+"""
+Aggregator interface for loading ``DatasetModel`` objects from model-fit results.
+
+A ``DatasetModel`` holds dataset-level nuisance parameters (e.g. an overall background
+offset or a noise scaling factor) that form part of the fitted model.  This module
+provides the helper function ``_dataset_model_from`` which reconstructs these objects from
+a stored ``PyAutoFit`` ``Fit`` entry so that the full fit can be replicated during
+offline analysis.
+
+When no ``dataset_model`` is present in the model (the common case), ``None`` is returned
+for that entry so that downstream ``Fit*`` constructors receive a well-typed argument.
+"""
 from __future__ import annotations
 import logging
 from typing import List

autogalaxy/aggregator/ellipse/ellipses.py

@@ -1,3 +1,18 @@
+"""
+Aggregator interface for loading ``Ellipse`` objects from ellipse model-fit results.
+
+After an ellipse model-fit the best-fit ellipse parameters are stored in the output
+directory or SQLite database as part of the model JSON file.  This module reconstructs
+the list of ``Ellipse`` instances so that downstream analysis (e.g. re-plotting
+isophotes) can be performed without re-running the fit.
+
+Two public objects are provided:
+
+- ``_ellipses_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns the list of ``Ellipse`` objects for the requested model instance.
+- ``EllipsesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator`` that
+  exposes a generator of ellipse lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/ellipse/fit_ellipse.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``FitEllipse`` objects from ellipse model-fit results.
+
+This module reconstructs ``FitEllipse`` instances from the imaging dataset, fitted
+ellipses, and (optionally) multipole perturbations stored in an output directory or
+SQLite database, allowing full offline inspection of isophote fits without re-running the
+non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_ellipse_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``FitEllipse`` objects (one per ellipse in the fit).
+- ``FitEllipseAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator``
+  that exposes a generator of ``FitEllipse`` object lists, one entry per stored
+  model-fit.
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/ellipse/multipoles.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``EllipseMultipole`` objects from ellipse model-fit results.
+
+``EllipseMultipole`` objects represent higher-order harmonic perturbations (e.g. m=3, m=4
+boxy/disky distortions) on top of the base ellipse isophotes.  This module reconstructs
+the nested list of multipole objects from a stored ``PyAutoFit`` ``Fit`` entry so that
+multipole-enhanced isophote fits can be inspected offline.
+
+Two public objects are provided:
+
+- ``_multipoles_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns the nested list of ``EllipseMultipole`` objects for the requested
+  model instance.
+- ``MultipolesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an ``Aggregator``
+  that exposes a generator of multipole lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/galaxies.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading **PyAutoGalaxy** ``Galaxy`` objects from model-fit results.
+
+After a non-linear search completes, its outputs (best-fit parameters, adapt images, etc.)
+are written to an output directory or stored in an SQLite database.  The helpers in this
+module reconstruct ``Galaxy`` instances from those stored files so that the full galaxy
+model can be re-created and inspected without re-running the fit.
+
+Two public objects are provided:
+
+- ``_galaxies_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns the list of ``Galaxy`` objects (or lists of lists when multiple ``Analysis``
+  objects were summed).
+- ``GalaxiesAgg`` — a ``PyAutoFit`` ``AggBase`` subclass that wraps an ``Aggregator``
+  and returns a generator of galaxy lists, one per stored model-fit.
+"""
 from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Optional, List

autogalaxy/aggregator/imaging/fit_imaging.py

@@ -1,3 +1,19 @@
+"""
+Aggregator interface for loading ``FitImaging`` objects from model-fit results.
+
+This module combines all the pieces that are needed to re-create a ``FitImaging``
+object offline — the imaging dataset, galaxy model, dataset model, and adapt images —
+and assembles them into a ``FitImaging`` instance identical to the one produced during
+the original non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_imaging_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``FitImaging`` objects (one per summed ``Analysis``).
+- ``FitImagingAgg`` — a ``PyAutoFit`` ``AggBase`` subclass that wraps an ``Aggregator``
+  and exposes a generator of ``FitImaging`` objects, enabling memory-efficient iteration
+  over large result sets.
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/imaging/imaging.py

@@ -1,3 +1,18 @@
+"""
+Aggregator interface for loading ``Imaging`` datasets from model-fit results.
+
+After a model-fit the imaging dataset (data array, noise-map, PSF, mask, and
+over-sampling settings) is written to a FITS file in the output directory or SQLite
+database.  This module reconstructs a fully-masked ``aa.Imaging`` object from those
+stored files.
+
+Two public objects are provided:
+
+- ``_imaging_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit`` entry
+  and returns a list of ``aa.Imaging`` datasets (one per summed ``Analysis``).
+- ``ImagingAgg`` — a class wrapping an ``Aggregator`` that returns a lazy generator of
+  ``Imaging`` datasets, avoiding loading all results into memory at once.
+"""
 from functools import partial
 from typing import List
 

autogalaxy/aggregator/interferometer/fit_interferometer.py

@@ -1,3 +1,20 @@
+"""
+Aggregator interface for loading ``FitInterferometer`` objects from model-fit results.
+
+This module combines all the pieces that are needed to re-create a ``FitInterferometer``
+object offline — the interferometer dataset, galaxy model, dataset model, and adapt
+images — and assembles them into a ``FitInterferometer`` instance identical to the one
+produced during the original non-linear search.
+
+Two public objects are provided:
+
+- ``_fit_interferometer_from`` — a free function that accepts a single ``PyAutoFit``
+  ``Fit`` entry and returns a list of ``FitInterferometer`` objects (one per summed
+  ``Analysis``).
+- ``FitInterferometerAgg`` — a ``PyAutoFit`` ``AggBase`` subclass wrapping an
+  ``Aggregator`` that exposes a generator of ``FitInterferometer`` objects, enabling
+  memory-efficient iteration over large result sets.
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, List
 

autogalaxy/aggregator/interferometer/interferometer.py

@@ -1,3 +1,20 @@
+"""
+Aggregator interface for loading ``Interferometer`` datasets from model-fit results.
+
+After an interferometer model-fit the dataset (complex visibilities, noise-map,
+uv-wavelengths, real-space mask, and transformer class) is written to a FITS file in
+the output directory or SQLite database.  This module reconstructs a fully-configured
+``aa.Interferometer`` object from those stored files.
+
+Two public objects are provided:
+
+- ``_interferometer_from`` — a free function that accepts a single ``PyAutoFit`` ``Fit``
+  entry and returns a list of ``aa.Interferometer`` datasets (one per summed
+  ``Analysis``).
+- ``InterferometerAgg`` — a class wrapping an ``Aggregator`` that returns a lazy
+  generator of ``Interferometer`` datasets, avoiding loading all results into memory at
+  once.
+"""
 from functools import partial
 from typing import List