autogluon.timeseries 1.4.1b20250830__py3-none-any.whl → 1.4.1b20251116__py3-none-any.whl

autogluon/timeseries/models/toto/model.py

@@ -0,0 +1,236 @@
+import logging
+import os
+from typing import TYPE_CHECKING, Any, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+from typing_extensions import Self
+
+from autogluon.common.loaders import load_pkl
+from autogluon.timeseries import TimeSeriesDataFrame
+from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
+from autogluon.timeseries.utils.features import CovariateMetadata
+
+if TYPE_CHECKING:
+    from ._internal import TotoForecaster
+
+logger = logging.getLogger(__name__)
+
+
+class TotoModel(AbstractTimeSeriesModel):
+    """Toto (Time-Series-Optimized Transformer for Observability) [CohenKhwajaetal2025]_ pretrained time series forecasting model.
+
+    Toto is a 151M parameter model trained on over 1T data points from DataDog's internal observability systems, as well as
+    the GIFT-eval pretrain, Chronos pretraining, and synthetically generated time series corpora. It is a decoder-only
+    architecture that autoregressively outputs parametric distribution forecasts. More details can be found on
+    `Hugging Face <https://huggingface.co/Datadog/Toto-Open-Base-1.0>`_ and `GitHub <https://github.com/DataDog/toto>`_.
+
+    The AutoGluon implementation of Toto is on a port of the original implementation. AutoGluon supports Toto for
+    **inference only**, i.e., the model will not be trained or fine-tuned on the provided training data. Toto is optimized
+    for easy maintenance with the rest of the AutoGluon model zoo, and does not feature some important optimizations such
+    as xformers and flash-attention available in the original model repository. The AutoGluon implementation of Toto
+    requires a CUDA-compatible GPU.
+
+    References
+    ----------
+    .. [CohenKhwajaetal2025] Cohen, Ben, Khwaja, Emaad et al.
+        "This Time is Different: An Observability Perspective on Time Series Foundation Models."
+        https://arxiv.org/abs/2505.14766
+
+
+    Other Parameters
+    ----------------
+    model_path : str, default = "Datadog/Toto-Open-Base-1.0"
+        Model path used for the model, i.e., a HuggingFace transformers ``name_or_path``. Can be a
+        compatible model name on HuggingFace Hub or a local path to a model directory.
+    batch_size : int, default = 24
+        Size of batches used during inference.
+    num_samples : int, default = 256
+        Number of samples used during inference.
+    device : str, default = "cuda"
+        Device to use for inference. Toto requires a CUDA-compatible GPU to run.
+    context_length : int or None, default = 4096
+        The context length to use in the model. Shorter context lengths will decrease model accuracy, but result
+        in faster inference.
+    compile_model : bool, default = True
+        Whether to compile the model using torch.compile() for faster inference. May increase initial loading time
+        but can provide speedups during inference.
+    """
+
+    default_model_path: str = "Datadog/Toto-Open-Base-1.0"
+
+    def __init__(
+        self,
+        path: Optional[str] = None,
+        name: Optional[str] = None,
+        hyperparameters: Optional[dict[str, Any]] = None,
+        freq: Optional[str] = None,
+        prediction_length: int = 1,
+        covariate_metadata: Optional[CovariateMetadata] = None,
+        target: str = "target",
+        quantile_levels: Sequence[float] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9),
+        eval_metric: Any = None,
+    ):
+        hyperparameters = hyperparameters if hyperparameters is not None else {}
+
+        self.model_path = hyperparameters.get("model_path", self.default_model_path)
+
+        super().__init__(
+            path=path,
+            name=name,
+            hyperparameters=hyperparameters,
+            freq=freq,
+            prediction_length=prediction_length,
+            covariate_metadata=covariate_metadata,
+            target=target,
+            quantile_levels=quantile_levels,
+            eval_metric=eval_metric,
+        )
+
+        self._forecaster: Optional[TotoForecaster] = None
+
+    def save(self, path: Optional[str] = None, verbose: bool = True) -> str:
+        forecaster = self._forecaster
+        self._forecaster = None
+        path = super().save(path=path, verbose=verbose)
+        self._forecaster = forecaster
+
+        return str(path)
+
+    @classmethod
+    def load(cls, path: str, reset_paths: bool = True, load_oof: bool = False, verbose: bool = True) -> Self:
+        model = load_pkl.load(path=os.path.join(path, cls.model_file_name), verbose=verbose)
+        if reset_paths:
+            model.set_contexts(path)
+
+        return model
+
+    def _is_gpu_available(self) -> bool:
+        import torch.cuda
+
+        return torch.cuda.is_available()
+
+    def get_minimum_resources(self, is_gpu_available: bool = False) -> dict[str, Union[int, float]]:
+        return {"num_cpus": 1, "num_gpus": 1}
+
+    def load_forecaster(self):
+        from ._internal import TotoForecaster
+        from .hf_pretrained_model import TotoConfig, TotoPretrainedModel
+
+        if not self._is_gpu_available():
+            raise RuntimeError(
+                f"{self.name} requires a GPU to run, but no GPU was detected. "
+                "Please make sure that you are using a computer with a CUDA-compatible GPU and "
+                "`import torch; torch.cuda.is_available()` returns `True`."
+            )
+
+        hyperparameters = self.get_hyperparameters()
+        pretrained_model = TotoPretrainedModel.from_pretrained(
+            self.model_path,
+            config=TotoConfig.from_pretrained(self.model_path),
+            device_map=hyperparameters["device"],
+        )
+
+        if hyperparameters["compile_model"]:
+            pretrained_model.model.compile()
+
+        self._forecaster = TotoForecaster(model=pretrained_model.model)
+
+    def persist(self) -> Self:
+        if self._forecaster is None:
+            self.load_forecaster()
+        return self
+
+    def _get_default_hyperparameters(self) -> dict:
+        return {
+            "batch_size": 24,
+            "num_samples": 256,
+            "device": "cuda",
+            "context_length": 4096,
+            "compile_model": True,
+        }
+
+    @property
+    def allowed_hyperparameters(self) -> list[str]:
+        return super().allowed_hyperparameters + [
+            "model_path",
+            "batch_size",
+            "num_samples",
+            "device",
+            "context_length",
+            "compile_model",
+        ]
+
+    def _more_tags(self) -> dict:
+        return {
+            "allow_nan": True,
+            "can_use_train_data": False,
+            "can_use_val_data": False,
+        }
+
+    def _fit(
+        self,
+        train_data: TimeSeriesDataFrame,
+        val_data: Optional[TimeSeriesDataFrame] = None,
+        time_limit: Optional[float] = None,
+        num_cpus: Optional[int] = None,
+        num_gpus: Optional[int] = None,
+        verbosity: int = 2,
+        **kwargs,
+    ) -> None:
+        self._check_fit_params()
+        self.load_forecaster()
+
+    def _predict(
+        self, data: TimeSeriesDataFrame, known_covariates: Optional[TimeSeriesDataFrame] = None, **kwargs
+    ) -> TimeSeriesDataFrame:
+        import torch
+
+        from .dataloader import TotoDataLoader, TotoInferenceDataset
+
+        hyperparameters = self.get_hyperparameters()
+
+        if self._forecaster is None:
+            self.load_forecaster()
+        assert self._forecaster, "Toto model failed to load"
+        device = self._forecaster.model.device
+
+        dataset = TotoInferenceDataset(
+            target_df=data.fill_missing_values("auto"),
+            max_context_length=hyperparameters["context_length"],
+        )
+        loader = TotoDataLoader(
+            dataset,
+            freq=self.freq,
+            batch_size=hyperparameters["batch_size"],
+            time_limit=kwargs.get("time_limit"),
+            device=device,
+        )
+
+        batch_means, batch_quantiles = [], []
+        with torch.inference_mode():
+            for masked_timeseries in loader:
+                forecast = self._forecaster.forecast(
+                    masked_timeseries,
+                    prediction_length=self.prediction_length,
+                    num_samples=hyperparameters["num_samples"],
+                    samples_per_batch=32,
+                )
+
+                batch_means.append(forecast.mean.cpu().numpy())
+                qs = np.array([forecast.quantile(q).cpu().numpy() for q in self.quantile_levels])
+                batch_quantiles.append(qs.squeeze(2).transpose(1, 2, 0))
+
+        df = pd.DataFrame(
+            np.concatenate(
+                [
+                    np.concatenate(batch_means, axis=0).reshape(-1, 1),
+                    np.concatenate(batch_quantiles, axis=0).reshape(-1, len(self.quantile_levels)),
+                ],
+                axis=1,
+            ),
+            columns=["mean"] + [str(q) for q in self.quantile_levels],
+            index=self.get_forecast_horizon_index(data),
+        )
+
+        return TimeSeriesDataFrame(df)

