greenpick 0.1.0__py3-none-any.whl

greenpick/data/entsoe_repository.py

@@ -0,0 +1,401 @@
+"""ENTSO-E Transparency Platform carbon source (EU zones).
+
+Free EU grid data. We query A75 (Actual Generation per Production Type) for a region's
+area (EIC code), take the most recent period's MW per production type, and weight by
+per-fuel emission factors -> directional gCO2/kWh. Mirrors the EIA source for the EU.
+
+Token (free): register at https://transparency.entsoe.eu/ then request API access
+(email transparency@entsoe.eu per their docs) -> security token.
+Endpoint: GET https://web-api.tp.entsoe.eu/api
+  params: securityToken, documentType=A75, processType=A16 (realised),
+          in_Domain=<area EIC>, periodStart/periodEnd = YYYYMMDDHHMM (UTC)
+Response: XML with <TimeSeries> per production type:
+  <MktPSRType><psrType>B04</psrType></MktPSRType> and <Period><Point><quantity> MW.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import time
+from datetime import datetime, timedelta, timezone
+from xml.etree import ElementTree as ET
+
+import httpx
+
+from ..models import CarbonReading, Provider, HourlyCarbon, ForecastHour
+from .mock_repository import MockCarbonRepository
+from .static_data import region_meta, emission_factors
+
+log = logging.getLogger("greenpick.entsoe")
+
+_URL = "https://web-api.tp.entsoe.eu/api"
+
+
+def _strip_ns(tag: str) -> str:
+    """ENTSO-E XML is namespaced; strip '{ns}tag' -> 'tag' for simple matching."""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _parse_interval_start(text: str) -> datetime | None:
+    """ENTSO-E timestamps look like '2026-10-11T18:00Z' or '2026-10-11T18:00:00Z'.
+    Parse to an aware UTC datetime; return None if unrecognisable."""
+    if not text:
+        return None
+    t = text.strip().replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(t)
+    except ValueError:
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def _resolution_minutes(text: str) -> int:
+    """Parse an ISO-8601 duration like 'PT60M' / 'PT15M' / 'PT1H' -> minutes.
+    Defaults to 60 if absent/unrecognised (A75 realised data is typically hourly)."""
+    if not text:
+        return 60
+    m = re.match(r"PT(?:(\d+)H)?(?:(\d+)M)?", text.strip())
+    if not m:
+        return 60
+    hours = int(m.group(1) or 0)
+    mins = int(m.group(2) or 0)
+    total = hours * 60 + mins
+    return total or 60
+
+
+class ENTSOERepository:
+    def __init__(self, token: str, cache_ttl_seconds: int = 1800) -> None:
+        self._token = token
+        self._ttl = cache_ttl_seconds
+        self._cache: dict[str, tuple[float, CarbonReading]] = {}  # EIC -> (fetched_at, reading)
+        self._fallback = MockCarbonRepository()
+        self._warned_no_token = False
+
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        meta = region_meta(provider, region) or {}
+        eic = meta.get("entsoe_eic")
+
+        if not self._token:
+            if not self._warned_no_token:
+                log.warning("No ENTSOE_TOKEN set — falling back to mock. Register at "
+                            "https://transparency.entsoe.eu/ and request API access.")
+                self._warned_no_token = True
+            return await self._fallback.carbon_now(provider, region)
+        if not eic:
+            # Non-EU region (no ENTSO-E area) -> mock, labelled.
+            return await self._fallback.carbon_now(provider, region)
+
+        hit = self._cache.get(eic)
+        if hit and (time.time() - hit[0]) < self._ttl:
+            cached = hit[1]
+            return cached.model_copy(update={"region": region, "provider": provider, "quality": "cached"})
+
+        xml_text = await self._fetch_xml(eic, hours_back=3)
+        if xml_text is None:
+            return await self._fallback.carbon_now(provider, region)
+        reading = self._xml_to_reading(provider, region, xml_text)
+        if reading is None:
+            return await self._fallback.carbon_now(provider, region)
+        self._cache[eic] = (time.time(), reading)
+        return reading
+
+    async def _fetch_xml(self, eic: str, hours_back: int) -> str | None:
+        """Fetch A75 realised-generation XML for an area over the last `hours_back` hours.
+        Retries transient empties/errors; returns the body text, or None on auth failure or
+        exhausted retries (callers fall back to mock). Shared by carbon_now and carbon_history."""
+        now = datetime.now(timezone.utc)
+        start = now - timedelta(hours=hours_back)
+        params = {
+            "securityToken": self._token,
+            "documentType": "A75",
+            "processType": "A16",
+            "in_Domain": eic,
+            "periodStart": start.strftime("%Y%m%d%H%M"),
+            "periodEnd": now.strftime("%Y%m%d%H%M"),
+        }
+
+        # ENTSO-E is occasionally slow / empty for a given zone (their docs warn about response
+        # times). Retry a couple of times before degrading to mock, since a transient miss would
+        # otherwise show a region as mock for the whole cache window.
+        import asyncio
+        attempts = 3
+        for attempt in range(1, attempts + 1):
+            try:
+                async with httpx.AsyncClient(timeout=15) as client:
+                    resp = await client.get(_URL, params=params)
+                if resp.status_code in (401, 403):
+                    log.warning("ENTSO-E rejected the token (HTTP %s) — using mock. Check ENTSOE_TOKEN.",
+                                resp.status_code)
+                    return None   # auth: don't retry
+                resp.raise_for_status()
+                if resp.text and "<TimeSeries" in resp.text:
+                    return resp.text
+                # 200 but no usable generation (transient empty) -> retry
+                log.debug("ENTSO-E empty for %s (attempt %d/%d)", eic, attempt, attempts)
+            except Exception as e:
+                log.debug("ENTSO-E call failed for %s (attempt %d/%d): %s", eic, attempt, attempts, e)
+            if attempt < attempts:
+                await asyncio.sleep(0.6 * attempt)   # brief backoff: 0.6s, 1.2s
+        return None
+
+    async def _fetch_forecast_xml(self, eic: str, document_type: str, hours_ahead: int,
+                                  load: bool = False) -> str | None:
+        """Fetch a day-ahead FORWARD forecast document (periodStart=now). document_type is e.g.
+        'A69' (wind+solar) or 'A65' (load). Load uses outBiddingZone_Domain, generation uses
+        in_Domain. Returns body text or None (auth fail / exhausted retries / empty)."""
+        now = datetime.now(timezone.utc)
+        end = now + timedelta(hours=hours_ahead)
+        params = {
+            "securityToken": self._token,
+            "documentType": document_type,
+            "processType": "A01",   # day-ahead
+            "periodStart": now.strftime("%Y%m%d%H%M"),
+            "periodEnd": end.strftime("%Y%m%d%H%M"),
+        }
+        params["outBiddingZone_Domain" if load else "in_Domain"] = eic
+
+        import asyncio
+        attempts = 3
+        for attempt in range(1, attempts + 1):
+            try:
+                async with httpx.AsyncClient(timeout=15) as client:
+                    resp = await client.get(_URL, params=params)
+                if resp.status_code in (401, 403):
+                    log.warning("ENTSO-E rejected the token (HTTP %s) on forecast — using fallback.",
+                                resp.status_code)
+                    return None
+                resp.raise_for_status()
+                if resp.text and "<TimeSeries" in resp.text:
+                    return resp.text
+                # 'No matching data' (common for A65 in some zones) is not retryable — bail quietly.
+                if "No matching data" in resp.text:
+                    log.debug("ENTSO-E %s: no matching data for %s", document_type, eic)
+                    return None
+                log.debug("ENTSO-E %s empty for %s (attempt %d/%d)", document_type, eic, attempt, attempts)
+            except Exception as e:
+                log.debug("ENTSO-E %s failed for %s (attempt %d/%d): %s",
+                          document_type, eic, attempt, attempts, e)
+            if attempt < attempts:
+                await asyncio.sleep(0.6 * attempt)
+        return None
+
+    async def renewable_forecast(self, provider: Provider, region: str, hours_ahead: int = 24
+                                 ) -> list[ForecastHour]:
+        """Forward-looking renewable (wind+solar) output forecast per hour, for 'which upcoming
+        hours are cleaner' scheduling. Uses A69 (reliable across zones); where A65 load is also
+        available, adds a renewable-share ratio. Returns [] if no token/EIC/forecast (caller
+        falls back to the historical pattern). RELATIVE signal, not a gCO2/kWh forecast."""
+        meta = region_meta(provider, region) or {}
+        eic = meta.get("entsoe_eic")
+        if not self._token or not eic:
+            return []
+
+        a69 = await self._fetch_forecast_xml(eic, "A69", hours_ahead, load=False)
+        if a69 is None:
+            return []
+        renew_by_hour = self._forecast_mw_by_hour(a69)   # sums wind+solar across its TimeSeries
+        if not renew_by_hour:
+            return []
+
+        # Optional refinement: load forecast (A65) -> renewable share. Best-effort; many zones 404.
+        load_by_hour: dict[str, float] = {}
+        a65 = await self._fetch_forecast_xml(eic, "A65", hours_ahead, load=True)
+        if a65 is not None:
+            load_by_hour = self._forecast_mw_by_hour(a65)
+
+        out: list[ForecastHour] = []
+        for hour_iso in sorted(renew_by_hour):
+            mw = round(renew_by_hour[hour_iso], 1)
+            share = None
+            load = load_by_hour.get(hour_iso)
+            if load and load > 0:
+                share = round(min(1.0, mw / load), 3)
+            out.append(ForecastHour(period=hour_iso, renewable_mw=mw, renewable_share=share))
+        return out
+
+    def _forecast_mw_by_hour(self, xml_text: str) -> dict[str, float]:
+        """Parse a forecast document (A69/A65) into {hour_iso -> summed MW}. Sums across all
+        TimeSeries (e.g. wind + solar), mapping each Point's position to its hour via the period
+        start + resolution. Sub-hourly points are summed into their hour (then we'd double-count,
+        so we AVERAGE within an hour per TimeSeries instead — see below)."""
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError:
+            return {}
+
+        totals: dict[str, float] = {}
+        for ts in root.iter():
+            if _strip_ns(ts.tag) != "TimeSeries":
+                continue
+            for el in ts.iter():
+                if _strip_ns(el.tag) != "Period":
+                    continue
+                start_dt = None
+                resolution_min = 60
+                for c in el.iter():
+                    ct = _strip_ns(c.tag)
+                    if ct == "start" and c.text and start_dt is None:
+                        start_dt = _parse_interval_start(c.text)
+                    elif ct == "resolution" and c.text:
+                        resolution_min = _resolution_minutes(c.text)
+                if start_dt is None:
+                    continue
+                # Collect per-hour: average sub-hourly points within an hour (MW is a rate, not a
+                # sum over sub-intervals), then add this TimeSeries' hourly value to the total.
+                hour_vals: dict[str, list[float]] = {}
+                for pt in el.iter():
+                    if _strip_ns(pt.tag) != "Point":
+                        continue
+                    pos = qty = None
+                    for c in pt:
+                        ct = _strip_ns(c.tag)
+                        if ct == "position" and c.text:
+                            pos = int(c.text)
+                        elif ct == "quantity" and c.text:
+                            qty = float(c.text)
+                    if pos is None or qty is None:
+                        continue
+                    point_dt = start_dt + timedelta(minutes=(pos - 1) * resolution_min)
+                    hour_iso = point_dt.strftime("%Y-%m-%dT%H")
+                    hour_vals.setdefault(hour_iso, []).append(qty)
+                for hour_iso, vals in hour_vals.items():
+                    totals[hour_iso] = totals.get(hour_iso, 0.0) + sum(vals) / len(vals)
+        return totals
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        """Recent hourly carbon intensity for an EU zone, for scheduling deferrable work.
+
+        Parses A75 realised generation across the whole 24h window (every Point position,
+        not just the latest), aligns all production types onto their hour, and weights each
+        hour's fuel mix by emission factors. Falls back to the synthetic mock curve only when
+        there's no token, no EIC, or the fetch/parse yields nothing usable."""
+        meta = region_meta(provider, region) or {}
+        eic = meta.get("entsoe_eic")
+        if not self._token or not eic:
+            return await self._fallback.carbon_history(provider, region)
+
+        xml_text = await self._fetch_xml(eic, hours_back=24)
+        if xml_text is None:
+            return await self._fallback.carbon_history(provider, region)
+
+        series = self._xml_to_hourly(xml_text)
+        return series or await self._fallback.carbon_history(provider, region)
+
+    def _xml_to_hourly(self, xml_text: str) -> list[HourlyCarbon]:
+        """Parse A75 XML into an hourly carbon series.
+
+        For each TimeSeries (one production type) we walk every Point, map its position to a
+        timestamp (period start + (position-1) * resolution), and accumulate MW per fuel into
+        the Point's hour bucket. Then per hour: weighted mean of fuels -> gCO2/kWh.
+        Sub-hourly resolutions (e.g. PT15M) are summed into their containing hour."""
+        factor_map = emission_factors()["entsoe_psrtype_to_factor"]
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError:
+            return []
+
+        # hour_iso -> {psrType -> summed MW}  (MW summed across sub-hour points & timeseries chunks)
+        by_hour: dict[str, dict[str, float]] = {}
+
+        for ts in root.iter():
+            if _strip_ns(ts.tag) != "TimeSeries":
+                continue
+            psr = None
+            for el in ts.iter():
+                tag = _strip_ns(el.tag)
+                if tag == "psrType" and el.text:
+                    psr = el.text.strip()
+                elif tag == "Period":
+                    start_dt = None
+                    resolution_min = 60
+                    for c in el.iter():
+                        ct = _strip_ns(c.tag)
+                        if ct == "start" and c.text and start_dt is None:
+                            start_dt = _parse_interval_start(c.text)
+                        elif ct == "resolution" and c.text:
+                            resolution_min = _resolution_minutes(c.text)
+                    if start_dt is None or psr is None or psr not in factor_map:
+                        continue
+                    for pt in el.iter():
+                        if _strip_ns(pt.tag) != "Point":
+                            continue
+                        pos = qty = None
+                        for c in pt:
+                            ct = _strip_ns(c.tag)
+                            if ct == "position" and c.text:
+                                pos = int(c.text)
+                            elif ct == "quantity" and c.text:
+                                qty = float(c.text)
+                        if pos is None or qty is None:
+                            continue
+                        point_dt = start_dt + timedelta(minutes=(pos - 1) * resolution_min)
+                        hour_iso = point_dt.strftime("%Y-%m-%dT%H")
+                        bucket = by_hour.setdefault(hour_iso, {})
+                        bucket[psr] = bucket.get(psr, 0.0) + qty
+
+        out: list[HourlyCarbon] = []
+        for hour_iso in sorted(by_hour):
+            fuels = by_hour[hour_iso]
+            total = sum(fuels.values())
+            if total <= 0:
+                continue
+            weighted = sum(mw * factor_map[f] for f, mw in fuels.items())
+            out.append(HourlyCarbon(period=hour_iso, g_co2_per_kwh=round(weighted / total, 1)))
+        return out
+
+    def _xml_to_reading(self, provider: Provider, region: str, xml_text: str) -> CarbonReading | None:
+        """Parse A75 XML: for each TimeSeries (one production type), take its latest
+        Point quantity; weight all types by emission factors -> gCO2/kWh."""
+        factor_map = emission_factors()["entsoe_psrtype_to_factor"]
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError:
+            return None
+
+        gen_by_fuel: dict[str, float] = {}   # psrType -> latest MW
+        latest_ts = ""
+
+        for ts in root.iter():
+            if _strip_ns(ts.tag) != "TimeSeries":
+                continue
+            psr = None
+            latest_qty = None
+            latest_pos_time = ""
+            for el in ts.iter():
+                tag = _strip_ns(el.tag)
+                if tag == "psrType" and el.text:
+                    psr = el.text.strip()
+                elif tag == "Period":
+                    # find the newest Point in this period by its 'position'
+                    start_el = next((c for c in el.iter() if _strip_ns(c.tag) == "start"), None)
+                    pstart = start_el.text if start_el is not None else ""
+                    best_pos = -1
+                    for pt in el.iter():
+                        if _strip_ns(pt.tag) != "Point":
+                            continue
+                        pos = qty = None
+                        for c in pt:
+                            ct = _strip_ns(c.tag)
+                            if ct == "position" and c.text:
+                                pos = int(c.text)
+                            elif ct == "quantity" and c.text:
+                                qty = float(c.text)
+                        if pos is not None and qty is not None and pos > best_pos:
+                            best_pos, latest_qty, latest_pos_time = pos, qty, pstart or ""
+            if psr and latest_qty is not None and psr in factor_map:
+                # Keep the max across time series chunks (latest known MW for that fuel).
+                gen_by_fuel[psr] = max(gen_by_fuel.get(psr, 0.0), latest_qty)
+                latest_ts = latest_ts or latest_pos_time
+
+        total = sum(gen_by_fuel.values())
+        if total <= 0:
+            return None
+        weighted = sum(mw * factor_map[f] for f, mw in gen_by_fuel.items())
+        return CarbonReading(
+            region=region,
+            provider=provider,
+            g_co2_per_kwh=round(weighted / total, 1),
+            source="entsoe",
+            timestamp=latest_ts or datetime.now(timezone.utc).isoformat(),
+            quality="live",
+        )

