saef 3.3.0__tar.gz → 3.3.2__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.
- {saef-3.3.0 → saef-3.3.2}/PKG-INFO +23 -7
- {saef-3.3.0 → saef-3.3.2}/PYPI_README.md +17 -3
- {saef-3.3.0 → saef-3.3.2}/pyproject.toml +5 -3
- {saef-3.3.0 → saef-3.3.2}/src/saef/__init__.py +1 -1
- {saef-3.3.0 → saef-3.3.2}/src/saef/_core.py +9 -7
- {saef-3.3.0 → saef-3.3.2}/src/saef/mcp_server.py +3 -2
- {saef-3.3.0 → saef-3.3.2}/tests/test_saef.py +1 -0
- {saef-3.3.0 → saef-3.3.2}/.gitignore +0 -0
- {saef-3.3.0 → saef-3.3.2}/LICENSE +0 -0
- {saef-3.3.0 → saef-3.3.2}/LICENSE-CODE +0 -0
- {saef-3.3.0 → saef-3.3.2}/cloud_region_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/factors_v3_lifecycle.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/grid_intensity_all.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/model_class_mapping.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/model_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/region_grid_crosswalk.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/region_water_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/reserved_capacity_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/scripts/sync_data.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/__main__.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/_calc.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/cli.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/cloud_region_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/factors_v3_lifecycle.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/grid_intensity_all.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/model_class_mapping.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/model_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/region_grid_crosswalk.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/region_water_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/reserved_capacity_factors.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/data/token_basis_constants.csv +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/integrations/__init__.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/integrations/_base.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/integrations/langchain.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/integrations/litellm.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/src/saef/integrations/openai.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/tests/test_integrations.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/tests/test_mcp_server.py +0 -0
- {saef-3.3.0 → saef-3.3.2}/token_basis_constants.csv +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: saef
|
|
3
|
-
Version: 3.3.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 3.3.2
|
|
4
|
+
Summary: Estimate the carbon and water footprint of AI API calls (OpenAI, Anthropic, LiteLLM, LangChain) with SAEF, open per-token emission factors
|
|
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
|
|
7
7
|
Project-URL: Repository, https://github.com/guillermollopis/soma-ai-emission-factors
|
|
@@ -11,7 +11,7 @@ Author-email: Guillermo Llopis-Garcia <guillermollopis@somaai.earth>
|
|
|
11
11
|
License-Expression: MIT AND CC-BY-4.0
|
|
12
12
|
License-File: LICENSE
|
|
13
13
|
License-File: LICENSE-CODE
|
|
14
|
-
Keywords: ai-emissions,carbon-footprint,csrd,emission-factors,ghg-protocol,llm,scope-3,water-footprint
|
|
14
|
+
Keywords: ai-carbon-footprint,ai-emissions,anthropic,carbon-footprint,carbon-tracking,csrd,emission-factors,ghg-protocol,green-ai,langchain,litellm,llm,mcp,openai,scope-3,sustainability,water-footprint
|
|
15
15
|
Classifier: Development Status :: 4 - Beta
|
|
16
16
|
Classifier: Intended Audience :: Developers
|
|
17
17
|
Classifier: Intended Audience :: Science/Research
|
|
@@ -22,13 +22,15 @@ Classifier: Programming Language :: Python :: 3.11
|
|
|
22
22
|
Classifier: Programming Language :: Python :: 3.12
|
|
23
23
|
Classifier: Programming Language :: Python :: 3.13
|
|
24
24
|
Classifier: Topic :: Scientific/Engineering
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
|
|
26
|
+
Classifier: Topic :: System :: Monitoring
|
|
25
27
|
Requires-Python: >=3.9
|
|
26
28
|
Provides-Extra: langchain
|
|
27
29
|
Requires-Dist: langchain>=1.0; extra == 'langchain'
|
|
28
30
|
Provides-Extra: litellm
|
|
29
31
|
Requires-Dist: litellm; extra == 'litellm'
|
|
30
32
|
Provides-Extra: mcp
|
|
31
|
-
Requires-Dist: mcp
|
|
33
|
+
Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
|
|
32
34
|
Provides-Extra: pandas
|
|
33
35
|
Requires-Dist: pandas; extra == 'pandas'
|
|
34
36
|
Provides-Extra: test
|
|
@@ -39,6 +41,8 @@ Description-Content-Type: text/markdown
|
|
|
39
41
|
|
|
40
42
|
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.
|
|
41
43
|
|
|
44
|
+
Use it to track the estimated carbon and water footprint of OpenAI, Anthropic and other LLM API calls from the token usage each response already reports, with a LiteLLM callback, a LangChain handler, an MCP server, or one function call on a response object. The method is peer reviewed, published in Sustainable Production and Consumption 70 (2026) 320-347 (https://doi.org/10.1016/j.spc.2026.11.003).
|
|
45
|
+
|
|
42
46
|
Every number comes with the file, column and row it was read from, so you can trace an estimate back to the dataset.
|
|
43
47
|
|
|
44
48
|
## Install
|
|
@@ -49,6 +53,18 @@ pip install saef
|
|
|
49
53
|
|
|
50
54
|
For pandas users, `pip install "saef[pandas]"` adds the optional extra. The framework integrations below use `saef[litellm]` and `saef[langchain]`.
|
|
51
55
|
|
|
56
|
+
## Track OpenAI and Anthropic API calls
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from saef.integrations.openai import estimate_from_response
|
|
60
|
+
|
|
61
|
+
resp = client.chat.completions.create(model="gpt-4o-mini", messages=[...]) # or client.messages.create(...) with Anthropic
|
|
62
|
+
e = estimate_from_response(resp, region="eu-west-1")
|
|
63
|
+
print(e.kg_co2e, e.kg_co2e_high_case, e.water_ml) # kg CO2e central and high case, water in mL
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
No SDK import is needed, so the same call works on OpenAI Chat Completions, OpenAI Responses and Anthropic Messages objects, or the same shapes as dicts. Running totals per model and a JSON lines log are covered under Integrations below.
|
|
67
|
+
|
|
52
68
|
## Example
|
|
53
69
|
|
|
54
70
|
```python
|
|
@@ -62,7 +78,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
|
|
|
62
78
|
print(r.water_ml) # mL, or None where the region has no water factor
|
|
63
79
|
for s in r.provenance[:3]:
|
|
64
80
|
print(s["file"], s["line"], s["column"]) # the file, line and column behind each number
|
|
65
|
-
print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.
|
|
81
|
+
print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.2, 3.1.0
|
|
66
82
|
print(saef.citation())
|
|
67
83
|
```
|
|
68
84
|
|
|
@@ -258,13 +274,13 @@ Dataset (concept DOI, always the latest version): https://doi.org/10.5281/zenodo
|
|
|
258
274
|
}
|
|
259
275
|
```
|
|
260
276
|
|
|
261
|
-
Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories, a Token-Based Method.
|
|
277
|
+
Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories, a Token-Based Method. Sustainable Production and Consumption 70 (2026) 320-347. https://doi.org/10.1016/j.spc.2026.11.003
|
|
262
278
|
|
|
263
279
|
## Links
|
|
264
280
|
|
|
265
281
|
- Homepage: https://somaai.earth/ai-footprint
|
|
266
282
|
- Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
|
|
267
283
|
- Repository: https://github.com/guillermollopis/soma-ai-emission-factors
|
|
268
|
-
- Paper: https://arxiv.org/abs/2606.10660
|
|
284
|
+
- Paper: https://doi.org/10.1016/j.spc.2026.11.003 (preprint https://arxiv.org/abs/2606.10660)
|
|
269
285
|
|
|
270
286
|
mcp-name: io.github.guillermollopis/saef
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
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
4
|
|
|
5
|
+
Use it to track the estimated carbon and water footprint of OpenAI, Anthropic and other LLM API calls from the token usage each response already reports, with a LiteLLM callback, a LangChain handler, an MCP server, or one function call on a response object. The method is peer reviewed, published in Sustainable Production and Consumption 70 (2026) 320-347 (https://doi.org/10.1016/j.spc.2026.11.003).
|
|
6
|
+
|
|
5
7
|
Every number comes with the file, column and row it was read from, so you can trace an estimate back to the dataset.
|
|
6
8
|
|
|
7
9
|
## Install
|
|
@@ -12,6 +14,18 @@ pip install saef
|
|
|
12
14
|
|
|
13
15
|
For pandas users, `pip install "saef[pandas]"` adds the optional extra. The framework integrations below use `saef[litellm]` and `saef[langchain]`.
|
|
14
16
|
|
|
17
|
+
## Track OpenAI and Anthropic API calls
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from saef.integrations.openai import estimate_from_response
|
|
21
|
+
|
|
22
|
+
resp = client.chat.completions.create(model="gpt-4o-mini", messages=[...]) # or client.messages.create(...) with Anthropic
|
|
23
|
+
e = estimate_from_response(resp, region="eu-west-1")
|
|
24
|
+
print(e.kg_co2e, e.kg_co2e_high_case, e.water_ml) # kg CO2e central and high case, water in mL
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
No SDK import is needed, so the same call works on OpenAI Chat Completions, OpenAI Responses and Anthropic Messages objects, or the same shapes as dicts. Running totals per model and a JSON lines log are covered under Integrations below.
|
|
28
|
+
|
|
15
29
|
## Example
|
|
16
30
|
|
|
17
31
|
```python
|
|
@@ -25,7 +39,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
|
|
|
25
39
|
print(r.water_ml) # mL, or None where the region has no water factor
|
|
26
40
|
for s in r.provenance[:3]:
|
|
27
41
|
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.3.
|
|
42
|
+
print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.2, 3.1.0
|
|
29
43
|
print(saef.citation())
|
|
30
44
|
```
|
|
31
45
|
|
|
@@ -221,13 +235,13 @@ Dataset (concept DOI, always the latest version): https://doi.org/10.5281/zenodo
|
|
|
221
235
|
}
|
|
222
236
|
```
|
|
223
237
|
|
|
224
|
-
Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories, a Token-Based Method.
|
|
238
|
+
Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories, a Token-Based Method. Sustainable Production and Consumption 70 (2026) 320-347. https://doi.org/10.1016/j.spc.2026.11.003
|
|
225
239
|
|
|
226
240
|
## Links
|
|
227
241
|
|
|
228
242
|
- Homepage: https://somaai.earth/ai-footprint
|
|
229
243
|
- Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
|
|
230
244
|
- Repository: https://github.com/guillermollopis/soma-ai-emission-factors
|
|
231
|
-
- Paper: https://arxiv.org/abs/2606.10660
|
|
245
|
+
- Paper: https://doi.org/10.1016/j.spc.2026.11.003 (preprint https://arxiv.org/abs/2606.10660)
|
|
232
246
|
|
|
233
247
|
mcp-name: io.github.guillermollopis/saef
|
|
@@ -5,13 +5,13 @@ build-backend = "hatchling.build"
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "saef"
|
|
7
7
|
dynamic = ["version"]
|
|
8
|
-
description = "
|
|
8
|
+
description = "Estimate the carbon and water footprint of AI API calls (OpenAI, Anthropic, LiteLLM, LangChain) with SAEF, open per-token emission factors"
|
|
9
9
|
readme = "PYPI_README.md"
|
|
10
10
|
requires-python = ">=3.9"
|
|
11
11
|
license = "MIT AND CC-BY-4.0"
|
|
12
12
|
license-files = ["LICENSE-CODE", "LICENSE"]
|
|
13
13
|
authors = [{ name = "Guillermo Llopis-Garcia", email = "guillermollopis@somaai.earth" }]
|
|
14
|
-
keywords = ["carbon-footprint", "ai-emissions", "llm", "scope-3", "csrd", "ghg-protocol", "emission-factors", "water-footprint"]
|
|
14
|
+
keywords = ["carbon-footprint", "ai-emissions", "llm", "scope-3", "csrd", "ghg-protocol", "emission-factors", "water-footprint", "openai", "anthropic", "litellm", "langchain", "mcp", "green-ai", "carbon-tracking", "ai-carbon-footprint", "sustainability"]
|
|
15
15
|
classifiers = [
|
|
16
16
|
"Development Status :: 4 - Beta",
|
|
17
17
|
"Intended Audience :: Developers",
|
|
@@ -23,6 +23,8 @@ classifiers = [
|
|
|
23
23
|
"Programming Language :: Python :: 3.12",
|
|
24
24
|
"Programming Language :: Python :: 3.13",
|
|
25
25
|
"Topic :: Scientific/Engineering",
|
|
26
|
+
"Topic :: Scientific/Engineering :: Atmospheric Science",
|
|
27
|
+
"Topic :: System :: Monitoring",
|
|
26
28
|
]
|
|
27
29
|
dependencies = []
|
|
28
30
|
|
|
@@ -30,7 +32,7 @@ dependencies = []
|
|
|
30
32
|
pandas = ["pandas"]
|
|
31
33
|
litellm = ["litellm"]
|
|
32
34
|
langchain = ["langchain>=1.0"]
|
|
33
|
-
mcp = ["mcp>=1.2"]
|
|
35
|
+
mcp = ["mcp>=1.2,<2"]
|
|
34
36
|
test = ["pytest"]
|
|
35
37
|
|
|
36
38
|
[project.scripts]
|
|
@@ -16,13 +16,15 @@ BIBTEX = """@misc{llopis2026somafactors,
|
|
|
16
16
|
url = {https://doi.org/10.5281/zenodo.20443585}
|
|
17
17
|
}
|
|
18
18
|
|
|
19
|
-
@
|
|
20
|
-
author
|
|
21
|
-
title
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
19
|
+
@article{llopis2026accounting,
|
|
20
|
+
author = {Llopis-Garcia, Guillermo},
|
|
21
|
+
title = {Accounting for purchased artificial intelligence inference in corporate greenhouse gas inventories: A token-based method},
|
|
22
|
+
journal = {Sustainable Production and Consumption},
|
|
23
|
+
volume = {70},
|
|
24
|
+
pages = {320--347},
|
|
25
|
+
year = {2026},
|
|
26
|
+
doi = {10.1016/j.spc.2026.11.003},
|
|
27
|
+
url = {https://doi.org/10.1016/j.spc.2026.11.003}
|
|
26
28
|
}
|
|
27
29
|
"""
|
|
28
30
|
|
|
@@ -16,6 +16,7 @@ CLASS_DESCRIPTIONS = {
|
|
|
16
16
|
|
|
17
17
|
DOI = "10.5281/zenodo.20443585"
|
|
18
18
|
ARXIV = "2606.10660"
|
|
19
|
+
PAPER_DOI = "10.1016/j.spc.2026.11.003"
|
|
19
20
|
HOMEPAGE = "https://somaai.earth/ai-footprint"
|
|
20
21
|
NOTE = "Estimate, not a measurement. SOMA AI Emission Factors (SAEF) factors are modelled from published benchmarks and grid data."
|
|
21
22
|
|
|
@@ -46,7 +47,7 @@ def _report(e):
|
|
|
46
47
|
"dataset_version": e.version,
|
|
47
48
|
"warnings": e.warnings,
|
|
48
49
|
"provenance": e.provenance,
|
|
49
|
-
"citation": f"SOMA AI Emission Factors (SAEF) v{e.version}, doi:{DOI}; method paper
|
|
50
|
+
"citation": f"SOMA AI Emission Factors (SAEF) v{e.version}, doi:{DOI}; method paper doi:{PAPER_DOI}",
|
|
50
51
|
"note": NOTE,
|
|
51
52
|
}
|
|
52
53
|
if grid > 0:
|
|
@@ -190,7 +191,7 @@ def about() -> str:
|
|
|
190
191
|
"for Scope 3 category 1 reporting. All figures are estimates, not measurements.\n"
|
|
191
192
|
"Licence: data CC BY 4.0, code MIT.\n"
|
|
192
193
|
f"Dataset DOI: {DOI} (https://doi.org/{DOI})\n"
|
|
193
|
-
f"Method paper:
|
|
194
|
+
f"Method paper: Sustainable Production and Consumption 70 (2026) 320-347, doi {PAPER_DOI} (https://doi.org/{PAPER_DOI}), preprint arXiv {ARXIV}\n"
|
|
194
195
|
f"Homepage: {HOMEPAGE}\n"
|
|
195
196
|
)
|
|
196
197
|
|
|
@@ -110,6 +110,7 @@ def test_coverage_counts_and_citation():
|
|
|
110
110
|
assert len(saef.grids()) == 240
|
|
111
111
|
assert "eu-west-1" in saef.regions()
|
|
112
112
|
assert "10.5281/zenodo.20443585" in saef.citation()
|
|
113
|
+
assert "10.1016/j.spc.2026.11.003" in saef.citation()
|
|
113
114
|
|
|
114
115
|
|
|
115
116
|
def run_cli(*args):
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|