autogluon/timeseries/predictor.py

@@ -22,10 +22,9 @@ from autogluon.core.utils.loaders import load_pkl, load_str
 from autogluon.core.utils.savers import save_pkl, save_str
 from autogluon.timeseries import __version__ as current_ag_version
 from autogluon.timeseries.configs import get_predictor_presets
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.learner import TimeSeriesLearner
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
-from autogluon.timeseries.splitter import ExpandingWindowSplitter
 from autogluon.timeseries.trainer import TimeSeriesTrainer
 from autogluon.timeseries.utils.forecast import make_future_data_frame
 
@@ -221,20 +220,6 @@ class TimeSeriesPredictor:
             ensemble_model_type=kwargs.pop("ensemble_model_type", None),
         )
 
-        if "ignore_time_index" in kwargs:
-            raise TypeError(
-                "`ignore_time_index` argument to TimeSeriesPredictor.__init__() has been deprecated.\n"
-                "If your data has irregular timestamps, please either 1) specify the desired regular frequency when "
-                "creating the predictor as `TimeSeriesPredictor(freq=...)` or 2) manually convert timestamps to "
-                "regular frequency with `data.convert_frequency(freq=...)`."
-            )
-        for k in ["learner_type", "learner_kwargs"]:
-            if k in kwargs:
-                val = kwargs.pop(k)
-                logger.warning(
-                    f"Passing `{k}` to TimeSeriesPredictor has been deprecated and will be removed in v1.4. "
-                    f"The provided value {val} will be ignored."
-                )
         if len(kwargs) > 0:
             for key in kwargs:
                 raise TypeError(f"TimeSeriesPredictor.__init__() got an unexpected keyword argument '{key}'")
