ecocost 0.1.0__py3-none-any.whl

ecocost/__init__.py

@@ -0,0 +1,108 @@
+"""ecocost: estimated carbon, energy and water per LLM run.
+
+Pure Python; the only dependency is PyYAML. See METHODOLOGY.md for how the
+estimate is built and CONTRIBUTING.md for how to update the data.
+
+    >>> from ecocost import estimate
+    >>> estimate("accounts/fireworks/models/gpt-oss-120b", provider="fireworks",
+    ...          input_tokens=800, output_tokens=300)["carbon"]
+    {'unit': 'gCO2e', 'value': ..., 'min': ..., 'max': ...}
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+from numbers import Integral
+
+from . import calc
+from .errors import UnknownModelError, UnknownProviderError
+from .loader import get_kb
+from .result import EstimateResult
+
+__all__ = ["estimate", "EstimateResult", "UnknownModelError", "UnknownProviderError"]
+
+# far above any single request; beyond it the float maths would overflow
+MAX_TOKENS = 10**12
+
+try:
+    __version__ = version("ecocost")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0+unknown"
+
+
+def estimate(
+    model: str,
+    *,
+    provider: str | None = None,
+    base_url: str | None = None,
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    cached_input_tokens: int = 0,
+    timestamp: datetime | None = None,
+) -> EstimateResult:
+    """Estimate one request.
+
+    ``model`` is a model id; provider-specific ids resolve through aliases.
+    Who serves the request is taken, in order, from ``provider`` (an id from
+    providers.yaml, listed in the README), else ``base_url`` (an API endpoint
+    whose host a provider publishes), else, for a closed model, its vendor's
+    own API; otherwise wide US defaults. ``reasons`` says when it was inferred
+    or defaulted.
+
+    Ids are matched ignoring case. ``UnknownModelError`` and
+    ``UnknownProviderError`` suggest close matches and where to add the
+    record. Bad arguments raise ``TypeError`` or ``ValueError``.
+    """
+    _check_args(
+        model, provider, base_url, input_tokens, output_tokens, cached_input_tokens
+    )
+    kb = get_kb()
+    m = kb.resolve_model(model)
+    p, provider_reason = kb.resolve_provider(provider, base_url=base_url, model=m)
+    est = calc.estimate(
+        m,
+        p,
+        kb.regions[p.region],
+        kb.hardware[p.hardware],
+        kb.hardware[calc.REFERENCE_HARDWARE_ID],
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_input_tokens=cached_input_tokens,
+        candidate_regions=[(kb.regions[rid], w) for rid, w in p.region_candidates],
+        candidate_hardware=[(kb.hardware[hid], w) for hid, w in p.hardware_candidates],
+    )
+    # timestamp is reserved for hourly grid intensity and not used yet.
+    if provider_reason:
+        est.reasons.insert(0, provider_reason)
+    out = est.to_dict()
+    out["requested"] = {"model": model, "provider": provider, "base_url": base_url}
+    return out
+
+
+def _check_args(
+    model, provider, base_url, input_tokens, output_tokens, cached_input_tokens
+):
+    if not isinstance(model, str):
+        raise TypeError(f"model must be a string, got {type(model).__name__}")
+    if not model:
+        raise ValueError("model must not be empty")
+    for name, value in (("provider", provider), ("base_url", base_url)):
+        if value is not None and not isinstance(value, str):
+            raise TypeError(
+                f"{name} must be a string or None, got {type(value).__name__}"
+            )
+    for name, n in (
+        ("input_tokens", input_tokens),
+        ("output_tokens", output_tokens),
+        ("cached_input_tokens", cached_input_tokens),
+    ):
+        if isinstance(n, bool) or not isinstance(n, Integral):
+            raise TypeError(f"{name} must be an int, got {type(n).__name__}")
+        if not 0 <= n <= MAX_TOKENS:
+            raise ValueError(f"{name} must be between 0 and {MAX_TOKENS:,}, got {n}")
+    if cached_input_tokens > input_tokens:
+        raise ValueError(
+            f"cached_input_tokens ({cached_input_tokens}) exceeds input_tokens "
+            f"({input_tokens}); input_tokens counts cached tokens too"
+        )

ecocost/calc.py

@@ -0,0 +1,308 @@
+"""Eco-cost estimation pipeline.
+
+    tokens ──(active params, utilization)──▶ H100-seconds (work, chip-independent)
+           ──(chip energy ratio, TDP, PUE)─▶ Wh at the meter
+           ──(grid intensity)────────────▶ gCO2e (usage)
+           ──(embodied per H100-second)──▶ gCO2e (embodied)
+           ──(WUE)───────────────────────▶ mL water, on-site cooling
+           ──(generation water)──────────▶ mL water, upstream at the plant
+           ──(primary energy factor)─────▶ MJ primary energy
+
+Every step is arithmetic over ``Range``. min/max is the likely range:
+independent multiplicative inputs combine in quadrature in log space.
+``worst_case`` keeps the plain interval bounds with every input at its
+extreme at once. Confidence is bucketed from the max/min ratio of the likely
+carbon range and explained by listing every tier-3 input that went into it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .schema import (
+    DEFAULT_HALF_WIDTH,
+    H100_TDP_W,
+    Hardware,
+    Model,
+    Provider,
+    Range,
+    Region,
+    Tier,
+    sig_round,
+)
+
+METHOD_VERSION = "0.2.0"
+
+# H100 SXM is the unit of work: an H100-second is "the work one H100 does in
+# one second", whatever chip actually ran it.
+REFERENCE_HARDWARE_ID = "h100-sxm"
+
+# Cached prefix tokens cost about a tenth of a fresh prefill (assumed).
+CACHED_INPUT_COST = 0.1
+
+# Confidence label from the max/min ratio of the likely carbon range. "high"
+# is within about +/-40% of the point value, "medium" within about a factor
+# of 2.2 either way. For scale, Epoch's plausible range for a ChatGPT query
+# is 0.1 to 4 Wh, a 40x span.
+HIGH_CONFIDENCE_RATIO = 2.0
+MEDIUM_CONFIDENCE_RATIO = 5.0
+
+
+def estimate(
+    model: Model,
+    provider: Provider,
+    region: Region,
+    hardware: Hardware,
+    reference_hardware: Hardware,
+    *,
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    cached_input_tokens: int = 0,
+    candidate_regions: Sequence[tuple[Region, float]] = (),
+    candidate_hardware: Sequence[tuple[Hardware, float]] = (),
+) -> Estimate:
+    """``region`` and ``hardware`` are the provider's primary site and chip.
+    When the provider discloses several, the candidates set the ranges."""
+    chips = list(candidate_hardware) or [(hardware, 1.0)]
+
+    def regional(factor: str, floor: float = 0.0) -> Range:
+        return _regional(factor, region, provider.region_tier, candidate_regions, floor)
+
+    # 1. Work, in H100-seconds on the reference chip so the unit does not
+    #    depend on the fleet; the fleet enters in step 2.
+    fresh_input = max(input_tokens - cached_input_tokens, 0)
+    work = _h100_seconds(
+        model,
+        reference_hardware,
+        fresh_input + cached_input_tokens * CACHED_INPUT_COST,
+        provider.prefill_utilization.as_range(),
+    )
+    measured = model.measured_wh_per_1k_output_tokens_h100
+    if measured is not None:
+        # Measured path: Wh on an H100 -> H100-seconds at its TDP.
+        wh = measured.as_range() * (output_tokens / 1000)
+        work += wh * 3600 / reference_hardware.tdp_w.as_range()
+    else:
+        work += _h100_seconds(
+            model,
+            reference_hardware,
+            output_tokens,
+            provider.decode_utilization.as_range(),
+        )
+
+    # 2. Energy at the meter. The chip ratio is how much energy this fleet
+    #    spends per H100-second of work (B200 ~0.75, H200 ~0.85). Serving
+    #    overhead covers host CPU/RAM/network and idle capacity: Google reports
+    #    0.24 Wh/prompt all-in vs 0.10 Wh for the accelerators alone.
+    chip_ratio = _envelope([(hw.energy_vs_h100.as_range(), w) for hw, w in chips])
+    energy_wh = (
+        work
+        * H100_TDP_W
+        / 3600
+        * chip_ratio
+        * provider.serving_overhead.as_range()
+        * provider.pue.as_range()
+    )
+    kwh = energy_wh / 1000
+
+    # 3. Carbon. An uncertain site widens the grid range too: "somewhere in
+    #    the US" spans ~100-700 gCO2e/kWh.
+    grid = regional("carbon_intensity_gco2e_per_kwh", floor=10.0)
+    embodied_rate = _envelope(
+        [(hw.embodied_gco2e_per_h100_second, w) for hw, w in chips]
+    )
+
+    # 4. Water, in two parts because they follow different conventions.
+    #    On-site is what the operator's WUE measures (and what Google's
+    #    0.26 mL per prompt counts). Generation water (WRI 2020) is the LCA
+    #    convention; it is usually larger and, on hydro grids, contested.
+    return Estimate(
+        model=model,
+        provider=provider,
+        region=region,
+        hardware=hardware,
+        chips=tuple(hw.id for hw, _ in chips),
+        tokens=(input_tokens, output_tokens, cached_input_tokens),
+        h100_seconds=work,
+        chip_energy_ratio=chip_ratio,
+        energy_wh=energy_wh,
+        primary_energy_mj=kwh * 3.6 * regional("primary_energy_factor"),
+        grid_intensity=grid,
+        carbon_usage_g=kwh * grid,
+        carbon_embodied_g=work * embodied_rate,
+        water_onsite_ml=kwh * provider.wue_l_per_kwh.as_range() * 1000,
+        water_generation_ml=kwh * regional("water_l_per_kwh_generation") * 1000,
+        reasons=_assumed_inputs(model, provider, region, [hw for hw, _ in chips]),
+    )
+
+
+@dataclass(frozen=True)
+class Estimate:
+    model: Model
+    provider: Provider
+    region: Region
+    hardware: Hardware
+    chips: tuple[str, ...]
+    tokens: tuple[int, int, int]  # input, output, cached input
+    h100_seconds: Range
+    chip_energy_ratio: Range  # vs H100, envelope over the fleet
+    energy_wh: Range
+    primary_energy_mj: Range
+    grid_intensity: Range
+    carbon_usage_g: Range
+    carbon_embodied_g: Range
+    water_onsite_ml: Range
+    water_generation_ml: Range
+    reasons: list[str]
+
+    @property
+    def carbon_g(self) -> Range:
+        return self.carbon_usage_g + self.carbon_embodied_g
+
+    @property
+    def water_ml(self) -> Range:
+        return self.water_onsite_ml + self.water_generation_ml
+
+    @property
+    def confidence_level(self) -> str:
+        ratio = self.carbon_g.ratio
+        if ratio < HIGH_CONFIDENCE_RATIO:
+            return "high"
+        if ratio < MEDIUM_CONFIDENCE_RATIO:
+            return "medium"
+        return "low"
+
+    def to_dict(self) -> dict:
+        input_tokens, output_tokens, cached_input_tokens = self.tokens
+        grid = self.grid_intensity
+        return {
+            "model": self.model.id,
+            "provider": self.provider.id,
+            "tokens": {
+                "input": input_tokens,
+                "output": output_tokens,
+                "cached_input": cached_input_tokens,
+            },
+            "carbon": self.carbon_g.to_dict("gCO2e"),
+            "energy": {
+                **self.energy_wh.to_dict("Wh"),
+                "primary_energy_mj": sig_round(self.primary_energy_mj.mid),
+            },
+            "water": {
+                **self.water_ml.to_dict("mL"),
+                "on_site": self.water_onsite_ml.to_dict("mL"),
+                "generation": self.water_generation_ml.to_dict("mL"),
+            },
+            "confidence": {
+                "level": self.confidence_level,
+                "ratio": round(self.carbon_g.ratio, 2),
+                "reasons": self.reasons,
+            },
+            "electricity": {
+                "region": self.region.id,
+                "country": self.region.country,
+                "gco2e_per_kwh": sig_round(grid.mid),
+                "gco2e_per_kwh_range": [sig_round(grid.lo), sig_round(grid.hi)],
+                "primary_source": self.region.primary_source.value,
+                "mix": {k.value: v for k, v in self.region.mix.items()},
+                "dataset_year": self.region.dataset_year,
+            },
+            "breakdown": {
+                "h100_seconds": self.h100_seconds.to_dict("s"),
+                "usage": {"gco2e": sig_round(self.carbon_usage_g.mid)},
+                "embodied": {"gco2e": sig_round(self.carbon_embodied_g.mid)},
+            },
+            "assumptions": {
+                "active_params_b": {
+                    "min": self.model.active_params_b.min,
+                    "max": self.model.active_params_b.max,
+                },
+                "hardware": list(self.chips),
+                "chip_energy_vs_h100": sig_round(self.chip_energy_ratio.mid),
+                "pue": self.provider.pue.value,
+                "decode_utilization": self.provider.decode_utilization.value,
+                "serving_overhead": self.provider.serving_overhead.value,
+                "method_version": METHOD_VERSION,
+            },
+            "provenance": {
+                name: {
+                    "trust": record.provenance.trust.value,
+                    "status": record.provenance.status.value,
+                    "generated_by": record.provenance.generated_by,
+                    "stale": record.provenance.is_stale(),
+                }
+                for name, record in (
+                    ("model", self.model),
+                    ("provider", self.provider),
+                    ("region", self.region),
+                    ("hardware", self.hardware),
+                )
+            },
+        }
+
+
+def _h100_seconds(
+    model: Model, reference: Hardware, tokens: float, utilization: Range
+) -> Range:
+    """A forward pass is ~2 FLOPs per active parameter per token."""
+    if tokens <= 0:
+        return Range(0.0, 0.0, 0.0)
+    flops = model.active_params_b.as_range() * 2e9 * tokens
+    return flops / (reference.peak_dense_flops.as_range() * utilization)
+
+
+def _envelope(ranges: Sequence[tuple[Range, float]]) -> Range:
+    """Weighted mean as the point, min/max of the members as the range."""
+    total = sum(w for _, w in ranges)
+    return Range(
+        min(r.lo for r, _ in ranges),
+        sum(r.mid * w for r, w in ranges) / total,
+        max(r.hi for r, _ in ranges),
+        min(r.wlo for r, _ in ranges),
+        max(r.whi for r, _ in ranges),
+    )
+
+
+def _regional(
+    factor: str,
+    region: Region,
+    region_tier: Tier,
+    candidates: Sequence[tuple[Region, float]],
+    floor: float,
+) -> Range:
+    """A per-kWh regional factor for a provider whose site may be uncertain.
+
+    Disclosed candidate sites give an envelope, which is evidence. Without
+    them, the national figure is widened by the region tier's half-width.
+    """
+    if candidates:
+        return _envelope([(getattr(c, factor).as_range(), w) for c, w in candidates])
+    r = getattr(region, factor).as_range()
+    if region_tier == Tier.primary:
+        return r
+    half_width = DEFAULT_HALF_WIDTH[region_tier]
+    return Range(max(r.lo / half_width, floor), r.mid, r.hi * half_width)
+
+
+def _assumed_inputs(
+    model: Model, provider: Provider, region: Region, chips: Sequence[Hardware]
+) -> list[str]:
+    """Reason codes: every tier-3 input, most important first."""
+    measured = model.measured_wh_per_1k_output_tokens_h100 is not None
+    reasons = []
+    if not measured and not model.open_weights:
+        reasons.append("active_params_undisclosed")
+    tiers = {
+        # measured energy replaces the parameter count on the decode path
+        "active_params_estimated": None if measured else model.active_params_b.tier,
+        "region_inferred": provider.region_tier,
+        "hardware_assumed": provider.hardware_tier,
+        "pue_assumed": provider.pue.tier,
+        "wue_assumed": provider.wue_l_per_kwh.tier,
+        "utilization_assumed": provider.decode_utilization.tier,
+        "serving_overhead_assumed": provider.serving_overhead.tier,
+        "grid_intensity_national_average": region.carbon_intensity_gco2e_per_kwh.tier,
+        "embodied_carbon_default": max(hw.embodied_tier for hw in chips),
+    }
+    return reasons + [code for code, tier in tiers.items() if tier == Tier.assumed]

