eb-optimization 0.1.0__tar.gz

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

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: eb-optimization
+Version: 0.1.0
+Summary: Electric Barometer: Optimization and tuning utilities for EB objectives and policy parameters.
+Author-email: "Kyle Corrie (Economistician)" <kcorrie@economistician.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Economistician/eb-optimization
+Project-URL: Repository, https://github.com/Economistician/eb-optimization
+Project-URL: Issues, https://github.com/Economistician/eb-optimization/issues
+Project-URL: Documentation, https://github.com/Economistician/eb-docs
+Keywords: electric-barometer,optimization,tuning,grid-search,calibration,asymmetric-loss,forecasting,pandas
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: eb
+Requires-Dist: eb-metrics<0.3,>=0.2; extra == "eb"
+Requires-Dist: eb-evaluation<0.3,>=0.2; extra == "eb"
+Provides-Extra: opt
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: scikit-learn>=1.3; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Electric Barometer · Optimization (`eb-optimization`)
+
+Decision and policy layer for the Electric Barometer ecosystem, responsible for tuning, calibration, and governed parameter selection.
+
+---
+
+## Overview
+
+This repository contains the optimization, tuning, and policy governance layer of the Electric Barometer ecosystem. It defines how key evaluation parameters—such as cost ratios, tolerances, and readiness controls—are selected from data, validated under governance rules, and formalized into deterministic policies that can be reused across systems and environments.
+
+Rather than computing metrics or running evaluations, this repository focuses on decision logic: how parameters are calibrated, how tradeoffs are resolved, and how those decisions are frozen into auditable artifacts. It provides the bridge between metric theory and operational deployment, ensuring that forecast evaluation behavior is consistent, explainable, and governed by explicit intent rather than ad-hoc configuration.
+
+---
+
+## Role in the Electric Barometer Ecosystem
+
+`eb-optimization` defines the parameter selection, calibration, and governance logic used throughout the Electric Barometer ecosystem. It is responsible for determining how key operational parameters—such as cost ratios, tolerance bands, and readiness controls—are selected from data in a disciplined, reproducible, and decision-aware manner.
+
+This repository focuses exclusively on optimization mechanics and policy formation. It does not define metric primitives, perform evaluation orchestration, manage model interfaces, or execute runtime decision logic. Those responsibilities are handled by adjacent layers in the ecosystem that compute metrics, evaluate forecasts, or apply frozen policies in production workflows.
+
+By separating parameter selection and governance from metric semantics and execution concerns, eb-optimization provides a stable optimization layer that enables consistent calibration, transparent decision rules, and auditable policy artifacts across heterogeneous forecasting and operational contexts.
+
+---
+
+## Installation
+
+`eb-optimization` is distributed as a standard Python package.
+
+```bash
+pip install eb-optimization
+```
+
+---
+
+## Core Concepts
+
+- **Parameter governance** — Operational parameters (e.g., cost ratios, tolerances) should be selected through explicit, reproducible rules rather than ad-hoc tuning or implicit defaults.
+- **Search over candidate spaces** — Optimization is framed as deterministic search over bounded, interpretable candidate sets, enabling transparent tradeoffs and stable outcomes.
+- **Cost balance calibration** — Asymmetric operational costs can be balanced by selecting parameters that equalize or appropriately trade off opposing risk exposures.
+- **Tolerance selection from residuals** — Acceptable error bands can be learned directly from historical performance, reflecting empirical system behavior rather than arbitrary thresholds.
+- **Policy separation** — Calibration logic is separated from frozen policy artifacts so that parameter selection is auditable, versioned, and safely applied in downstream systems.
+- **Decision-aligned optimization** — Optimization is evaluated by operational interpretability and governance fitness, not by abstract numerical optimality alone.
+
+---
+
+## Minimal Example
+
+The example below illustrates a typical optimization workflow using `eb-optimization`: calibrating an operational parameter from historical data and applying it via a frozen policy.
+
+```python
+import numpy as np
+from eb_optimization.policies import (
+    CostRatioPolicy,
+    apply_cost_ratio_policy,
+)
+
+# Historical actuals and forecasts
+y_true = np.array([10, 12, 15, 20])
+y_pred = np.array([9, 14, 18, 17])
+
+# Define a frozen cost-ratio policy
+policy = CostRatioPolicy(
+    R_grid=(0.5, 1.0, 2.0, 3.0),
+    co=1.0,
+)
+
+# Estimate a global cost ratio R
+R, diagnostics = apply_cost_ratio_policy(
+    y_true=y_true,
+    y_pred=y_pred,
+    policy=policy,
+)
+
+print(R)
+```
+
+---
+
+## License
+
+BSD 3-Clause License.  
+© 2025 Kyle Corrie.

