saef 3.0.0__tar.gz → 3.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. {saef-3.0.0 → saef-3.2.0}/PKG-INFO +107 -4
  2. saef-3.2.0/PYPI_README.md +183 -0
  3. {saef-3.0.0 → saef-3.2.0}/cloud_region_factors.csv +2 -2
  4. {saef-3.0.0 → saef-3.2.0}/grid_intensity_all.csv +1 -1
  5. {saef-3.0.0 → saef-3.2.0}/pyproject.toml +4 -2
  6. {saef-3.0.0 → saef-3.2.0}/src/saef/__init__.py +1 -1
  7. {saef-3.0.0 → saef-3.2.0}/src/saef/_core.py +2 -2
  8. {saef-3.0.0 → saef-3.2.0}/src/saef/data/cloud_region_factors.csv +2 -2
  9. {saef-3.0.0 → saef-3.2.0}/src/saef/data/grid_intensity_all.csv +1 -1
  10. saef-3.2.0/src/saef/integrations/__init__.py +1 -0
  11. saef-3.2.0/src/saef/integrations/_base.py +100 -0
  12. saef-3.2.0/src/saef/integrations/langchain.py +185 -0
  13. saef-3.2.0/src/saef/integrations/litellm.py +74 -0
  14. saef-3.2.0/src/saef/integrations/openai.py +54 -0
  15. saef-3.2.0/tests/test_integrations.py +251 -0
  16. {saef-3.0.0 → saef-3.2.0}/tests/test_saef.py +2 -2
  17. saef-3.0.0/PYPI_README.md +0 -84
  18. {saef-3.0.0 → saef-3.2.0}/.gitignore +0 -0
  19. {saef-3.0.0 → saef-3.2.0}/LICENSE +0 -0
  20. {saef-3.0.0 → saef-3.2.0}/LICENSE-CODE +0 -0
  21. {saef-3.0.0 → saef-3.2.0}/factors_v3_lifecycle.csv +0 -0
  22. {saef-3.0.0 → saef-3.2.0}/model_class_mapping.csv +0 -0
  23. {saef-3.0.0 → saef-3.2.0}/model_factors.csv +0 -0
  24. {saef-3.0.0 → saef-3.2.0}/region_grid_crosswalk.csv +0 -0
  25. {saef-3.0.0 → saef-3.2.0}/region_water_factors.csv +0 -0
  26. {saef-3.0.0 → saef-3.2.0}/reserved_capacity_factors.csv +0 -0
  27. {saef-3.0.0 → saef-3.2.0}/scripts/sync_data.py +0 -0
  28. {saef-3.0.0 → saef-3.2.0}/src/saef/__main__.py +0 -0
  29. {saef-3.0.0 → saef-3.2.0}/src/saef/_calc.py +0 -0
  30. {saef-3.0.0 → saef-3.2.0}/src/saef/cli.py +0 -0
  31. {saef-3.0.0 → saef-3.2.0}/src/saef/data/factors_v3_lifecycle.csv +0 -0
  32. {saef-3.0.0 → saef-3.2.0}/src/saef/data/model_class_mapping.csv +0 -0
  33. {saef-3.0.0 → saef-3.2.0}/src/saef/data/model_factors.csv +0 -0
  34. {saef-3.0.0 → saef-3.2.0}/src/saef/data/region_grid_crosswalk.csv +0 -0
  35. {saef-3.0.0 → saef-3.2.0}/src/saef/data/region_water_factors.csv +0 -0
  36. {saef-3.0.0 → saef-3.2.0}/src/saef/data/reserved_capacity_factors.csv +0 -0
  37. {saef-3.0.0 → saef-3.2.0}/src/saef/data/token_basis_constants.csv +0 -0
  38. {saef-3.0.0 → saef-3.2.0}/token_basis_constants.csv +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: saef
3
- Version: 3.0.0
3
+ Version: 3.2.0
4
4
  Summary: SOMA AI Emission Factors: estimated carbon and water factors for AI inference, per million tokens
5
5
  Project-URL: Homepage, https://somaai.earth/ai-footprint
6
6
  Project-URL: Documentation, https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
@@ -23,6 +23,10 @@ Classifier: Programming Language :: Python :: 3.12
23
23
  Classifier: Programming Language :: Python :: 3.13
24
24
  Classifier: Topic :: Scientific/Engineering
25
25
  Requires-Python: >=3.9
26
+ Provides-Extra: langchain
27
+ Requires-Dist: langchain>=1.0; extra == 'langchain'
28
+ Provides-Extra: litellm
29
+ Requires-Dist: litellm; extra == 'litellm'
26
30
  Provides-Extra: pandas
27
31
  Requires-Dist: pandas; extra == 'pandas'
28
32
  Provides-Extra: test
@@ -41,7 +45,7 @@ Every number comes with the file, column and row it was read from, so you can tr
41
45
  pip install saef
42
46
  ```
43
47
 
44
- For pandas users, `pip install "saef[pandas]"` adds the optional extra.
48
+ For pandas users, `pip install "saef[pandas]"` adds the optional extra. The framework integrations below use `saef[litellm]` and `saef[langchain]`.
45
49
 
46
50
  ## Example
47
51
 
@@ -56,7 +60,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
56
60
  print(r.water_ml) # mL, or None where the region has no water factor
57
61
  for s in r.provenance[:3]:
58
62
  print(s["file"], s["line"], s["column"]) # the file, line and column behind each number
59
- print(len(saef.regions()), saef.__version__) # 143 cloud regions, 3.0.0
63
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.2.0, 3.1.0
60
64
  print(saef.citation())
61
65
  ```
62
66
 
@@ -70,6 +74,105 @@ saef regions --provider aws
70
74
  saef cite
