tirex-mirror 2025.12.2__tar.gz → 2025.12.23__tar.gz

{tirex_mirror-2025.12.2/src/tirex_mirror.egg-info → tirex_mirror-2025.12.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tirex-mirror
-Version: 2025.12.2
+Version: 2025.12.23
 Summary: Unofficial mirror of NX-AI/tirex for packaging
 Author-email: Arpad Rozsas <rozsasarpi@gmail.com>
 License: NXAI COMMUNITY LICENSE AGREEMENT
@@ -55,7 +55,7 @@ License: NXAI COMMUNITY LICENSE AGREEMENT
         
 Project-URL: Repository, https://github.com/rozsasarpi/tirex-mirror
 Project-URL: Issues, https://github.com/rozsasarpi/tirex-mirror/issues
-Keywords: TiRex,xLSTM,Time Series,Zero-shot,Deep Learning,Classification,Timeseries-Classification
+Keywords: TiRex,xLSTM,Timeseries,Zero-shot,Deep Learning,Timeseries-Forecasting,Timeseries-Classification,Timeseries-Regression
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
@@ -66,6 +66,7 @@ License-File: NOTICE.txt
 Requires-Dist: torch
 Requires-Dist: huggingface-hub
 Requires-Dist: numpy
+Requires-Dist: scikit-learn
 Provides-Extra: cuda
 Requires-Dist: xlstm; extra == "cuda"
 Requires-Dist: ninja; extra == "cuda"
@@ -84,9 +85,11 @@ Requires-Dist: datasets; extra == "hfdataset"
 Provides-Extra: test
 Requires-Dist: fev>=0.6.0; extra == "test"
 Requires-Dist: pytest; extra == "test"
+Requires-Dist: aeon; extra == "test"
 Provides-Extra: classification
-Requires-Dist: scikit-learn; extra == "classification"
 Requires-Dist: lightgbm[scikit-learn]; extra == "classification"
+Provides-Extra: regression
+Requires-Dist: lightgbm[scikit-learn]; extra == "regression"
 Provides-Extra: all
 Requires-Dist: xlstm; extra == "all"
 Requires-Dist: ninja; extra == "all"

{tirex_mirror-2025.12.2 → tirex_mirror-2025.12.23}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "tirex-mirror"
-version = "2025.12.02"
+version = "2025.12.23"
 description = "Unofficial mirror of NX-AI/tirex for packaging"
 readme = "README.md"
 requires-python = ">=3.11"
 classifiers = [ "Programming Language :: Python :: 3", "Operating System :: OS Independent",]
-keywords = [ "TiRex", "xLSTM", "Time Series", "Zero-shot", "Deep Learning", "Classification", "Timeseries-Classification",]
-dependencies = [ "torch", "huggingface-hub", "numpy",]
+keywords = [ "TiRex", "xLSTM", "Timeseries", "Zero-shot", "Deep Learning", "Timeseries-Forecasting", "Timeseries-Classification", "Timeseries-Regression",]
+dependencies = [ "torch", "huggingface-hub", "numpy", "scikit-learn",]
 [[project.authors]]
 name = "Arpad Rozsas"
 email = "rozsasarpi@gmail.com"
@@ -28,8 +28,9 @@ notebooks = [ "ipykernel", "matplotlib", "pandas", "python-dotenv",]
 plotting = [ "matplotlib",]
 gluonts = [ "gluonts", "pandas",]
 hfdataset = [ "datasets",]
-test = [ "fev>=0.6.0", "pytest",]
-classification = [ "scikit-learn", "lightgbm[scikit-learn]",]
+test = [ "fev>=0.6.0", "pytest", "aeon",]
+classification = [ "lightgbm[scikit-learn]",]
+regression = [ "lightgbm[scikit-learn]",]
 all = [ "xlstm", "ninja", "ipykernel", "matplotlib", "pandas", "python-dotenv", "gluonts", "datasets", "pytest", "fev>=0.6.0", "scikit-learn", "lightgbm[scikit-learn]",]
 
 [tool.docformatter]

tirex_mirror-2025.12.23/src/tirex/models/base/base_classifier.py

@@ -0,0 +1,36 @@
+# Copyright (c) NXAI GmbH.
+# This software may be used and distributed according to the terms of the NXAI Community License Agreement.
+
+import torch
+
+from .base_tirex import BaseTirexEmbeddingModel
+
+
+class BaseTirexClassifier(BaseTirexEmbeddingModel):
+    """Abstract base class for TiRex classification models."""
+
+    @torch.inference_mode()
+    def predict(self, x: torch.Tensor) -> torch.Tensor:
+        """Predict class labels for input time series data.
+
+        Args:
+            x: Input time series data as torch.Tensor with shape
+                (batch_size, num_variates, seq_len).
+        Returns:
+            torch.Tensor: Predicted class labels with shape (batch_size,).
+        """
+        emb = self._compute_embeddings(x)
+        return torch.from_numpy(self.head.predict(emb)).long()
+
+    @torch.inference_mode()
+    def predict_proba(self, x: torch.Tensor) -> torch.Tensor:
+        """Predict class probabilities for input time series data.
+
+        Args:
+            x: Input time series data as torch.Tensor with shape
+                (batch_size, num_variates, seq_len).
+        Returns:
+            torch.Tensor: Class probabilities with shape (batch_size, num_classes).
+        """
+        emb = self._compute_embeddings(x)
+        return torch.from_numpy(self.head.predict_proba(emb))

tirex_mirror-2025.12.23/src/tirex/models/base/base_regressor.py

@@ -0,0 +1,23 @@
+# Copyright (c) NXAI GmbH.
+# This software may be used and distributed according to the terms of the NXAI Community License Agreement.
+
+import torch
+
+from .base_tirex import BaseTirexEmbeddingModel
+
+
+class BaseTirexRegressor(BaseTirexEmbeddingModel):
+    """Abstract base class for TiRex regression models."""
+
+    @torch.inference_mode()
+    def predict(self, x: torch.Tensor) -> torch.Tensor:
+        """Predict values for input time series data.
+
+        Args:
+            x: Input time series data as torch.Tensor with shape
+                (batch_size, num_variates, seq_len).
+        Returns:
+            torch.Tensor: Predicted values with shape (batch_size,).
+        """
+        emb = self._compute_embeddings(x)
+        return torch.from_numpy(self.head.predict(emb)).float()

tirex_mirror-2025.12.2/src/tirex/models/classification/heads/base_classifier.py → tirex_mirror-2025.12.23/src/tirex/models/base/base_tirex.py

@@ -3,15 +3,18 @@
 
 from abc import ABC, abstractmethod
 
+import numpy as np
 import torch
 
+from tirex.util import train_val_split
+
 from ..embedding import TiRexEmbedding
 
 
-class BaseTirexClassifier(ABC):
-    """Abstract base class for TiRex classification models.
+class BaseTirexEmbeddingModel(ABC):
+    """Abstract base class for TiRex models.
 
-    This base class provides common functionality for all TiRex classifiers,
+    This base class provides common functionality for all TiRex classifier and regression models,
     including embedding model initialization and a consistent interface.
 
     """
@@ -19,7 +22,10 @@ class BaseTirexClassifier(ABC):
     def __init__(
         self, data_augmentation: bool = False, device: str | None = None, compile: bool = False, batch_size: int = 512
     ) -> None:
-        """Initializes a TiRex classification model.
+        """Initializes a base TiRex model.
+
+        This base class initializes the embedding model and common configuration
+        used by both classification and regression models.
 
         Args:
             data_augmentation : bool
@@ -49,45 +55,55 @@ class BaseTirexClassifier(ABC):
 
     @abstractmethod
     def fit(self, train_data: tuple[torch.Tensor, torch.Tensor]) -> None:
+        """Abstract method for model training"""
         pass
 
-    @torch.inference_mode()
-    def predict(self, x: torch.Tensor) -> torch.Tensor:
-        """Predict class labels for input time series data.
+    def _compute_embeddings(self, x: torch.Tensor) -> np.ndarray:
+        """Compute embeddings for input time series data.
 
         Args:
             x: Input time series data as torch.Tensor with shape
                 (batch_size, num_variates, seq_len).
-        Returns:
-            torch.Tensor: Predicted class labels with shape (batch_size,).
-        """
-        self.emb_model.eval()
-        x = x.to(self.device)
-        embeddings = self.emb_model(x).cpu().numpy()
-        return torch.from_numpy(self.head.predict(embeddings)).long()
-
-    @torch.inference_mode()
-    def predict_proba(self, x: torch.Tensor) -> torch.Tensor:
-        """Predict class probabilities for input time series data.
 
-        Args:
-            x: Input time series data as torch.Tensor with shape
-                (batch_size, num_variates, seq_len).
         Returns:
-            torch.Tensor: Class probabilities with shape (batch_size, num_classes).
+            np.ndarray: Embeddings with shape (batch_size, embedding_dim).
         """
         self.emb_model.eval()
         x = x.to(self.device)
-        embeddings = self.emb_model(x).cpu().numpy()
-        return torch.from_numpy(self.head.predict_proba(embeddings))
+        return self.emb_model(x).cpu().numpy()
+
+    def _create_train_val_datasets(
+        self,
+        train_data: tuple[torch.Tensor, torch.Tensor],
+        val_data: tuple[torch.Tensor, torch.Tensor] | None = None,
+        val_split_ratio: float = 0.2,
+        stratify: bool = False,
+        seed: int | None = None,
+    ) -> tuple[tuple[torch.Tensor, torch.Tensor], tuple[torch.Tensor, torch.Tensor]]:
+        if val_data is None:
+            train_data, val_data = train_val_split(
+                train_data=train_data, val_split_ratio=val_split_ratio, stratify=stratify, seed=seed
+            )
+        return train_data, val_data
 
     @abstractmethod
     def save_model(self, path: str) -> None:
-        """Saving model abstract method"""
+        """Save model to file.
+
+        Args:
+            path: File path where the model should be saved.
+        """
         pass
 
     @classmethod
     @abstractmethod
     def load_model(cls, path: str):
-        """Loading model abstract method"""
+        """Load model from file.
+
+        Args:
+            path: File path to the saved model checkpoint.
+
+        Returns:
+            Instance of the model class with loaded weights and configuration.
+        """
         pass

tirex_mirror-2025.12.23/src/tirex/models/classification/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) NXAI GmbH.
+# This software may be used and distributed according to the terms of the NXAI Community License Agreement.
+
+from .gbm_classifier import TirexGBMClassifier
+from .linear_classifier import TirexLinearClassifier
+from .rf_classifier import TirexRFClassifier
+
+__all__ = ["TirexLinearClassifier", "TirexRFClassifier", "TirexGBMClassifier"]

