saef 3.2.0__tar.gz → 3.3.1__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.2.0 → saef-3.3.1}/PKG-INFO +54 -2
  2. {saef-3.2.0 → saef-3.3.1}/PYPI_README.md +51 -1
  3. {saef-3.2.0 → saef-3.3.1}/pyproject.toml +2 -0
  4. {saef-3.2.0 → saef-3.3.1}/src/saef/__init__.py +1 -1
  5. saef-3.3.1/src/saef/mcp_server.py +203 -0
  6. saef-3.3.1/tests/test_mcp_server.py +91 -0
  7. {saef-3.2.0 → saef-3.3.1}/.gitignore +0 -0
  8. {saef-3.2.0 → saef-3.3.1}/LICENSE +0 -0
  9. {saef-3.2.0 → saef-3.3.1}/LICENSE-CODE +0 -0
  10. {saef-3.2.0 → saef-3.3.1}/cloud_region_factors.csv +0 -0
  11. {saef-3.2.0 → saef-3.3.1}/factors_v3_lifecycle.csv +0 -0
  12. {saef-3.2.0 → saef-3.3.1}/grid_intensity_all.csv +0 -0
  13. {saef-3.2.0 → saef-3.3.1}/model_class_mapping.csv +0 -0
  14. {saef-3.2.0 → saef-3.3.1}/model_factors.csv +0 -0
  15. {saef-3.2.0 → saef-3.3.1}/region_grid_crosswalk.csv +0 -0
  16. {saef-3.2.0 → saef-3.3.1}/region_water_factors.csv +0 -0
  17. {saef-3.2.0 → saef-3.3.1}/reserved_capacity_factors.csv +0 -0
  18. {saef-3.2.0 → saef-3.3.1}/scripts/sync_data.py +0 -0
  19. {saef-3.2.0 → saef-3.3.1}/src/saef/__main__.py +0 -0
  20. {saef-3.2.0 → saef-3.3.1}/src/saef/_calc.py +0 -0
  21. {saef-3.2.0 → saef-3.3.1}/src/saef/_core.py +0 -0
  22. {saef-3.2.0 → saef-3.3.1}/src/saef/cli.py +0 -0
  23. {saef-3.2.0 → saef-3.3.1}/src/saef/data/cloud_region_factors.csv +0 -0
  24. {saef-3.2.0 → saef-3.3.1}/src/saef/data/factors_v3_lifecycle.csv +0 -0
  25. {saef-3.2.0 → saef-3.3.1}/src/saef/data/grid_intensity_all.csv +0 -0
  26. {saef-3.2.0 → saef-3.3.1}/src/saef/data/model_class_mapping.csv +0 -0
  27. {saef-3.2.0 → saef-3.3.1}/src/saef/data/model_factors.csv +0 -0
  28. {saef-3.2.0 → saef-3.3.1}/src/saef/data/region_grid_crosswalk.csv +0 -0
  29. {saef-3.2.0 → saef-3.3.1}/src/saef/data/region_water_factors.csv +0 -0
  30. {saef-3.2.0 → saef-3.3.1}/src/saef/data/reserved_capacity_factors.csv +0 -0
  31. {saef-3.2.0 → saef-3.3.1}/src/saef/data/token_basis_constants.csv +0 -0
  32. {saef-3.2.0 → saef-3.3.1}/src/saef/integrations/__init__.py +0 -0
  33. {saef-3.2.0 → saef-3.3.1}/src/saef/integrations/_base.py +0 -0
  34. {saef-3.2.0 → saef-3.3.1}/src/saef/integrations/langchain.py +0 -0
  35. {saef-3.2.0 → saef-3.3.1}/src/saef/integrations/litellm.py +0 -0
  36. {saef-3.2.0 → saef-3.3.1}/src/saef/integrations/openai.py +0 -0
  37. {saef-3.2.0 → saef-3.3.1}/tests/test_integrations.py +0 -0
  38. {saef-3.2.0 → saef-3.3.1}/tests/test_saef.py +0 -0
  39. {saef-3.2.0 → saef-3.3.1}/token_basis_constants.csv +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: saef
