phenoforge 0.1.2__tar.gz

phenoforge-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Santibanez-Leal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phenoforge-0.1.2/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: phenoforge
+Version: 0.1.2
+Summary: Phenomenological model-family bank and ensemble calibration engine for industrial processes (BAPE: Bootstrap-Aggregated Phenomenological Ensembles)
+Author-email: Felipe Santibanez-Leal <fsantibanez@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/fsantibanezleal/CAOS_PhenoForge
+Keywords: phenomenological-models,ensemble,model-averaging,mineral-processing,flotation,uncertainty-quantification,bootstrap,stacking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# phenoforge
+
+Phenomenological model-family bank and ensemble calibration engine for industrial
+processes. The reference implementation of **BAPE (Bootstrap-Aggregated
+Phenomenological Ensembles)**: instead of selecting one phenomenological model for a
+process dataset, fit many realizations (model families x parameter multistarts x
+bootstrap resamples) from a curated family bank and aggregate them into a calibrated
+ensemble with structural inclusion probabilities.
+
+Consumed by the Fragua research product (`CAOS_RES_Fragua`); designed as a
+standalone, domain-agnostic library. The core is pure numpy/scipy (Pyodide-safe).
+
+## What it provides
+
+- **A family bank** (`phenoforge.families`): named, cited, bounded phenomenological
+  models with physical parameter ranges and declared calibration-data contracts.
+  Shipping now: the flotation kinetics zoo (Garcia-Zuniga first-order, Klimpel,
+  Kelsall, modified Kelsall, gamma rate distribution, second-order, fully mixed, bank
+  of N mixers) and the comminution energy-size laws (Rittinger, Kick, Bond, Morrell
+  Mi). The bank grows with the Fragua build (thickening, leaching, utilities, PBM).
+- **Fitting** (`phenoforge.fit`): bounded multistart trust-region nonlinear least
+  squares per family; information criteria (AIC/AICc/BIC) on every fit.
+- **Ensembles** (`phenoforge.ensemble`):
+  - `select` / `akaike_weights` / `averaged_prediction`: IC selection and multimodel
+    averaging (Burnham-Anderson).
+  - `glue_fit`: GLUE behavioural parameter-set ensembles (Beven-Binley).
+  - `bootstrap_fit`: bagging/bragging of one family (paired or moving-block).
+  - `stack_fit`: cross-validated convex stacking over the bank (super-learner
+    recipe; M-open rationale per Yao-Vehtari-Simpson-Gelman).
+  - `bape_fit`: the BAPE ensemble (bootstrap x family-library subsampling, one
+    fitted model per member, inclusion probabilities over families).
+- **Metrics** (`phenoforge.metrics`): point (RMSE/MAE/R2), probabilistic calibration
+  (ensemble CRPS, PIT, interval coverage), and structural readouts (weight entropy,
+  known-truth structural recovery that refuses to run silently null).
+- **Routing** (`phenoforge.route`): match a dataset's declared data kinds to the
+  families they can calibrate.
+
+## Quick start
+
+```python
+import numpy as np
+from phenoforge import list_families
+from phenoforge.families import flotation
+from phenoforge.ensemble import bape_fit
+
+t = np.array([0.5, 1, 2, 4, 8, 12, 16, 20], dtype=float)
+r = 0.85 * (1 - np.exp(-1.2 * t))  # a batch flotation test
+
+ens = bape_fit(flotation.BATCH_FAMILIES, t, r, n_members=200, seed=0)
+print(ens.selection_shares())        # which family explains the data, with what share
+print(ens.quantiles(t))              # calibrated predictive bands
+```
+
+## Method background (primary sources)
+
+- Fasel, Kutz, Brunton, Brunton 2022. Ensemble-SINDy. Proc. R. Soc. A 478:20210904.
+  DOI 10.1098/rspa.2021.0904.
+- Pinto, de Azevedo, Oliveira, von Stosch 2019. Bioprocess Biosyst. Eng.
+  42:1853-1865. DOI 10.1007/s00449-019-02181-y.
+- Duan, Ajami, Gao, Sorooshian 2007. Adv. Water Resour. 30:1371-1386.
+  DOI 10.1016/j.advwatres.2006.11.014.
+- Beven, Binley 1992. Hydrol. Process. 6:279-298; Beven 2006. J. Hydrol. 320:18-36.
+  DOI 10.1016/j.jhydrol.2005.07.007.
+- Yao, Vehtari, Simpson, Gelman 2018. Bayesian Anal. 13:917-1007.
+  DOI 10.1214/17-BA1091.
+- Burnham, Anderson 2004. Sociol. Methods Res. 33:261-304.
+  DOI 10.1177/0049124104268644.
+- Polat, Chander 2000. Int. J. Miner. Process. 58:145-166.
+  DOI 10.1016/S0301-7516(99)00069-1 (flotation family library).
+
+## Development
+
+```
+py -3.12 -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pytest tests -v
+.venv/Scripts/python -m ruff check src tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

phenoforge-0.1.2/README.md

@@ -0,0 +1,82 @@
+# phenoforge
+
+Phenomenological model-family bank and ensemble calibration engine for industrial
+processes. The reference implementation of **BAPE (Bootstrap-Aggregated
+Phenomenological Ensembles)**: instead of selecting one phenomenological model for a
+process dataset, fit many realizations (model families x parameter multistarts x
+bootstrap resamples) from a curated family bank and aggregate them into a calibrated
+ensemble with structural inclusion probabilities.
+
+Consumed by the Fragua research product (`CAOS_RES_Fragua`); designed as a
+standalone, domain-agnostic library. The core is pure numpy/scipy (Pyodide-safe).
+
+## What it provides
+
+- **A family bank** (`phenoforge.families`): named, cited, bounded phenomenological
+  models with physical parameter ranges and declared calibration-data contracts.
+  Shipping now: the flotation kinetics zoo (Garcia-Zuniga first-order, Klimpel,
+  Kelsall, modified Kelsall, gamma rate distribution, second-order, fully mixed, bank
+  of N mixers) and the comminution energy-size laws (Rittinger, Kick, Bond, Morrell
+  Mi). The bank grows with the Fragua build (thickening, leaching, utilities, PBM).
+- **Fitting** (`phenoforge.fit`): bounded multistart trust-region nonlinear least
+  squares per family; information criteria (AIC/AICc/BIC) on every fit.
+- **Ensembles** (`phenoforge.ensemble`):
+  - `select` / `akaike_weights` / `averaged_prediction`: IC selection and multimodel
+    averaging (Burnham-Anderson).
+  - `glue_fit`: GLUE behavioural parameter-set ensembles (Beven-Binley).
+  - `bootstrap_fit`: bagging/bragging of one family (paired or moving-block).
+  - `stack_fit`: cross-validated convex stacking over the bank (super-learner
+    recipe; M-open rationale per Yao-Vehtari-Simpson-Gelman).
+  - `bape_fit`: the BAPE ensemble (bootstrap x family-library subsampling, one
+    fitted model per member, inclusion probabilities over families).
+- **Metrics** (`phenoforge.metrics`): point (RMSE/MAE/R2), probabilistic calibration
+  (ensemble CRPS, PIT, interval coverage), and structural readouts (weight entropy,
+  known-truth structural recovery that refuses to run silently null).
+- **Routing** (`phenoforge.route`): match a dataset's declared data kinds to the
+  families they can calibrate.
+
+## Quick start
+
+```python
+import numpy as np
+from phenoforge import list_families
+from phenoforge.families import flotation
+from phenoforge.ensemble import bape_fit
+
+t = np.array([0.5, 1, 2, 4, 8, 12, 16, 20], dtype=float)
+r = 0.85 * (1 - np.exp(-1.2 * t))  # a batch flotation test
+
+ens = bape_fit(flotation.BATCH_FAMILIES, t, r, n_members=200, seed=0)
+print(ens.selection_shares())        # which family explains the data, with what share
+print(ens.quantiles(t))              # calibrated predictive bands
+```
+
+## Method background (primary sources)
+
+- Fasel, Kutz, Brunton, Brunton 2022. Ensemble-SINDy. Proc. R. Soc. A 478:20210904.
+  DOI 10.1098/rspa.2021.0904.
+- Pinto, de Azevedo, Oliveira, von Stosch 2019. Bioprocess Biosyst. Eng.
+  42:1853-1865. DOI 10.1007/s00449-019-02181-y.
+- Duan, Ajami, Gao, Sorooshian 2007. Adv. Water Resour. 30:1371-1386.
+  DOI 10.1016/j.advwatres.2006.11.014.
+- Beven, Binley 1992. Hydrol. Process. 6:279-298; Beven 2006. J. Hydrol. 320:18-36.
+  DOI 10.1016/j.jhydrol.2005.07.007.
+- Yao, Vehtari, Simpson, Gelman 2018. Bayesian Anal. 13:917-1007.
+  DOI 10.1214/17-BA1091.
+- Burnham, Anderson 2004. Sociol. Methods Res. 33:261-304.
+  DOI 10.1177/0049124104268644.
+- Polat, Chander 2000. Int. J. Miner. Process. 58:145-166.
+  DOI 10.1016/S0301-7516(99)00069-1 (flotation family library).
+
+## Development
+
+```
+py -3.12 -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pytest tests -v
+.venv/Scripts/python -m ruff check src tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

