eb-optimization 0.1.0__py3-none-any.whl

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/_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/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",
+]

eb_optimization/policies/cost_ratio_policy.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+"""
+Cost-ratio (R = c_u / c_o) policy artifacts for eb-optimization.
+
+This module defines *frozen governance* for selecting and applying a cost ratio `R`
+(and derived underbuild cost `c_u`) used by asymmetric cost metrics like CWSL.
+
+Layering & responsibilities
+---------------------------
+- `tuning/cost_ratio.py`:
+    Calibration logic (estimating R from residuals / cost balance).
+- `policies/cost_ratio_policy.py`:
+    Frozen configuration + deterministic application wrappers.
+
+The policy layer exists so downstream consumers can:
+- pin method + governance settings in a versioned, auditable object
+- apply the same selection logic consistently across environments
+- avoid re-encoding configuration details in orchestration code
+
+Design intent
+-------------
+Policies should be:
+- stable: schema changes are deliberate and versioned
+- deterministic: same inputs + same policy -> same outputs
+- safe: validated governance parameters + clear failure semantics
+
+This module provides:
+- `CostRatioPolicy`: frozen configuration
+- `DEFAULT_COST_RATIO_POLICY`: exported default policy
+- `apply_cost_ratio_policy`: estimate global R from arrays/Series
+- `apply_entity_cost_ratio_policy`: estimate per-entity R from a DataFrame
+
+Notes
+-----
+- This policy does *not* compute CWSL. It only governs parameter selection.
+- `co` may be scalar or per-interval array for global estimation; for entity-level
+  estimation, `co` is currently modeled as a scalar (consistent with tuning).
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+
+from eb_optimization.tuning.cost_ratio import (
+    estimate_R_cost_balance,
+    estimate_entity_R_from_balance,
+)
+
+
+@dataclass(frozen=True)
+class CostRatioPolicy:
+    """
+    Frozen cost-ratio (R) policy configuration.
+
+    Attributes
+    ----------
+    R_grid : Sequence[float]
+        Candidate ratios to search. Only strictly positive values are considered.
+        Order matters for tie-breaking (first-minimizer behavior).
+    co : float
+        Default overbuild cost coefficient used for entity-level estimation
+        (and as a default for global estimation if `co` is not passed at call time).
+    min_n : int
+        Minimum number of observations required to estimate an entity-level R.
+        Entities with fewer observations are returned with NaN R (and diagnostics).
+    """
+
+    R_grid: Sequence[float] = (0.5, 1.0, 2.0, 3.0)
+    co: float = 1.0
+    min_n: int = 30
+
+    def __post_init__(self) -> None:
+        grid = np.asarray(list(self.R_grid), dtype=float)
+        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.")
+
+        if not np.isfinite(self.co) or float(self.co) <= 0:
+            raise ValueError(f"co must be finite and strictly positive. Got {self.co}.")
+
+        if self.min_n < 1:
+            raise ValueError(f"min_n must be >= 1. Got {self.min_n}.")
+
+
+DEFAULT_COST_RATIO_POLICY = CostRatioPolicy()
+
+
+def apply_cost_ratio_policy(
+    y_true: ArrayLike,
+    y_pred: ArrayLike,
+    *,
+    policy: CostRatioPolicy = DEFAULT_COST_RATIO_POLICY,
+    co: Union[float, ArrayLike, None] = None,
+    sample_weight: ArrayLike | None = None,
+) -> Tuple[float, Dict[str, Any]]:
+    """
+    Apply a frozen cost-ratio policy to estimate a global R.
+
+    Parameters
+    ----------
+    y_true, y_pred
+        Realized and forecast demand vectors (non-negative, same shape).
+    policy
+        Frozen configuration controlling the candidate grid and defaults.
+    co
+        Overbuild cost coefficient. If None, uses `policy.co`.
+        Can be scalar or per-interval array (passed through to tuning).
+    sample_weight
+        Optional non-negative per-interval weights.
+
+    Returns
+    -------
+    (R, diagnostics)
+        R is a float.
+        Diagnostics include the chosen R, co summary, and candidate grid.
+
+    Notes
+    -----
+    The underlying selection rule is in `tuning.estimate_R_cost_balance`:
+    choose R that minimizes |under_cost(R) - over_cost|.
+    """
+    co_val = policy.co if co is None else co
+
+    R = float(
+        estimate_R_cost_balance(
+            y_true=y_true,
+            y_pred=y_pred,
+            R_grid=policy.R_grid,
+            co=co_val,
+            sample_weight=sample_weight,
+        )
+    )
+
+    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)),
+        "co_default_used": co is None,
+        "R": R,
+    }
+    return (R, diag)
+
+
+def apply_entity_cost_ratio_policy(
+    df: pd.DataFrame,
+    *,
+    entity_col: str,
+    y_true_col: str,
+    y_pred_col: str,
+    policy: CostRatioPolicy = DEFAULT_COST_RATIO_POLICY,
+    co: Optional[float] = None,
+    sample_weight_col: Optional[str] = None,
+    include_diagnostics: bool = True,
+) -> pd.DataFrame:
+    """
+    Apply a frozen cost-ratio policy per entity.
+
+    This wraps `tuning.estimate_entity_R_from_balance` but adds policy governance:
+    - enforces a minimum sample size per entity (min_n)
+    - pins the candidate ratio grid (R_grid)
+    - provides stable, auditable defaults for co and configuration
+
+    Parameters
+    ----------
+    df
+        Input data containing entity ids, actuals, forecasts, and optionally weights.
+    entity_col
+        Column name identifying the entity to calibrate (e.g., restaurant_id).
+    y_true_col, y_pred_col
+        Column names for realized demand and forecast.
+    policy
+        Frozen configuration controlling ratios grid and governance.
+    co
+        Scalar overbuild cost coefficient. If None, uses `policy.co`.
+    sample_weight_col
+        Optional column name containing non-negative sample weights.
+    include_diagnostics
+        If True, returns diagnostics columns (under_cost, over_cost, diff) produced
+        by tuning. If False, trims to [entity_col, R, cu, co] plus governance columns.
+
+    Returns
+    -------
+    pandas.DataFrame
+        One row per entity with chosen R and supporting diagnostics. Entities
+        with fewer than `policy.min_n` observations will be returned with NaN R.
+
+    Raises
+    ------
+    KeyError
+        If required columns are missing.
+    ValueError
+        If invalid governance values or negative weights are present.
+
+    Notes
+    -----
+    The tuning implementation currently treats `co` as a scalar for entity-level
+    estimation (consistent with the function signature in tuning).
+    """
+    # ---- validation: columns ----
+    if entity_col not in df.columns:
+        raise KeyError(f"entity_col {entity_col!r} not found in df")
+    if y_true_col not in df.columns:
+        raise KeyError(f"y_true_col {y_true_col!r} not found in df")
+    if y_pred_col not in df.columns:
+        raise KeyError(f"y_pred_col {y_pred_col!r} not found in df")
+    if sample_weight_col is not None and sample_weight_col not in df.columns:
+        raise KeyError(f"sample_weight_col {sample_weight_col!r} not found in df")
+
+    co_val = float(policy.co if co is None else co)
+    if not np.isfinite(co_val) or co_val <= 0:
+        raise ValueError(f"co must be finite and strictly positive. Got {co_val}.")
+
+    # ---- governance: min_n (simple deterministic rule: row count per entity) ----
+    counts = df.groupby(entity_col, dropna=False, sort=False).size()
+    eligible_entities = counts[counts >= policy.min_n].index
+    ineligible_entities = counts[counts < policy.min_n].index
+
+    eligible = df[df[entity_col].isin(eligible_entities)].copy()
+    ineligible = df[df[entity_col].isin(ineligible_entities)].copy()
+
+    # ---- tune eligible entities ----
+    if not eligible.empty:
+        tuned = estimate_entity_R_from_balance(
+            df=eligible,
+            entity_col=entity_col,
+            y_true_col=y_true_col,
+            y_pred_col=y_pred_col,
+            ratios=policy.R_grid,
+            co=co_val,
+            sample_weight_col=sample_weight_col,
+        ).copy()
+        tuned["reason"] = None
+        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"]
+        )
+
+    # ---- build rows for ineligible entities (one row per entity) ----
+    if not ineligible.empty:
+        ineligible_rows = (
+            ineligible[[entity_col]]
+            .drop_duplicates()
+            .assign(
+                R=np.nan,
+                cu=np.nan,
+                co=co_val,
+                under_cost=np.nan,
+                over_cost=np.nan,
+                diff=np.nan,
+                reason=f"min_n_not_met(<{policy.min_n})",
+            )
+            .copy()
+        )
+        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"]
+        )
+
+    # ---- combine (avoid pandas FutureWarning on concat with empty/all-NA frames) ----
+    if ineligible_rows.empty:
+        out = tuned
+    elif tuned.empty:
+        out = ineligible_rows
+    else:
+        out = pd.concat([tuned, ineligible_rows], ignore_index=True, sort=False)
+
+    # ---- stable column ordering ----
+    base_cols = [entity_col, "R", "cu", "co", "n", "reason"]
+    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)
+
+    # Ensure all expected columns exist (even if empty)
+    for c in cols:
+        if c not in out.columns:
+            out[c] = np.nan
+
+    return out[cols]
+
+
+__all__ = [
+    "CostRatioPolicy",
+    "DEFAULT_COST_RATIO_POLICY",
+    "apply_cost_ratio_policy",
+    "apply_entity_cost_ratio_policy",
+]

eb_optimization/policies/ral_policy.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+"""
+Policy artifacts for the Readiness Adjustment Layer (RAL).
+
+This module defines portable, immutable policy objects produced by offline
+optimization and consumed by deterministic evaluation and production workflows.
+
+Responsibilities:
+- Represent learned RAL parameters (global and optional segment-level uplifts)
+- Provide a stable, serializable contract between optimization and evaluation
+- Support audit and governance workflows
+
+Non-responsibilities:
+- Learning or tuning parameters
+- Applying policies to data
+- Defining metric or loss functions
+
+Design philosophy:
+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
+import pandas as pd
+
+@dataclass(frozen=True)
+class RALPolicy:
+    r"""Portable policy artifact for the Readiness Adjustment Layer (RAL).
+
+    A :class:`~eb_optimization.policies.ral_policy.RALPolicy` is the *output* of an
+    offline tuning process (e.g., grid search or evolutionary optimization) and the
+    *input* to deterministic evaluation / production application.
+
+    Conceptually, RAL applies a multiplicative uplift to a baseline forecast:
+
+    $$ \hat{y}^{(r)} = u \cdot \hat{y} $$
+
+    where `u` can be either:
+
+    - a **global uplift** (`global_uplift`), applied to all rows, and/or
+    - **segment-level** uplifts stored in `uplift_table`, keyed by `segment_cols`
+
+    Segment-level uplifts must fall back to the global uplift for unseen segment
+    combinations at application time.
+
+    Attributes
+    ----------
+    global_uplift
+        The global multiplicative uplift used as a fallback and baseline readiness adjustment.
+    segment_cols
+        The segmentation columns used to key `uplift_table`. Empty means "global-only".
+    uplift_table
+        Optional DataFrame with columns `[*segment_cols, "uplift"]` containing
+        segment-level uplifts. If `None` or empty, the policy is global-only.
+
+    Notes
+    -----
+    This dataclass is intentionally simple and serializable. It is meant to be:
+
+    - produced offline in `eb-optimization`
+    - applied deterministically in `eb-evaluation`
+    - loggable/auditable as part of operational governance
+
+    The policy does *not* encode metric definitions or optimization state—only the
+    artifacts needed to execute the adjustment.
+    """
+
+    global_uplift: float
+    segment_cols: Sequence[str] = ()
+    uplift_table: Optional[pd.DataFrame] = 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
+
+    def adjust_forecast(self, df: pd.DataFrame, forecast_col: str) -> pd.Series:
+        """Apply the RAL policy to adjust the forecast values.
+
+        This method applies the global uplift to all rows, and applies segment-level uplifts
+        if the policy is segmented and matching segments exist in the `uplift_table`.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            The input DataFrame containing the forecast to adjust.
+        forecast_col : str
+            The name of the column in `df` containing the forecast values to adjust.
+
+        Returns
+        -------
+        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
+
+        # 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
+        return adjusted_forecast
+
+    def transform(self, df: pd.DataFrame, forecast_col: str) -> pd.DataFrame:
+        """Transform the input DataFrame by applying the forecast adjustment.
+
+        This method applies the RAL policy to adjust the forecast column and adds a new column
+        with the adjusted forecast.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            The input DataFrame containing the forecast to adjust.
+        forecast_col : str
+            The name of the column in `df` containing the forecast values to adjust.
+
+        Returns
+        -------
+        pd.DataFrame
+            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