@@ -417,7 +402,9 @@ class TimeSeriesPredictor:
             )
             train_data = train_data.query("item_id not in @too_short_items")
 
-        all_nan_items = train_data.item_ids[train_data[self.target].isna().groupby(ITEMID, sort=False).all()]
+        all_nan_items = train_data.item_ids[
+            train_data[self.target].isna().groupby(TimeSeriesDataFrame.ITEMID, sort=False).all()
+        ]
         if len(all_nan_items) > 0:
             logger.info(f"\tRemoving {len(all_nan_items)} time series consisting of only NaN values from train_data.")
             train_data = train_data.query("item_id not in @all_nan_items")
@@ -751,10 +738,6 @@ class TimeSeriesPredictor:
                 train_data, num_val_windows=num_val_windows, val_step_size=val_step_size
             )
 
-        val_splitter = ExpandingWindowSplitter(
-            prediction_length=self.prediction_length, num_val_windows=num_val_windows, val_step_size=val_step_size
-        )
-
         time_left = None if time_limit is None else time_limit - (time.time() - time_start)
         self._learner.fit(
             train_data=train_data,
@@ -764,7 +747,8 @@ class TimeSeriesPredictor:
             excluded_model_types=excluded_model_types,
             time_limit=time_left,
             verbosity=verbosity,
-            val_splitter=val_splitter,
+            num_val_windows=num_val_windows,
+            val_step_size=val_step_size,
             refit_every_n_windows=refit_every_n_windows,
             skip_model_selection=skip_model_selection,
             enable_ensemble=enable_ensemble,
@@ -866,7 +850,7 @@ class TimeSeriesPredictor:
             use_cache=use_cache,
             random_seed=random_seed,
         )
-        return cast(TimeSeriesDataFrame, predictions.reindex(original_item_id_order, level=ITEMID))
+        return cast(TimeSeriesDataFrame, predictions.reindex(original_item_id_order, level=TimeSeriesDataFrame.ITEMID))
 
     def evaluate(
         self,
@@ -1498,7 +1482,7 @@ class TimeSeriesPredictor:
         )
 
         y_val: list[TimeSeriesDataFrame] = [
-            select_target(df) for df in trainer._get_ensemble_oof_data(train_data=train_data, val_data=val_data)
+            select_target(df) for df in trainer._get_validation_windows(train_data=train_data, val_data=val_data)
         ]
         y_test: TimeSeriesDataFrame = select_target(test_data)
 
@@ -1621,7 +1605,7 @@ class TimeSeriesPredictor:
                         for q in quantile_levels:
                             ax.fill_between(forecast.index, point_forecast, forecast[str(q)], color="C1", alpha=0.2)
             if len(axes) > len(item_ids):