71
75
  ```
72
76
 
77
+ ## Integrations
78
+
79
+ 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=`.
80
+
81
+ LiteLLM, installed with `pip install "saef[litellm]"`. The estimate is also attached to `response._hidden_params["saef"]`.
82
+
83
+ ```python
84
+ import time
85
+ import litellm
86
+ from saef.integrations.litellm import SaefLogger
87
+
88
+ logger = SaefLogger(region="eu-west-1")
89
+ litellm.callbacks = [logger]
90
+ resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], mock_response="Hi there")
91
+ time.sleep(1) # LiteLLM runs success callbacks in a background thread
92
+ t = logger.totals()
93
+ print(t["calls"], t["input_tokens"], t["output_tokens"])
94
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
95
+ ```
96
+
97
+ ```text
98
+ 1 10 20
99
+ 3.905e-07 kg CO2e, 6.250e-07 high case, 0.0018 mL
100
+ ```
101
+
102
+ 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`.
103
+
104
+ ```python
105
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
106
+ from langchain_core.messages import AIMessage
107
+ from saef.integrations.langchain import SaefCallbackHandler
108
+
109
+ handler = SaefCallbackHandler(region="eu-west-1")
110
+ reply = AIMessage(
111
+ content="Hi there",
112
+ response_metadata={"model_name": "gpt-4o"},
113
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
114
+ )
115
+ llm = GenericFakeChatModel(messages=iter([reply]))
116
+ llm.invoke("Hello", config={"callbacks": [handler]})
117
+ t = handler.totals()
118
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
119
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
120
+ ```
121
+
122
+ ```text
123
+ 1 400 800 300
124
+ 2.894e-05 kg CO2e, 4.433e-05 high case
125
+ ```
126
+
127
+ 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.
128
+
129
+ ```python
130
+ from langchain.agents import create_agent
131
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
132
+ from langchain_core.messages import AIMessage
133
+ from saef.integrations.langchain import SaefMiddleware
134
+
135
+ reply = AIMessage(
136
+ content="Hi there",
137
+ response_metadata={"model_name": "gpt-4o"},
138
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
139
+ )
140
+ llm = GenericFakeChatModel(messages=iter([reply]))
141
+ mw = SaefMiddleware(region="eu-west-1", attach=True)
142
+ agent = create_agent(llm, tools=[], middleware=[mw])
143
+ out = agent.invoke({"messages": [("user", "Hello")]})
144
+ t = mw.totals()
145
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
146
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
147
+ print(out["messages"][-1].response_metadata["saef"]["kg_co2e"])
148
+ ```
149
+
150
+ ```text
151
+ 1 400 800 300
152
+ 2.894e-05 kg CO2e, 4.433e-05 high case
153
+ 2.894105237117252e-05
154
+ ```
155
+
156
+ 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.
157
+
158
+ ```python
159
+ from types import SimpleNamespace
160
+ from saef.integrations.openai import estimate_from_response
161
+
162
+ resp = SimpleNamespace(
163
+ type="message", model="claude-sonnet-4-5",
164
+ usage=SimpleNamespace(input_tokens=200, output_tokens=150, cache_read_input_tokens=1800, cache_creation_input_tokens=0),
165
+ )
166
+ e = estimate_from_response(resp, region="eu-west-1")
167
+ print(e.model_class, f"{e.kg_co2e:.3e}", f"{e.kg_co2e_high_case:.3e}", f"{e.water_ml:.4f}")
168
+ ```
169
+
170
+ ```text
171
+ B 2.231e-05 3.235e-05 0.0785
172
+ ```
173
+
174
+ Every figure is an estimate. Models the dataset treats as out of scope, such as embeddings, are skipped and counted in `totals()["skipped_calls"]`.
175
+
73
176
  ## What the numbers are
74
177
 
75
178
  The factors follow the v3 lifecycle boundary. An estimate has four terms: electricity, embodied hardware and data-centre construction (charged on effective tokens) and amortised training (charged on billed tokens).
@@ -85,7 +188,7 @@ The factors follow the v3 lifecycle boundary. An estimate has four terms: electr
85
188
 
86
189
  These figures are modelled estimates built from published benchmarks, grid averages and lifecycle studies. They are not measurements of any provider's infrastructure. The tables carry six significant figures as arithmetic, but the inputs support about two. Report the central value with the high case, and read the methodology before quoting them.
87
190
 
88
- This package bundles the SAEF v3.0.0 tables (dataset date 2026-10-02) and covers the H100 central case. Reserved accelerator-hour factors, the B200 sensitivity and the Tier 2b seat-based estimates in the full deposit are not exposed by this API.
191
+ This package bundles the SAEF v3.1.0 tables (dataset date 2026-10-02, a corrective release of v3.0.0) and covers the H100 central case. Reserved accelerator-hour factors, the B200 sensitivity and the Tier 2b seat-based estimates in the full deposit are not exposed by this API.
89
192
 
90
193
  ## Licence
91
194
 
@@ -0,0 +1,183 @@
1
+ # saef
2
+
3
+ Python access to SAEF, the SOMA AI Emission Factors. SAEF is an open, versioned dataset of estimated carbon and water factors for AI inference, by model class and region, built for Scope 3 Category 1 reporting under the GHG Protocol and CSRD. This package bundles the CSV files and gives you a small API and command line on top of them. It has no dependencies beyond the standard library.
4
+
5
+ Every number comes with the file, column and row it was read from, so you can trace an estimate back to the dataset.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install saef
11
+ ```
12
+
13
+ For pandas users, `pip install "saef[pandas]"` adds the optional extra. The framework integrations below use `saef[litellm]` and `saef[langchain]`.
14
+
15
+ ## Example
16
+
17
+ ```python
18
+ import saef
19
+
20
+ print(saef.model_class_for("gpt-4o")) # B
21
+ print(saef.factor("B", "eu-west-1")["kg_co2e_per_1m_billed_tokens"])
22
+
23
+ r = saef.estimate(tokens=1_000_000, model="gpt-4o-mini", region="eu-west-1")
24
+ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative high case, kg CO2e
25
+ print(r.water_ml) # mL, or None where the region has no water factor
26
+ for s in r.provenance[:3]:
27
+ print(s["file"], s["line"], s["column"]) # the file, line and column behind each number
28
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.2.0, 3.1.0
29
+ print(saef.citation())
30
+ ```
31
+
32
+ Command line:
33
+
34
+ ```bash
35
+ saef estimate --tokens 1000000 --model gpt-4o-mini --region eu-west-1
36
+ saef estimate --output-tokens 2e6 --input-tokens 10e6 --model gpt-4o --provider azure --region swedencentral
37
+ saef factor --model-class B --region us-east-1
38
+ saef regions --provider aws
39
+ saef cite
40
+ ```
41
+
42
+ ## Integrations
43
+
44
+ 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=`.
45
+
46
+ LiteLLM, installed with `pip install "saef[litellm]"`. The estimate is also attached to `response._hidden_params["saef"]`.
47
+
48
+ ```python
49
+ import time
50
+ import litellm
51
+ from saef.integrations.litellm import SaefLogger
52
+
53
+ logger = SaefLogger(region="eu-west-1")
54
+ litellm.callbacks = [logger]
55
+ resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], mock_response="Hi there")
56
+ time.sleep(1) # LiteLLM runs success callbacks in a background thread
57
+ t = logger.totals()
58
+ print(t["calls"], t["input_tokens"], t["output_tokens"])
59
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
60
+ ```
61
+
62
+ ```text
63
+ 1 10 20
64
+ 3.905e-07 kg CO2e, 6.250e-07 high case, 0.0018 mL
65
+ ```
66
+
67
+ 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`.
68
+
69
+ ```python
70
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
71
+ from langchain_core.messages import AIMessage
72
+ from saef.integrations.langchain import SaefCallbackHandler
73
+
74
+ handler = SaefCallbackHandler(region="eu-west-1")
75
+ reply = AIMessage(
76
+ content="Hi there",
77
+ response_metadata={"model_name": "gpt-4o"},
78
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
79
+ )
80
+ llm = GenericFakeChatModel(messages=iter([reply]))
81
+ llm.invoke("Hello", config={"callbacks": [handler]})
82
+ t = handler.totals()
83
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
84
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
85
+ ```
86
+
87
+ ```text
88
+ 1 400 800 300
89
+ 2.894e-05 kg CO2e, 4.433e-05 high case
90
+ ```
91
+
92
+ 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.
93
+
94
+ ```python
95
+ from langchain.agents import create_agent
96
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
97
+ from langchain_core.messages import AIMessage
98
+ from saef.integrations.langchain import SaefMiddleware
99
+
100
+ reply = AIMessage(
101
+ content="Hi there",
102
+ response_metadata={"model_name": "gpt-4o"},
103
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
104
+ )
105
+ llm = GenericFakeChatModel(messages=iter([reply]))
106
+ mw = SaefMiddleware(region="eu-west-1", attach=True)
107
+ agent = create_agent(llm, tools=[], middleware=[mw])
108
+ out = agent.invoke({"messages": [("user", "Hello")]})
109
+ t = mw.totals()
110
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
111
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
112
+ print(out["messages"][-1].response_metadata["saef"]["kg_co2e"])
113
+ ```
114
+
115
+ ```text
116
+ 1 400 800 300
117
+ 2.894e-05 kg CO2e, 4.433e-05 high case
118
+ 2.894105237117252e-05
119
+ ```
120
+
121
+ 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.
122
+
123
+ ```python
124
+ from types import SimpleNamespace
125
+ from saef.integrations.openai import estimate_from_response
126
+
127
+ resp = SimpleNamespace(
128
+ type="message", model="claude-sonnet-4-5",
129
+ usage=SimpleNamespace(input_tokens=200, output_tokens=150, cache_read_input_tokens=1800, cache_creation_input_tokens=0),
130
+ )
131
+ e = estimate_from_response(resp, region="eu-west-1")
132
+ print(e.model_class, f"{e.kg_co2e:.3e}", f"{e.kg_co2e_high_case:.3e}", f"{e.water_ml:.4f}")
133
+ ```
134
+
135
+ ```text
136
+ B 2.231e-05 3.235e-05 0.0785
137
+ ```
138
+
139
+ Every figure is an estimate. Models the dataset treats as out of scope, such as embeddings, are skipped and counted in `totals()["skipped_calls"]`.
140
+
141
+ ## What the numbers are
142
+
143
+ The factors follow the v3 lifecycle boundary. An estimate has four terms: electricity, embodied hardware and data-centre construction (charged on effective tokens) and amortised training (charged on billed tokens).
144
+
145
+ - Effective tokens are output tokens plus weighted input tokens, divided by a reference-mix normaliser. Pass `tokens` for a billed total, which applies the default input share of 85% and no cache credit. Pass `output_tokens`, `input_tokens` and `cached_input_tokens` when your billing export gives the split.
146
+ - Never multiply a billed token count by a per-effective-token footprint yourself. Use `estimate`, or the `kg_co2e_per_1m_billed_tokens` value from `factor`.
147
+ - A model maps to class A, B or C through 187 identifier patterns, including AWS Bedrock, Azure and Vertex AI spellings. Closed models are class proxies by pricing tier, and the result says so in `warnings`. An unmapped identifier is assigned the conservative class C and flagged. Embeddings, image, audio and video models are out of scope and raise an error.
148
+ - `region` can be a cloud region id (143 AWS, Azure and Google Cloud regions), an ISO-3 country code (210 countries and economies), a US eGRID subregion, `eu-27`, or `None` for the global average. A region that matches nothing raises `saef.SaefError` with suggestions.
149
+ - Water covers 17 regions, under two hydropower conventions (`water_ml` and `water_ml_excl_hydro`). Elsewhere `water_ml` is `None`, by design.
150
+ - `kg_co2e_high_case` is a conservative bound. The development line is reported separately and is never added to `kg_co2e`.
151
+
152
+ ## Estimates, not measurements
153
+
154
+ These figures are modelled estimates built from published benchmarks, grid averages and lifecycle studies. They are not measurements of any provider's infrastructure. The tables carry six significant figures as arithmetic, but the inputs support about two. Report the central value with the high case, and read the methodology before quoting them.
155
+
156
+ This package bundles the SAEF v3.1.0 tables (dataset date 2026-10-02, a corrective release of v3.0.0) and covers the H100 central case. Reserved accelerator-hour factors, the B200 sensitivity and the Tier 2b seat-based estimates in the full deposit are not exposed by this API.
157
+
158
+ ## Licence
159
+
160
+ The dataset is licensed under CC BY 4.0. The Python code is licensed under MIT. Attribution for the data is required, see the citation below.
161
+
162
+ ## Citation
163
+
164
+ Dataset (concept DOI, always the latest version): https://doi.org/10.5281/zenodo.20443585
165
+
166
+ ```bibtex
167
+ @misc{llopis2026somafactors,
168
+ author = {Llopis-Garcia, Guillermo},
169
+ title = {{SOMA AI Emission Factors (SAEF)}},
170
+ year = {2026},
171
+ publisher = {Zenodo},
172
+ doi = {10.5281/zenodo.20443585}
173
+ }
174
+ ```
175
+
176
+ Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories, a Token-Based Method. arXiv 2606.10660, accepted for publication in Sustainable Production and Consumption.
177
+
178
+ ## Links
179
+
180
+ - Homepage: https://somaai.earth/ai-footprint
181
+ - Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
182
+ - Repository: https://github.com/guillermollopis/soma-ai-emission-factors
183
+ - Paper: https://arxiv.org/abs/2606.10660
@@ -45,7 +45,7 @@ azure,belgiumcentral,Belgium Central,Brussels,BEL,BEL,0.1347,"Ember yearly elect
45
45
  azure,brazilsouth,Brazil South,Sao Paulo State,BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