greenpick/data/gpu_power.json

@@ -0,0 +1,26 @@
+{
+  "_comment": "Directional power model for datacenter GPU/accelerator training, used to estimate the energy (kWh) of a training run so it can be placed in a greener region and/or timed to the cleanest hours. tdp_watts are PUBLISHED peak board power (TDP) from NVIDIA datasheets and corroborating sources; a training run does NOT sit at TDP the whole time, so energy = tdp_watts * gpu_count * default_utilization * hours, plus a per-GPU host overhead, all x datacenter PUE at calc time. ORDER-OF-MAGNITUDE, directional estimates. NOT measured for your model/run. Replace with measured power telemetry before any non-directional use.",
+  "_as_of": "2026-10-12",
+  "_sources": "NVIDIA datasheets/product pages (A100 400W SXM; H100 700W SXM / 350W PCIe; H200 700W; T4 70W; L4 72W; V100 300W SXM; L40S 350W; B200 ~1000W; GB200 superchip ~1200W). Corroborated across NVIDIA, thundercompute, cyfuture, semianalysis, gmicloud (2024-2026). Values rounded.",
+  "_method": {
+    "formula": "energy_kwh = (sum over GPUs of [tdp_watts * utilization + host_overhead_watts_per_gpu]) / 1000 * gpu_hours_per_gpu * pue",
+    "utilization_note": "TDP is PEAK board power. Sustained training typically averages below TDP; default_utilization (0.85) is a documented directional assumption, overridable per call.",
+    "host_overhead_note": "Each accelerator is fed by host CPU/RAM/NIC/storage; host_overhead_watts_per_gpu is a rough per-GPU allocation of that non-GPU server draw. Directional.",
+    "pue_note": "Datacenter overhead multiplier taken from power.json pue_default at calculation time (not duplicated here)."
+  },
+  "default_utilization": 0.85,
+  "host_overhead_watts_per_gpu": 100,
+  "gpus": {
+    "t4":    { "name": "NVIDIA T4",        "arch": "Turing", "tdp_watts": 70,   "class": "inference", "aliases": ["tesla-t4"] },
+    "l4":    { "name": "NVIDIA L4",        "arch": "Ada Lovelace", "tdp_watts": 72, "class": "inference", "aliases": [] },
+    "v100":  { "name": "NVIDIA V100 (SXM)", "arch": "Volta", "tdp_watts": 300,  "class": "training", "aliases": ["tesla-v100"] },
+    "l40s":  { "name": "NVIDIA L40S",      "arch": "Ada Lovelace", "tdp_watts": 350, "class": "training/graphics", "aliases": ["l40"] },
+    "a100":  { "name": "NVIDIA A100 (SXM 80GB)", "arch": "Ampere", "tdp_watts": 400, "class": "training", "aliases": ["a100-80gb", "a100-sxm"] },
+    "a100-pcie": { "name": "NVIDIA A100 (PCIe)", "arch": "Ampere", "tdp_watts": 300, "class": "training", "aliases": [] },
+    "h100":  { "name": "NVIDIA H100 (SXM)", "arch": "Hopper", "tdp_watts": 700, "class": "training", "aliases": ["h100-sxm"] },
+    "h100-pcie": { "name": "NVIDIA H100 (PCIe)", "arch": "Hopper", "tdp_watts": 350, "class": "training", "aliases": [] },
+    "h200":  { "name": "NVIDIA H200",      "arch": "Hopper", "tdp_watts": 700,  "class": "training", "aliases": [] },
+    "b200":  { "name": "NVIDIA B200",      "arch": "Blackwell", "tdp_watts": 1000, "class": "training", "aliases": [] },
+    "gb200": { "name": "NVIDIA GB200 Superchip", "arch": "Blackwell", "tdp_watts": 1200, "class": "training", "aliases": ["gb200-superchip"], "_note": "Two Blackwell GPUs + Grace CPU; TDP is the combined superchip." }
+  }
+}

