eb-adapters 0.1.0__py3-none-any.whl

eb_adapters/__init__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+"""
+eb_adapters.
+
+Adapter classes for integrating external forecasting and regression engines
+(Prophet, statsmodels, CatBoost, LightGBM, etc.) into the ElectricBarometer
+ecosystem using a consistent scikit-learn-like interface.
+
+All adapters exposed by this package implement:
+
+- `fit(X, y, sample_weight=None)` returning `self`
+- `predict(X)` returning a one-dimensional numpy array
+
+This allows ElectricBarometer evaluation, selection, and cloning utilities to
+treat native scikit-learn estimators and wrapped external models uniformly.
+"""
+
+from .base import BaseAdapter, _clone_model, clone_model
+from .prophet import ProphetAdapter
+from .statsmodels import SarimaxAdapter, ArimaAdapter
+from .catboost import CatBoostAdapter
+from .lightgbm import LightGBMRegressorAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "_clone_model",
+    "clone_model",
+    "ProphetAdapter",
+    "SarimaxAdapter",
+    "ArimaAdapter",
+    "CatBoostAdapter",
+    "LightGBMRegressorAdapter",
+]

eb_adapters/base.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+"""
+Base adapter interfaces and cloning utilities.
+
+This module defines the minimal adapter contract used throughout the
+ElectricBarometer ecosystem, along with a lightweight cloning helper for
+estimator-like objects.
+
+Adapters are intended to wrap non-scikit-learn forecasting or regression
+libraries (for example, statsmodels, Prophet, or custom models) and expose
+a scikit-learn-like interface so they can be used interchangeably inside
+ElectricBarometer evaluation and selection workflows.
+"""
+
+from typing import Any, Optional
+
+import numpy as np
+
+
+def _clone_model(model: Any) -> Any:
+    """
+    Lightweight cloning utility for estimator-like or adapter-like objects.
+
+    This function attempts to reconstruct a fresh instance of a model using a
+    best-effort strategy that favors compatibility with scikit-learn-style APIs
+    while remaining usable for custom adapters.
+
+    Cloning strategy
+    ----------------
+    The following steps are attempted in order:
+
+    1. If scikit-learn is available, call `sklearn.base.clone(model)`.
+    2. Otherwise, if the object implements `get_params()`, re-instantiate via::
+
+           model.__class__(**model.get_params())
+
+    3. As a final fallback, instantiate the class with no arguments::
+
+           model.__class__()
+
+    Notes
+    -----
+    For custom adapters, the most reliable approach is to make the adapter
+    configuration-only at initialization time and implement `get_params()`
+    so that the instance can be reconstructed deterministically.
+
+    If a model cannot be meaningfully cloned using parameters alone, callers
+    may choose to bypass this helper and explicitly construct fresh adapter
+    instances before passing them into ElectricBarometer workflows.
+    """
+    # Try sklearn.clone if available
+    try:  # pragma: no cover - optional dependency path
+        from sklearn.base import clone as sk_clone  # type: ignore
+
+        return sk_clone(model)
+    except Exception:
+        pass
+
+    # Fallback: re-create via class + get_params
+    if hasattr(model, "get_params"):
+        try:
+            params = model.get_params()  # type: ignore[assignment]
+            return model.__class__(**params)
+        except Exception:
+            # If get_params exists but reconstruction fails, fall through
+            # to the final fallback below.
+            pass
+
+    # Last resort: call class with no args
+    return model.__class__()
+
+
+# Optional public alias for convenience / backwards compatibility
+clone_model = _clone_model
+
+
+class BaseAdapter:
+    """
+    Minimal base class defining the adapter contract for ElectricBarometer.
+
+    This class documents the expected interface for wrapping non-scikit-learn
+    forecasting or regression engines so they can be evaluated and selected
+    alongside native scikit-learn estimators.
+
+    Subclasses are expected to present a scikit-learn-like API:
+
+    - `fit(X, y, sample_weight=None)` returning `self`
+    - `predict(X)` returning a one-dimensional numpy array
+
+    The ElectricBarometer engine does not distinguish between native
+    scikit-learn estimators and adapters; it simply calls `fit` and `predict`.
+    This base class serves as a clear, documented contract for adapter authors.
+    """
+
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> "BaseAdapter":
+        """
+        Fit the underlying forecasting or regression model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix. For pure time-series models, this may be ignored
+            or used only for alignment.
+        y : numpy.ndarray
+            One-dimensional target vector.
+        sample_weight : numpy.ndarray | None
+            Optional per-sample weights. Adapters may ignore this argument if
+            weighting is not supported by the underlying model.
+
+        Returns
+        -------
+        BaseAdapter
+            The fitted adapter instance (self).
+
+        Raises
+        ------
+        NotImplementedError
+            If the subclass does not override this method.
+        """
+        raise NotImplementedError(
+            "BaseAdapter subclasses must implement fit(X, y, sample_weight=None)."
+        )
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Generate predictions from the fitted model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix used to generate predictions.
+
+        Returns
+        -------
+        numpy.ndarray
+            One-dimensional array of predictions.
+
+        Raises
+        ------
+        NotImplementedError
+            If the subclass does not override this method.
+        """
+        raise NotImplementedError(
+            "BaseAdapter subclasses must implement predict(X)."
+        )

eb_adapters/catboost.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+"""
+CatBoost adapter.
+
+This module provides `CatBoostAdapter`, a thin wrapper around
+`catboost.CatBoostRegressor` with a scikit-learn-like interface (`fit`, `predict`).
+
+The adapter is designed for use within the ElectricBarometer ecosystem and aims to be:
+
+- Lightweight: minimal behavior beyond input normalization and parameter storage.
+- Cloneable: constructor parameters are preserved in `self.params` so cloning utilities
+  can reconstruct the instance consistently.
+- Optional-dependency safe: importing this module does not require CatBoost, but
+  instantiating `CatBoostAdapter` does.
+
+"""
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .base import BaseAdapter
+
+
+# Optional CatBoost dependency guard -----------------------------------------
+try:  # pragma: no cover - optional dependency
+    from catboost import CatBoostRegressor  # type: ignore
+
+    HAS_CATBOOST = True
+except Exception:  # pragma: no cover - optional dependency
+    CatBoostRegressor = None
+    HAS_CATBOOST = False
+
+
+class CatBoostAdapter(BaseAdapter):
+    """
+    Adapter for `catboost.CatBoostRegressor`.
+
+    This adapter exposes a scikit-learn-like API and stores initialization parameters
+    so the instance can be reconstructed by cloning utilities (for example, an internal
+    `clone_model()` helper or `sklearn.base.clone`).
+
+    Parameters
+    ----------
+    **params
+        Keyword arguments forwarded to `catboost.CatBoostRegressor`.
+
+    Notes
+    -----
+    - `X` and `y` are treated as standard tabular regression inputs.
+    - If provided, `sample_weight` is passed through to CatBoost training.
+    - Training verbosity is disabled by default (`verbose=False`) unless the caller
+      supplies `verbose` explicitly.
+    - All initialization parameters are stored in `self.params`.
+
+    Examples
+    --------
+    >>> model = CatBoostAdapter(
+    ...     depth=4,
+    ...     learning_rate=0.1,
+    ...     iterations=200,
+    ...     loss_function="RMSE",
+    ... )
+    >>> # X, y are numpy arrays (or array-like)
+    >>> # model.fit(X, y).predict(X)
+
+    """
+
+    def __init__(self, **params: Any) -> None:
+        if not HAS_CATBOOST:
+            raise ImportError(
+                "CatBoostAdapter requires the optional 'catboost' package. "
+                "Install it via `pip install catboost`."
+            )
+
+        # Store params for clone() compatibility
+        self.params: Dict[str, Any] = dict(params)
+
+        # Default: no spammy training logs
+        if "verbose" not in self.params:
+            self.params["verbose"] = False
+
+        # Instantiate the underlying CatBoost model
+        self.model: Optional[CatBoostRegressor] = CatBoostRegressor(**self.params)
+
+    # ------------------------------------------------------------------
+    # Fit
+    # ------------------------------------------------------------------
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> "CatBoostAdapter":
+        """
+        Fit the underlying `catboost.CatBoostRegressor`.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix of shape (n_samples, n_features).
+        y : numpy.ndarray
+            Target vector of shape (n_samples,).
+        sample_weight : numpy.ndarray | None
+            Optional per-sample weights of shape (n_samples,). If provided, this is
+            forwarded to CatBoost training.
+
+        Returns
+        -------
+        CatBoostAdapter
+            The fitted adapter (self), allowing method chaining.
+
+        Raises
+        ------
+        RuntimeError
+            If CatBoost is not available or the internal model is not initialized.
+
+        """
+        if not HAS_CATBOOST or self.model is None:
+            raise RuntimeError(
+                "CatBoostAdapter cannot train: CatBoost is not available or "
+                "the internal model was not initialized correctly."
+            )
+
+        X_arr = np.asarray(X)
+        y_arr = np.asarray(y, dtype=float)
+
+        if sample_weight is not None:
+            sw_arr = np.asarray(sample_weight, dtype=float)
+            self.model.fit(X_arr, y_arr, sample_weight=sw_arr)
+        else:
+            self.model.fit(X_arr, y_arr)
+
+        return self
+
+    # ------------------------------------------------------------------
+    # Predict
+    # ------------------------------------------------------------------
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Predict using the fitted CatBoost model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix of shape (n_samples, n_features).
+
+        Returns
+        -------
+        numpy.ndarray
+            Predicted values of shape (n_samples,).
+
+        Raises
+        ------
+        RuntimeError
+            If the adapter has not been fit yet.
+
+        """
+        if self.model is None:
+            raise RuntimeError("CatBoostAdapter has not been fit yet. Call `fit(...)` first.")
+
+        X_arr = np.asarray(X)
+        preds = self.model.predict(X_arr)
+        return np.asarray(preds, dtype=float).ravel()
+
+    # ------------------------------------------------------------------
+    # Param API for clone_model() compatibility
+    # ------------------------------------------------------------------
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        """
+        Return initialization parameters for cloning utilities.
+
+        Parameters
+        ----------
+        deep : bool
+            Included for scikit-learn compatibility. This adapter does not expose
+            nested estimators, so the value does not change the output.
+
+        Returns
+        -------
+        dict[str, Any]
+            A shallow copy of the stored initialization parameters.
+
+        """
+        _ = deep  # intentionally unused; kept for API compatibility
+        return dict(self.params)
+
+    def set_params(self, **params: Any) -> "CatBoostAdapter":
+        """
+        Update parameters and rebuild the underlying CatBoost model.
+
+        Parameters
+        ----------
+        **params
+            Keyword parameters to merge into the stored initialization parameters.
+
+        Returns
+        -------
+        CatBoostAdapter
+            The updated adapter instance (self).
+
+        Notes
+        -----
+        This method updates `self.params` and then re-instantiates
+        `catboost.CatBoostRegressor` using the merged parameter set.
+
+        """
+        self.params.update(params)
+        if HAS_CATBOOST:
+            self.model = CatBoostRegressor(**self.params)
+        return self
+
+    # ------------------------------------------------------------------
+    # Representation
+    # ------------------------------------------------------------------
+    def __repr__(self) -> str:
+        return f"CatBoostAdapter(params={self.params})"

