feat(tuning): Bayesian hyperparameter tuning via Optuna integration

[egordm]

New feature: Bayesian hyperparameter tuning with Optuna

This PR introduces a first-class hyperparameter tuning API to OpenSTEF, powered by Optuna. The design goal is to keep search space declarations co-located with the model definition — no separate config files, no extra boilerplate.

---

How it works

Step 1 — declare the search space inline

Pass a FloatRange, IntRange, or CategoricalRange directly in the HyperParams constructor to mark fields for tuning. Everything else keeps its default value.

from openstef_core.mixins.param_ranges import FloatRange, IntRange
from openstef_models.models.forecasting.xgboost_forecaster import XGBoostHyperParams

config = ForecastingWorkflowConfig(
    model_id="my_forecast",
    model="xgboost",
    xgboost_hyperparams=XGBoostHyperParams(
        learning_rate=FloatRange(0.01, 0.3, log=True, tune=True),
        n_estimators=IntRange(50, 500, tune=True),
        max_depth=IntRange(3, 10, tune=True),
    ),
)

Step 2 — run the tuner

from openstef_models.integrations.optuna import HyperparameterTuner

tuner = HyperparameterTuner(
    config=config,
    train_dataset=dataset,
    create_workflow=create_forecasting_workflow,
    target_quantile=Q(0.5),
    metric_name="R2",
    n_trials=50,
)
result = tuner.fit_with_tuning()

Step 3 — use the result

result.best_config   # ForecastingWorkflowConfig with tuned values applied
result.workflow      # Fitted workflow, ready to generate forecasts
result.study         # Full optuna.Study for analysis and visualisation

---

What's included

Component	Package	Description
FloatRange, IntRange, CategoricalRange	openstef-core	Frozen dataclasses that encode tuning search spaces as field annotations
HyperParams.get_search_space()	openstef-core	Resolves instance overrides against class-level defaults and returns only tune=True fields
get_tuning_range(field_info)	openstef-core	Public helper that extracts a TuningRange from a Pydantic FieldInfo's metadata
HyperparameterTuner	openstef-models	Optuna-backed tuner: TPE sampling, median pruning, configurable direction/parallelism
TuningResult	openstef-models	Typed result container: best_config, study, and fitted workflow
XGBoostHyperParams, GBLinearHyperParams	openstef-models	All fields annotated with class-level default ranges; tuning opt-in per instantiation

The HyperparameterTuner is extensible: override _evaluate_trial, _create_study, or suggest_value to customise sampling, cross-validation, or pruning behaviour.

---

Installation

Optuna is an optional dependency. Install via:

pip install openstef-models[tuning]
# or with uv:
uv add openstef-models[tuning]

---

Tutorial

examples/tutorials/hyperparameter_tuning_with_optuna.ipynb walks through the full workflow:

• Downloading the Liander benchmark dataset
• Declaring an inline search space
• Running a 20-trial study
• Inspecting trial history and hyperparameter importances
• Training the final model with the best config

---

Testing

# All tests (includes 36 targeted tuning tests)
uv run poe tests

# Targeted subset
uv run pytest packages/openstef-models/tests/unit/integrations/optuna/
uv run pytest packages/openstef-core/tests/unit/mixins/

[egordm]

Made with improvements for #840

[bartpleiter]

Nice feature! Some minor comment comments. Also the sonar suggestions of comparing with floats is good to take a look at.

[bartpleiter]

Since the Liander 2024 dataset is now being used in multiple parts of the code base (examples, openstef-beam, and now openstef-core as well). Does it make sense to have an "appsetting" like config somewhere with paths? In case we want to change the dataset in the future I want to prevent having to search though all code in all packages.

[egordm]

Not sure about the app setting. It may be a bit overkill for constants. But a constants module would work.

[egordm]

Made constant. Other things can use it.

[egordm]

TODO:

• Check what happens if you have set searching range and accidentally run fit. If it gracefully errors out.
• Double check that first run actually uses openstef defaults and not something random.

[sonarqubecloud]

Quality Gate failed

Failed conditions
6.3% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE