eb-optimization 0.1.1__tar.gz → 0.2.1__tar.gz

{eb_optimization-0.1.1/src/eb_optimization.egg-info → eb_optimization-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eb-optimization
-Version: 0.1.1
+Version: 0.2.1
 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
@@ -28,13 +28,20 @@ Provides-Extra: opt
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: scikit-learn>=1.3; extra == "test"
+Requires-Dist: eb-optimization[eb]; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: eb-optimization[eb]; extra == "dev"
 Dynamic: license-file
 
 # Electric Barometer · Optimization (`eb-optimization`)
 
+[![CI](https://github.com/Economistician/eb-optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/Economistician/eb-optimization/actions/workflows/ci.yml)
+![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
+![Python Versions](https://img.shields.io/pypi/pyversions/eb-optimization)
+![PyPI](https://img.shields.io/pypi/v/eb-optimization)
+
 Decision and policy layer for the Electric Barometer ecosystem, responsible for tuning, calibration, and governed parameter selection.
 
 ---

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/README.md

@@ -1,5 +1,10 @@
 # Electric Barometer · Optimization (`eb-optimization`)
 
+[![CI](https://github.com/Economistician/eb-optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/Economistician/eb-optimization/actions/workflows/ci.yml)
+![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)
+![Python Versions](https://img.shields.io/pypi/pyversions/eb-optimization)
+![PyPI](https://img.shields.io/pypi/v/eb-optimization)
+
 Decision and policy layer for the Electric Barometer ecosystem, responsible for tuning, calibration, and governed parameter selection.
 
 ---

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/pyproject.toml

@@ -3,7 +3,7 @@
 ######################################
 [project]
 name = "eb-optimization"
-version = "0.1.1"
+version = "0.2.1"
 description = "Electric Barometer: Optimization and tuning utilities for EB objectives and policy parameters."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -75,12 +75,14 @@ opt = [
 test = [
   "pytest>=8.0",
   "scikit-learn>=1.3",
+  "eb-optimization[eb]",
 ]
 
 # Local developer tooling
 dev = [
   "pytest>=8.0",
   "pytest-cov>=5.0",
+  "eb-optimization[eb]",
 ]
 
 ######################################

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/__init__.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
+
 """
 `eb_optimization` — optimization and tuning layer for the Electric Barometer ecosystem.
 
@@ -13,8 +15,6 @@ 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:
     """
@@ -35,4 +35,4 @@ def _resolve_version() -> str:
 
 __version__ = _resolve_version()
 
-__all__ = ["__version__"]
+__all__ = ["__version__"]

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/_utils.py

@@ -4,9 +4,9 @@ import numpy as np
 from numpy.typing import ArrayLike
 
 __all__ = [
-    "to_1d_array",
     "broadcast_param",
     "handle_sample_weight",
+    "to_1d_array",
 ]
 
 
@@ -119,4 +119,4 @@ def handle_sample_weight(sample_weight: ArrayLike | None, n: int) -> np.ndarray:
     if np.any(w < 0):
         raise ValueError("sample_weight must be non-negative.")
 
-    return w
+    return w

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/policies/__init__.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Frozen policy artifacts for the Electric Barometer optimization layer.
 
@@ -27,48 +25,32 @@ Exported policies
 - 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,
-)
+from __future__ import annotations
 
-# ---------------------------------------------------------------------
-# Cost-ratio (R) policies
-# ---------------------------------------------------------------------
 from .cost_ratio_policy import (
-    CostRatioPolicy,
     DEFAULT_COST_RATIO_POLICY,
+    CostRatioPolicy,
     apply_cost_ratio_policy,
     apply_entity_cost_ratio_policy,
 )
-
-# ---------------------------------------------------------------------
-# RAL policies
-# ---------------------------------------------------------------------
-from .ral_policy import (
-    RALPolicy,
-    DEFAULT_RAL_POLICY,
-    apply_ral_policy,
+from .ral_policy import DEFAULT_RAL_POLICY, RALPolicy, apply_ral_policy
+from .tau_policy import (
+    TauPolicy,
+    apply_entity_tau_policy,
+    apply_tau_policy,
+    apply_tau_policy_hr,
 )
 
 __all__ = [
-    # Tau policies
-    "TauPolicy",
-    "apply_tau_policy",
-    "apply_tau_policy_hr",
-    "apply_entity_tau_policy",
-    # Cost ratio policies
-    "CostRatioPolicy",
     "DEFAULT_COST_RATIO_POLICY",
+    "DEFAULT_RAL_POLICY",
+    "CostRatioPolicy",
+    "RALPolicy",
+    "TauPolicy",
     "apply_cost_ratio_policy",
     "apply_entity_cost_ratio_policy",
-    # RAL policies
-    "RALPolicy",
-    "DEFAULT_RAL_POLICY",
+    "apply_entity_tau_policy",
     "apply_ral_policy",
-]
+    "apply_tau_policy",
+    "apply_tau_policy_hr",
+]

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/policies/cost_ratio_policy.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Cost-ratio (R = c_u / c_o) policy artifacts for eb-optimization.
 
@@ -38,16 +36,19 @@ Notes
   estimation, `co` is currently modeled as a scalar (consistent with tuning).
 """
 
+from __future__ import annotations
+
+from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union
+from typing import Any
 
 import numpy as np
-import pandas as pd
 from numpy.typing import ArrayLike
+import pandas as pd
 
 from eb_optimization.tuning.cost_ratio import (
-    estimate_R_cost_balance,
     estimate_entity_R_from_balance,
+    estimate_R_cost_balance,
 )
 
 
@@ -78,7 +79,9 @@ class CostRatioPolicy:
         if grid.ndim != 1 or grid.size == 0:
             raise ValueError("R_grid must be a non-empty 1D sequence of floats.")
         if not np.any(grid > 0):
-            raise ValueError("R_grid must contain at least one strictly positive value.")
+            raise ValueError(
+                "R_grid must contain at least one strictly positive value."
+            )
 
         if not np.isfinite(self.co) or float(self.co) <= 0:
             raise ValueError(f"co must be finite and strictly positive. Got {self.co}.")
@@ -95,9 +98,9 @@ def apply_cost_ratio_policy(
     y_pred: ArrayLike,
     *,
     policy: CostRatioPolicy = DEFAULT_COST_RATIO_POLICY,
-    co: Union[float, ArrayLike, None] = None,
+    co: float | ArrayLike | None = None,
     sample_weight: ArrayLike | None = None,
-) -> Tuple[float, Dict[str, Any]]:
+) -> tuple[float, dict[str, Any]]:
     """
     Apply a frozen cost-ratio policy to estimate a global R.
 
@@ -136,7 +139,7 @@ def apply_cost_ratio_policy(
         )
     )
 
-    diag: Dict[str, Any] = {
+    diag: dict[str, Any] = {
         "method": "cost_balance",
         "R_grid": list(map(float, policy.R_grid)),
         "co_is_array": isinstance(co_val, (list, tuple, np.ndarray, pd.Series)),
@@ -153,8 +156,8 @@ def apply_entity_cost_ratio_policy(
     y_true_col: str,
     y_pred_col: str,
     policy: CostRatioPolicy = DEFAULT_COST_RATIO_POLICY,
-    co: Optional[float] = None,
-    sample_weight_col: Optional[str] = None,
+    co: float | None = None,
+    sample_weight_col: str | None = None,
     include_diagnostics: bool = True,
 ) -> pd.DataFrame:
     """
@@ -238,7 +241,17 @@ def apply_entity_cost_ratio_policy(
         tuned["n"] = tuned[entity_col].map(counts).astype(int)
     else:
         tuned = pd.DataFrame(
-            columns=[entity_col, "R", "cu", "co", "under_cost", "over_cost", "diff", "reason", "n"]
+            columns=[
+                entity_col,
+                "R",
+                "cu",
+                "co",
+                "under_cost",
+                "over_cost",
+                "diff",
+                "reason",
+                "n",
+            ],
         )
 
     # ---- build rows for ineligible entities (one row per entity) ----
@@ -260,7 +273,17 @@ def apply_entity_cost_ratio_policy(
         ineligible_rows["n"] = ineligible_rows[entity_col].map(counts).astype(int)
     else:
         ineligible_rows = pd.DataFrame(
-            columns=[entity_col, "R", "cu", "co", "under_cost", "over_cost", "diff", "reason", "n"]
+            columns=[
+                entity_col,
+                "R",
+                "cu",
+                "co",
+                "under_cost",
+                "over_cost",
+                "diff",
+                "reason",
+                "n",
+            ],
         )
 
     # ---- combine (avoid pandas FutureWarning on concat with empty/all-NA frames) ----
@@ -276,7 +299,11 @@ def apply_entity_cost_ratio_policy(
     diag_cols = ["under_cost", "over_cost", "diff"]
     remaining = [c for c in out.columns if c not in base_cols + diag_cols]
 
-    cols = (base_cols + diag_cols + remaining) if include_diagnostics else (base_cols + remaining)
+    cols = (
+        (base_cols + diag_cols + remaining)
+        if include_diagnostics
+        else (base_cols + remaining)
+    )
 
     # Ensure all expected columns exist (even if empty)
     for c in cols:
@@ -287,8 +314,8 @@ def apply_entity_cost_ratio_policy(
 
 
 __all__ = [
-    "CostRatioPolicy",
     "DEFAULT_COST_RATIO_POLICY",
+    "CostRatioPolicy",
     "apply_cost_ratio_policy",
     "apply_entity_cost_ratio_policy",
-]
+]

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/policies/ral_policy.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Policy artifacts for the Readiness Adjustment Layer (RAL).
 
@@ -21,10 +19,13 @@ Policies are artifacts, not algorithms. They encode *decisions* derived from
 optimization, not the optimization process itself.
 """
 
-from dataclasses import dataclass
-from typing import Optional, Sequence
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
 import pandas as pd
 
+
 @dataclass(frozen=True)
 class RALPolicy:
     r"""Portable policy artifact for the Readiness Adjustment Layer (RAL).
@@ -67,13 +68,17 @@ class RALPolicy:
     artifacts needed to execute the adjustment.
     """
 
-    global_uplift: float
-    segment_cols: Sequence[str] = ()
-    uplift_table: Optional[pd.DataFrame] = None
+    global_uplift: float = 1.0
+    segment_cols: list[str] = field(default_factory=list)
+    uplift_table: pd.DataFrame | None = None
 
     def is_segmented(self) -> bool:
         """Return True if the policy contains segment-level uplifts."""
-        return bool(self.segment_cols) and self.uplift_table is not None and not self.uplift_table.empty
+        return (
+            bool(self.segment_cols)
+            and self.uplift_table is not None
+            and not self.uplift_table.empty
+        )
 
     def adjust_forecast(self, df: pd.DataFrame, forecast_col: str) -> pd.Series:
         """Apply the RAL policy to adjust the forecast values.
@@ -93,16 +98,19 @@ class RALPolicy:
         pd.Series
             A series with the adjusted forecast values.
         """
-        # Start with the global uplift applied to the forecast column
-        adjusted_forecast = df[forecast_col] * self.global_uplift
+        adjusted_forecast = df[forecast_col] * float(self.global_uplift)
 
-        # Apply segment-level uplifts if available
         if self.is_segmented():
             # Merge uplift_table with the DataFrame based on segment columns
-            uplift_df = df.merge(self.uplift_table, on=self.segment_cols, how="left")
-            # Apply the segment-level uplift (if available) to the forecast
-            uplifted_forecast = adjusted_forecast * uplift_df["uplift"].fillna(1.0)  # Default to 1.0 if no uplift
-            return uplifted_forecast
+            uplift_df = df.merge(
+                self.uplift_table, on=list(self.segment_cols), how="left"
+            )
+
+            # Apply the segment-level uplift (if available) to the forecast.
+            # NOTE: `uplift` here is interpreted as a multiplicative factor relative to the
+            # global uplift. Missing segments default to 1.0 (no additional uplift).
+            return adjusted_forecast * uplift_df["uplift"].fillna(1.0)
+
         return adjusted_forecast
 
     def transform(self, df: pd.DataFrame, forecast_col: str) -> pd.DataFrame:
@@ -124,6 +132,36 @@ class RALPolicy:
             The transformed DataFrame with the adjusted forecast values added.
         """
         df_copy = df.copy()
-        adjusted_forecast = self.adjust_forecast(df_copy, forecast_col)
-        df_copy["readiness_forecast"] = adjusted_forecast
-        return df_copy
+        df_copy["readiness_forecast"] = self.adjust_forecast(df_copy, forecast_col)
+        return df_copy
+
+
+# Convenience default policy instance (for the policies package API)
+DEFAULT_RAL_POLICY = RALPolicy()
+
+
+def apply_ral_policy(
+    df: pd.DataFrame,
+    forecast_col: str,
+    policy: RALPolicy = DEFAULT_RAL_POLICY,
+) -> pd.DataFrame:
+    """Convenience functional wrapper to apply a RALPolicy.
+
+    This is a thin wrapper around :meth:`RALPolicy.transform` used by callers/tests
+    that prefer a functional interface.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Input DataFrame containing the forecast column.
+    forecast_col : str
+        Name of the forecast column to adjust.
+    policy : RALPolicy
+        Policy artifact to apply. Defaults to :data:`DEFAULT_RAL_POLICY`.
+
+    Returns
+    -------
+    pd.DataFrame
+        Copy of `df` with `readiness_forecast` added.
+    """
+    return policy.transform(df=df, forecast_col=forecast_col)

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/policies/tau_policy.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Tau (τ) policy artifacts for eb-optimization.
 
@@ -11,16 +9,19 @@ This module defines *frozen governance* for selecting a tolerance τ used by HR@
 Policies should be stable, auditable, and safe to apply at runtime.
 """
 
-from dataclasses import dataclass
-from typing import Any, Dict, Iterable, Mapping, Tuple, Union
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
 
 import numpy as np
 import pandas as pd
 
 from eb_optimization.tuning.tau import (
     TauMethod,
-    estimate_tau,
     estimate_entity_tau,
+    estimate_tau,
     hr_at_tau,
 )
 
@@ -44,17 +45,13 @@ class TauPolicy:
     min_n: int = 30
 
     # Passed to estimate_tau(...)
-    estimate_kwargs: Mapping[str, Any] = None  # type: ignore[assignment]
+    estimate_kwargs: Mapping[str, Any] = field(default_factory=dict)
 
     # Governance
     cap_with_global: bool = False
     global_cap_quantile: float = 0.99
 
     def __post_init__(self) -> None:
-        # dataclasses + Mapping default guard
-        if self.estimate_kwargs is None:  # type: ignore[truthy-bool]
-            object.__setattr__(self, "estimate_kwargs", {})
-
         if self.min_n < 1:
             raise ValueError(f"min_n must be >= 1. Got {self.min_n}.")
         if not (0.0 < self.global_cap_quantile <= 1.0):
@@ -80,10 +77,10 @@ DEFAULT_TAU_POLICY = TauPolicy(
 
 
 def apply_tau_policy(
-    y: Union[pd.Series, np.ndarray, Iterable[float]],
-    yhat: Union[pd.Series, np.ndarray, Iterable[float]],
+    y: pd.Series | np.ndarray | Iterable[float],
+    yhat: pd.Series | np.ndarray | Iterable[float],
     policy: TauPolicy = DEFAULT_TAU_POLICY,
-) -> Tuple[float, Dict[str, Any]]:
+) -> tuple[float, dict[str, Any]]:
     """
     Apply a frozen τ policy to produce τ (global).
 
@@ -101,10 +98,10 @@ def apply_tau_policy(
 
 
 def apply_tau_policy_hr(
-    y: Union[pd.Series, np.ndarray, Iterable[float]],
-    yhat: Union[pd.Series, np.ndarray, Iterable[float]],
+    y: pd.Series | np.ndarray | Iterable[float],
+    yhat: pd.Series | np.ndarray | Iterable[float],
     policy: TauPolicy = DEFAULT_TAU_POLICY,
-) -> Tuple[float, float, Dict[str, Any]]:
+) -> tuple[float, float, dict[str, Any]]:
     """
     Apply τ policy, then compute HR@τ.
 
@@ -148,9 +145,9 @@ def apply_entity_tau_policy(
 
 
 __all__ = [
-    "TauPolicy",
     "DEFAULT_TAU_POLICY",
+    "TauPolicy",
+    "apply_entity_tau_policy",
     "apply_tau_policy",
     "apply_tau_policy_hr",
-    "apply_entity_tau_policy",
-]
+]

eb_optimization-0.2.1/src/eb_optimization/search/__init__.py

@@ -0,0 +1,12 @@
+"""
+Search primitives for the Electric Barometer optimization layer.
+
+The `eb_optimization.search` package contains generic, reusable search utilities
+for iterating over candidate spaces (e.g., grid generation, argmin/argmax kernels).
+"""
+
+from __future__ import annotations
+
+from . import grid, kernels
+
+__all__ = ["grid", "kernels"]

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/search/grid.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Grid construction utilities for optimization search spaces.
 
@@ -21,10 +19,16 @@ This utility favors bounded, discrete search spaces for interpretability, audita
 and deployability of learned policies.
 """
 
-import numpy as np
+from __future__ import annotations
+
 import math
 
-def make_float_grid(x_min: float, x_max: float, step: float, decimals: int = 10) -> np.ndarray:
+import numpy as np
+
+
+def make_float_grid(
+    x_min: float, x_max: float, step: float, decimals: int = 10
+) -> np.ndarray:
     r"""Create a numerically robust 1D grid over a closed interval.
 
     This utility is used throughout optimization to create bounded, interpretable
@@ -88,4 +92,4 @@ def make_float_grid(x_min: float, x_max: float, step: float, decimals: int = 10)
     vals = np.unique(vals)
     vals.sort()
 
-    return vals
+    return vals

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/search/kernels.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Generic discrete-search kernels for eb-optimization.
 
@@ -28,15 +26,16 @@ They serve as reusable building blocks for higher-level tuning logic
 across the Electric Barometer ecosystem.
 """
 
-from typing import Callable, Iterable, Literal, TypeVar
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Literal, TypeVar
+
 import numpy as np
 
 T = TypeVar("T")
 
-__all__ = [
-    "argmin_over_candidates",
-    "argmax_over_candidates",
-]
+__all__ = ["argmax_over_candidates", "argmin_over_candidates"]
 
 
 def argmin_over_candidates(
@@ -84,12 +83,14 @@ def argmin_over_candidates(
             best_score = score
             continue
 
-        if score == best_score:
-            if tie_break == "last":
-                best_candidate = cand
-            elif tie_break == "closest_to_zero":
-                if abs(float(cand)) < abs(float(best_candidate)):  # type: ignore[arg-type]
-                    best_candidate = cand
+        if score == best_score and (
+            tie_break == "last"
+            or (
+                tie_break == "closest_to_zero"
+                and abs(float(cand)) < abs(float(best_candidate))  # type: ignore[arg-type]
+            )
+        ):
+            best_candidate = cand
 
     if best_candidate is None or best_score is None:
         raise ValueError("candidates must be a non-empty iterable")
@@ -112,4 +113,4 @@ def argmax_over_candidates(
         candidates=candidates,
         score_fn=lambda c: -float(score_fn(c)),
         tie_break=tie_break,
-    )
+    )

{eb_optimization-0.1.1 → eb_optimization-0.2.1}/src/eb_optimization/tuning/__init__.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Tuning utilities for the Electric Barometer ecosystem.
 
@@ -19,9 +17,13 @@ re-exporting function symbols. This avoids import-time breakage when internals
 are renamed during refactors.
 """
 
+from __future__ import annotations
+
+from . import cost_ratio, ral, sensitivity, tau
+
 __all__ = [
     "cost_ratio",
+    "ral",
     "sensitivity",
     "tau",
-    "ral",
-]
+]