46
46
  azure,brazilsoutheast,Brazil Southeast,Rio,BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,Access restricted by Microsoft to specific customer scenarios (e.g. disaster recovery); listed on the official page but not open to general new subscriptions.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
47
47
  azure,canadacentral,Canada Central,Toronto,CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,Canadian grid intensity varies by province; provider-stated city/province used.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
48
- azure,canadaeast,Canada East,Quebec,CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,Canadian grid intensity varies by province; provider-stated city/province used.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
48
+ azure,canadaeast,Canada East,Quebec,CAN,CAN-QC,0.0265,"Derived: 2023 generation shares (Canada Energy Regulator, Renewable power in Canada: Quebec (page updated 2026-03-25): 'In 2023, Quebec generated 195.5 terawatt-hours (TWh) of electricity, with 194.8 TWh (99.6%) coming from renewable sources' and 'Most generation in 2023 came from hydroelectricity (94.0%), wind (5.0%), and biomass (0.7%)') x Ember 2023 implied Canadian life-cycle factor per fuel, g/kWh: Hydro 0.940 x 23.8; Wind 0.050 x 9.6; Bioenergy 0.007 x 216.3; Gas 0.003 x 721.8 = 26.5 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",high,"Provider states the physical location as Quebec (Microsoft Learn, List of Azure Regions, read 12 November 2026), so the region is in the province of Quebec and the serving grid is Hydro-Quebec. v3.1.0: row now takes the Quebec provincial grid CAN-QC (v4_inputs/subnational_grids.csv) via grid_override, as AWS ca-central-1 already did; v3.0.0 used the Canadian national average.",https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00190674,0.000887014,0.000459429,0.00325319,0.00060411,0.00158808,0.0038573,0.00315017,0.0048871,0.00208228,0.00549121,0.0026001,0.00624409,0.00334385,0.00150451,0.0110925,0.00293425,0.00628932,0.0140267,0.010316,0.0165529,0.00794091,0.0194871,0.00851467,0.0232516,0.0128425,0.00560246,0.0416966,0.0128445,0.0254562,0.0545411,0.0384145,0.0621277,0.0316359,0.0749722,0.0317067
49
49
  azure,centralindia,Central India,Pune,IND,IND,0.7137,"Ember yearly electricity data, CO2 intensity 2023, 713.72 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0513687,0.000887014,0.000459429,0.0527151,0.00060411,0.0165486,0.0533193,0.0848673,0.0866043,0.0267988,0.0872084,0.0700482,0.168219,0.00334385,0.00150451,0.173068,0.00293425,0.0552811,0.176002,0.277919,0.284156,0.0888812,0.28709,0.22939,0.626411,0.0128425,0.00560246,0.644856,0.0128445,0.207891,0.6577,1.03491,1.05862,0.33304,1.07146,0.854197
