ecocost

ecocost calculates the carbon emissions, energy use and water use of each AI inference request.

pip install ecocost

Maintained by Gooey.AI. Learn more at gooey.ai/ecocost. Read how the estimates are made in METHODOLOGY.md.

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. The exception is a model listed as a proxy of a related record: it is estimated from that record and flagged, with a wider range and low confidence. 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.

id	provider	API hosts
fireworks	Fireworks AI	api.fireworks.ai
nscale	nScale	inference.api.nscale.com
openai	OpenAI (direct API)	api.openai.com
anthropic	Anthropic (direct API)	api.anthropic.com
google-vertex	Google Vertex AI (us-central1)	aiplatform.googleapis.com
vercel-gateway	Vercel AI Gateway	ai-gateway.vercel.sh
mistral	Mistral AI (La Plateforme)	api.mistral.ai
alibaba-sg	Alibaba Cloud Model Studio (Singapore)	.ap-southeast-1.maas.aliyuncs.com
modal	Modal	.modal.run
zai	Z.ai (Zhipu)	api.z.ai
sarvam	Sarvam AI (Yotta NM1, Navi Mumbai)	api.sarvam.ai
fal	fal.ai	—
novita	Novita AI	api.novita.ai
meta	Meta AI API	api.meta.ai
dhenu	KissanAI Dhenu	apibeta.dhenu.ai
sea-lion	AI Singapore SEA-LION API	api.sea-lion.ai
unknown-us	Unknown provider (US default)	—

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

File	What
ecocost/data/models.yaml	active and total parameters, measured energy, aliases
ecocost/data/providers.yaml	serving regions and chips (with candidates), PUE, WUE, utilization, overhead
ecocost/data/regions.yaml	grid intensity (lifecycle), mix, generation water, primary energy
ecocost/data/hardware.yaml	TDP, peak FLOPS, energy ratio vs H100, embodied carbon
ecocost/data/sources.yaml	every cited source, with its licence and terms of use

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.