eb_optimization-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Electric Barometer · Optimization (`eb-optimization`)
+
+Decision and policy layer for the Electric Barometer ecosystem, responsible for tuning, calibration, and governed parameter selection.
+
+---
+
+## Overview
+
+This repository contains the optimization, tuning, and policy governance layer of the Electric Barometer ecosystem. It defines how key evaluation parameters—such as cost ratios, tolerances, and readiness controls—are selected from data, validated under governance rules, and formalized into deterministic policies that can be reused across systems and environments.
+
+Rather than computing metrics or running evaluations, this repository focuses on decision logic: how parameters are calibrated, how tradeoffs are resolved, and how those decisions are frozen into auditable artifacts. It provides the bridge between metric theory and operational deployment, ensuring that forecast evaluation behavior is consistent, explainable, and governed by explicit intent rather than ad-hoc configuration.
+
+---
+
+## Role in the Electric Barometer Ecosystem
+
+`eb-optimization` defines the parameter selection, calibration, and governance logic used throughout the Electric Barometer ecosystem. It is responsible for determining how key operational parameters—such as cost ratios, tolerance bands, and readiness controls—are selected from data in a disciplined, reproducible, and decision-aware manner.
+
+This repository focuses exclusively on optimization mechanics and policy formation. It does not define metric primitives, perform evaluation orchestration, manage model interfaces, or execute runtime decision logic. Those responsibilities are handled by adjacent layers in the ecosystem that compute metrics, evaluate forecasts, or apply frozen policies in production workflows.
+
+By separating parameter selection and governance from metric semantics and execution concerns, eb-optimization provides a stable optimization layer that enables consistent calibration, transparent decision rules, and auditable policy artifacts across heterogeneous forecasting and operational contexts.
+
+---
+
+## Installation
+
+`eb-optimization` is distributed as a standard Python package.
+
+```bash
+pip install eb-optimization
+```
+
+---
+
+## Core Concepts
+
+- **Parameter governance** — Operational parameters (e.g., cost ratios, tolerances) should be selected through explicit, reproducible rules rather than ad-hoc tuning or implicit defaults.
+- **Search over candidate spaces** — Optimization is framed as deterministic search over bounded, interpretable candidate sets, enabling transparent tradeoffs and stable outcomes.
+- **Cost balance calibration** — Asymmetric operational costs can be balanced by selecting parameters that equalize or appropriately trade off opposing risk exposures.
+- **Tolerance selection from residuals** — Acceptable error bands can be learned directly from historical performance, reflecting empirical system behavior rather than arbitrary thresholds.
+- **Policy separation** — Calibration logic is separated from frozen policy artifacts so that parameter selection is auditable, versioned, and safely applied in downstream systems.
+- **Decision-aligned optimization** — Optimization is evaluated by operational interpretability and governance fitness, not by abstract numerical optimality alone.
+
+---
+
+## Minimal Example
+
+The example below illustrates a typical optimization workflow using `eb-optimization`: calibrating an operational parameter from historical data and applying it via a frozen policy.
+
+```python
+import numpy as np
+from eb_optimization.policies import (
+    CostRatioPolicy,
+    apply_cost_ratio_policy,
+)
+
+# Historical actuals and forecasts
+y_true = np.array([10, 12, 15, 20])
+y_pred = np.array([9, 14, 18, 17])
+
+# Define a frozen cost-ratio policy
+policy = CostRatioPolicy(
+    R_grid=(0.5, 1.0, 2.0, 3.0),
+    co=1.0,
+)
+
+# Estimate a global cost ratio R
+R, diagnostics = apply_cost_ratio_policy(
+    y_true=y_true,
+    y_pred=y_pred,
+    policy=policy,
+)
+
+print(R)
+```
+
+---
+
+## License
+
+BSD 3-Clause License.  
+© 2025 Kyle Corrie.

