mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
feat/https-compose-caddy
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> |