greenpick 0.2.0__tar.gz → 0.2.1__tar.gz

{greenpick-0.2.0/src/greenpick.egg-info → greenpick-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.2.0
+Version: 0.2.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
@@ -149,7 +149,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `compare_regions_tri_axis` | Rank candidate regions by carbon with cost + latency tradeoffs; recommend a pick, each axis rated R/Y/G. Pass `regions` to rank only the ones you'd actually consider. |
 | `greener_alternative_to` | "You picked X — the greenest region within +N ms latency is Y (−Z% carbon, Δcost)." The core nudge. |
-| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness. |
+| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness — and, when live, whether that's cleaner, dirtier or about usual for that hour this month. |
 
 ### Time a job (scheduling)
 

{greenpick-0.2.0 → greenpick-0.2.1}/README.md

@@ -119,7 +119,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `compare_regions_tri_axis` | Rank candidate regions by carbon with cost + latency tradeoffs; recommend a pick, each axis rated R/Y/G. Pass `regions` to rank only the ones you'd actually consider. |
 | `greener_alternative_to` | "You picked X — the greenest region within +N ms latency is Y (−Z% carbon, Δcost)." The core nudge. |
-| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness. |
+| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness — and, when live, whether that's cleaner, dirtier or about usual for that hour this month. |
 
 ### Time a job (scheduling)
 

{greenpick-0.2.0 → greenpick-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.2.0"
+version = "0.2.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.2.0 → greenpick-0.2.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.2.0"
+__version__ = "0.2.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.2.0 → greenpick-0.2.1}/src/greenpick/data/typical_repository.py

@@ -27,6 +27,56 @@ def _month(entry: dict) -> Optional[dict]:
     return entry.get("months", {}).get(str(datetime.now(timezone.utc).month))
 
 
+# Within this % of the typical value, a reading is "about usual" rather than cleaner/dirtier.
+USUAL_BAND_PCT = 10.0
+
+
+def _when(timestamp: str) -> datetime:
+    """The UTC moment a reading refers to (EIA '2026-10-23T06', ISO with Z/offset); now if unparseable."""
+    t = (timestamp or "").strip().replace("Z", "+00:00")
+    for candidate in (t, t[:13]):
+        try:
+            dt = datetime.fromisoformat(candidate) if len(candidate) > 13 else \
+                datetime.strptime(candidate, "%Y-%m-%dT%H")
+            return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+    return datetime.now(timezone.utc)
+
+
+def typical_context(provider: str, region: str, g_co2_per_kwh: float, timestamp: str) -> Optional[dict]:
+    """Compare a live reading with what's typical for that region, month and hour of day.
+    None if the region has no typical data."""
+    entry = typical_entry(provider, region)
+    if not entry:
+        return None
+    when = _when(timestamp).astimezone(timezone.utc)
+    month = entry.get("months", {}).get(str(when.month))
+    if not month:
+        return None
+    hourly = month["hourly_utc"][when.hour]
+    typical_now = hourly if hourly is not None else month["avg_g_co2_per_kwh"]
+    pct = round((g_co2_per_kwh - typical_now) / typical_now * 100, 1) if typical_now else None
+    if pct is None or abs(pct) < USUAL_BAND_PCT:
+        verdict = "about_usual"
+        words = "about usual"
+    elif pct < 0:
+        verdict, words = "cleaner_than_usual", f"~{abs(pct):.0f}% cleaner than usual"
+    else:
+        verdict, words = "dirtier_than_usual", f"~{pct:.0f}% dirtier than usual"
+    month_name = when.strftime("%B")
+    return {
+        "typical_this_hour_g_co2_per_kwh": typical_now,
+        "typical_month_avg_g_co2_per_kwh": month["avg_g_co2_per_kwh"],
+        "vs_typical_pct": pct,
+        "vs_typical": verdict,
+        "typical_note": (f"Live {g_co2_per_kwh:.0f} gCO2/kWh is {words} for {when.hour:02d}:00 UTC in "
+                         f"{month_name} (typical ~{typical_now:.0f}; {month_name} average "
+                         f"~{month['avg_g_co2_per_kwh']:.0f}, from a year of {entry['source'].upper()} "
+                         f"data). Directional context, not a forecast."),
+    }
+
+
 class TypicalCarbonRepository:
     def __init__(self) -> None:
         self._mock = MockCarbonRepository()

{greenpick-0.2.0 → greenpick-0.2.1}/src/greenpick/server.py

@@ -18,6 +18,7 @@ from .services import (
 )
 from .models import ServingHub
 from .services.data_hint import with_hint
+from .data.typical_repository import typical_context
 
 # Sent to every MCP client at connect. Agents learn a server from its tool list, not its README, and
 # the tool list starts with region-picking — so without this they lead with the rarest decision and
@@ -135,9 +136,17 @@ async def estimate_workload_carbon(
 
 @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."""
+    """Current grid carbon intensity for a region, with source, timestamp, and data freshness.
+    When the reading is live, also says how it compares with what's typical for that hour this month
+    (vs_typical: cleaner_than_usual / about_usual / dirtier_than_usual) — useful for "is now a good
+    moment to run this?"."""
     reading = await carbon_service.carbon_now(_repo, provider, region)  # type: ignore[arg-type]
-    return with_hint(reading.model_dump())
+    out = reading.model_dump()
+    if reading.quality in ("live", "live_estimated", "cached"):
+        ctx = typical_context(provider, region, reading.g_co2_per_kwh, reading.timestamp)
+        if ctx:
+            out.update(ctx)
+    return with_hint(out)
 
 
 @mcp.tool()

{greenpick-0.2.0 → greenpick-0.2.1/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.2.0
+Version: 0.2.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
@@ -149,7 +149,7 @@ See `docs/user-questions-backlog.md`.
 |------|--------------|
 | `compare_regions_tri_axis` | Rank candidate regions by carbon with cost + latency tradeoffs; recommend a pick, each axis rated R/Y/G. Pass `regions` to rank only the ones you'd actually consider. |
 | `greener_alternative_to` | "You picked X — the greenest region within +N ms latency is Y (−Z% carbon, Δcost)." The core nudge. |
-| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness. |
+| `region_carbon_now` | Current gCO₂/kWh for a region, with source + timestamp + freshness — and, when live, whether that's cleaner, dirtier or about usual for that hour this month. |
 
 ### Time a job (scheduling)
 

{greenpick-0.2.0 → greenpick-0.2.1}/tests/test_services.py

@@ -1544,3 +1544,54 @@ def test_default_repository_is_typical(monkeypatch):
     from greenpick import data as data_pkg
     monkeypatch.setattr(data_pkg, "SETTINGS", _settings(source="mock"))
     assert isinstance(data_pkg.get_repository(), TypicalCarbonRepository)
+
+
+# --- 0.2.1: a live reading says how it compares with what's typical for that hour ---
+
+from greenpick.data.typical_repository import typical_context
+
+
+def _typical_at(prov, reg, month, hour):
+    return typical_entry(prov, reg)["months"][str(month)]["hourly_utc"][hour]
+
+
+def test_typical_context_compares_with_same_hour_this_month():
+    base = _typical_at("aws", "us-east-1", 10, 6)
+    clean = typical_context("aws", "us-east-1", base * 0.7, "2026-10-23T06")
+    assert clean["typical_this_hour_g_co2_per_kwh"] == base
+    assert clean["vs_typical"] == "cleaner_than_usual" and clean["vs_typical_pct"] == -30.0
+    assert "06:00 UTC in October" in clean["typical_note"]
+    dirty = typical_context("aws", "us-east-1", base * 1.25, "2026-10-23T06")
+    assert dirty["vs_typical"] == "dirtier_than_usual"
+    usual = typical_context("aws", "us-east-1", base * 1.05, "2026-10-23T06")
+    assert usual["vs_typical"] == "about_usual"
+
+
+def test_typical_context_reads_entsoe_timestamps():
+    base = _typical_at("aws", "eu-north-1", 10, 18)
+    ctx = typical_context("aws", "eu-north-1", base, "2026-10-23T18:00Z")
+    assert ctx["typical_this_hour_g_co2_per_kwh"] == base and ctx["vs_typical"] == "about_usual"
+
+
+def test_no_typical_context_for_uncovered_region():
+    assert typical_context("aws", "ap-southeast-2", 500.0, "2026-10-23T06") is None
+
+
+@pytest.mark.asyncio
+async def test_region_carbon_now_adds_context_only_to_live_readings(monkeypatch):
+    from greenpick import server
+    from greenpick.models import CarbonReading
+
+    class LiveRepo(MockCarbonRepository):
+        async def carbon_now(self, provider, region):
+            return CarbonReading(region=region, provider=provider, g_co2_per_kwh=200.0,
+                                 source="eia", timestamp="2026-10-23T06", quality="live")
+
+    f = getattr(server.region_carbon_now, "fn", server.region_carbon_now)
+    monkeypatch.setattr(server, "_repo", LiveRepo())
+    live = await f(provider="aws", region="us-east-1")
+    assert live["vs_typical"] == "cleaner_than_usual" and "live_data_hint" not in live
+
+    monkeypatch.setattr(server, "_repo", TypicalCarbonRepository())
+    fallback = await f(provider="aws", region="us-east-1")
+    assert fallback["quality"] == "typical" and "vs_typical" not in fallback   # no self-comparison