-                axes[len(item_ids)].set_axis_off()
-            handles, labels = axes[0].get_legend_handles_labels()
+                axes[len(item_ids)].set_axis_off()  # type: ignore
+            handles, labels = axes[0].get_legend_handles_labels()  # type: ignore
             fig.legend(handles, labels, bbox_to_anchor=(0.5, 0.0), ncols=len(handles))
         return fig

autogluon/timeseries/regressor.py

@@ -7,7 +7,7 @@ import pandas as pd
 
 from autogluon.core.models import AbstractModel
 from autogluon.tabular.registry import ag_model_registry as tabular_ag_model_registry
-from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.utils.features import CovariateMetadata
 
 logger = logging.getLogger(__name__)
@@ -119,9 +119,9 @@ class GlobalCovariateRegressor(CovariateRegressor):
         median_ts_length = data.num_timesteps_per_item().median()
         features_to_drop = [self.target]
         if not self.include_item_id:
-            features_to_drop += [ITEMID]
+            features_to_drop += [TimeSeriesDataFrame.ITEMID]
         if self.validation_fraction is not None:
-            grouped_df = tabular_df.groupby(ITEMID, observed=False, sort=False)
+            grouped_df = tabular_df.groupby(TimeSeriesDataFrame.ITEMID, observed=False, sort=False)
             val_size = max(int(self.validation_fraction * median_ts_length), 1)
             train_df = self._subsample_df(grouped_df.head(-val_size))
             val_df = self._subsample_df(grouped_df.tail(val_size))
@@ -201,7 +201,7 @@ class GlobalCovariateRegressor(CovariateRegressor):
         assert self.model is not None, "CovariateRegressor must be fit before calling predict."
         tabular_df = self._get_tabular_df(data, static_features=static_features)
         if not self.include_item_id:
-            tabular_df = tabular_df.drop(columns=[ITEMID])
+            tabular_df = tabular_df.drop(columns=[TimeSeriesDataFrame.ITEMID])
         return self.model.predict(X=tabular_df)
 
     def _get_tabular_df(
@@ -211,12 +211,14 @@ class GlobalCovariateRegressor(CovariateRegressor):
         include_target: bool = False,
     ) -> pd.DataFrame:
         """Construct a tabular dataframe from known covariates and static features."""
-        available_columns = [ITEMID] + self.covariate_metadata.known_covariates
+        available_columns = [TimeSeriesDataFrame.ITEMID] + self.covariate_metadata.known_covariates
         if include_target:
             available_columns += [self.target]
-        tabular_df = pd.DataFrame(data).reset_index()[available_columns].astype({ITEMID: "category"})
+        tabular_df = (
+            pd.DataFrame(data).reset_index()[available_columns].astype({TimeSeriesDataFrame.ITEMID: "category"})
+        )
         if static_features is not None and self.include_static_features:
-            tabular_df = pd.merge(tabular_df, static_features, on=ITEMID)
+            tabular_df = pd.merge(tabular_df, static_features, on=TimeSeriesDataFrame.ITEMID)
         return tabular_df
 
     def _subsample_df(self, df: pd.DataFrame) -> pd.DataFrame:

autogluon/timeseries/splitter.py

@@ -1,6 +1,6 @@
 from typing import Iterator, Optional
 
-from .dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 
 __all__ = [
     "AbstractWindowSplitter",
@@ -57,27 +57,3 @@ class ExpandingWindowSplitter(AbstractWindowSplitter):
             train_data = data.slice_by_timestep(None, train_end)
             val_data = data.slice_by_timestep(None, val_end)
             yield train_data, val_data
-
-
-class AbstractTimeSeriesSplitter:
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`AbstractTimeSeriesSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )
-
-
-class MultiWindowSplitter(AbstractTimeSeriesSplitter):
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`MultiWindowSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )
-
-
-class LastWindowSplitter(MultiWindowSplitter):
-    def __init__(self, *args, **kwargs):
-        raise ValueError(
-            "`LastWindowSplitter` has been deprecated. "
-            "Please use `autogluon.timeseries.splitter.ExpandingWindowSplitter` instead."
-        )

autogluon/timeseries/trainer/ensemble_composer.py

