autogluon.timeseries 1.4.1b20250820__py3-none-any.whl → 1.4.1b20250901__py3-none-any.whl

autogluon/timeseries/predictor.py

@@ -5,7 +5,7 @@ import os
 import pprint
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional, Type, Union, cast
+from typing import Any, Literal, Optional, Type, Union, cast
 
 import numpy as np
 import pandas as pd
@@ -21,7 +21,7 @@ from autogluon.core.utils.decorators import apply_presets
 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 TIMESERIES_PRESETS_CONFIGS
+from autogluon.timeseries.configs import get_predictor_presets
 from autogluon.timeseries.dataset.ts_dataframe import ITEMID, TimeSeriesDataFrame
 from autogluon.timeseries.learner import TimeSeriesLearner
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
@@ -93,7 +93,7 @@ class TimeSeriesPredictor:
     eval_metric_seasonal_period : int, optional
         Seasonal period used to compute some evaluation metrics such as mean absolute scaled error (MASE). Defaults to
         ``None``, in which case the seasonal period is computed based on the data frequency.
-    horizon_weight : List[float], optional
+    horizon_weight : list[float], optional
         Weight assigned to each time step in the forecast horizon when computing the ``eval_metric``. If provided, this
         must be a list with ``prediction_length`` non-negative values, where at least some values are greater than zero.
         AutoGluon will automatically normalize the weights so that they sum up to ``prediction_length``. By default, all
@@ -101,7 +101,7 @@ class TimeSeriesPredictor:
 
         This parameter only affects model selection and ensemble construction; it has no effect on the loss function of
         the individual forecasting models.
-    known_covariates_names: List[str], optional
+    known_covariates_names: list[str], optional
         Names of the covariates that are known in advance for all time steps in the forecast horizon. These are also
         known as dynamic features, exogenous variables, additional regressors or related time series. Examples of such
         covariates include holidays, promotions or weather forecasts.
@@ -111,7 +111,7 @@ class TimeSeriesPredictor:
         - :meth:`~autogluon.timeseries.TimeSeriesPredictor.fit`, :meth:`~autogluon.timeseries.TimeSeriesPredictor.evaluate`, and :meth:`~autogluon.timeseries.TimeSeriesPredictor.leaderboard` will expect a dataframe with columns listed in ``known_covariates_names`` (in addition to the ``target`` column).
         - :meth:`~autogluon.timeseries.TimeSeriesPredictor.predict` will expect an additional keyword argument ``known_covariates`` containing the future values of the known covariates in ``TimeSeriesDataFrame`` format.
 
-    quantile_levels : List[float], optional
+    quantile_levels : list[float], optional
         List of increasing decimals that specifies which quantiles should be estimated when making distributional
         forecasts. Defaults to ``[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]``.
     path : str or pathlib.Path, optional
@@ -147,17 +147,17 @@ class TimeSeriesPredictor:
     def __init__(
         self,
         target: Optional[str] = None,
-        known_covariates_names: Optional[List[str]] = None,
+        known_covariates_names: Optional[list[str]] = None,
         prediction_length: int = 1,
         freq: Optional[str] = None,
         eval_metric: Union[str, TimeSeriesScorer, None] = None,
         eval_metric_seasonal_period: Optional[int] = None,
-        horizon_weight: Optional[List[float]] = None,
+        horizon_weight: Optional[list[float]] = None,
         path: Optional[Union[str, Path]] = None,
         verbosity: int = 2,
         log_to_file: bool = True,
         log_file_path: Union[str, Path] = "auto",
-        quantile_levels: Optional[List[float]] = None,
+        quantile_levels: Optional[list[float]] = None,
         cache_predictions: bool = True,
         label: Optional[str] = None,
         **kwargs,
@@ -432,16 +432,16 @@ class TimeSeriesPredictor:
             )
         return train_data
 
