greenpick 0.4.2__tar.gz → 0.5.1__tar.gz

{greenpick-0.4.2/src/greenpick.egg-info → greenpick-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.4.2
+Version: 0.5.1
 Summary: Design-time sustainability co-pilot (MCP server): greener, cheaper cloud infrastructure decisions with carbon + cost + latency tradeoffs.
 Author-email: "Data Science Advisers, LLC" <info@datascienceadvisers.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-15-0ea5e9" alt="MCP tools: 15" />
+  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -52,7 +52,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 15 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -143,7 +143,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-15 tools, grouped by what you're trying to do.
+17 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -159,6 +159,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `cleanest_hours_to_run` | Cleanest recent hours to time a deferrable job (ETL, backups, training), + % reduction. Pass `window_hours` for a job of known duration → cleanest contiguous window to start at. |
 | `cleanest_time_of_day` | For a **recurring** job (nightly batch): the region's cleanest time of day, averaged across recent days. A daily pattern, not a 7-day weekly one. |
+| `greenest_regions_on_average` | Which regions are cleanest on a **typical** day in a given month (or the whole year), ranked from last year's real data. Offline, no keys; a planning view, not today's grid. |
 | `carbon_forecast` | Forward-looking: which **upcoming** hours will be cleanest, from the EU day-ahead wind+solar forecast (ENTSO-E). Relative ranking; US/uncovered zones degrade to the recent historical pattern. |
 
 ### Estimate a workload's carbon
@@ -175,6 +176,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `greener_instance_family` | A greener same-size family in the same region via perf-per-watt (newer generation / ARM Graviton-class does the same work on less energy). |
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
+| `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 

{greenpick-0.4.2 → greenpick-0.5.1}/README.md

@@ -14,7 +14,7 @@
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-15-0ea5e9" alt="MCP tools: 15" />
+  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -22,7 +22,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 15 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -113,7 +113,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-15 tools, grouped by what you're trying to do.
+17 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -129,6 +129,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `cleanest_hours_to_run` | Cleanest recent hours to time a deferrable job (ETL, backups, training), + % reduction. Pass `window_hours` for a job of known duration → cleanest contiguous window to start at. |
 | `cleanest_time_of_day` | For a **recurring** job (nightly batch): the region's cleanest time of day, averaged across recent days. A daily pattern, not a 7-day weekly one. |
+| `greenest_regions_on_average` | Which regions are cleanest on a **typical** day in a given month (or the whole year), ranked from last year's real data. Offline, no keys; a planning view, not today's grid. |
 | `carbon_forecast` | Forward-looking: which **upcoming** hours will be cleanest, from the EU day-ahead wind+solar forecast (ENTSO-E). Relative ranking; US/uncovered zones degrade to the recent historical pattern. |
 
 ### Estimate a workload's carbon
@@ -145,6 +146,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `greener_instance_family` | A greener same-size family in the same region via perf-per-watt (newer generation / ARM Graviton-class does the same work on less energy). |
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
+| `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 

{greenpick-0.4.2 → greenpick-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.4.2"
+version = "0.5.1"
 description = "Design-time sustainability co-pilot (MCP server): greener, cheaper cloud infrastructure decisions with carbon + cost + latency tradeoffs."
 readme = "README.md"
 requires-python = ">=3.11"

{greenpick-0.4.2 → greenpick-0.5.1}/src/greenpick/__init__.py

@@ -4,7 +4,7 @@ Greener cloud-region choices with honest carbon + cost + latency tradeoffs,
 delivered inside the vibe-coding loop. Directional guidance, not audited accounting.
 """
 
-__version__ = "0.4.2"
+__version__ = "0.5.1"
 
 # httpx logs every request URL at INFO, and our live sources pass their API key / token as a URL
 # query parameter — so at the default log level the secret would land in the MCP client's logs.

{greenpick-0.4.2 → greenpick-0.5.1}/src/greenpick/models.py

@@ -317,6 +317,7 @@ class DataLocalityWarning(BaseModel):
     transfer_carbon_quality: Optional[str] = None
     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
+    verdict_status: str = "not_evaluated"       # 'evaluated' only when a saving was supplied
     residency_note: Optional[str] = None        # neutral cross-jurisdiction heads-up, if any
     warning: str = ""
     recommendation: str = ""
@@ -348,3 +349,32 @@ class Recommendation(BaseModel):
     residency_note: Optional[str] = None        # neutral heads-up if the pick crosses jurisdictions
     rationale: str = ""
     limitations: str = ""
+
+
+class OffHoursAdvice(BaseModel):
+    """What switching a non-prod / idle environment off outside the hours it's needed saves.
+
+    The other FinOps basic next to right-sizing: the cheapest hour is the one you don't run.
+    Cost and carbon both scale with running hours, so the saving is the same fraction of each.
+    Directional, compute only."""
+    provider: Provider
+    region: str
+    vcpu: float
+    ram_gb: float
+    hours_per_week_on: float
+    hours_per_month_now: float                    # always-on baseline (730)
+    hours_per_month_scheduled: float
+    on_share_pct: float                           # share of the month it's running
+    cost_now_usd_per_month: Optional[float] = None
+    cost_scheduled_usd_per_month: Optional[float] = None
+    monthly_usd_saving: Optional[float] = None
+    cost_saving_pct: Optional[float] = None
+    carbon_now_kg_per_month: Optional[float] = None
+    carbon_scheduled_kg_per_month: Optional[float] = None
+    monthly_kg_co2_saving: Optional[float] = None
+    carbon_saving_pct: Optional[float] = None
+    is_worthwhile: bool = False
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
+    rationale: str = ""
+    limitations: str = ""

{greenpick-0.4.2 → greenpick-0.5.1}/src/greenpick/server.py

@@ -1,4 +1,4 @@
-"""MCP server: exposes GreenPick's 15 tools over FastMCP.
+"""MCP server: exposes GreenPick's 17 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.
@@ -25,7 +25,7 @@ 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,
+    rightsizing_service, inference_service, offhours_service, typical_ranking_service,
 )
 from .models import ServingHub
 from .services.data_hint import with_hint
@@ -38,13 +38,15 @@ INSTRUCTIONS = """\
 GreenPick advises on cloud infrastructure decisions BEFORE you deploy, weighing carbon, cost and \
 latency together. Strongest uses, in order:
 1. Right-sizing (rightsizing_check): an over-provisioned instance cut to a standard, buyable size \
-saves money and carbon in the same move. Lead with the monthly dollar saving.
+saves money and carbon in the same move. Lead with the monthly dollar saving. For dev, test or other \
+environments that don't need to run 24/7, offhours_check shows what switching them off saves.
 2. Scheduling deferrable jobs: cleanest_hours_to_run (one-off), cleanest_time_of_day (recurring), \
 carbon_forecast (EU day-ahead).
 3. GPU training and LLM inference footprints: estimate_training_carbon (gpu_hours is the TOTAL across \
 all GPUs; report wall_clock_hours as the run length), estimate_inference_carbon.
 4. Efficiency and placement: greener_instance_family, compare_regions_tri_axis, greener_alternative_to, \
-serving_pattern_advice; carbon_metric_scaffold for an app to track its own estimated carbon.
+serving_pattern_advice, greenest_regions_on_average (which regions are normally cleanest in a month); \
+carbon_metric_scaffold for an app to track its own estimated carbon.
 Before recommending a region move, run data_locality_egress_check: egress can erase the win. Mention \
 any residency_note.
 Every carbon figure carries source and quality fields. Report 'typical', 'mock', 'cached' or \
@@ -248,6 +250,48 @@ async def rightsizing_check(
     return with_hint(advice.model_dump())
 
 
+@mcp.tool(annotations=LIVE_DATA_TOOL)
+async def offhours_check(
+    provider: str,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    hours_per_week_on: float,
+) -> dict:
+    """Non-prod / idle scheduling, the other FinOps basic next to right-sizing: "this doesn't need to
+    run 24/7." Give the instance size and how many hours a WEEK it actually needs to be on (weekdays
+    9-17 is 40, weekdays 7-19 is 60, around the clock is 168). Returns the monthly $ AND kg CO2 saved
+    by switching it off the rest of the time. Lead with the dollar number. Only for on-demand capacity
+    that tolerates being off (dev, test, staging, demo, batch); reserved instances and savings plans
+    are paid for regardless. Directional, compute only."""
+    if not 0 < hours_per_week_on <= 168:
+        return {"provider": provider, "region": region,
+                "error": "hours_per_week_on must be between 0 and 168 (there are 168 hours in a week)."}
+    advice = await offhours_service.offhours_check(
+        _repo, provider, region, vcpu, ram_gb, hours_per_week_on,  # type: ignore[arg-type]
+    )
+    return with_hint(advice.model_dump())
+
+
+@mcp.tool(annotations=LOCAL_TOOL)
+def greenest_regions_on_average(
+    month: Optional[int] = None,
+    whole_year: bool = False,
+    providers: Optional[list[str]] = None,
+    regions: Optional[list[str]] = None,
+    top_n: Optional[int] = None,
+) -> dict:
+    """Which regions are normally the cleanest in a given month (default: the current one), or over
+    the whole year? Ranks regions by their TYPICAL average grid carbon, built from a year of real
+    hourly data, with each region's cleanest and dirtiest month. Use it to pick a region on a monthly
+    norm rather than a single hour; use region_carbon_now for what the grid is doing today. Carbon only
+    (no cost or latency; compare_regions_tri_axis weighs all three). Offline, needs no keys. Regions
+    labelled annual_average have only a yearly national figure and are not month-specific."""
+    return typical_ranking_service.rank_regions(
+        month=month, whole_year=whole_year, providers=providers, regions=regions, top_n=top_n,
+    )
+
+
 @mcp.tool(annotations=LIVE_DATA_TOOL)
 async def carbon_metric_scaffold(
     language: str = "python",
@@ -314,7 +358,9 @@ async def data_locality_egress_check(
     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."""
+    before accepting a greener-region suggestion when your data stays put. Use the user's real GB and
+    data location; if unknown, ask rather than assume. If verdict_status is 'not_evaluated' there is NO
+    answer yet to 'does it backfire?': say so, and get carbon_saving_kg_co2_from_move first."""
     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,

{greenpick-0.4.2 → greenpick-0.5.1}/src/greenpick/services/locality_service.py

@@ -109,7 +109,9 @@ async def data_locality_check(
 
     # Net verdict only if the caller told us what the move saves.
     verdict = None
+    verdict_status = "not_evaluated"
     if carbon_saving_kg_co2_from_move is not None:
+        verdict_status = "evaluated"
         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 "
@@ -130,9 +132,10 @@ async def data_locality_check(
                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 verdict is None:
-        # Point the caller at the optional input that turns this into a net win/backfire verdict.
-        warning += (" For a net verdict, pass carbon_saving_kg_co2_from_move (the kg CO2/mo the move "
-                    "saves, e.g. the difference between estimate_workload_carbon in the two regions).")
+        # Say up front that the question 'does it backfire?' is NOT answered yet, and what is missing.
+        warning = ("NO NET VERDICT: you did not pass carbon_saving_kg_co2_from_move, so this does NOT say "
+                   "whether the move backfires on carbon. Ask the user for it, or compute it as the difference "
+                   "between estimate_workload_carbon in the two regions, and call again. " + warning)
 
     if severity == "high":
         rec = ("High exposure. Co-locate compute with the data, or move the data to the greener "
@@ -160,6 +163,6 @@ async def data_locality_check(
         est_monthly_transfer_kg_co2=transfer_kg,
         transfer_carbon_source=reading.source, transfer_carbon_quality=reading.quality,
         carbon_saving_kg_co2_from_move=carbon_saving_kg_co2_from_move,
-        net_carbon_verdict=verdict, residency_note=residency_note,
+        net_carbon_verdict=verdict, verdict_status=verdict_status, residency_note=residency_note,
         warning=warning, recommendation=rec, limitations=LIMITATIONS,
     )

greenpick-0.5.1/src/greenpick/services/offhours_service.py

@@ -0,0 +1,82 @@
+"""Off-hours scheduling: "this doesn't need to run 24/7."
+
+Dev, test, staging, demo and batch environments are often left running all night and all weekend.
+Switching them off when nobody uses them is the other FinOps basic next to right-sizing, and it has
+the same dual benefit: cost and carbon both scale with running hours, so every hour you don't run
+saves both, with no tradeoff in the hours you do.
+
+Design-time and directional. It reuses GreenPick's cost table and power model unchanged: the only
+new input is how many hours a week the environment actually needs to be on.
+"""
+from __future__ import annotations
+
+from ..data.repository import CarbonRepository
+from ..models import OffHoursAdvice, Provider, Workload
+from . import carbon_service, cost_service
+
+HOURS_PER_WEEK_ALWAYS_ON = 168
+HOURS_PER_MONTH_ALWAYS_ON = 730                         # GreenPick's always-on baseline
+WEEKS_PER_MONTH = HOURS_PER_MONTH_ALWAYS_ON / HOURS_PER_WEEK_ALWAYS_ON   # ~4.345
+_MIN_SAVING_PCT = 10.0                                  # below this, not worth the machinery
+
+
+async def offhours_check(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    hours_per_week_on: float,
+) -> OffHoursAdvice:
+    scheduled_hours = round(min(HOURS_PER_MONTH_ALWAYS_ON, hours_per_week_on * WEEKS_PER_MONTH), 1)
+    now_wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=HOURS_PER_MONTH_ALWAYS_ON)
+    sched_wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=scheduled_hours)
+
+    reading = await carbon_service.carbon_now(repo, provider, region)
+    cost_now = cost_service.estimate_monthly_cost_usd(provider, now_wl)
+    cost_s = cost_service.estimate_monthly_cost_usd(provider, sched_wl)
+    carbon_now = carbon_service.estimate_kg_co2_per_month(now_wl, reading)
+    carbon_s = carbon_service.estimate_kg_co2_per_month(sched_wl, reading)
+
+    usd_saving = round(cost_now - cost_s, 2) if cost_now is not None and cost_s is not None else None
+    cost_pct = round((cost_now - cost_s) / cost_now * 100, 1) if cost_now and cost_s is not None else None
+    kg_saving = round(carbon_now - carbon_s, 2)
+    carbon_pct = round((carbon_now - carbon_s) / carbon_now * 100, 1) if carbon_now > 0 else None
+    on_share = round(scheduled_hours / HOURS_PER_MONTH_ALWAYS_ON * 100, 1)
+    worthwhile = bool(carbon_pct is not None and carbon_pct >= _MIN_SAVING_PCT)
+
+    if worthwhile:
+        usd_txt = f"~${usd_saving:,.0f}/mo" if usd_saving is not None else "a lower bill"
+        rationale = (
+            f"Running ~{hours_per_week_on:g} h a week instead of around the clock (168 h) means it is on "
+            f"{on_share:.0f}% of the time: ~{cost_pct:.0f}% cheaper ({usd_txt} saved) AND "
+            f"~{carbon_pct:.0f}% less carbon (~{kg_saving:.1f} kg CO2/mo, {reading.quality} grid data). "
+            f"Same hours of use, nothing running when nobody is there. Only worth it for an "
+            f"environment that can be off, and you need something to stop and start it on schedule.")
+    else:
+        rationale = (
+            f"At ~{hours_per_week_on:g} h a week it is already on {on_share:.0f}% of the time, so "
+            f"switching it off outside those hours would save under {_MIN_SAVING_PCT:.0f}% — not worth "
+            f"building a scheduler for. Look to right-sizing or region choice instead.")
+
+    return OffHoursAdvice(
+        provider=provider, region=region, vcpu=vcpu, ram_gb=ram_gb,
+        hours_per_week_on=hours_per_week_on,
+        hours_per_month_now=HOURS_PER_MONTH_ALWAYS_ON, hours_per_month_scheduled=scheduled_hours,
+        on_share_pct=on_share,
+        cost_now_usd_per_month=cost_now, cost_scheduled_usd_per_month=cost_s,
+        monthly_usd_saving=usd_saving, cost_saving_pct=cost_pct,
+        carbon_now_kg_per_month=carbon_now, carbon_scheduled_kg_per_month=carbon_s,
+        monthly_kg_co2_saving=kg_saving, carbon_saving_pct=carbon_pct,
+        is_worthwhile=worthwhile,
+        carbon_source=reading.source, carbon_quality=reading.quality,
+        rationale=rationale,
+        limitations=(
+            "Directional, compute only. A stopped instance still costs for its attached disks, IP "
+            "addresses and snapshots, so the real bill falls a little less than shown. Reserved "
+            "instances and savings plans are paid for whether the instance runs or not, so they cancel "
+            "the saving: this applies to on-demand capacity. Assumes the instance works as hard when it "
+            "is on, and that start-up time and data warm-up are acceptable. Carbon uses today's grid "
+            "intensity; the hours you actually run may be cleaner or dirtier (see cleanest_time_of_day). "
+            "Hours per week: weekdays 9-17 is 40, weekdays 7-19 is 60, around the clock is 168."),
+    )

greenpick-0.5.1/src/greenpick/services/typical_ranking_service.py

@@ -0,0 +1,106 @@
+"""Which regions are greenest ON AVERAGE for a month (or the whole year)?
+
+Answers the "across a whole month, which region is greenest on average?" question from the data
+GreenPick already bundles: typical.json (12 months of real hourly EIA / ENTSO-E / Hydro-Québec /
+IESO data, averaged per calendar month) and annual.json (a sourced yearly national figure, for
+regions with no free hourly data).
+
+Pure and offline: no network, no keys. Because it is built from LAST year's data it describes what
+is typical for the time of year, not what the grid is doing today (use region_carbon_now or
+compare_regions_tri_axis for that).
+"""
+from __future__ import annotations
+
+import calendar
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..data.static_data import iter_regions
+from ..data.typical_repository import annual_entry, typical_entry
+
+LIMITATIONS = (
+    "Typical figures are built from the last 12 months of real hourly grid data, averaged per "
+    "calendar month. They describe what is normal for the time of year, not today's grid, and "
+    "a given year can differ (wind, hydro, outages). Regions marked annual_average have only a "
+    "yearly national figure, so they are not month-specific: compare them with the monthly "
+    "figures with care. Carbon only; this ranking ignores cost and latency (use "
+    "compare_regions_tri_axis for the three together). Directional, not audited."
+)
+
+
+def _month_name(m: int) -> str:
+    return calendar.month_name[m]
+
+
+def rank_regions(
+    month: Optional[int] = None,
+    whole_year: bool = False,
+    providers: Optional[list[str]] = None,
+    regions: Optional[list[str]] = None,
+    top_n: Optional[int] = None,
+) -> dict:
+    now_month = datetime.now(timezone.utc).month
+    m = month or now_month
+    if not whole_year and not 1 <= m <= 12:
+        return {"error": f"month must be 1-12, got {month}.", "ranking": []}
+
+    rows = []
+    for prov, reg, meta in iter_regions():
+        if providers and prov not in providers:
+            continue
+        if regions and reg not in regions:
+            continue
+        entry = typical_entry(prov, reg)
+        if entry and entry.get("months"):
+            months = {int(k): v for k, v in entry["months"].items()}
+            if whole_year:
+                hours = sum(v["hours"] for v in months.values())
+                value = sum(v["avg_g_co2_per_kwh"] * v["hours"] for v in months.values()) / hours
+            elif m in months:
+                value = months[m]["avg_g_co2_per_kwh"]
+            else:
+                continue
+            avgs = {k: v["avg_g_co2_per_kwh"] for k, v in months.items()}
+            best, worst = min(avgs, key=avgs.get), max(avgs, key=avgs.get)
+            rows.append({
+                "provider": prov, "region": reg, "name": meta.get("name"),
+                "g_co2_per_kwh": round(value, 1), "quality": "typical",
+                "source": entry["source"], "data_from": entry["from"][:7], "data_to": entry["to"][:7],
+                "year_low_g_co2_per_kwh": avgs[best], "year_high_g_co2_per_kwh": avgs[worst],
+                "cleanest_month": _month_name(best), "dirtiest_month": _month_name(worst),
+            })
+            continue
+        yearly = annual_entry(prov, reg)
+        if yearly:
+            rows.append({
+                "provider": prov, "region": reg, "name": meta.get("name"),
+                "g_co2_per_kwh": yearly["g_co2_per_kwh"], "quality": "annual_average",
+                "source": "ember_annual", "data_from": str(yearly["year"]), "data_to": str(yearly["year"]),
+                "year_low_g_co2_per_kwh": None, "year_high_g_co2_per_kwh": None,
+                "cleanest_month": None, "dirtiest_month": None,
+            })
+
+    if not rows:
+        return {"error": "No regions matched.", "ranking": []}
+
+    rows.sort(key=lambda r: r["g_co2_per_kwh"])
+    worst = rows[-1]["g_co2_per_kwh"]
+    for i, r in enumerate(rows, 1):
+        r["rank"] = i
+        r["vs_dirtiest_pct"] = round((r["g_co2_per_kwh"] - worst) / worst * 100, 1) if worst else None
+    shown = rows[:top_n] if top_n else rows
+
+    period = "the whole year" if whole_year else _month_name(m)
+    best_r, worst_r = rows[0], rows[-1]
+    ratio = worst_r["g_co2_per_kwh"] / best_r["g_co2_per_kwh"] if best_r["g_co2_per_kwh"] else None
+    spread = f" (~{ratio:.0f}x apart)" if ratio and ratio >= 2 else ""
+    rationale = (
+        f"On a typical {period if whole_year else period + ' day'}, the greenest of {len(rows)} regions is "
+        f"{best_r['provider']}/{best_r['region']} at ~{best_r['g_co2_per_kwh']:.0f} gCO2/kWh and the "
+        f"dirtiest is {worst_r['provider']}/{worst_r['region']} at ~{worst_r['g_co2_per_kwh']:.0f}"
+        f"{spread}. Built from last year's real data, so it shows what is normal for the time of "
+        f"year, not what the grid is doing right now.")
+    return {
+        "period": period, "regions_ranked": len(rows), "ranking": shown,
+        "rationale": rationale, "limitations": LIMITATIONS,
+    }

{greenpick-0.4.2 → greenpick-0.5.1/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.4.2
+Version: 0.5.1
 Summary: Design-time sustainability co-pilot (MCP server): greener, cheaper cloud infrastructure decisions with carbon + cost + latency tradeoffs.
 Author-email: "Data Science Advisers, LLC" <info@datascienceadvisers.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-15-0ea5e9" alt="MCP tools: 15" />
+  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -52,7 +52,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 15 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -143,7 +143,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-15 tools, grouped by what you're trying to do.
+17 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -159,6 +159,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `cleanest_hours_to_run` | Cleanest recent hours to time a deferrable job (ETL, backups, training), + % reduction. Pass `window_hours` for a job of known duration → cleanest contiguous window to start at. |
 | `cleanest_time_of_day` | For a **recurring** job (nightly batch): the region's cleanest time of day, averaged across recent days. A daily pattern, not a 7-day weekly one. |
+| `greenest_regions_on_average` | Which regions are cleanest on a **typical** day in a given month (or the whole year), ranked from last year's real data. Offline, no keys; a planning view, not today's grid. |
 | `carbon_forecast` | Forward-looking: which **upcoming** hours will be cleanest, from the EU day-ahead wind+solar forecast (ENTSO-E). Relative ranking; US/uncovered zones degrade to the recent historical pattern. |
 
 ### Estimate a workload's carbon
@@ -175,6 +176,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `greener_instance_family` | A greener same-size family in the same region via perf-per-watt (newer generation / ARM Graviton-class does the same work on less energy). |
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
+| `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 

{greenpick-0.4.2 → greenpick-0.5.1}/src/greenpick.egg-info/SOURCES.txt

@@ -43,10 +43,12 @@ src/greenpick/services/instance_service.py
 src/greenpick/services/latency_service.py
 src/greenpick/services/locality_service.py
 src/greenpick/services/metric_scaffold_service.py
+src/greenpick/services/offhours_service.py
 src/greenpick/services/recommender.py
 src/greenpick/services/residency_service.py
 src/greenpick/services/rightsizing_service.py
 src/greenpick/services/scheduling_service.py
 src/greenpick/services/serving_service.py
 src/greenpick/services/training_service.py
+src/greenpick/services/typical_ranking_service.py
 tests/test_services.py