saef 3.1.0__tar.gz → 3.2.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 (37) hide show
  1. {saef-3.1.0 → saef-3.2.0}/PKG-INFO +35 -4
  2. {saef-3.1.0 → saef-3.2.0}/PYPI_README.md +33 -2
  3. {saef-3.1.0 → saef-3.2.0}/pyproject.toml +1 -1
  4. {saef-3.1.0 → saef-3.2.0}/src/saef/__init__.py +1 -1
  5. {saef-3.1.0 → saef-3.2.0}/src/saef/integrations/langchain.py +95 -0
  6. {saef-3.1.0 → saef-3.2.0}/tests/test_integrations.py +63 -0
  7. {saef-3.1.0 → saef-3.2.0}/.gitignore +0 -0
  8. {saef-3.1.0 → saef-3.2.0}/LICENSE +0 -0
  9. {saef-3.1.0 → saef-3.2.0}/LICENSE-CODE +0 -0
  10. {saef-3.1.0 → saef-3.2.0}/cloud_region_factors.csv +0 -0
  11. {saef-3.1.0 → saef-3.2.0}/factors_v3_lifecycle.csv +0 -0
  12. {saef-3.1.0 → saef-3.2.0}/grid_intensity_all.csv +0 -0
  13. {saef-3.1.0 → saef-3.2.0}/model_class_mapping.csv +0 -0
  14. {saef-3.1.0 → saef-3.2.0}/model_factors.csv +0 -0
  15. {saef-3.1.0 → saef-3.2.0}/region_grid_crosswalk.csv +0 -0
  16. {saef-3.1.0 → saef-3.2.0}/region_water_factors.csv +0 -0
  17. {saef-3.1.0 → saef-3.2.0}/reserved_capacity_factors.csv +0 -0
  18. {saef-3.1.0 → saef-3.2.0}/scripts/sync_data.py +0 -0
  19. {saef-3.1.0 → saef-3.2.0}/src/saef/__main__.py +0 -0
  20. {saef-3.1.0 → saef-3.2.0}/src/saef/_calc.py +0 -0
  21. {saef-3.1.0 → saef-3.2.0}/src/saef/_core.py +0 -0
  22. {saef-3.1.0 → saef-3.2.0}/src/saef/cli.py +0 -0
  23. {saef-3.1.0 → saef-3.2.0}/src/saef/data/cloud_region_factors.csv +0 -0
  24. {saef-3.1.0 → saef-3.2.0}/src/saef/data/factors_v3_lifecycle.csv +0 -0
  25. {saef-3.1.0 → saef-3.2.0}/src/saef/data/grid_intensity_all.csv +0 -0
  26. {saef-3.1.0 → saef-3.2.0}/src/saef/data/model_class_mapping.csv +0 -0
  27. {saef-3.1.0 → saef-3.2.0}/src/saef/data/model_factors.csv +0 -0
  28. {saef-3.1.0 → saef-3.2.0}/src/saef/data/region_grid_crosswalk.csv +0 -0
  29. {saef-3.1.0 → saef-3.2.0}/src/saef/data/region_water_factors.csv +0 -0
  30. {saef-3.1.0 → saef-3.2.0}/src/saef/data/reserved_capacity_factors.csv +0 -0
  31. {saef-3.1.0 → saef-3.2.0}/src/saef/data/token_basis_constants.csv +0 -0
  32. {saef-3.1.0 → saef-3.2.0}/src/saef/integrations/__init__.py +0 -0
  33. {saef-3.1.0 → saef-3.2.0}/src/saef/integrations/_base.py +0 -0
  34. {saef-3.1.0 → saef-3.2.0}/src/saef/integrations/litellm.py +0 -0
  35. {saef-3.1.0 → saef-3.2.0}/src/saef/integrations/openai.py +0 -0
  36. {saef-3.1.0 → saef-3.2.0}/tests/test_saef.py +0 -0
  37. {saef-3.1.0 → saef-3.2.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.2.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,7 +24,7 @@ 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
30
  Provides-Extra: pandas
@@ -60,7 +60,7 @@ print(r.kg_co2e, r.kg_co2e_high_case) # central and conservative hig
60
60
  print(r.water_ml) # mL, or None where the region has no water factor
61
61
  for s in r.provenance[:3]:
62
62
  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
63
+ print(len(saef.regions()), saef.__version__, saef.DATASET_VERSION) # 143 cloud regions, 3.2.0, 3.1.0
64
64
  print(saef.citation())
65
65
  ```
66
66
 
@@ -76,17 +76,19 @@ saef cite
76
76
 
77
77
  ## Integrations
78
78
 
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=`.
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 of them keep running totals and can append one JSON line per call with `log_path=`.
80
80
 
81
81
  LiteLLM, installed with `pip install "saef[litellm]"`. The estimate is also attached to `response._hidden_params["saef"]`.
82
82
 
83
83
  ```python
84
+ import time
84
85
  import litellm
85
86
  from saef.integrations.litellm import SaefLogger
86
87
 
87
88
  logger = SaefLogger(region="eu-west-1")
88
89
  litellm.callbacks = [logger]
89
90
  resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], mock_response="Hi there")
91
+ time.sleep(1) # LiteLLM runs success callbacks in a background thread
90
92
  t = logger.totals()
91
93
  print(t["calls"], t["input_tokens"], t["output_tokens"])
92
94
  print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case, {t['water_ml']:.4f} mL")
@@ -122,6 +124,35 @@ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
122
124
  2.894e-05 kg CO2e, 4.433e-05 high case
123
125
  ```
124
126
 
127
+ 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.
128
+
129
+ ```python
130
+ from langchain.agents import create_agent
131
+ from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
132
+ from langchain_core.messages import AIMessage
133
+ from saef.integrations.langchain import SaefMiddleware
134
+
135
+ reply = AIMessage(
136
+ content="Hi there",
137
+ response_metadata={"model_name": "gpt-4o"},
138
+ usage_metadata={"input_tokens": 1200, "output_tokens": 300, "total_tokens": 1500, "input_token_details": {"cache_read": 800}},
139
+ )
140
+ llm = GenericFakeChatModel(messages=iter([reply]))
141
+ mw = SaefMiddleware(region="eu-west-1", attach=True)
142
+ agent = create_agent(llm, tools=[], middleware=[mw])
143
+ out = agent.invoke({"messages": [("user", "Hello")]})
144
+ t = mw.totals()
145
+ print(t["calls"], t["input_tokens"], t["cached_input_tokens"], t["output_tokens"])
146
+ print(f"{t['kg_co2e']:.3e} kg CO2e, {t['kg_co2e_high_case']:.3e} high case")
147
+ print(out["messages"][-1].response_metadata["saef"]["kg_co2e"])
148
+ ```
149
+
150
+ ```text
151
+ 1 400 800 300
152
+ 2.894e-05 kg CO2e, 4.433e-05 high case
153
+ 2.894105237117252e-05
154
+ ```
155
+
125
156
  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
157
 
127
158
  ```python
@@ -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.2.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
@@ -29,7 +29,7 @@ dependencies = []
29
29
  [project.optional-dependencies]
30
30
  pandas = ["pandas"]
31
31
  litellm = ["litellm"]
32
- langchain = ["langchain-core"]
32
+ langchain = ["langchain>=1.0"]
33
33
  test = ["pytest"]
34
34
 
35
35
  [project.scripts]
@@ -11,7 +11,7 @@ from ._core import (
11
11
  regions,
12
12
  )
13
13
 
14
- __version__ = "3.1.0"
14
+ __version__ = "3.2.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
@@ -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
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