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.