greenpick/data/inference_energy.json

@@ -0,0 +1,50 @@
+{
+  "_comment": "Directional energy intensity for LLM INFERENCE, by model SIZE CLASS, in Wh per 1,000 OUTPUT tokens. Output tokens dominate inference energy (generation is the costly part; R^2>0.95 vs output length in measurement studies). These are LOW-HIGH bands, not point values: serving choices (quantisation, batching, request shaping) move energy by up to ~100x for the SAME model, so a single number would be false precision. Keyed on size class, NOT named commercial products (vendors don't disclose serving hardware/batching). Estimate, not a measurement; for self-hosted/open models the band is most trustworthy. Replace with your own measured J/token before any non-directional use.",
+  "_as_of": "2026-10-16",
+  "_unit": "Wh per 1000 output tokens",
+  "_sources": "Directional, synthesised from peer-reviewed inference-energy measurement studies (2024-2026): arXiv 2509.20241 (median 0.34 Wh/query, IQR 0.18-0.67, for >200B models on an H100 node w/ realistic utilisation+PUE); arXiv 2505.09598 (~0.42 Wh short GPT-4o query); arXiv 2407.16893 (70B ~2 orders of magnitude more energy/token than small models; output length predicts energy R^2>0.95); arXiv 2601.22362 (quantisation/batching/shaping => up to ~100x spread, same model). Bands rounded by GreenPick. Assume a ~300-output-token 'typical query' when converting to per-query.",
+  "_notes": {
+    "output_tokens_dominate": "Energy tracks OUTPUT (generated) tokens + response time far more than input tokens. The tool keys on output tokens; if only total tokens are known, assume ~25-40% are output or flag the assumption.",
+    "moe": "Mixture-of-Experts models run near their ACTIVE parameter count, not total — a '~400B MoE' behaves more like a mid/large dense model, NOT like dense-400B. Use the 'moe_frontier' class, not 'frontier_dense', for MoE.",
+    "serving_variance": "quantisation (int8/int4), batching, and request shaping can cut energy many-fold; a naive un-batched fp16 deployment sits near the HIGH end. Hence bands, not points."
+  },
+  "size_classes": {
+    "small": {
+      "label": "small (~1-7B params)",
+      "wh_per_1k_output_tokens_low": 0.15,
+      "wh_per_1k_output_tokens_high": 0.9,
+      "example_models": "Llama-3-8B, Mistral-7B, Phi-3"
+    },
+    "mid": {
+      "label": "mid (~8-34B params)",
+      "wh_per_1k_output_tokens_low": 0.6,
+      "wh_per_1k_output_tokens_high": 3.5,
+      "example_models": "Llama-3-13B, Mixtral-ish dense, Qwen-32B"
+    },
+    "large": {
+      "label": "large (~35-120B dense)",
+      "wh_per_1k_output_tokens_low": 2.5,
+      "wh_per_1k_output_tokens_high": 12.0,
+      "example_models": "Llama-3-70B, dense ~70B"
+    },
+    "frontier_dense": {
+      "label": "frontier dense (>200B)",
+      "wh_per_1k_output_tokens_low": 8.0,
+      "wh_per_1k_output_tokens_high": 30.0,
+      "example_models": "dense >200B (research-scale); ~0.34 Wh median per typical query"
+    },
+    "moe_frontier": {
+      "label": "frontier MoE (large total, smaller active)",
+      "wh_per_1k_output_tokens_low": 3.0,
+      "wh_per_1k_output_tokens_high": 15.0,
+      "example_models": "Mixture-of-Experts frontier models (active params << total)"
+    }
+  },
+  "_aliases": {
+    "1b": "small", "3b": "small", "7b": "small", "8b": "small",
+    "13b": "mid", "14b": "mid", "32b": "mid", "34b": "mid",
+    "70b": "large", "65b": "large",
+    "175b": "frontier_dense", "200b": "frontier_dense", "400b": "frontier_dense",
+    "moe": "moe_frontier", "mixtral": "moe_frontier"
+  }
+}

