openstef-models 4.0.1__tar.gz → 4.1.1.dev0__tar.gz

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/.gitignore

@@ -35,10 +35,6 @@ MANIFEST
 # Ruff
 .ruff_cache/
 
-# Pyright
-.pyright/
-# pyright-report/
-
 # Test, coverage, tox
 .pytest_cache/
 .coverage
@@ -69,6 +65,8 @@ docs/_build/
 docs/source/api/generated/
 docs/source/tutorials/
 docs/source/benchmarks/
+# Community health files materialized from OpenSTEF/.github at build time
+docs/source/contribute/_community/
 docs/source/user_guide/**/quick_start_tutorial.py
 docs/source/user_guide/**/feature_engineering_tutorial.py
 docs/source/user_guide/**/datasets_tutorial.py
@@ -135,6 +133,9 @@ benchmark_results*/
 # Local dataset files
 liander_dataset/
 
+# Deployment example run artifacts (MLflow store, forecasts, dataset, Celery/Airflow state)
+openstef_deployment_runs/
+
 # Mlflow
 /mlflow
 /mlflow_artifacts_local

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openstef-models
-Version: 4.0.1
+Version: 4.1.1.dev0
 Summary: Core models for OpenSTEF
 Project-URL: Documentation, https://openstef.github.io/openstef/index.html
 Project-URL: Homepage, https://lfenergy.org/projects/openstef/
@@ -18,8 +18,8 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <4.0,>=3.12
 Requires-Dist: holidays>=0.79
 Requires-Dist: mlflow-skinny<4,>=3
-Requires-Dist: openstef-beam<5,>=4.0.0.dev0
-Requires-Dist: openstef-core<5,>=4.0.0.dev0
+Requires-Dist: openstef-beam<5,>=4
+Requires-Dist: openstef-core<5,>=4
 Requires-Dist: pvlib>=0.13
 Requires-Dist: pycountry>=24.6.1
 Requires-Dist: scikit-learn<1.8,>=1.7.1

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/pyproject.toml

@@ -1,15 +1,13 @@
 # SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
 #
 # SPDX-License-Identifier: MPL-2.0
-
 [build-system]
 build-backend = "hatchling.build"
-
 requires = [ "hatchling" ]
 
 [project]
 name = "openstef-models"
-version = "4.0.1"
+version = "4.1.1.dev0"
 description = "Core models for OpenSTEF"
 readme = "README.md"
 keywords = [ "energy", "forecasting", "machinelearning" ]
@@ -26,34 +24,39 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-
 dependencies = [
   "holidays>=0.79",
   "mlflow-skinny>=3,<4",
-  "openstef-beam>=4.0.0.dev0,<5",
-  "openstef-core>=4.0.0.dev0,<5",
+  "openstef-beam>=4,<5",
+  "openstef-core>=4,<5",
   "pvlib>=0.13",
   "pycountry>=24.6.1",
   "scikit-learn>=1.7.1,<1.8",
   "scipy>=1.16.3,<2",
 ]
-
 optional-dependencies.lgbm = [
   "lightgbm>=4.6",
 ]
-
 optional-dependencies.tuning = [ "optuna>=4.7" ]
-
 optional-dependencies.xgb-cpu = [
   "xgboost>=3,<4; sys_platform=='darwin'",
   "xgboost-cpu>=3,<4; sys_platform=='linux' or sys_platform=='win32'",
 ]
-
 optional-dependencies.xgb-gpu = [ "xgboost>=3,<4" ]
 urls.Documentation = "https://openstef.github.io/openstef/index.html"
 urls.Homepage = "https://lfenergy.org/projects/openstef/"
 urls.Issues = "https://github.com/OpenSTEF/openstef/issues"
 urls.Repository = "https://github.com/OpenSTEF/openstef"
 
-[tool.hatch.build.targets.wheel]
-packages = [ "src/openstef_models" ]
+[tool.hatch]
+build.targets.wheel.packages = [ "src/openstef_models" ]
+
+[tool.uv]
+# xgb-cpu installs xgboost-cpu (Linux/Windows) and xgb-gpu installs the full
+# xgboost; both provide the same import, so exactly one may be installed.
+conflicts = [
+  [
+    { extra = "xgb-cpu" },
+    { extra = "xgb-gpu" },
+  ],
+]

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/explainability/plotters/contributions_plotter.py