{tirex_mirror-2025.12.2/src/tirex/models/classification/heads → tirex_mirror-2025.12.23/src/tirex/models/classification}/gbm_classifier.py

@@ -5,8 +5,7 @@ import joblib
 import torch
 from lightgbm import LGBMClassifier, early_stopping
 
-from ..utils import train_val_split
-from .base_classifier import BaseTirexClassifier
+from ..base.base_classifier import BaseTirexClassifier
 
 
 class TirexGBMClassifier(BaseTirexClassifier):
@@ -118,11 +117,11 @@ class TirexGBMClassifier(BaseTirexClassifier):
             seed=self.random_state,
         )
 
-        self.emb_model.eval()
         X_train = X_train.to(self.device)
         X_val = X_val.to(self.device)
-        embeddings_train = self.emb_model(X_train).cpu().numpy()
-        embeddings_val = self.emb_model(X_val).cpu().numpy()
+
+        embeddings_train = self._compute_embeddings(X_train)
+        embeddings_val = self._compute_embeddings(X_val)
 
         y_train = y_train.detach().cpu().numpy() if isinstance(y_train, torch.Tensor) else y_train
         y_val = y_val.detach().cpu().numpy() if isinstance(y_val, torch.Tensor) else y_val
@@ -187,24 +186,3 @@ class TirexGBMClassifier(BaseTirexClassifier):
         model.random_state = getattr(model.head, "random_state", None)
 
         return model
