HyperparameterTuner

class openstef_models.integrations.optuna.HyperparameterTuner(**data: Any) → None

Bases: BaseConfig, Generic

Bayesian hyperparameter tuner powered by Optuna.

Orchestrates an Optuna study over the tunable search spaces declared on HyperParams fields of the provided config. Override methods prefixed with _ to customise study creation, objective evaluation, or parameter suggestion.

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

config: Annotated[TypeVar(ConfigT, bound= BaseConfig)]

train_dataset: Annotated[TimeSeriesDataset]

create_workflow: Annotated[Callable[[TypeVar(ConfigT, bound= BaseConfig)], CustomForecastingWorkflow]]

target_quantile: Union[Quantile, Literal['global']]

metric_name: str

direction: Literal['maximize', 'minimize']

n_trials: int

n_jobs: int

seed: int | None

study_name: str

static suggest_value(trial: Trial, trial_key: str, tuning_range: TuningRange) → bool | int | float | str | None

Suggest a single parameter value via the Optuna trial API.

Override to add custom suggestion logic or constraints.

Returns:

Suggested value, or None when the range is incomplete.

Parameters:

• trial (Trial)

• trial_key (str)

• tuning_range (TypeAliasType)

Return type:

bool | int | float | str | None

tune(*, show_progress_bar: bool = True) → tuple[ConfigT, Study]

Run the Optuna study and return the best config.

Returns:

(best_config, study) tuple.

Raises:

ValueError – If no tunable fields are found or metric_name is invalid.

Parameters:

show_progress_bar (bool)

Return type:

tuple[TypeVar(ConfigT, bound= BaseConfig), Study]

fit_with_tuning(*, show_progress_bar: bool = True) → TuningResult

Tune, then fit a final workflow with the best config.

Returns:

TuningResult with the best config and Optuna study.

Raises:

RuntimeError – If the final workflow fit fails after tuning.

Parameters:

show_progress_bar (bool)

Return type:

TuningResult[TypeVar(ConfigT, bound= BaseConfig)]