greenpick 0.1.0__py3-none-any.whl

greenpick/services/serving_service.py

@@ -0,0 +1,202 @@
+"""Serving-pattern advice: should I serve my users from ONE region or SEVERAL?
+
+A design-time question for a user-facing platform: given where your users are (rough geographic
+shares are fine), is it better to serve everyone from a single region, or run multiple regions
+closer to each hub? GreenPick scores both on traffic-weighted latency and grid carbon, then
+composes the caveats that make multi-region non-free: cross-region DATA-SYNC egress (keeping shared
+state consistent across regions) and cross-JURISDICTION residency (a hub served from another
+jurisdiction).
+
+Firmly in GreenPick's lane: design-time, directional, stateless, reuses carbon + latency + egress +
+residency. It is NOT a runtime meter — it never measures a running app; it advises before you build.
+Input (user geography) is soft and often unknown precisely at design time, so rough % shares are
+accepted and everything is labelled directional.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import (
+    Workload, GeoPoint, Provider, ServingHub, ServingSinglePlan,
+    ServingPerHubChoice, ServingPatternAdvice,
+)
+from ..data.repository import CarbonRepository
+from ..data.static_data import iter_regions, region_meta
+from . import carbon_service, latency_service, residency_service
+
+# Representative coordinates for common named hubs, so callers can say "eu"/"us"/"apac" without
+# supplying lat/lon. Rough centroids of where users typically are, not of the regions.
+_HUB_COORDS = {
+    "us": (39.0, -98.0), "us-east": (38.9, -77.0), "us-west": (37.8, -122.3),
+    "eu": (50.1, 8.7), "eu-west": (53.3, -6.3), "eu-north": (59.3, 18.1),
+    "uk": (51.5, -0.1), "apac": (1.35, 103.8), "au": (-33.9, 151.2),
+    "india": (19.1, 72.9), "japan": (35.7, 139.7), "sa": (-23.5, -46.6),
+}
+
+LIMITATIONS = (
+    "Directional, design-time guidance — NOT a runtime measurement of your app. User geography is "
+    "whatever you supply (rough % shares are fine); results are only as good as that estimate. "
+    "Multi-region adds operational complexity, data-sync egress, and possible residency constraints "
+    "that GreenPick flags but does not fully cost. Carbon/latency are directional (see "
+    "explain_methodology_and_limits)."
+)
+
+
+def resolve_hub(h: ServingHub) -> GeoPoint:
+    """A hub may give explicit lat/lon, or rely on a known name -> representative coords."""
+    key = h.name.strip().lower()
+    if key in _HUB_COORDS and (h.lat == 0 and h.lon == 0):
+        lat, lon = _HUB_COORDS[key]
+        return GeoPoint(lat=lat, lon=lon)
+    return GeoPoint(lat=h.lat, lon=h.lon)
+
+
+async def _carbon(repo: CarbonRepository, provider: str, region: str):
+    return await carbon_service.carbon_now(repo, provider, region)  # type: ignore[arg-type]
+
+
+async def serving_pattern(
+    repo: CarbonRepository,
+    hubs: list[ServingHub],
+    workload: Workload,
+    providers: Optional[list[Provider]] = None,
+) -> ServingPatternAdvice:
+    if not hubs:
+        return ServingPatternAdvice(hubs=[], rationale="No user hubs supplied — give at least one "
+                                    "(name + rough share) so I can advise on where to serve from.",
+                                    limitations=LIMITATIONS)
+
+    # Normalise shares so they sum to 1 (callers often give rough buckets like 40/40/20).
+    total_share = sum(h.share for h in hubs) or 1.0
+    weights = [h.share / total_share for h in hubs]
+    points = [resolve_hub(h) for h in hubs]
+
+    wanted = set(providers) if providers else {"aws", "gcp", "azure"}
+    catalog = [(p, r) for p, r, _m in iter_regions() if p in wanted]
+
+    # Carbon per candidate region (one fetch each). Latency is pure geometry, no fetch.
+    carbon_cache: dict[tuple[str, str], object] = {}
+    import asyncio
+    readings = await asyncio.gather(*(_carbon(repo, p, r) for p, r in catalog))
+    for (p, r), reading in zip(catalog, readings):
+        carbon_cache[(p, r)] = reading
+
+    def latency(p: str, r: str, pt: GeoPoint) -> Optional[float]:
+        return latency_service.estimate_latency_ms(p, r, pt)  # type: ignore[arg-type]
+
+    # --- Single-region-for-all: pick the region minimising traffic-weighted latency ---
+    best_single = None
+    for (p, r) in catalog:
+        lats = [latency(p, r, pt) for pt in points]
+        if any(l is None for l in lats):
+            continue
+        wlat = sum(w * l for w, l in zip(weights, lats))  # type: ignore[arg-type]
+        if best_single is None or wlat < best_single[0]:
+            best_single = (wlat, p, r)
+
+    single_plan = None
+    if best_single is not None:
+        wlat, p, r = best_single
+        reading = carbon_cache[(p, r)]
+        single_plan = ServingSinglePlan(
+            provider=p, region=r, weighted_latency_ms=round(wlat, 1),  # type: ignore[arg-type]
+            carbon_g_co2_per_kwh=reading.g_co2_per_kwh, carbon_source=reading.source,  # type: ignore[attr-defined]
+            carbon_quality=reading.quality,  # type: ignore[attr-defined]
+        )
+
+    # --- Multi-region: for each hub, the region that best balances latency + carbon near it ---
+    per_hub: list[ServingPerHubChoice] = []
+    for h, pt, w in zip(hubs, points, weights):
+        scored = []
+        for (p, r) in catalog:
+            l = latency(p, r, pt)
+            if l is None:
+                continue
+            reading = carbon_cache[(p, r)]
+            # Rank each hub's region by latency first (serving locality is the point of going
+            # multi-region), using carbon as the tiebreaker among nearby options (+/-30ms).
+            scored.append((l, reading.g_co2_per_kwh, p, r))  # type: ignore[attr-defined]
+        if not scored:
+            continue
+        scored.sort(key=lambda t: t[0])
+        near_min = scored[0][0] + 30.0
+        nearby = [s for s in scored if s[0] <= near_min]
+        nearby.sort(key=lambda t: t[1])   # greenest among the near-latency options
+        l, g, p, r = nearby[0]
+        per_hub.append(ServingPerHubChoice(
+            hub=h.name, provider=p, region=r, latency_ms=round(l, 1),
+            carbon_g_co2_per_kwh=g,
+        ))
+
+    multi_wlat = None
+    multi_blended = None
+    if len(per_hub) == len(hubs):
+        multi_wlat = round(sum(w * c.latency_ms for w, c in zip(weights, per_hub)), 1)
+        multi_blended = round(sum(w * c.carbon_g_co2_per_kwh for w, c in zip(weights, per_hub)), 1)
+
+    # --- Caveats that make multi-region non-free ---
+    data_sync_note = None
+    residency_note = None
+    distinct_regions = {(c.provider, c.region) for c in per_hub}
+    if len(distinct_regions) > 1:
+        data_sync_note = (
+            "Multi-region means shared state (DBs, sessions, caches) must sync ACROSS regions — "
+            "that cross-region traffic is billed egress and adds its own transfer carbon. Model it "
+            "with data_locality_egress_check before committing; it can erase the latency/carbon win "
+            "for write-heavy or chatty-shared-state apps.")
+        # Residency: does any hub get served from a different jurisdiction than the hub sits in?
+        for h, pt, c in zip(hubs, points, per_hub):
+            hub_jur = _nearest_jurisdiction(pt)
+            serve_jur = residency_service.jurisdiction_of(c.provider, c.region)
+            if hub_jur and serve_jur and hub_jur != serve_jur:
+                residency_note = (
+                    f"RESIDENCY: at least one hub ('{h.name}') would be served from a region in a "
+                    f"different jurisdiction ({serve_jur}) than the users appear to sit in ({hub_jur}). "
+                    f"If user data is regulated, this may matter. " + residency_service.DISCLAIMER)
+                break
+
+    # --- Decide + explain ---
+    recommended, rationale = _decide(single_plan, per_hub, multi_wlat, multi_blended,
+                                     len(distinct_regions))
+
+    return ServingPatternAdvice(
+        hubs=hubs, single_region=single_plan, multi_region=per_hub,
+        multi_region_weighted_latency_ms=multi_wlat,
+        multi_region_blended_carbon_g_co2_per_kwh=multi_blended,
+        recommended_pattern=recommended, data_sync_egress_note=data_sync_note,
+        residency_note=residency_note, rationale=rationale, limitations=LIMITATIONS,
+    )
+
+
+def _nearest_jurisdiction(pt: GeoPoint) -> Optional[str]:
+    """Infer a hub's jurisdiction from the nearest catalogued region's tag (directional)."""
+    best = None
+    for p, r, meta in iter_regions():
+        if "lat" not in meta or "jurisdiction" not in meta:
+            continue
+        d = (meta["lat"] - pt.lat) ** 2 + (meta["lon"] - pt.lon) ** 2
+        if best is None or d < best[0]:
+            best = (d, meta["jurisdiction"])
+    return best[1] if best else None
+
+
+def _decide(single, per_hub, multi_wlat, multi_blended, n_distinct):
+    """Recommend single vs multi. Single wins unless multi-region materially cuts weighted latency
+    (users are genuinely spread), since multi-region's complexity/egress is a real cost."""
+    if single is None or not per_hub or multi_wlat is None:
+        if single is not None:
+            return "single_region", (f"Serve all users from {single.provider}/{single.region} "
+                                     f"(~{single.weighted_latency_ms:.0f}ms weighted latency).")
+        return "single_region", "Not enough data to compare serving patterns."
+
+    lat_saving = single.weighted_latency_ms - multi_wlat
+    if n_distinct > 1 and lat_saving >= 40:
+        return "multi_region", (
+            f"Your users are spread enough that multi-region helps: serving each hub locally cuts "
+            f"weighted latency from ~{single.weighted_latency_ms:.0f}ms (single region) to "
+            f"~{multi_wlat:.0f}ms, and blends to ~{multi_blended:.0f} gCO2/kWh. Weigh that against "
+            f"the data-sync egress and complexity below before committing.")
+    return "single_region", (
+        f"A single region ({single.provider}/{single.region}, ~{single.weighted_latency_ms:.0f}ms "
+        f"weighted) is the better call: multi-region would only save ~{max(0, lat_saving):.0f}ms, "
+        f"which rarely justifies the added data-sync egress and operational complexity.")