50
50
  azure,chilecentral,Chile Central,Santiago,CHL,CHL,0.3048,"Ember yearly electricity data, CO2 intensity 2023, 304.83 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0219396,0.000887014,0.000459429,0.023286,0.00060411,0.00764731,0.0238901,0.0362469,0.0379838,0.0120929,0.0385879,0.0299176,0.0718465,0.00334385,0.00150451,0.0766949,0.00293425,0.0261317,0.0796291,0.118699,0.124936,0.040723,0.12787,0.0979725,0.26754,0.0128425,0.00560246,0.285985,0.0128445,0.0993449,0.29883,0.442009,0.465722,0.153709,0.478567,0.364828
51
51
  azure,denmarkeast,Denmark East,Copenhagen,DNK,DNK,0.1523,"Ember yearly electricity data, CO2 intensity 2023, 152.26 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0109586,0.000887014,0.000459429,0.0123051,0.00060411,0.00432596,0.0129092,0.018105,0.0198419,0.00660559,0.020446,0.0149436,0.0358867,0.00334385,0.00150451,0.0407351,0.00293425,0.0152552,0.0436693,0.0592892,0.0655261,0.0227536,0.0684603,0.0489364,0.133634,0.0128425,0.00560246,0.152079,0.0128445,0.058843,0.164924,0.22078,0.244493,0.086795,0.257337,0.182228
@@ -128,7 +128,7 @@ gcp,europe-west12,europe-west12,"Turin, Italy",ITA,ITA,0.3233,"Ember yearly elec
128
128
  gcp,me-central1,me-central1,"Doha, Qatar",QAT,QAT,0.5843,"Ember yearly electricity data, CO2 intensity 2023, 584.25 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0420503,0.000887014,0.000459429,0.0433968,0.00060411,0.0137301,0.0440009,0.0694723,0.0712092,0.0221424,0.0718133,0.0573414,0.137704,0.00334385,0.00150451,0.142552,0.00293425,0.0460513,0.145487,0.227504,0.233741,0.0736325,0.236675,0.187778,0.512779,0.0128425,0.00560246,0.531224,0.0128445,0.173521,0.544068,0.847173,0.870886,0.276257,0.883731,0.699244
129
129
  gcp,me-central2,me-central2,"Dammam, Saudi Arabia",SAU,SAU,0.6973,"Ember yearly electricity data, CO2 intensity 2023, 697.31 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0501876,0.000887014,0.000459429,0.0515341,0.00060411,0.0161913,0.0521382,0.082916,0.084653,0.0262086,0.0852571,0.0684377,0.164352,0.00334385,0.00150451,0.1692,0.00293425,0.0541112,0.172134,0.271529,0.277766,0.0869485,0.2807,0.224116,0.612008,0.0128425,0.00560246,0.630453,0.0128445,0.203534,0.643298,1.01111,1.03483,0.325842,1.04767,0.834557
130
130
  gcp,me-west1,me-west1,"Tel Aviv, Israel",ISR,ISR,0.5588,"Ember yearly electricity data, CO2 intensity 2023, 558.83 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0402208,0.000887014,0.000459429,0.0415672,0.00060411,0.0131767,0.0421713,0.0664496,0.0681865,0.0212281,0.0687906,0.0548465,0.131713,0.00334385,0.00150451,0.136561,0.00293425,0.0442391,0.139495,0.217605,0.223842,0.0706386,0.226776,0.179608,0.490469,0.0128425,0.00560246,0.508914,0.0128445,0.166773,0.521758,0.810314,0.834027,0.265108,0.846871,0.668821
131
- gcp,northamerica-northeast1,northamerica-northeast1,"Montréal, Québec",CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
131
+ gcp,northamerica-northeast1,northamerica-northeast1,"Montréal, Québec",CAN,CAN-QC,0.0265,"Derived: 2023 generation shares (Canada Energy Regulator, Renewable power in Canada: Quebec (page updated 2026-03-25): 'In 2023, Quebec generated 195.5 terawatt-hours (TWh) of electricity, with 194.8 TWh (99.6%) coming from renewable sources' and 'Most generation in 2023 came from hydroelectricity (94.0%), wind (5.0%), and biomass (0.7%)') x Ember 2023 implied Canadian life-cycle factor per fuel, g/kWh: Hydro 0.940 x 23.8; Wind 0.050 x 9.6; Bioenergy 0.007 x 216.3; Gas 0.003 x 721.8 = 26.5 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",high,"Provider states the location as Montreal, Quebec (Google Cloud, Regions and zones, read 12 November 2026), so the serving grid is Hydro-Quebec. v3.1.0: row now takes the Quebec provincial grid CAN-QC (v4_inputs/subnational_grids.csv) via grid_override, as AWS ca-central-1 already did; v3.0.0 used the Canadian national average.",https://cloud.google.com/compute/docs/regions-zones,0.3025,0.00190674,0.000887014,0.000459429,0.00325319,0.00060411,0.00158808,0.0038573,0.00315017,0.0048871,0.00208228,0.00549121,0.0026001,0.00624409,0.00334385,0.00150451,0.0110925,0.00293425,0.00628932,0.0140267,0.010316,0.0165529,0.00794091,0.0194871,0.00851467,0.0232516,0.0128425,0.00560246,0.0416966,0.0128445,0.0254562,0.0545411,0.0384145,0.0621277,0.0316359,0.0749722,0.0317067
132
132
  gcp,northamerica-northeast2,northamerica-northeast2,"Toronto, Ontario",CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
