Repository avatar
AI Tools
v3.3.1
active

saef

io.github.guillermollopis/saef

Estimate carbon, energy and water of AI inference by model class and cloud region (SAEF).

Documentation

SOMA AI Emission Factors (SAEF)

DOI arXiv License: CC BY 4.0

SOMA AI Emission Factors (SAEF) is an open, versioned dataset of estimated carbon and water factors for AI inference, by model class and by region, built for Scope 3 Category 1 reporting under the GHG Protocol and CSRD. It covers 210 countries and economies, 27 US eGRID subregions and 143 AWS, Azure and Google Cloud regions. Every factor traces to a file and a source, and the calculator returns the file, line and column behind each number. Published by SOMA AI, Barcelona, under CC BY 4.0. The method paper (arXiv 2606.10660) is accepted for publication in Sustainable Production and Consumption.

This repository holds the v3.1.0 tables (lifecycle boundary, dataset date 2026-10-02, version DOI 10.5281/zenodo.24160409; v3.1.0 is a corrective release of v3.0.0 that maps Azure canadaeast and Google Cloud northamerica-northeast1 to the Quebec grid and replaces the Central African Republic's rounded-to-zero grid row, see the release notes) and the source of the saef Python package. The complete deposit, with the reference calculator, the generator scripts and the supplementary documents, is on Zenodo.

How can I measure the environmental impact of the AI I use?

AI that runs on hardware you control can be metered, with a power meter or with tools such as CodeCarbon that read hardware energy counters. AI you buy as a service (ChatGPT, Copilot, Claude, Gemini, API calls to a provider) cannot be metered by the customer, because providers do not publish energy for the requests you send. It can only be estimated from usage (tokens, messages or spend), an energy factor for the model size and the grid where it runs. That estimate is what SAEF is for.

Your AI useFitsWhat you get
Training or inference on your own GPUsCodeCarbon, Green AlgorithmsEstimated energy and emissions of your own hardware
API calls made from your codesaef (this package, LiteLLM and LangChain SaefMiddleware integrations) or EcoLogitsPer-call estimates
ChatGPT, Copilot or Claude seats across a companySAEF factors applied to seats x messages, or the free SOMA AI calculator (also as a Hugging Face Space)An organisation-wide estimate for Scope 3 category 1
Cloud infrastructure you rentYour cloud provider's carbon dashboardEmissions of your cloud account

Full answer with a worked 250-seat Copilot example and published per-query figures: How can I measure the environmental impact of the AI I use? (Spanish: ¿Cómo puedo medir el impacto ambiental de la IA que uso?). All SAEF figures are estimates, not measurements.

Questions this dataset answers

How can I estimate the carbon footprint of the AI tools my company uses (ChatGPT, Copilot, Claude)?

Count usage per tool, such as seats, messages or tokens, and multiply by a per-query or per-token factor for the model class and the grid region. SAEF (SOMA AI Emission Factors) publishes those factors, and the free SOMA AI calculator applies them to company seats. The result is an estimate with a range, not a meter reading.

How do I calculate CO2e from LLM API token usage?

Divide billed tokens by one million and multiply by the SAEF factor F (kg CO2e per million tokens) for the model class and region: kg CO2e = T_billed / 1e6 x F. This one-line form assumes the dataset's default mix of input and output tokens and gives no cache credit. For a different mix, use the full form on the formula page. For a mid-size model, F is 0.00714 kg per million tokens in EU North (Sweden) and 0.0261 kg in US East (N. Virginia).

Which tool fits which kind of AI use?

CodeCarbon or Green Algorithms fit your own GPUs. EcoLogits or the saef package fit API calls made from code. The SOMA AI calculator or SAEF factors fit company seats. Your cloud provider's carbon dashboard fits infrastructure you rent.

Where does purchased AI go in a GHG inventory?

Under Scope 3 category 1 (purchased goods and services). Label the figure as an estimate, show a low-to-high band, and name the factor version used, for example SAEF v3.1.0.

Can the energy use of a provider's AI be measured directly?

No. Providers do not publish per-customer energy for the requests you send, so a customer can only estimate it from usage, model size and grid. SAEF is an estimation dataset built on published benchmarks, and its figures are not measurements.

How much electricity does one AI prompt use?

SAEF estimates 0.03 to 0.37 Wh at facility level for a 1,210-token chat exchange, from a small (class A) to a large (class C) model, and 0.099 Wh for a mid-size (class B) model. Published figures for comparison are 0.24 Wh for the median Gemini Apps text prompt (Google, August 2025) and about 0.3 Wh for a GPT-4o query (Epoch AI). Long documents, coding agents and reasoning modes process far more tokens and use far more.

How much water does ChatGPT or another AI chatbot use per prompt?

SAEF estimates 0.15 to 0.94 mL for a mid-size chat exchange, depending on the cloud region, because the region changes the water, not the watt-hours. Google reports 0.26 mL for its median Gemini Apps text prompt. The viral bottle-of-water-per-email figure (about 519 mL, Washington Post and UC Riverside, 2024) counted the water behind the electricity with mid-2024 assumptions. Details on the water page.

How do I measure the carbon footprint of my own AI use, as one person?

Count your messages, pick a model class and apply the grid of the region. With a mid-size model, a reasoning uplift and a US East grid, 20 chat messages a day for a year come to about 0.4 kg CO2e (band 0.2 to 1 kg), and about 0.1 kg on a Swedish grid. Coding agents, long documents and image or video generation add much more per request. A step-by-step answer is on How can I measure the environmental impact of the AI I use?

Which AI model has the lowest footprint?

Model size class and serving region decide most of the estimate, more than the brand. Smaller models and low-carbon grids give the lowest carbon per exchange, but low-carbon grids are not always the lowest-water ones. Per-model estimates are on the models compared page.

Cite the dataset as 10.5281/zenodo.20443585.

Install

pip install saef
import saef

saef.model_class_for("gpt-4o")                                   # B
r = saef.estimate(tokens=1_000_000, model="gpt-4o-mini", region="eu-west-1")
r.kg_co2e, r.kg_co2e_high_case, r.water_ml                      # estimates, with provenance in r.provenance
saef estimate --tokens 1000000 --model gpt-4o-mini --region eu-west-1

The package bundles the nine CSV files below and has no dependencies. It is built from this repository with python scripts/sync_data.py && python -m build.

Integrations

The core package has no dependencies. The integrations below estimate carbon and water for each call from the token usage your framework already reports. The region comes from the region argument, then from the SAEF_REGION environment variable, then falls back to the global average. All of them keep running totals and can append one JSON line per call with log_path=.

LiteLLM, installed with pip install "saef[litellm]". The estimate is also attached to response._hidden_params["saef"].

import time
import litellm
from saef.integrations.litellm import SaefLogger

logger = SaefLogger(region="eu-west-1")
litellm.callbacks = [logger]
resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], mock_response="Hi there")
time.sleep(1)  # LiteLLM runs success callbacks in a background thread
t = logger.totals()
print(t["calls"], t["input_tokens"], t["output_tokens"])
print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
1 10 20
3.905e-07 kg CO2e, 6.250e-07 high case, 0.0018 mL

