greenpick 0.1.0__py3-none-any.whl

greenpick/server.py

@@ -0,0 +1,349 @@
+"""MCP server: exposes GreenPick's 15 tools over FastMCP.
+
+Thin layer — parse/validate inputs, call services, return JSON-friendly dicts. All math
+lives in services/; this file only wires tools to them.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .models import Workload, GeoPoint, Provider
+from .data import get_repository
+from .services import (
+    carbon_service, recommender, scheduling_service, instance_service, locality_service,
+    training_service, forecast_service, serving_service, metric_scaffold_service,
+    rightsizing_service, inference_service,
+)
+from .models import ServingHub
+
+mcp = FastMCP("greenpick")
+_repo = get_repository()
+
+
+@mcp.tool()
+async def compare_regions_tri_axis(
+    user_lat: float,
+    user_lon: float,
+    vcpu: float,
+    ram_gb: float,
+    est_monthly_egress_gb: float = 0,
+    providers: Optional[list[str]] = None,
+    optimize_for: str = "carbon",
+    max_added_latency_ms: Optional[float] = None,
+    baseline_region: Optional[str] = None,
+    regions: Optional[list[str]] = None,
+) -> dict:
+    """Rank candidate cloud regions by carbon, with cost + latency tradeoffs, and recommend one.
+    Give the user's location (lat/lon) and the service shape (vcpu, ram_gb, egress). Pass `regions`
+    (e.g. ["us-east-1","us-west-2","eu-west-1"]) to rank ONLY those you'd actually consider,
+    instead of the whole catalog — your baseline is always kept in the comparison. If the pick is
+    in a different region from where your data lives, run data_locality_egress_check before moving:
+    cross-region/cross-cloud egress can erase the carbon/cost win."""
+    rec = await recommender.compare_regions(
+        _repo,
+        providers=[p for p in (providers or [])] or None,  # type: ignore[list-item]
+        user_location=GeoPoint(lat=user_lat, lon=user_lon),
+        workload=Workload(vcpu=vcpu, ram_gb=ram_gb, est_monthly_egress_gb=est_monthly_egress_gb),
+        optimize_for=optimize_for,
+        max_added_latency_ms=max_added_latency_ms,
+        baseline_region=baseline_region,
+        regions=[r for r in (regions or [])] or None,
+    )
+    return rec.model_dump()
+
+
+@mcp.tool()
+async def greener_alternative_to(
+    current_region: str,
+    user_lat: float,
+    user_lon: float,
+    vcpu: float,
+    ram_gb: float,
+    est_monthly_egress_gb: float = 0,
+    max_added_latency_ms: float = 100,
+    providers: Optional[list[str]] = None,
+    regions: Optional[list[str]] = None,
+) -> dict:
+    """You picked `current_region` — find the greenest region within +max_added_latency_ms,
+    with the carbon/cost/latency delta vs. your current choice. The core 'nudge' tool. Pass
+    `regions` to limit the search to options you'd actually move to; your current region is
+    always included. Before accepting a move, run data_locality_egress_check if your data stays in
+    the current region — the egress to feed compute from afar can outweigh the greener-region win."""
+    rec = await recommender.compare_regions(
+        _repo,
+        providers=[p for p in (providers or [])] or None,  # type: ignore[list-item]
+        user_location=GeoPoint(lat=user_lat, lon=user_lon),
+        workload=Workload(vcpu=vcpu, ram_gb=ram_gb, est_monthly_egress_gb=est_monthly_egress_gb),
+        optimize_for="carbon",
+        max_added_latency_ms=max_added_latency_ms,
+        baseline_region=current_region,
+        regions=[r for r in (regions or [])] or None,
+    )
+    return rec.model_dump()
+
+
+@mcp.tool()
+async def estimate_workload_carbon(
+    provider: str,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    hours_per_month: float = 730,
+) -> dict:
+    """Rough kgCO2/month for a workload running in a region. An ESTIMATE (documented power
+    model x grid intensity), not a measurement."""
+    reading = await carbon_service.carbon_now(_repo, provider, region)  # type: ignore[arg-type]
+    wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=hours_per_month)
+    kg = carbon_service.estimate_kg_co2_per_month(wl, reading)
+    return {
+        "provider": provider,
+        "region": region,
+        "estimated_kg_co2_per_month": kg,
+        "grid_intensity_g_co2_per_kwh": reading.g_co2_per_kwh,
+        "carbon_source": reading.source,
+        "carbon_quality": reading.quality,
+        "note": "Estimate only: documented power model x grid intensity. Not a measurement.",
+    }
+
+
+@mcp.tool()
+async def region_carbon_now(provider: str, region: str) -> dict:
+    """Current grid carbon intensity for a region, with source, timestamp, and data freshness."""
+    reading = await carbon_service.carbon_now(_repo, provider, region)  # type: ignore[arg-type]
+    return reading.model_dump()
+
+
+@mcp.tool()
+async def cleanest_hours_to_run(
+    provider: str, region: str, top_n: int = 3, window_hours: Optional[int] = None,
+) -> dict:
+    """Carbon-aware scheduling: given a region, report its cleanest recent hours so you can
+    time a DEFERRABLE job (nightly ETL, batch, backups, training) when the grid is greenest.
+    Returns the lowest-carbon hours + the % reduction vs. the dirtiest hour. Pass `window_hours`
+    (e.g. 6) for a job of known duration — it finds the cleanest CONTIGUOUS run of that many hours
+    to start at, since you can't split one job across scattered non-adjacent hours. Directional."""
+    advice = await scheduling_service.cleanest_hours(
+        _repo, provider, region, top_n, window_hours=window_hours,  # type: ignore[arg-type]
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def greener_instance_family(
+    provider: str,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    current_family: Optional[str] = None,
+    hours_per_month: float = 730,
+) -> dict:
+    """Suggest a greener SAME-SIZE instance family in the SAME region. The mechanism is
+    performance-per-watt: a newer-generation or ARM (Graviton-class) family does the same
+    work on less energy -> less CO2 at the region's grid intensity. Give your current family
+    (e.g. 'm5', 'n2', 'Dv5') for a savings delta. Directional, not a measurement."""
+    if not instance_service.is_supported_provider(provider):
+        return {
+            "provider": provider,
+            "region": region,
+            "error": f"Unsupported provider '{provider}'.",
+            "supported_providers": list(instance_service.SUPPORTED_PROVIDERS),
+            "options": [],
+        }
+    advice = await instance_service.greener_instance_family(
+        _repo, provider, region, vcpu, ram_gb,  # type: ignore[arg-type]
+        current_family=current_family, hours_per_month=hours_per_month,
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def estimate_inference_carbon(
+    size_class: str,
+    monthly_requests: float,
+    avg_output_tokens: int = 300,
+    region: Optional[str] = None,
+    provider: Optional[str] = None,
+) -> dict:
+    """Energy + CO2 of running an LLM INFERENCE workload (serving queries) — the inference-side
+    sibling of estimate_training_carbon. Give the model SIZE CLASS (small | mid | large |
+    frontier_dense | moe, or a param alias like '8b' / '70b' / 'moe'), monthly request volume, and
+    avg OUTPUT tokens per request (output drives inference energy). Pass `region` to add CO2 at live
+    grid intensity. Returns a LOW-HIGH kWh/CO2 band (wide on purpose — serving choices move the same
+    model many-fold). Directional, most trustworthy for self-hosted/open models; keyed on size class,
+    NOT a named-model leaderboard. Smaller size class is the biggest lever."""
+    advice = await inference_service.estimate_inference_carbon(
+        _repo, size_class, monthly_requests, avg_output_tokens=avg_output_tokens,  # type: ignore[arg-type]
+        region=region, provider=provider,  # type: ignore[arg-type]
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def rightsizing_check(
+    provider: str,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    cpu_utilization: float,
+    ram_utilization: Optional[float] = None,
+    hours_per_month: float = 730,
+) -> dict:
+    """Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller
+    size cuts BOTH cost and carbon — same work, less waste, no tradeoff. Give the provisioned size
+    (vcpu, ram_gb) and observed CPU utilisation (0..1, e.g. 0.2 for 20%); optionally RAM utilisation.
+    Returns the right-sized target (keeps ~40% headroom) with the monthly $ AND kg CO2 saving. Lead
+    with the cost number, carbon is the twin. Directional, design-time — uses the utilisation you
+    report, not a reading of your fleet."""
+    advice = await rightsizing_service.rightsizing_check(
+        _repo, provider, region, vcpu, ram_gb, cpu_utilization,  # type: ignore[arg-type]
+        ram_utilization=ram_utilization, hours_per_month=hours_per_month,
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def carbon_metric_scaffold(
+    language: str = "python",
+    region: Optional[str] = None,
+    provider: Optional[str] = None,
+    vcpu: float = 1,
+    ram_gb: float = 2,
+) -> dict:
+    """Emit paste-in instrumentation so the user's OWN app can report an ESTIMATED carbon metric
+    over time. Consider offering this when the user is building an app/service and wants ongoing
+    visibility into its footprint. GreenPick returns a code snippet (Python in v1) + the power-model
+    coefficients + a methodology note; the app measures observable proxies (CPU utilisation, vCPU/RAM,
+    uptime) and multiplies by GreenPick's power model x the region's grid intensity. Pass `region`
+    to bake in live grid intensity. The emitted number is a DIRECTIONAL estimate, self-labelled, NOT
+    metered energy — and it's for SELF-tracking, not ranking against other apps. GreenPick does not
+    run or measure anything itself."""
+    scaffold = await metric_scaffold_service.carbon_metric_scaffold(
+        _repo, language=language, region=region, provider=provider,  # type: ignore[arg-type]
+        vcpu=vcpu, ram_gb=ram_gb,
+    )
+    return scaffold.model_dump()
+
+
+@mcp.tool()
+async def serving_pattern_advice(
+    hubs: list[dict],
+    vcpu: float = 1,
+    ram_gb: float = 2,
+    providers: Optional[list[str]] = None,
+) -> dict:
+    """Design-time advice for a USER-FACING PLATFORM: should you serve users from ONE region or
+    SEVERAL? Consider calling this when the user is building a web app / dashboard / API that serves
+    end users. Give `hubs` as where your users are — a list like
+    [{"name":"eu","share":0.4},{"name":"us","share":0.4},{"name":"apac","share":0.2}] (known names
+    us/eu/uk/apac/au/india/japan/sa resolve automatically, or pass lat+lon). Rough shares are fine.
+    Scores single-region-for-all vs one-region-per-hub on weighted latency + grid carbon, and flags
+    the multi-region catches: cross-region data-sync egress and cross-jurisdiction residency. This is
+    design-time guidance, NOT a runtime meter — it never measures your running app."""
+    parsed = [
+        ServingHub(
+            name=str(h.get("name", f"hub{i}")),
+            lat=float(h.get("lat", 0) or 0), lon=float(h.get("lon", 0) or 0),
+            share=float(h.get("share", 1.0 / max(1, len(hubs)))),
+        )
+        for i, h in enumerate(hubs)
+    ]
+    advice = await serving_service.serving_pattern(
+        _repo, parsed, Workload(vcpu=vcpu, ram_gb=ram_gb),
+        providers=[p for p in (providers or [])] or None,  # type: ignore[list-item]
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def data_locality_egress_check(
+    compute_provider: str,
+    compute_region: str,
+    data_provider: str,
+    data_region: str,
+    monthly_cross_boundary_gb: float,
+    carbon_saving_kg_co2_from_move: Optional[float] = None,
+) -> dict:
+    """Will running compute away from where your DATA lives backfire via egress? Give where
+    compute runs, where the data lives (provider+region), and monthly GB crossing between them.
+    Returns a directional egress-COST ballpark, a coarse transfer-carbon figure, and — if you
+    pass the carbon saving the greener-region move buys — whether it's still a net win. Use this
+    before accepting a greener-region suggestion when your data stays put."""
+    advice = await locality_service.data_locality_check(
+        _repo, compute_provider, compute_region, data_provider, data_region,  # type: ignore[arg-type]
+        monthly_cross_boundary_gb=monthly_cross_boundary_gb,
+        carbon_saving_kg_co2_from_move=carbon_saving_kg_co2_from_move,
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def carbon_forecast(
+    provider: str, region: str, hours_ahead: int = 24, top_n: int = 5,
+) -> dict:
+    """Forward-looking scheduling: which UPCOMING hours will be cleanest? Uses the EU day-ahead
+    wind+solar forecast (ENTSO-E) to rank the greenest hours over the next `hours_ahead`. This is
+    a RELATIVE ranking (more forecast renewables = cleaner), not an absolute gCO2/kWh forecast.
+    EU regions get a true forecast; US/uncovered regions degrade to the recent historical pattern
+    (labelled 'historical'). Use this to PLAN a deferrable job, vs cleanest_hours_to_run (reactive)."""
+    advice = await forecast_service.carbon_forecast(
+        _repo, provider, region, hours_ahead=hours_ahead, top_n=top_n,  # type: ignore[arg-type]
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def cleanest_time_of_day(provider: str, region: str) -> dict:
+    """For a RECURRING job (e.g. a nightly batch you run every day), find the region's cleanest
+    time of day — each hour-of-day averaged across the recent days of data. Returns the cleanest/
+    dirtiest hour-of-day and the % gap. Honest scope: a DAILY pattern over the few days of free
+    data, NOT a 7-day day-of-week pattern. Use `cleanest_hours_to_run` for a one-off job's timing."""
+    advice = await scheduling_service.cleanest_time_of_day(_repo, provider, region)  # type: ignore[arg-type]
+    return advice.model_dump()
+
+
+@mcp.tool()
+async def estimate_training_carbon(
+    gpu: str,
+    gpu_count: int,
+    gpu_hours: float,
+    region: Optional[str] = None,
+    provider: Optional[str] = None,
+    utilization: Optional[float] = None,
+    top_n_regions: int = 5,
+) -> dict:
+    """Carbon of a GPU training run, with greener WHERE (region) and WHEN (hours) guidance.
+    Give the GPU (e.g. 'a100', 'h100', 'l4'), how many, and total GPU-hours for the run. Omit
+    `region` to rank regions greenest-first; pass one to score just that region. Training is both
+    portable and deferrable, so this combines region choice with cleanest-hours timing. Directional
+    (TDP-based energy); GPU availability per region is NOT checked - verify your card is offered there.
+    Training data is often large: if your dataset lives in another region, run data_locality_egress_check
+    before shipping the job to the greenest region - the data egress can outweigh the carbon saving."""
+    advice = await training_service.estimate_training_carbon(
+        _repo, gpu, gpu_count, gpu_hours,  # type: ignore[arg-type]
+        region=region, provider=provider, utilization=utilization,  # type: ignore[arg-type]
+        top_n_regions=top_n_regions,
+    )
+    return advice.model_dump()
+
+
+@mcp.tool()
+def explain_methodology_and_limits() -> dict:
+    """GreenPick's assumptions and what it explicitly does NOT claim. Read this before trusting a number."""
+    return {
+        "what_it_is": "Directional, design-time guidance for choosing a greener cloud region.",
+        "what_it_is_not": "Audited carbon accounting, ESG/Scope-2 reporting, or a real-time scheduler.",
+        "carbon": "Grid carbon intensity by region, point-in-time. Not flow-traced consumption accounting.",
+        "cost": "Ballpark from a dated static table (compute + egress). Not a quote.",
+        "latency": "Great-circle geographic estimate, not a measured ping.",
+        "carbon_estimate": "Workload CO2 = documented power model (vCPU/RAM -> watts) x PUE x grid intensity.",
+        "instance_family": "Greener-family suggestion uses DIRECTIONAL perf-per-watt multipliers by generation/arch (ARM/Graviton-class = biggest win), not a benchmark of your workload.",
+        "data_locality": "Egress check leads with a DIRECTIONAL cost ballpark (flat per-GB, ignores free tiers/tiered pricing); transfer carbon uses a single kWh/GB coefficient whose published estimates span orders of magnitude — order-of-magnitude only.",
+        "training": "Training carbon uses published GPU TDP (peak, not your run's measured draw) x a utilization assumption + host overhead x PUE, then x the region's grid intensity. GPU availability per region is NOT checked. Ignores spot/on-demand, checkpointing, multi-node networking.",
+        "inference": "LLM inference carbon is keyed on model SIZE CLASS (not a named product) with a wide LOW-HIGH band (quantisation/batching/serving move the same model many-fold); output tokens drive it. Directional, most trustworthy for self-hosted/open models; NOT a named-model leaderboard.",
+        "forecast": "Day-ahead forecast is RELATIVE: upcoming hours ranked by forecast wind+solar output (ENTSO-E A69), not an absolute gCO2/kWh forecast. EU only; US/uncovered zones degrade to the recent historical pattern (labelled 'historical').",
+        "data_residency": "GreenPick flags when a recommended move CROSSES a jurisdiction (esp. leaving the EEA) as a geographic heads-up only. It does NOT assess legal/GDPR compliance, does not encode adequacy decisions, and is not legal advice — confirm with your own data governance.",
+        "ignored": "Embodied/hardware carbon and provider renewable-energy certificates.",
+        "data_sources": "Electricity Maps free tier (primary); ENTSO-E / EIA / NESO fallbacks; annual averages offline.",
+    }

greenpick/services/__init__.py

@@ -0,0 +1,5 @@
+"""Business logic: pure, unit-testable functions over models + static data.
+
+Deliberately free of MCP and I/O concerns (except carbon, which takes a repository),
+so the math can be tested in isolation and the LLM never supplies figures.
+"""

greenpick/services/carbon_service.py

@@ -0,0 +1,28 @@
+"""Carbon readings (via the repository) + a workload CO2 ESTIMATE.
+
+The estimate turns a workload into average watts (power model) -> kWh/month ->
+multiply by grid intensity. Clearly an estimate, not a measurement.
+"""
+from __future__ import annotations
+
+from ..models import CarbonReading, Workload, Provider
+from ..data.repository import CarbonRepository
+from ..data.static_data import power_model
+
+
+async def carbon_now(repo: CarbonRepository, provider: Provider, region: str) -> CarbonReading:
+    return await repo.carbon_now(provider, region)
+
+
+def workload_kwh_per_month(workload: Workload) -> float:
+    pm = power_model()
+    watts = workload.vcpu * pm["watts_per_vcpu"] + workload.ram_gb * pm["watts_per_gb_ram"]
+    watts *= pm["pue_default"]
+    kwh = watts / 1000.0 * workload.hours_per_month
+    return kwh
+
+
+def estimate_kg_co2_per_month(workload: Workload, reading: CarbonReading) -> float:
+    kwh = workload_kwh_per_month(workload)
+    grams = kwh * reading.g_co2_per_kwh
+    return round(grams / 1000.0, 2)

greenpick/services/cost_service.py

@@ -0,0 +1,21 @@
+"""Ballpark monthly cost (compute + egress) from the dated static pricing table.
+
+Deterministic. Returns None if the provider isn't in the table rather than guessing.
+NOT a quote — see data/pricing.json caveats.
+"""
+from __future__ import annotations
+
+from ..models import Workload, Provider
+from ..data.static_data import pricing
+
+
+def estimate_monthly_cost_usd(provider: Provider, workload: Workload) -> float | None:
+    table = pricing().get(provider)
+    if not table:
+        return None
+    compute = (
+        workload.vcpu * table["compute_usd_per_vcpu_hour"]
+        + workload.ram_gb * table["compute_usd_per_gb_ram_hour"]
+    ) * workload.hours_per_month
+    egress = workload.est_monthly_egress_gb * table["egress_usd_per_gb"]
+    return round(compute + egress, 2)

greenpick/services/forecast_service.py

@@ -0,0 +1,72 @@
+"""Forward-looking carbon-aware scheduling: which UPCOMING hours will be cleanest?
+
+Turns scheduling from reactive (recent history) to planned (day-ahead). The honest signal — per
+the data spike — is the ENTSO-E day-ahead wind+solar forecast (A69), reliable across EU zones.
+We rank upcoming hours by forecast renewable output: more wind+solar = cleaner hour. This is a
+RELATIVE ranking, not a gCO2/kWh forecast (the free data can't support absolute intensity ahead).
+
+Degrade path: no forecast for the region (US today, or a zone ENTSO-E has no A69 for) -> fall back
+to the recent historical daily pattern we already compute, relabelled 'historical' so the user
+knows it's backward-looking, not a true forecast.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import ForecastAdvice, ForecastHour, Provider
+from ..data.repository import CarbonRepository
+from . import scheduling_service
+
+LIMITATIONS = (
+    "RELATIVE forecast: upcoming hours ranked by day-ahead wind+solar output (more renewables = "
+    "cleaner), NOT an absolute gCO2/kWh forecast — the free day-ahead data has no forecast fuel mix "
+    "across all zones. EU only (ENTSO-E A69); US and uncovered zones degrade to the recent historical "
+    "pattern (labelled 'historical'). Directional; forecasts shift with weather."
+)
+
+
+async def carbon_forecast(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+    hours_ahead: int = 24,
+    top_n: int = 5,
+) -> ForecastAdvice:
+    forecast: list[ForecastHour] = []
+    getter = getattr(repo, "renewable_forecast", None)
+    if getter is not None:
+        forecast = await getter(provider, region, hours_ahead)
+
+    if forecast:
+        # Cleaner = MORE forecast renewable output. Rank descending by renewable_mw (or share if
+        # every hour has it, which is a better normaliser).
+        use_share = all(h.renewable_share is not None for h in forecast)
+        key = (lambda h: h.renewable_share) if use_share else (lambda h: h.renewable_mw)
+        by_clean = sorted(forecast, key=key, reverse=True)  # type: ignore[arg-type,return-value]
+        peak = by_clean[0]
+        low = by_clean[-1]
+        metric = "renewable share" if use_share else "forecast wind+solar"
+        note = (f"Over the next ~{hours_ahead}h, the grid in {provider}/{region} is forecast "
+                f"cleanest around {peak.period} (highest {metric}) and dirtiest around "
+                f"{low.period}. Shift deferrable work toward the cleanest upcoming hours.")
+        return ForecastAdvice(
+            region=region, provider=provider, source="entsoe_forecast", quality="forecast",
+            hours_ahead=hours_ahead, cleanest_upcoming=by_clean[:max(1, top_n)],
+            peak_renewable_period=peak.period, low_renewable_period=low.period,
+            note=note, limitations=LIMITATIONS,
+        )
+
+    # --- Degrade: no forward forecast for this region -> recent historical daily pattern ---
+    pattern = await scheduling_service.cleanest_time_of_day(repo, provider, region)
+    note = ("No day-ahead forecast available for this region, so this is the recent HISTORICAL "
+            "pattern, not a true forecast. ")
+    if pattern.cleanest_hour_of_day is not None:
+        note += (f"Over the last ~{pattern.days_analyzed} day(s) it's been cleanest around "
+                 f"{pattern.cleanest_hour_of_day:02d}:00 - a reasonable default for a recurring job.")
+    else:
+        note += "No usable recent history either."
+    return ForecastAdvice(
+        region=region, provider=provider, source="historical_fallback", quality="historical",
+        hours_ahead=hours_ahead, cleanest_upcoming=[],
+        note=note, limitations=LIMITATIONS,
+    )

greenpick/services/inference_service.py

@@ -0,0 +1,100 @@
+"""LLM inference carbon — the inference-side sibling of estimate_training_carbon.
+
+Most of an LLM's lifetime carbon is INFERENCE (serving queries), not training. A developer building
+on an LLM makes a carbon choice constantly and invisibly: which model (size), how many requests, how
+many output tokens, where it runs. This estimates the energy + CO2 of that serving workload.
+
+Honest scoping (per the data spike):
+- Keyed on model SIZE CLASS, not named commercial products (vendors don't disclose serving hardware).
+- OUTPUT tokens drive the estimate (generation dominates inference energy).
+- Reported as a LOW-HIGH band, because quantisation/batching/serving move the same model many-fold.
+- Carbon = energy x the region's live grid intensity (reuses the carbon repository), when a region
+  is given. Directional; most trustworthy for self-hosted/open models.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import Provider, InferenceCarbonAdvice
+from ..data.repository import CarbonRepository
+from ..data.static_data import inference_energy, resolve_size_class
+from . import carbon_service
+
+LIMITATIONS = (
+    "DIRECTIONAL estimate, not a measurement. Keyed on model SIZE CLASS (not a named product — "
+    "vendors don't publish serving hardware/batching). The LOW-HIGH band is wide on purpose: "
+    "quantisation, batching, and request shaping move the same model's energy many-fold. Output "
+    "tokens drive it; input tokens are ignored. MoE models use the 'moe' class (they run near their "
+    "ACTIVE param count, not total). Most trustworthy for self-hosted/open models; a hosted API's "
+    "real figure depends on the provider's undisclosed setup. Not for ranking named commercial models."
+)
+
+
+async def estimate_inference_carbon(
+    repo: CarbonRepository,
+    size_class: str,
+    monthly_requests: float,
+    avg_output_tokens: int = 300,
+    region: Optional[str] = None,
+    provider: Optional[Provider] = None,
+) -> InferenceCarbonAdvice:
+    resolved = resolve_size_class(size_class)
+    if resolved is None:
+        classes = ", ".join(inference_energy().get("size_classes", {}).keys())
+        return InferenceCarbonAdvice(
+            size_class=size_class, size_class_label=size_class,
+            monthly_requests=monthly_requests, avg_output_tokens=avg_output_tokens,
+            monthly_output_tokens=0, wh_per_1k_output_low=0, wh_per_1k_output_high=0,
+            monthly_kwh_low=0, monthly_kwh_high=0,
+            rationale=(f"Unknown size class '{size_class}'. Use one of: {classes} "
+                       f"(or a param-count alias like 8b / 70b / moe)."),
+            limitations=LIMITATIONS,
+        )
+
+    cls_key, spec = resolved
+    lo = spec["wh_per_1k_output_tokens_low"]
+    hi = spec["wh_per_1k_output_tokens_high"]
+
+    monthly_output_tokens = monthly_requests * avg_output_tokens
+    # Wh = (Wh per 1k output tokens) x (output tokens / 1000); kWh = Wh / 1000.
+    kwh_low = round(lo * monthly_output_tokens / 1000.0 / 1000.0, 3)
+    kwh_high = round(hi * monthly_output_tokens / 1000.0 / 1000.0, 3)
+
+    advice = InferenceCarbonAdvice(
+        size_class=cls_key, size_class_label=spec["label"],
+        monthly_requests=monthly_requests, avg_output_tokens=avg_output_tokens,
+        monthly_output_tokens=monthly_output_tokens,
+        wh_per_1k_output_low=lo, wh_per_1k_output_high=hi,
+        monthly_kwh_low=kwh_low, monthly_kwh_high=kwh_high,
+        limitations=LIMITATIONS,
+    )
+
+    carbon_txt = ""
+    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]
+            g = reading.g_co2_per_kwh
+            advice.region = region
+            advice.grid_intensity_g_co2_per_kwh = g
+            advice.carbon_source = reading.source
+            advice.carbon_quality = reading.quality
+            advice.monthly_kg_co2_low = round(kwh_low * g / 1000.0, 2)
+            advice.monthly_kg_co2_high = round(kwh_high * g / 1000.0, 2)
+            carbon_txt = (f" In {prov}/{region} ({g:.0f} gCO2/kWh, {reading.source}) that's "
+                          f"~{advice.monthly_kg_co2_low:.1f}-{advice.monthly_kg_co2_high:.1f} kg CO2/mo.")
+
+    advice.rationale = (
+        f"{spec['label']}: ~{monthly_requests:,.0f} requests/mo x ~{avg_output_tokens} output tokens "
+        f"= ~{monthly_output_tokens/1e6:.1f}M output tokens -> ~{kwh_low:,.1f}-{kwh_high:,.1f} kWh/mo "
+        f"(band reflects serving choices: quantisation/batching/shaping).{carbon_txt} A smaller size "
+        f"class is the biggest lever - energy scales steeply with model size.")
+    return advice
+
+
+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