saef 3.3.1__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.
Files changed (39) hide show
  1. {saef-3.3.1 → saef-3.3.2}/PKG-INFO +22 -6
  2. {saef-3.3.1 → saef-3.3.2}/PYPI_README.md +17 -3
  3. {saef-3.3.1 → saef-3.3.2}/pyproject.toml +4 -2
  4. {saef-3.3.1 → saef-3.3.2}/src/saef/__init__.py +1 -1
  5. {saef-3.3.1 → saef-3.3.2}/src/saef/_core.py +9 -7
  6. {saef-3.3.1 → saef-3.3.2}/src/saef/mcp_server.py +3 -2
  7. {saef-3.3.1 → saef-3.3.2}/tests/test_saef.py +1 -0
  8. {saef-3.3.1 → saef-3.3.2}/.gitignore +0 -0
  9. {saef-3.3.1 → saef-3.3.2}/LICENSE +0 -0
  10. {saef-3.3.1 → saef-3.3.2}/LICENSE-CODE +0 -0
  11. {saef-3.3.1 → saef-3.3.2}/cloud_region_factors.csv +0 -0
  12. {saef-3.3.1 → saef-3.3.2}/factors_v3_lifecycle.csv +0 -0
  13. {saef-3.3.1 → saef-3.3.2}/grid_intensity_all.csv +0 -0
  14. {saef-3.3.1 → saef-3.3.2}/model_class_mapping.csv +0 -0
  15. {saef-3.3.1 → saef-3.3.2}/model_factors.csv +0 -0
  16. {saef-3.3.1 → saef-3.3.2}/region_grid_crosswalk.csv +0 -0
  17. {saef-3.3.1 → saef-3.3.2}/region_water_factors.csv +0 -0
  18. {saef-3.3.1 → saef-3.3.2}/reserved_capacity_factors.csv +0 -0
  19. {saef-3.3.1 → saef-3.3.2}/scripts/sync_data.py +0 -0
  20. {saef-3.3.1 → saef-3.3.2}/src/saef/__main__.py +0 -0
  21. {saef-3.3.1 → saef-3.3.2}/src/saef/_calc.py +0 -0
  22. {saef-3.3.1 → saef-3.3.2}/src/saef/cli.py +0 -0
  23. {saef-3.3.1 → saef-3.3.2}/src/saef/data/cloud_region_factors.csv +0 -0
  24. {saef-3.3.1 → saef-3.3.2}/src/saef/data/factors_v3_lifecycle.csv +0 -0
  25. {saef-3.3.1 → saef-3.3.2}/src/saef/data/grid_intensity_all.csv +0 -0
  26. {saef-3.3.1 → saef-3.3.2}/src/saef/data/model_class_mapping.csv +0 -0
  27. {saef-3.3.1 → saef-3.3.2}/src/saef/data/model_factors.csv +0 -0
  28. {saef-3.3.1 → saef-3.3.2}/src/saef/data/region_grid_crosswalk.csv +0 -0
  29. {saef-3.3.1 → saef-3.3.2}/src/saef/data/region_water_factors.csv +0 -0
  30. {saef-3.3.1 → saef-3.3.2}/src/saef/data/reserved_capacity_factors.csv +0 -0
  31. {saef-3.3.1 → saef-3.3.2}/src/saef/data/token_basis_constants.csv +0 -0
  32. {saef-3.3.1 → saef-3.3.2}/src/saef/integrations/__init__.py +0 -0
  33. {saef-3.3.1 → saef-3.3.2}/src/saef/integrations/_base.py +0 -0
  34. {saef-3.3.1 → saef-3.3.2}/src/saef/integrations/langchain.py +0 -0
  35. {saef-3.3.1 → saef-3.3.2}/src/saef/integrations/litellm.py +0 -0
  36. {saef-3.3.1 → saef-3.3.2}/src/saef/integrations/openai.py +0 -0
  37. {saef-3.3.1 → saef-3.3.2}/tests/test_integrations.py +0 -0
  38. {saef-3.3.1 → saef-3.3.2}/tests/test_mcp_server.py +0 -0
  39. {saef-3.3.1 → 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.1
4
- Summary: SOMA AI Emission Factors: estimated carbon and water factors for AI inference, per million tokens
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,6 +22,8 @@ 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'
@@ -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.1, 3.1.0
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. arXiv 2606.10660, accepted for publication in Sustainable Production and Consumption.
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.1, 3.1.0
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. arXiv 2606.10660, accepted for publication in Sustainable Production and Consumption.
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 = "SOMA AI Emission Factors: estimated carbon and water factors for AI inference, per million tokens"
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
 
@@ -11,7 +11,7 @@ from ._core import (
11
11
  regions,
12
12
  )
13
13
 
14
- __version__ = "3.3.1"
14
+ __version__ = "3.3.2"
15
15
 
16
16
  __all__ = [
17
17
  "DATASET_VERSION",
@@ -16,13 +16,15 @@ BIBTEX = """@misc{llopis2026somafactors,
16
16
  url = {https://doi.org/10.5281/zenodo.20443585}
17
17
  }
18
18
 
19
- @misc{llopis2026accounting,
20
- author = {Llopis-Garcia, Guillermo},
21
- title = {Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories: A Token-Based Method},
22
- year = {2026},
23
- eprint = {2606.10660},
24
- archivePrefix = {arXiv},
25
- note = {Accepted for publication in Sustainable Production and Consumption (Elsevier)}
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 arXiv:{ARXIV}",
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: arXiv {ARXIV} (https://arxiv.org/abs/{ARXIV})\n"
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