greenpick/data/instance_families.json

@@ -0,0 +1,32 @@
+{
+  "_comment": "Directional energy-efficiency (performance-per-watt) multipliers for general-purpose instance FAMILIES, used to suggest a greener same-size family in the same region. The carbon mechanism is real: newer process nodes and ARM (Graviton-class) cores do the same work on less energy. 'relative_energy' is the energy drawn to deliver a fixed amount of work, normalised so a modern x86 generation = 1.00; LOWER is greener. These are ORDER-OF-MAGNITUDE, directional figures consistent with public vendor/analyst claims (e.g. AWS Graviton ~60% less energy for the same performance; each x86 generation ~10-20% better perf/watt). NOT measured for your workload. Replace with cited, benchmarked values before any non-directional use.",
+  "_as_of": "2026-10-12",
+  "_source": "Directional: AWS Graviton energy claims; Intel/AMD generational perf-per-watt disclosures; SPECpower-style public results. Normalised and rounded by GreenPick. Do not cite as measured.",
+  "_relative_energy_note": "relative_energy LOWER = greener (less energy for the same work). arch 'arm' families are the biggest honest win.",
+  "aws": {
+    "_general_purpose_generations": [
+      { "family": "m5",   "arch": "x86", "cpu": "Intel Xeon (Skylake/Cascade)", "relative_energy": 1.00, "generation": 5, "notes": "Baseline modern x86 general-purpose." },
+      { "family": "m6i",  "arch": "x86", "cpu": "Intel Xeon (Ice Lake)",        "relative_energy": 0.88, "generation": 6, "notes": "~10-15% better perf/watt than m5." },
+      { "family": "m7i",  "arch": "x86", "cpu": "Intel Xeon (Sapphire Rapids)", "relative_energy": 0.80, "generation": 7, "notes": "Newer x86; further perf/watt gain." },
+      { "family": "m6g",  "arch": "arm", "cpu": "AWS Graviton2",                "relative_energy": 0.55, "generation": 6, "notes": "ARM; AWS claims large energy reduction for same work." },
+      { "family": "m7g",  "arch": "arm", "cpu": "AWS Graviton3",                "relative_energy": 0.45, "generation": 7, "notes": "Greenest general-purpose option where ARM is viable." }
+    ]
+  },
+  "gcp": {
+    "_general_purpose_generations": [
+      { "family": "n1",         "arch": "x86", "cpu": "Intel (Skylake/Broadwell)", "relative_energy": 1.08, "generation": 1, "notes": "Older generation; least efficient." },
+      { "family": "n2",         "arch": "x86", "cpu": "Intel Cascade/Ice Lake",    "relative_energy": 1.00, "generation": 2, "notes": "Baseline modern x86." },
+      { "family": "n2d",        "arch": "x86", "cpu": "AMD EPYC (Milan)",          "relative_energy": 0.90, "generation": 2, "notes": "AMD; typically better perf/watt than n2." },
+      { "family": "c3",         "arch": "x86", "cpu": "Intel Sapphire Rapids",     "relative_energy": 0.80, "generation": 3, "notes": "Newer x86." },
+      { "family": "c4a",        "arch": "arm", "cpu": "Google Axion",              "relative_energy": 0.47, "generation": 4, "notes": "ARM (Axion); greenest where ARM is viable." }
+    ]
+  },
+  "azure": {
+    "_general_purpose_generations": [
+      { "family": "Dv4",  "arch": "x86", "cpu": "Intel Cascade Lake",   "relative_energy": 1.05, "generation": 4, "notes": "Older modern x86." },
+      { "family": "Dv5",  "arch": "x86", "cpu": "Intel Ice Lake",       "relative_energy": 1.00, "generation": 5, "notes": "Baseline modern x86." },
+      { "family": "Dasv5","arch": "x86", "cpu": "AMD EPYC (Milan)",     "relative_energy": 0.90, "generation": 5, "notes": "AMD; better perf/watt than Dv5." },
+      { "family": "Dpsv5","arch": "arm", "cpu": "Ampere Altra",         "relative_energy": 0.52, "generation": 5, "notes": "ARM (Ampere); large energy reduction for same work." }
+    ]
+  }
+}

