Commit Graph
1 Commits
Author SHA1 Message Date
2bc9419467 feat(dashboard): add CO₂ Saved card to dashboard and /stats API (#1369)
## Description

Adds an estimated CO₂ Saved card to the proxy dashboard and `/stats`
JSON response, surfacing carbon footprint reduction alongside the
existing token and cost savings.

Motivation: Honey (Green-PT/honey-for-devs) ships a CO₂ tracking feature
ported from EcoLogits. Headroom already has all the data needed — tokens
saved per model — to make the same estimate. This PR wires that up.

Methodology: EcoLogits v0.8 energy-per-token constants (Wh/token per
model tier) × IEA 2023 global average carbon intensity (0.4 kg CO₂/kWh).
Conservative bias throughout — we underestimate rather than
overestimate. The methodology string and a bias note are exposed in the
API response and dashboard tooltip so users understand the estimate's
limits.

---

## Type of Change

- [ ] Bug fix
- [x] New feature (non-breaking addition)
- [ ] Breaking change
- [ ] Documentation update
- [x] Performance improvement
- [ ] Refactoring

---

## Changes Made

`headroom/proxy/savings_tracker.py`
- Added `estimate_co2_saved_mg(tokens_saved, model)` public function
with EcoLogits-based energy constants for Claude, GPT-4, GPT-4o, o1/o3,
Gemini families; default for unknown models
- Added `co2` block to `stats_preview()` return: `co2_saved_mg`,
`co2_saved_g`, `methodology`, `note`
- Added `model` parameter to `stats_preview()` (default `""`, backward
compatible)

`headroom/dashboard/templates/dashboard.html`
- Added CO₂ Saved stat card in the token stats grid, after the Savings%
card
- `formatCO2(mg)` Alpine.js helper: auto-scales to mg / g / kg
- Tooltip on card shows EcoLogits methodology

`tests/test_co2_estimation.py` (new file)
- 7 tests (see Testing section)

`CHANGELOG.md`
- Added entry under `## Unreleased → ### Features`

---

## Testing

- [x] New tests added and passing
- [x] Backward compatible — `stats_preview()` default `model=""` uses
conservative default factor

New tests — all pass:

```
tests/test_co2_estimation.py::test_zero_tokens_returns_zero
tests/test_co2_estimation.py::test_positive_tokens_returns_positive
tests/test_co2_estimation.py::test_claude_sonnet_uses_correct_factor
tests/test_co2_estimation.py::test_unknown_model_uses_default_factor
tests/test_co2_estimation.py::test_claude_haiku_lower_than_sonnet
tests/test_co2_estimation.py::test_large_savings_in_grams
tests/test_co2_estimation.py::test_stats_preview_includes_co2
```

---

## Real Behavior Proof

- Environment: macOS 15.5 arm64, Python 3.12, local editable current PR
checkout.
- Exact command / steps: ran the seven estimator/API tests, Ruff, the
Chromium Playwright UI regression, a local proxy, and queried `/stats`.
- Observed result: estimator/API tests and UI rendering pass; `/stats`
exposes the CO2 block and the dashboard renders the estimated savings
card.
- Not tested: every dashboard theme and operator-supplied custom carbon
intensity.

Environment:
- OS: macOS 15.5 arm64 (Apple M3 Pro)
- Python: 3.12.0
- headroom-ai: 0.28.0 (local editable install from this branch)
- pytest: 9.0.3

Exact commands:

```bash
git clone https://github.com/peterlodri-sec/headroom
cd headroom
git checkout feat/co2-dashboard-card
pip install -e ".[dev]" -q
python -m pytest tests/test_co2_estimation.py -v
```

Observed result:

```
collected 7 items

tests/test_co2_estimation.py::test_zero_tokens_returns_zero PASSED
tests/test_co2_estimation.py::test_positive_tokens_returns_positive PASSED
tests/test_co2_estimation.py::test_claude_sonnet_uses_correct_factor PASSED
tests/test_co2_estimation.py::test_unknown_model_uses_default_factor PASSED
tests/test_co2_estimation.py::test_claude_haiku_lower_than_sonnet PASSED
tests/test_co2_estimation.py::test_large_savings_in_grams PASSED
tests/test_co2_estimation.py::test_stats_preview_includes_co2 PASSED

7 passed in 1.73s
```

Live verification (headroom proxy running locally):

```bash
curl -s http://127.0.0.1:8787/stats | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('co2'))"
# → {'tokens_saved': 51046, 'co2_saved_mg': 4.084, 'co2_saved_g': 4.1e-06, 'methodology': '...', 'note': '...'}
```

Not tested:
- Dashboard visual rendering in all themes (tested dark mode locally)
- Operator-supplied custom carbon intensity (not configurable in this PR
— could be a follow-up `HEADROOM_CO2_CARBON_INTENSITY_KG_PER_KWH` env
var)

---

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review
- [x] Tests passing (`python -m pytest tests/test_co2_estimation.py -v`
— 7 passed)
- [x] `ruff check headroom/proxy/savings_tracker.py` — clean
- [x] I did not edit CHANGELOG.md; release notes are generated
automatically
- [x] Backward compatible — `model=""` default, `co2` block is additive
to existing JSON shape

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
2026-10-03 00:33:04 -05:00