3
- Version: 3.2.0
3
+ Version: 3.3.1
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
@@ -27,6 +27,8 @@ Provides-Extra: langchain
27
27
  Requires-Dist: langchain>=1.0; extra == 'langchain'
28
28
  Provides-Extra: litellm
29
29
  Requires-Dist: litellm; extra == 'litellm'
30
+ Provides-Extra: mcp
31
+ Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
30
32
  Provides-Extra: pandas
31
33
  Requires-Dist: pandas; extra == 'pandas'
32
34
  Provides-Extra: test
@@ -60,7 +62,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
60
62
  print(r.water_ml) # mL, or None where the region has no water factor
61
63
  for s in r.provenance[:3]:
62
64
  print(s["file"], s["line"], s["column"]) # the file, line and column behind each number
63
- print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.2.0, 3.1.0
65
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.1, 3.1.0
64
66
  print(saef.citation())
65
67
  ```
66
68
 
@@ -173,6 +175,54 @@ B 2.231e-05 3.235e-05 0.0785
173
175
 
174
176
  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
177
 
178
+ ## MCP server
179
+
180
+ 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.
181
+
182
+ ```bash
183
+ pip install "saef[mcp]"
184
+ ```
185
+
186
+ Claude Code.
187
+
188
+ ```bash
189
+ claude mcp add saef -- saef-mcp
190
+ ```
191
+
192
+ Claude Desktop, in `claude_desktop_config.json`.
193
+
194
+ ```json
195
+ {
196
+ "mcpServers": {
197
+ "saef": { "command": "saef-mcp" }
198
+ }
199
+ }
200
+ ```
201
+
202
+ Cursor, in `.cursor/mcp.json`.
203
+
204
+ ```json
205
+ {
206
+ "mcpServers": {
207
+ "saef": { "command": "saef-mcp" }
208
+ }
209
+ }
210
+ ```
211
+
212
+ If `saef-mcp` is not on your PATH, use `uvx --from "saef[mcp]" saef-mcp` as the command instead.
213
+
214
+ Tools.
215
+
216
+ - `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.
217
+ - `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).
218
+ - `model_class(model)` returns the class letter (A small, B mid-size, C large) and a description.
219
+ - `list_regions()` returns the accepted region codes, with names for cloud regions and countries.
220
+ - `compare_regions(tokens, model, regions)` returns carbon and water per region, sorted from lowest to highest carbon.
221
+
222
+ The server also exposes the resource `saef://about` with the licence, DOI and method paper. Every figure is an estimate, not a measurement.
223
+
224
+ 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?"
225
+
176
226
  ## What the numbers are
177
227
 
178
228
  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).
@@ -216,3 +266,5 @@ Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Inte
216
266
  - Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
217
267
  - Repository: https://github.com/guillermollopis/soma-ai-emission-factors
218
268
  - Paper: https://arxiv.org/abs/2606.10660
269
+
270
+ mcp-name: io.github.guillermollopis/saef
@@ -25,7 +25,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
25
25
  print(r.water_ml) # mL, or None where the region has no water factor
26
26
  for s in r.provenance[:3]:
27
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
28
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.1, 3.1.0
29
29
  print(saef.citation())
30
30
  ```
31
31
 
@@ -138,6 +138,54 @@ B 2.231e-05 3.235e-05 0.0785
138
138
 
139
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
140
 
141
+ ## MCP server
142
+
143
+ 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.
144
+
145
+ ```bash
146
+ pip install "saef[mcp]"
147
+ ```
148
+
149
+ Claude Code.
150
+
151
+ ```bash
152
+ claude mcp add saef -- saef-mcp
153
+ ```
154
+
155
+ Claude Desktop, in `claude_desktop_config.json`.
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "saef": { "command": "saef-mcp" }
161
+ }
162
+ }
163
+ ```
164
+
165
+ Cursor, in `.cursor/mcp.json`.
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "saef": { "command": "saef-mcp" }
171
+ }
172
+ }
173
+ ```
174
+
175
+ If `saef-mcp` is not on your PATH, use `uvx --from "saef[mcp]" saef-mcp` as the command instead.
176
+
177
+ Tools.
178
+
179
+ - `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.
180
+ - `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).
181
+ - `model_class(model)` returns the class letter (A small, B mid-size, C large) and a description.
182
+ - `list_regions()` returns the accepted region codes, with names for cloud regions and countries.
183
+ - `compare_regions(tokens, model, regions)` returns carbon and water per region, sorted from lowest to highest carbon.
184
+
185
+ The server also exposes the resource `saef://about` with the licence, DOI and method paper. Every figure is an estimate, not a measurement.
186
+
187
+ 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?"
188
+
141
189
  ## What the numbers are