@@ -0,0 +1,250 @@
+import logging
+import os
+import time
+import traceback
+from typing import Iterator, Optional
+
+import networkx as nx
+import numpy as np
+from typing_extensions import Self
+
+from autogluon.timeseries import TimeSeriesDataFrame
+from autogluon.timeseries.metrics import TimeSeriesScorer
+from autogluon.timeseries.models.ensemble import AbstractTimeSeriesEnsembleModel, get_ensemble_class
+from autogluon.timeseries.splitter import AbstractWindowSplitter
+from autogluon.timeseries.utils.warning_filters import warning_filter
+
+from .utils import log_scores_and_times
+
+logger = logging.getLogger("autogluon.timeseries.trainer")
+
+
+class EnsembleComposer:
+    """Helper class for TimeSeriesTrainer to build multi-layer stack ensembles."""
+
+    def __init__(
+        self,
+        path,
+        prediction_length: int,
+        eval_metric: TimeSeriesScorer,
+        target: str,
+        quantile_levels: list[float],
+        model_graph: nx.DiGraph,
+        ensemble_hyperparameters: dict,
+        window_splitter: AbstractWindowSplitter,
+    ):
+        self.eval_metric = eval_metric
+        self.path = path
+        self.prediction_length = prediction_length
+        self.target = target
+        self.quantile_levels = quantile_levels
+
+        self.ensemble_hyperparameters = ensemble_hyperparameters
+
+        self.window_splitter = window_splitter
+
+        self.banned_model_names = list(model_graph.nodes)
+        self.model_graph = self._get_base_model_graph(source_graph=model_graph)
+
+    @staticmethod
+    def _get_base_model_graph(source_graph: nx.DiGraph) -> nx.DiGraph:
+        """Return a model graph by copying only base models (nodes without predecessors)
+        This ensures we start fresh for ensemble building.
+        """
+        rootset = EnsembleComposer._get_rootset(source_graph)
+
+        dst_graph = nx.DiGraph()
+        for node in rootset:
+            dst_graph.add_node(node, **source_graph.nodes[node])
+
+        return dst_graph
+
+    @staticmethod
+    def _get_rootset(graph: nx.DiGraph) -> list[str]:
+        return [n for n in graph.nodes if not list(graph.predecessors(n))]
+
+    def iter_ensembles(self) -> Iterator[tuple[int, AbstractTimeSeriesEnsembleModel, list[str]]]:
+        """Iterate over trained ensemble models, layer by layer.
+
+        Yields
+        ------
+        layer_ix
+            The layer index of the ensemble.
+        model
+            The ensemble model object
+        base_model_names
+            The names of the base models that are part of the ensemble.
+        """
+        rootset = self._get_rootset(self.model_graph)
+
+        for layer_ix, layer in enumerate(nx.traversal.bfs_layers(self.model_graph, rootset)):
+            if layer_ix == 0:  # we don't need base models
+                continue
+
+            for model_name in layer:
+                attrs = self.model_graph.nodes[model_name]
+                model_path = os.path.join(self.path, *attrs["path"])
+                model = attrs["type"].load(path=model_path)
+
+                yield (
+                    layer_ix,
+                    model,
+                    list(self.model_graph.predecessors(model_name)),
+                )
+
+    def fit(
+        self,
+        train_data: TimeSeriesDataFrame,
+        val_data: Optional[TimeSeriesDataFrame] = None,
+        time_limit: Optional[float] = None,
+    ) -> Self:
+        base_model_scores = {k: self.model_graph.nodes[k]["val_score"] for k in self.model_graph.nodes}
+        model_names = list(base_model_scores.keys())
+
+        if not self._can_fit_ensemble(time_limit, len(model_names)):
+            return self
+
+        logger.info(f"Fitting {len(self.ensemble_hyperparameters)} ensemble(s).")
+
+        # get target and base model prediction data for ensemble training
+        data_per_window = self._get_validation_windows(train_data=train_data, val_data=val_data)
+        predictions_per_window = self._get_base_model_predictions(model_names)
+
+        for ensemble_name, ensemble_hp_dict in self.ensemble_hyperparameters.items():
+            try:
+                time_start = time.monotonic()
+                ensemble_class = get_ensemble_class(ensemble_name)
+                ensemble = ensemble_class(
+                    eval_metric=self.eval_metric,
+                    target=self.target,
+                    prediction_length=self.prediction_length,
+                    path=self.path,
+                    freq=data_per_window[0].freq,
+                    quantile_levels=self.quantile_levels,
+                    hyperparameters=ensemble_hp_dict,
+                )
+                # update name to prevent name collisions
+                ensemble.name = self._get_ensemble_model_name(ensemble.name)
+
+                with warning_filter():
+                    ensemble.fit(
+                        predictions_per_window=predictions_per_window,
+                        data_per_window=data_per_window,
+                        model_scores=base_model_scores,
+                        time_limit=time_limit,
+                    )
+                ensemble.fit_time = time.monotonic() - time_start
+
+                score_per_fold = []
+                for window_idx, data in enumerate(data_per_window):
+                    predictions = ensemble.predict(
+                        {n: predictions_per_window[n][window_idx] for n in ensemble.model_names}
+                    )
+                    score_per_fold.append(self.eval_metric.score(data, predictions, self.target))
+                ensemble.val_score = float(np.mean(score_per_fold, dtype=np.float64))
+
+                # TODO: add ensemble's own time to predict_time
+                ensemble.predict_time = self._calculate_base_models_predict_time(ensemble.model_names)
+
+                log_scores_and_times(
+                    ensemble.val_score,
+                    ensemble.fit_time,
+                    ensemble.predict_time,
+                    eval_metric_name=self.eval_metric.name_with_sign,
+                )
+
+                self._add_model(ensemble, base_models=ensemble.model_names)
+
+                # Save the ensemble model to disk
+                ensemble.save()
+            except Exception as err:  # noqa
+                logger.error(
+                    f"\tWarning: Exception caused {ensemble_name} to fail during training... Skipping this model."
+                )
+                logger.error(f"\t{err}")
+                logger.debug(traceback.format_exc())
+
+        return self
+
+    def _add_model(self, model, base_models: list[str]):
+        self.model_graph.add_node(
+            model.name,
+            path=os.path.relpath(model.path, self.path).split(os.sep),
+            type=type(model),
+            fit_time=model.fit_time,
+            predict_time=model.predict_time,
+            val_score=model.val_score,
+        )
+        for base_model in base_models:
+            self.model_graph.add_edge(base_model, model.name)
+
+    def _can_fit_ensemble(
+        self,
+        time_limit: Optional[float],
+        num_models_available_for_ensemble: int,
+    ) -> bool:
+        if time_limit is not None and time_limit <= 0:
+            logger.info(f"Not fitting ensemble due to lack of time remaining. Time left: {time_limit:.1f} seconds")
+            return False
+
+        if num_models_available_for_ensemble <= 1:
+            logger.info(
+                "Not fitting ensemble as "
+                + (
+                    "no models were successfully trained."
+                    if not num_models_available_for_ensemble
+                    else "only 1 model was trained."
+                )
+            )
+            return False
+
+        return True
+
+    def _get_validation_windows(
+        self, train_data: TimeSeriesDataFrame, val_data: Optional[TimeSeriesDataFrame]
+    ) -> list[TimeSeriesDataFrame]:
+        # TODO: update for window/stack-layer logic and refit logic
+        if val_data is None:
+            return [val_fold for _, val_fold in self.window_splitter.split(train_data)]
+        else:
+            return [val_data]
+
+    def _get_ensemble_model_name(self, name: str) -> str:
+        """Revise name for an ensemble model, ensuring we don't have name collisions"""
+        base_name = name
+        increment = 1
+        while name in self.banned_model_names:
+            increment += 1
+            name = f"{base_name}_{increment}"
+        return name
+
+    def _get_base_model_predictions(self, model_names: list[str]) -> dict[str, list[TimeSeriesDataFrame]]:
+        """Get base model predictions for ensemble training / inference."""
+        # TODO: update for window/stack-layer logic and refit logic
+        predictions_per_window = {}
+
+        for model_name in model_names:
+            model_attrs = self.model_graph.nodes[model_name]
+
+            model_path = os.path.join(self.path, *model_attrs["path"])
+            model_type = model_attrs["type"]
+
+            predictions_per_window[model_name] = model_type.load_oof_predictions(path=model_path)
+
+        return predictions_per_window
+
+    def _calculate_base_models_predict_time(self, model_names: list[str]) -> float:
+        """Calculate ensemble predict time as sum of base model predict times."""
+        return sum(self.model_graph.nodes[name]["predict_time"] for name in model_names)
+
+
+def validate_ensemble_hyperparameters(hyperparameters) -> dict:
+    """Validate ensemble hyperparameters dict."""
+    if not isinstance(hyperparameters, dict):
+        raise ValueError(f"ensemble_hyperparameters must be dict, got {type(hyperparameters)}")
+
+    # Validate all ensemble names are known
+    for ensemble_name, ensemble_hyperparameters in hyperparameters.items():
+        get_ensemble_class(ensemble_name)  # Will raise if unknown
+        assert isinstance(ensemble_hyperparameters, dict)
+    return hyperparameters