Metadata-Version: 2.4
Name: eb-optimization
Version: 0.2.8
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: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: eb-metrics==0.2.9
Requires-Dist: eb-evaluation==0.2.10
Provides-Extra: eb
Requires-Dist: eb-metrics==0.2.9; extra == "eb"
Requires-Dist: eb-evaluation==0.2.10; 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"
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.2.9; extra == "all"
Requires-Dist: eb-evaluation==0.2.10; 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`)

[![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.

---

## Overview

`eb-optimization` calibrates operational parameters (cost ratios, τ, readiness controls) and freezes them into auditable runtime policies. It does not compute metrics or run evaluation panels; those belong to `eb-metrics` and `eb-evaluation`.

---

## 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.
© 2026 Kyle Corrie.