142
190
 
143
191
  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).
@@ -181,3 +229,5 @@ Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Inte
181
229
  - Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
182
230
  - Repository: https://github.com/guillermollopis/soma-ai-emission-factors
183
231
  - Paper: https://arxiv.org/abs/2606.10660
232
+
233
+ mcp-name: io.github.guillermollopis/saef
@@ -30,10 +30,12 @@ dependencies = []
30
30
  pandas = ["pandas"]
31
31
  litellm = ["litellm"]
32
32
  langchain = ["langchain>=1.0"]
33
+ mcp = ["mcp>=1.2,<2"]
33
34
  test = ["pytest"]
34
35
 
35
36
  [project.scripts]
36
37
  saef = "saef.cli:main"
38
+ saef-mcp = "saef.mcp_server:main"
37
39
 
38
40
  [project.urls]
39
41
  Homepage = "https://somaai.earth/ai-footprint"
@@ -11,7 +11,7 @@ from ._core import (
11
11
  regions,
12
12
  )
13
13
 
14
- __version__ = "3.2.0"
14
+ __version__ = "3.3.1"
15
15
 
16
16
  __all__ = [
17
17
  "DATASET_VERSION",
@@ -0,0 +1,203 @@
1
+ """MCP server exposing SAEF estimates to AI agents over stdio. Needs the optional `mcp` extra."""
2
+ from mcp.server.fastmcp import FastMCP
3
+
4
+ from . import DATASET_VERSION, SaefError, __version__, estimate, model_class_for
5
+ from . import _calc
6
+
7
+ EXCHANGE_INPUT_TOKENS = 928
8
+ EXCHANGE_OUTPUT_TOKENS = 282
9
+ EXCHANGE_TOKENS = EXCHANGE_INPUT_TOKENS + EXCHANGE_OUTPUT_TOKENS
10
+
11
+ CLASS_DESCRIPTIONS = {
12
+ "A": "small model (for example mini, nano, flash or 8B to 14B open-weight models)",
13
+ "B": "mid-size model (for example GPT-4o, Claude Sonnet, Gemini Pro)",
14
+ "C": "large or frontier model (for example the largest GPT, Claude Opus or Gemini Ultra tiers)",
15
+ }
16
+
17
+ DOI = "10.5281/zenodo.20443585"
18
+ ARXIV = "2606.10660"
19
+ HOMEPAGE = "https://somaai.earth/ai-footprint"
20
+ NOTE = "Estimate, not a measurement. SOMA AI Emission Factors (SAEF) factors are modelled from published benchmarks and grid data."
21
+
22
+ mcp = FastMCP("saef")
23
+
24
+
25
+ def _check_tokens(tokens):
26
+ if tokens < 0:
27
+ raise ValueError("tokens must be >= 0")
28
+
29
+
30
+ def _report(e):
31
+ grid = e.grid_kg_co2e_per_kwh
32
+ out = {
33
+ "carbon": {
34
+ "kg_co2e": e.kg_co2e,
35
+ "g_co2e": e.kg_co2e * 1000,
36
+ "high_case_kg_co2e": e.kg_co2e_high_case,
37
+ "high_case_g_co2e": e.kg_co2e_high_case * 1000,
38
+ "note": "kg_co2e is the central case. The high case is a conservative upper bound.",
39
+ },
40
+ "model": e.model,
41
+ "model_class": e.model_class,
42
+ "class_basis": e.class_basis,
43
+ "region_used": e.region_id,
44
+ "grid_kg_co2e_per_kwh": grid,
45
+ "billed_tokens": e.billed_tokens,
46
+ "dataset_version": e.version,
47
+ "warnings": e.warnings,
48
+ "provenance": e.provenance,
49
+ "citation": f"SOMA AI Emission Factors (SAEF) v{e.version}, doi:{DOI}; method paper arXiv:{ARXIV}",
50
+ "note": NOTE,
51
+ }
52
+ if grid > 0:
53
+ out["energy"] = {
54
+ "facility_wh": e.terms_kg_co2e["electricity"] / grid * 1000,
55
+ "note": "Facility-level electricity including cooling and overhead, derived from the electricity term and the grid intensity.",
56
+ }
57
+ if e.water_ml is not None:
58
+ out["water"] = {
59
+ "ml": e.water_ml,
60
+ "ml_excluding_hydropower_allocation": e.water_ml_excl_hydro,
61
+ "note": "Two hydropower conventions exist and neither is preferred. ml allocates reservoir evaporation to electricity.",
62
+ }
63
+ else:
64
+ out["water"] = {"ml": None, "note": "No water factor for this region. Water is not available, not zero."}
65
+ return out
66
+
67
+
68
+ @mcp.tool()
69
+ def estimate_footprint(tokens: int, model: str, region: str = "global") -> dict:
70
+ """Estimate carbon, energy and water for AI inference using SOMA AI Emission Factors (SAEF).
71
+
72
+ Args:
73
+ tokens: Billed tokens, input plus output, as shown on the provider invoice or usage page.
74
+ model: Model identifier such as "gpt-4o", "claude-sonnet-4-5" or "gemini-2.5-flash". Unmapped models are treated as the conservative class C.
75
+ region: Cloud region id (for example "eu-west-1", "us-east-1"), ISO-3 country code (for example "ESP"), eGRID subregion, "eu-27" or "global" for the world-average grid. Use list_regions to see options.
76
+
77
+ 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 (A small, B mid-size, C large), the region used, the dataset version and a provenance trail to the source CSV rows.
78
+ All figures are estimates, not measurements. They exclude model training development lines and are intended for Scope 3 category 1 reporting.
79
+ """
80
+ _check_tokens(tokens)
81
+ return _report(estimate(tokens=tokens, model=model, region=region))
82
+
83
+
84
+ @mcp.tool()
85
+ def estimate_chat_usage(messages: int, model: str, region: str = "global") -> dict:
86
+ """Estimate carbon, energy and water for chat usage, counted in messages, using SOMA AI Emission Factors (SAEF).
87
+
88
+ Each message is one chat exchange (a question and its answer) of 1,210 tokens, the dataset's short-chat default of 928 input and 282 output tokens. Long documents, coding agents and reasoning modes use far more tokens, so use estimate_footprint when you know the token count.
89
+
90
+ Args:
91
+ messages: Number of chat exchanges.
92
+ model: Model identifier such as "gpt-4o" or "claude-sonnet-4-5".
93
+ region: Cloud region id, ISO-3 country code, eGRID subregion, "eu-27" or "global". Use list_regions to see options.
94
+
95
+ Same output as estimate_footprint, plus the token assumption used. All figures are estimates, not measurements.
96
+ """
97
+ if messages < 0:
98
+ raise ValueError("messages must be >= 0")
99
+ e = estimate(
100
+ model=model, region=region,
101
+ input_tokens=EXCHANGE_INPUT_TOKENS * messages, output_tokens=EXCHANGE_OUTPUT_TOKENS * messages,
102
+ )
103
+ out = _report(e)
104
+ out["messages"] = messages
105
+ out["assumption"] = (
106
+ f"{EXCHANGE_TOKENS} tokens per exchange ({EXCHANGE_INPUT_TOKENS} input, {EXCHANGE_OUTPUT_TOKENS} output), "
107
+ "the SAEF short-chat default"
108
+ )
109
+ return out
110
+
111
+
112
+ @mcp.tool()
113
+ def model_class(model: str) -> dict:
114
+ """Return the SAEF model class (A small, B mid-size, C large) for a model identifier.
115
+
116
+ SOMA AI Emission Factors (SAEF) assign factors by class, not by brand. A model that matches no known pattern gets the conservative class C. Embeddings, image, audio, video and moderation models are out of scope and return an error.
117
+ """
118
+ cls = model_class_for(model)
119
+ return {"model": model, "model_class": cls, "description": CLASS_DESCRIPTIONS[cls], "dataset_version": DATASET_VERSION}
120
+
121
+
122
+ @mcp.tool()
123
+ def list_regions() -> dict:
124
+ """List the region codes accepted by the other SAEF tools.
125
+
126
+ Returns the special values ("global", "eu-27"), the cloud regions of AWS, Azure and Google Cloud with names, and how to pass a country. Any ISO-3 country code (for example "ESP", "DEU", "USA") or eGRID subregion (for example "RFCE") also works.
127
+ """
128
+ cloud = [
129
+ {"region": r["region_id"], "provider": r["provider"], "name": r["region_name"]}
130
+ for r in _calc.read("cloud_region_factors.csv")
131
+ ]
132
+ cloud.sort(key=lambda r: (r["provider"], r["region"]))
133
+ countries = {r["grid_id"]: r["name"] for r in _calc.read("grid_intensity_all.csv") if r["kind"] == "country"}
134
+ return {
135
+ "special": {"global": "world-average grid", "eu-27": "EU-27 average grid"},
136
+ "cloud_regions": cloud,
137
+ "country_codes": countries,
138
+ "dataset_version": DATASET_VERSION,
139
+ }
140
+
141
+
142
+ @mcp.tool()
143
+ def compare_regions(tokens: int, model: str, regions: list[str]) -> dict:
144
+ """Compare the carbon and water estimate for the same workload across regions using SOMA AI Emission Factors (SAEF).
145
+
146
+ Args:
147
+ tokens: Billed tokens, input plus output.
148
+ model: Model identifier such as "gpt-4o".
149
+ regions: Region codes to compare, for example ["eu-north-1", "us-east-1", "ap-south-1"]. See list_regions.
150
+
151
+ Returns one row per region, sorted from lowest to highest carbon, with kg and g CO2e (central and high case) and water in mL. The lowest-carbon grid is not always the lowest-water one. A region that is not recognised gets an error entry instead of failing the whole call. Estimates, not measurements.
152
+ """
153
+ _check_tokens(tokens)
154
+ rows = []
155
+ errors = []
156
+ cls = None
157
+ for region in regions:
158
+ try:
159
+ e = estimate(tokens=tokens, model=model, region=region)
160
+ except SaefError as exc:
161
+ errors.append({"region": region, "error": str(exc)})
162
+ continue
163
+ cls = e.model_class
164
+ rows.append({
165
+ "region": region,
166
+ "region_used": e.region_id,
167
+ "kg_co2e": e.kg_co2e,
168
+ "g_co2e": e.kg_co2e * 1000,
169
+ "high_case_kg_co2e": e.kg_co2e_high_case,
170
+ "water_ml": e.water_ml,
171
+ })
172
+ rows.sort(key=lambda r: r["kg_co2e"])
173
+ return {
174
+ "tokens": tokens,
175
+ "model": model,
176
+ "model_class": cls,
177
+ "regions": rows,
178
+ "errors": errors,
179
+ "dataset_version": DATASET_VERSION,
180
+ "note": NOTE,
181
+ }
182
+
183
+
184
+ @mcp.resource("saef://about")
185
+ def about() -> str:
186
+ """About SAEF, its licence, citation and links."""
187
+ return (
188
+ f"SOMA AI Emission Factors (SAEF), package saef {__version__}, dataset v{DATASET_VERSION}.\n"
189
+ "Open, versioned estimates of carbon (kg CO2e), energy and water for AI inference, per token, by model class and region, "
190
+ "for Scope 3 category 1 reporting. All figures are estimates, not measurements.\n"
191
+ "Licence: data CC BY 4.0, code MIT.\n"
192
+ f"Dataset DOI: {DOI} (https://doi.org/{DOI})\n"
193
+ f"Method paper: arXiv {ARXIV} (https://arxiv.org/abs/{ARXIV})\n"
194
+ f"Homepage: {HOMEPAGE}\n"
195
+ )
196
+
197
+
198
+ def main():
199
+ mcp.run(transport="stdio")
200
+
201
+
202
+ if __name__ == "__main__":
203
+ main()
@@ -0,0 +1,91 @@
1
+ import pytest
2
+
3
+ pytest.importorskip("mcp")
4
+
5
+ import saef
6
+ from saef import mcp_server as m
7
+
8
+
9
+ def test_estimate_footprint_matches_core():
10
+ r = m.estimate_footprint(1_000_000, "gpt-4o", "eu-west-1")
11
+ e = saef.estimate(tokens=1_000_000, model="gpt-4o", region="eu-west-1")
12
+ assert r["carbon"]["kg_co2e"] == e.kg_co2e
13
+ assert r["carbon"]["g_co2e"] == pytest.approx(e.kg_co2e * 1000)
14
+ assert r["carbon"]["high_case_kg_co2e"] >= r["carbon"]["kg_co2e"]
15
+ assert r["water"]["ml"] == e.water_ml
16
+ assert r["model_class"] == "B"
17
+ assert r["region_used"] == "eu-west-1"
18
+ assert r["dataset_version"] == saef.DATASET_VERSION
19
+ assert r["provenance"]
20
+ assert "not a measurement" in r["note"]
21
+
22
+
23
+ def test_energy_matches_readme_figure_for_class_b_chat():
24
+ r = m.estimate_chat_usage(1, "gpt-4o")
25
+ assert r["energy"]["facility_wh"] == pytest.approx(0.099, abs=0.001)
26
+ assert "1210" in r["assumption"]
27
+
28
+
29
+ def test_chat_usage_scales_linearly():
30
+ one = m.estimate_chat_usage(1, "gpt-4o", "eu-west-1")
31
+ ten = m.estimate_chat_usage(10, "gpt-4o", "eu-west-1")
32
+ assert ten["carbon"]["kg_co2e"] == pytest.approx(one["carbon"]["kg_co2e"] * 10)
33
+ assert ten["messages"] == 10
34
+
35
+
36
+ def test_global_region_has_no_water():
37
+ r = m.estimate_footprint(1000, "gpt-4o")
38
+ assert r["water"]["ml"] is None
39
+ assert r["region_used"] == "global-average"
40
+
41
+
42
+ def test_model_class():
43
+ r = m.model_class("gpt-4o")
44
+ assert r["model_class"] == "B"
45
+ assert r["description"]
46
+ assert m.model_class("totally-unknown-model")["model_class"] == "C"
47
+
48
+
49
+ def test_out_of_scope_model_raises():
50
+ with pytest.raises(saef.SaefError):
51
+ m.model_class("text-embedding-3-small")
52
+
53
+
54
+ def test_list_regions():
55
+ r = m.list_regions()
56
+ ids = {c["region"] for c in r["cloud_regions"]}
57
+ assert "eu-west-1" in ids
58
+ assert "ESP" in r["country_codes"]
59
+ assert "global" in r["special"]
60
+
61
+
62
+ def test_compare_regions_sorted_with_bad_region_reported():
63
+ r = m.compare_regions(1_000_000, "gpt-4o", ["us-east-1", "eu-north-1", "nowhere-land"])
64
+ names = [x["region"] for x in r["regions"]]
65
+ assert set(names) == {"us-east-1", "eu-north-1"}
66
+ assert r["regions"][0]["kg_co2e"] <= r["regions"][1]["kg_co2e"]
67
+ assert names[0] == "eu-north-1"
68
+ assert r["errors"][0]["region"] == "nowhere-land"
69
+ assert r["model_class"] == "B"
70
+
71
+
72
+ def test_negative_tokens_rejected():
73
+ with pytest.raises(ValueError):
74
+ m.estimate_footprint(-1, "gpt-4o")
75
+ with pytest.raises(ValueError):
76
+ m.estimate_chat_usage(-1, "gpt-4o")
77
+
78
+
79
+ def test_about_resource_and_registration():
80
+ text = m.about()
81
+ for s in ("10.5281/zenodo.20443585", "2606.10660", "https://somaai.earth/ai-footprint", "CC BY 4.0"):
82
+ assert s in text
83
+
84
+
85
+ def test_tools_and_resource_registered():
86
+ import asyncio
87
+
88
+ tools = {t.name for t in asyncio.run(m.mcp.list_tools())}
89
+ assert tools == {"estimate_footprint", "estimate_chat_usage", "model_class", "list_regions", "compare_regions"}
90
+ uris = {str(r.uri) for r in asyncio.run(m.mcp.list_resources())}
91
+ assert "saef://about" in uris
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