ecocost

pip install ecocost

Per-request carbon, energy and water estimates for AI inference, each with a likely range and a confidence label computed from the evidence behind it. Every input is sourced and tiered, and the knowledge base in ecocost/data/ is open to pull requests from providers, hardware makers and researchers.

Maintained by Gooey.AI. Pure Python; the only dependency is PyYAML.

Quick start

from ecocost import estimate

r = estimate(
    "gpt-oss-120b",
    provider="nscale",
    input_tokens=800,
    output_tokens=300,
)
r["carbon"]      # {"unit": "gCO2e", "value": 0.0018, "min": ..., "max": ..., "worst_case": {...},
                 #  "operational": {...}, "embodied": {...}}
r["confidence"]  # {"level": "low", "range_ratio": 16.6, "reasons": ["wue_assumed", ...]}

Model ids are matched through aliases, so provider-specific ids such as accounts/fireworks/models/gpt-oss-120b resolve to the same record. A model that isn't in the knowledge base raises UnknownModelError, which suggests close matches and links to adding it. Ids are matched ignoring case.

Provider ids

Who serves the request is taken, in order, from:

1. provider: one of these ids. An unrecognised id raises UnknownProviderError, so a typo can't silently estimate the wrong site.
2. endpoint (optional): the API URL or host you called. Its host is matched against the hosts below; an unlisted host is ignored.
3. For a closed model, its vendor's own API (claude-* → anthropic, gpt-* → openai, …), flagged provider_inferred_from_model.
4. Otherwise wide US defaults, flagged provider_unknown.

To add a provider, see CONTRIBUTING.md.

If you know where the request ran, pass region, a grid id from ecocost/data/regions.yaml (US-VA, US-CA, GB, FR, SG, IN, …). It replaces the provider's region, including one implied by endpoint; the provider still sets PUE, water use and hardware. An unrecognised id raises UnknownRegionError.

API

One function:

estimate(model, *, provider=None, endpoint=None, region=None, input_tokens=0, output_tokens=0, cached_input_tokens=0) -> EstimateResult

Full parameters, every output field, reason codes, errors and fallbacks, and versioning: API.md.

Output

model, provider, method_version, tokens
carbon          gCO2e: value, min, max, worst_case {min, max}; operational, embodied
energy          Wh at the meter; chips, chip_energy_vs_h100, serving_overhead, pue
primary_energy  MJ of raw energy behind that electricity
water           mL consumed: data_center (cooling, with its wue), power_plant (generating the electricity)
compute         H100-seconds of work; method, active_params_billion, decode_utilization
confidence      level, range_ratio (max/min), reasons (every assumed input)
grid            region, country, carbon_intensity (range), largest_source, mix, data_year
provenance      trust, status, generated_by, stale for model, provider, region, hardware

min/max is the likely range; worst_case puts every input at its extreme at once. Cache results against method_version.

How it works

tokens ─▶ FLOPs ─▶ H100-seconds ─▶ Wh at the meter ─▶ gCO2e operational + gCO2e embodied
                                                    ─▶ mL water at the data centre + power plant

Location-based, lifecycle grid intensity, embodied carbon included, usage only. See METHODOLOGY.md for the pipeline, the sources behind every default, how ranges and confidence are computed, calibration against published measurements, and the known gaps.

Confidence

Every input carries an evidence tier: 1 published by the primary source, 2 derived or proxy, 3 assumed. The confidence label is computed from the width of the likely carbon range (under 2x high, under 5x medium, otherwise low), never typed in. reasons lists each assumed input, so it doubles as the list of figures a provider could publish to tighten its estimates.

Data

Every value has a source, a tier and an OKF v0.2 provenance block. To correct or add a figure, see CONTRIBUTING.md.

Development

poetry install
poetry run pytest -q

License

Code: Apache-2.0. The data draws on Ember and Our World in Data (CC BY 4.0), EPA eGRID, WRI, EcoLogits (MPL-2.0) and ML.ENERGY, among others; see NOTICE for attribution and each source's terms.