LangChain, installed with pip install "saef[langchain]". This example uses a fake chat model so it runs offline. With a real model you pass the same handler in callbacks.

from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
from langchain_core.messages import AIMessage
from saef.integrations.langchain import SaefCallbackHandler

handler = SaefCallbackHandler(region="eu-west-1")
reply = AIMessage(
    content="Hi there",
    response_metadata={"model_name": "gpt-4o"},
    usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
)
llm = GenericFakeChatModel(messages=iter([reply]))
llm.invoke("Hello", config={"callbacks": [handler]})
t = handler.totals()
print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
1 400 800 300
2.894e-05 kg CO2e, 4.433e-05 high case

LangChain v1 agents can use middleware instead of a callback. SaefMiddleware hooks wrap_model_call and awrap_model_call, records one estimate per model call, and with attach=True also writes the estimate to AIMessage.response_metadata["saef"]. It needs the langchain package, which the langchain extra installs. The example again uses a fake chat model.

from langchain.agents import create_agent
from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
from langchain_core.messages import AIMessage
from saef.integrations.langchain import SaefMiddleware

reply = AIMessage(
    content="Hi there",
    response_metadata={"model_name": "gpt-4o"},
    usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
)
llm = GenericFakeChatModel(messages=iter([reply]))
mw = SaefMiddleware(region="eu-west-1", attach=True)
agent = create_agent(llm, tools=[], middleware=[mw])
out = agent.invoke({"messages": [("user", "Hello")]})
t = mw.totals()
print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
print(out["messages"][-1].response_metadata["saef"]["kg_co2e"])
1 400 800 300
2.894e-05 kg CO2e, 4.433e-05 high case
2.894105237117252e-05

Response objects, with no extra install and no SDK import. estimate_from_response reads OpenAI Chat Completions, OpenAI Responses and Anthropic Messages objects, or the same shapes as dicts. Cache reads get the cache credit and cache writes count as ordinary input.

from types import SimpleNamespace
from saef.integrations.openai import estimate_from_response

resp = SimpleNamespace(
    type="message", model="claude-sonnet-4-5",
    usage=SimpleNamespace(input_tokens=200, output_tokens=150, cache_read_input_tokens=1800, cache_creation_input_tokens=0),
)
e = estimate_from_response(resp, region="eu-west-1")
print(e.model_class, f"{e.kg_co2e:.3e}", f"{e.kg_co2e_high_case:.3e}", f"{e.water_ml:.4f}")
B 2.231e-05 3.235e-05 0.0785

Every figure is an estimate. Models the dataset treats as out of scope, such as embeddings, are skipped and counted in totals()["skipped_calls"].

Example notebooks: examples/quickstart.ipynb, and a runnable copy on Kaggle, Estimate the carbon footprint of your LLM API calls.

MCP server

SAEF ships an MCP server so an AI agent can estimate the carbon, energy and water of AI usage on request. It runs locally over stdio and needs the optional mcp extra. The core package stays dependency-free.