eb_optimization-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+######################################
+# Project metadata
+######################################
+[project]
+name = "eb-optimization"
+version = "0.1.0"
+description = "Electric Barometer: Optimization and tuning utilities for EB objectives and policy parameters."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+license-files = ["LICENSE*"]
+
+authors = [
+  { name = "Kyle Corrie (Economistician)", email = "kcorrie@economistician.com" }
+]
+
+keywords = [
+  "electric-barometer",
+  "optimization",
+  "tuning",
+  "grid-search",
+  "calibration",
+  "asymmetric-loss",
+  "forecasting",
+  "pandas",
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+]
+
+######################################
+# Core runtime dependencies
+######################################
+# Keep this intentionally lean. eb-optimization should be installable even
+# without pulling the rest of the EB stack unless users opt-in via extras.
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+]
+
+######################################
+# Project URLs
+######################################
+[project.urls]
+Homepage = "https://github.com/Economistician/eb-optimization"
+Repository = "https://github.com/Economistician/eb-optimization"
+Issues = "https://github.com/Economistician/eb-optimization/issues"
+Documentation = "https://github.com/Economistician/eb-docs"
+
+######################################
+# Optional dependencies (extras)
+######################################
+[project.optional-dependencies]
+
+# Pull in EB ecosystem deps when tuning objectives/policies that rely on them
+eb = [
+  # Electric Barometer compatibility band (0.2.x)
+  "eb-metrics>=0.2,<0.3",
+  "eb-evaluation>=0.2,<0.3",
+]
+
+# Optional optimization backends (future-proofing)
+# Keep empty for now; add later when you actually introduce them.
+opt = [
+]
+
+# CI / test-only dependencies
+test = [
+  "pytest>=8.0",
+  "scikit-learn>=1.3",
+]
+
+# Local developer tooling
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+]
+
+######################################
+# Build system
+######################################
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+######################################
+# Package discovery
+######################################
+[tool.setuptools.packages.find]
+where = ["src"]
+
+######################################
+# Pytest configuration
+######################################
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"

eb_optimization-0.1.0/setup.cfg

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