greenpick/data/mock_repository.py

@@ -0,0 +1,53 @@
+"""Mock carbon source — deterministic, offline, the default.
+
+Lets the whole server run and be tested without any API token or network. Values are
+plausible, stable per region, and clearly labelled quality="mock" so nothing mistakes
+them for real readings.
+"""
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from ..models import CarbonReading, Provider, HourlyCarbon
+
+# Rough, stable gCO2/kWh per approximate grid zone (illustrative, NOT real-time).
+_ZONE_INTENSITY = {
+    "US-MIDA-PJM": 350,
+    "US-NW-PACW": 110,
+    "US-MIDW-MISO": 430,
+    "IE": 290,
+    "SE": 25,
+    "FI": 70,
+    "AU-NSW": 580,
+}
+_DEFAULT = 400
+
+
+class MockCarbonRepository:
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        from .static_data import region_meta
+        meta = region_meta(provider, region) or {}
+        zone = meta.get("zone", "")
+        intensity = _ZONE_INTENSITY.get(zone, _DEFAULT)
+        return CarbonReading(
+            region=region,
+            provider=provider,
+            g_co2_per_kwh=float(intensity),
+            source="mock",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            quality="mock",
+        )
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        """Synthetic 24h curve around the region's base intensity: cleaner overnight / midday
+        (solar), dirtier at evening peak — a plausible shape so scheduling logic is testable offline."""
+        from .static_data import region_meta
+        meta = region_meta(provider, region) or {}
+        base = _ZONE_INTENSITY.get(meta.get("zone", ""), _DEFAULT)
+        out: list[HourlyCarbon] = []
+        for h in range(24):
+            # +/-30% swing: trough ~04:00 and ~13:00, peak ~19:00.
+            factor = 1 + 0.3 * math.sin((h - 9) / 24 * 2 * math.pi) \
+                     - 0.15 * math.cos((h - 13) / 24 * 4 * math.pi)
+            out.append(HourlyCarbon(period=f"H{h:02d}", g_co2_per_kwh=round(base * factor, 1)))
+        return out