-    @apply_presets(TIMESERIES_PRESETS_CONFIGS)
+    @apply_presets(get_predictor_presets())
     def fit(
         self,
         train_data: Union[TimeSeriesDataFrame, pd.DataFrame, Path, str],
         tuning_data: Optional[Union[TimeSeriesDataFrame, pd.DataFrame, Path, str]] = None,
         time_limit: Optional[int] = None,
         presets: Optional[str] = None,
-        hyperparameters: Optional[Union[str, Dict[Union[str, Type], Any]]] = None,
-        hyperparameter_tune_kwargs: Optional[Union[str, Dict]] = None,
-        excluded_model_types: Optional[List[str]] = None,
+        hyperparameters: Optional[Union[str, dict[Union[str, Type], Any]]] = None,
+        hyperparameter_tune_kwargs: Optional[Union[str, dict]] = None,
+        excluded_model_types: Optional[list[str]] = None,
         num_val_windows: int = 1,
         val_step_size: Optional[int] = None,
         refit_every_n_windows: Optional[int] = 1,
@@ -614,7 +614,7 @@ class TimeSeriesPredictor:
                         "scheduler": "local",
                     },
                 )
-        excluded_model_types: List[str], optional
+        excluded_model_types: list[str], optional
             Banned subset of model types to avoid training during ``fit()``, even if present in ``hyperparameters``.
             For example, the following code will train all models included in the ``high_quality`` presets except ``DeepAR``::
 
@@ -779,7 +779,7 @@ class TimeSeriesPredictor:
         self.save()
         return self
 
-    def model_names(self) -> List[str]:
+    def model_names(self) -> list[str]:
         """Returns the list of model names trained by this predictor object."""
         return self._trainer.get_model_names()
 
@@ -872,11 +872,11 @@ class TimeSeriesPredictor:
         self,
         data: Union[TimeSeriesDataFrame, pd.DataFrame, Path, str],
         model: Optional[str] = None,
-        metrics: Optional[Union[str, TimeSeriesScorer, List[Union[str, TimeSeriesScorer]]]] = None,
+        metrics: Optional[Union[str, TimeSeriesScorer, list[Union[str, TimeSeriesScorer]]]] = None,
         cutoff: Optional[int] = None,
         display: bool = False,
         use_cache: bool = True,
-    ) -> Dict[str, float]:
+    ) -> dict[str, float]:
         """Evaluate the forecast accuracy for given dataset.
 
         This method measures the forecast accuracy using the last ``self.prediction_length`` time steps of each time
@@ -907,7 +907,7 @@ class TimeSeriesPredictor:
         model : str, optional
             Name of the model that you would like to evaluate. By default, the best model during training
             (with highest validation score) will be used.
-        metrics : str, TimeSeriesScorer or List[Union[str, TimeSeriesScorer]], optional
+        metrics : str, TimeSeriesScorer or list[Union[str, TimeSeriesScorer]], optional
             Metric or a list of metrics to compute scores with. Defaults to ``self.eval_metric``. Supports both
             metric names as strings and custom metrics based on TimeSeriesScorer.
         cutoff : int, optional
@@ -923,7 +923,7 @@ class TimeSeriesPredictor:
 
         Returns
         -------
-        scores_dict : Dict[str, float]
+        scores_dict : dict[str, float]
             Dictionary where keys = metrics, values = performance along each metric. For consistency, error metrics
             will have their signs flipped to obey this convention. For example, negative MAPE values will be reported.
             To get the ``eval_metric`` score, do ``output[predictor.eval_metric.name]``.
@@ -943,7 +943,7 @@ class TimeSeriesPredictor:
         data: Optional[Union[TimeSeriesDataFrame, pd.DataFrame, Path, str]] = None,
         model: Optional[str] = None,
         metric: Optional[Union[str, TimeSeriesScorer]] = None,
-        features: Optional[List[str]] = None,
+        features: Optional[list[str]] = None,
         time_limit: Optional[float] = None,
         method: Literal["naive", "permutation"] = "permutation",
         subsample_size: int = 50,
@@ -990,7 +990,7 @@ class TimeSeriesPredictor:
         metric : str or TimeSeriesScorer, optional
             Metric to be used for computing feature importance. If None, the ``eval_metric`` specified during initialization of
             the ``TimeSeriesPredictor`` will be used.
-        features : List[str], optional
+        features : list[str], optional
             List of feature names that feature importances are calculated for and returned. By default, all feature importances
             will be returned.
         method : {"permutation", "naive"}, default = "permutation"
@@ -1168,7 +1168,7 @@ class TimeSeriesPredictor:
         self._learner = tmp_learner
         self._save_version_file()
 
-    def info(self) -> Dict[str, Any]:
+    def info(self) -> dict[str, Any]:
         """Returns a dictionary of objects each describing an attribute of the training process and trained models."""
         return self._learner.get_info(include_model_info=True)
 
@@ -1182,8 +1182,8 @@ class TimeSeriesPredictor:
         return self._trainer.get_model_best()
 
     def persist(
-        self, models: Union[Literal["all", "best"], List[str]] = "best", with_ancestors: bool = True
-    ) -> List[str]:
+        self, models: Union[Literal["all", "best"], list[str]] = "best", with_ancestors: bool = True
+    ) -> list[str]:
         """Persist models in memory for reduced inference latency. This is particularly important if the models are being used for online
         inference where low latency is critical. If models are not persisted in memory, they are loaded from disk every time they are
         asked to make predictions. This is especially cumbersome for large deep learning based models which have to be loaded into