-
-    def _create_train_val_datasets(
-        self,
-        train_data: tuple[torch.Tensor, torch.Tensor],
-        val_data: tuple[torch.Tensor, torch.Tensor] | None = None,
-        val_split_ratio: float = 0.2,
-        stratify: bool = True,
-        seed: int | None = None,
-    ) -> tuple[tuple[torch.Tensor, torch.Tensor], tuple[torch.Tensor, torch.Tensor]]:
-        X_train, y_train = train_data
-
-        if val_data is None:
-            train_data, val_data = train_val_split(
-                train_data=train_data, val_split_ratio=val_split_ratio, stratify=stratify, seed=seed
-            )
-            X_train, y_train = train_data
-            X_val, y_val = val_data
-        else:
-            X_val, y_val = val_data
-
-        return (X_train, y_train), (X_val, y_val)

{tirex_mirror-2025.12.2/src/tirex/models/classification/heads → tirex_mirror-2025.12.23/src/tirex/models/classification}/linear_classifier.py

@@ -5,11 +5,11 @@ from dataclasses import asdict
 
 import torch
 
-from ..trainer import TrainConfig, Trainer
-from .base_classifier import BaseTirexClassifier
+from ..base.base_classifier import BaseTirexClassifier
+from ..trainer import TrainConfig, Trainer, TrainingMetrics
 
 
-class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
+class TirexLinearClassifier(BaseTirexClassifier, torch.nn.Module):
     """
     A PyTorch classifier that combines time series embeddings with a linear classification head.
 
@@ -19,10 +19,10 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
 
     Example:
         >>> import torch
-        >>> from tirex.models.classification import TirexClassifierTorch
+        >>> from tirex.models.classification import TirexLinearClassifier
         >>>
         >>> # Create model with TiRex embeddings
-        >>> model = TirexClassifierTorch(
+        >>> model = TirexLinearClassifier(
         ...     data_augmentation=True,
         ...     max_epochs=2,
         ...     lr=1e-4,
@@ -72,7 +72,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
             compile: bool
                 Whether to compile the frozen embedding model. Default: False
             max_epochs : int
-                Maximum number of training epochs. Default: 50
+                Maximum number of training epochs. Default: 10
             lr : float
                 Learning rate for the optimizer. Default: 1e-4
             weight_decay : float
@@ -115,6 +115,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
             lr=lr,
             weight_decay=weight_decay,
             class_weights=class_weights,
+            task_type="classification",
             batch_size=batch_size,
             val_split_ratio=val_split_ratio,
             stratify=stratify,
@@ -132,9 +133,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
 
     @torch.inference_mode()
     def _identify_head_dims(self, x: torch.Tensor, y: torch.Tensor) -> None:
-        self.emb_model.eval()
-        sample_emb = self.emb_model(x[:1])
-        self.emb_dim = sample_emb.shape[-1]
+        self.emb_dim = self._compute_embeddings(x[:1]).shape[-1]
         self.num_classes = len(torch.unique(y))
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
@@ -155,7 +154,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
 
     def fit(
         self, train_data: tuple[torch.Tensor, torch.Tensor], val_data: tuple[torch.Tensor, torch.Tensor] | None = None
-    ) -> dict[str, float]:
+    ) -> TrainingMetrics:
         """Train the classification head on the provided data.
 
         This method initializes the classification head based on the data dimensions,
