eb-optimization 0.2.0__tar.gz → 0.2.3__tar.gz

{eb_optimization-0.2.0/src/eb_optimization.egg-info → eb_optimization-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eb-optimization
-Version: 0.2.0
+Version: 0.2.3
 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,11 +28,21 @@ 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"
+Requires-Dist: ruff>=0.0.1; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: eb-metrics<0.3,>=0.2; extra == "all"
+Requires-Dist: eb-evaluation<0.3,>=0.2; extra == "all"
+Requires-Dist: pytest>=8.0; extra == "all"
+Requires-Dist: scikit-learn>=1.3; extra == "all"
+Requires-Dist: pytest-cov>=5.0; extra == "all"
+Requires-Dist: ruff>=0.0.1; extra == "all"
+Requires-Dist: pyright>=1.1; extra == "all"
+Requires-Dist: twine>=4.0; extra == "all"
 Dynamic: license-file
 
 # Electric Barometer · Optimization (`eb-optimization`)
@@ -120,5 +130,5 @@ print(R)
 
 ## License
 
-BSD 3-Clause License.  
+BSD 3-Clause License.
 © 2025 Kyle Corrie.

{eb_optimization-0.2.0 → eb_optimization-0.2.3}/README.md

@@ -83,5 +83,5 @@ print(R)
 
 ## License
 
-BSD 3-Clause License.  
-© 2025 Kyle Corrie.
+BSD 3-Clause License.
+© 2025 Kyle Corrie.

{eb_optimization-0.2.0 → eb_optimization-0.2.3}/pyproject.toml

@@ -3,7 +3,7 @@
 ######################################
 [project]
 name = "eb-optimization"
-version = "0.2.0"
+version = "0.2.3"
 description = "Electric Barometer: Optimization and tuning utilities for EB objectives and policy parameters."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -67,22 +67,39 @@ eb = [
 ]
 
 # Optional optimization backends (future-proofing)
-# Keep empty for now; add later when you actually introduce them.
-opt = [
-]
+opt = []
 
 # CI / test-only dependencies
 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]",
+  "ruff>=0.0.1",
+  "pyright>=1.1",
+  "twine>=4.0",
+]
+
+# Combined extra to satisfy the "extras: all" CI contract.
+# Aggregates EB ecosystem dependencies and test tooling.
+all = [
+  # EB ecosystem deps
+  "eb-metrics>=0.2,<0.3",
+  "eb-evaluation>=0.2,<0.3",
+
+  # test deps
+  "pytest>=8.0",
+  "scikit-learn>=1.3",
+
+  # dev tooling
+  "pytest-cov>=5.0",
+  "ruff>=0.0.1",
+  "pyright>=1.1",
+  "twine>=4.0",
 ]
 
 ######################################
@@ -103,4 +120,4 @@ where = ["src"]
 ######################################
 [tool.pytest.ini_options]
 pythonpath = ["src"]
-addopts = "-ra"
+addopts = "-ra"

{eb_optimization-0.2.0 → eb_optimization-0.2.3}/src/eb_optimization/__init__.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 `eb_optimization` — optimization and tuning layer for the Electric Barometer ecosystem.
 
@@ -13,8 +11,18 @@ It intentionally does **not** define metric primitives or evaluation math.
 Those live in `eb-metrics` (and orchestration lives in `eb-evaluation`).
 """
 
+from __future__ import annotations
+
 from importlib.metadata import PackageNotFoundError, version
 
+from .policies.ral_policy import (
+    DEFAULT_RAL_POLICY,
+    RALDeltas,
+    RALTwoBandPolicy,
+    apply_ral_policy,
+)
+from .tuning.cost_ratio import EntityCostRatioEstimate
+
 
 def _resolve_version() -> str:
     """
@@ -35,4 +43,11 @@ def _resolve_version() -> str:
 
 __version__ = _resolve_version()
 
-__all__ = ["__version__"]
+__all__ = [
+    "DEFAULT_RAL_POLICY",
+    "EntityCostRatioEstimate",
+    "RALDeltas",
+    "RALTwoBandPolicy",
+    "__version__",
+    "apply_ral_policy",
+]

{eb_optimization-0.2.0 → eb_optimization-0.2.3}/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",
 ]
 
 
@@ -73,9 +73,7 @@ def broadcast_param(x: ArrayLike, shape: tuple[int, ...], name: str) -> np.ndarr
         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}"
-        )
+        raise ValueError(f"{name} must be scalar or have shape {shape}; got shape {arr.shape}")
 
     return arr
 