eb_optimization-0.1.0/src/eb_optimization/__init__.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+"""
+`eb_optimization` — optimization and tuning layer for the Electric Barometer ecosystem.
+
+This package contains the **optimization layer** of Electric Barometer:
+
+- **search**: generic, reusable search mechanics (grids, tie-breaking kernels)
+- **tuning**: calibration and selection utilities (e.g., cost-ratio tuning, sensitivity sweeps)
+- **policies**: frozen, declarative policy artifacts for downstream execution
+
+It intentionally does **not** define metric primitives or evaluation math.
+Those live in `eb-metrics` (and orchestration lives in `eb-evaluation`).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _resolve_version() -> str:
+    """
+    Resolve the installed distribution version.
+
+    Returns
+    -------
+    str
+        Installed version string. If the distribution is not installed (e.g., running
+        from source), returns ``"0.0.0"``.
+    """
+    try:
+        # Must match the distribution name in pyproject.toml ([project].name)
+        return version("eb-optimization")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

eb_optimization-0.1.0/src/eb_optimization/_utils.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+__all__ = [
+    "to_1d_array",
+    "broadcast_param",
+    "handle_sample_weight",
+]
+
+
+def to_1d_array(x: ArrayLike, name: str) -> np.ndarray:
+    """
+    Convert input to a 1D numpy float array.
+
+    Parameters
+    ----------
+    x
+        Array-like input.
+    name
+        Name used in error messages.
+
+    Returns
+    -------
+    numpy.ndarray
+        1D float array.
+
+    Raises
+    ------
+    ValueError
+        If the input is not 1-dimensional.
+    """
+    arr = np.asarray(x, dtype=float)
+
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be a 1D array; got shape {arr.shape}")
+
+    return arr
+
+
+def broadcast_param(x: ArrayLike, shape: tuple[int, ...], name: str) -> np.ndarray:
+    """
+    Broadcast a scalar or 1D array parameter to a target shape.
+
+    Rules
+    -----
+    - Scalars are expanded to the given shape
+    - 1D arrays must exactly match the target shape
+
+    Parameters
+    ----------
+    x
+        Scalar or 1D array parameter.
+    shape
+        Target shape.
+    name
+        Name used in error messages.
+
+    Returns
+    -------
+    numpy.ndarray
+        Float array of shape ``shape``.
+
+    Raises
+    ------
+    ValueError
+        If ``x`` is neither scalar nor matches the target shape.
+    """
+    arr = np.asarray(x, dtype=float)
+
+    if arr.ndim == 0:
+        return np.full(shape, float(arr), dtype=float)
+
+    if arr.shape != shape:
+        raise ValueError(
+            f"{name} must be scalar or have shape {shape}; got shape {arr.shape}"
+        )
+
+    return arr
+
+
+def handle_sample_weight(sample_weight: ArrayLike | None, n: int) -> np.ndarray:
+    """
+    Normalize sample weights to a non-negative 1D float array of length n.
+
+    If ``sample_weight`` is None, returns an array of ones.
+
+    Parameters
+    ----------
+    sample_weight
+        None or a 1D array of non-negative weights.
+    n
+        Expected length.
+
+    Returns
+    -------
+    numpy.ndarray
+        1D float array of length n.
+
+    Raises
+    ------
+    ValueError
+        If weights are not length-n, not 1D, or contain negative values.
+    """
+    if n <= 0:
+        raise ValueError(f"n must be a positive integer; got {n}")
+
+    if sample_weight is None:
+        return np.ones(n, dtype=float)
+
+    w = np.asarray(sample_weight, dtype=float)
+
+    if w.ndim != 1 or w.shape[0] != n:
+        raise ValueError(
+            f"sample_weight must be a 1D array of length {n}; got shape {w.shape}"
+        )
+
+    if np.any(w < 0):
+        raise ValueError("sample_weight must be non-negative.")
+
+    return w

eb_optimization-0.1.0/src/eb_optimization/policies/__init__.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+"""
+Frozen policy artifacts for the Electric Barometer optimization layer.
+
+The `eb_optimization.policies` package contains **governance-level, immutable
+configuration objects** that define how tuned parameters are selected and applied
+at runtime.
+
+Design principles
+-----------------
+- Policies are **frozen** (dataclass(frozen=True)) and versionable
+- Policies contain **no learning or tuning logic**
+- Policies wrap tuning utilities with deterministic application semantics
+- Policies are safe to ship to production systems
+
+Layering
+--------
+- tuning/    : derives parameters from data (calibration, grid search)
+- policies/  : freezes configuration + applies tuning deterministically
+- runtime    : consumes policy outputs only (no re-tuning)
+
+Exported policies
+-----------------
+- Tau (τ) tolerance governance for HR@τ
+- Cost-ratio (R = c_u / c_o) governance for asymmetric loss
+- RAL policy governance (readiness adjustment layer)
+"""
+
+# ---------------------------------------------------------------------
+# Tau (tolerance) policies
+# ---------------------------------------------------------------------
+from .tau_policy import (
+    TauPolicy,
+    apply_tau_policy,
+    apply_tau_policy_hr,
+    apply_entity_tau_policy,
+)
+
+# ---------------------------------------------------------------------
+# Cost-ratio (R) policies
+# ---------------------------------------------------------------------
+from .cost_ratio_policy import (
+    CostRatioPolicy,
+    DEFAULT_COST_RATIO_POLICY,
+    apply_cost_ratio_policy,
+    apply_entity_cost_ratio_policy,
+)
+
+# ---------------------------------------------------------------------
+# RAL policies
+# ---------------------------------------------------------------------
+from .ral_policy import (
+    RALPolicy,
+    DEFAULT_RAL_POLICY,
+    apply_ral_policy,
+)
+
+__all__ = [
+    # Tau policies
+    "TauPolicy",
+    "apply_tau_policy",
+    "apply_tau_policy_hr",
+    "apply_entity_tau_policy",
+    # Cost ratio policies
+    "CostRatioPolicy",
+    "DEFAULT_COST_RATIO_POLICY",
+    "apply_cost_ratio_policy",
+    "apply_entity_cost_ratio_policy",
+    # RAL policies
+    "RALPolicy",
+    "DEFAULT_RAL_POLICY",
+    "apply_ral_policy",
+]