@@ -1203,12 +1203,12 @@ class TimeSeriesPredictor:
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models : list[str]
             List of persisted model names.
         """
         return self._learner.persist_trainer(models=models, with_ancestors=with_ancestors)
 
-    def unpersist(self) -> List[str]:
+    def unpersist(self) -> list[str]:
         """Unpersist models in memory for reduced memory usage. If models are not persisted in memory, they are loaded from
         disk every time they are asked to make predictions.
 
@@ -1217,7 +1217,7 @@ class TimeSeriesPredictor:
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models : list[str]
             List of unpersisted model names.
         """
         return self._learner.unpersist_trainer()
@@ -1227,7 +1227,7 @@ class TimeSeriesPredictor:
         data: Optional[Union[TimeSeriesDataFrame, pd.DataFrame, Path, str]] = None,
         cutoff: Optional[int] = None,
         extra_info: bool = False,
-        extra_metrics: Optional[List[Union[str, TimeSeriesScorer]]] = None,
+        extra_metrics: Optional[list[Union[str, TimeSeriesScorer]]] = None,
         display: bool = False,
         use_cache: bool = True,
         **kwargs,
@@ -1271,7 +1271,7 @@ class TimeSeriesPredictor:
             If True, the leaderboard will contain an additional column ``hyperparameters`` with the hyperparameters used
             by each model during training. An empty dictionary ``{}`` means that the model was trained with default
             hyperparameters.
-        extra_metrics : List[Union[str, TimeSeriesScorer]], optional
+        extra_metrics : list[Union[str, TimeSeriesScorer]], optional
             A list of metrics to calculate scores for and include in the output DataFrame.
 
             Only valid when ``data`` is specified. The scores refer to the scores on ``data`` (same data as used to
@@ -1355,7 +1355,7 @@ class TimeSeriesPredictor:
         data = self._check_and_prepare_data_frame(data)
         return make_future_data_frame(data, prediction_length=self.prediction_length, freq=self.freq)
 
-    def fit_summary(self, verbosity: int = 1) -> Dict[str, Any]:
+    def fit_summary(self, verbosity: int = 1) -> dict[str, Any]:
         """Output summary of information about models produced during
         :meth:`~autogluon.timeseries.TimeSeriesPredictor.fit`.
 
@@ -1366,7 +1366,7 @@ class TimeSeriesPredictor:
 
         Returns
         -------
-        summary_dict : Dict[str, Any]
+        summary_dict : dict[str, Any]
             Dict containing various detailed information. We do not recommend directly printing this dict as it may
             be very large.
         """
@@ -1405,7 +1405,7 @@ class TimeSeriesPredictor:
             print("****************** End of fit() summary ******************")
         return results
 
-    def refit_full(self, model: str = "all", set_best_to_refit_full: bool = True) -> Dict[str, str]:
+    def refit_full(self, model: str = "all", set_best_to_refit_full: bool = True) -> dict[str, str]:
         """Retrain model on all of the data (training + validation).
 
         This method can only be used if no ``tuning_data`` was passed to :meth:`~autogluon.timeseries.TimeSeriesPredictor.fit`.
@@ -1483,7 +1483,7 @@ class TimeSeriesPredictor:
         train_data = trainer.load_train_data()
         val_data = trainer.load_val_data()
         base_model_names = trainer.get_model_names(level=0)