@@ -231,7 +230,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
         )
 
     @classmethod
-    def load_model(cls, path: str) -> "TirexClassifierTorch":
+    def load_model(cls, path: str) -> "TirexLinearClassifier":
         """Load a saved model from file.
 
         This reconstructs the model architecture and loads the trained weights from
@@ -240,7 +239,7 @@ class TirexClassifierTorch(BaseTirexClassifier, torch.nn.Module):
         Args:
             path: File path to the saved model checkpoint.
         Returns:
-            TirexClassifierTorch: The loaded model with trained weights, ready for inference.
+            TirexLinearClassifier: The loaded model with trained weights, ready for inference.
         """
         checkpoint = torch.load(path)
 

{tirex_mirror-2025.12.2/src/tirex/models/classification/heads → tirex_mirror-2025.12.23/src/tirex/models/classification}/rf_classifier.py

@@ -5,7 +5,7 @@ import joblib
 import torch
 from sklearn.ensemble import RandomForestClassifier
 
-from .base_classifier import BaseTirexClassifier
+from ..base.base_classifier import BaseTirexClassifier
 
 
 class TirexRFClassifier(BaseTirexClassifier):
@@ -84,9 +84,9 @@ class TirexRFClassifier(BaseTirexClassifier):
         if isinstance(y_train, torch.Tensor):
             y_train = y_train.detach().cpu().numpy()
 