greenpick/data/network.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "Directional network data-transfer energy intensity, used ONLY for a secondary 'transfer carbon' signal in the data-locality / egress check. The primary output of that tool is egress COST; this carbon figure is deliberately coarse because the science is unsettled.",
+  "_as_of": "2026-10-12",
+  "kwh_per_gb_transfer": 0.03,
+  "_uncertainty": "WIDE. Published estimates for internet data-transfer energy intensity span ~0.004 to 136 kWh/GB (orders of magnitude). A peer-reviewed 2015 figure was ~0.06 kWh/GB, expected to roughly halve every ~2 years; 0.03 reflects continued efficiency gains. Recent literature argues per-GB intensity is a poor model and that network energy is not directly proportional to data volume. Treat this as order-of-magnitude only.",
+  "_sources": "Aslan et al. 2018 (Electricity Intensity of Internet Data Transmission, ~0.06 kWh/GB for 2015); Whole Grain Digital review (range 0.004-136 kWh/GB); Journal of Industrial Ecology 2024 (power-model critique of per-GB intensity). Not a measurement; replace with a cited, workload-specific model before any non-directional use."
+}

greenpick/data/power.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "Simple, documented power model for the carbon ESTIMATE. Turns a workload (vCPU, RAM) into average watts, then kWh/month. These are deliberately rough published-style coefficients; this is an estimate, not a measurement. PUE is the datacenter overhead multiplier.",
+  "watts_per_vcpu": 3.5,
+  "watts_per_gb_ram": 0.4,
+  "pue_default": 1.2,
+  "_sources": "Coefficients are order-of-magnitude figures consistent with public cloud power-model literature (e.g. Cloud Carbon Footprint methodology). Replace with cited values before any non-directional use."
+}