@@ -112,11 +110,9 @@ def handle_sample_weight(sample_weight: ArrayLike | None, n: int) -> np.ndarray:
     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}"
-        )
+        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
+    return w

{eb_optimization-0.2.0 → eb_optimization-0.2.3}/src/eb_optimization/policies/__init__.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 Frozen policy artifacts for the Electric Barometer optimization layer.
 
@@ -25,52 +23,51 @@ Exported policies
 - Tau (τ) tolerance governance for HR@τ
 - Cost-ratio (R = c_u / c_o) governance for asymmetric loss
 - RAL policy governance (readiness adjustment layer)
+- DQC (Δ*) governance for packed / quantized demand snapping and evaluation
 """
 
-# ---------------------------------------------------------------------
-# 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 .dqc_policy import (
+    DEFAULT_DQC_POLICY,
+    DQCPolicy,
+    DQCResult,
+    compute_dqc,
+    enforce_snapping,
+    hr_at_tau_grid_units,
+    snap_to_grid,
+)
+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_DQC_POLICY",
+    "DEFAULT_RAL_POLICY",
+    "CostRatioPolicy",
+    "DQCPolicy",
+    "DQCResult",
+    "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",
+    "compute_dqc",
+    "enforce_snapping",
+    "hr_at_tau_grid_units",
+    "snap_to_grid",
+]

eb_optimization-0.2.3/src/eb_optimization/policies/cost_ratio_policy.py

@@ -0,0 +1,409 @@
+"""
+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.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+import warnings
+
+import numpy as np
+from numpy.typing import ArrayLike
+import pandas as pd
+
+from eb_optimization.tuning.cost_ratio import (
+    CostRatioEstimate,
+    EntityCostRatioEstimate,
+    estimate_entity_R_from_balance,
+    estimate_R_cost_balance,
+)
+
+GateMode = Literal["off", "warn", "raise"]
+
+
+@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.
+    co : float
+        Default overbuild cost coefficient used for entity-level estimation.
+    min_n : int
+        Minimum number of observations required to estimate an entity-level R.
+    """
+
+    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 _handle_identifiability_gate(
+    *,
+    gate: GateMode,
+    ok: bool,
+    message: str,
+    override_reason: str | None,
+) -> dict[str, Any]:
+    """
+    Warn-only / gateable hook shared by global + entity policy applications.
+
+    Returns a JSON-serializable dict with the gating decision metadata that can be
+    merged into diagnostics payloads.
+    """
+    gate = cast(GateMode, gate)
+    if gate not in ("off", "warn", "raise"):
+        raise ValueError("gate must be one of: 'off', 'warn', 'raise'")
+
+    meta: dict[str, Any] = {
+        "gate_mode": gate,
+        "gate_triggered": bool(not ok),
+        "gate_overridden": bool((not ok) and (override_reason is not None)),
+        "gate_override_reason": override_reason,
+    }
+
+    if ok or gate == "off":
+        return meta
+
+    # If not ok:
+    if override_reason is not None:
+        # Override: do not warn/raise; record reason.
+        return meta
+
+    if gate == "warn":
+        warnings.warn(message, RuntimeWarning, stacklevel=2)
+        return meta
+
+    # gate == "raise"
+    raise ValueError(message)
+
+
+def apply_cost_ratio_policy(
+    y_true: ArrayLike,
+    y_pred: ArrayLike,
+    *,
+    policy: CostRatioPolicy = DEFAULT_COST_RATIO_POLICY,
+    co: float | ArrayLike | None = None,
+    sample_weight: ArrayLike | None = None,
+    gate: GateMode = "warn",
+    identifiability_override_reason: str | None = None,
+) -> tuple[float, dict[str, Any]]:
+    """
+    Apply a frozen cost-ratio policy to estimate a global R.
+
+    Notes
+    -----
+    This policy boundary surfaces identifiability / stability diagnostics when available.
+    It does NOT change the selection behavior; it only enriches the returned diagnostics.
+
+    Gating
+    ------
+    `gate` controls what happens when tuning reports `is_identifiable=False`:
+
+    - gate="off"  : no action (still reports diagnostics)
+    - gate="warn" : emit a RuntimeWarning (default)
+    - gate="raise": raise ValueError
+
+    Overrides
+    ---------
+    If `identifiability_override_reason` is provided, the gate will not warn/raise,
+    and the reason is recorded in diagnostics for auditability.
+    """
+    co_val = policy.co if co is None else co
+
+    # Request the richer artifact so we can surface identifiability at the policy boundary.
+    est_any: Any = estimate_R_cost_balance(
+        y_true=y_true,
+        y_pred=y_pred,
+        R_grid=policy.R_grid,
+        co=co_val,
+        sample_weight=sample_weight,
+        return_curve=True,
+        selection="curve",
+    )
+
+    stability_diag: dict[str, Any]
+    gate_meta: dict[str, Any] = {}
+
+    if isinstance(est_any, CostRatioEstimate):
+        est = est_any
+        R = float(est.R_star)
+
+        ok = bool(est.is_identifiable)
+        msg = (
+            "Cost ratio calibration is not identifiable/stable under configured diagnostics. "
+            f"(rel_min_gap={float(est.rel_min_gap):.6g}, "
+            f"grid_instability_log={float(est.grid_instability_log):.6g}, "
+            f"R_star={float(est.R_star):.6g}, R_range=[{float(est.R_min):.6g}, {float(est.R_max):.6g}])."
+        )
+
+        gate_meta = _handle_identifiability_gate(
+            gate=gate,
+            ok=ok,
+            message=msg,
+            override_reason=identifiability_override_reason,
+        )
+
+        stability_diag = {
+            # Policy-surfaced stability fields (governance/reporting only)
+            "rel_min_gap": float(est.rel_min_gap),
+            "R_min": float(est.R_min),
+            "R_max": float(est.R_max),
+            "grid_instability_log": float(est.grid_instability_log),
+            "is_identifiable": bool(est.is_identifiable),
+            # Full tuning diagnostics
+            "calibration_diagnostics": dict(est.diagnostics),
+        }
+    else:
+        R = float(est_any)
+        stability_diag = {
+            "calibration_diagnostics": {
+                "note": "Upstream returned a scalar R; stability diagnostics unavailable.",
+            }
+        }
+
+    diag: dict[str, Any] = {
+        "method": "cost_balance",
+        "R_grid": [float(x) for x in policy.R_grid],
+        "co_is_array": isinstance(co_val, list | tuple | np.ndarray | pd.Series),
+        "co_default_used": co is None,
+        "R": float(R),
+        **stability_diag,
+        **({"identifiability_gate": gate_meta} if gate_meta else {}),
+    }
+    return (float(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: float | None = None,
+    sample_weight_col: str | None = None,
+    include_diagnostics: bool = True,
+    gate: GateMode = "warn",
+    identifiability_override_reason: str | None = None,
+) -> pd.DataFrame:
+    """
+    Apply a frozen cost-ratio policy per entity.
+
+    Notes
+    -----
+    This policy boundary surfaces per-entity calibration diagnostics (in the
+    `diagnostics` column) for eligible entities when `include_diagnostics=True`.
+
+    Entity-level identifiability
+    ----------------------------
+    The tuning artifact returns per-entity `diagnostics` dicts. If those dicts contain
+    an `is_identifiable` field, this function will:
+      - surface a convenience `is_identifiable` column, and
+      - optionally warn/raise based on `gate`.
+
+    If no such field exists (older tuning versions), gating is a no-op.
+    """
+    # ---- validation: columns ----
+    required_cols = {entity_col, y_true_col, y_pred_col}
+    if sample_weight_col is not None:
+        required_cols.add(sample_weight_col)
+
+    missing = [c for c in required_cols if c not in df.columns]
+    if missing:
+        raise KeyError(f"Missing required columns: {missing}")
+
+    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: identify eligible entities ----
+    counts_ser = cast(pd.Series, df.groupby(entity_col, dropna=False, sort=False).size())
+    eligible_counts = cast(pd.Series, counts_ser[counts_ser >= policy.min_n])
+    eligible_list = cast(list[Any], eligible_counts.index.tolist())
+
+    mask = df[entity_col].isin(eligible_list)
+
+    eligible_df = cast(pd.DataFrame, df[mask]).copy()
+    ineligible_df = cast(pd.DataFrame, df[~mask]).copy()
+
+    results_list: list[pd.DataFrame] = []
+
+    gate_meta: dict[str, Any] = {}
+    failed_entities: list[Any] = []
+
+    # Track whether we can gate at all (only if the diagnostics dicts contain is_identifiable)
+    identifiability_available = False
+
+    if not eligible_df.empty:
+        tuned_any: Any = estimate_entity_R_from_balance(
+            df=eligible_df,
+            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,
+            return_result=True,
+            selection="curve",
+        )
+        tuned_art = cast(EntityCostRatioEstimate, tuned_any)
+
+        tuned_table = cast(pd.DataFrame, tuned_art.table).copy()
+
+        tuned = pd.DataFrame(
+            {
+                entity_col: tuned_table[entity_col],
+                "R": tuned_table["R_star"].astype(float),
+                "cu": (tuned_table["R_star"].astype(float) * float(co_val)).astype(float),
+                "co": float(co_val),
+                "under_cost": tuned_table["under_cost"].astype(float),
+                "over_cost": tuned_table["over_cost"].astype(float),
+                "diff": tuned_table["gap"].astype(float),
+            }
+        )
+
+        # Always attach diagnostics internally (for gating), drop later if include_diagnostics=False
+        if "diagnostics" in tuned_table.columns:
+            tuned["diagnostics"] = tuned_table["diagnostics"]
+        else:
+            tuned["diagnostics"] = None
+
+        tuned["reason"] = None
+
+        mapper: Any = counts_ser
+        tuned["n"] = tuned[entity_col].map(mapper).astype(int)
+
+        # Surface an `is_identifiable` column if diagnostics provides it.
+        # This is a convenience field for users/tests and lets gating be explicit/inspectable.
+        def _extract_is_identifiable(v: Any) -> Any:
+            if isinstance(v, dict) and ("is_identifiable" in v):
+                return bool(v.get("is_identifiable"))
+            return None
+
+        tuned["is_identifiable"] = tuned["diagnostics"].map(_extract_is_identifiable)
+
+        # ---- FIX: make the conditional unambiguously bool for Pyright ----
+        has_ident = bool(tuned["is_identifiable"].notna().to_numpy().any())
+        if has_ident:
+            identifiability_available = True
+            failed_mask = tuned["is_identifiable"] == False  # noqa: E712
+            failed_entities = cast(list[Any], tuned.loc[failed_mask, entity_col].tolist())
+
+        if identifiability_available and failed_entities:
+            msg = (
+                "One or more entities have non-identifiable cost ratio calibration. "
+                f"Failed entities (first 10): {failed_entities[:10]!r}. "
+                "You may override with identifiability_override_reason."
+            )
+            gate_meta = _handle_identifiability_gate(
+                gate=gate,
+                ok=False,
+                message=msg,
+                override_reason=identifiability_override_reason,
+            )
+
+        results_list.append(tuned)
+
+    if not ineligible_df.empty:
+        ineligible_rows = cast(pd.DataFrame, ineligible_df[[entity_col]]).drop_duplicates()
+        ineligible_rows = ineligible_rows.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})",
+            diagnostics=None,
+            is_identifiable=None,
+        )
+
+        mapper_ineligible: Any = counts_ser
+        ineligible_rows["n"] = ineligible_rows[entity_col].map(mapper_ineligible).astype(int)
+        results_list.append(ineligible_rows)
+
+    if not results_list:
+        schema_cols = [
+            entity_col,
+            "R",
+            "cu",
+            "co",
+            "n",
+            "reason",
+            "under_cost",
+            "over_cost",
+            "diff",
+        ]
+        if include_diagnostics:
+            schema_cols.append("diagnostics")
+        # Include is_identifiable if we can ever surface it (safe default: include it anyway)
+        schema_cols.append("is_identifiable")
+        if gate_meta:
+            schema_cols.append("identifiability_gate")
+
+        return pd.DataFrame(columns=pd.Index(schema_cols))
+
+    out = pd.concat(results_list, ignore_index=True, sort=False)
+
+    # Attach gate metadata as a repeated column (JSON-serializable) if it exists
+    if gate_meta:
+        out["identifiability_gate"] = [gate_meta] * int(out.shape[0])
+
+    base_cols = [entity_col, "R", "cu", "co", "n", "reason", "is_identifiable"]
+    diag_cols = ["under_cost", "over_cost", "diff"]
+
+    if include_diagnostics:
+        base_cols.append("diagnostics")
+
+    if not include_diagnostics and "diagnostics" in out.columns:
+        out = out.drop(columns=["diagnostics"])
+
+    if "identifiability_gate" in out.columns:
+        base_cols.append("identifiability_gate")
+
+    remaining = [str(c) for c in out.columns if c not in base_cols + diag_cols]
+    target_cols = (
+        (base_cols + diag_cols + remaining) if include_diagnostics else (base_cols + remaining)
+    )
+
+    return cast(pd.DataFrame, out[pd.Index(target_cols)])
+
+
+__all__ = [
+    "DEFAULT_COST_RATIO_POLICY",
+    "CostRatioPolicy",
+    "apply_cost_ratio_policy",
+    "apply_entity_cost_ratio_policy",
+]