phenoforge-0.1.2/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phenoforge"
+version = "0.1.2"
+description = "Phenomenological model-family bank and ensemble calibration engine for industrial processes (BAPE: Bootstrap-Aggregated Phenomenological Ensembles)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Felipe Santibanez-Leal", email = "fsantibanez@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "scipy>=1.10"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+keywords = ["phenomenological-models", "ensemble", "model-averaging", "mineral-processing", "flotation", "uncertainty-quantification", "bootstrap", "stacking"]
+
+[project.urls]
+Repository = "https://github.com/fsantibanezleal/CAOS_PhenoForge"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.4"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

phenoforge-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phenoforge-0.1.2/src/phenoforge/__init__.py

@@ -0,0 +1,41 @@
+"""phenoforge: phenomenological model-family bank + ensemble calibration engine.
+
+The package implements the BAPE methodology (Bootstrap-Aggregated Phenomenological
+Ensembles): instead of selecting ONE phenomenological model for a process dataset,
+fit MANY realizations (model families x parameter multistarts x bootstrap resamples)
+from a curated family bank and aggregate them into a calibrated ensemble with
+structural inclusion probabilities.
+
+Nearest prior art, cited and differentiated (see the Fragua research dossiers):
+- Fasel, Kutz, Brunton, Brunton 2022, Ensemble-SINDy, Proc. R. Soc. A 478:20210904,
+  DOI 10.1098/rspa.2021.0904 (bagging over generic term libraries).
+- Pinto, de Azevedo, Oliveira, von Stosch 2019, Bioprocess Biosyst. Eng. 42:1853-1865,
+  DOI 10.1007/s00449-019-02181-y (bootstrap-aggregated hybrid models, one family).
+- Duan, Ajami, Gao, Sorooshian 2007, Adv. Water Resour. 30:1371-1386,
+  DOI 10.1016/j.advwatres.2006.11.014 (BMA across model structures, hydrology).
+- Beven, Binley 1992, Hydrol. Process. 6:279-298 (GLUE); Beven 2006,
+  J. Hydrol. 320:18-36, DOI 10.1016/j.jhydrol.2005.07.007 (equifinality).
+- Yao, Vehtari, Simpson, Gelman 2018, Bayesian Anal. 13:917-1007,
+  DOI 10.1214/17-BA1091 (stacking in the M-open setting).
+
+The core is pure numpy/scipy (Pyodide-safe by design).
+"""
+
+__version__ = "0.01.002"
+
+from phenoforge.families.base import DataKind, FitResult, ModelFamily, Param
+from phenoforge.families.registry import get_family, list_families
+from phenoforge.fit.nls import fit_family
+from phenoforge.router import route
+
+__all__ = [
+    "DataKind",
+    "FitResult",
+    "ModelFamily",
+    "Param",
+    "__version__",
+    "fit_family",
+    "get_family",
+    "list_families",
+    "route",
+]

