greenpick 0.1.0__py3-none-any.whl

greenpick/services/instance_service.py

@@ -0,0 +1,132 @@
+"""Greener instance-family suggestion.
+
+The honest carbon mechanism here is performance-per-watt: a newer-generation or ARM
+(Graviton-class) family does the SAME work on less energy, so for a fixed grid intensity it
+emits less CO2. We take the user's current general-purpose family, look up directional
+energy multipliers for the same-size families in that cloud, and rank the greener options —
+reporting the energy saving, the CO2 estimate (energy x the region's live grid intensity),
+and a relative R/Y/G rating.
+
+Deliberately NOT a pricing engine: we don't claim per-family prices we don't have. Cost is
+left to the region/cost tools; this tool's axis is energy -> carbon.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import (
+    Workload, Provider, CarbonReading,
+    GreenerComputeAdvice, FamilyOption,
+)
+from ..data.repository import CarbonRepository
+from ..data.static_data import power_model, instance_families
+from . import carbon_service
+
+
+SUPPORTED_PROVIDERS = ("aws", "gcp", "azure")
+
+
+def is_supported_provider(provider: str) -> bool:
+    return provider in SUPPORTED_PROVIDERS
+
+
+def _families_for(provider: str) -> list[dict]:
+    data = instance_families().get(provider, {})
+    return list(data.get("_general_purpose_generations", []))
+
+
+def _base_kwh_per_month(workload: Workload) -> float:
+    """Energy for the baseline (relative_energy = 1.00) family — same power model the
+    carbon estimate uses. Each family then scales this by its relative_energy."""
+    pm = power_model()
+    watts = (workload.vcpu * pm["watts_per_vcpu"] + workload.ram_gb * pm["watts_per_gb_ram"])
+    watts *= pm["pue_default"]
+    return watts / 1000.0 * workload.hours_per_month
+
+
+def _rate(options: list[FamilyOption]) -> None:
+    """Assign relative R/Y/G by energy terciles across the option set (greenest = green)."""
+    if not options:
+        return
+    ordered = sorted(options, key=lambda o: o.relative_energy)
+    n = len(ordered)
+    for i, opt in enumerate(ordered):
+        if n <= 2:
+            opt.rating = "green" if i == 0 else ("red" if i == n - 1 else "yellow")
+        else:
+            third = n / 3.0
+            opt.rating = "green" if i < third else ("red" if i >= 2 * third else "yellow")
+
+
+async def greener_instance_family(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    current_family: Optional[str] = None,
+    hours_per_month: float = 730,
+) -> GreenerComputeAdvice:
+    families = _families_for(provider)
+    if not families:
+        return GreenerComputeAdvice(
+            provider=provider, region=region, current_family=current_family,
+            rationale=f"No instance-family efficiency data for provider '{provider}'.",
+            limitations="Supported providers: aws, gcp, azure (general-purpose families only).",
+        )
+
+    reading: CarbonReading = await carbon_service.carbon_now(repo, provider, region)
+    wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=hours_per_month)
+    base_kwh = _base_kwh_per_month(wl)
+
+    # Resolve the current family (case-insensitive); if unknown/omitted, compare against the
+    # LEAST efficient family so savings are framed conservatively ("at least this much").
+    by_name = {f["family"].lower(): f for f in families}
+    current = by_name.get((current_family or "").lower())
+    current_rel = current["relative_energy"] if current else max(f["relative_energy"] for f in families)
+    current_resolved = current["family"] if current else None
+
+    options: list[FamilyOption] = []
+    for f in families:
+        rel = f["relative_energy"]
+        kwh = base_kwh * rel
+        kg = round(kwh * reading.g_co2_per_kwh / 1000.0, 2)
+        energy_saving = round((current_rel - rel) / current_rel * 100, 1) if current_rel > 0 else None
+        co2_saving = energy_saving  # same grid intensity, so CO2 scales with energy
+        options.append(FamilyOption(
+            family=f["family"], arch=f["arch"], cpu=f["cpu"],
+            relative_energy=rel,
+            energy_saving_vs_current_pct=energy_saving,
+            est_kg_co2_per_month=kg,
+            co2_saving_vs_current_pct=co2_saving,
+            note=f.get("notes", ""),
+        ))
+
+    options.sort(key=lambda o: o.relative_energy)   # greenest first
+    _rate(options)
+    greenest = options[0]
+
+    # Rationale: honest about the mechanism and the ARM caveat.
+    if current_resolved and greenest.family.lower() == current_resolved.lower():
+        rationale = (f"You're already on {current_resolved}, the greenest general-purpose family "
+                     f"available here. No change needed.")
+    else:
+        saving = greenest.energy_saving_vs_current_pct
+        arm_note = (" It's an ARM (Graviton-class) family, so this assumes your workload can run "
+                    "on ARM - a recompile/container rebuild may be needed."
+                    if greenest.arch == "arm" else "")
+        base = (f"vs {current_resolved}" if current_resolved
+                else "vs the least-efficient family here")
+        rationale = (f"{greenest.family} ({greenest.cpu}) does the same work on "
+                     f"~{saving:.0f}% less energy {base}, so ~{saving:.0f}% less CO2 at this "
+                     f"region's grid intensity.{arm_note}")
+
+    return GreenerComputeAdvice(
+        provider=provider, region=region, current_family=current_resolved,
+        grid_intensity_g_co2_per_kwh=reading.g_co2_per_kwh,
+        carbon_source=reading.source, carbon_quality=reading.quality,
+        options=options, recommended_family=greenest.family, rationale=rationale,
+        limitations=("Energy multipliers are DIRECTIONAL (perf-per-watt by generation/arch), "
+                     "not measured for your workload; general-purpose families only; embodied "
+                     "hardware carbon ignored. ARM options require ARM-compatible builds."),
+    )

greenpick/services/latency_service.py

@@ -0,0 +1,33 @@
+"""Geographic latency estimate: great-circle distance -> rough round-trip ms.
+
+A deliberate approximation (speed of light in fiber + routing overhead), good enough
+for "is this region far from my users?" Not a measured ping.
+"""
+from __future__ import annotations
+
+import math
+from ..models import GeoPoint, Provider
+from ..data.static_data import region_meta
+
+# Rough rule of thumb: ~fiber latency plus routing/queuing overhead.
+# ~0.0107 ms per km one-way for light in fiber; double for round trip; add a fixed overhead.
+_MS_PER_KM_RTT = 0.0107 * 2 * 1.4   # 1.4 fudge for non-great-circle routing
+_FIXED_OVERHEAD_MS = 10.0
+
+
+def _haversine_km(a: GeoPoint, b: GeoPoint) -> float:
+    r = 6371.0
+    dlat = math.radians(b.lat - a.lat)
+    dlon = math.radians(b.lon - a.lon)
+    h = (math.sin(dlat / 2) ** 2
+         + math.cos(math.radians(a.lat)) * math.cos(math.radians(b.lat)) * math.sin(dlon / 2) ** 2)
+    return 2 * r * math.asin(math.sqrt(h))
+
+
+def estimate_latency_ms(provider: Provider, region: str, user: GeoPoint) -> float | None:
+    meta = region_meta(provider, region)
+    if not meta:
+        return None
+    region_pt = GeoPoint(lat=meta["lat"], lon=meta["lon"])
+    km = _haversine_km(user, region_pt)
+    return round(_FIXED_OVERHEAD_MS + km * _MS_PER_KM_RTT, 1)

greenpick/services/locality_service.py

@@ -0,0 +1,160 @@
+"""Data-locality / egress warning.
+
+The trap this guards against: you move COMPUTE to a greener (often farther) region, but your
+DATA stays put — a database, object store, or another service. Every byte crossing that
+boundary is billed as egress and burns extra network energy. A naive "greener region" pick can
+be eaten alive by egress cost, and sometimes by the transfer carbon too.
+
+This tool is explicit by design: the caller tells us where compute runs, where the data lives,
+and how much crosses per month. We classify the separation, give a DIRECTIONAL egress-cost
+ballpark (the decision-relevant number), a deliberately-coarse transfer-carbon figure, and — if
+the caller supplies the carbon saving the move buys — a net verdict on whether the move still
+pays off.
+
+Honesty posture: egress COST leads (it's concrete, if approximate). Transfer CARBON is secondary
+and loudly flagged as order-of-magnitude, because the science on kWh/GB is unsettled.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import DataLocalityWarning, Provider, CarbonReading
+from ..data.repository import CarbonRepository
+from ..data.static_data import pricing, network_model
+from . import carbon_service, residency_service
+
+LIMITATIONS = (
+    "Egress cost is DIRECTIONAL: a LOW-HIGH range for the locality tier (same-region / cross-region / "
+    "cross-cloud) from dated list prices — it ignores free-tier allowances, committed-use/negotiated "
+    "discounts, exact region-pair rates, and NAT/load-balancer fees, so treat it as a ballpark, not a "
+    "quote. Transfer carbon uses a single kWh/GB coefficient whose published estimates vary by orders "
+    "of magnitude; it's order-of-magnitude only. You supply where data lives and how much crosses — "
+    "GreenPick can't infer your architecture."
+)
+
+
+def _classify(compute_provider: str, compute_region: str,
+              data_provider: str, data_region: str) -> tuple[str, str]:
+    """Return (locality, severity). Severity is the structural separation, before volume."""
+    if compute_provider == data_provider and compute_region == data_region:
+        return "same_region", "none"
+    if compute_provider == data_provider:
+        return "cross_region_same_cloud", "medium"
+    return "cross_cloud", "high"
+
+
+def _bump_severity_for_volume(severity: str, gb: float) -> str:
+    """A tiny cross-boundary trickle barely matters; a firehose matters a lot. Nudge severity
+    by monthly volume so the warning tracks real exposure, not just topology."""
+    if severity == "none":
+        return "none"
+    order = ["low", "medium", "high"]
+    base = {"low": 0, "medium": 1, "high": 2}[severity]
+    if gb >= 1000:
+        base = min(2, base + 1)
+    elif gb < 50:
+        base = max(0, base - 1)
+    return order[base]
+
+
+async def data_locality_check(
+    repo: CarbonRepository,
+    compute_provider: Provider,
+    compute_region: str,
+    data_provider: Provider,
+    data_region: str,
+    monthly_cross_boundary_gb: float,
+    carbon_saving_kg_co2_from_move: Optional[float] = None,
+) -> DataLocalityWarning:
+    compute_loc = f"{compute_provider}/{compute_region}"
+    data_loc = f"{data_provider}/{data_region}"
+    locality, severity = _classify(compute_provider, compute_region, data_provider, data_region)
+
+    if locality == "same_region":
+        return DataLocalityWarning(
+            compute_location=compute_loc, data_location=data_loc,
+            monthly_cross_boundary_gb=monthly_cross_boundary_gb,
+            locality=locality, severity="none",
+            egress_rate_usd_per_gb_low=0.0, egress_rate_usd_per_gb_high=0.0,
+            est_monthly_egress_usd_low=0.0, est_monthly_egress_usd_high=0.0,
+            est_monthly_transfer_kg_co2=0.0,
+            warning="Compute and data are co-located — no cross-boundary egress for this flow.",
+            recommendation="No locality penalty. Choose the region on carbon/latency/cost as usual.",
+            limitations=LIMITATIONS,
+        )
+
+    severity = _bump_severity_for_volume(severity, monthly_cross_boundary_gb)
+
+    # Egress is a TIER LADDER by where the bytes cross — not one flat rate. Price the tier we just
+    # classified, as a LOW-HIGH range (region-pair rates vary). For cross-cloud/internet the rate
+    # is provider-specific, so anchor the high end to the data provider's own internet rate.
+    tiers = pricing().get("_egress_tiers_usd_per_gb", {})
+    tier = tiers.get(locality, {})
+    rate_low = tier.get("low")
+    rate_high = tier.get("high")
+    if locality == "cross_cloud":
+        prov_internet = (pricing().get(data_provider) or {}).get("egress_usd_per_gb")
+        if prov_internet is not None and rate_high is not None:
+            rate_high = max(rate_high, prov_internet)   # don't under-quote this provider's internet rate
+    cost_low = round(monthly_cross_boundary_gb * rate_low, 2) if rate_low is not None else None
+    cost_high = round(monthly_cross_boundary_gb * rate_high, 2) if rate_high is not None else None
+
+    # Transfer carbon: energy to move the bytes x the grid intensity where that energy is drawn.
+    # Use the data region's grid as the representative intensity (coarse — energy is spread along
+    # the path, but this keeps it tied to a real, live number).
+    kwh_per_gb = network_model()["kwh_per_gb_transfer"]
+    reading: CarbonReading = await carbon_service.carbon_now(repo, data_provider, data_region)
+    transfer_kwh = monthly_cross_boundary_gb * kwh_per_gb
+    transfer_kg = round(transfer_kwh * reading.g_co2_per_kwh / 1000.0, 2)
+
+    # Net verdict only if the caller told us what the move saves.
+    verdict = None
+    if carbon_saving_kg_co2_from_move is not None:
+        net = carbon_saving_kg_co2_from_move - transfer_kg
+        if net > 0:
+            verdict = (f"Still a net win: the move saves ~{carbon_saving_kg_co2_from_move:.1f} kg "
+                       f"CO2/mo, the extra transfer costs ~{transfer_kg:.1f} kg, net "
+                       f"~{net:.1f} kg saved. (Egress COST may still argue against it.)")
+        else:
+            verdict = (f"Backfires on carbon: the move saves ~{carbon_saving_kg_co2_from_move:.1f} kg "
+                       f"CO2/mo but the extra transfer adds ~{transfer_kg:.1f} kg - net "
+                       f"~{abs(net):.1f} kg WORSE. Keep compute near the data, or move the data too.")
+
+    sep = ("across clouds" if locality == "cross_cloud" else "across regions in the same cloud")
+    if cost_low is not None and cost_high is not None:
+        cost_txt = (f"roughly ${cost_low:,.0f}-${cost_high:,.0f}/mo in egress "
+                    f"(~${rate_low:.2f}-${rate_high:.2f}/GB for this tier)")
+    else:
+        cost_txt = "an egress cost (rate unknown for this tier)"
+    warning = (f"Compute and data are separated {sep}: ~{monthly_cross_boundary_gb:,.0f} GB/mo would "
+               f"cross the boundary, costing {cost_txt}, plus ~{transfer_kg:.1f} kg CO2/mo of extra "
+               f"transfer. A greener-region move can be undone by this.")
+
+    if severity == "high":
+        rec = ("High exposure. Co-locate compute with the data, or move the data to the greener "
+               "region too. If you can't, confirm the carbon/cost saving beats this egress penalty "
+               "before moving compute alone.")
+    elif severity == "medium":
+        rec = ("Moderate exposure. Weigh the egress cost against the region's carbon/cost saving; "
+               "co-locating is usually cleaner and cheaper.")
+    else:
+        rec = ("Low exposure at this volume. The locality penalty is small — the region's "
+               "carbon/latency/cost tradeoff probably dominates.")
+
+    # Residency heads-up: compute processing data that lives in another jurisdiction is exactly the
+    # residency-sensitive case. Flag the data-region -> compute-region crossing (neutral, not legal).
+    residency_note = residency_service.residency_flag(
+        data_provider, data_region, compute_provider, compute_region,
+    )
+
+    return DataLocalityWarning(
+        compute_location=compute_loc, data_location=data_loc,
+        monthly_cross_boundary_gb=monthly_cross_boundary_gb,
+        locality=locality, severity=severity,
+        egress_rate_usd_per_gb_low=rate_low, egress_rate_usd_per_gb_high=rate_high,
+        est_monthly_egress_usd_low=cost_low, est_monthly_egress_usd_high=cost_high,
+        est_monthly_transfer_kg_co2=transfer_kg,
+        carbon_saving_kg_co2_from_move=carbon_saving_kg_co2_from_move,
+        net_carbon_verdict=verdict, residency_note=residency_note,
+        warning=warning, recommendation=rec, limitations=LIMITATIONS,
+    )

greenpick/services/metric_scaffold_service.py

@@ -0,0 +1,149 @@
+"""carbon_metric_scaffold: emit paste-in instrumentation so an app measures its OWN estimated carbon.
+
+GreenPick does not run or measure anything here. Software can't read its own wattage, so the app
+measures the cheap proxies it CAN observe (CPU utilisation, provisioned vCPU/RAM, uptime) and
+applies GreenPick's power model x the region's grid intensity to emit an ESTIMATED gCO2 metric.
+GreenPick's job is to supply (a) the code and (b) the coefficients that make the number meaningful.
+
+Hard guardrails baked into the output:
+- The metric is self-labelled `estimated_gco2*` with a comment stating it's directional, model-based,
+  NOT metered energy — because it will live in production dashboards and get quoted.
+- v1 is SELF-tracking (watch your own app over time/version/region/load), NOT cross-app ranking,
+  which would need a shared spec to be anything but noise.
+- Deliverable is a snippet + coefficients + methodology note, NOT a framework/SDK.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import CarbonMetricScaffold, Provider
+from ..data.repository import CarbonRepository
+from ..data.static_data import power_model
+from . import carbon_service
+
+SUPPORTED_LANGUAGES = ("python",)
+
+METHODOLOGY = (
+    "estimated_gco2_per_hour = ((vcpu * watts_per_vcpu * cpu_utilisation) + (ram_gb * watts_per_gb_ram)) "
+    "* pue / 1000 * grid_g_co2_per_kwh. Proxies (CPU util, vCPU, RAM, uptime) are what an app can "
+    "actually observe; the watts/PUE come from GreenPick's documented power model; grid intensity from "
+    "the region. It is an ESTIMATE, not a measurement of real energy drawn."
+)
+
+LIMITATIONS = (
+    "DIRECTIONAL estimate, not metered energy — software cannot read its true wattage, so this models "
+    "it from CPU utilisation and a published power model. Ignores GPU/accelerator, disk/network, "
+    "embodied carbon, and real hardware variance. If you hardcode a grid intensity it goes stale — "
+    "refresh it (or call region_carbon_now) periodically. Use for SELF-tracking over time, NOT to rank "
+    "against other apps (different boundaries/coefficients make that meaningless)."
+)
+
+
+def _python_snippet(vcpu_default: float, ram_default: float, pm: dict,
+                     grid: Optional[float], region: Optional[str]) -> str:
+    watts_vcpu = pm["watts_per_vcpu"]
+    watts_ram = pm["watts_per_gb_ram"]
+    pue = pm["pue_default"]
+    grid_literal = repr(grid) if grid is not None else "None"
+    region_comment = f"  # region: {region}" if region else ""
+    return f'''# --- GreenPick carbon metric (PASTE INTO YOUR APP) ---------------------------------
+# estimated_gco2 is a DIRECTIONAL ESTIMATE from CPU utilisation x a documented power model
+# x grid carbon intensity. It is NOT a measurement of real energy drawn. Use it to watch THIS
+# app's footprint over time/versions/regions - not to compare against other apps.
+# Model + coefficients: GreenPick (power.json). Methodology in the accompanying note.
+import time
+
+# --- Coefficients from GreenPick's power model (safe to keep; refresh grid intensity periodically)
+_WATTS_PER_VCPU = {watts_vcpu}
+_WATTS_PER_GB_RAM = {watts_ram}
+_PUE = {pue}
+_GRID_G_CO2_PER_KWH = {grid_literal}{region_comment}   # set/refresh for YOUR region; see region_carbon_now
+
+
+class CarbonEstimator:
+    """Estimates this process's grid carbon from observable proxies. Directional, not metered."""
+
+    def __init__(self, vcpu: float = {vcpu_default}, ram_gb: float = {ram_default},
+                 grid_g_co2_per_kwh: float | None = _GRID_G_CO2_PER_KWH):
+        self.vcpu = vcpu
+        self.ram_gb = ram_gb
+        self.grid = grid_g_co2_per_kwh
+        self._start = time.time()
+
+    def estimated_watts(self, cpu_utilisation: float) -> float:
+        """cpu_utilisation in 0..1 (e.g. psutil.cpu_percent()/100)."""
+        u = max(0.0, min(1.0, cpu_utilisation))
+        return (self.vcpu * _WATTS_PER_VCPU * u + self.ram_gb * _WATTS_PER_GB_RAM) * _PUE
+
+    def estimated_gco2_per_hour(self, cpu_utilisation: float) -> float | None:
+        if self.grid is None:
+            return None   # no grid intensity set -> can't estimate carbon honestly
+        return self.estimated_watts(cpu_utilisation) / 1000.0 * self.grid
+
+    def estimated_gco2_since_start(self, avg_cpu_utilisation: float) -> float | None:
+        rate = self.estimated_gco2_per_hour(avg_cpu_utilisation)
+        if rate is None:
+            return None
+        hours = (time.time() - self._start) / 3600.0
+        return rate * hours
+
+
+# Example: expose as a metric (Prometheus-style gauge, a log line, or a /metrics field).
+#   import psutil
+#   est = CarbonEstimator(vcpu=2, ram_gb=4)
+#   gco2_per_hour = est.estimated_gco2_per_hour(psutil.cpu_percent() / 100.0)
+#   # -> publish `estimated_gco2_per_hour` to your dashboard
+# ---------------------------------------------------------------------------------'''
+
+
+async def carbon_metric_scaffold(
+    repo: CarbonRepository,
+    language: str = "python",
+    region: Optional[str] = None,
+    provider: Optional[Provider] = None,
+    vcpu: float = 1,
+    ram_gb: float = 2,
+) -> CarbonMetricScaffold:
+    lang = language.strip().lower()
+    if lang not in SUPPORTED_LANGUAGES:
+        return CarbonMetricScaffold(
+            language=language,
+            how_to_use=f"Language '{language}' not supported yet. v1 emits Python; "
+                       f"the math (see methodology) ports easily to any language.",
+            methodology=METHODOLOGY, limitations=LIMITATIONS,
+        )
+
+    pm = power_model()
+    grid = None
+    source = quality = None
+    if region is not None:
+        prov = provider or _guess_provider(region)
+        if prov is not None:
+            reading = await carbon_service.carbon_now(repo, prov, region)  # type: ignore[arg-type]
+            grid = reading.g_co2_per_kwh
+            source, quality = reading.source, reading.quality
+
+    code = _python_snippet(vcpu, ram_gb, pm, grid, region)
+    how = ("Paste the snippet into your app. Instantiate CarbonEstimator with your instance's vcpu/"
+           "ram_gb, feed it CPU utilisation (e.g. psutil.cpu_percent()/100), and publish "
+           "estimated_gco2_per_hour to your dashboard/metrics. Set the grid intensity for your "
+           "region — if you gave GreenPick a region it's baked in; otherwise call region_carbon_now "
+           "and refresh it periodically so it doesn't go stale.")
+    return CarbonMetricScaffold(
+        language="python", region=region,
+        grid_intensity_g_co2_per_kwh=grid, carbon_source=source, carbon_quality=quality,
+        coefficients={
+            "watts_per_vcpu": pm["watts_per_vcpu"],
+            "watts_per_gb_ram": pm["watts_per_gb_ram"],
+            "pue_default": pm["pue_default"],
+        },
+        code=code, how_to_use=how, methodology=METHODOLOGY, limitations=LIMITATIONS,
+    )
+
+
+def _guess_provider(region: str) -> Optional[str]:
+    from ..data.static_data import iter_regions
+    for prov, reg, _meta in iter_regions():
+        if reg == region:
+            return prov
+    return None