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.
- {saef-3.1.0 → saef-3.3.0}/PKG-INFO +87 -4
- {saef-3.1.0 → saef-3.3.0}/PYPI_README.md +83 -2
- {saef-3.1.0 → saef-3.3.0}/pyproject.toml +3 -1
- {saef-3.1.0 → saef-3.3.0}/src/saef/__init__.py +1 -1
- {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/langchain.py +95 -0
- saef-3.3.0/src/saef/mcp_server.py +203 -0
- {saef-3.1.0 → saef-3.3.0}/tests/test_integrations.py +63 -0
- saef-3.3.0/tests/test_mcp_server.py +91 -0
- {saef-3.1.0 → saef-3.3.0}/.gitignore +0 -0
- {saef-3.1.0 → saef-3.3.0}/LICENSE +0 -0
- {saef-3.1.0 → saef-3.3.0}/LICENSE-CODE +0 -0
- {saef-3.1.0 → saef-3.3.0}/cloud_region_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/factors_v3_lifecycle.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/grid_intensity_all.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/model_class_mapping.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/model_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/region_grid_crosswalk.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/region_water_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/reserved_capacity_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/scripts/sync_data.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/__main__.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/_calc.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/_core.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/cli.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/cloud_region_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/factors_v3_lifecycle.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/grid_intensity_all.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/model_class_mapping.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/model_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/region_grid_crosswalk.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/region_water_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/reserved_capacity_factors.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/data/token_basis_constants.csv +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/__init__.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/_base.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/litellm.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/src/saef/integrations/openai.py +0 -0
- {saef-3.1.0 → saef-3.3.0}/tests/test_saef.py +0 -0
- {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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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"
|
|
@@ -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
|
|
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
|