greenpick/data/pricing.json

@@ -0,0 +1,31 @@
+{
+  "_comment": "DATED, STATIC pricing ballpark for v1. Deterministic \u2014 the LLM must never invent these. Figures are rough on-demand approximations for a general-purpose vCPU+RAM service and per-GB internet egress; refresh periodically and update _as_of. NOT a quote.",
+  "_as_of": "2026-10-12",
+  "_units": {
+    "compute": "USD per vCPU-hour and USD per GB-RAM-hour",
+    "egress": "USD per GB to internet"
+  },
+  "_egress_comment": "Egress is NOT one price — it's a tier ladder by WHERE the bytes cross. We price the locality tier (same-region / cross-region / cross-cloud+internet) as a LOW-HIGH RANGE because region-pair rates vary. Per-GB, USD, DIRECTIONAL list prices as of _as_of; excludes free-tier allowances, committed-use/negotiated discounts, and NAT/load-balancer processing fees. Not a quote. Keys: internet rate stays per-provider (differs most); same-region & cross-region tiers are broadly consistent across AWS/GCP/Azure so we use one shared range.",
+  "_egress_tiers_usd_per_gb": {
+    "same_region": { "low": 0.0, "high": 0.01, "note": "Same region: free within an AZ over private IP; ~$0.01/GB each way if it crosses AZs." },
+    "cross_region_same_cloud": { "low": 0.01, "high": 0.02, "note": "Inter-region within one cloud: most pairs ~$0.01-0.02/GB; a few source regions/continent pairs run higher." },
+    "cross_cloud": { "low": 0.085, "high": 0.12, "note": "Leaving the cloud to another provider or the public internet: the expensive tier; GCP Premium ~$0.12, AWS ~$0.09, Azure ~$0.087 at entry bands." }
+  },
+  "_egress_sources": "AWS/GCP/Azure published data-transfer pricing pages + corroborating 2026 guides (usage.ai, nops.io, egresscost.com, redresscompliance, bacancy, tatacommunications). Rounded to ranges; verify against the provider pricing page for a specific region pair.",
+  "aws": {
+    "compute_usd_per_vcpu_hour": 0.0469,
+    "compute_usd_per_gb_ram_hour": 0.0039,
+    "egress_usd_per_gb": 0.09
+  },
+  "gcp": {
+    "compute_usd_per_vcpu_hour": 0.0438,
+    "compute_usd_per_gb_ram_hour": 0.0037,
+    "egress_usd_per_gb": 0.085
+  },
+  "azure": {
+    "compute_usd_per_vcpu_hour": 0.0472,
+    "compute_usd_per_gb_ram_hour": 0.0039,
+    "egress_usd_per_gb": 0.087
+  },
+  "_source": "Compute coefficients for [aws+azure+gcp] derived from Vantage live data using ONE matched method: general-purpose 4GB/vCPU families (AWS m5/m6i, GCP n2-standard, Azure D-series v5), on-demand Linux, mean $/vCPU across regions, 25% split to RAM. Egress remains static. Apples-to-apples DIRECTIONAL comparison, not a quote."
+}