-        self.emb_model.eval()
         X_train = X_train.to(self.device)
-        embeddings = self.emb_model(X_train).cpu().numpy()
+        embeddings = self._compute_embeddings(X_train)
+
         self.head.fit(embeddings, y_train)
 
     def save_model(self, path: str) -> None:

{tirex_mirror-2025.12.2/src/tirex/models/classification → tirex_mirror-2025.12.23/src/tirex/models}/embedding.py

@@ -6,8 +6,7 @@ import torch.nn as nn
 import torch.nn.functional as F
 
 from tirex import load_model
-
-from .utils import nanmax, nanmin, nanstd
+from tirex.util import nanmax, nanmin, nanstd
 
 
 class TiRexEmbedding(nn.Module):
@@ -20,7 +19,7 @@ class TiRexEmbedding(nn.Module):
         self.batch_size = batch_size
 
         if device is None:
-            device = "cuda" if torch.cuda.is_available() else "cpu"
+            device = "cuda:0" if torch.cuda.is_available() else "cpu"
         self.device = device
         self._compile = compile
 

tirex_mirror-2025.12.23/src/tirex/models/regression/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) NXAI GmbH.
+# This software may be used and distributed according to the terms of the NXAI Community License Agreement.
+
+from .gbm_regressor import TirexGBMRegressor
+from .linear_regressor import TirexLinearRegressor
+from .rf_regressor import TirexRFRegressor
+
+__all__ = ["TirexLinearRegressor", "TirexRFRegressor", "TirexGBMRegressor"]

tirex_mirror-2025.12.23/src/tirex/models/regression/gbm_regressor.py