-        pred_proba_dict_val: Dict[str, List[TimeSeriesDataFrame]] = {
+        pred_proba_dict_val: dict[str, list[TimeSeriesDataFrame]] = {
             model_name: trainer._get_model_oof_predictions(model_name)
             for model_name in base_model_names
             if "_FULL" not in model_name
@@ -1497,7 +1497,7 @@ class TimeSeriesPredictor:
             base_model_names, data=past_data, known_covariates=known_covariates
         )
 
-        y_val: List[TimeSeriesDataFrame] = [
+        y_val: list[TimeSeriesDataFrame] = [
             select_target(df) for df in trainer._get_ensemble_oof_data(train_data=train_data, val_data=val_data)
         ]
         y_test: TimeSeriesDataFrame = select_target(test_data)
@@ -1520,8 +1520,8 @@ class TimeSeriesPredictor:
         self,
         data: Union[TimeSeriesDataFrame, pd.DataFrame, Path, str],
         predictions: Optional[TimeSeriesDataFrame] = None,
-        quantile_levels: Optional[List[float]] = None,
-        item_ids: Optional[List[Union[str, int]]] = None,
+        quantile_levels: Optional[list[float]] = None,
+        item_ids: Optional[list[Union[str, int]]] = None,
         max_num_item_ids: int = 8,
         max_history_length: Optional[int] = None,
         point_forecast_column: Optional[str] = None,
@@ -1535,10 +1535,10 @@ class TimeSeriesPredictor:
             Observed time series data.
         predictions : TimeSeriesDataFrame, optional
             Predictions generated by calling :meth:`~autogluon.timeseries.TimeSeriesPredictor.predict`.
-        quantile_levels : List[float], optional
+        quantile_levels : list[float], optional
             Quantile levels for which to plot the prediction intervals. Defaults to lowest & highest quantile levels
             available in ``predictions``.
-        item_ids : List[Union[str, int]], optional
+        item_ids : list[Union[str, int]], optional
             If provided, plots will only be generated for time series with these item IDs. By default (if set to
             ``None``), item IDs are selected randomly. In either case, plots are generated for at most
             ``max_num_item_ids`` time series.

autogluon/timeseries/regressor.py

@@ -1,6 +1,6 @@
 import logging
 import time
-from typing import Any, Dict, Optional, Protocol, Union, overload, runtime_checkable
+from typing import Any, Optional, Protocol, Union, overload, runtime_checkable
 
 import numpy as np
 import pandas as pd
@@ -40,42 +40,42 @@ class GlobalCovariateRegressor(CovariateRegressor):
 
     Parameters
     ----------
-    model_name : str
+    model_name
         Name of the tabular regression model. See ``autogluon.tabular.registry.ag_model_registry`` or
         `the documentation <https://auto.gluon.ai/stable/api/autogluon.tabular.models.html>`_ for the list of available
         tabular models.
-    model_hyperparameters : dict or None
+    model_hyperparameters
         Hyperparameters passed to the tabular regression model.
-    eval_metric : str
+    eval_metric
         Metric provided as ``eval_metric`` to the tabular regression model. Must be compatible with `problem_type="regression"`.
-    refit_during_predict : bool
+    refit_during_predict
         If True, the model will be re-trained every time ``fit_transform`` is called. If False, the model will only be
         trained the first time that ``fit_transform`` is called, and future calls to ``fit_transform`` will only perform a
         ``transform``.
-    max_num_samples : int or None
+    max_num_samples
         If not None, training dataset passed to regression model will contain at most this many rows.
-    covariate_metadata : CovariateMetadata
+    covariate_metadata
         Metadata object describing the covariates available in the dataset.
-    target : str
+    target
         Name of the target column.
-    validation_fraction : float, optional
+    validation_fraction
         Fraction of observations that are reserved as the validation set during training (starting from the end of each
         time series).
-    fit_time_fraction: float
+    fit_time_fraction
         The fraction of the time_limit that will be reserved for model training. The remainder (1 - fit_time_fraction)
         will be reserved for prediction.
 
         If the estimated prediction time exceeds ``(1 - fit_time_fraction) * time_limit``, the regressor will be disabled.
-    include_static_features: bool
+    include_static_features
         If True, static features will be included as features for the regressor.
-    include_item_id: bool
+    include_item_id
         If True, item_id will be included as a categorical feature for the regressor.
     """
 
     def __init__(
         self,
         model_name: str = "CAT",
-        model_hyperparameters: Optional[Dict[str, Any]] = None,
+        model_hyperparameters: Optional[dict[str, Any]] = None,
         eval_metric: str = "mean_absolute_error",
         refit_during_predict: bool = False,
         max_num_samples: Optional[int] = 500_000,

autogluon/timeseries/splitter.py

@@ -1,4 +1,4 @@
-from typing import Iterator, Optional, Tuple
+from typing import Iterator, Optional
 
 from .dataset.ts_dataframe import TimeSeriesDataFrame
 
@@ -13,7 +13,7 @@ class AbstractWindowSplitter:
         self.prediction_length = prediction_length
         self.num_val_windows = num_val_windows
 
-    def split(self, data: TimeSeriesDataFrame) -> Iterator[Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
+    def split(self, data: TimeSeriesDataFrame) -> Iterator[tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
         raise NotImplementedError
 
 
@@ -33,11 +33,11 @@ class ExpandingWindowSplitter(AbstractWindowSplitter):
 
     Parameters
     ----------
-    prediction_length : int
+    prediction_length
         Length of the forecast horizon.
-    num_val_windows: int, default = 1
+    num_val_windows
         Number of windows to generate from each time series in the dataset.
-    val_step_size : int, optional
+    val_step_size
         The end of each subsequent window is moved this many time steps forward.
     """
 
@@ -47,7 +47,7 @@ class ExpandingWindowSplitter(AbstractWindowSplitter):
             val_step_size = prediction_length
         self.val_step_size = val_step_size
 
-    def split(self, data: TimeSeriesDataFrame) -> Iterator[Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
+    def split(self, data: TimeSeriesDataFrame) -> Iterator[tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]]:
         """Generate train and validation folds for a time series dataset."""
         for window_idx in range(1, self.num_val_windows + 1):
             val_end = -(self.num_val_windows - window_idx) * self.val_step_size

autogluon/timeseries/trainer/__init__.py

@@ -0,0 +1,3 @@
+from .trainer import TimeSeriesTrainer
+
+__all__ = ["TimeSeriesTrainer"]

autogluon/timeseries/trainer/model_set_builder.py

@@ -0,0 +1,256 @@
+import copy
+import logging
+import re
+from collections import defaultdict
+from typing import Any, Optional, Type, Union
+
+from autogluon.common import space
+from autogluon.core import constants
+from autogluon.timeseries.configs import get_hyperparameter_presets
+from autogluon.timeseries.metrics import TimeSeriesScorer
+from autogluon.timeseries.models import ModelRegistry
+from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
+from autogluon.timeseries.models.multi_window import MultiWindowBacktestingModel
+from autogluon.timeseries.utils.features import CovariateMetadata
+
+logger = logging.getLogger(__name__)
+
+
+ModelKey = Union[str, Type[AbstractTimeSeriesModel]]
+ModelHyperparameters = dict[str, Any]
+TrainerHyperparameterSpec = dict[ModelKey, list[ModelHyperparameters]]
+
+
+class TrainableModelSetBuilder:
+    """Responsible for building a list of model objects, in priority order, that will be trained by the
+    Trainer."""
+
+    VALID_AG_ARGS_KEYS = {
+        "name",
+        "name_prefix",
+        "name_suffix",
+    }
+
+    def __init__(
+        self,
+        path: str,
+        freq: Optional[str],
+        prediction_length: int,
+        eval_metric: TimeSeriesScorer,
+        target: str,
+        quantile_levels: list[float],
+        covariate_metadata: CovariateMetadata,
+        multi_window: bool,
+    ):
+        self.path = path
+        self.freq = freq
+        self.prediction_length = prediction_length
+        self.eval_metric = eval_metric
+        self.target = target
+        self.quantile_levels = quantile_levels
+        self.covariate_metadata = covariate_metadata
+        self.multi_window = multi_window
+
+    def get_model_set(
+        self,
+        hyperparameters: Union[str, dict, None],
+        hyperparameter_tune: bool,
+        excluded_model_types: Optional[list[str]],
+        banned_model_names: Optional[list[str]] = None,
+    ) -> list[AbstractTimeSeriesModel]:
+        """Resolve hyperparameters and create the requested list of models"""
+        models = []
+        banned_model_names = [] if banned_model_names is None else banned_model_names.copy()
+
+        # resolve and normalize hyperparameters
+        model_hp_map: TrainerHyperparameterSpec = HyperparameterBuilder(
+            hyperparameters=hyperparameters,
+            hyperparameter_tune=hyperparameter_tune,
+            excluded_model_types=excluded_model_types,
+        ).get_hyperparameters()
+
+        for k in model_hp_map.keys():
+            if isinstance(k, type) and not issubclass(k, AbstractTimeSeriesModel):
+                raise ValueError(f"Custom model type {k} must inherit from `AbstractTimeSeriesModel`.")
+
+        model_priority_list = sorted(
+            model_hp_map.keys(), key=lambda x: ModelRegistry.get_model_priority(x), reverse=True
+        )
+
+        for model_key in model_priority_list:
+            model_type = self._get_model_type(model_key)
+
+            for model_hps in model_hp_map[model_key]:
+                ag_args = model_hps.pop(constants.AG_ARGS, {})
+
+                for key in ag_args:
+                    if key not in self.VALID_AG_ARGS_KEYS:
+                        raise ValueError(
+                            f"Model {model_type} received unknown ag_args key: {key} (valid keys {self.VALID_AG_ARGS_KEYS})"
+                        )
+                model_name_base = self._get_model_name(ag_args, model_type)
+
+                model_type_kwargs: dict[str, Any] = dict(
+                    name=model_name_base,
+                    hyperparameters=model_hps,
+                    **self._get_default_model_init_kwargs(),
+                )
+
+                # add models while preventing name collisions
+                model = model_type(**model_type_kwargs)
+                model_type_kwargs.pop("name", None)
+
+                increment = 1
+                while model.name in banned_model_names:
+                    increment += 1
+                    model = model_type(name=f"{model_name_base}_{increment}", **model_type_kwargs)
+
+                if self.multi_window:
+                    model = MultiWindowBacktestingModel(model_base=model, name=model.name, **model_type_kwargs)  # type: ignore
+
+                banned_model_names.append(model.name)
+                models.append(model)
+
+        return models
+
+    def _get_model_type(self, model: ModelKey) -> Type[AbstractTimeSeriesModel]:
+        if isinstance(model, str):
+            model_type: Type[AbstractTimeSeriesModel] = ModelRegistry.get_model_class(model)
+        elif isinstance(model, type):
+            model_type = model
+        else:
+            raise ValueError(
+                f"Keys of the `hyperparameters` dictionary must be strings or types, received {type(model)}."
+            )
+
+        return model_type
+
+    def _get_default_model_init_kwargs(self) -> dict[str, Any]:
+        return dict(
+            path=self.path,
+            freq=self.freq,
+            prediction_length=self.prediction_length,
+            eval_metric=self.eval_metric,
+            target=self.target,
+            quantile_levels=self.quantile_levels,
+            covariate_metadata=self.covariate_metadata,
+        )
+
+    def _get_model_name(self, ag_args: dict[str, Any], model_type: Type[AbstractTimeSeriesModel]) -> str:
+        name = ag_args.get("name")
+        if name is None:
+            name_stem = re.sub(r"Model$", "", model_type.__name__)
+            name_prefix = ag_args.get("name_prefix", "")
+            name_suffix = ag_args.get("name_suffix", "")
+            name = name_prefix + name_stem + name_suffix
+        return name
+
+
+class HyperparameterBuilder:
+    """Given user hyperparameter specifications, this class resolves them against presets, removes
+    excluded model types and canonicalizes the hyperparameter specification.
+    """
+
+    def __init__(
+        self,
+        hyperparameters: Union[str, dict, None],
+        hyperparameter_tune: bool,
+        excluded_model_types: Optional[list[str]],
+    ):
+        self.hyperparameters = hyperparameters
+        self.hyperparameter_tune = hyperparameter_tune
+        self.excluded_model_types = excluded_model_types
+
+    def get_hyperparameters(self) -> TrainerHyperparameterSpec:
+        hyperparameter_dict = {}
+        hp_presets = get_hyperparameter_presets()
+
+        if self.hyperparameters is None:
+            hyperparameter_dict = hp_presets["default"]
+        elif isinstance(self.hyperparameters, str):
+            try:
+                hyperparameter_dict = hp_presets[self.hyperparameters]
+            except KeyError:
+                raise ValueError(f"{self.hyperparameters} is not a valid preset.")
+        elif isinstance(self.hyperparameters, dict):
+            hyperparameter_dict = copy.deepcopy(self.hyperparameters)
+        else:
+            raise ValueError(
+                f"hyperparameters must be a dict, a string or None (received {type(self.hyperparameters)}). "
+                f"Please see the documentation for TimeSeriesPredictor.fit"
+            )
+
+        return self._check_and_clean_hyperparameters(hyperparameter_dict)  # type: ignore
+
+    def _check_and_clean_hyperparameters(
+        self,
+        hyperparameters: dict[ModelKey, Union[ModelHyperparameters, list[ModelHyperparameters]]],
+    ) -> TrainerHyperparameterSpec:
+        """Convert the hyperparameters dictionary to a unified format:
+        - Remove 'Model' suffix from model names, if present
+        - Make sure that each value in the hyperparameters dict is a list with model configurations
+        - Checks if hyperparameters contain searchspaces
+        """
+        excluded_models = self._get_excluded_models()
+        hyperparameters_clean = defaultdict(list)
+        for model_name, model_hyperparameters in hyperparameters.items():
+            # Handle model names ending with "Model", e.g., "DeepARModel" is mapped to "DeepAR"
+            if isinstance(model_name, str):
+                model_name = self._normalize_model_type_name(model_name)
+                if model_name in excluded_models:
+                    logger.info(
+                        f"\tFound '{model_name}' model in `hyperparameters`, but '{model_name}' "
+                        "is present in `excluded_model_types` and will be removed."
+                    )
+                    continue
+            if not isinstance(model_hyperparameters, list):
+                model_hyperparameters = [model_hyperparameters]
+            hyperparameters_clean[model_name].extend(model_hyperparameters)
+
+        self._verify_searchspaces(hyperparameters_clean)
+
+        return dict(hyperparameters_clean)
+
+    def _get_excluded_models(self) -> set[str]:
+        excluded_models = set()
+        if self.excluded_model_types is not None and len(self.excluded_model_types) > 0:
+            if not isinstance(self.excluded_model_types, list):
+                raise ValueError(f"`excluded_model_types` must be a list, received {type(self.excluded_model_types)}")
+            logger.info(f"Excluded model types: {self.excluded_model_types}")
+            for model in self.excluded_model_types:
+                if not isinstance(model, str):
+                    raise ValueError(f"Each entry in `excluded_model_types` must be a string, received {type(model)}")
+                excluded_models.add(self._normalize_model_type_name(model))
+        return excluded_models
+
+    @staticmethod
+    def _normalize_model_type_name(model_name: str) -> str:
+        return model_name.removesuffix("Model")
+
+    def _verify_searchspaces(self, hyperparameters: dict[str, list[ModelHyperparameters]]):
+        if self.hyperparameter_tune:
+            for model, model_hps_list in hyperparameters.items():
+                for model_hps in model_hps_list:
+                    if contains_searchspace(model_hps):
+                        return
+
+            raise ValueError(
+                "Hyperparameter tuning specified, but no model contains a hyperparameter search space. "
+                "Please disable hyperparameter tuning with `hyperparameter_tune_kwargs=None` or provide a search space "
+                "for at least one model."
+            )
+        else:
+            for model, model_hps_list in hyperparameters.items():
+                for model_hps in model_hps_list:
+                    if contains_searchspace(model_hps):
+                        raise ValueError(
+                            f"Hyperparameter tuning not specified, so hyperparameters must have fixed values. "
+                            f"However, for model {model} hyperparameters {model_hps} contain a search space."
+                        )
+
+
+def contains_searchspace(model_hyperparameters: ModelHyperparameters) -> bool:
+    for hp_value in model_hyperparameters.values():
+        if isinstance(hp_value, space.Space):
+            return True
+    return False