eb_adapters/lightgbm.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+"""
+LightGBM adapter.
+
+This module provides `LightGBMRegressorAdapter`, a thin wrapper around
+`lightgbm.LGBMRegressor` with a scikit-learn-like interface (`fit`, `predict`).
+
+The adapter is designed for use within the ElectricBarometer ecosystem and aims to be:
+
+- Lightweight: minimal behavior beyond input normalization and parameter storage.
+- Cloneable: constructor parameters are preserved so cloning utilities can
+  reconstruct the instance consistently.
+- Optional-dependency safe: importing this module does not require LightGBM, but
+  instantiating `LightGBMRegressorAdapter` does.
+
+"""
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .base import BaseAdapter
+
+
+# Optional LightGBM dependency guard ------------------------------------------
+try:  # pragma: no cover - optional dependency
+    from lightgbm import LGBMRegressor  # type: ignore
+
+    HAS_LIGHTGBM = True
+except Exception:  # pragma: no cover - optional dependency
+    LGBMRegressor = None
+    HAS_LIGHTGBM = False
+
+
+class LightGBMRegressorAdapter(BaseAdapter):
+    """
+    Adapter for `lightgbm.LGBMRegressor`.
+
+    This adapter exposes a scikit-learn-like API and stores initialization parameters
+    so the instance can be reconstructed by cloning utilities (for example, an internal
+    `clone_model()` helper or `sklearn.base.clone`).
+
+    Parameters
+    ----------
+    **lgbm_params
+        Keyword arguments forwarded to `lightgbm.LGBMRegressor`.
+
+    Notes
+    -----
+    - `X` and `y` are treated as standard tabular regression inputs.
+    - If provided, `sample_weight` is passed through to LightGBM training.
+    - All initialization parameters are stored in `self.lgbm_params`.
+
+    Examples
+    --------
+    >>> model = LightGBMRegressorAdapter(
+    ...     n_estimators=200,
+    ...     learning_rate=0.05,
+    ...     max_depth=-1,
+    ... )
+    >>> # X, y are numpy arrays (or array-like)
+    >>> # model.fit(X, y).predict(X)
+
+    """
+
+    def __init__(self, **lgbm_params: Any) -> None:
+        if not HAS_LIGHTGBM:
+            raise ImportError(
+                "LightGBMRegressorAdapter requires the optional 'lightgbm' package. "
+                "Install it via `pip install lightgbm`."
+            )
+
+        # Store init params so the adapter is cloneable.
+        self.lgbm_params: Dict[str, Any] = dict(lgbm_params)
+
+        # Underlying LightGBM model instance
+        self.model: Optional[LGBMRegressor] = LGBMRegressor(**self.lgbm_params)
+
+    # ------------------------------------------------------------------
+    # Fit
+    # ------------------------------------------------------------------
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> "LightGBMRegressorAdapter":
+        """
+        Fit the underlying `lightgbm.LGBMRegressor`.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix of shape (n_samples, n_features).
+        y : numpy.ndarray
+            Target vector of shape (n_samples,).
+        sample_weight : numpy.ndarray | None
+            Optional per-sample weights of shape (n_samples,). If provided, this is
+            forwarded to LightGBM training.
+
+        Returns
+        -------
+        LightGBMRegressorAdapter
+            The fitted adapter (self), allowing method chaining.
+
+        Raises
+        ------
+        RuntimeError
+            If LightGBM is not available or the internal model is not initialized.
+
+        """
+        if not HAS_LIGHTGBM or self.model is None:
+            raise RuntimeError(
+                "LightGBMRegressorAdapter cannot train: LightGBM is not available "
+                "or the internal model was not initialized."
+            )
+
+        X_arr = np.asarray(X)
+        y_arr = np.asarray(y, dtype=float)
+
+        if sample_weight is not None:
+            sw_arr = np.asarray(sample_weight, dtype=float)
+            self.model.fit(X_arr, y_arr, sample_weight=sw_arr)
+        else:
+            self.model.fit(X_arr, y_arr)
+
+        return self
+
+    # ------------------------------------------------------------------
+    # Predict
+    # ------------------------------------------------------------------
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Predict using the fitted LightGBM model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Feature matrix of shape (n_samples, n_features).
+
+        Returns
+        -------
+        numpy.ndarray
+            Predicted values of shape (n_samples,).
+
+        Raises
+        ------
+        RuntimeError
+            If the adapter has not been fit yet.
+
+        """
+        if self.model is None:
+            raise RuntimeError(
+                "LightGBMRegressorAdapter has not been fit yet. Call `fit(...)` first."
+            )
+
+        X_arr = np.asarray(X)
+        preds = self.model.predict(X_arr)
+        return np.asarray(preds, dtype=float).ravel()
+
+    # ------------------------------------------------------------------
+    # Param API for clone_model() compatibility
+    # ------------------------------------------------------------------
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        """
+        Return initialization parameters for cloning utilities.
+
+        Parameters
+        ----------
+        deep : bool
+            Included for scikit-learn compatibility. This adapter does not expose
+            nested estimators, so the value does not change the output.
+
+        Returns
+        -------
+        dict[str, Any]
+            A shallow copy of the stored initialization parameters.
+
+        """
+        _ = deep  # intentionally unused; kept for API compatibility
+        return dict(self.lgbm_params)
+
+    def set_params(self, **params: Any) -> "LightGBMRegressorAdapter":
+        """
+        Update parameters and rebuild the underlying LightGBM model.
+
+        Parameters
+        ----------
+        **params
+            Keyword parameters to merge into the stored initialization parameters.
+
+        Returns
+        -------
+        LightGBMRegressorAdapter
+            The updated adapter instance (self).
+
+        Notes
+        -----
+        This method updates `self.lgbm_params` and then re-instantiates
+        `lightgbm.LGBMRegressor` using the merged parameter set.
+
+        """
+        self.lgbm_params.update(params)
+        if HAS_LIGHTGBM:
+            self.model = LGBMRegressor(**self.lgbm_params)
+        return self
+
+    # ------------------------------------------------------------------
+    # Representation
+    # ------------------------------------------------------------------
+    def __repr__(self) -> str:
+        return f"LightGBMRegressorAdapter(params={self.lgbm_params})"

eb_adapters/prophet.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+"""
+Prophet adapter.
+
+This module provides `ProphetAdapter`, a thin wrapper around `prophet.Prophet`
+with a scikit-learn-like interface (`fit`, `predict`).
+
+Unlike tabular regressors, Prophet expects a pandas DataFrame with a timestamp
+column named `ds` and a target column named `y`. This adapter converts common
+array-like inputs into that canonical format for use within the
+ElectricBarometer ecosystem.
+"""
+
+from typing import Any, Optional
+
+import numpy as np
+
+from .base import BaseAdapter
+
+
+class ProphetAdapter(BaseAdapter):
+    """
+    Adapter for `prophet.Prophet`.
+
+    This adapter enables Prophet models to be used inside ElectricBarometer or
+    other CWSL-based evaluation workflows by exposing a scikit-learn-like API.
+
+    Parameters
+    ----------
+    model : Any | None
+        Optional pre-configured `prophet.Prophet` instance. If None, a default
+        Prophet model is constructed. If the `prophet` package is not installed,
+        constructing a default model will raise `ImportError`.
+
+    Notes
+    -----
+    Input conventions:
+
+    - `X` encodes the time index as either:
+      - shape (n_samples,) of datetime-like values, or
+      - shape (n_samples, n_features) where the first column is datetime-like
+    - `y` is a one-dimensional array-like of numeric targets.
+
+    At fit time, the adapter constructs a DataFrame with columns:
+
+    - `ds`: timestamps parsed from `X`
+    - `y`: targets from `y`
+
+    and calls `Prophet.fit(df)`.
+
+    At predict time, the adapter constructs a DataFrame with column `ds` and
+    returns the `yhat` predictions as a one-dimensional numpy array.
+
+    Examples
+    --------
+    >>> from prophet import Prophet
+    >>> base = Prophet()
+    >>> model = ProphetAdapter(model=base)
+    >>> # X contains datetimes, y contains numeric targets
+    >>> # model.fit(X, y).predict(X)
+
+    """
+
+    def __init__(self, model: Optional[Any] = None) -> None:
+        if model is None:
+            try:
+                from prophet import Prophet as _Prophet  # type: ignore
+            except Exception as e:  # pragma: no cover - import failure path
+                raise ImportError(
+                    "ProphetAdapter requires the optional 'prophet' package. "
+                    "Install it via `pip install prophet`."
+                ) from e
+
+            model = _Prophet()
+
+        self.model = model
+
+    # ------------------------------------------------------------------
+    # Fit
+    # ------------------------------------------------------------------
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,  # ignored
+    ) -> "ProphetAdapter":
+        """
+        Fit the underlying Prophet model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Time index values. Accepted forms are:
+            - shape (n_samples,) of datetime-like values, or
+            - shape (n_samples, n_features) where the first column is datetime-like
+        y : numpy.ndarray
+            Target vector of shape (n_samples,).
+        sample_weight : numpy.ndarray | None
+            Accepted for API compatibility but ignored by this adapter.
+
+        Returns
+        -------
+        ProphetAdapter
+            The fitted adapter (self), allowing method chaining.
+
+        Notes
+        -----
+        This method imports pandas locally to avoid making pandas a hard
+        dependency at module import time.
+        """
+        _ = sample_weight  # intentionally unused; kept for API compatibility
+
+        # Local import to avoid making pandas a hard dependency for the module
+        import pandas as pd
+
+        X_arr = np.asarray(X)
+
+        # Use the first column if 2D
+        if X_arr.ndim > 1:
+            X_arr = X_arr[:, 0]
+
+        ds = pd.to_datetime(X_arr)
+        y_arr = np.asarray(y, dtype=float)
+
+        df = pd.DataFrame({"ds": ds, "y": y_arr})
+        self.model.fit(df)
+        return self
+
+    # ------------------------------------------------------------------
+    # Predict
+    # ------------------------------------------------------------------
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Predict using the fitted Prophet model.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Time index values in the same format accepted by `fit`.
+
+        Returns
+        -------
+        numpy.ndarray
+            Predicted values of shape (n_samples,), taken from Prophet's `yhat`
+            output column.
+
+        Raises
+        ------
+        RuntimeError
+            If the Prophet forecast output does not contain the `yhat` column.
+
+        Notes
+        -----
+        This method imports pandas locally to avoid making pandas a hard
+        dependency at module import time.
+        """
+        import pandas as pd
+
+        X_arr = np.asarray(X)
+        if X_arr.ndim > 1:
+            X_arr = X_arr[:, 0]
+
+        ds = pd.to_datetime(X_arr)
+        df_future = pd.DataFrame({"ds": ds})
+        forecast = self.model.predict(df_future)
+
+        if "yhat" not in forecast.columns:
+            raise RuntimeError("ProphetAdapter: expected 'yhat' column in forecast output.")
+
+        return np.asarray(forecast["yhat"], dtype=float)

