Skip to main content

ecocost

PyPI Python License

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.

Eco-cost labeling architecture: source data, curation and contributions, the open source estimation engine, the API contract, and product interfaces

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.

Metadata

Release files for ecocost 0.2.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ecocost 0.2.9
File Size Uploaded Provenance Actions
ecocost-0.2.9.tar.gz 62.7 kB With provenance Details for ecocost-0.2.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ecocost 0.2.9
File Interpreter ABI Platform Actions
ecocost-0.2.9-py3-none-any.whl Python 3 none any Details for ecocost-0.2.9-py3-none-any.whl

Total release size: 129.3 kB

Release files / ecocost-0.2.9.tar.gz

Download URL ecocost-0.2.9.tar.gz
Size 62.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1485533d9637e08f3293193f8429a49ffb55e8f772c63010944175c334bba6ae
BLAKE2b-256 checksum
How to use checksums
458c65375e636973a36e69a4faa28880d1b8b744a65447d71ee2eb4db303e639
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / ecocost-0.2.9-py3-none-any.whl

Download URL ecocost-0.2.9-py3-none-any.whl
Size 66.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
826e6f44acee38a34af924f810ed32d8019ffd874e57a45de3852172f7eb920f
BLAKE2b-256 checksum
How to use checksums
a9cd013b35f7b50df3e23d3fb6460898470c0911c3b0cbc9181c118e4fcd1075
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for ecocost 0.2.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ecocost-0.2.9.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page