greenpick/services/training_service.py

@@ -0,0 +1,209 @@
+"""GPU training carbon: how much CO2 a training run emits, and the greener WHERE + WHEN.
+
+Training is the workload where GreenPick's two best levers compound: a run is both PORTABLE
+(pick the region) and DEFERRABLE (pick the hours). Unlike the always-on web service, a run is a
+FIXED batch of work (~N GPU-hours, once), so we can place it in space and time.
+
+Energy comes from the directional GPU power table (TDP x utilization + host overhead, x PUE);
+carbon = energy x the region's LIVE grid intensity. Placement ranks regions greener-first; timing
+reuses the carbon-aware scheduling service for the chosen (or greenest) region.
+
+Honesty posture: energy is directional (TDP is peak, not a measurement of your run); region GPU
+availability is NOT modelled — we flag it as something to verify, rather than maintain a matrix
+that rots. Spot/on-demand, checkpointing, and multi-node networking are out of scope (orchestration,
+not placement/timing).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import (
+    Provider, TrainingCarbonAdvice, TrainingRegionOption, HourlyCarbon,
+)
+from ..data.repository import CarbonRepository
+from ..data.static_data import gpu_power, resolve_gpu, power_model, iter_regions
+from . import carbon_service, scheduling_service, residency_service
+
+
+def run_energy_kwh(gpu_key: str, gpu_count: int, gpu_hours: float,
+                   utilization: float) -> float:
+    """Directional energy for a run. gpu_hours is TOTAL accelerator-hours across all GPUs
+    (e.g. 2 GPUs for 20h = 40 GPU-hours). Energy is independent of how it's split, since
+    both the GPU draw and host overhead are per-accelerator."""
+    gp = gpu_power()
+    _key, spec = resolve_gpu(gpu_key)  # caller guarantees resolvable
+    tdp = spec["tdp_watts"]
+    host = gp["host_overhead_watts_per_gpu"]
+    pue = power_model()["pue_default"]
+    watts_per_gpu = tdp * utilization + host
+    # gpu_hours is total accelerator-hours, so multiply watts-per-gpu by total gpu-hours directly.
+    return watts_per_gpu / 1000.0 * gpu_hours * pue
+
+
+def _rate(options: list[TrainingRegionOption]) -> None:
+    """Relative R/Y/G by carbon terciles across the option set (greenest = green)."""
+    if not options:
+        return
+    ordered = sorted(options, key=lambda o: o.est_kg_co2)
+    n = len(ordered)
+    for i, opt in enumerate(ordered):
+        frac = i / n
+        opt.rating = "green" if frac < 1/3 else "yellow" if frac < 2/3 else "red"
+
+
+LIMITATIONS = (
+    "Energy is DIRECTIONAL: published GPU TDP (peak, not your run's measured draw) x a utilization "
+    "assumption + host overhead x PUE. Carbon = energy x the region's grid intensity. GPU AVAILABILITY "
+    "per region is NOT checked — verify the card you need is offered there. Ignores spot/on-demand, "
+    "checkpointing, multi-node networking, and embodied hardware carbon. Training datasets are often "
+    "large and may live in another region: shipping them to the greenest region can incur significant "
+    "EGRESS cost and transfer carbon — run data_locality_egress_check before moving the job."
+)
+
+
+async def estimate_training_carbon(
+    repo: CarbonRepository,
+    gpu: str,
+    gpu_count: int,
+    gpu_hours: float,
+    region: Optional[str] = None,
+    provider: Optional[Provider] = None,
+    utilization: Optional[float] = None,
+    top_n_regions: int = 5,
+) -> TrainingCarbonAdvice:
+    gp = gpu_power()
+    resolved = resolve_gpu(gpu)
+    util = utilization if utilization is not None else gp["default_utilization"]
+
+    if resolved is None:
+        known = ", ".join(gp["gpus"].keys())
+        return TrainingCarbonAdvice(
+            gpu=gpu, gpu_name=gpu, gpu_count=gpu_count, gpu_hours=gpu_hours,
+            utilization=util, est_energy_kwh=0.0,
+            rationale=f"Unknown GPU '{gpu}'. Known: {known}.",
+            limitations=LIMITATIONS,
+        )
+
+    gpu_key, spec = resolved
+    energy = round(run_energy_kwh(gpu_key, gpu_count, gpu_hours, util), 2)
+
+    base = TrainingCarbonAdvice(
+        gpu=gpu_key, gpu_name=spec["name"], gpu_count=gpu_count, gpu_hours=gpu_hours,
+        utilization=util, est_energy_kwh=energy, limitations=LIMITATIONS,
+    )
+
+    # --- Placement: a specific region, or rank the catalog greener-first ---
+    if region is not None:
+        prov = provider or _guess_provider(region)
+        if prov is None:
+            base.rationale = (f"Region '{region}' not found. Pass provider= explicitly, or omit "
+                              f"region to rank all regions.")
+            return base
+        reading = await carbon_service.carbon_now(repo, prov, region)
+        kg = round(energy * reading.g_co2_per_kwh / 1000.0, 2)
+        base.region = region
+        base.recommended_region = f"{prov}/{region}"
+        base.options = [TrainingRegionOption(
+            provider=prov, region=region, grid_intensity_g_co2_per_kwh=reading.g_co2_per_kwh,
+            carbon_source=reading.source, carbon_quality=reading.quality, est_kg_co2=kg,
+            rating="green",
+        )]
+        chosen_prov, chosen_region = prov, region
+        place_txt = (f"This run is ~{energy:.0f} kWh. In {prov}/{region} that's ~{kg:.1f} kg CO2 "
+                     f"at {reading.g_co2_per_kwh:.0f} gCO2/kWh ({reading.source}, {reading.quality}).")
+    else:
+        wanted = {provider} if provider else {"aws", "gcp", "azure"}
+        targets = [(prov, reg) for prov, reg, _meta in iter_regions() if prov in wanted]
+        # Fetch all regions' carbon CONCURRENTLY — live sources (esp. ENTSO-E with retries) are
+        # slow serially, and ranking needs every region before it can sort.
+        import asyncio
+        readings = await asyncio.gather(
+            *(carbon_service.carbon_now(repo, prov, reg) for prov, reg in targets)  # type: ignore[arg-type]
+        )
+        options: list[TrainingRegionOption] = []
+        for (prov, reg), reading in zip(targets, readings):
+            kg = round(energy * reading.g_co2_per_kwh / 1000.0, 2)
+            options.append(TrainingRegionOption(
+                provider=prov, region=reg,  # type: ignore[arg-type]
+                grid_intensity_g_co2_per_kwh=reading.g_co2_per_kwh,
+                carbon_source=reading.source, carbon_quality=reading.quality, est_kg_co2=kg,
+            ))
+        if not options:
+            base.rationale = "No known regions matched the request."
+            return base
+        options.sort(key=lambda o: o.est_kg_co2)   # greenest first
+        greenest = options[0]
+        dirtiest = options[-1]
+        # vs_baseline computed against the FULL set's dirtiest (the real worst case), so the
+        # headline "X% less than the dirtiest" reflects every region, not just the shown slice.
+        for o in options:
+            if dirtiest.est_kg_co2 > 0:
+                o.vs_baseline_pct = round((o.est_kg_co2 - dirtiest.est_kg_co2) / dirtiest.est_kg_co2 * 100, 1)
+        shown = options[:max(1, top_n_regions)]
+        _rate(shown)   # R/Y/G relative to what's actually displayed
+        base.options = shown
+        base.recommended_region = f"{greenest.provider}/{greenest.region}"
+        chosen_prov, chosen_region = greenest.provider, greenest.region
+        saved_pct = abs(greenest.vs_baseline_pct) if greenest.vs_baseline_pct else 0.0
+        place_txt = (f"This run is ~{energy:.0f} kWh. Greenest option is {greenest.provider}/"
+                     f"{greenest.region} at ~{greenest.est_kg_co2:.1f} kg CO2 - ~{saved_pct:.0f}% "
+                     f"less than the dirtiest option ({dirtiest.provider}/{dirtiest.region}, "
+                     f"~{dirtiest.est_kg_co2:.1f} kg).")
+
+    # --- Timing: reuse carbon-aware scheduling for the chosen/greenest region ---
+    # A run's wall-clock duration ~= total GPU-hours / GPUs running in parallel. If that's >= 2h,
+    # ask for the cleanest CONTIGUOUS window of that length (you start one job once), not scattered
+    # hours. Cap at 24 so it stays within the history window.
+    wall_clock_h = int(round(gpu_hours / max(1, gpu_count)))
+    window = wall_clock_h if 2 <= wall_clock_h <= 24 else None
+    advice = await scheduling_service.cleanest_hours(
+        repo, chosen_prov, chosen_region, top_n=3, window_hours=window,
+    )
+    base.cleanest_hours = advice.cleanest
+    base.cleanest_window = advice.window
+    base.timing_reduction_pct = advice.potential_reduction_pct
+    base.timing_source = advice.source
+    base.timing_quality = advice.quality
+
+    if advice.window and advice.window_reduction_pct and advice.window_reduction_pct >= 10:
+        w = advice.window
+        time_txt = (f" It runs ~{wall_clock_h}h wall-clock; the cleanest {w.window_hours}h window to "
+                    f"start is {w.start_period} (avg ~{w.avg_g_co2_per_kwh:.0f} gCO2/kWh), "
+                    f"~{advice.window_reduction_pct:.0f}% cleaner than the worst same-length window - "
+                    f"training is deferrable, so this stacks on the region choice.")
+    elif advice.potential_reduction_pct and advice.potential_reduction_pct >= 10 and advice.cleanest:
+        best = advice.cleanest[0].period
+        time_txt = (f" Timing it to the cleanest hours in that region (around {best}) cuts a further "
+                    f"~{advice.potential_reduction_pct:.0f}% vs the dirtiest hour - training is "
+                    f"deferrable, so this stacks on the region choice.")
+    else:
+        time_txt = (" That region's grid is fairly flat over the window, so when you run matters "
+                    "little there — the region choice is the lever.")
+
+    base.rationale = place_txt + time_txt
+
+    # Residency context: training usually means shipping a dataset INTO the recommended region.
+    # We don't know where the data lives, so we state the recommended region's jurisdiction as a
+    # neutral heads-up (not a verdict) — most pointed when it's inside the EEA.
+    jur = residency_service.jurisdiction_of(chosen_prov, chosen_region)
+    if jur:
+        where = residency_service._LABEL.get(jur, jur)
+        if jur == "EEA":
+            base.residency_note = (
+                f"RESIDENCY: the recommended region ({chosen_prov}/{chosen_region}) is in {where}. "
+                f"Shipping a training dataset in or out of the EEA can trigger GDPR transfer rules "
+                f"if it contains personal data. {residency_service.DISCLAIMER}")
+        else:
+            base.residency_note = (
+                f"RESIDENCY: the recommended region ({chosen_prov}/{chosen_region}) is in {where}. "
+                f"If your training data lives in another jurisdiction, moving it here may trigger "
+                f"residency rules. {residency_service.DISCLAIMER}")
+    return base
+
+
+def _guess_provider(region: str) -> Optional[str]:
+    """Find which provider a region code belongs to (region codes are unique across our catalog)."""
+    for prov, reg, _meta in iter_regions():
+        if reg == region:
+            return prov
+    return None