saef 3.0.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,27 @@
1
+ """SOMA AI Emission Factors (SAEF): estimated carbon and water factors for AI inference."""
2
+ from ._core import (
3
+ DATASET_VERSION,
4
+ Estimate,
5
+ SaefError,
6
+ citation,
7
+ estimate,
8
+ factor,
9
+ grids,
10
+ model_class_for,
11
+ regions,
12
+ )
13
+
14
+ __version__ = DATASET_VERSION
15
+
16
+ __all__ = [
17
+ "DATASET_VERSION",
18
+ "Estimate",
19
+ "SaefError",
20
+ "__version__",
21
+ "citation",
22
+ "estimate",
23
+ "factor",
24
+ "grids",
25
+ "model_class_for",
26
+ "regions",
27
+ ]
saef/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
saef/_calc.py ADDED
@@ -0,0 +1,350 @@
1
+ """Calculator for the SAEF v3 lifecycle-boundary tables. Reads only the bundled CSVs.
2
+
3
+ Method (dataset V3_LIFECYCLE_SPEC.md, section 10):
4
+ kg CO2e = T_eff / 1e6 x inference footprint + T_billed / 1e6 x training term
5
+ T_eff = (T_out + W_in x T_in_uncached + W_cache x T_in_cached) / D
6
+ Never multiply a billed token count by an inference footprint.
7
+ """
8
+ import csv
9
+ import difflib
10
+ import io
11
+ import re
12
+ from functools import lru_cache
13
+ from importlib import resources
14
+
15
+ PATH_NOISE = {
16
+ "models", "model", "publishers", "registries", "versions", "version", "projects", "locations",
17
+ "deployments", "inference-profile", "inference-profiles", "endpoints", "foundry", "openai",
18
+ "azureml:", "azureml", "arn:aws:bedrock:", "providers", "catalogs", "assets",
19
+ }
20
+ DOT_REGION = {"us", "eu", "apac", "us-gov", "global", "jp", "au", "ca", "sa", "me", "il", "uk", "in"}
21
+ DOT_VENDOR = {
22
+ "anthropic", "amazon", "meta", "mistral", "cohere", "ai21", "stability", "deepseek", "openai",
23
+ "google", "writer", "luma", "twelvelabs", "qwen", "nvidia", "moonshot", "zai", "minimax",
24
+ "microsoft", "xai", "alibaba", "tencent", "baidu", "perplexity", "snowflake", "databricks",
25
+ }
26
+ UNKNOWN_REGION = {"", "unknown", "global", "global-average", "world", "any", "none", "mixed", "multi-region"}
27
+ EU27_REGION = {"eu-27", "eu27", "eu", "eu-only", "eu data zone", "european union"}
28
+
29
+
30
+ class SaefError(ValueError):
31
+ pass
32
+
33
+
34
+ @lru_cache(maxsize=None)
35
+ def read(name):
36
+ text = resources.files("saef").joinpath("data", name).read_text(encoding="utf-8")
37
+ rows = list(csv.DictReader(io.StringIO(text, newline="")))
38
+ for i, r in enumerate(rows, 2):
39
+ r["_file"], r["_line"] = name, i
40
+ return tuple(rows)
41
+
42
+
43
+ def prov(out, quantity, row, col):
44
+ out.append({"quantity": quantity, "file": row["_file"], "line": row["_line"], "column": col, "value": row[col]})
45
+
46
+
47
+ @lru_cache(maxsize=None)
48
+ def constants():
49
+ return {r["constant"]: r for r in read("token_basis_constants.csv")}
50
+
51
+
52
+ def const(name):
53
+ return float(constants()[name]["central"])
54
+
55
+
56
+ def normalise_identifier(identifier):
57
+ s = str(identifier).strip().lower()
58
+ cands = [s]
59
+ body = s
60
+ if body.startswith("arn:aws:bedrock:"):
61
+ body = body.rsplit("/", 1)[-1]
62
+ segs = [x for x in body.split("/") if x and x not in PATH_NOISE and not x.isdigit()]
63
+ if segs:
64
+ body = segs[-1]
65
+ cands.append(body)
66
+ stripped, dropped = body, []
67
+ while "." in stripped:
68
+ head, rest = stripped.split(".", 1)
69
+ if head in DOT_REGION or head in DOT_VENDOR:
70
+ dropped.append(head)
71
+ stripped = rest
72
+ else:
73
+ break
74
+ if stripped != body:
75
+ cands.append(stripped)
76
+ if dropped and dropped[-1] in DOT_VENDOR:
77
+ cands.append(f"{dropped[-1]}-{stripped}")
78
+ cands += [c.replace(".", "-") for c in cands if "." in c]
79
+ out = list(dict.fromkeys(c for c in cands if c))
80
+ return out
81
+
82
+
83
+ def _rank(pattern):
84
+ lit_prefix = pattern.split("*", 1)[0]
85
+ return (len(lit_prefix), len(pattern.replace("*", "")), len(pattern), pattern)
86
+
87
+
88
+ @lru_cache(maxsize=None)
89
+ def _patterns():
90
+ out = []
91
+ for r in read("model_class_mapping.csv"):
92
+ for alt in r["pattern"].split(";"):
93
+ alt = alt.strip().lower()
94
+ if alt:
95
+ rx = re.compile("".join(".*" if p == "*" else re.escape(p) for p in re.split(r"(\*)", alt)))
96
+ out.append((_rank(alt), rx, r))
97
+ out.sort(key=lambda x: x[0], reverse=True)
98
+ return out
99
+
100
+
101
+ def _measured_id(cands):
102
+ byid = {r["model_id"].lower(): r["model_id"] for r in read("model_factors.csv")}
103
+ bylast = {k.rsplit("/", 1)[-1]: v for k, v in byid.items()}
104
+ for c in cands:
105
+ c = c.strip().lower()
106
+ if c in byid:
107
+ return byid[c]
108
+ if c in bylast:
109
+ return bylast[c]
110
+ return None
111
+
112
+
113
+ def map_model(identifier):
114
+ cands = normalise_identifier(identifier)
115
+ warnings, p = [], []
116
+ hit = next((r for _k, rx, r in _patterns() if any(rx.match(c) for c in cands)), None)
117
+ if hit is None:
118
+ raise SaefError("model_class_mapping.csv has no default row")
119
+ prov(p, "model class", hit, "model_class")
120
+ out = dict(
121
+ identifier=str(identifier), pattern=hit["pattern"], basis=hit["basis"], model_class=hit["model_class"],
122
+ own_factor_model_id=hit["own_factor_model_id"] or None, out_of_scope=hit["model_class"] == "out-of-scope",
123
+ is_default_fallback=hit["basis"] == "default", warnings=warnings, provenance=p,
124
+ )
125
+ if out["is_default_fallback"]:
126
+ warnings.append(f"unmapped model identifier {identifier!r}: defaulted to Class {hit['model_class']} and flagged")
127
+ if out["out_of_scope"]:
128
+ out["model_class"] = None
129
+ warnings.append(f"{identifier!r} matches the out-of-scope pattern {hit['pattern']!r}: {hit['notes']}")
130
+ elif hit["basis"] == "tier":
131
+ warnings.append(
132
+ f"class proxy for a closed model: {identifier!r} was placed in Class {hit['model_class']} by the "
133
+ f"vendor pricing tier, not by a disclosed size ({hit['size_or_tier_note']})"
134
+ )
135
+ direct = _measured_id(cands + [str(identifier)])
136
+ if direct:
137
+ out["own_factor_model_id"] = direct
138
+ out["basis"] = "measured"
139
+ return out
140
+
141
+
142
+ def _suggest(region):
143
+ pool = {r["region_id"] for r in read("cloud_region_factors.csv")} | {r["grid_id"] for r in read("grid_intensity_all.csv")}
144
+ low = region.lower()
145
+ near = sorted(x for x in pool if x.lower().startswith(low))[:8] or difflib.get_close_matches(region, sorted(pool), n=5)
146
+ return near
147
+
148
+
149
+ def resolve_region(provider=None, region=None):
150
+ """Resolve to one grid row. Unknown or global regions use the global average, as the dataset's decision rule says;
151
+ a region string that matches nothing raises SaefError."""
152
+ warnings, p = [], []
153
+ grids = {r["grid_id"]: r for r in read("grid_intensity_all.csv")}
154
+ key = (region or "").strip()
155
+ low = key.lower()
156
+
157
+ def finish(grid_row, how, class_row=None, region_id=None):
158
+ prov(p, "grid carbon intensity", grid_row, "grid_kg_co2e_per_kwh")
159
+ return dict(
160
+ grid_id=grid_row["grid_id"], grid_name=grid_row["name"],
161
+ grid_kg_co2e_per_kwh=float(grid_row["grid_kg_co2e_per_kwh"]),
162
+ class_row=grid_row if class_row is None else class_row,
163
+ region_id=region_id or grid_row["grid_id"], how=how, warnings=warnings, provenance=p,
164
+ )
165
+
166
+ if low in UNKNOWN_REGION:
167
+ warnings.append("region unknown or global: the global-average grid row (WORLD) is applied, per the dataset's serving-region decision rule")
168
+ return finish(grids["WORLD"], "unknown -> global average", region_id="global-average")
169
+ if low in EU27_REGION:
170
+ warnings.append("EU data zone or EU-only processing: the EU-27 average grid row (EU27) is applied")
171
+ return finish(grids["EU27"], "EU-only processing -> EU-27", region_id="eu-27")
172
+
173
+ cloud = [r for r in read("cloud_region_factors.csv") if r["region_id"].lower() == low]
174
+ if provider:
175
+ cloud = [r for r in cloud if r["provider"].lower() == provider.strip().lower()]
176
+ if cloud:
177
+ if len({r["grid_id"] for r in cloud}) > 1:
178
+ raise SaefError(f"Region {region!r} is used by several providers with different grids, pass provider=")
179
+ r = cloud[0]
180
+ if r["mapping_confidence"] == "medium":
181
+ warnings.append(f"region mapping confidence is medium for {r['provider']}/{r['region_id']}: {r['mapping_notes']}")
182
+ prov(p, "cloud region to grid", r, "grid_id")
183
+ return finish(grids[r["grid_id"]], f"cloud region {r['provider']}/{r['region_id']}", class_row=r, region_id=r["region_id"])
184
+
185
+ hit = next((r for r in read("region_grid_crosswalk.csv") if r["region_id"].lower() == low), None)
186
+ if hit:
187
+ prov(p, "printed region to grid", hit, "grid_id")
188
+ return finish(grids[hit["grid_id"]], f"printed region {hit['region_id']}", region_id=hit["region_id"])
189
+ if key.upper() in grids:
190
+ g = grids[key.upper()]
191
+ return finish(g, f"{g['kind'].replace('_', ' ')} {g['grid_id']}")
192
+ byname = [r for r in grids.values() if r["name"].strip().lower() == low]
193
+ if len(byname) == 1:
194
+ return finish(byname[0], f"country name -> {byname[0]['grid_id']}")
195
+ hint = _suggest(key)
196
+ msg = f"Unknown region {region!r}."
197
+ if hint:
198
+ msg += f" Did you mean: {', '.join(hint)}?"
199
+ msg += " Use a cloud region id (see saef.regions()), an ISO-3 country code, an eGRID subregion, 'eu-27' or 'unknown'."
200
+ raise SaefError(msg)
201
+
202
+
203
+ def effective_tokens(output=0.0, uncached_input=0.0, cached_input=0.0):
204
+ return (output + const("W_in") * uncached_input + const("W_cache") * cached_input) / const("D")
205
+
206
+
207
+ def effective_from_billed(billed):
208
+ s = const("default_input_share")
209
+ return billed * (1 - s + const("W_in") * s) / const("D")
210
+
211
+
212
+ def _class_terms(cl, reg, p):
213
+ c = cl.lower()
214
+ row = reg["class_row"]
215
+ cols = {
216
+ "footprint": f"class_{c}_inference_footprint_kg_per_m_effective_tokens",
217
+ "training": f"class_{c}_training_kg_per_m_billed_tokens",
218
+ "footprint_high": f"class_{c}_inference_footprint_high_case_kg_per_m_effective_tokens",
219
+ "development": f"class_{c}_development_line_kg_per_m_effective_tokens",
220
+ "electricity": f"class_{c}_electricity_kg_per_m_effective_tokens",
221
+ "embodied": f"class_{c}_embodied_kg_per_m_effective_tokens",
222
+ "construction": f"class_{c}_construction_kg_per_m_effective_tokens",
223
+ "per_billed": f"class_{c}_factor_kg_per_m_billed_tokens_default_mix",
224
+ }
225
+ if cols["footprint"] not in row:
226
+ raise SaefError(f"no class factors for model class {cl!r}; use A, B or C")
227
+ f = {k: float(row[col]) for k, col in cols.items()}
228
+ for k in ("footprint", "training", "footprint_high", "development"):
229
+ prov(p, k.replace("_", " "), row, cols[k])
230
+ f["basis"] = f"class {cl} mean of the measured members, H100"
231
+ return f
232
+
233
+
234
+ def _model_terms(model_id, reg, p):
235
+ r = next((r for r in read("model_factors.csv") if r["model_id"] == model_id and r["gpu"] == "H100"), None)
236
+ if r is None:
237
+ return None
238
+ grid = reg["grid_kg_co2e_per_kwh"]
239
+ fac, fac_hi = float(r["facility_wh_per_1k_effective_tokens"]), float(r["facility_wh_high_case_per_1k_effective_tokens"])
240
+ emb, con = float(r["embodied_kg_co2e_per_m_tokens"]), float(r["construction_kg_co2e_per_m_tokens"])
241
+ emb_hi, con_hi = float(r["embodied_high_case_kg_co2e_per_m_tokens"]), float(r["construction_high_case_kg_co2e_per_m_tokens"])
242
+ tr = float(r["training_kg_co2e_per_m_billed_tokens"])
243
+ for q, col in (("facility Wh per 1,000 effective tokens", "facility_wh_per_1k_effective_tokens"),
244
+ ("embodied", "embodied_kg_co2e_per_m_tokens"), ("construction", "construction_kg_co2e_per_m_tokens"),
245
+ ("training term", "training_kg_co2e_per_m_billed_tokens")):
246
+ prov(p, q, r, col)
247
+ mult = (1 - const("default_input_share") + const("W_in") * const("default_input_share")) / const("D")
248
+ foot = fac * grid + emb + con
249
+ return dict(
250
+ footprint=foot, training=tr, footprint_high=fac_hi * grid + emb_hi + con_hi,
251
+ development=float(r["development_line_kg_co2e_per_m_tokens_global"]) / float(r["grid_kg_co2e_per_kwh"]) * grid,
252
+ electricity=fac * grid, embodied=emb, construction=con, per_billed=foot * mult + tr,
253
+ model_class=r["model_class"], basis=f"measured model {model_id}, H100",
254
+ )
255
+
256
+
257
+ def emissions(model=None, model_class=None, provider=None, region=None, billed_tokens=None,
258
+ output_tokens=0.0, input_tokens=0.0, cached_input_tokens=0.0):
259
+ warnings, p = [], []
260
+ if (model is None) == (model_class is None):
261
+ raise SaefError("Pass exactly one of model or model_class")
262
+ own = None
263
+ if model is not None:
264
+ mm = map_model(model)
265
+ warnings += mm["warnings"]
266
+ p += mm["provenance"]
267
+ if mm["out_of_scope"]:
268
+ raise SaefError(f"{model!r} is out of scope (embeddings, image, audio, video or moderation): no estimate. {mm['warnings'][-1]}")
269
+ cl, own, basis = mm["model_class"], mm["own_factor_model_id"], mm["basis"]
270
+ matched = mm["pattern"]
271
+ else:
272
+ cl = {"a": "A", "b": "B", "c": "C"}.get(str(model_class).strip().lower().replace("class_", "")[:1], None)
273
+ if cl is None:
274
+ raise SaefError(f"Unknown model class {model_class!r}; use A, B or C")
275
+ basis, matched = "caller-supplied", None
276
+ reg = resolve_region(provider, region)
277
+ warnings += reg["warnings"]
278
+ p += reg["provenance"]
279
+
280
+ if billed_tokens is not None:
281
+ billed = float(billed_tokens)
282
+ t_eff = effective_from_billed(billed)
283
+ warnings.append(
284
+ f"no input/output split given: the default input share {const('default_input_share'):g} and no cache credit were applied"
285
+ )
286
+ else:
287
+ billed = float(input_tokens) + float(cached_input_tokens) + float(output_tokens)
288
+ t_eff = effective_tokens(float(output_tokens), float(input_tokens), float(cached_input_tokens))
289
+ if not cached_input_tokens:
290
+ warnings.append("no cached-token count given, so no cache credit was taken")
291
+ for k in ("W_in", "W_cache", "D", "default_input_share"):
292
+ prov(p, f"token basis {k}", constants()[k], "central")
293
+
294
+ f = _model_terms(own, reg, p) if own else None
295
+ if f is not None:
296
+ cl, basis = f["model_class"], "measured"
297
+ else:
298
+ f = _class_terms(cl, reg, p)
299
+ kg = t_eff / 1e6 * f["footprint"] + billed / 1e6 * f["training"]
300
+ kg_high = t_eff / 1e6 * f["footprint_high"] + billed / 1e6 * f["training"]
301
+ return dict(
302
+ kg_co2e=kg, kg_co2e_high_case=kg_high, development_line_kg_co2e=t_eff / 1e6 * f["development"],
303
+ electricity_kg_co2e=t_eff / 1e6 * f["electricity"], embodied_kg_co2e=t_eff / 1e6 * f["embodied"],
304
+ construction_kg_co2e=t_eff / 1e6 * f["construction"], training_kg_co2e=billed / 1e6 * f["training"],
305
+ model=model, matched_pattern=matched, model_class=cl, class_basis=basis, own_factor_model_id=own,
306
+ is_default_fallback=bool(model is not None and mm["is_default_fallback"]),
307
+ region_id=reg["region_id"], grid_id=reg["grid_id"], grid_kg_co2e_per_kwh=reg["grid_kg_co2e_per_kwh"],
308
+ region_resolution=reg["how"], billed_tokens=billed, effective_tokens=t_eff, factors=f,
309
+ warnings=warnings, provenance=p, _reg=reg,
310
+ )
311
+
312
+
313
+ def water(t_eff, model_class, provider=None, region=None):
314
+ """Water for an effective-token count under both hydropower conventions, or available=False."""
315
+ warnings, p = [], []
316
+ reg = resolve_region(provider, region)
317
+ warnings += reg["warnings"]
318
+ rid = reg["region_id"]
319
+ wf = {r["region_id"]: r for r in read("region_water_factors.csv")}
320
+ if reg["how"].startswith("unknown") or rid not in wf:
321
+ warnings.append(
322
+ f"no water factor for region {rid!r}: region_water_factors.csv covers {len(wf)} regions only "
323
+ f"and has no unknown-region fallback. Disclose water as not available"
324
+ )
325
+ return dict(available=False, region_id=rid, warnings=warnings, provenance=p)
326
+ w = wf[rid]
327
+ fl = next((r for r in read("factors_v3_lifecycle.csv") if r["model_class"] == model_class and r["gpu"] == "H100" and r["region_id"] == rid), None)
328
+ if fl is None:
329
+ raise SaefError(f"no factors_v3_lifecycle.csv row for class {model_class} / H100 / {rid}")
330
+ fac, srv = float(fl["facility_wh_per_1k_effective_tokens"]), float(fl["server_wh_per_1k_effective_tokens"])
331
+ prov(p, "facility Wh per 1,000 effective tokens", fl, "facility_wh_per_1k_effective_tokens")
332
+ prov(p, "server Wh per 1,000 effective tokens", fl, "server_wh_per_1k_effective_tokens")
333
+ k = t_eff / 1000.0
334
+ base = srv if w["wue_denominator"].startswith("IT load") else fac
335
+ onsite = base * float(w["wue_l_per_kwh"])
336
+ if w["wue_basis_as_published"] == "withdrawal":
337
+ onsite *= float(w["withdrawal_to_consumption"])
338
+ prov(p, "on-site WUE", w, "wue_l_per_kwh")
339
+ out = dict(available=True, region_id=rid, ml_onsite=onsite * k, ml_offsite_reig=None, ml_offsite_excl_hydro=None,
340
+ ml_total_reig=None, ml_total_excl_hydro=None, warnings=warnings, provenance=p)
341
+ if not w["ewif_l_per_kwh"]:
342
+ warnings.append(f"no off-site water factor for {rid}: {w['ewif_source']}. Only the on-site term is reported")
343
+ else:
344
+ off, off_x = fac * float(w["ewif_l_per_kwh"]), fac * float(w["ewif_excl_hydro_l_per_kwh"])
345
+ prov(p, "off-site EWIF (hydropower allocated)", w, "ewif_l_per_kwh")
346
+ prov(p, "off-site EWIF excluding hydropower", w, "ewif_excl_hydro_l_per_kwh")
347
+ out.update(ml_offsite_reig=off * k, ml_offsite_excl_hydro=off_x * k,
348
+ ml_total_reig=(onsite + off) * k, ml_total_excl_hydro=(onsite + off_x) * k)
349
+ warnings.append("two hydropower conventions are reported and neither is preferred: 'reig' allocates reservoir evaporation to electricity, 'excl_hydro' excludes it")
350
+ return out
saef/_core.py ADDED
@@ -0,0 +1,165 @@
1
+ from dataclasses import dataclass, field
2
+ from typing import Optional
3
+
4
+ from . import _calc
5
+ from ._calc import SaefError
6
+
7
+ DATASET_VERSION = "3.0.0"
8
+
9
+ BIBTEX = """@misc{llopis2026somafactors,
10
+ author = {Llopis-Garcia, Guillermo},
11
+ title = {{SOMA AI Emission Factors (SAEF)}},
12
+ year = {2026},
13
+ publisher = {Zenodo},
14
+ version = {v3.0.0},
15
+ doi = {10.5281/zenodo.20443585},
16
+ url = {https://doi.org/10.5281/zenodo.20443585}
17
+ }
18
+
19
+ @misc{llopis2026accounting,
20
+ author = {Llopis-Garcia, Guillermo},
21
+ title = {Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories: A Token-Based Method},
22
+ year = {2026},
23
+ eprint = {2606.10660},
24
+ archivePrefix = {arXiv},
25
+ note = {Accepted for publication in Sustainable Production and Consumption (Elsevier)}
26
+ }
27
+ """
28
+
29
+
30
+ def regions(provider=None):
31
+ """Cloud region ids (AWS, Azure, Google Cloud), sorted. Pass provider='aws'|'azure'|'gcp' to filter."""
32
+ rows = _calc.read("cloud_region_factors.csv")
33
+ if provider:
34
+ rows = [r for r in rows if r["provider"].lower() == provider.strip().lower()]
35
+ return sorted({r["region_id"] for r in rows})
36
+
37
+
38
+ def grids():
39
+ """Grid ids usable as a region: ISO-3 country codes, eGRID subregions, EU27, WORLD and one subnational row."""
40
+ return sorted(r["grid_id"] for r in _calc.read("grid_intensity_all.csv"))
41
+
42
+
43
+ def model_class_for(model):
44
+ """Map a model identifier such as 'gpt-4o' to its class (A, B or C) via model_class_mapping.csv.
45
+
46
+ An identifier that matches no pattern is assigned the conservative class C, as the dataset specifies."""
47
+ m = _calc.map_model(model)
48
+ if m["out_of_scope"]:
49
+ raise SaefError(f"{model!r} is out of scope (embeddings, image, audio, video or moderation)")
50
+ return m["model_class"]
51
+
52
+
53
+ def factor(model_class="B", region="us-east-1", provider=None):
54
+ """Class factor at one region, H100 central case.
55
+
56
+ kg_co2e_per_1m_billed_tokens is the headline for a billed total with the default input share.
57
+ terms are kg CO2e per million EFFECTIVE tokens (electricity, embodied, construction), plus training per million billed tokens."""
58
+ cl = _calc.emissions(model_class=model_class, provider=provider, region=region, billed_tokens=1e6)
59
+ f = cl["factors"]
60
+ return {
61
+ "model_class": cl["model_class"],
62
+ "region_id": cl["region_id"],
63
+ "grid_id": cl["grid_id"],
64
+ "grid_kg_co2e_per_kwh": cl["grid_kg_co2e_per_kwh"],
65
+ "kg_co2e_per_1m_billed_tokens": f["per_billed"],
66
+ "kg_co2e_per_1m_effective_tokens": f["footprint"],
67
+ "kg_co2e_per_1m_effective_tokens_high_case": f["footprint_high"],
68
+ "terms": {
69
+ "electricity": f["electricity"],
70
+ "embodied": f["embodied"],
71
+ "construction": f["construction"],
72
+ "training_per_1m_billed_tokens": f["training"],
73
+ },
74
+ "effective_per_billed_tokens": _calc.effective_from_billed(1.0),
75
+ "version": DATASET_VERSION,
76
+ "warnings": cl["warnings"],
77
+ "provenance": cl["provenance"],
78
+ }
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class Estimate:
83
+ kg_co2e: float
84
+ kg_co2e_high_case: float
85
+ development_line_kg_co2e: float
86
+ terms_kg_co2e: dict
87
+ water_ml: Optional[float]
88
+ water_ml_excl_hydro: Optional[float]
89
+ model: Optional[str]
90
+ model_class: str
91
+ class_basis: str
92
+ region_id: str
93
+ grid_kg_co2e_per_kwh: float
94
+ billed_tokens: float
95
+ effective_tokens: float
96
+ warnings: list = field(repr=False)
97
+ provenance: list = field(repr=False)
98
+ water: dict = field(repr=False)
99
+ version: str = DATASET_VERSION
100
+ note: str = "Estimate, not a measurement. The high case is a conservative bound; the development line is reported separately and is not part of kg_co2e."
101
+
102
+ @property
103
+ def sources(self):
104
+ return self.provenance
105
+
106
+ def to_dict(self):
107
+ return {k: getattr(self, k) for k in self.__dataclass_fields__}
108
+
109
+
110
+ def estimate(
111
+ tokens=None,
112
+ model=None,
113
+ model_class=None,
114
+ region=None,
115
+ provider=None,
116
+ output_tokens=None,
117
+ input_tokens=0.0,
118
+ cached_input_tokens=0.0,
119
+ ):
120
+ """Estimate kg CO2e (and water in mL where the region has a water factor) for AI inference.
121
+
122
+ Pass tokens, the BILLED total (input plus output), or pass output_tokens with input_tokens and
123
+ cached_input_tokens for a billing-export split. Pass model or model_class. region may be a cloud
124
+ region id, an ISO-3 country code, an eGRID subregion, 'eu-27' or None for the global average.
125
+ Every number is traced in provenance by file, line and column.
126
+ """
127
+ if (tokens is None) == (output_tokens is None):
128
+ raise SaefError("Pass either tokens (billed total) or output_tokens (with input_tokens)")
129
+ given = tokens if tokens is not None else output_tokens
130
+ if given < 0 or input_tokens < 0 or cached_input_tokens < 0:
131
+ raise SaefError("token counts must be >= 0")
132
+ r = _calc.emissions(
133
+ model=model, model_class=model_class, provider=provider, region=region,
134
+ billed_tokens=tokens, output_tokens=output_tokens or 0.0,
135
+ input_tokens=input_tokens, cached_input_tokens=cached_input_tokens,
136
+ )
137
+ w = _calc.water(r["effective_tokens"], r["model_class"], provider, region)
138
+ return Estimate(
139
+ kg_co2e=r["kg_co2e"],
140
+ kg_co2e_high_case=r["kg_co2e_high_case"],
141
+ development_line_kg_co2e=r["development_line_kg_co2e"],
142
+ terms_kg_co2e={
143
+ "electricity": r["electricity_kg_co2e"],
144
+ "embodied": r["embodied_kg_co2e"],
145
+ "construction": r["construction_kg_co2e"],
146
+ "training": r["training_kg_co2e"],
147
+ },
148
+ water_ml=w["ml_total_reig"] if w["available"] else None,
149
+ water_ml_excl_hydro=w["ml_total_excl_hydro"] if w["available"] else None,
150
+ model=model,
151
+ model_class=r["model_class"],
152
+ class_basis=r["class_basis"],
153
+ region_id=r["region_id"],
154
+ grid_kg_co2e_per_kwh=r["grid_kg_co2e_per_kwh"],
155
+ billed_tokens=r["billed_tokens"],
156
+ effective_tokens=r["effective_tokens"],
157
+ warnings=list(dict.fromkeys(r["warnings"] + w["warnings"])),
158
+ provenance=r["provenance"] + w["provenance"],
159
+ water=w,
160
+ )
161
+
162
+
163
+ def citation():
164
+ """BibTeX for the dataset (Zenodo concept DOI 10.5281/zenodo.20443585) and the method paper."""
165
+ return BIBTEX
saef/cli.py ADDED
@@ -0,0 +1,73 @@
1
+ import argparse
2
+ import json
3
+
4
+ from . import __version__, citation, estimate, factor, regions
5
+ from ._core import SaefError
6
+
7
+
8
+ def _print_estimate(e):
9
+ print(f"SAEF {e.version} model={e.model or '-'} class={e.model_class} ({e.class_basis}) region={e.region_id} grid={e.grid_kg_co2e_per_kwh:g} kg/kWh")
10
+ print(f"billed tokens: {e.billed_tokens:,.0f} effective tokens: {e.effective_tokens:,.0f}")
11
+ print(f"kg CO2e: {e.kg_co2e:.6g} (conservative high case {e.kg_co2e_high_case:.6g}; development line {e.development_line_kg_co2e:.6g}, reported separately)")
12
+ for term, value in e.terms_kg_co2e.items():
13
+ print(f" {term}: {value:.6g} kg")
14
+ if e.water_ml is None:
15
+ print("water: not available for this region")
16
+ else:
17
+ print(f"water mL: {e.water_ml:.6g} (hydropower allocated), {e.water_ml_excl_hydro:.6g} (excluding hydropower)")
18
+ for w in e.warnings:
19
+ print(f"warning: {w}")
20
+ print("sources (file:line, column):")
21
+ for s in e.provenance:
22
+ print(f" {s['quantity']}: {s['file']}:{s['line']} {s['column']} = {s['value']}")
23
+ print(e.note)
24
+
25
+
26
+ def main(argv=None):
27
+ p = argparse.ArgumentParser(prog="saef", description="SOMA AI Emission Factors (estimates, not measurements)")
28
+ p.add_argument("--version", action="version", version=f"saef {__version__}")
29
+ sub = p.add_subparsers(dest="cmd", required=True)
30
+
31
+ e = sub.add_parser("estimate", help="estimate kg CO2e and water for a token count")
32
+ e.add_argument("--tokens", type=float, help="billed total (input plus output)")
33
+ e.add_argument("--output-tokens", type=float, help="output tokens, with --input-tokens")
34
+ e.add_argument("--input-tokens", type=float, default=0.0)
35
+ e.add_argument("--cached-input-tokens", type=float, default=0.0)
36
+ g = e.add_mutually_exclusive_group(required=True)
37
+ g.add_argument("--model")
38
+ g.add_argument("--model-class", dest="model_class")
39
+ e.add_argument("--region", default=None, help="cloud region id, ISO-3 country, eGRID subregion, eu-27; default global average")
40
+ e.add_argument("--provider", default=None)
41
+ e.add_argument("--json", action="store_true")
42
+
43
+ f = sub.add_parser("factor", help="show the class factor at a region")
44
+ f.add_argument("--model-class", dest="model_class", default="B")
45
+ f.add_argument("--region", default="us-east-1")
46
+ f.add_argument("--provider", default=None)
47
+
48
+ r = sub.add_parser("regions", help="list cloud region ids")
49
+ r.add_argument("--provider", default=None)
50
+ sub.add_parser("cite", help="print BibTeX")
51
+
52
+ args = p.parse_args(argv)
53
+ try:
54
+ if args.cmd == "estimate":
55
+ res = estimate(
56
+ tokens=args.tokens, model=args.model, model_class=args.model_class, region=args.region,
57
+ provider=args.provider, output_tokens=args.output_tokens, input_tokens=args.input_tokens,
58
+ cached_input_tokens=args.cached_input_tokens,
59
+ )
60
+ if args.json:
61
+ print(json.dumps(res.to_dict(), indent=2))
62
+ else:
63
+ _print_estimate(res)
64
+ elif args.cmd == "factor":
65
+ print(json.dumps(factor(args.model_class, args.region, args.provider), indent=2))
66
+ elif args.cmd == "regions":
67
+ print("\n".join(regions(args.provider)))
68
+ else:
69
+ print(citation())
70
+ except SaefError as err:
71
+ print(f"saef: error: {err}")
72
+ return 2
73
+ return 0