@@ -0,0 +1,181 @@
+# Copyright (c) NXAI GmbH.
+# This software may be used and distributed according to the terms of the NXAI Community License Agreement.
+
+import joblib
+import torch
+from lightgbm import LGBMRegressor, early_stopping
+
+from ..base.base_regressor import BaseTirexRegressor
+
+
+class TirexGBMRegressor(BaseTirexRegressor):
+    """
+    A Gradient Boosting regressor that uses time series embeddings as features.
+
+    This regressor combines a pre-trained embedding model for feature extraction with a
+    Gradient Boosting regressor.
+
+    Example:
+        >>> import torch
+        >>> from tirex.models.regression import TirexGBMRegressor
+        >>>
+        >>> # Create model with custom LightGBM parameters
+        >>> model = TirexGBMRegressor(
+        ...     data_augmentation=True,
+        ...     n_estimators=50,
+        ...     random_state=42
+        ... )
+        >>>
+        >>> # Prepare data (can use NumPy arrays or PyTorch tensors)
+        >>> X_train = torch.randn(100, 1, 128)  # 100 samples, 1 number of variates, 128 sequence length
+        >>> y_train = torch.randn(100,)  # target values
+        >>>
+        >>> # Train the model
+        >>> model.fit((X_train, y_train))
+        >>>
+        >>> # Make predictions
+        >>> X_test = torch.randn(20, 1, 128)
+        >>> predictions = model.predict(X_test)
+    """
+
+    def __init__(
+        self,
+        data_augmentation: bool = False,
+        device: str | None = None,
+        compile: bool = False,
+        batch_size: int = 512,
+        early_stopping_rounds: int | None = 10,
+        min_delta: float = 0.0,
+        val_split_ratio: float = 0.2,
+        # LightGBM kwargs
+        **lgbm_kwargs,
+    ) -> None:
+        """Initializes Embedding Based Gradient Boosting Regression model.
+
+        Args:
+            data_augmentation : bool
+                Whether to use data_augmentation for embeddings (sample statistics and first-order differences of the original data). Default: False
+            device : str | None
+                Device to run the embedding model on. If None, uses CUDA if available, else CPU. Default: None
+            compile: bool
+                Whether to compile the frozen embedding model. Default: False
+            batch_size : int
+                Batch size for embedding calculations. Default: 512
+            early_stopping_rounds: int | None
+                Number of rounds without improvement of all metrics for Early Stopping. Default: 10
+            min_delta: float
+                Minimum improvement in score to keep training. Default 0.0
+            val_split_ratio : float
+                Proportion of training data to use for validation, if validation data are not provided. Default: 0.2
+            **lgbm_kwargs
+                Additional keyword arguments to pass to LightGBM's LGBMRegressor.
+                Common options include n_estimators, max_depth, learning_rate, random_state, etc.
+        """
+        super().__init__(data_augmentation=data_augmentation, device=device, compile=compile, batch_size=batch_size)
+
+        # Early Stopping callback
+        self.early_stopping_rounds = early_stopping_rounds
+        self.min_delta = min_delta
+
+        # Data split parameters:
+        self.val_split_ratio = val_split_ratio
+
+        # Extract random_state for train_val_split if provided
+        self.random_state = lgbm_kwargs.get("random_state", None)
+
+        self.head = LGBMRegressor(**lgbm_kwargs)
+
+    @torch.inference_mode()
+    def fit(
+        self,
+        train_data: tuple[torch.Tensor, torch.Tensor],
+        val_data: tuple[torch.Tensor, torch.Tensor] | None = None,
+    ) -> None:
+        """Train the LightGBM regressor on embedded time series data.
+
+        This method generates embeddings for the training data using the embedding
+        model, then trains the LightGBM regressor on these embeddings.
+
+        Args:
+            train_data: Tuple of (X_train, y_train) where X_train is the input time
+                series data (torch.Tensor) and y_train is a torch.Tensor
+                of target values.
+            val_data: Optional tuple of (X_val, y_val) for validation where X_val is the input time
+                series data (torch.Tensor) and y_val is a torch.Tensor
+                of target values. If None, validation data will be automatically split from train_data (20% split).
+        """
+
+        (X_train, y_train), (X_val, y_val) = self._create_train_val_datasets(
+            train_data=train_data,
+            val_data=val_data,
+            val_split_ratio=self.val_split_ratio,
+            seed=self.random_state,
+        )
+
+        X_train = X_train.to(self.device)
+        X_val = X_val.to(self.device)
+
+        embeddings_train = self._compute_embeddings(X_train)
+        embeddings_val = self._compute_embeddings(X_val)
+
+        y_train = y_train.detach().cpu().numpy() if isinstance(y_train, torch.Tensor) else y_train
+        y_val = y_val.detach().cpu().numpy() if isinstance(y_val, torch.Tensor) else y_val
+
+        self.head.fit(
+            embeddings_train,
+            y_train,
+            eval_set=[(embeddings_val, y_val)],
+            callbacks=[early_stopping(stopping_rounds=self.early_stopping_rounds, min_delta=self.min_delta)]
+            if self.early_stopping_rounds is not None
+            else None,
+        )
+
+    def save_model(self, path: str) -> None:
+        """This method saves the trained LightGBM regressor head (joblib format) and embedding information.
+
+        Args:
+            path: File path where the model should be saved (e.g., 'model.joblib').
+        """
+
+        payload = {
+            "data_augmentation": self.data_augmentation,
+            "compile": self._compile,
+            "batch_size": self.batch_size,
+            "early_stopping_rounds": self.early_stopping_rounds,
+            "min_delta": self.min_delta,
+            "val_split_ratio": self.val_split_ratio,
+            "head": self.head,
+        }
+        joblib.dump(payload, path)
+
+    @classmethod
+    def load_model(cls, path: str) -> "TirexGBMRegressor":
+        """Load a saved model from file.
+
+        This reconstructs the model with the embedding configuration and loads
+        the trained LightGBM regressor from a checkpoint file created by save_model().
+
+        Args:
+            path: File path to the saved model checkpoint.
+        Returns:
+            TirexGBMRegressor: The loaded model with trained Gradient Boosting regressor, ready for inference.
+        """
+        checkpoint = joblib.load(path)
+
+        # Create new instance with saved configuration
+        model = cls(
+            data_augmentation=checkpoint["data_augmentation"],
+            compile=checkpoint["compile"],
+            batch_size=checkpoint["batch_size"],
+            early_stopping_rounds=checkpoint["early_stopping_rounds"],
+            min_delta=checkpoint["min_delta"],
+            val_split_ratio=checkpoint["val_split_ratio"],
+        )
+
+        # Load the trained LightGBM head
+        model.head = checkpoint["head"]
+
+        # Extract random_state from the loaded head if available
+        model.random_state = getattr(model.head, "random_state", None)
+
+        return model