greenpick/data/regions.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Minimal v1 region catalog: coordinates (for latency estimate) and an approximate grid-zone key (for carbon lookup). Zone mapping is country/zone-approximate — a known v1 limitation. Expand as needed.",
+  "_jurisdiction_comment": "'jurisdiction' is a STABLE geographic tag (EEA / US / AU / ...), used ONLY to flag when a recommended move crosses a data-residency boundary (esp. leaving the EEA). It is NOT a compliance verdict and encodes NO legal/adequacy status (those change — e.g. EU adequacy lists and the US framework shift over time). GreenPick flags the crossing; the user confirms legality with their own data governance. EEA = 27 EU states + Norway/Iceland/Liechtenstein (the GDPR transfer boundary).",
+  "aws": {
+    "us-east-1":      { "name": "N. Virginia",   "lat": 38.95, "lon": -77.45, "zone": "US-MIDA-PJM", "eia_ba": "PJM", "jurisdiction": "US" },
+    "us-west-2":      { "name": "Oregon",        "lat": 45.87, "lon": -119.69, "zone": "US-NW-PACW", "eia_ba": "BPAT", "jurisdiction": "US" },
+    "eu-west-1":      { "name": "Ireland",       "lat": 53.41, "lon": -8.24,  "zone": "IE", "entsoe_eic": "10Y1001A1001A59C", "jurisdiction": "EEA" },
+    "eu-north-1":     { "name": "Stockholm",     "lat": 59.33, "lon": 18.07,  "zone": "SE", "entsoe_eic": "10YSE-1--------K", "jurisdiction": "EEA" },
+    "ap-southeast-2": { "name": "Sydney",        "lat": -33.87, "lon": 151.21, "zone": "AU-NSW", "jurisdiction": "AU" },
+    "us-east-nyc":    { "name": "New York (NYISO)", "lat": 40.71, "lon": -74.01, "zone": "US-NY-NYIS", "eia_ba": "NYIS", "jurisdiction": "US" }
+  },
+  "gcp": {
+    "us-central1":    { "name": "Iowa",          "lat": 41.26, "lon": -95.86, "zone": "US-MIDW-MISO", "eia_ba": "MISO", "jurisdiction": "US" },
+    "europe-north1":  { "name": "Finland",       "lat": 60.57, "lon": 27.19,  "zone": "FI", "entsoe_eic": "10YFI-1--------U", "jurisdiction": "EEA" },
+    "us-west1":       { "name": "Oregon",        "lat": 45.60, "lon": -121.18, "zone": "US-NW-PACW", "eia_ba": "BPAT", "jurisdiction": "US" }
+  },
+  "azure": {
+    "eastus":         { "name": "Virginia",      "lat": 37.37, "lon": -79.82, "zone": "US-MIDA-PJM", "eia_ba": "PJM", "jurisdiction": "US" },
+    "northeurope":    { "name": "Ireland",       "lat": 53.35, "lon": -6.26,  "zone": "IE", "entsoe_eic": "10Y1001A1001A59C", "jurisdiction": "EEA" },
+    "swedencentral":  { "name": "Sweden",        "lat": 60.67, "lon": 17.14,  "zone": "SE", "entsoe_eic": "10YSE-1--------K", "jurisdiction": "EEA" }
+  }
+}