phenoforge-0.1.2/src/phenoforge/ensemble/__init__.py

@@ -0,0 +1,19 @@
+from phenoforge.ensemble.bape import BapeEnsemble, bape_fit
+from phenoforge.ensemble.bootstrap import BootstrapEnsemble, bootstrap_fit
+from phenoforge.ensemble.glue import GlueEnsemble, glue_fit
+from phenoforge.ensemble.ic import akaike_weights, averaged_prediction, select
+from phenoforge.ensemble.stacking import StackedEnsemble, stack_fit
+
+__all__ = [
+    "BapeEnsemble",
+    "BootstrapEnsemble",
+    "GlueEnsemble",
+    "StackedEnsemble",
+    "akaike_weights",
+    "averaged_prediction",
+    "bape_fit",
+    "bootstrap_fit",
+    "glue_fit",
+    "select",
+    "stack_fit",
+]

phenoforge-0.1.2/src/phenoforge/ensemble/bape.py

@@ -0,0 +1,172 @@
+"""BAPE: Bootstrap-Aggregated Phenomenological Ensembles (rung 6, the novel method).
+
+The random-forest recipe with phenomenological model families as base learners:
+
+- Each ensemble MEMBER sees (a) a bootstrap resample of the data (the bagging axis,
+  Breiman 1996) and (b) a random SUBSET of the family library (the feature-subsampling
+  analog applied to equation structure; in E-SINDy this is "library bagging" over
+  candidate terms, Fasel et al. 2022, DOI 10.1098/rspa.2021.0904; here it operates
+  over whole curated families).
+- Within its subset, the member fits every family and keeps the AICc-best fit (one
+  member = one fitted phenomenological model, the way one random-forest member is one
+  tree).
+- The ensemble aggregates member predictions (mean/median/quantiles) and reads
+  STRUCTURE off the member population: the inclusion probability of a family is the
+  fraction of members that selected it (the E-SINDy inclusion-probability readout
+  lifted from terms to families).
+
+Differentiation from prior art (all cited in the package docstring): E-SINDy bags
+sparse regressions over generic term libraries; Pinto et al. 2019 bags ONE hybrid
+structure; BMA/stacking weight given models without resampling; GLUE keeps parameter
+sets of given structures. BAPE crosses the family axis with the bootstrap axis.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from phenoforge.ensemble.bootstrap import bootstrap_indices
+from phenoforge.families.base import FitResult, ModelFamily
+from phenoforge.fit.nls import fit_family
+
+
+@dataclass
+class BapeMember:
+    family: ModelFamily
+    fit: FitResult
+    boot_index: int
+    subset_keys: tuple[str, ...]
+
+
+@dataclass
+class BapeEnsemble:
+    families: tuple[ModelFamily, ...]
+    members: list[BapeMember]
+    requested: int
+    meta: dict = field(default_factory=dict)
+
+    @property
+    def kept(self) -> int:
+        return len(self.members)
+
+    def member_predictions(self, x: np.ndarray) -> np.ndarray:
+        return np.stack([m.family.predict(x, m.fit.theta) for m in self.members])
+
+    def predict(self, x: np.ndarray, aggregate: str = "mean") -> np.ndarray:
+        m = self.member_predictions(x)
+        if aggregate == "mean":
+            return m.mean(axis=0)
+        if aggregate == "median":
+            return np.median(m, axis=0)
+        raise ValueError("aggregate must be 'mean' or 'median'")
+
+    def quantiles(
+        self, x: np.ndarray, qs: tuple[float, ...] = (0.05, 0.25, 0.5, 0.75, 0.95)
+    ) -> np.ndarray:
+        return np.quantile(self.member_predictions(x), qs, axis=0)
+
+    def inclusion_probabilities(self) -> dict[str, float]:
+        """P(family selected | member), the structural-uncertainty readout.
+
+        Normalizing by the number of members in which the family was OFFERED (it was
+        in the member's random subset) rather than by all members, so a family is not
+        penalized for having been absent from a member's menu.
+        """
+        offered: dict[str, int] = {f.key: 0 for f in self.families}
+        selected: dict[str, int] = {f.key: 0 for f in self.families}
+        for m in self.members:
+            for key in m.subset_keys:
+                offered[key] += 1
+            selected[m.family.key] += 1
+        return {
+            k: (selected[k] / offered[k]) if offered[k] > 0 else 0.0 for k in offered
+        }
+
+    def selection_shares(self) -> dict[str, float]:
+        """Fraction of members won by each family (sums to 1)."""
+        shares: dict[str, int] = {f.key: 0 for f in self.families}
+        for m in self.members:
+            shares[m.family.key] += 1
+        total = max(self.kept, 1)
+        return {k: v / total for k, v in shares.items()}
+
+
+def bape_fit(
+    families: tuple[ModelFamily, ...],
+    x: np.ndarray,
+    y: np.ndarray,
+    *,
+    n_members: int = 200,
+    subset_size: int | None = None,
+    seed: int = 0,
+    block: int | None = None,
+    n_starts: int = 6,
+    criterion: str = "aicc",
+) -> BapeEnsemble:
+    """Fit a BAPE ensemble over the bank.
+
+    subset_size defaults to ceil(sqrt(len(families))) + 1, the random-forest
+    heuristic adapted to small libraries (guarantees >= 2 families per member when
+    the bank has >= 2).
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = y.shape[0]
+    n_fam = len(families)
+    if n_fam == 0:
+        raise ValueError("empty family bank")
+    if subset_size is None:
+        subset_size = min(n_fam, int(np.ceil(np.sqrt(n_fam))) + 1)
+    subset_size = max(1, min(subset_size, n_fam))
+
+    rng = np.random.default_rng(seed)
+    idx = bootstrap_indices(n, n_members, rng, block=block)
+
+    members: list[BapeMember] = []
+    for b in range(n_members):
+        xb, yb = x[idx[b]], y[idx[b]]
+        chosen = rng.choice(n_fam, size=subset_size, replace=False)
+        subset = tuple(families[int(c)] for c in chosen)
+        fits: list[tuple[ModelFamily, FitResult]] = []
+        for j, fam in enumerate(subset):
+            res = fit_family(
+                fam, xb, yb, n_starts=n_starts, seed=seed + 104729 * (b + 1) + j
+            )
+            if res.success and np.isfinite(res.rss):
+                fits.append((fam, res))
+        # coherent per-member criterion: preferred unless it is +inf for every
+        # candidate in this member's menu (tiny resamples), then BIC for all
+        crit = criterion
+        if fits and not any(np.isfinite(getattr(r, criterion)) for _, r in fits):
+            crit = "bic"
+        best: tuple[ModelFamily, FitResult] | None = None
+        best_val = float("inf")
+        for fam, res in fits:
+            val = getattr(res, crit)
+            if np.isfinite(val) and val < best_val:
+                best_val = val
+                best = (fam, res)
+        if best is not None:
+            members.append(
+                BapeMember(
+                    family=best[0],
+                    fit=best[1],
+                    boot_index=b,
+                    subset_keys=tuple(f.key for f in subset),
+                )
+            )
+
+    return BapeEnsemble(
+        families=families,
+        members=members,
+        requested=n_members,
+        meta={
+            "subset_size": subset_size,
+            "criterion": criterion,
+            "seed": seed,
+            "block": block,
+            "n_starts": n_starts,
+        },
+    )

phenoforge-0.1.2/src/phenoforge/ensemble/bootstrap.py

@@ -0,0 +1,98 @@
+"""Bootstrap-aggregated fits of one family (rung 5 substrate).
+
+Paired (case) bootstrap for independent observations and a moving-block bootstrap for
+serially correlated data (plant time series). Aggregation by mean (bagging, Breiman
+1996) or median (bragging, the E-SINDy usage: Fasel et al. 2022,
+DOI 10.1098/rspa.2021.0904). The single-family bootstrap generalizes the mechanism of
+Pinto et al. 2019 (DOI 10.1007/s00449-019-02181-y) beyond one hybrid structure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from phenoforge.families.base import FitResult, ModelFamily
+from phenoforge.fit.nls import fit_family
+
+
+def bootstrap_indices(
+    n: int, n_boot: int, rng: np.random.Generator, block: int | None = None
+) -> np.ndarray:
+    """(n_boot, n) resample index matrix; block > 1 switches to moving-block."""
+    if block is None or block <= 1:
+        return rng.integers(0, n, size=(n_boot, n))
+    n_blocks = int(np.ceil(n / block))
+    starts = rng.integers(0, max(n - block + 1, 1), size=(n_boot, n_blocks))
+    idx = (starts[:, :, None] + np.arange(block)[None, None, :]).reshape(n_boot, -1)
+    return idx[:, :n]
+
+
+@dataclass
+class BootstrapEnsemble:
+    """Fitted bootstrap fleet of ONE family."""
+
+    family: ModelFamily
+    fits: list[FitResult]
+    kept: int
+    requested: int
+    meta: dict = field(default_factory=dict)
+
+    def thetas(self) -> np.ndarray:
+        return np.stack([f.theta for f in self.fits])
+
+    def member_predictions(self, x: np.ndarray) -> np.ndarray:
+        """(n_members, n_x) member prediction matrix."""
+        return np.stack([self.family.predict(x, f.theta) for f in self.fits])
+
+    def predict(self, x: np.ndarray, aggregate: str = "mean") -> np.ndarray:
+        m = self.member_predictions(x)
+        if aggregate == "mean":
+            return m.mean(axis=0)
+        if aggregate == "median":
+            return np.median(m, axis=0)
+        raise ValueError("aggregate must be 'mean' (bagging) or 'median' (bragging)")
+
+    def quantiles(
+        self, x: np.ndarray, qs: tuple[float, ...] = (0.05, 0.25, 0.5, 0.75, 0.95)
+    ) -> np.ndarray:
+        return np.quantile(self.member_predictions(x), qs, axis=0)
+
+
+def bootstrap_fit(
+    family: ModelFamily,
+    x: np.ndarray,
+    y: np.ndarray,
+    *,
+    n_boot: int = 200,
+    seed: int = 0,
+    block: int | None = None,
+    n_starts: int = 6,
+) -> BootstrapEnsemble:
+    """Fit `family` on n_boot bootstrap resamples of (x, y).
+
+    Members whose fit fails (non-finite RSS) are dropped and COUNTED: `kept` vs
+    `requested` is part of the record, never silently equalized.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = y.shape[0]
+    rng = np.random.default_rng(seed)
+    idx = bootstrap_indices(n, n_boot, rng, block=block)
+
+    fits: list[FitResult] = []
+    for b in range(n_boot):
+        xb, yb = x[idx[b]], y[idx[b]]
+        res = fit_family(family, xb, yb, n_starts=n_starts, seed=seed + 7919 * (b + 1))
+        if res.success and np.isfinite(res.rss):
+            res.meta["boot_index"] = b
+            fits.append(res)
+
+    return BootstrapEnsemble(
+        family=family,
+        fits=fits,
+        kept=len(fits),
+        requested=n_boot,
+        meta={"block": block, "seed": seed},
+    )