@@ -9,9 +9,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 import plotly.graph_objects as go
-from plotly.subplots import make_subplots  # pyright: ignore[reportUnknownVariableType]
+from plotly.subplots import make_subplots
 
-from openstef_core.datasets import TimeSeriesDataset  # noqa: TC001  # runtime needed for pyright
+from openstef_core.datasets import TimeSeriesDataset  # noqa: TC001
 
 if TYPE_CHECKING:
     import pandas as pd
@@ -77,7 +77,7 @@ class ContributionsPlotter:
                 vertical_spacing=0.03,
             )
 
-            fig.add_trace(  # pyright: ignore[reportUnknownMemberType]
+            fig.add_trace(
                 go.Scatter(
                     x=df.index,
                     y=prediction,
@@ -89,9 +89,9 @@ class ContributionsPlotter:
                 row=1,
                 col=1,
             )
-            fig.add_trace(heatmap, row=2, col=1)  # pyright: ignore[reportUnknownMemberType]
+            fig.add_trace(heatmap, row=2, col=1)
 
-            fig.update_layout(  # pyright: ignore[reportUnknownMemberType]
+            fig.update_layout(
                 yaxis_title="Prediction",
                 yaxis2_title="Feature",
                 xaxis2_title="Time",
@@ -150,7 +150,7 @@ class ContributionsPlotter:
 
         for feat in top:
             names.append(feat)
-            values.append(float(row[feat]))  # pyright: ignore[reportArgumentType]
+            values.append(float(row[feat]))
             measures.append("relative")
 
         if len(remaining) > 0:
@@ -213,7 +213,7 @@ class ContributionsPlotter:
 
         return go.Figure(
             go.Bar(
-                x=mean_abs.values,  # pyright: ignore[reportArgumentType]
+                x=mean_abs.values,
                 y=mean_abs.index.tolist(),
                 orientation="h",
                 marker_color="#1f77b4",

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/integrations/__init__.py

@@ -9,4 +9,4 @@ extend OpenSTEF functionality by integrating with external systems such as
 monitoring tools, databases, cloud storage, and custom processing pipelines.
 """
 
-__all__ = ["joblib", "mlflow", "optuna"]  # noqa: F822  # pyright: ignore[reportUnsupportedDunderAll]  # Sub-packages with optional deps; not imported to avoid missing-extra errors at import time
+__all__ = ["joblib", "mlflow", "optuna"]

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/integrations/joblib/joblib_model_serializer.py

@@ -58,11 +58,11 @@ class JoblibModelSerializer(ModelSerializer):
 
     @override
     def serialize(self, model: object, file: BinaryIO) -> None:
-        joblib.dump(model, file)  # type: ignore[reportUnknownMemberType]
+        joblib.dump(model, file)
 
     @override
     def deserialize(self, file: BinaryIO) -> object:
-        return joblib.load(file)  # type: ignore[reportUnknownMemberType]
+        return joblib.load(file)
 
 
 __all__ = ["JoblibModelSerializer"]

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/integrations/mlflow/mlflow_storage.py

@@ -69,6 +69,13 @@ class MLFlowStorage(BaseConfig):
     local_artifacts_path: Path = Field(
         default=Path("./mlflow_artifacts_local"), description="Local path for storing MLflow artifacts before upload."
     )
+    artifact_location: str | None = Field(
+        default=None,
+        description="Artifact storage location for newly created experiments. Defaults to MLflow's "
+        "own default (a ``./mlruns`` directory relative to the working directory). Set this to an "
+        "absolute URI (e.g. ``file:///abs/path`` or ``s3://bucket/prefix``) to keep artifacts "
+        "self-contained — useful with a database tracking backend such as ``sqlite:///...``.",
+    )
     experiment_name_prefix: str = Field(default="", description="Prefix for MLflow experiment names.")
     # Artifact subdirectories
     data_path: str = Field(default="data", description="Subdirectory for storing training data artifacts.")
@@ -119,6 +126,7 @@ class MLFlowStorage(BaseConfig):
         if experiment is None:
             experiment_id = self._client.create_experiment(
                 name=f"{self.experiment_name_prefix}{model_id}",
+                artifact_location=self.artifact_location,
                 tags=experiment_tags,
             )
         else:

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/integrations/mlflow/mlflow_storage_callback.py

@@ -194,7 +194,7 @@ class MLFlowStorageCallback(BaseConfig, ForecastingCallback):
             )
             return
 
-        context.workflow.model = old_model  # pyright: ignore[reportAttributeAccessIssue]
+        context.workflow.model = old_model
         self._logger.info(
             "Loaded model from MLflow run %s for model %s",
             run_id,
@@ -209,7 +209,7 @@ class MLFlowStorageCallback(BaseConfig, ForecastingCallback):
         run_id = cast(str, run.info.run_id)
 
         if not self._check_tags_compatible(
-            run_tags=run.data.tags,  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+            run_tags=run.data.tags,
             new_tags=workflow.model.tags,
             run_id=run_id,
         ):
@@ -233,9 +233,9 @@ class MLFlowStorageCallback(BaseConfig, ForecastingCallback):
             return
 
         if self._check_is_new_model_better(old_metrics=old_metrics, new_metrics=new_metrics):
-            workflow.model = new_model  # pyright: ignore[reportAttributeAccessIssue]
+            workflow.model = new_model
         else:
-            workflow.model = old_model  # pyright: ignore[reportAttributeAccessIssue]
+            workflow.model = old_model
             self._logger.info(
                 "New model did not improve %s metric from previous run %s, reusing old model",
                 self.model_selection_metric,
@@ -250,7 +250,7 @@ class MLFlowStorageCallback(BaseConfig, ForecastingCallback):
                 continue
             suffix = f"_{name}" if name else ""
             fig = component.plot_feature_importances()
-            fig.write_html(data_path / f"feature_importances{suffix}.html")  # pyright: ignore[reportUnknownMemberType]
+            fig.write_html(data_path / f"feature_importances{suffix}.html")
 
     def _find_run(self, model_id: str, run_name: str | None) -> Run | None:
         """Find an MLflow run by model_id and optional run_name.

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/integrations/optuna/tuner.py

@@ -7,7 +7,7 @@
 from collections import defaultdict
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Literal, NamedTuple, cast
+from typing import Any, Literal, NamedTuple, cast, override
 
 from pydantic import ConfigDict, Field, SkipValidation
 
@@ -16,7 +16,7 @@ try:
 except ImportError as _err:
     from openstef_core.exceptions import MissingExtraError
 
-    raise MissingExtraError("optuna", "openstef-models[tuning]") from _err
+    raise MissingExtraError("optuna", "openstef-models", install_extra="tuning") from _err
 
 from openstef_core.base_model import BaseConfig
 from openstef_core.datasets import TimeSeriesDataset
@@ -65,7 +65,8 @@ class TuningResult[ConfigT: BaseConfig]:
     study: optuna.Study
     workflow: CustomForecastingWorkflow
 
-    def __repr__(self) -> str:  # noqa: D105  # self-explanatory
+    @override
+    def __repr__(self) -> str:  # self-explanatory
         n = len(self.study.best_params)
         return f"TuningResult({n} params tuned)" if n else "TuningResult(no tuning)"
 
@@ -328,7 +329,7 @@ class HyperparameterTuner[ConfigT: BaseConfig](BaseConfig):
         best_config = self._reconstruct_best_config(
             config=self.config, model_tuning_info=model_tuning_info, study=study
         )
-        return best_config, study  # type: ignore[return-value]  # ConfigT narrowing not expressible
+        return best_config, study  # ty: ignore[invalid-return-type]  # ConfigT narrowing not expressible
 
     def fit_with_tuning(self, *, show_progress_bar: bool = True) -> TuningResult[ConfigT]:
         """Tune, then fit a final workflow with the best config.

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/component_splitting/constant_component_splitter.py

@@ -14,6 +14,7 @@ components like solar, wind, or other energy sources. No training is required
 since ratios are predefined by the user.
 """
 
+import math
 from typing import Self, override
 
 import pandas as pd
@@ -39,7 +40,7 @@ class ConstantComponentSplitterConfig(ComponentSplitterConfig):
     @field_validator("component_ratios")
     @classmethod
     def _validate_component_ratios(cls, value: dict[EnergyComponentType, float]) -> dict[EnergyComponentType, float]:
-        if sum(value.values()) != 1.0:
+        if not math.isclose(sum(value.values()), 1.0):
             raise ValueError("Component ratios must sum to 1.0.")
 
         return value

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/component_splitting/linear_component_splitter.py

@@ -101,7 +101,7 @@ class LinearComponentSplitter(ComponentSplitter):
         """
         super().__init__()
         self._config = config
-        self._model = joblib.load(self.config.linear_model_path)  # type: ignore[reportUnknownMemberType]
+        self._model = joblib.load(self.config.linear_model_path)
 
     @property
     @override
@@ -148,7 +148,7 @@ class LinearComponentSplitter(ComponentSplitter):
         )
 
         # Drop rows with NaN values
-        input_df = input_df.dropna()  # pyright: ignore[reportUnknownMemberType]
+        input_df = input_df.dropna()
 
         if input_df.empty:
             error_msg = "No valid data available for component splitting after dropping NaNs"

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/base_case_forecaster.py

@@ -149,7 +149,7 @@ class BaseCaseForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         # Fill missing values with fallback lag if needed
         if prediction.isna().any():
             prediction_fallback = target_series.shift(freq=self.hyperparams.fallback_lag).reindex(forecast_index)
-            prediction = prediction.fillna(prediction_fallback)  # pyright: ignore[reportUnknownMemberType]
+            prediction = prediction.fillna(prediction_fallback)
 
         return ForecastDataset(
             data=pd.DataFrame(
@@ -171,7 +171,7 @@ class BaseCaseForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
     @override
     def feature_importances(self) -> pd.DataFrame:
         return pd.DataFrame(
-            data=[1.0],
+            data=1.0,
             index=["load"],
             columns=[quantile.format() for quantile in self.quantiles],
         )

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/constant_quantile_forecaster.py

@@ -114,7 +114,7 @@ class ConstantQuantileForecaster(Forecaster, ExplainableForecaster, Contribution
     @override
     def feature_importances(self) -> pd.DataFrame:
         return pd.DataFrame(
-            data=[1.0],
+            data=1.0,
             index=["load"],
             columns=[quantile.format() for quantile in self.quantiles],
         )

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/gblinear_forecaster.py

@@ -38,7 +38,7 @@ from openstef_models.utils.xgboost import get_median_shap_contribs
 try:
     import xgboost as xgb
 except ImportError as e:
-    raise MissingExtraError("xgboost", "openstef-models") from e
+    raise MissingExtraError("xgboost", "openstef-models", install_extra="xgb-cpu") from e
 
 
 class GBLinearHyperParams(HyperParams):
@@ -186,6 +186,7 @@ class GBLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
     def hparams(self) -> GBLinearHyperParams:
         return self.hyperparams
 
+    @override
     def model_post_init(self, _context: object, /) -> None:
         """Initialize the underlying XGBoost gblinear model from configuration."""
         self._gblinear_model = xgb.XGBRegressor(
@@ -290,6 +291,7 @@ class GBLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
             target_column=data.target_column,
         )
 
+    @override
     def predict_contributions(self, data: ForecastInputDataset) -> TimeSeriesDataset:
         """Compute SHAP feature contributions for the median quantile.
 

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/lgbm_forecaster.py

@@ -196,6 +196,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
     def hparams(self) -> LGBMHyperParams:
         return self.hyperparams
 
+    @override
     def model_post_init(self, _context: object, /) -> None:
         """Initialize the underlying LightGBM model from configuration.
 
@@ -205,7 +206,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         try:
             from lightgbm import LGBMRegressor  # noqa: PLC0415
         except ImportError as e:
-            raise MissingExtraError("lightgbm", "openstef-models") from e
+            raise MissingExtraError("lightgbm", "openstef-models", install_extra="lgbm") from e
 
         lgbm_params = {
             # Core parameters
@@ -234,7 +235,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         }
 
         self._lgbm_model = MultiQuantileRegressor(
-            base_learner=LGBMRegressor,  # type: ignore
+            base_learner=LGBMRegressor,
             quantile_param="alpha",
             hyperparams=lgbm_params,
             quantiles=[float(q) for q in self.quantiles],
@@ -294,6 +295,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
             target_column=data.target_column,
         )
 
+    @override
     def predict_contributions(self, data: ForecastInputDataset) -> TimeSeriesDataset:
         """Compute SHAP feature contributions for the median quantile.
 
@@ -317,7 +319,7 @@ class LGBMForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         model: LGBMRegressor = self._lgbm_model.models[median_idx]  # type: ignore
 
         # Get SHAP contributions from median quantile model (includes bias as last column)
-        contribs: np.ndarray = model.predict(input_data, pred_contrib=True)  # type: ignore
+        contribs: np.ndarray = model.predict(input_data, pred_contrib=True)
 
         columns = [*input_data.columns, "bias"]
         contribs_df = pd.DataFrame(contribs, index=input_data.index, columns=columns)

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/lgbmlinear_forecaster.py

@@ -197,6 +197,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
     def hparams(self) -> LGBMLinearHyperParams:
         return self.hyperparams
 
+    @override
     def model_post_init(self, _context: object, /) -> None:
         """Initialize the underlying LightGBM linear model from configuration.
 
@@ -206,7 +207,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
         try:
             from lightgbm import LGBMRegressor  # noqa: PLC0415
         except ImportError as e:
-            raise MissingExtraError("lightgbm", "openstef-models") from e
+            raise MissingExtraError("lightgbm", "openstef-models", install_extra="lgbm") from e
 
         lgbmlinear_params = {
             # Core parameters
@@ -235,7 +236,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
         }
 
         self._lgbmlinear_model = MultiQuantileRegressor(
-            base_learner=LGBMRegressor,  # type: ignore
+            base_learner=LGBMRegressor,
             quantile_param="alpha",
             hyperparams=lgbmlinear_params,
             quantiles=[float(q) for q in self.quantiles],
@@ -319,7 +320,7 @@ class LGBMLinearForecaster(Forecaster, ExplainableForecaster, ContributionsMixin
         model: LGBMRegressor = self._lgbmlinear_model.models[median_idx]  # type: ignore
 
         # Get SHAP contributions from median quantile model (includes bias as last column)
-        contribs: np.ndarray = model.predict(input_data, pred_contrib=True)  # type: ignore
+        contribs: np.ndarray = model.predict(input_data, pred_contrib=True)
 
         columns = [*input_data.columns, "bias"]
         contribs_df = pd.DataFrame(contribs, index=input_data.index, columns=columns)

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/median_forecaster.py

@@ -214,13 +214,11 @@ class MedianForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         for time_step in range(lag_array.shape[0]):
             # Get the lag features for the current time step.
             current_lags = lag_array[time_step]
-            # Calculate the median of the available lag features, ignoring NaNs.
-            median = np.nanmedian(current_lags)  # type: ignore
-            # If the median calculation resulted in NaN (e.g., all lags were NaN), skip the autoregression step.
-            if not np.isnan(median):  # type: ignore
-                median = float(median)  # type: ignore
-            else:
+            # If all lags are NaN there is no value to predict, so skip the autoregressive step.
+            if np.all(np.isnan(current_lags)):
                 continue
+            # Calculate the median of the available lag features, ignoring NaNs.
+            median = float(np.nanmedian(current_lags))
 
             # Store the calculated median in the prediction array.
             prediction[time_step] = median
@@ -239,7 +237,7 @@ class MedianForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
         prediction_df = prediction_df.reindex(input_data.index)
 
         return ForecastDataset(
-            data=prediction_df.dropna().rename(columns={"median": self.quantiles[0].format()}),  # type: ignore
+            data=prediction_df.dropna().rename(columns={"median": self.quantiles[0].format()}),
             sample_interval=data.sample_interval,
             forecast_start=data.forecast_start,
             target_column=data.target_column,

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting/xgboost_forecaster.py

@@ -34,7 +34,7 @@ from openstef_models.utils.xgboost import get_median_shap_contribs
 try:
     import xgboost as xgb
 except ImportError as e:
-    raise MissingExtraError("xgboost", "openstef-models") from e
+    raise MissingExtraError("xgboost", "openstef-models", install_extra="xgb-cpu") from e
 
 
 class XGBoostHyperParams(HyperParams):
@@ -250,6 +250,7 @@ class XGBoostForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
     def hparams(self) -> XGBoostHyperParams:
         return self.hyperparams
 
+    @override
     def model_post_init(self, _context: object, /) -> None:
         """Initialize the underlying XGBoost model from configuration."""
         self._xgboost_model = xgb.XGBRegressor(
@@ -364,6 +365,7 @@ class XGBoostForecaster(Forecaster, ExplainableForecaster, ContributionsMixin):
             target_column=data.target_column,
         )
 
+    @override
     def predict_contributions(self, data: ForecastInputDataset) -> TimeSeriesDataset:
         """Compute SHAP feature contributions for the median quantile.
 

{openstef_models-4.0.1 → openstef_models-4.1.1.dev0}/src/openstef_models/models/forecasting_model.py

@@ -12,6 +12,7 @@ unified interface while providing consistent data transformation and validation.
 
 import logging
 from abc import abstractmethod
+from collections.abc import Sequence
 from datetime import datetime, timedelta
 from functools import partial
 from typing import Self, cast, override
@@ -29,7 +30,7 @@ from openstef_core.datasets import (
     TimeSeriesDataset,
 )
 from openstef_core.datasets.timeseries_dataset import validate_horizons_present
-from openstef_core.exceptions import InsufficientlyCompleteError, NotFittedError
+from openstef_core.exceptions import InsufficientlyCompleteError, NotFittedError, PredictError
 from openstef_core.mixins import HyperParams, Predictor, TransformPipeline
 from openstef_core.types import LeadTime, Quantile
 from openstef_models.explainability.mixins import ContributionsMixin, ExplainableForecaster
@@ -137,7 +138,7 @@ class BaseForecastingModel(BaseModel, Predictor[TimeSeriesDataset, ForecastDatas
         "Default of 0 assumes no invalid rows are created by preprocessing.",
     )
 
-    evaluation_metrics: list[MetricProvider] = Field(
+    evaluation_metrics: list[MetricProvider] = Field(  # ty: ignore[invalid-assignment]
         default_factory=lambda: [R2Provider(), ObservedProbabilityProvider()],
         description="List of metric providers for evaluating model score.",
     )
@@ -206,7 +207,7 @@ class BaseForecastingModel(BaseModel, Predictor[TimeSeriesDataset, ForecastDatas
             raise ValueError(msg)
         return self
 
-    def get_explainable_components(self) -> dict[str, ExplainableForecaster]:  # noqa: PLR6301
+    def get_explainable_components(self) -> dict[str, ExplainableForecaster]:
         """Return named components that support feature-importance plotting.
 
         Keys are used as filename suffixes; an empty key means no suffix.
@@ -310,6 +311,58 @@ class BaseForecastingModel(BaseModel, Predictor[TimeSeriesDataset, ForecastDatas
 
         return self.postprocessing.transform(data=raw_predictions)
 
+    def predict_batch(
+        self,
+        data: list[TimeSeriesDataset],
+        forecast_start: Sequence[datetime],
+    ) -> list[ForecastDataset]:
+        """Generate forecasts for a batch of inputs with one model instance.
+
+        Each item is preprocessed independently (keeping its own ``forecast_start``);
+        the preprocessed batch is then forecast together via ``_predict_batch`` and
+        each raw forecast is postprocessed.
+
+        Args:
+            data: One ``TimeSeriesDataset`` per location/series to forecast.
+            forecast_start: One forecast start per item, in input order. Pass
+                ``[origin] * len(data)`` to share a single origin across the batch.
+
+        Returns:
+            One ``ForecastDataset`` per input, in input order.
+
+        Raises:
+            NotFittedError: If the model has not been fitted.
+            ValueError: If ``forecast_start`` length differs from the batch size.
+        """
+        if not self.is_fitted:
+            raise NotFittedError(type(self).__name__)
+        if not data:
+            return []
+        if len(forecast_start) != len(data):
+            msg = f"forecast_start sequence length {len(forecast_start)} != batch size {len(data)}."
+            raise ValueError(msg)
+
+        inputs = [
+            self.prepare_input(data=item, forecast_start=start)
+            for item, start in zip(data, forecast_start, strict=True)
+        ]
+        raw = self._predict_batch(input_data=inputs)
+        return [self.postprocessing.transform(data=forecast) for forecast in raw]
+
+    def _predict_batch(self, input_data: list[ForecastInputDataset]) -> list[ForecastDataset]:
+        """Generate raw forecasts for a preprocessed batch.
+
+        The default fallback loops ``_predict`` item by item. Subclasses backed by a
+        batch-native forecaster override this to issue a single batched call.
+
+        Args:
+            input_data: One preprocessed ``ForecastInputDataset`` per batch item.
+
+        Returns:
+            One raw ``ForecastDataset`` per input, in input order.
+        """
+        return [self._predict(input_data=item) for item in input_data]
+
     def score(self, data: TimeSeriesDataset) -> SubsetMetric:
         """Evaluate model performance on the provided dataset.
 
@@ -330,7 +383,7 @@ class BaseForecastingModel(BaseModel, Predictor[TimeSeriesDataset, ForecastDatas
         if prediction.target_series is None:
             raise ValueError("Prediction dataset must contain target series for scoring.")
 
-        prediction = prediction.pipe_pandas(pd.DataFrame.dropna, subset=[self.target_column])  # pyright: ignore[reportUnknownArgumentType, reportUnknownMemberType]
+        prediction = prediction.pipe_pandas(pd.DataFrame.dropna, subset=[self.target_column])
 
         pipeline = EvaluationPipeline(
             config=EvaluationConfig(available_ats=[], lead_times=[self.max_horizon]),
@@ -482,7 +535,7 @@ class ForecastingModel(BaseForecastingModel):
         """
         validate_horizons_present(data, self.forecaster.horizons)
 
-        target_dropna = partial(pd.DataFrame.dropna, subset=[self.target_column])  # pyright: ignore[reportUnknownMemberType]
+        target_dropna = partial(pd.DataFrame.dropna, subset=[self.target_column])
         if data.pipe_pandas(target_dropna).data.empty:
             msg = (
                 f"No training data available after dropping NaN targets in column '{self.target_column}'. "
@@ -542,6 +595,22 @@ class ForecastingModel(BaseForecastingModel):
         prediction = self.forecaster.predict(data=input_data)
         return restore_target(dataset=prediction, original_dataset=input_data, target_column=self.target_column)
 
+    @override
+    def _predict_batch(self, input_data: list[ForecastInputDataset]) -> list[ForecastDataset]:
+        raw = self.forecaster.predict_batch(data=input_data)
+        forecasts: list[ForecastDataset] = []
+        for item, forecast in zip(input_data, raw, strict=True):
+            if isinstance(forecast, PredictError):
+                raise forecast
+            forecasts.append(
+                restore_target(
+                    dataset=forecast,
+                    original_dataset=item,
+                    target_column=self.target_column,
+                )
+            )
+        return forecasts
+
     @override
     def predict_contributions(
         self,
@@ -580,7 +649,7 @@ def restore_target[T: TimeSeriesDataset](
     target_series = original_dataset.select_features([target_column]).select_version().data[target_column]
 
     def _transform_restore_target(df: pd.DataFrame) -> pd.DataFrame:
-        original_values = df.index.map(target_series)  # pyright: ignore[reportUnknownMemberType]
+        original_values = df.index.map(target_series)  # ty: ignore[invalid-argument-type]
         restored = pd.Series(original_values, index=df.index, name=target_column)
 
         # Preserve NaN values introduced by the OutlierHandler for the target column.