133
133
  gcp,northamerica-south1,northamerica-south1,"Queretaro, Mexico",MEX,MEX,0.4890,"Ember yearly electricity data, CO2 intensity 2023, 489.05 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0351985,0.000887014,0.000459429,0.0365449,0.00060411,0.0116577,0.037149,0.0581522,0.0598891,0.0187184,0.0604932,0.0479979,0.115266,0.00334385,0.00150451,0.120114,0.00293425,0.0392646,0.123049,0.190433,0.19667,0.06242,0.199605,0.157181,0.429225,0.0128425,0.00560246,0.44767,0.0128445,0.148249,0.460514,0.709131,0.732845,0.234504,0.745689,0.585306
134
134
  gcp,southamerica-east1,southamerica-east1,"Osasco, São Paulo, Brazil",BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
@@ -33,7 +33,7 @@ KHM,Cambodia,country,KHM,0.4912,2023,,"Ember yearly electricity data, CO2 intens
33
33
  CMR,Cameroon,country,CMR,0.2244,2023,,"Ember yearly electricity data, CO2 intensity 2023, 224.38 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0161493,0.000887014,0.000459429,0.0174958,0.00060411,0.00589596,0.0180999,0.0266807,0.0284176,0.00919943,0.0290217,0.0220218,0.0528849,0.00334385,0.00150451,0.0577333,0.00293425,0.0203965,0.0606676,0.0873723,0.0936092,0.0312477,0.0965435,0.0721158,0.196932,0.0128425,0.00560246,0.215377,0.0128445,0.0779883,0.228221,0.325355,0.349068,0.118425,0.361913,0.268543
34
34
  CAN,Canada,country,CAN,0.1744,2023,,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
35
35
  CYM,Cayman Islands (the),country,CYM,0.6429,2023,,"Ember yearly electricity data, CO2 intensity 2023, 642.86 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0462687,0.000887014,0.000459429,0.0476151,0.00060411,0.015006,0.0482192,0.0764415,0.0781784,0.0242503,0.0787825,0.0630937,0.151518,0.00334385,0.00150451,0.156366,0.00293425,0.0502295,0.159301,0.250326,0.256563,0.0805355,0.259497,0.206616,0.564219,0.0128425,0.00560246,0.582664,0.0128445,0.18908,0.595509,0.932159,0.955872,0.301962,0.968716,0.76939
36
- CAF,Central African Republic (the),country,CAF,0.0000,2023,,"Ember yearly electricity data, CO2 intensity 2023, 0.0 g/kWh (lifecycle, IPCC AR5)",0.3025,0,0.000887014,0.000459429,0.00134644,0.00060411,0.00101136,0.00195055,0,0.00173693,0.00112947,0.00234104,0,0,0.00334385,0.00150451,0.00484836,0.00293425,0.0044007,0.00778261,0,0.00623689,0.00482068,0.00917114,0,0,0.0128425,0.00560246,0.018445,0.0128445,0.0184235,0.0312895,0,0.0237132,0.0200169,0.0365577,0
36
+ CAF,Central African Republic (the),country,CAF,0.0238,2023,,"Ember yearly electricity data, CO2 intensity 2023 published as 0.0 g/kWh (power-sector emissions round to 0.00 MtCO2 on 0.14 TWh); zero-intensity fallback (v3.1.0): Ember 2023 generation shares x Ember 2023 implied World life-cycle factor per fuel, g/kWh: Hydro 1.000 x 23.8 = 23.8 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",0.3025,0.00171154,0.000887014,0.000459429,0.00305799,0.00060411,0.00152904,0.00366209,0.00282767,0.00456461,0.00198474,0.00516872,0.00233392,0.00560486,0.00334385,0.00150451,0.0104532,0.00293425,0.00609597,0.0133875,0.00925991,0.0154968,0.00762148,0.018431,0.00764299,0.0208712,0.0128425,0.00560246,0.0393162,0.0128445,0.0247363,0.0521607,0.0344818,0.058195,0.0304465,0.0710396,0.0284608
37
37
  TCD,Chad,country,TCD,0.6111,2023,,"Ember yearly electricity data, CO2 intensity 2023, 611.11 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0439835,0.000887014,0.000459429,0.04533,0.00060411,0.0143148,0.0459341,0.0726661,0.0744031,0.0231084,0.0750072,0.0599775,0.144035,0.00334385,0.00150451,0.148883,0.00293425,0.0479661,0.151817,0.237963,0.2442,0.076796,0.247134,0.196411,0.536353,0.0128425,0.00560246,0.554798,0.0128445,0.180651,0.567643,0.88612,0.909834,0.288037,0.922678,0.731391
38
38
  CHL,Chile,country,CHL,0.3048,2023,,"Ember yearly electricity data, CO2 intensity 2023, 304.83 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0219396,0.000887014,0.000459429,0.023286,0.00060411,0.00764731,0.0238901,0.0362469,0.0379838,0.0120929,0.0385879,0.0299176,0.0718465,0.00334385,0.00150451,0.0766949,0.00293425,0.0261317,0.0796291,0.118699,0.124936,0.040723,0.12787,0.0979725,0.26754,0.0128425,0.00560246,0.285985,0.0128445,0.0993449,0.29883,0.442009,0.465722,0.153709,0.478567,0.364828
39
39
  CHN,China,country,CHN,0.5833,2023,,"Ember yearly electricity data, CO2 intensity 2023, 583.25 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0419784,0.000887014,0.000459429,0.0433248,0.00060411,0.0137083,0.0439289,0.0693533,0.0710903,0.0221064,0.0716944,0.0572432,0.137468,0.00334385,0.00150451,0.142317,0.00293425,0.04598,0.145251,0.227114,0.233351,0.0735147,0.236285,0.187457,0.511901,0.0128425,0.00560246,0.530346,0.0128445,0.173255,0.543191,0.845723,0.869436,0.275818,0.882281,0.698047
@@ -28,6 +28,8 @@ dependencies = []
28
28
 
29
29
  [project.optional-dependencies]
30
30
  pandas = ["pandas"]
31
+ litellm = ["litellm"]
32
+ langchain = ["langchain>=1.0"]
31
33
  test = ["pytest"]
32
34
 
33
35
  [project.scripts]
@@ -41,8 +43,8 @@ Dataset = "https://doi.org/10.5281/zenodo.20443585"
41
43
  Paper = "https://arxiv.org/abs/2606.10660"
42
44
 
43
45
  [tool.hatch.version]
44
- path = "src/saef/_core.py"
45
- pattern = 'DATASET_VERSION = "(?P<version>[^"]+)"'
46
+ path = "src/saef/__init__.py"
47
+ pattern = '__version__ = "(?P<version>[^"]+)"'
46
48
 
47
49
  [tool.hatch.build.targets.wheel]
48
50
  packages = ["src/saef"]
@@ -11,7 +11,7 @@ from ._core import (
11
11
  regions,
12
12
  )
13
13
 
14
- __version__ = DATASET_VERSION
14
+ __version__ = "3.2.0"
15
15
 
