eb-adapters 0.1.0__tar.gz

eb_adapters-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,157 @@
+# 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/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "eb-adapters"
+version = "0.1.0"
+description = "Adapter layer for third-party forecasting libraries in Electric Barometer"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+dependencies = [
+    "numpy",
+    "pandas",        # only really needed for Prophet adapter
+]
+
+[project.optional-dependencies]
+prophet = ["prophet>=1.1"]
+statsmodels = ["statsmodels>=0.14"]
+catboost = ["catboost>=1.2"]
+lightgbm = ["lightgbm>=4.0"]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "mypy",
+    "ruff",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

eb_adapters-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eb_adapters-0.1.0/src/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-0.1.0/src/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)."
+        )