LLM Carbon Index
English | 中文 | Deutsch
A public, transparent dashboard that estimates the CO₂ footprint of the
LLM-inference traffic visible through OpenRouter's public rankings,
broken down by model, open- vs closed-weight, provider, model origin country,
and the electricity grid of the model's likely serving region.
▶ View the live dashboard — leaderboards by total CO₂ and by efficiency, green-electricity scenario sliders, a market-vs-location Scope-2 toggle, and a Methodology & Uncertainty page. Trilingual (EN / 中文 / DE).
Scope statement (NON-NEGOTIABLE)
This project estimates the CO₂ footprint of OpenRouter-visible LLM inference —
a representative but partial slice of global AI usage. Consumer apps like
ChatGPT, Gemini, and Claude are not in it. It is NOT a measurement of
total global data-center emissions. All figures are estimates with explicit
uncertainty ranges, not measurements — especially for closed models, whose
parameters, hardware, and data-center locations are not publicly disclosed.
📊 For Researchers & ESG Professionals
The data generated by this project is fully open and designed to be ingested into your own sustainability reports, LCA (Life Cycle Assessment) tools, or CSRD/ESRS Scope 3 disclosures.
- Download Data: The daily updated JSON is available at
data/output/latest.json.
- ESG / CSRD export:
data/output/esg_export.json maps location- and market-based totals to GHG-Protocol Scope-2 dual reporting + an ESRS-E1 line item, with the scope/uncertainty caveat embedded. A JSON/CSV download is also in the web UI.
- Methodology: Read our comprehensive Methodology & Uncertainty Framework detailing equations, sources (e.g., EcoLogits, AI Energy Score, Electricity Maps), and sensitivity analysis (e.g., PUE variations).
- Contribute: See CONTRIBUTING.md and check out our Issue Templates for reporting data corrections or new model architecture profiles.
Architecture (decided)
Static-first, no server to babysit (per PLAN.md):
OpenRouter rankings ─▶ pipeline (Python) ─▶ data/output/*.json (committed by CI) ─▶ web/ (Vite + React, static)
│
EcoLogits + AI Energy Score (energy)
Electricity Maps + annual fallbacks (grid)
No live backend for v1. The frontend reads committed JSON; a daily GitHub
Actions cron (.github/workflows/pipeline.yml)
re-runs the pipeline, snapshots its inputs, runs all gates, and opens a
data-only PR. The dedicated auto-merge workflow queues a squash merge only
after its scope check and required checks pass.
Status
Built strictly phase by phase (PLAN.md); the authoritative phase
ledger with commit hashes lives in specs/INDEX.md.
Current methodology version 0.8.0; main is green (ruff · 186 pytest ·
make verify byte-identical replay of all 76 published dates · web tsc+build ·
57 vitest) and deployed.
| Phase | Scope | State |
|---|
| 0–1 | Scaffold + prove the math · OpenRouter ingestion | ✅ done |
| 2 | Energy estimation (pipeline/energy.py) | ✅ done |
| 3 | Carbon + grid + green substitution (pipeline/carbon.py, pipeline/grid.py) | ✅ done |
| 4 | Output assembly + frontend (pipeline/output.py, web/) | ✅ done |
| 5 | Methodology doc + CI + deploy | ✅ done |
| 6A–6E | Green scenarios · market-vs-location · history/Jevons · water (WUE) · coverage automation | ✅ done |
| 6F–6I | Estimation-tier honesty · provenance ledger (no-unsourced-number gate) · reproducibility harness (make verify) · fairness + boundary | ✅ done |
| 6J–6K | Measured per-token energy + idle term (energy_measured_fraction 0 → 0.29) · OAT sensitivity analysis | ✅ done |
| 6L–6R | Retrofuturist re-skin · ranking → tiering · physical embodied estimator · literature cross-validation · MoE active-param energy · dynamic regime/batching · ESG/CSRD Scope-2 export | ✅ done |
Repository layout
Model data lives only in data/*.yaml (Hard Constraint #6); the pipeline is
pure Python; the frontend is a static Vite + React app that reads committed JSON.
llm-carbon-index/
├── PLAN.md · CLAUDE.md · README.md · LICENSE · NOTICE.md · SECURITY.md · CONTRIBUTING.md · CHANGELOG.md
├── pyproject.toml · Makefile · .env.example # deps, `make verify|test|lint`, env-var NAMES only
├── data/ # model data ONLY here (Hard Constraint #6)
│ ├── crosswalk/model_crosswalk.yaml # OpenRouter slug → energy source + assumptions
│ ├── assumptions/ # closed-model, embodied-hardware, vendor-claim, regime sets
│ ├── grid/annual_factors.yaml # annual gCO₂/kWh fallbacks (Ember/IEA, cited)
│ ├── energy/intensity.yaml # per-token energy intensities (cited)
│ ├── provenance/sources.yaml # source registry — every number resolves here (6G gate)
│ ├── validation/literature_anchors.yaml # external Wh/query anchors for cross-checking
│ ├── raw/snapshots/<date>/ # frozen daily inputs for reproducible replay (6H)
│ └── output/ # generated JSON, committed by CI
│ ├── latest.json · timeseries.json · sensitivity.json
│ ├── validation.json · esg_export.json · manifest.json
│ └── history/<date>.json
├── pipeline/ # ingest → energy → carbon → embodied/water → output
│ ├── ingest.py · openrouter.py · slugs.py · tokens.py
│ ├── energy.py · carbon.py · grid.py · embodied.py · water.py
│ ├── sensitivity.py · fairness.py · precision.py · ranges.py
│ ├── provenance.py · snapshot.py · manifest.py · verify.py # provenance + reproducibility (6G/6H)
│ ├── validate_literature.py · output.py · run.py # cross-validation, assembly, daily entrypoint
│ └── README.md # module map
├── tests/ # 149 tests — full CO₂ chain + unit-conversion guards
├── web/ # Vite + React static dashboard (reads data/output/*.json)
│ └── src/{components,lib,theme} # 6L retrofuturist theme; trilingual i18n (en/zh/de)
├── docs/ # methodology · DATA_SCHEMAS · ASSUMPTIONS · BOUNDARY · FAIRNESS (each ×3 langs)
├── schemas/ # JSON Schema for output + ESG export
├── specs/ # phase specs + INDEX.md (authoritative phase ledger)
└── .github/workflows/ # ci · pipeline (daily cron) · deploy · codeql · gitleaks
Reproduce & verify
To reproduce a published daily run from its exact frozen inputs (Phase 6H):
git clone https://github.com/wyl2607/llm-carbon-index.git
cd llm-carbon-index
uv sync
make verify 2026-06-14 # expect PASS
See docs/methodology.md §11 for snapshot layout, manifest.json checksums, golden-file comparison (ignoring generated_at), and the pinned-dep contract.
Attribution
- Rankings:
Source: OpenRouter (openrouter.ai/rankings), as of {date}.
- Grid intensity: EIA hourly (PJM for us-east when keyed) + Ember/IEA annual (fallback). Live paths exist;
grid_live_fraction = 0.0 in published goldens until a keyed run is committed (see docs/methodology.md §11a).
- Energy: EcoLogits + Hugging Face AI Energy Score. See
docs/methodology.md.
License
MIT — see LICENSE. The published figures are estimates with uncertainty
ranges, not measurements; see NOTICE.md.