16
16
  __all__ = [
17
17
  "DATASET_VERSION",
@@ -4,14 +4,14 @@ from typing import Optional
4
4
  from . import _calc
5
5
  from ._calc import SaefError
6
6
 
7
- DATASET_VERSION = "3.0.0"
7
+ DATASET_VERSION = "3.1.0"
8
8
 
9
9
  BIBTEX = """@misc{llopis2026somafactors,
10
10
  author = {Llopis-Garcia, Guillermo},
11
11
  title = {{SOMA AI Emission Factors (SAEF)}},
12
12
  year = {2026},
13
13
  publisher = {Zenodo},
14
- version = {v3.0.0},
14
+ version = {v3.1.0},
15
15
  doi = {10.5281/zenodo.20443585},
16
16
  url = {https://doi.org/10.5281/zenodo.20443585}
17
17
  }
@@ -45,7 +45,7 @@ azure,belgiumcentral,Belgium Central,Brussels,BEL,BEL,0.1347,"Ember yearly elect
45
45
  azure,brazilsouth,Brazil South,Sao Paulo State,BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
46
46
  azure,brazilsoutheast,Brazil Southeast,Rio,BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,Access restricted by Microsoft to specific customer scenarios (e.g. disaster recovery); listed on the official page but not open to general new subscriptions.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
47
47
  azure,canadacentral,Canada Central,Toronto,CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,Canadian grid intensity varies by province; provider-stated city/province used.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
48
- azure,canadaeast,Canada East,Quebec,CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,Canadian grid intensity varies by province; provider-stated city/province used.,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
48
+ azure,canadaeast,Canada East,Quebec,CAN,CAN-QC,0.0265,"Derived: 2023 generation shares (Canada Energy Regulator, Renewable power in Canada: Quebec (page updated 2026-03-25): 'In 2023, Quebec generated 195.5 terawatt-hours (TWh) of electricity, with 194.8 TWh (99.6%) coming from renewable sources' and 'Most generation in 2023 came from hydroelectricity (94.0%), wind (5.0%), and biomass (0.7%)') x Ember 2023 implied Canadian life-cycle factor per fuel, g/kWh: Hydro 0.940 x 23.8; Wind 0.050 x 9.6; Bioenergy 0.007 x 216.3; Gas 0.003 x 721.8 = 26.5 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",high,"Provider states the physical location as Quebec (Microsoft Learn, List of Azure Regions, read 12 November 2026), so the region is in the province of Quebec and the serving grid is Hydro-Quebec. v3.1.0: row now takes the Quebec provincial grid CAN-QC (v4_inputs/subnational_grids.csv) via grid_override, as AWS ca-central-1 already did; v3.0.0 used the Canadian national average.",https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.00190674,0.000887014,0.000459429,0.00325319,0.00060411,0.00158808,0.0038573,0.00315017,0.0048871,0.00208228,0.00549121,0.0026001,0.00624409,0.00334385,0.00150451,0.0110925,0.00293425,0.00628932,0.0140267,0.010316,0.0165529,0.00794091,0.0194871,0.00851467,0.0232516,0.0128425,0.00560246,0.0416966,0.0128445,0.0254562,0.0545411,0.0384145,0.0621277,0.0316359,0.0749722,0.0317067
49
49
  azure,centralindia,Central India,Pune,IND,IND,0.7137,"Ember yearly electricity data, CO2 intensity 2023, 713.72 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0513687,0.000887014,0.000459429,0.0527151,0.00060411,0.0165486,0.0533193,0.0848673,0.0866043,0.0267988,0.0872084,0.0700482,0.168219,0.00334385,0.00150451,0.173068,0.00293425,0.0552811,0.176002,0.277919,0.284156,0.0888812,0.28709,0.22939,0.626411,0.0128425,0.00560246,0.644856,0.0128445,0.207891,0.6577,1.03491,1.05862,0.33304,1.07146,0.854197
50
50
  azure,chilecentral,Chile Central,Santiago,CHL,CHL,0.3048,"Ember yearly electricity data, CO2 intensity 2023, 304.83 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0219396,0.000887014,0.000459429,0.023286,0.00060411,0.00764731,0.0238901,0.0362469,0.0379838,0.0120929,0.0385879,0.0299176,0.0718465,0.00334385,0.00150451,0.0766949,0.00293425,0.0261317,0.0796291,0.118699,0.124936,0.040723,0.12787,0.0979725,0.26754,0.0128425,0.00560246,0.285985,0.0128445,0.0993449,0.29883,0.442009,0.465722,0.153709,0.478567,0.364828
51
51
  azure,denmarkeast,Denmark East,Copenhagen,DNK,DNK,0.1523,"Ember yearly electricity data, CO2 intensity 2023, 152.26 g/kWh (lifecycle, IPCC AR5)",high,,https://learn.microsoft.com/azure/reliability/regions-list,0.3025,0.0109586,0.000887014,0.000459429,0.0123051,0.00060411,0.00432596,0.0129092,0.018105,0.0198419,0.00660559,0.020446,0.0149436,0.0358867,0.00334385,0.00150451,0.0407351,0.00293425,0.0152552,0.0436693,0.0592892,0.0655261,0.0227536,0.0684603,0.0489364,0.133634,0.0128425,0.00560246,0.152079,0.0128445,0.058843,0.164924,0.22078,0.244493,0.086795,0.257337,0.182228
@@ -128,7 +128,7 @@ gcp,europe-west12,europe-west12,"Turin, Italy",ITA,ITA,0.3233,"Ember yearly elec
128
128
  gcp,me-central1,me-central1,"Doha, Qatar",QAT,QAT,0.5843,"Ember yearly electricity data, CO2 intensity 2023, 584.25 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0420503,0.000887014,0.000459429,0.0433968,0.00060411,0.0137301,0.0440009,0.0694723,0.0712092,0.0221424,0.0718133,0.0573414,0.137704,0.00334385,0.00150451,0.142552,0.00293425,0.0460513,0.145487,0.227504,0.233741,0.0736325,0.236675,0.187778,0.512779,0.0128425,0.00560246,0.531224,0.0128445,0.173521,0.544068,0.847173,0.870886,0.276257,0.883731,0.699244
129
129
  gcp,me-central2,me-central2,"Dammam, Saudi Arabia",SAU,SAU,0.6973,"Ember yearly electricity data, CO2 intensity 2023, 697.31 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0501876,0.000887014,0.000459429,0.0515341,0.00060411,0.0161913,0.0521382,0.082916,0.084653,0.0262086,0.0852571,0.0684377,0.164352,0.00334385,0.00150451,0.1692,0.00293425,0.0541112,0.172134,0.271529,0.277766,0.0869485,0.2807,0.224116,0.612008,0.0128425,0.00560246,0.630453,0.0128445,0.203534,0.643298,1.01111,1.03483,0.325842,1.04767,0.834557
130
130
  gcp,me-west1,me-west1,"Tel Aviv, Israel",ISR,ISR,0.5588,"Ember yearly electricity data, CO2 intensity 2023, 558.83 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0402208,0.000887014,0.000459429,0.0415672,0.00060411,0.0131767,0.0421713,0.0664496,0.0681865,0.0212281,0.0687906,0.0548465,0.131713,0.00334385,0.00150451,0.136561,0.00293425,0.0442391,0.139495,0.217605,0.223842,0.0706386,0.226776,0.179608,0.490469,0.0128425,0.00560246,0.508914,0.0128445,0.166773,0.521758,0.810314,0.834027,0.265108,0.846871,0.668821
131
- gcp,northamerica-northeast1,northamerica-northeast1,"Montréal, Québec",CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
131
+ gcp,northamerica-northeast1,northamerica-northeast1,"Montréal, Québec",CAN,CAN-QC,0.0265,"Derived: 2023 generation shares (Canada Energy Regulator, Renewable power in Canada: Quebec (page updated 2026-03-25): 'In 2023, Quebec generated 195.5 terawatt-hours (TWh) of electricity, with 194.8 TWh (99.6%) coming from renewable sources' and 'Most generation in 2023 came from hydroelectricity (94.0%), wind (5.0%), and biomass (0.7%)') x Ember 2023 implied Canadian life-cycle factor per fuel, g/kWh: Hydro 0.940 x 23.8; Wind 0.050 x 9.6; Bioenergy 0.007 x 216.3; Gas 0.003 x 721.8 = 26.5 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",high,"Provider states the location as Montreal, Quebec (Google Cloud, Regions and zones, read 12 November 2026), so the serving grid is Hydro-Quebec. v3.1.0: row now takes the Quebec provincial grid CAN-QC (v4_inputs/subnational_grids.csv) via grid_override, as AWS ca-central-1 already did; v3.0.0 used the Canadian national average.",https://cloud.google.com/compute/docs/regions-zones,0.3025,0.00190674,0.000887014,0.000459429,0.00325319,0.00060411,0.00158808,0.0038573,0.00315017,0.0048871,0.00208228,0.00549121,0.0026001,0.00624409,0.00334385,0.00150451,0.0110925,0.00293425,0.00628932,0.0140267,0.010316,0.0165529,0.00794091,0.0194871,0.00851467,0.0232516,0.0128425,0.00560246,0.0416966,0.0128445,0.0254562,0.0545411,0.0384145,0.0621277,0.0316359,0.0749722,0.0317067
132
132
  gcp,northamerica-northeast2,northamerica-northeast2,"Toronto, Ontario",CAN,CAN,0.1744,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
133
133
  gcp,northamerica-south1,northamerica-south1,"Queretaro, Mexico",MEX,MEX,0.4890,"Ember yearly electricity data, CO2 intensity 2023, 489.05 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.0351985,0.000887014,0.000459429,0.0365449,0.00060411,0.0116577,0.037149,0.0581522,0.0598891,0.0187184,0.0604932,0.0479979,0.115266,0.00334385,0.00150451,0.120114,0.00293425,0.0392646,0.123049,0.190433,0.19667,0.06242,0.199605,0.157181,0.429225,0.0128425,0.00560246,0.44767,0.0128445,0.148249,0.460514,0.709131,0.732845,0.234504,0.745689,0.585306
134
134
  gcp,southamerica-east1,southamerica-east1,"Osasco, São Paulo, Brazil",BRA,BRA,0.0963,"Ember yearly electricity data, CO2 intensity 2023, 96.26 g/kWh (lifecycle, IPCC AR5)",high,,https://cloud.google.com/compute/docs/regions-zones,0.3025,0.00692814,0.000887014,0.000459429,0.00827458,0.00060411,0.00310688,0.00887869,0.0114461,0.0131831,0.00459152,0.0137872,0.00944746,0.0226879,0.00334385,0.00150451,0.0275362,0.00293425,0.011263,0.0304705,0.0374831,0.04372,0.016158,0.0466543,0.030938,0.0844846,0.0128425,0.00560246,0.10293,0.0128445,0.043977,0.115774,0.139579,0.163292,0.0622345,0.176136,0.115206
@@ -33,7 +33,7 @@ KHM,Cambodia,country,KHM,0.4912,2023,,"Ember yearly electricity data, CO2 intens
33
33
  CMR,Cameroon,country,CMR,0.2244,2023,,"Ember yearly electricity data, CO2 intensity 2023, 224.38 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0161493,0.000887014,0.000459429,0.0174958,0.00060411,0.00589596,0.0180999,0.0266807,0.0284176,0.00919943,0.0290217,0.0220218,0.0528849,0.00334385,0.00150451,0.0577333,0.00293425,0.0203965,0.0606676,0.0873723,0.0936092,0.0312477,0.0965435,0.0721158,0.196932,0.0128425,0.00560246,0.215377,0.0128445,0.0779883,0.228221,0.325355,0.349068,0.118425,0.361913,0.268543
34
34
  CAN,Canada,country,CAN,0.1744,2023,,"Ember yearly electricity data, CO2 intensity 2023, 174.43 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0125543,0.000887014,0.000459429,0.0139007,0.00060411,0.00480859,0.0145048,0.0207412,0.0224781,0.00740295,0.0230822,0.0171195,0.041112,0.00334385,0.00150451,0.0459604,0.00293425,0.0168356,0.0488947,0.0679221,0.074159,0.0253647,0.0770932,0.0560619,0.153092,0.0128425,0.00560246,0.171537,0.0128445,0.0647284,0.184382,0.252927,0.27664,0.0965183,0.289484,0.208762
35
35
  CYM,Cayman Islands (the),country,CYM,0.6429,2023,,"Ember yearly electricity data, CO2 intensity 2023, 642.86 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0462687,0.000887014,0.000459429,0.0476151,0.00060411,0.015006,0.0482192,0.0764415,0.0781784,0.0242503,0.0787825,0.0630937,0.151518,0.00334385,0.00150451,0.156366,0.00293425,0.0502295,0.159301,0.250326,0.256563,0.0805355,0.259497,0.206616,0.564219,0.0128425,0.00560246,0.582664,0.0128445,0.18908,0.595509,0.932159,0.955872,0.301962,0.968716,0.76939
36
- CAF,Central African Republic (the),country,CAF,0.0000,2023,,"Ember yearly electricity data, CO2 intensity 2023, 0.0 g/kWh (lifecycle, IPCC AR5)",0.3025,0,0.000887014,0.000459429,0.00134644,0.00060411,0.00101136,0.00195055,0,0.00173693,0.00112947,0.00234104,0,0,0.00334385,0.00150451,0.00484836,0.00293425,0.0044007,0.00778261,0,0.00623689,0.00482068,0.00917114,0,0,0.0128425,0.00560246,0.018445,0.0128445,0.0184235,0.0312895,0,0.0237132,0.0200169,0.0365577,0
36
+ CAF,Central African Republic (the),country,CAF,0.0238,2023,,"Ember yearly electricity data, CO2 intensity 2023 published as 0.0 g/kWh (power-sector emissions round to 0.00 MtCO2 on 0.14 TWh); zero-intensity fallback (v3.1.0): Ember 2023 generation shares x Ember 2023 implied World life-cycle factor per fuel, g/kWh: Hydro 1.000 x 23.8 = 23.8 g/kWh (lifecycle, IPCC AR5 basis of the Ember rows)",0.3025,0.00171154,0.000887014,0.000459429,0.00305799,0.00060411,0.00152904,0.00366209,0.00282767,0.00456461,0.00198474,0.00516872,0.00233392,0.00560486,0.00334385,0.00150451,0.0104532,0.00293425,0.00609597,0.0133875,0.00925991,0.0154968,0.00762148,0.018431,0.00764299,0.0208712,0.0128425,0.00560246,0.0393162,0.0128445,0.0247363,0.0521607,0.0344818,0.058195,0.0304465,0.0710396,0.0284608
37
37
  TCD,Chad,country,TCD,0.6111,2023,,"Ember yearly electricity data, CO2 intensity 2023, 611.11 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0439835,0.000887014,0.000459429,0.04533,0.00060411,0.0143148,0.0459341,0.0726661,0.0744031,0.0231084,0.0750072,0.0599775,0.144035,0.00334385,0.00150451,0.148883,0.00293425,0.0479661,0.151817,0.237963,0.2442,0.076796,0.247134,0.196411,0.536353,0.0128425,0.00560246,0.554798,0.0128445,0.180651,0.567643,0.88612,0.909834,0.288037,0.922678,0.731391
38
38
  CHL,Chile,country,CHL,0.3048,2023,,"Ember yearly electricity data, CO2 intensity 2023, 304.83 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0219396,0.000887014,0.000459429,0.023286,0.00060411,0.00764731,0.0238901,0.0362469,0.0379838,0.0120929,0.0385879,0.0299176,0.0718465,0.00334385,0.00150451,0.0766949,0.00293425,0.0261317,0.0796291,0.118699,0.124936,0.040723,0.12787,0.0979725,0.26754,0.0128425,0.00560246,0.285985,0.0128445,0.0993449,0.29883,0.442009,0.465722,0.153709,0.478567,0.364828
39
39
  CHN,China,country,CHN,0.5833,2023,,"Ember yearly electricity data, CO2 intensity 2023, 583.25 g/kWh (lifecycle, IPCC AR5)",0.3025,0.0419784,0.000887014,0.000459429,0.0433248,0.00060411,0.0137083,0.0439289,0.0693533,0.0710903,0.0221064,0.0716944,0.0572432,0.137468,0.00334385,0.00150451,0.142317,0.00293425,0.04598,0.145251,0.227114,0.233351,0.0735147,0.236285,0.187457,0.511901,0.0128425,0.00560246,0.530346,0.0128445,0.173255,0.543191,0.845723,0.869436,0.275818,0.882281,0.698047
@@ -0,0 +1 @@
1
+ """Optional framework integrations. Import the submodule you need, for example saef.integrations.litellm."""
@@ -0,0 +1,100 @@
1
+ import json
2
+ import os
3
+ import threading
4
+
5
+ from .. import SaefError, estimate
6
+
7
+ DEFAULT_REGION = "global-average"
8
+
9
+
10
+ def default_region():
11
+ return os.environ.get("SAEF_REGION") or DEFAULT_REGION
12
+
13
+
14
+ class Tracker:
15
+ """Thread-safe running totals of per-call estimates, with optional JSON lines output."""
16
+
17
+ def __init__(self, region=None, provider=None, log_path=None):
18
+ self.region = region or default_region()
19
+ self.provider = provider
20
+ self.log_path = log_path
21
+ self._lock = threading.Lock()
22
+ self.reset()
23
+
24
+ def reset(self):
25
+ with self._lock:
26
+ self._calls = 0
27
+ self._skipped = 0
28
+ self._input = self._cached = self._output = 0
29
+ self._kg = self._kg_high = self._water = 0.0
30
+ self._water_missing = 0
31
+ self._by_model = {}
32
+
33
+ def _estimate(self, model, input_tokens, output_tokens, cached_input_tokens, region, provider):
34
+ kw = dict(
35
+ model=model, provider=provider or self.provider, input_tokens=input_tokens,
36
+ output_tokens=output_tokens, cached_input_tokens=cached_input_tokens,
37
+ )
38
+ try:
39
+ return estimate(region=region or self.region, **kw)
40
+ except SaefError:
41
+ if region and region != self.region:
42
+ return estimate(region=self.region, **kw)
43
+ raise
44
+
45
+ def record(self, model, input_tokens, output_tokens, cached_input_tokens=0, region=None, provider=None, extra=None):
46
+ """Estimate one call, add it to the totals and return a plain dict, or None if the model is out of scope.
47
+
48
+ A per-call region that SAEF does not know falls back to the configured region."""
49
+ try:
50
+ e = self._estimate(model, input_tokens, output_tokens, cached_input_tokens, region, provider)
51
+ except SaefError:
52
+ with self._lock:
53
+ self._skipped += 1
54
+ return None
55
+ out = {
56
+ "model": model,
57
+ "model_class": e.model_class,
58
+ "region_id": e.region_id,
59
+ "input_tokens": input_tokens,
60
+ "cached_input_tokens": cached_input_tokens,
61
+ "output_tokens": output_tokens,
62
+ "kg_co2e": e.kg_co2e,
63
+ "kg_co2e_high_case": e.kg_co2e_high_case,
64
+ "water_ml": e.water_ml,
65
+ "dataset_version": e.version,
66
+ "note": "estimate",
67
+ }
68
+ with self._lock:
69
+ self._calls += 1
70
+ self._input += input_tokens
71
+ self._cached += cached_input_tokens
72
+ self._output += output_tokens
73
+ self._kg += e.kg_co2e
74
+ self._kg_high += e.kg_co2e_high_case
75
+ if e.water_ml is None:
76
+ self._water_missing += 1
77
+ else:
78
+ self._water += e.water_ml
79
+ m = self._by_model.setdefault(model, {"calls": 0, "kg_co2e": 0.0})
80
+ m["calls"] += 1
81
+ m["kg_co2e"] += e.kg_co2e
82
+ if self.log_path:
83
+ with open(self.log_path, "a", encoding="utf-8") as f:
84
+ f.write(json.dumps(dict(out, **(extra or {}))) + "\n")
85
+ return out
86
+
87
+ def totals(self):
88
+ with self._lock:
89
+ return {
90
+ "calls": self._calls,
91
+ "skipped_calls": self._skipped,
92
+ "input_tokens": self._input,
93
+ "cached_input_tokens": self._cached,
94
+ "output_tokens": self._output,
95
+ "kg_co2e": self._kg,
96
+ "kg_co2e_high_case": self._kg_high,
97
+ "water_ml": self._water,
98
+ "calls_without_water_factor": self._water_missing,
99
+ "by_model": {k: dict(v) for k, v in self._by_model.items()},
100
+ }