pip install "saef[mcp]"

Claude Code.

claude mcp add saef -- saef-mcp

Claude Desktop, in claude_desktop_config.json.

{
  "mcpServers": {
    "saef": { "command": "saef-mcp" }
  }
}

Cursor, in .cursor/mcp.json.

{
  "mcpServers": {
    "saef": { "command": "saef-mcp" }
  }
}

If saef-mcp is not on your PATH, use uvx --from "saef[mcp]" saef-mcp as the command instead.

Tools.

  • estimate_footprint(tokens, model, region="global") returns carbon in kg and g CO2e with a central and a high case, facility energy in Wh, water in mL where the region has a water factor, the model class, the region used, the dataset version and a provenance trail.
  • estimate_chat_usage(messages, model, region="global") returns the same for chat exchanges, using the dataset's short-chat default of 1,210 tokens per exchange (928 input, 282 output).
  • model_class(model) returns the class letter (A small, B mid-size, C large) and a description.
  • list_regions() returns the accepted region codes, with names for cloud regions and countries.
  • compare_regions(tokens, model, regions) returns carbon and water per region, sorted from lowest to highest carbon.

The server also exposes the resource saef://about with the licence, DOI and method paper. Every figure is an estimate, not a measurement.

Example prompt, "Using SAEF, what is the carbon and water footprint of 2 million gpt-4o tokens a month in eu-north-1 compared with us-east-1?"

Files

FileRowsWhat it contains
cloud_region_factors.csv143Class A, B and C factors for each AWS, Azure and Google Cloud region, resolved to a grid, with the confidence of the region mapping
grid_intensity_all.csv240Grid carbon intensity (kg CO2e per kWh) for 210 countries and economies, 27 US eGRID subregions, EU-27, the world average and one subnational row, with the class factors at each grid
factors_v3_lifecycle.csv102Class factors by class, GPU (H100 central, B200 sensitivity) and printed region, with the energy and the four terms
model_factors.csv32Factors for the 18 measured open-weight models on H100 and B200, from the ML.ENERGY Leaderboard v3
model_class_mapping.csv187Identifier patterns, including AWS Bedrock, Azure and Vertex AI spellings, mapped to class A, B or C, plus the class C default for unmapped names
region_water_factors.csv17On-site and off-site water factors under both hydropower conventions, with AWARE 2.0 scarcity weighting
region_grid_crosswalk.csv17Printed region ids mapped to grids
token_basis_constants.csv7Weights that convert billed tokens to effective tokens
reserved_capacity_factors.csv3Factors per accelerator-hour for provisioned capacity
src/saef/n/aThe Python package: a standard-library calculator over these files

Three model classes are used: A (small, about 8B to 30B), B (standard, about 70B) and C (frontier). Every closed commercial model is class-only, assigned by the provider's pricing tier, and must be disclosed as an assumption.

Method

An estimate has four terms. Electricity, embodied hardware and data-centre construction are charged on effective tokens. Amortised training is charged on billed tokens.

kg CO2e = T_eff / 1e6 x inference footprint  +  T_billed / 1e6 x training term
T_eff   = (T_out + 0.30 x T_in_uncached + 0.05 x T_in_cached) / 1.339

Never multiply a billed token count by an inference footprint. At the default mix that overstates the result by about 3.1 times. Where only a billed total is known, use the default-mix factor per billed token, which already carries the conversion (0.302465 effective tokens per billed token at an 85% input share with no cache credit).

  • An unmapped identifier is assigned class C and flagged. Embeddings, image, audio, video and fine-tuning jobs are out of scope.
  • Unknown or global regions use the global-average grid. Water has no fallback, and covers 17 regions only.
  • Each result carries a conservative high case. A development line is reported separately and never added to a total.
  • Six significant figures are arithmetic, not evidence. The inputs support about two. Report the central value with the high case.

The numbers are estimates, not measurements.

Citation

@misc{llopis2026somafactors,
  author       = {Llopis-Garcia, Guillermo},
  title        = {{SOMA AI Emission Factors (SAEF)}},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {v3.1.0},
  doi          = {10.5281/zenodo.20443585},
  url          = {https://doi.org/10.5281/zenodo.20443585}
}

@misc{llopis2026accounting,
  author        = {Llopis-Garcia, Guillermo},
  title         = {Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories: A Token-Based Method},
  year          = {2026},
  eprint        = {2606.10660},
  archivePrefix = {arXiv},
  note          = {Accepted for publication in Sustainable Production and Consumption (Elsevier)}
}

Pin a dataset in an inventory by the version DOI. The concept DOI always resolves to the latest version.

Links

License

The data is licensed under CC BY 4.0, see LICENSE. Attribution: Llopis-Garcia, G. (2026), SOMA AI Emission Factors (SAEF), https://doi.org/10.5281/zenodo.20443585. The Python package code in src/ is licensed under MIT, see LICENSE-CODE.

PYPI
saef
Install Command
pip install saef
Runtime: uvx