ecocost/data/hardware.yaml

@@ -0,0 +1,145 @@
+  # Reference hardware. H100 SXM is the unit everything is normalised to.
+# Leaf shape: {value, unit, tier, [min, max], source, note}
+hardware:
+  h100-sxm:
+    label: NVIDIA H100 SXM5 80GB
+    tdp_w:
+      value: 700
+      unit: W
+      tier: 1
+      source: https://www.nvidia.com/en-us/data-center/h100/
+      note: Board TDP. Real draw under inference load is lower; captured via utilization.
+    peak_dense_flops:
+      value: 9.89e14
+      unit: FLOP/s
+      tier: 1
+      source: https://www.nvidia.com/en-us/data-center/h100/
+      note: BF16 dense, no sparsity.
+    # Embodied carbon per H100-second = kg / (years * active fraction). Kept as
+    # three inputs so the range is propagated instead of stacking every extreme
+    # (276 kg over 6 busy years vs 985 kg over 3 half-idle years is a 14x span
+    # that no single deployment sits at both ends of).
+    embodied_kgco2e_per_gpu:
+      value: 500
+      min: 276
+      max: 985
+      unit: kgCO2e per GPU incl. server share
+      tier: 2
+      source: https://images.nvidia.com/aem-dam/Solutions/documents/HGX-H100-PCF-Summary.pdf
+      note: >-
+        Cradle-to-gate GPU 164 kgCO2e (NVIDIA HGX H100 PCF, 1,312 kg / 8) to
+        273 kgCO2e (ADEME, Lees-Perasso et al. 2026), plus server share per GPU
+        112 kg (BoaviztAPI default server / 8) to 712 kg (EcoLogits p5.48xlarge
+        5,700 kg / 8). Min and max are the sums of the low and high ends.
+    lifetime_years:
+      value: 4.5
+      min: 3
+      max: 6
+      unit: years
+      tier: 3
+      source: assumption
+      note: Policy choice, not a measurement. 3 years is the pessimistic economic life of an AI accelerator, 6 the longest server depreciation schedule in use.
+    active_fraction:
+      value: 0.7
+      min: 0.5
+      max: 1.0
+      unit: fraction of lifetime spent serving
+      tier: 3
+      source: assumption
+      note: Assumed. Embodied carbon is charged only to seconds that do work, so idle time raises the per-second rate.
+    energy_vs_h100:
+      value: 1.0
+      min: 1.0
+      max: 1.0
+      unit: ratio
+      tier: 1
+      source: definition
+      note: Reference chip by definition.
+    provenance:
+      generated: {by: agent:claude-fable-5-1, at: 2026-09-18}
+      verified: []
+      status: draft
+      stale_after: 2027-03-31
+      sources:
+        - {resource: https://www.nvidia.com/en-us/data-center/h100/}
+        - {resource: https://images.nvidia.com/aem-dam/Solutions/documents/HGX-H100-PCF-Summary.pdf}
+        - {resource: https://www.actu-environnement.com/media/pdf/news-47749-acv-gpu-ademe.pdf}
+        - {resource: https://ecologits.ai/latest/methodology/llm_inference/}
+        - {resource: https://doc.api.boavizta.org/getting_started/single_server/}
+
+  # ---- Newer chips. Work stays in H100-seconds; each chip carries the energy it
+  # spends per H100-second of work relative to an H100. The honest finding from
+  # ML.ENERGY's paired H100/B200 runs (55 matched batch sizes, 10 models, Feb
+  # 2026): a newer chip is only greener when it is kept busy. gpt-oss-120b on
+  # B200 uses 0.66 to 0.80x the energy per token; a 1 kW B200 serving an 8B
+  # dense model at batch 8 uses 1.9x. Median across every pair is 0.98.
+  # Embodied figures for non-H100 chips are scaled from the H100 record by die
+  # area and HBM and are tier 3 until a PCF exists.
+
+  h200-sxm:
+    label: NVIDIA H200 SXM 141GB
+    tdp_w: {value: 700, unit: W, tier: 1, source: https://www.nvidia.com/en-us/data-center/h200/, note: "Up to 700W (configurable)"}
+    peak_dense_flops: {value: 9.89e14, unit: FLOP/s, tier: 1, source: https://www.nvidia.com/en-us/data-center/h200/, note: "Same GH100 die; 1,979 TFLOPS BF16 with sparsity = 989 dense."}
+    embodied_kgco2e_per_gpu: {value: 550, min: 300, max: 1080, unit: kgCO2e per GPU incl. server share, tier: 3, source: derived, note: "H100 record x1.1 for 141 GB HBM3e vs 80 GB; no PCF published."}
+    lifetime_years: {value: 4.5, min: 3, max: 6, unit: years, tier: 3, source: assumption, note: Same policy as H100.}
+    active_fraction: {value: 0.7, min: 0.5, max: 1.0, unit: fraction, tier: 3, source: assumption, note: Same policy as H100.}
+    energy_vs_h100:
+      value: 0.85
+      min: 0.7
+      max: 1.0
+      unit: ratio
+      tier: 2
+      source: https://www.nvidia.com/en-us/data-center/h200/
+      note: "Spec-derived: identical compute and TDP, 4.8 vs 3.35 TB/s HBM. Decode is memory-bound so the ceiling is 0.7x; prefill is unchanged at 1.0x. No ML.ENERGY pair yet."
+    provenance: {generated: {by: agent:claude-fable-5-1, at: 2026-09-22}, verified: [], status: draft, stale_after: 2027-03-31, sources: [{resource: https://www.nvidia.com/en-us/data-center/h200/}]}
+
+  b200-sxm:
+    label: NVIDIA B200 SXM 180GB
+    tdp_w: {value: 1000, unit: W, tier: 1, source: https://www.nvidia.com/en-us/data-center/dgx-b200/, note: "DGX B200 ~14.3 kW for 8 GPUs; per-GPU TDP up to 1,000 W."}
+    peak_dense_flops: {value: 2.25e15, unit: FLOP/s, tier: 1, source: https://www.nvidia.com/en-us/data-center/dgx-b200/, note: "FP8 72 PFLOPS sparse per 8-GPU system = 4.5 PFLOPS dense FP8 per GPU = 2.25 PFLOPS dense BF16."}
+    embodied_kgco2e_per_gpu: {value: 750, min: 414, max: 1478, unit: kgCO2e per GPU incl. server share, tier: 3, source: derived, note: "H100 record x1.5: dual-die 208 B transistors, 180 to 192 GB HBM3e, heavier board. No PCF published."}
+    lifetime_years: {value: 4.5, min: 3, max: 6, unit: years, tier: 3, source: assumption, note: Same policy as H100.}
+    active_fraction: {value: 0.7, min: 0.5, max: 1.0, unit: fraction, tier: 3, source: assumption, note: Same policy as H100.}
+    energy_vs_h100:
+      value: 0.8
+      min: 0.65
+      max: 1.6
+      unit: ratio
+      tier: 1
+      source: https://raw.githubusercontent.com/ml-energy/leaderboard/master/public/data/tasks/gpqa.json
+      note: "Measured. ML.ENERGY v3.0 paired runs: gpt-oss-120b 0.66 to 0.80 across batch 8 to 2048, gpt-oss-20b 0.65 to 0.88, Qwen3-235B FP8 0.71 to 0.81; but BF16 dense 8 to 32B models at batch 8 to 16 run 1.2 to 2.0x because the 1 kW chip idles. Point 0.8 for the MoE, high-batch serving our providers do; max covers the small-dense-low-batch case."
+    provenance: {generated: {by: agent:claude-fable-5-1, at: 2026-09-22}, verified: [], status: draft, stale_after: 2027-03-31, sources: [{resource: https://www.nvidia.com/en-us/data-center/dgx-b200/}, {resource: https://raw.githubusercontent.com/ml-energy/leaderboard/master/public/data/tasks/gpqa.json}]}
+
+  mi300x:
+    label: AMD Instinct MI300X 192GB
+    tdp_w: {value: 750, unit: W, tier: 1, source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/data-sheets/amd-instinct-mi300x-data-sheet.pdf, note: "Datasheet: Maximum TBP 750W (read from the PDF 2026-09-22)."}
+    peak_dense_flops: {value: 1.3074e15, unit: FLOP/s, tier: 1, source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/data-sheets/amd-instinct-mi300x-data-sheet.pdf, note: "Datasheet: BFLOAT16 1307.4 TFLOPs dense, 2614.9 with sparsity; 192 GB HBM3 at 5.3 TB/s."}
+    embodied_kgco2e_per_gpu: {value: 650, min: 360, max: 1280, unit: kgCO2e per GPU incl. server share, tier: 3, source: derived, note: "H100 record x1.3: 8 XCD + 4 IOD chiplets, 192 GB HBM3. No PCF published."}
+    lifetime_years: {value: 4.5, min: 3, max: 6, unit: years, tier: 3, source: assumption, note: Same policy as H100.}
+    active_fraction: {value: 0.7, min: 0.5, max: 1.0, unit: fraction, tier: 3, source: assumption, note: Same policy as H100.}
+    energy_vs_h100:
+      value: 0.9
+      min: 0.7
+      max: 1.3
+      unit: ratio
+      tier: 3
+      note: "Spec says 0.7 to 0.8 (1.07x TBP, 1.32x FLOPS, 1.58x bandwidth vs H100) but ROCm inference kernels reach lower MFU than CUDA in every public benchmark, so the point sits near parity. No ML.ENERGY measurement."
+      source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/data-sheets/amd-instinct-mi300x-data-sheet.pdf
+    provenance: {generated: {by: agent:claude-fable-5-1, at: 2026-09-22}, verified: [{by: agent:claude-fable-5-1, at: 2026-09-22}], status: draft, stale_after: 2027-03-31, sources: [{resource: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/data-sheets/amd-instinct-mi300x-data-sheet.pdf}]}
+
+  mi325x:
+    label: AMD Instinct MI325X 256GB
+    tdp_w: {value: 1000, unit: W, tier: 1, source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/product-briefs/instinct-mi325x-datasheet.pdf, note: "Datasheet: Maximum TBP 1000W (read from the PDF 2026-09-22)."}
+    peak_dense_flops: {value: 1.3074e15, unit: FLOP/s, tier: 1, source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/product-briefs/instinct-mi325x-datasheet.pdf, note: "Datasheet: BFLOAT16 1307.4 TFLOPs dense, 2614.9 with sparsity; 256 GB HBM3E at 6 TB/s. Same CDNA 3 compute as MI300X."}
+    embodied_kgco2e_per_gpu: {value: 700, min: 390, max: 1380, unit: kgCO2e per GPU incl. server share, tier: 3, source: derived, note: "H100 record x1.4: MI300X package plus 256 GB HBM3e. No PCF published."}
+    lifetime_years: {value: 4.5, min: 3, max: 6, unit: years, tier: 3, source: assumption, note: Same policy as H100.}
+    active_fraction: {value: 0.7, min: 0.5, max: 1.0, unit: fraction, tier: 3, source: assumption, note: Same policy as H100.}
+    energy_vs_h100:
+      value: 1.0
+      min: 0.75
+      max: 1.4
+      unit: ratio
+      tier: 3
+      note: "Same compute as MI300X at 1.33x the power; the extra bandwidth helps decode but not enough to pay for the watts unless batches are large. Spec-derived, no measurement."
+      source: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/product-briefs/instinct-mi325x-datasheet.pdf
+    provenance: {generated: {by: agent:claude-fable-5-1, at: 2026-09-22}, verified: [{by: agent:claude-fable-5-1, at: 2026-09-22}], status: draft, stale_after: 2027-03-31, sources: [{resource: https://www.amd.com/content/dam/amd/en/documents/instinct-tech-docs/product-briefs/instinct-mi325x-datasheet.pdf}]}