saef 3.1.0__tar.gz → 3.3.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 (39) hide show
  1. {saef-3.1.0 → saef-3.3.0}/PKG-INFO +87 -4
  2. {saef-3.1.0 → saef-3.3.0}/PYPI_README.md +83 -2
  3. {saef-3.1.0 → saef-3.3.0}/pyproject.toml +3 -1
  4. {saef-3.1.0 → saef-3.3.0}/src/saef/__init__.py +1 -1
  5. {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/langchain.py +95 -0
  6. saef-3.3.0/src/saef/mcp_server.py +203 -0
  7. {saef-3.1.0 → saef-3.3.0}/tests/test_integrations.py +63 -0
  8. saef-3.3.0/tests/test_mcp_server.py +91 -0
  9. {saef-3.1.0 → saef-3.3.0}/.gitignore +0 -0
  10. {saef-3.1.0 → saef-3.3.0}/LICENSE +0 -0
  11. {saef-3.1.0 → saef-3.3.0}/LICENSE-CODE +0 -0
  12. {saef-3.1.0 → saef-3.3.0}/cloud_region_factors.csv +0 -0
  13. {saef-3.1.0 → saef-3.3.0}/factors_v3_lifecycle.csv +0 -0
  14. {saef-3.1.0 → saef-3.3.0}/grid_intensity_all.csv +0 -0
  15. {saef-3.1.0 → saef-3.3.0}/model_class_mapping.csv +0 -0
  16. {saef-3.1.0 → saef-3.3.0}/model_factors.csv +0 -0
  17. {saef-3.1.0 → saef-3.3.0}/region_grid_crosswalk.csv +0 -0
  18. {saef-3.1.0 → saef-3.3.0}/region_water_factors.csv +0 -0
  19. {saef-3.1.0 → saef-3.3.0}/reserved_capacity_factors.csv +0 -0
  20. {saef-3.1.0 → saef-3.3.0}/scripts/sync_data.py +0 -0
  21. {saef-3.1.0 → saef-3.3.0}/src/saef/__main__.py +0 -0
  22. {saef-3.1.0 → saef-3.3.0}/src/saef/_calc.py +0 -0
  23. {saef-3.1.0 → saef-3.3.0}/src/saef/_core.py +0 -0
  24. {saef-3.1.0 → saef-3.3.0}/src/saef/cli.py +0 -0
  25. {saef-3.1.0 → saef-3.3.0}/src/saef/data/cloud_region_factors.csv +0 -0
  26. {saef-3.1.0 → saef-3.3.0}/src/saef/data/factors_v3_lifecycle.csv +0 -0
  27. {saef-3.1.0 → saef-3.3.0}/src/saef/data/grid_intensity_all.csv +0 -0
  28. {saef-3.1.0 → saef-3.3.0}/src/saef/data/model_class_mapping.csv +0 -0
  29. {saef-3.1.0 → saef-3.3.0}/src/saef/data/model_factors.csv +0 -0
  30. {saef-3.1.0 → saef-3.3.0}/src/saef/data/region_grid_crosswalk.csv +0 -0
  31. {saef-3.1.0 → saef-3.3.0}/src/saef/data/region_water_factors.csv +0 -0
  32. {saef-3.1.0 → saef-3.3.0}/src/saef/data/reserved_capacity_factors.csv +0 -0
  33. {saef-3.1.0 → saef-3.3.0}/src/saef/data/token_basis_constants.csv +0 -0
  34. {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/__init__.py +0 -0
  35. {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/_base.py +0 -0
  36. {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/litellm.py +0 -0
  37. {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/openai.py +0 -0
  38. {saef-3.1.0 → saef-3.3.0}/tests/test_saef.py +0 -0
  39. {saef-3.1.0 → saef-3.3.0}/token_basis_constants.csv +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: saef
3
- Version: 3.1.0
3
+ Version: 3.3.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
@@ -24,9 +24,11 @@ Classifier: Programming Language :: Python :: 3.13
24
24
  Classifier: Topic :: Scientific/Engineering
25
25
  Requires-Python: >=3.9
26
26
  Provides-Extra: langchain
27
- Requires-Dist: langchain-core; extra == 'langchain'
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>=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.1.0, 3.1.0
65
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.0, 3.1.0
64
66
  print(saef.citation())
65
67
  ```
66
68
 
@@ -76,17 +78,19 @@ saef cite
76
78
 
77
79
  ## Integrations
78
80
 
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 three keep running totals and can append one JSON line per call with `log_path=`.
81
+ 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
82
 
81
83
  LiteLLM, installed with `pip install "saef[litellm]"`. The estimate is also attached to `response._hidden_params["saef"]`.
82
84
 
83
85
  ```python
86
+ import time
84
87
  import litellm
85
88
  from saef.integrations.litellm import SaefLogger
86
89
 
87
90
  logger = SaefLogger(region="eu-west-1")
88
91
  litellm.callbacks = [logger]
89
92
  resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], mock_response="Hi there")
93
+ time.sleep(1) # LiteLLM runs success callbacks in a background thread
90
94
  t = logger.totals()
91
95
  print(t["calls"], t["input_tokens"], t["output_tokens"])
92
96
  print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
@@ -122,6 +126,35 @@ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
122
126
  2.894e-05 kg CO2e, 4.433e-05 high case
123
127
  ```
124
128
 
129
+ 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.
130
+
131
+ ```python
132
+ from langchain.agents import create_agent
133
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
134
+ from langchain_core.messages import AIMessage
135
+ from saef.integrations.langchain import SaefMiddleware
136
+
137
+ reply = AIMessage(
138
+ content="Hi there",
139
+ response_metadata={"model_name": "gpt-4o"},
140
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
141
+ )
142
+ llm = GenericFakeChatModel(messages=iter([reply]))
143
+ mw = SaefMiddleware(region="eu-west-1", attach=True)
144
+ agent = create_agent(llm, tools=[], middleware=[mw])
145
+ out = agent.invoke({"messages": [("user", "Hello")]})
146
+ t = mw.totals()
147
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
148
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
149
+ print(out["messages"][-1].response_metadata["saef"]["kg_co2e"])
150
+ ```
151
+
152
+ ```text
153
+ 1 400 800 300
154
+ 2.894e-05 kg CO2e, 4.433e-05 high case
155
+ 2.894105237117252e-05
156
+ ```
157
+
125
158
  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.
126
159
 
127
160
  ```python
@@ -142,6 +175,54 @@ B 2.231e-05 3.235e-05 0.0785
142
175
 
143
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"]`.
144
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
+
145
226
  ## What the numbers are
146
227
 
147
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).
@@ -185,3 +266,5 @@ Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Inte
185
266
  - Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
186
267
  - Repository: https://github.com/guillermollopis/soma-ai-emission-factors
187
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.1.0, 3.1.0
28
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.3.0, 3.1.0
29
29
  print(saef.citation())
30
30
  ```
31
31
 
@@ -41,17 +41,19 @@ saef cite
41
41
 
42
42
  ## Integrations
43
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 three keep running totals and can append one JSON line per call with `log_path=`.
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
45
 
46
46
  LiteLLM, installed with `pip install "saef[litellm]"`. The estimate is also attached to `response._hidden_params["saef"]`.
47
47
 
48
48
  ```python
49
+ import time
49
50
  import litellm
50
51
  from saef.integrations.litellm import SaefLogger
51
52
 
52
53
  logger = SaefLogger(region="eu-west-1")
53
54
  litellm.callbacks = [logger]
54
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
55
57
  t = logger.totals()
56
58
  print(t["calls"], t["input_tokens"], t["output_tokens"])
57
59
  print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
@@ -87,6 +89,35 @@ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
87
89
  2.894e-05 kg CO2e, 4.433e-05 high case
88
90
  ```
89
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
+
90
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.
91
122
 
92
123
  ```python
@@ -107,6 +138,54 @@ B 2.231e-05 3.235e-05 0.0785
107
138
 
108
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"]`.
109
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
+
110
189
  ## What the numbers are
111
190
 
112
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).
@@ -150,3 +229,5 @@ Method paper: Llopis-Garcia, G. (2026), Accounting for Purchased Artificial Inte
150
229
  - Docs: https://somaai.earth/ai-footprint/how-to/track-ai-api-emissions
151
230
  - Repository: https://github.com/guillermollopis/soma-ai-emission-factors
152
231
  - Paper: https://arxiv.org/abs/2606.10660
232
+
233
+ mcp-name: io.github.guillermollopis/saef
@@ -29,11 +29,13 @@ dependencies = []
29
29
  [project.optional-dependencies]
30
30
  pandas = ["pandas"]
31
31
  litellm = ["litellm"]
32
- langchain = ["langchain-core"]
32
+ langchain = ["langchain>=1.0"]
33
+ mcp = ["mcp>=1.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.1.0"
14
+ __version__ = "3.3.0"
15
15
 
16
16
  __all__ = [
17
17
  "DATASET_VERSION",
@@ -5,8 +5,18 @@
5
5
  handler = SaefCallbackHandler(region="eu-west-1")
6
6
  llm.invoke("hello", config={"callbacks": [handler]})
7
7
  handler.totals()
8
+
9
+ For LangChain v1 agents, SaefMiddleware (needs the `langchain` package) records one estimate per model call:
10
+
11
+ from langchain.agents import create_agent
12
+ from saef.integrations.langchain import SaefMiddleware
13
+
14
+ saef_mw = SaefMiddleware(region="eu-west-1", attach=True)
15
+ agent = create_agent("openai:gpt-4o", tools=[], middleware=[saef_mw])
16
+ saef_mw.totals()
8
17
  """
9
18
  from langchain_core.callbacks import BaseCallbackHandler
19
+ from langchain_core.messages import AIMessage
10
20
 
11
21
  from ._base import Tracker
12
22
 
@@ -88,3 +98,88 @@ class SaefCallbackHandler(BaseCallbackHandler):
88
98
  if inp + cached + out <= 0:
89
99
  return
90
100
  self._tracker.record(model, inp, out, cached, extra={"run_id": str(run_id)})
101
+
102
+
103
+ try:
104
+ from langchain.agents.middleware import AgentMiddleware, ExtendedModelResponse, ModelResponse
105
+ except ImportError:
106
+ AgentMiddleware = None
107
+
108
+
109
+ def _ai_message(result):
110
+ if isinstance(result, ExtendedModelResponse):
111
+ result = result.model_response
112
+ msgs = result.result if isinstance(result, ModelResponse) else [result]
113
+ for m in reversed(msgs):
114
+ if isinstance(m, AIMessage):
115
+ return m
116
+ return None
117
+
118
+
119
+ def _model_from_message(msg, request):
120
+ rm = msg.response_metadata or {}
121
+ model = rm.get("model_name") or rm.get("model")
122
+ if model:
123
+ return model
124
+ m = getattr(request, "model", None)
125
+ for k in ("model_name", "model", "model_id"):
126
+ v = getattr(m, k, None)
127
+ if isinstance(v, str) and v:
128
+ return v
129
+ return None
130
+
131
+
132
+ if AgentMiddleware is None:
133
+
134
+ class SaefMiddleware:
135
+ def __init__(self, *args, **kwargs):
136
+ raise ImportError('SaefMiddleware needs LangChain v1: pip install langchain')
137
+
138
+ else:
139
+
140
+ class SaefMiddleware(AgentMiddleware):
141
+ """Estimates carbon and water for every model call an agent makes, via wrap_model_call and awrap_model_call.
142
+
143
+ region defaults to env SAEF_REGION, then 'global-average'. The model name comes from the response metadata, then
144
+ from the request's chat model. Calls without a model name or without usage_metadata are not counted. With
145
+ attach=True the estimate is also written to AIMessage.response_metadata["saef"]."""
146
+
147
+ def __init__(self, region=None, log_path=None, attach=False):
148
+ super().__init__()
149
+ self._tracker = Tracker(region=region, log_path=log_path)
150
+ self.attach = attach
151
+
152
+ def totals(self):
153
+ return self._tracker.totals()
154
+
155
+ def reset(self):
156
+ self._tracker.reset()
157
+
158
+ def _record(self, request, result):
159
+ msg = _ai_message(result)
160
+ if msg is None:
161
+ return
162
+ um = msg.usage_metadata
163
+ if not um:
164
+ return
165
+ model = _model_from_message(msg, request)
166
+ if not model:
167
+ return
168
+ c = _num((um.get("input_token_details") or {}).get("cache_read"))
169
+ inp = _num(um.get("input_tokens")) - c
170
+ out = _num(um.get("output_tokens"))
171
+ if inp + c + out <= 0:
172
+ return
173
+ rec = self._tracker.record(model, inp, out, c, extra={"message_id": msg.id})
174
+ if rec and self.attach:
175
+ msg.response_metadata["saef"] = rec
176
+
177
+ def wrap_model_call(self, request, handler):
178
+ result = handler(request)
179
+ self._record(request, result)
180
+ return result
181
+
182
+ async def awrap_model_call(self, request, handler):
183
+ result = await handler(request)
184
+ self._record(request, result)
185
+ return result
@@ -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()
@@ -186,3 +186,66 @@ def test_langchain_skips_without_model_or_usage():
186
186
  h.on_llm_end(LLMResult(generations=[[Generation(text="x")]], llm_output={"token_usage": {"prompt_tokens": 1}}), run_id=uuid.uuid4())
187
187
  h.on_llm_end(LLMResult(generations=[[Generation(text="x")]], llm_output={"model_name": "gpt-4o"}), run_id=uuid.uuid4())
188
188
  assert h.totals()["calls"] == 0
189
+
190
+
191
+ def _fake_agent_parts(replies):
192
+ from langchain.agents import create_agent
193
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
194
+ from langchain_core.messages import AIMessage
195
+
196
+ msgs = [AIMessage(content="Hi there", response_metadata={"model_name": "gpt-4o"}, usage_metadata=u) for u in replies]
197
+ return create_agent, GenericFakeChatModel(messages=iter(msgs))
198
+
199
+
200
+ _USAGE = {"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}}
201
+
202
+
203
+ def test_langchain_middleware_agent_run_attaches_and_totals(tmp_path):
204
+ pytest.importorskip("langchain.agents")
205
+ from saef.integrations.langchain import SaefMiddleware
206
+
207
+ create_agent, llm = _fake_agent_parts([_USAGE])
208
+ log = tmp_path / "mw.jsonl"
209
+ mw = SaefMiddleware(region="eu-west-1", attach=True, log_path=str(log))
210
+ out = create_agent(llm, tools=[], middleware=[mw]).invoke({"messages": [("user", "Hello")]})
211
+ d = direct(model="gpt-4o", region="eu-west-1", input_tokens=400, cached_input_tokens=800, output_tokens=300)
212
+ t = mw.totals()
213
+ assert t["calls"] == 1 and t["kg_co2e"] == d.kg_co2e
214
+ assert out["messages"][-1].response_metadata["saef"]["kg_co2e"] == d.kg_co2e
215
+ assert len(log.read_text().splitlines()) == 1
216
+
217
+
218
+ def test_langchain_middleware_no_attach_by_default_and_async():
219
+ pytest.importorskip("langchain.agents")
220
+ import asyncio
221
+
222
+ from saef.integrations.langchain import SaefMiddleware
223
+
224
+ create_agent, llm = _fake_agent_parts([_USAGE, _USAGE])
225
+ mw = SaefMiddleware(region="eu-west-1")
226
+ agent = create_agent(llm, tools=[], middleware=[mw])
227
+ out = agent.invoke({"messages": [("user", "Hello")]})
228
+ assert "saef" not in out["messages"][-1].response_metadata
229
+ asyncio.run(agent.ainvoke({"messages": [("user", "Again")]}))
230
+ assert mw.totals()["calls"] == 2
231
+ mw.reset()
232
+ assert mw.totals()["calls"] == 0
233
+
234
+
235
+ def test_langchain_middleware_skips_without_usage_and_falls_back_to_request_model():
236
+ pytest.importorskip("langchain.agents")
237
+ from langchain_core.messages import AIMessage
238
+
239
+ from saef.integrations.langchain import SaefMiddleware
240
+
241
+ class M:
242
+ model_name = "gpt-4o"
243
+
244
+ class R:
245
+ model = M()
246
+
247
+ mw = SaefMiddleware(region="eu-west-1")
248
+ mw.wrap_model_call(R(), lambda r: AIMessage(content="x"))
249
+ assert mw.totals()["calls"] == 0
250
+ mw.wrap_model_call(R(), lambda r: AIMessage(content="x", usage_metadata={"input_tokens": 10, "output_tokens": 5, "total_tokens": 15}))
251
+ assert mw.totals()["calls"] == 1
@@ -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