greenpick 0.3.0__tar.gz → 0.4.1__tar.gz

{greenpick-0.3.0/src/greenpick.egg-info → greenpick-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.3.0
+Version: 0.4.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
@@ -60,11 +60,12 @@ seconds. (It responds when you ask; auto-nudging on infra-code changes is on the
 > this month's average for each grid, from a year of real data.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~30× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
+  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~28× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
 </p>
 
-*The same 40-GPU-hour training run emits ~0.7 kg CO₂ in Stockholm vs ~19 kg in Sydney — a ~30×
-difference from region choice alone. Ask GreenPick and it surfaces that (with the cost and latency
+*The same 40-GPU-hour training run emits ~0.6 kg CO₂ in Stockholm vs ~17.5 kg in Sydney — a ~28×
+difference from region choice alone (typical October grids; Sydney on Ember's 2025 national figure,
+a lower bound for its coal-heavier state grid). Ask GreenPick and it surfaces that (with the cost and latency
 tradeoff) while you're still in the editor, before you commit.*
 
 **▶ [See the 5-minute demo](docs/demo.md)** — three scenarios with real tool output (training placement, the egress backfire, the forecast).
@@ -124,7 +125,7 @@ backfire guards** — is the part nothing else puts together.
 
 ## Scope
 
-- Providers: **AWS, GCP, Azure** regions.
+- Providers: **AWS, GCP, Azure** — 25 regions across the US, Europe, Canada, Asia and Australia.
 - Workloads: long-running **web/API services**, **GPU training** runs, and **deferrable jobs**
   (ETL / batch / backups) — placement and timing for each.
 - Carbon = **grid carbon intensity by region** (directional, point-in-time; live US + EU), plus a
@@ -195,8 +196,12 @@ See `docs/user-questions-backlog.md`.
   intensity and average hour-of-day profile (UTC), computed from 12 months of real hourly EIA-930 /
   ENTSO-E data (`data/typical.json`, refreshed by `scripts/refresh_typical.py`). Labelled
   `quality: "typical"` — a realistic norm, never presented as a current reading.
-- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, used only for regions no free
-  source covers (e.g. Sydney).
+- **Annual** — for Singapore, Tokyo, Mumbai/Pune and Sydney, where no free hourly data exists: the country's
+  yearly lifecycle grid intensity from [Ember](https://ember-energy.org/) (via Our World in Data,
+  CC BY 4.0), with source and year (`data/annual.json`). Labelled `quality: "annual_average"`; fine for
+  comparing regions, but carries no timing signal.
+- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, kept only as a last resort if
+  every other source is missing. No catalog region relies on it.
 - Cost: a **dated static pricing table** (`data/pricing.json`), refreshed from live Vantage
   pricing via `scripts/refresh_pricing.py` using one matched method across all three clouds.
 - Instance-family efficiency: directional perf-per-watt multipliers (`data/instance_families.json`).
@@ -300,8 +305,9 @@ Top-level `await` works in Jupyter. In a plain script, put the `with` block insi
 and run it with `asyncio.run(...)`.
 
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
-this month's average from last year's real data, and `mock` means a hand-set value for a region
-with no real data. Check it to confirm live data is on. A result that isn't live also includes a
+this month's average from last year's real data, `annual_average` means a sourced yearly national
+figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm
+live data is on. A result that isn't live also includes a
 `live_data_hint` saying why (no key set, the source didn't respond, or no free source covers that
 region) and what to do about it.
 
@@ -313,7 +319,7 @@ carbon, set two free keys (`EIA_API_KEY` for US, `ENTSOE_TOKEN` for EU) and
 `GREENPICK_CARBON_SOURCE=auto` — see [Turn on live data](#turn-on-live-data).
 
 **Why "directional" and not audited numbers?** Because it's for a *design-time decision*, not a
-compliance report. "Stockholm is ~30× cleaner than Sydney" is what you need to pick a region in
+compliance report. "Stockholm is ~28× cleaner than Sydney" is what you need to pick a region in
 seconds — a certified figure is a different job for a different tool (Electricity Maps, WattTime).
 GreenPick is for *decisions*, not *disclosures*, and says so in every tool's limitations.
 

{greenpick-0.3.0 → greenpick-0.4.1}/README.md

@@ -30,11 +30,12 @@ seconds. (It responds when you ask; auto-nudging on infra-code changes is on the
 > this month's average for each grid, from a year of real data.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~30× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
+  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~28× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
 </p>
 
-*The same 40-GPU-hour training run emits ~0.7 kg CO₂ in Stockholm vs ~19 kg in Sydney — a ~30×
-difference from region choice alone. Ask GreenPick and it surfaces that (with the cost and latency
+*The same 40-GPU-hour training run emits ~0.6 kg CO₂ in Stockholm vs ~17.5 kg in Sydney — a ~28×
+difference from region choice alone (typical October grids; Sydney on Ember's 2025 national figure,
+a lower bound for its coal-heavier state grid). Ask GreenPick and it surfaces that (with the cost and latency
 tradeoff) while you're still in the editor, before you commit.*
 
 **▶ [See the 5-minute demo](docs/demo.md)** — three scenarios with real tool output (training placement, the egress backfire, the forecast).
@@ -94,7 +95,7 @@ backfire guards** — is the part nothing else puts together.
 
 ## Scope
 
-- Providers: **AWS, GCP, Azure** regions.
+- Providers: **AWS, GCP, Azure** — 25 regions across the US, Europe, Canada, Asia and Australia.
 - Workloads: long-running **web/API services**, **GPU training** runs, and **deferrable jobs**
   (ETL / batch / backups) — placement and timing for each.
 - Carbon = **grid carbon intensity by region** (directional, point-in-time; live US + EU), plus a
@@ -165,8 +166,12 @@ See `docs/user-questions-backlog.md`.
   intensity and average hour-of-day profile (UTC), computed from 12 months of real hourly EIA-930 /
   ENTSO-E data (`data/typical.json`, refreshed by `scripts/refresh_typical.py`). Labelled
   `quality: "typical"` — a realistic norm, never presented as a current reading.
-- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, used only for regions no free
-  source covers (e.g. Sydney).
+- **Annual** — for Singapore, Tokyo, Mumbai/Pune and Sydney, where no free hourly data exists: the country's
+  yearly lifecycle grid intensity from [Ember](https://ember-energy.org/) (via Our World in Data,
+  CC BY 4.0), with source and year (`data/annual.json`). Labelled `quality: "annual_average"`; fine for
+  comparing regions, but carries no timing signal.
+- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, kept only as a last resort if
+  every other source is missing. No catalog region relies on it.
 - Cost: a **dated static pricing table** (`data/pricing.json`), refreshed from live Vantage
   pricing via `scripts/refresh_pricing.py` using one matched method across all three clouds.
 - Instance-family efficiency: directional perf-per-watt multipliers (`data/instance_families.json`).
@@ -270,8 +275,9 @@ Top-level `await` works in Jupyter. In a plain script, put the `with` block insi
 and run it with `asyncio.run(...)`.
 
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
-this month's average from last year's real data, and `mock` means a hand-set value for a region
-with no real data. Check it to confirm live data is on. A result that isn't live also includes a
+this month's average from last year's real data, `annual_average` means a sourced yearly national
+figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm
+live data is on. A result that isn't live also includes a
 `live_data_hint` saying why (no key set, the source didn't respond, or no free source covers that
 region) and what to do about it.
 
@@ -283,7 +289,7 @@ carbon, set two free keys (`EIA_API_KEY` for US, `ENTSOE_TOKEN` for EU) and
 `GREENPICK_CARBON_SOURCE=auto` — see [Turn on live data](#turn-on-live-data).
 
 **Why "directional" and not audited numbers?** Because it's for a *design-time decision*, not a
-compliance report. "Stockholm is ~30× cleaner than Sydney" is what you need to pick a region in
+compliance report. "Stockholm is ~28× cleaner than Sydney" is what you need to pick a region in
 seconds — a certified figure is a different job for a different tool (Electricity Maps, WattTime).
 GreenPick is for *decisions*, not *disclosures*, and says so in every tool's limitations.
 

{greenpick-0.3.0 → greenpick-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.3.0"
+version = "0.4.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.3.0 → greenpick-0.4.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.3.0"
+__version__ = "0.4.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.1/src/greenpick/data/annual.json

@@ -0,0 +1,15 @@
+{
+ "_comment": "Yearly average grid carbon intensity for regions with no free hourly data source. Lifecycle gCO2e/kWh (full lifecycle incl. upstream methane), the same basis as GreenPick's per-fuel factors, so these compare fairly with live/typical regions. National figures: no hourly or sub-national lifecycle data is freely available for these grids. Used with quality='annual_average'; no hourly profile, so no timing advice.",
+ "_source": "Ember yearly electricity data (lifecycle CO2 intensity of electricity generation), via Our World in Data grapher 'carbon-intensity-electricity'. CC BY 4.0.",
+ "_as_of": "2026-10-27",
+ "zones": {
+  "SG": { "country": "Singapore", "g_co2_per_kwh": 497.1, "year": 2025,
+          "note": "About 95% natural gas; a yearly figure is a fair description of this steady grid." },
+  "JP": { "country": "Japan", "g_co2_per_kwh": 477.3, "year": 2025,
+          "note": "National average; the Tokyo (TEPCO) area mix differs somewhat and varies by hour." },
+  "IN": { "country": "India", "g_co2_per_kwh": 670.1, "year": 2025,
+          "note": "National average; Maharashtra (Mumbai, Pune) runs about 6% above it on Ember's state-level data." },
+  "AU": { "country": "Australia", "g_co2_per_kwh": 525.2, "year": 2025,
+          "note": "National average; New South Wales (Sydney) is more coal-heavy and runs higher, so treat this as a lower bound for Sydney." }
+ }
+}

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/data/regions.json

@@ -6,21 +6,30 @@
     "us-west-2":      { "name": "Oregon",        "lat": 45.87, "lon": -119.69, "zone": "US-NW-PACW", "eia_ba": "BPAT", "jurisdiction": "US" },
     "eu-west-1":      { "name": "Ireland",       "lat": 53.41, "lon": -8.24,  "zone": "IE", "entsoe_eic": "10Y1001A1001A59C", "jurisdiction": "EEA" },
     "eu-north-1":     { "name": "Stockholm",     "lat": 59.33, "lon": 18.07,  "zone": "SE", "entsoe_eic": "10YSE-1--------K", "jurisdiction": "EEA" },
-    "ap-southeast-2": { "name": "Sydney",        "lat": -33.87, "lon": 151.21, "zone": "AU-NSW", "jurisdiction": "AU" },
-    "ca-central-1":   { "name": "Montreal",      "lat": 45.50, "lon": -73.57, "zone": "CA-QC", "ca_source": "hq", "jurisdiction": "CA" }
+    "ap-southeast-2": { "name": "Sydney",        "lat": -33.87, "lon": 151.21, "zone": "AU-NSW", "annual_zone": "AU", "jurisdiction": "AU" },
+    "ca-central-1":   { "name": "Montreal",      "lat": 45.50, "lon": -73.57, "zone": "CA-QC", "ca_source": "hq", "jurisdiction": "CA" },
+    "ap-southeast-1": { "name": "Singapore",     "lat": 1.29,  "lon": 103.85, "zone": "SG", "annual_zone": "SG", "jurisdiction": "SG" },
+    "ap-northeast-1": { "name": "Tokyo",         "lat": 35.68, "lon": 139.69, "zone": "JP-TK", "annual_zone": "JP", "jurisdiction": "JP" },
+    "ap-south-1":     { "name": "Mumbai",        "lat": 19.08, "lon": 72.88,  "zone": "IN-WE", "annual_zone": "IN", "jurisdiction": "IN" }
   },
   "gcp": {
     "us-central1":    { "name": "Iowa",          "lat": 41.26, "lon": -95.86, "zone": "US-MIDW-MISO", "eia_ba": "MISO", "jurisdiction": "US" },
     "europe-north1":  { "name": "Finland",       "lat": 60.57, "lon": 27.19,  "zone": "FI", "entsoe_eic": "10YFI-1--------U", "jurisdiction": "EEA" },
     "us-west1":       { "name": "Oregon",        "lat": 45.60, "lon": -121.18, "zone": "US-NW-PACW", "eia_ba": "BPAT", "jurisdiction": "US" },
     "northamerica-northeast1": { "name": "Montreal", "lat": 45.50, "lon": -73.57, "zone": "CA-QC", "ca_source": "hq", "jurisdiction": "CA" },
-    "northamerica-northeast2": { "name": "Toronto",  "lat": 43.65, "lon": -79.38, "zone": "CA-ON", "ca_source": "ieso", "jurisdiction": "CA" }
+    "northamerica-northeast2": { "name": "Toronto",  "lat": 43.65, "lon": -79.38, "zone": "CA-ON", "ca_source": "ieso", "jurisdiction": "CA" },
+    "asia-southeast1": { "name": "Singapore",    "lat": 1.35,  "lon": 103.70, "zone": "SG", "annual_zone": "SG", "jurisdiction": "SG" },
+    "asia-northeast1": { "name": "Tokyo",        "lat": 35.68, "lon": 139.69, "zone": "JP-TK", "annual_zone": "JP", "jurisdiction": "JP" },
+    "asia-south1":     { "name": "Mumbai",       "lat": 19.08, "lon": 72.88,  "zone": "IN-WE", "annual_zone": "IN", "jurisdiction": "IN" }
   },
   "azure": {
     "eastus":         { "name": "Virginia",      "lat": 37.37, "lon": -79.82, "zone": "US-MIDA-PJM", "eia_ba": "PJM", "jurisdiction": "US" },
     "northeurope":    { "name": "Ireland",       "lat": 53.35, "lon": -6.26,  "zone": "IE", "entsoe_eic": "10Y1001A1001A59C", "jurisdiction": "EEA" },
     "swedencentral":  { "name": "Sweden",        "lat": 60.67, "lon": 17.14,  "zone": "SE", "entsoe_eic": "10YSE-1--------K", "jurisdiction": "EEA" },
     "canadaeast":     { "name": "Quebec City",   "lat": 46.81, "lon": -71.21, "zone": "CA-QC", "ca_source": "hq", "jurisdiction": "CA" },
-    "canadacentral":  { "name": "Toronto",       "lat": 43.65, "lon": -79.38, "zone": "CA-ON", "ca_source": "ieso", "jurisdiction": "CA" }
+    "canadacentral":  { "name": "Toronto",       "lat": 43.65, "lon": -79.38, "zone": "CA-ON", "ca_source": "ieso", "jurisdiction": "CA" },
+    "southeastasia":  { "name": "Singapore",     "lat": 1.28,  "lon": 103.83, "zone": "SG", "annual_zone": "SG", "jurisdiction": "SG" },
+    "japaneast":      { "name": "Tokyo",         "lat": 35.68, "lon": 139.77, "zone": "JP-TK", "annual_zone": "JP", "jurisdiction": "JP" },
+    "centralindia":   { "name": "Pune",          "lat": 18.52, "lon": 73.86,  "zone": "IN-WE", "annual_zone": "IN", "jurisdiction": "IN" }
   }
 }

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/data/static_data.py

@@ -76,6 +76,15 @@ def typical() -> dict:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+@lru_cache(maxsize=1)
+def annual() -> dict:
+    """Yearly average intensity for regions with no free hourly source (lifecycle, sourced)."""
+    path = _DATA_DIR / "annual.json"
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
 @lru_cache(maxsize=1)
 def gpu_power() -> dict:
     """Directional GPU/accelerator power model (TDP + utilization + host overhead) for training."""

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/data/typical_repository.py

@@ -77,6 +77,13 @@ def typical_context(provider: str, region: str, g_co2_per_kwh: float, timestamp:
     }
 
 
+def annual_entry(provider: str, region: str) -> Optional[dict]:
+    """The annual.json zone for a region with no free hourly source (country, g, year), or None."""
+    from .static_data import annual, region_meta
+    zone = (region_meta(provider, region) or {}).get("annual_zone")  # type: ignore[arg-type]
+    return annual().get("zones", {}).get(zone) if zone else None
+
+
 class TypicalCarbonRepository:
     def __init__(self) -> None:
         self._mock = MockCarbonRepository()
@@ -85,6 +92,11 @@ class TypicalCarbonRepository:
         entry = typical_entry(provider, region)
         month = _month(entry) if entry else None
         if not month:
+            yearly = annual_entry(provider, region)
+            if yearly:
+                return CarbonReading(region=region, provider=provider,
+                                     g_co2_per_kwh=yearly["g_co2_per_kwh"], source="ember_annual",
+                                     timestamp=str(yearly["year"]), quality="annual_average")
             return await self._mock.carbon_now(provider, region)
         return CarbonReading(
             region=region,
@@ -101,6 +113,8 @@ class TypicalCarbonRepository:
         entry = typical_entry(provider, region)
         month = _month(entry) if entry else None
         if not month:
+            if annual_entry(provider, region):
+                return []        # a yearly figure has no hourly shape — don't invent one
             return await self._mock.carbon_history(provider, region)
         return [HourlyCarbon(period=f"H{h:02d}Z", g_co2_per_kwh=g)
                 for h, g in enumerate(month["hourly_utc"]) if g is not None]

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/server.py

@@ -381,6 +381,6 @@ def explain_methodology_and_limits() -> dict:
         "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.",
-        "fallback_data": "Used when live data isn't available (no key, the source didn't respond, or GreenPick isn't set to live). 'typical' = this calendar month's average intensity and average hour-of-day profile (UTC) for the region, computed from 12 months of real hourly EIA-930 / ENTSO-E data with GreenPick's own emission factors (bundled typical.json, refreshed by scripts/refresh_typical.py) — a realistic norm, not a current reading. 'mock' = a hand-set illustrative value with a synthetic hourly pattern, used only for regions with no free data source (e.g. Sydney); timing advice on mock isn't meaningful. Both carry a live_data_hint saying why the result isn't live and how to turn live data on.",
+        "fallback_data": "Used when live data isn't available (no key, the source didn't respond, or GreenPick isn't set to live). 'typical' = this calendar month's average intensity and average hour-of-day profile (UTC) for the region, computed from 12 months of real hourly EIA-930 / ENTSO-E data with GreenPick's own emission factors (bundled typical.json, refreshed by scripts/refresh_typical.py) — a realistic norm, not a current reading. 'annual_average' = the country's yearly lifecycle grid intensity from Ember (via Our World in Data; bundled annual.json with source and year), for regions with no free hourly data (Singapore, Tokyo, Mumbai/Pune, Sydney — national figures, so Sydney's is a lower bound for its coal-heavier state) — sound for comparing regions, no timing signal (no hourly profile). 'mock' = a hand-set illustrative value with a synthetic hourly pattern, a last resort no catalog region relies on; timing advice on mock isn't meaningful. Both carry a live_data_hint saying why the result isn't live and how to turn live data on.",
         "data_sources": "GREENPICK_CARBON_SOURCE=auto routes US regions to EIA-930 and EU regions to ENTSO-E (both free, key needed), and Canadian regions to Hydro-Québec (Québec) and IESO (Ontario) open data (free, no key). All mixes are weighted with the same per-fuel factors. Without live data a region uses its clearly-labelled typical value (or mock where no free source exists). Electricity Maps is available when selected explicitly (GREENPICK_CARBON_SOURCE=electricitymaps).",
     }

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/services/data_hint.py

@@ -53,13 +53,13 @@ def _walk(obj: Any) -> Iterator[dict]:
             yield from _walk(v)
 
 
-_FALLBACK = ("typical", "mock")
+_FALLBACK = ("typical", "annual_average", "mock")
 
 
 def _scan(result: dict) -> tuple[dict[str, set[tuple[str, str]]], bool, set[str]]:
     """For each fallback kind ('typical' / 'mock'): the regions whose figures use it; whether any
     such figure had no locatable region; and which kinds fed timing advice."""
-    regions: dict[str, set[tuple[str, str]]] = {k: set() for k in _FALLBACK}
+    regions: dict[str, set[tuple[str, str]]] = {k: set() for k in _FALLBACK}  # noqa: C420
     unlocated = False
     timing: set[str] = set()
     for d in _walk(result):
@@ -117,15 +117,26 @@ def _typical_sentence(locs: set[tuple[str, str]]) -> str:
             f"real hourly data{span} — a realistic norm, not a current reading.")
 
 
+def _annual_sentence(locs: set[tuple[str, str]]) -> str:
+    from ..data.typical_repository import annual_entry
+    found = sorted({(e["country"], e["year"]) for e in (annual_entry(p, r) for p, r in locs) if e})
+    which = ", ".join(f"{c} {y}" for c, y in found)
+    return (f"Annual figures here ({_names(list(locs))}) are the country's yearly average grid intensity "
+            f"(Ember, lifecycle basis{': ' + which if which else ''}) — no free hourly data exists for "
+            "these grids, so they're a sound basis for comparing regions but carry no timing signal.")
+
+
 def build_hint(result: dict) -> Optional[str]:
     by_kind, unlocated, timing = _scan(result)
-    all_locs = by_kind["typical"] | by_kind["mock"]
+    all_locs = by_kind["typical"] | by_kind["annual_average"] | by_kind["mock"]
     if not all_locs and not unlocated:
         return None
 
     parts = []
     if by_kind["typical"]:
         parts.append(_typical_sentence(by_kind["typical"]))
+    if by_kind["annual_average"]:
+        parts.append(_annual_sentence(by_kind["annual_average"]))
     if by_kind["mock"] or (unlocated and not by_kind["typical"]):
         where = f" for {_names(list(by_kind['mock']))}" if by_kind["mock"] else ""
         parts.append(f"Mock figures{where} are a hand-set illustrative value for the grid, used where "
@@ -155,6 +166,8 @@ def build_hint(result: dict) -> Optional[str]:
                          f"{_names(locs) or 'this region'}. Use GREENPICK_CARBON_SOURCE=auto to route "
                          "each region to its own live source.")
         elif reason == "uncovered":
+            if all(loc in by_kind["annual_average"] for loc in locs):
+                continue        # already explained by the annual sentence; no action to suggest
             parts.append(f"No free live source covers {_names(locs)} yet, so GreenPick uses its "
                          "fallback there.")
     if "typical" in timing:

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/services/forecast_service.py

@@ -67,6 +67,10 @@ async def carbon_forecast(
         if pattern.cleanest_hour_of_day is not None:
             note += (f"A typical day here is cleanest around {pattern.cleanest_hour_of_day:02d}:00 "
                      f"UTC - a reasonable default for a recurring job.")
+    elif pattern.quality == "annual_average":
+        source, quality = "ember_annual", "annual_average"
+        note = ("No day-ahead forecast or hourly data exists for this region — only a yearly "
+                "average — so GreenPick can't say which hours are cleaner here.")
     elif pattern.quality == "mock":
         # No live history either: the "pattern" is GreenPick's illustrative mock curve. Label it
         # mock — calling it 'historical' would pass a synthetic shape off as real past data.

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/services/recommender.py

@@ -146,7 +146,7 @@ async def compare_regions(
         if greener_improvement < MEANINGFUL_PCT:
             rationale = (
                 f"Staying on {baseline.provider}/{baseline.region} is reasonable — no candidate "
-                f"region is meaningfully greener (all within ~{MEANINGFUL_PCT:.0f}%)."
+                f"region is meaningfully greener (none is more than ~{MEANINGFUL_PCT:.0f}% cleaner)."
             )
         else:
             extra_lat = greenest.added_latency_ms

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/services/residency_service.py

@@ -22,6 +22,9 @@ _LABEL = {
     "US": "the United States",
     "AU": "Australia",
     "CA": "Canada",
+    "SG": "Singapore",
+    "JP": "Japan",
+    "IN": "India",
 }
 
 DISCLAIMER = ("GreenPick does NOT assess legal compliance - this is a geographic heads-up only. "

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick/services/training_service.py

@@ -186,6 +186,9 @@ async def estimate_training_carbon(
                     f"deferrable, so this stacks on the region choice."
                     + scheduling_service.small_gap_note(advice.cleanest_g_co2_per_kwh or 0,
                                                         advice.dirtiest_g_co2_per_kwh or 0))
+    elif advice.hours_analyzed == 0:
+        time_txt = (" There's no hourly data for that region (only a yearly average), so GreenPick "
+                    "can't advise on timing there — the region choice is the lever.")
     else:
         time_txt = (" That region's grid is fairly flat over the window, so when you run matters "
                     "little there — the region choice is the lever.")

{greenpick-0.3.0 → greenpick-0.4.1/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.3.0
+Version: 0.4.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
@@ -60,11 +60,12 @@ seconds. (It responds when you ask; auto-nudging on infra-code changes is on the
 > this month's average for each grid, from a year of real data.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~30× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
+  <img src="https://raw.githubusercontent.com/bithug01/greenpick/master/docs/img/region-carbon-30x.svg" alt="Same H100 training run, ~28× the carbon depending only on region (Stockholm vs Sydney)" width="560" />
 </p>
 
-*The same 40-GPU-hour training run emits ~0.7 kg CO₂ in Stockholm vs ~19 kg in Sydney — a ~30×
-difference from region choice alone. Ask GreenPick and it surfaces that (with the cost and latency
+*The same 40-GPU-hour training run emits ~0.6 kg CO₂ in Stockholm vs ~17.5 kg in Sydney — a ~28×
+difference from region choice alone (typical October grids; Sydney on Ember's 2025 national figure,
+a lower bound for its coal-heavier state grid). Ask GreenPick and it surfaces that (with the cost and latency
 tradeoff) while you're still in the editor, before you commit.*
 
 **▶ [See the 5-minute demo](docs/demo.md)** — three scenarios with real tool output (training placement, the egress backfire, the forecast).
@@ -124,7 +125,7 @@ backfire guards** — is the part nothing else puts together.
 
 ## Scope
 
-- Providers: **AWS, GCP, Azure** regions.
+- Providers: **AWS, GCP, Azure** — 25 regions across the US, Europe, Canada, Asia and Australia.
 - Workloads: long-running **web/API services**, **GPU training** runs, and **deferrable jobs**
   (ETL / batch / backups) — placement and timing for each.
 - Carbon = **grid carbon intensity by region** (directional, point-in-time; live US + EU), plus a
@@ -195,8 +196,12 @@ See `docs/user-questions-backlog.md`.
   intensity and average hour-of-day profile (UTC), computed from 12 months of real hourly EIA-930 /
   ENTSO-E data (`data/typical.json`, refreshed by `scripts/refresh_typical.py`). Labelled
   `quality: "typical"` — a realistic norm, never presented as a current reading.
-- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, used only for regions no free
-  source covers (e.g. Sydney).
+- **Annual** — for Singapore, Tokyo, Mumbai/Pune and Sydney, where no free hourly data exists: the country's
+  yearly lifecycle grid intensity from [Ember](https://ember-energy.org/) (via Our World in Data,
+  CC BY 4.0), with source and year (`data/annual.json`). Labelled `quality: "annual_average"`; fine for
+  comparing regions, but carries no timing signal.
+- **Mock** — a hand-set illustrative value, labelled `quality: "mock"`, kept only as a last resort if
+  every other source is missing. No catalog region relies on it.
 - Cost: a **dated static pricing table** (`data/pricing.json`), refreshed from live Vantage
   pricing via `scripts/refresh_pricing.py` using one matched method across all three clouds.
 - Instance-family efficiency: directional perf-per-watt multipliers (`data/instance_families.json`).
@@ -300,8 +305,9 @@ Top-level `await` works in Jupyter. In a plain script, put the `with` block insi
 and run it with `asyncio.run(...)`.
 
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
-this month's average from last year's real data, and `mock` means a hand-set value for a region
-with no real data. Check it to confirm live data is on. A result that isn't live also includes a
+this month's average from last year's real data, `annual_average` means a sourced yearly national
+figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm
+live data is on. A result that isn't live also includes a
 `live_data_hint` saying why (no key set, the source didn't respond, or no free source covers that
 region) and what to do about it.
 
@@ -313,7 +319,7 @@ carbon, set two free keys (`EIA_API_KEY` for US, `ENTSOE_TOKEN` for EU) and
 `GREENPICK_CARBON_SOURCE=auto` — see [Turn on live data](#turn-on-live-data).
 
 **Why "directional" and not audited numbers?** Because it's for a *design-time decision*, not a
-compliance report. "Stockholm is ~30× cleaner than Sydney" is what you need to pick a region in
+compliance report. "Stockholm is ~28× cleaner than Sydney" is what you need to pick a region in
 seconds — a certified figure is a different job for a different tool (Electricity Maps, WattTime).
 GreenPick is for *decisions*, not *disclosures*, and says so in every tool's limitations.
 

{greenpick-0.3.0 → greenpick-0.4.1}/src/greenpick.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/greenpick.egg-info/requires.txt
 src/greenpick.egg-info/top_level.txt
 src/greenpick/data/__init__.py
 src/greenpick/data/_net.py
+src/greenpick/data/annual.json
 src/greenpick/data/auto_repository.py
 src/greenpick/data/canada_repository.py
 src/greenpick/data/eia_repository.py

{greenpick-0.3.0 → greenpick-0.4.1}/tests/test_services.py

@@ -348,10 +348,10 @@ async def test_auto_router_picks_source_by_region(monkeypatch):
     repo = AutoRepository(eia_key="k", entsoe_token="t")
     us = await repo.carbon_now("aws", "us-east-1")      # -> EIA
     eu = await repo.carbon_now("aws", "eu-north-1")     # -> ENTSO-E
-    syd = await repo.carbon_now("aws", "ap-southeast-2")  # -> mock
+    syd = await repo.carbon_now("aws", "ap-southeast-2")  # -> no live source: sourced yearly figure
     assert us.source == "eia"
     assert eu.source == "entsoe"
-    assert syd.quality == "mock"
+    assert syd.quality == "annual_average"
 
 
 @pytest.mark.asyncio
@@ -1494,14 +1494,26 @@ async def test_typical_reading_is_this_months_real_average():
 
 
 @pytest.mark.asyncio
-async def test_uncovered_region_still_falls_back_to_mock():
+async def test_mock_is_only_the_last_resort(monkeypatch):
+    from greenpick.data import typical_repository as tr
     repo = TypicalCarbonRepository()
+    # Sydney has no typical data but a sourced yearly figure -> annual, not mock.
     r = await repo.carbon_now("aws", "ap-southeast-2")
-    assert r.quality == "mock"
+    assert r.quality == "annual_average" and r.g_co2_per_kwh == 525.2
+    # With no yearly figure either, mock still answers (labelled) rather than failing.
+    monkeypatch.setattr(tr, "annual_entry", lambda p, reg: None)
+    m = await repo.carbon_now("aws", "ap-southeast-2")
+    assert m.quality == "mock"
     hist = await repo.carbon_history("aws", "ap-southeast-2")
     assert hist and hist[0].period.startswith("H") and not hist[0].period.endswith("Z")
 
 
+def test_no_catalog_region_relies_on_mock():
+    from greenpick.data.static_data import iter_regions
+    for prov, reg, meta in iter_regions():
+        assert typical_entry(prov, reg) or annual_entry(prov, reg), f"{prov}/{reg} would be mock"
+
+
 @pytest.mark.asyncio
 async def test_typical_history_is_the_months_real_profile_in_utc():
     from greenpick.services import scheduling_service as ss
@@ -1721,3 +1733,62 @@ def test_montreal_is_a_greener_option_for_new_york():
     added = (latency_service.estimate_latency_ms("aws", "ca-central-1", nyc)
              - latency_service.estimate_latency_ms("aws", "us-east-1", nyc))
     assert added < 15                                  # within an East Coast latency budget
+
+
+# --- 0.4.0: Asia — Singapore, Tokyo, Mumbai/Pune on sourced yearly figures ---
+
+from greenpick.data.typical_repository import annual_entry
+
+_ASIA = [("aws", "ap-southeast-1", "SG"), ("aws", "ap-northeast-1", "JP"), ("aws", "ap-south-1", "IN"),
+         ("gcp", "asia-southeast1", "SG"), ("gcp", "asia-northeast1", "JP"), ("gcp", "asia-south1", "IN"),
+         ("azure", "southeastasia", "SG"), ("azure", "japaneast", "JP"), ("azure", "centralindia", "IN")]
+
+
+def test_asia_regions_have_a_sourced_yearly_figure():
+    from greenpick.data.static_data import annual, region_meta
+    assert "Ember" in annual()["_source"]
+    for prov, reg, zone in _ASIA:
+        meta = region_meta(prov, reg)
+        assert meta["annual_zone"] == zone and meta["jurisdiction"] == zone
+        e = annual_entry(prov, reg)
+        assert e["year"] >= 2024 and 300 < e["g_co2_per_kwh"] < 900
+
+
+@pytest.mark.asyncio
+async def test_asia_reading_is_labelled_annual_and_has_no_hourly_shape():
+    repo = TypicalCarbonRepository()
+    r = await repo.carbon_now("aws", "ap-southeast-1")
+    assert (r.quality, r.source) == ("annual_average", "ember_annual")
+    assert r.g_co2_per_kwh == annual_entry("aws", "ap-southeast-1")["g_co2_per_kwh"]
+    assert await repo.carbon_history("aws", "ap-southeast-1") == []       # never invent a curve
+
+
+@pytest.mark.asyncio
+async def test_timing_tools_say_there_is_no_hourly_data_for_asia():
+    from greenpick.services import scheduling_service, forecast_service, training_service
+    repo = TypicalCarbonRepository()
+    tod = await scheduling_service.cleanest_time_of_day(repo, "aws", "ap-northeast-1")
+    assert tod.hours_analyzed == 0 and "No recent hourly history" in tod.note
+    fc = await forecast_service.carbon_forecast(repo, "aws", "ap-northeast-1")
+    assert fc.quality == "annual_average" and "yearly average" in fc.note
+    tr = await training_service.estimate_training_carbon(
+        repo, gpu="a100", gpu_count=8, gpu_hours=40, region="ap-south-1", provider="aws")
+    assert "no hourly data" in tr.rationale and "fairly flat" not in tr.rationale
+
+
+def test_hint_explains_annual_figures_without_asking_for_a_key(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", eia="k", entsoe="t"))
+    r = {"provider": "gcp", "region": "asia-south1", "quality": "annual_average", "source": "ember_annual"}
+    hint = data_hint.with_hint(r)["live_data_hint"]
+    assert "yearly average grid intensity (Ember, lifecycle basis: India 2025)" in hint
+    assert "no timing signal" in hint
+    assert "set EIA_API_KEY" not in hint and "No free live source covers" not in hint
+
+
+@pytest.mark.asyncio
+async def test_asian_users_are_now_served_from_asia():
+    from greenpick.services import serving_service
+    hubs = [ServingHub(name="apac", lat=0, lon=0, share=1.0)]
+    adv = await serving_service.serving_pattern(TypicalCarbonRepository(), hubs, Workload(vcpu=1, ram_gb=2))
+    assert adv.single_region.region in ("ap-southeast-1", "asia-southeast1", "southeastasia")
+    assert adv.single_region.weighted_latency_ms < 40                  # was ~199 ms from Sydney