eb_adapters/statsmodels.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+"""
+Statsmodels adapters.
+
+This module provides thin wrappers around univariate statsmodels time-series models so
+they can be used inside the ElectricBarometer ecosystem via a scikit-learn-like API.
+
+Adapters in this module intentionally treat `X` as an index placeholder:
+
+- `fit(X, y)` fits the underlying time-series model to `y` only.
+- `predict(X)` forecasts `len(X)` steps ahead from the end of the training sample.
+
+This design supports evaluation workflows that expect the `predict(X)` signature while
+remaining faithful to how classic univariate ARIMA-family models operate.
+"""
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .base import BaseAdapter
+
+# Optional statsmodels support ------------------------------------------------
+try:  # pragma: no cover - import guard
+    import statsmodels.api as _sm  # type: ignore[import]
+
+    HAS_STATSMODELS = True
+except Exception:  # pragma: no cover - import guard
+    _sm = None
+    HAS_STATSMODELS = False
+
+
+class SarimaxAdapter(BaseAdapter):
+    """
+    Adapter for `statsmodels` SARIMAX.
+
+    This wrapper fits a univariate SARIMAX model on `y` and produces forecasts for
+    `len(X)` steps ahead when `predict(X)` is called.
+
+    Parameters
+    ----------
+    order : tuple[int, int, int], default (1, 0, 0)
+        ARIMA (p, d, q) order.
+    seasonal_order : tuple[int, int, int, int], default (0, 0, 0, 0)
+        Seasonal (P, D, Q, s) order.
+    trend : str | None, default None
+        Trend specification forwarded to SARIMAX.
+    enforce_stationarity : bool, default True
+        Whether to enforce stationarity in the SARIMAX model.
+    enforce_invertibility : bool, default True
+        Whether to enforce invertibility in the SARIMAX model.
+
+    Notes
+    -----
+    - `X` is ignored during fitting. It is only used at prediction time to
+      determine the forecast horizon (`n_steps = len(X)`).
+    - This adapter stores initialization parameters via `get_params()` so cloning
+      utilities can reconstruct the adapter.
+    """
+
+    def __init__(
+        self,
+        order: tuple[int, int, int] = (1, 0, 0),
+        seasonal_order: tuple[int, int, int, int] = (0, 0, 0, 0),
+        trend: Optional[str] = None,
+        enforce_stationarity: bool = True,
+        enforce_invertibility: bool = True,
+    ) -> None:
+        super().__init__()
+        self.order = order
+        self.seasonal_order = seasonal_order
+        self.trend = trend
+        self.enforce_stationarity = enforce_stationarity
+        self.enforce_invertibility = enforce_invertibility
+
+        self._result = None
+
+        # Failure is intentionally delayed until fit(); this flag supports
+        # feature detection and optional-dependency behavior.
+        if not HAS_STATSMODELS:
+            pass
+
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> "SarimaxAdapter":
+        """
+        Fit a univariate SARIMAX model on `y`.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Ignored. Present for API compatibility.
+        y : numpy.ndarray
+            Target series of shape (n_samples,).
+        sample_weight : numpy.ndarray | None
+            Accepted for API compatibility but ignored by this adapter.
+
+        Returns
+        -------
+        SarimaxAdapter
+            The fitted adapter (self), allowing method chaining.
+
+        Raises
+        ------
+        ImportError
+            If `statsmodels` is not installed.
+        """
+        _ = X  # intentionally unused; kept for API compatibility
+        _ = sample_weight  # intentionally unused; kept for API compatibility
+
+        if not HAS_STATSMODELS:
+            raise ImportError(
+                "SarimaxAdapter requires the optional 'statsmodels' package. "
+                "Install it via `pip install statsmodels`."
+            )
+
+        y_arr = np.asarray(y, dtype=float)
+
+        model = _sm.tsa.statespace.SARIMAX(
+            y_arr,
+            order=self.order,
+            seasonal_order=self.seasonal_order,
+            trend=self.trend,
+            enforce_stationarity=self.enforce_stationarity,
+            enforce_invertibility=self.enforce_invertibility,
+        )
+
+        # Keep fitting lightweight for typical adapter usage and tests.
+        self._result = model.fit(disp=False, maxiter=50)
+        return self
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Forecast `len(X)` steps ahead from the end of the training sample.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Array-like placeholder used to determine the forecast horizon.
+
+        Returns
+        -------
+        numpy.ndarray
+            Forecast values of shape (len(X),).
+
+        Raises
+        ------
+        RuntimeError
+            If the adapter has not been fit yet.
+        """
+        if self._result is None:
+            raise RuntimeError("SarimaxAdapter has not been fit yet. Call `fit(X, y)` first.")
+
+        n_steps = len(X)
+        if n_steps <= 0:
+            return np.array([], dtype=float)
+
+        forecast = self._result.forecast(steps=n_steps)
+        return np.asarray(forecast, dtype=float)
+
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        """
+        Return initialization parameters for cloning utilities.
+
+        Parameters
+        ----------
+        deep : bool
+            Included for scikit-learn compatibility.
+
+        Returns
+        -------
+        dict[str, Any]
+            Initialization parameters that can be passed back to `__init__`.
+        """
+        _ = deep  # intentionally unused; kept for API compatibility
+        return {
+            "order": self.order,
+            "seasonal_order": self.seasonal_order,
+            "trend": self.trend,
+            "enforce_stationarity": self.enforce_stationarity,
+            "enforce_invertibility": self.enforce_invertibility,
+        }
+
+    def set_params(self, **params: Any) -> "SarimaxAdapter":
+        """
+        Update adapter parameters.
+
+        Parameters
+        ----------
+        **params
+            Parameters to set as attributes on the adapter instance.
+
+        Returns
+        -------
+        SarimaxAdapter
+            The updated adapter instance (self).
+        """
+        for k, v in params.items():
+            setattr(self, k, v)
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f"SarimaxAdapter(order={self.order}, "
+            f"seasonal_order={self.seasonal_order}, trend={self.trend!r})"
+        )
+
+
+class ArimaAdapter(BaseAdapter):
+    """
+    Adapter for `statsmodels` ARIMA.
+
+    This wrapper fits a univariate ARIMA model on `y` and produces forecasts for
+    `len(X)` steps ahead when `predict(X)` is called.
+
+    Parameters
+    ----------
+    order : tuple[int, int, int], default (1, 0, 0)
+        ARIMA (p, d, q) order.
+    trend : str | None, default None
+        Trend specification forwarded to `statsmodels.tsa.ARIMA`.
+
+    Notes
+    -----
+    - `X` is ignored during fitting. It is only used at prediction time to
+      determine the forecast horizon (`n_steps = len(X)`).
+    - This adapter stores initialization parameters via `get_params()` so cloning
+      utilities can reconstruct the adapter.
+    """
+
+    def __init__(
+        self,
+        order: tuple[int, int, int] = (1, 0, 0),
+        trend: Optional[str] = None,
+    ) -> None:
+        super().__init__()
+        self.order = order
+        self.trend = trend
+        self._result = None
+
+        # Failure is intentionally delayed until fit(); this flag supports
+        # feature detection and optional-dependency behavior.
+        if not HAS_STATSMODELS:
+            pass
+
+    def fit(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        sample_weight: Optional[np.ndarray] = None,
+    ) -> "ArimaAdapter":
+        """
+        Fit a univariate ARIMA model on `y`.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Ignored. Present for API compatibility.
+        y : numpy.ndarray
+            Target series of shape (n_samples,).
+        sample_weight : numpy.ndarray | None
+            Accepted for API compatibility but ignored by this adapter.
+
+        Returns
+        -------
+        ArimaAdapter
+            The fitted adapter (self), allowing method chaining.
+
+        Raises
+        ------
+        ImportError
+            If `statsmodels` is not installed.
+        """
+        _ = X  # intentionally unused; kept for API compatibility
+        _ = sample_weight  # intentionally unused; kept for API compatibility
+
+        if not HAS_STATSMODELS:
+            raise ImportError(
+                "ArimaAdapter requires the optional 'statsmodels' package. "
+                "Install it via `pip install statsmodels`."
+            )
+
+        y_arr = np.asarray(y, dtype=float)
+
+        model = _sm.tsa.ARIMA(
+            y_arr,
+            order=self.order,
+            trend=self.trend,
+        )
+
+        self._result = model.fit()
+        return self
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """
+        Forecast `len(X)` steps ahead from the end of the training sample.
+
+        Parameters
+        ----------
+        X : numpy.ndarray
+            Array-like placeholder used to determine the forecast horizon.
+
+        Returns
+        -------
+        numpy.ndarray
+            Forecast values of shape (len(X),).
+
+        Raises
+        ------
+        RuntimeError
+            If the adapter has not been fit yet.
+        """
+        if self._result is None:
+            raise RuntimeError("ArimaAdapter has not been fit yet. Call `fit(X, y)` first.")
+
+        n_steps = len(X)
+        if n_steps <= 0:
+            return np.array([], dtype=float)
+
+        forecast = self._result.forecast(steps=n_steps)
+        return np.asarray(forecast, dtype=float)
+
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        """
+        Return initialization parameters for cloning utilities.
+
+        Parameters
+        ----------
+        deep : bool
+            Included for scikit-learn compatibility.
+
+        Returns
+        -------
+        dict[str, Any]
+            Initialization parameters that can be passed back to `__init__`.
+        """
+        _ = deep  # intentionally unused; kept for API compatibility
+        return {
+            "order": self.order,
+            "trend": self.trend,
+        }
+
+    def set_params(self, **params: Any) -> "ArimaAdapter":
+        """
+        Update adapter parameters.
+
+        Parameters
+        ----------
+        **params
+            Parameters to set as attributes on the adapter instance.
+
+        Returns
+        -------
+        ArimaAdapter
+            The updated adapter instance (self).
+        """
+        for k, v in params.items():
+            setattr(self, k, v)
+        return self
+
+    def __repr__(self) -> str:
+        return f"ArimaAdapter(order={self.order}, trend={self.trend!r})"

eb_adapters-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: eb-adapters
+Version: 0.1.0
+Summary: Adapter layer for third-party forecasting libraries in Electric Barometer
+License: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: prophet
+Requires-Dist: prophet>=1.1; extra == "prophet"
+Provides-Extra: statsmodels
+Requires-Dist: statsmodels>=0.14; extra == "statsmodels"
+Provides-Extra: catboost
+Requires-Dist: catboost>=1.2; extra == "catboost"
+Provides-Extra: lightgbm
+Requires-Dist: lightgbm>=4.0; extra == "lightgbm"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Electric Barometer Adapters (`eb-adapters`)
+
+![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
+![Python Versions](https://img.shields.io/badge/Python-3.10%2B-blue)
+[![Docs](https://img.shields.io/badge/docs-electric--barometer-blue)](https://economistician.github.io/eb-docs/)
+![Project Status](https://img.shields.io/badge/Status-Alpha-yellow)
+
+This repository contains the **model adapter layer** of the *Electric Barometer*
+ecosystem.
+
+`eb-adapters` provides standardized interfaces that adapt common forecasting and
+machine-learning libraries to the Electric Barometer evaluation and readiness
+frameworks, enabling consistent metric computation and model comparison across
+heterogeneous modeling approaches.
+
+Conceptual definitions and evaluation philosophy are maintained in the companion
+research repository:
+**`eb-papers`**.
+
+---
+
+## Naming convention
+
+Electric Barometer packages follow standard Python packaging conventions:
+
+- **Distribution names** (used with `pip install`) use hyphens  
+  e.g. `pip install eb-adapters`
+- **Python import paths** use underscores  
+  e.g. `import eb_adapters`
+
+This distinction is intentional and consistent across the Electric Barometer
+ecosystem.
+
+---
+
+## Role Within Electric Barometer
+
+Within the Electric Barometer ecosystem:
+
+- **`eb-papers`** defines *concepts, frameworks, and meaning*
+- **`eb-metrics`** implements *individual metrics*
+- **`eb-evaluation`** orchestrates *evaluation workflows*
+- **`eb-adapters`** standardizes *model interfaces*
+
+This repository focuses on bridging external modeling libraries into a common,
+evaluation-ready form.
+
+---
+
+## What This Library Provides
+
+- **A common adapter base class** defining a unified interface for forecast models
+- **Library-specific adapters** for popular forecasting and ML frameworks
+- **Consistent prediction and evaluation hooks** compatible with EB metrics
+- **Extensible patterns** for adding new model families without changing
+  downstream evaluation logic
+
+Current adapters include support for:
+- CatBoost
+- LightGBM
+- Prophet
+- Statsmodels-based models
+
+---
+
+## Scope
+
+This repository focuses on **model adaptation**, not model training algorithms or
+metric definitions.
+
+**In scope:**
+- Wrapping external model APIs behind a consistent adapter interface
+- Standardizing prediction outputs for evaluation
+- Providing compatibility with EB evaluation pipelines
+
+**Out of scope:**
+- Metric definitions and loss formulations (see `eb-metrics`)
+- Evaluation orchestration logic (see `eb-evaluation`)
+- Model training methodology or hyperparameter optimization
+- Conceptual framework definitions (see `eb-papers`)
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install eb-adapters
+```
+
+For development or local use:
+
+```bash
+pip install -e .
+```
+
+---
+
+## Package Structure
+
+The repository follows a clean, modern Python package layout:
+
+```text
+eb-adapters/
+├── src/eb_adapters/
+│   ├── base.py            # Abstract adapter base class
+│   ├── catboost.py        # CatBoost model adapter
+│   ├── lightgbm.py        # LightGBM model adapter
+│   ├── prophet.py         # Prophet model adapter
+│   └── statsmodels.py     # Statsmodels-based adapters
+│
+├── tests/
+│   └── adapters/          # Unit tests for adapter implementations
+│
+├── pyproject.toml         # Build and dependency configuration
+├── README.md              # Project documentation
+└── LICENSE                # BSD-3-Clause license
+```
+
+---
+
+## Relationship to Other EB Repositories
+
+- **`eb-papers`**  
+  Source of truth for conceptual definitions and evaluation philosophy.
+
+- **`eb-metrics`**  
+  Provides the metric implementations used during evaluation.
+
+- **`eb-evaluation`**  
+  Orchestrates evaluation workflows using adapted models.
+
+- **`eb-adapters`**  
+  Ensures heterogeneous models can be evaluated consistently.
+
+When discrepancies arise, conceptual intent in `eb-papers` should be treated as
+authoritative.
+
+---
+
+## Development and Testing
+
+Tests are located under the `tests/` directory and mirror adapter coverage.
+
+To run the test suite:
+
+```bash
+pytest
+```
+
+---
+
+## Status
+
+This package is under active development.
+Public APIs may evolve prior to the first stable release.

eb_adapters-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+eb_adapters/__init__.py,sha256=aFGCWDxo03BMHND98rf-ZGV1h2LPAgVn9OS2T9hP7PM,1036
+eb_adapters/base.py,sha256=-ZZ8-rPMZhhTNJ-aqA4TnmKciRxGCUaLsjupcXNJHZM,5020
+eb_adapters/catboost.py,sha256=R7U7cUFD4jJuZRHGAitmZ9scPCbg1k6edCjTZPLDFk4,7149
+eb_adapters/lightgbm.py,sha256=kHH7ea49PiarEmkE5kKjCcZtrQAKB0PX5lk4p5ITHhU,6997
+eb_adapters/prophet.py,sha256=6FBoBG-zFhg9XDxGTiy5OjcJpvLeD4K5iddZ6sG_JD0,5459
+eb_adapters/statsmodels.py,sha256=IhaZbY04bX7gyerM_fQEjR4HTAn-697vhDHpBT8ss88,11365
+eb_adapters-0.1.0.dist-info/licenses/LICENSE,sha256=qFjBKWIfPVLU4ZK4DgROjINVdZVLuNznTfyVaEgCa9w,1526
+eb_adapters-0.1.0.dist-info/METADATA,sha256=MhIHfGjhT-Piv7SE5mG2mGPUbqCRmW1ouKOH3FKHZ1E,5275
+eb_adapters-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eb_adapters-0.1.0.dist-info/top_level.txt,sha256=uVNItEBTrYVjvjMvKEpz91-Pzhc5oNT8vZB8wPOMP9w,12
+eb_adapters-0.1.0.dist-info/RECORD,,

eb_adapters-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

eb_adapters-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Kyle Corrie
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

eb_adapters-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+eb_adapters