greenpick 0.1.0__py3-none-any.whl

greenpick/data/repository.py

@@ -0,0 +1,27 @@
+"""Carbon data repository: the one interface every source implements.
+
+Services depend ONLY on this Protocol, so sources (mock / Electricity Maps / ENTSO-E /
+EIA) are swappable via config without touching business logic.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+from ..models import CarbonReading, Provider
+
+
+from ..models import HourlyCarbon
+
+
+@runtime_checkable
+class CarbonRepository(Protocol):
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        """Current grid carbon intensity for one region. Implementations should
+        degrade gracefully (cached -> annual average) and set CarbonReading.quality
+        to reflect what was actually returned."""
+        ...
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        """Recent hourly carbon intensity for a region (for scheduling deferrable work).
+        Return [] if the source doesn't support history for this region — callers must
+        handle the empty case. Default implementations may return []."""
+        ...

greenpick/data/static_data.py

@@ -0,0 +1,105 @@
+"""Loaders for the bundled static JSON (regions, pricing, power model).
+
+Cached at import; these change rarely and are versioned in-repo.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+_DATA_DIR = Path(__file__).parent
+
+
+@lru_cache(maxsize=1)
+def regions() -> dict:
+    return json.loads((_DATA_DIR / "regions.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def pricing() -> dict:
+    return json.loads((_DATA_DIR / "pricing.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def power_model() -> dict:
+    return json.loads((_DATA_DIR / "power.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def emission_factors() -> dict:
+    """Per-fuel gCO2/kWh factors (keyed by EIA fueltype code)."""
+    return json.loads((_DATA_DIR / "emission_factors.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def instance_families() -> dict:
+    """Directional perf-per-watt multipliers for general-purpose instance families."""
+    return json.loads((_DATA_DIR / "instance_families.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def network_model() -> dict:
+    """Directional data-transfer energy intensity (kWh/GB) for the egress carbon signal."""
+    return json.loads((_DATA_DIR / "network.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def inference_energy() -> dict:
+    """Directional LLM inference energy (Wh/1k output tokens) by model size class."""
+    return json.loads((_DATA_DIR / "inference_energy.json").read_text(encoding="utf-8"))
+
+
+def resolve_size_class(name: str) -> tuple[str, dict] | None:
+    """Resolve a size-class name or param-count alias (e.g. 'small', '8b', '70B', 'moe',
+    'mixtral') -> (canonical_class, spec), case-insensitive. None if unknown."""
+    if not name:
+        return None
+    data = inference_energy()
+    key = name.strip().lower()
+    classes = data.get("size_classes", {})
+    if key in classes:
+        return key, classes[key]
+    alias = data.get("_aliases", {}).get(key)
+    if alias and alias in classes:
+        return alias, classes[alias]
+    return None
+
+
+@lru_cache(maxsize=1)
+def gpu_power() -> dict:
+    """Directional GPU/accelerator power model (TDP + utilization + host overhead) for training."""
+    return json.loads((_DATA_DIR / "gpu_power.json").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _gpu_index() -> dict:
+    """Lowercased lookup from GPU key OR alias -> (canonical_key, spec dict)."""
+    idx: dict[str, tuple[str, dict]] = {}
+    for key, spec in gpu_power().get("gpus", {}).items():
+        idx[key.lower()] = (key, spec)
+        for alias in spec.get("aliases", []):
+            idx[alias.lower()] = (key, spec)
+    return idx
+
+
+def resolve_gpu(name: str) -> tuple[str, dict] | None:
+    """Resolve a user-supplied GPU name (case-insensitive, alias-aware) -> (canonical_key, spec),
+    or None if unknown. e.g. 'A100', 'a100-sxm', 'tesla-t4' all resolve."""
+    if not name:
+        return None
+    return _gpu_index().get(name.strip().lower())
+
+
+def iter_regions():
+    """Yield (provider, region_code, meta) for every known region."""
+    data = regions()
+    for provider, regs in data.items():
+        if provider.startswith("_"):
+            continue
+        for code, meta in regs.items():
+            yield provider, code, meta
+
+
+def region_meta(provider: str, region: str) -> dict | None:
+    return regions().get(provider, {}).get(region)

greenpick/models.py

@@ -0,0 +1,342 @@
+"""Domain models shared across data sources, services, and tools.
+
+Pydantic for validation at the MCP boundary (inputs arrive as loosely-typed JSON).
+"""
+from __future__ import annotations
+
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+
+
+Provider = Literal["aws", "gcp", "azure"]
+DataQuality = Literal[
+    "live", "live_estimated", "cached", "annual_average", "mock", "forecast", "historical",
+]
+
+
+class Workload(BaseModel):
+    """A long-running web/API service — the only workload shape in v1."""
+    vcpu: float = Field(gt=0, description="vCPUs provisioned")
+    ram_gb: float = Field(gt=0, description="RAM in GB")
+    est_monthly_egress_gb: float = Field(ge=0, default=0, description="Outbound GB/month")
+    hours_per_month: float = Field(gt=0, default=730, description="Running hours/month (730 = always-on)")
+
+
+class GeoPoint(BaseModel):
+    lat: float
+    lon: float
+
+
+class CarbonReading(BaseModel):
+    """Grid carbon intensity for a region at a point in time."""
+    region: str
+    provider: Provider
+    g_co2_per_kwh: float = Field(ge=0)
+    source: str                      # e.g. "electricitymaps", "eia", "mock"
+    timestamp: str                   # ISO 8601
+    quality: DataQuality             # how trustworthy / fresh this reading is
+
+
+class HourlyCarbon(BaseModel):
+    """One hour's grid carbon intensity, for scheduling deferrable work."""
+    period: str                       # the hour label from the source (e.g. "2026-10-12T03")
+    g_co2_per_kwh: float
+
+
+class ForecastHour(BaseModel):
+    """One upcoming hour's forecast renewable output (the relative-cleanliness signal)."""
+    period: str                        # ISO hour the forecast applies to (UTC)
+    renewable_mw: float                # forecast wind+solar MW for that hour
+    renewable_share: Optional[float] = None   # renewables / load, 0..1, when load is available
+
+
+class ForecastAdvice(BaseModel):
+    """Forward-looking cleanest hours from the day-ahead renewable forecast.
+
+    RELATIVE, not absolute: ranks upcoming hours by forecast wind+solar output (more renewables =
+    cleaner). Not a gCO2/kWh forecast — the free data doesn't support that reliably across zones."""
+    region: str
+    provider: Provider
+    source: str                        # "entsoe_forecast" | "historical_fallback" | "mock"
+    quality: DataQuality               # "forecast" | "historical" | "mock"
+    hours_ahead: int
+    cleanest_upcoming: list[ForecastHour] = []   # greenest upcoming hours, cleanest first
+    peak_renewable_period: Optional[str] = None
+    low_renewable_period: Optional[str] = None
+    note: str = ""
+    limitations: str = ""
+
+
+class CleanestWindow(BaseModel):
+    """The lowest-average contiguous run of N hours — for timing a job of known duration."""
+    window_hours: int
+    start_period: str                 # the hour the window begins (start your job here)
+    end_period: str                   # the last hour in the window
+    avg_g_co2_per_kwh: float           # mean intensity across the window
+    hours: list[HourlyCarbon] = []     # the per-hour breakdown of the chosen window
+
+
+class HourOfDayStat(BaseModel):
+    """Average carbon for a given hour-of-day across the days in the recent window."""
+    hour_of_day: int                   # 0..23 (UTC, matching the source timestamps)
+    avg_g_co2_per_kwh: float
+    days_observed: int                 # how many days contributed to this average
+
+
+class DailyPatternAdvice(BaseModel):
+    """The recurring time-of-day pattern for a region, for timing a RECURRING job (e.g. nightly).
+
+    This is a daily pattern over the N days we have, NOT a 7-day weekly pattern — the free data
+    windows are only a few days, so we honestly report 'cleanest time of day', not 'day of week'."""
+    region: str
+    provider: Provider
+    source: str
+    quality: DataQuality
+    days_analyzed: int
+    hours_analyzed: int
+    by_hour_of_day: list[HourOfDayStat] = []     # all 0..23 that had data, cleanest first
+    cleanest_hour_of_day: Optional[int] = None
+    dirtiest_hour_of_day: Optional[int] = None
+    potential_reduction_pct: Optional[float] = None
+    note: str = ""
+    limitations: str = ""
+
+
+class SchedulingAdvice(BaseModel):
+    """Cleanest hours to run a deferrable job in a region, from recent history."""
+    region: str
+    provider: Provider
+    source: str
+    quality: DataQuality
+    hours_analyzed: int
+    cleanest: list[HourlyCarbon]      # lowest-carbon hours, cleanest first
+    dirtiest_g_co2_per_kwh: Optional[float] = None
+    cleanest_g_co2_per_kwh: Optional[float] = None
+    potential_reduction_pct: Optional[float] = None   # cleanest vs dirtiest
+    # Window mode (set when window_hours >= 2): the best contiguous run to start a job of that length.
+    window: Optional[CleanestWindow] = None
+    window_reduction_pct: Optional[float] = None       # best vs worst same-length window
+    note: str = ""
+
+
+class FamilyOption(BaseModel):
+    """One instance family as a greener-compute candidate, same size & region."""
+    family: str
+    arch: str                                   # "x86" | "arm"
+    cpu: str
+    relative_energy: float                      # energy for the same work; lower = greener
+    energy_saving_vs_current_pct: Optional[float] = None   # vs. the user's current family
+    est_kg_co2_per_month: Optional[float] = None
+    co2_saving_vs_current_pct: Optional[float] = None
+    rating: Optional[str] = None                # "green" | "yellow" | "red", relative to the options
+    note: str = ""
+
+
+class GreenerComputeAdvice(BaseModel):
+    """Greener same-size instance families in the same region, ranked by energy efficiency."""
+    provider: Provider
+    region: str
+    current_family: Optional[str] = None
+    grid_intensity_g_co2_per_kwh: Optional[float] = None
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
+    options: list[FamilyOption] = []            # greenest first
+    recommended_family: Optional[str] = None
+    rationale: str = ""
+    limitations: str = ""
+
+
+class TrainingRegionOption(BaseModel):
+    """One region as a place to run a training job, with its carbon for this run."""
+    provider: Provider
+    region: str
+    grid_intensity_g_co2_per_kwh: float
+    carbon_source: str
+    carbon_quality: str
+    est_kg_co2: float                            # for the whole run, in this region
+    vs_baseline_pct: Optional[float] = None      # negative = cleaner than baseline/current
+    rating: Optional[str] = None                 # "green" | "yellow" | "red", relative
+
+
+class TrainingCarbonAdvice(BaseModel):
+    """Carbon of a GPU training run, with greener WHERE (region) and WHEN (hours) guidance."""
+    gpu: str                                      # canonical GPU key
+    gpu_name: str
+    gpu_count: int
+    gpu_hours: float                              # total accelerator-hours for the run
+    utilization: float
+    est_energy_kwh: float
+    # Placement:
+    region: Optional[str] = None                  # the resolved/queried region (if one was given)
+    options: list[TrainingRegionOption] = []      # ranked greener-first (when ranking regions)
+    recommended_region: Optional[str] = None
+    residency_note: Optional[str] = None          # heads-up if the pick is in a different jurisdiction
+    # Timing (reuses cleanest-hours scheduling for the chosen/greenest region):
+    cleanest_hours: list[HourlyCarbon] = []
+    cleanest_window: Optional["CleanestWindow"] = None   # set when the run is >= 2h wall-clock
+    timing_reduction_pct: Optional[float] = None
+    timing_source: Optional[str] = None
+    timing_quality: Optional[str] = None
+    rationale: str = ""
+    limitations: str = ""
+
+
+class InferenceCarbonAdvice(BaseModel):
+    """Directional energy + CO2 for an LLM INFERENCE workload, by model size class.
+
+    Estimate, not a measurement. Keyed on size class (not a named product); output tokens drive
+    the cost; reported as a LOW-HIGH band because serving choices move the same model many-fold."""
+    size_class: str                               # canonical class resolved
+    size_class_label: str
+    monthly_requests: float
+    avg_output_tokens: int
+    monthly_output_tokens: float                  # requests x avg_output_tokens
+    wh_per_1k_output_low: float
+    wh_per_1k_output_high: float
+    monthly_kwh_low: float
+    monthly_kwh_high: float
+    region: Optional[str] = None
+    grid_intensity_g_co2_per_kwh: Optional[float] = None
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
+    monthly_kg_co2_low: Optional[float] = None
+    monthly_kg_co2_high: Optional[float] = None
+    rationale: str = ""
+    limitations: str = ""
+
+
+class RightsizingAdvice(BaseModel):
+    """FinOps right-sizing with a carbon twin: if you're over-provisioned, a smaller size cuts
+    BOTH cost and carbon. The clearest efficiency dual-benefit. Directional."""
+    provider: Provider
+    region: str
+    provisioned_vcpu: float
+    provisioned_ram_gb: float
+    observed_cpu_utilization: float               # 0..1, peak/typical the user reports
+    observed_ram_utilization: Optional[float] = None
+    recommended_vcpu: float = 0
+    recommended_ram_gb: float = 0
+    is_oversized: bool = False
+    cost_now_usd_per_month: Optional[float] = None
+    cost_rightsized_usd_per_month: Optional[float] = None
+    monthly_usd_saving: Optional[float] = None
+    carbon_now_kg_per_month: Optional[float] = None
+    carbon_rightsized_kg_per_month: Optional[float] = None
+    monthly_kg_co2_saving: Optional[float] = None
+    saving_pct: Optional[float] = None
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
+    rationale: str = ""
+    limitations: str = ""
+
+
+class CarbonMetricScaffold(BaseModel):
+    """Paste-in instrumentation so an app can emit its OWN estimated carbon metric.
+
+    GreenPick supplies the code + the coefficients that make it meaningful; the app measures the
+    observable proxies (CPU util, vCPU/RAM, uptime) and multiplies by GreenPick's power model and
+    the region's grid intensity. The emitted number is a DIRECTIONAL estimate, not metered energy."""
+    language: str
+    region: Optional[str] = None
+    grid_intensity_g_co2_per_kwh: Optional[float] = None   # baked in if a region was given
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
+    coefficients: dict = {}                                 # the power-model constants used
+    code: str = ""                                          # the snippet to paste in
+    how_to_use: str = ""
+    methodology: str = ""
+    limitations: str = ""
+
+
+class ServingHub(BaseModel):
+    """One cluster of users, as a share of total traffic, located at a point."""
+    name: str                                   # e.g. "eu", "us", "apac", or a city
+    lat: float
+    lon: float
+    share: float = Field(gt=0, le=1)            # fraction of users here (shares sum ~1)
+
+
+class ServingSinglePlan(BaseModel):
+    """Serve ALL users from one region."""
+    provider: Provider
+    region: str
+    weighted_latency_ms: float                  # traffic-weighted latency across hubs
+    carbon_g_co2_per_kwh: float
+    carbon_source: str
+    carbon_quality: str
+
+
+class ServingPerHubChoice(BaseModel):
+    """The region chosen to serve one hub, in a multi-region plan."""
+    hub: str
+    provider: Provider
+    region: str
+    latency_ms: float
+    carbon_g_co2_per_kwh: float
+
+
+class ServingPatternAdvice(BaseModel):
+    """Design-time 'where should I serve my users from?' — single-region vs multi-region.
+
+    Directional. Reuses carbon + latency, and composes the egress (cross-region data sync) and
+    residency (cross-jurisdiction) caveats. NOT a runtime meter; NOT a verdict on legality."""
+    hubs: list[ServingHub]
+    single_region: Optional[ServingSinglePlan] = None       # best one-region-for-all option
+    multi_region: list[ServingPerHubChoice] = []            # one region per hub (nearest+greener)
+    multi_region_weighted_latency_ms: Optional[float] = None
+    multi_region_blended_carbon_g_co2_per_kwh: Optional[float] = None
+    recommended_pattern: str = ""                           # "single_region" | "multi_region"
+    data_sync_egress_note: Optional[str] = None             # multi-region implies shared-state sync
+    residency_note: Optional[str] = None                    # if any chosen region crosses a hub's jurisdiction
+    rationale: str = ""
+    limitations: str = ""
+
+
+class DataLocalityWarning(BaseModel):
+    """Whether running compute away from where the data lives will cost you in egress.
+
+    The core 'does the greener-region move backfire?' check. Primary signal is egress COST;
+    transfer carbon is a secondary, deliberately-coarse figure."""
+    compute_location: str                       # "provider/region"
+    data_location: str                          # "provider/region"
+    monthly_cross_boundary_gb: float
+    locality: str                               # "same_region" | "cross_region_same_cloud" | "cross_cloud"
+    severity: str                               # "none" | "low" | "medium" | "high"
+    egress_rate_usd_per_gb_low: Optional[float] = None    # per-GB rate range for this tier
+    egress_rate_usd_per_gb_high: Optional[float] = None
+    est_monthly_egress_usd_low: Optional[float] = None    # monthly cost range = rate range x GB
+    est_monthly_egress_usd_high: Optional[float] = None
+    est_monthly_transfer_kg_co2: Optional[float] = None   # secondary, coarse
+    carbon_saving_kg_co2_from_move: Optional[float] = None # echoed back if provided
+    net_carbon_verdict: Optional[str] = None    # set only when a saving was supplied
+    residency_note: Optional[str] = None        # neutral cross-jurisdiction heads-up, if any
+    warning: str = ""
+    recommendation: str = ""
+    limitations: str = ""
+
+
+class RegionCandidate(BaseModel):
+    """One region scored on all three axes — the tri-axis payload."""
+    region: str
+    provider: Provider
+    carbon: CarbonReading
+    carbon_rank: Optional[int] = None            # 1 = cleanest among candidates
+    carbon_vs_baseline_pct: Optional[float] = None  # negative = cleaner than the baseline region
+    est_monthly_cost_usd: Optional[float] = None    # compute + egress ballpark
+    latency_ms_estimate: Optional[float] = None     # to the user's location
+    added_latency_ms: Optional[float] = None        # vs. the baseline region
+    # Per-axis relative rating within the candidate set: "green" | "yellow" | "red".
+    # Relative, not absolute — "best available among your options", shown next to the raw value.
+    carbon_rating: Optional[str] = None
+    latency_rating: Optional[str] = None
+    cost_rating: Optional[str] = None
+    tradeoff: Optional[str] = None                  # one-line plain-English summary
+
+
+class Recommendation(BaseModel):
+    """The full answer: ranked candidates + a pick + honest caveats."""
+    candidates: list[RegionCandidate]
+    recommended_region: Optional[str] = None
+    residency_note: Optional[str] = None        # neutral heads-up if the pick crosses jurisdictions
+    rationale: str = ""
+    limitations: str = ""