greenpick 0.1.6__tar.gz → 0.1.8__tar.gz

{greenpick-0.1.6/src/greenpick.egg-info → greenpick-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.6
+Version: 0.1.8
 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
@@ -260,6 +260,7 @@ environment variables to it:
 
 ```python
 import sys
+# "mcp" is the MCP Python SDK (installed alongside greenpick), not a greenpick module.
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
@@ -273,7 +274,8 @@ params = StdioServerParameters(
     },
 )
 
-# In Jupyter, errlog must be a real file (the notebook's stderr has no fileno()).
+# Keep errlog=: in Jupyter it must be a real file, because the notebook's stderr has no fileno()
+# (without it you get "UnsupportedOperation: fileno").
 with open("greenpick-server.log", "w") as errlog:
     async with stdio_client(params, errlog=errlog) as (read, write):
         async with ClientSession(read, write) as session:
@@ -288,7 +290,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 real grid data, `mock` means a
-fallback value. Check it to confirm live data is on.
+fallback 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.
 
 ## FAQ
 

{greenpick-0.1.6 → greenpick-0.1.8}/README.md

@@ -230,6 +230,7 @@ environment variables to it:
 
 ```python
 import sys
+# "mcp" is the MCP Python SDK (installed alongside greenpick), not a greenpick module.
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
@@ -243,7 +244,8 @@ params = StdioServerParameters(
     },
 )
 
-# In Jupyter, errlog must be a real file (the notebook's stderr has no fileno()).
+# Keep errlog=: in Jupyter it must be a real file, because the notebook's stderr has no fileno()
+# (without it you get "UnsupportedOperation: fileno").
 with open("greenpick-server.log", "w") as errlog:
     async with stdio_client(params, errlog=errlog) as (read, write):
         async with ClientSession(read, write) as session:
@@ -258,7 +260,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 real grid data, `mock` means a
-fallback value. Check it to confirm live data is on.
+fallback 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.
 
 ## FAQ
 

{greenpick-0.1.6 → greenpick-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.1.6"
+version = "0.1.8"
 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.1.6 → greenpick-0.1.8}/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.1.6"
+__version__ = "0.1.8"
 
 # 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.1.6 → greenpick-0.1.8}/src/greenpick/models.py

@@ -70,7 +70,8 @@ class ForecastAdvice(BaseModel):
 class CleanestWindow(BaseModel):
     """The lowest-average contiguous run of N hours — for timing a job of known duration."""
     window_hours: int
-    start_period: str                 # the hour the window begins (start your job here)
+    start_hour_of_day: Optional[int] = None   # 0..23 — the advice: start around this hour each time
+    start_period: str                 # when that window began in the recent data (evidence, not a date to use)
     end_period: str                   # the last hour in the window
     avg_g_co2_per_kwh: float           # mean intensity across the window
     hours: list[HourlyCarbon] = []     # the per-hour breakdown of the chosen window
@@ -224,7 +225,9 @@ class RightsizingAdvice(BaseModel):
     carbon_now_kg_per_month: Optional[float] = None
     carbon_rightsized_kg_per_month: Optional[float] = None
     monthly_kg_co2_saving: Optional[float] = None
-    saving_pct: Optional[float] = None
+    cost_saving_pct: Optional[float] = None       # % off the monthly bill
+    carbon_saving_pct: Optional[float] = None     # % off monthly kg CO2
+    saving_pct: Optional[float] = None            # = carbon_saving_pct; kept for compatibility
     carbon_source: Optional[str] = None
     carbon_quality: Optional[str] = None
     rationale: str = ""
@@ -274,6 +277,8 @@ class ServingPerHubChoice(BaseModel):
     region: str
     latency_ms: float
     carbon_g_co2_per_kwh: float
+    carbon_source: Optional[str] = None
+    carbon_quality: Optional[str] = None
 
 
 class ServingPatternAdvice(BaseModel):
@@ -308,6 +313,8 @@ class DataLocalityWarning(BaseModel):
     est_monthly_egress_usd_low: Optional[float] = None    # monthly cost range = rate range x GB
     est_monthly_egress_usd_high: Optional[float] = None
     est_monthly_transfer_kg_co2: Optional[float] = None   # secondary, coarse
+    transfer_carbon_source: Optional[str] = None          # grid reading behind the transfer carbon
+    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
     residency_note: Optional[str] = None        # neutral cross-jurisdiction heads-up, if any

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/server.py

@@ -17,6 +17,7 @@ from .services import (
     rightsizing_service, inference_service,
 )
 from .models import ServingHub
+from .services.data_hint import with_hint
 
 # 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
@@ -35,7 +36,9 @@ serving_pattern_advice; carbon_metric_scaffold for an app to track its own estim
 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 'mock', 'cached' or 'historical' values \
-as such, never as live readings. If a call fails or output is missing, say so rather than describing \
+as such, never as live readings — including figures derived from them, such as a kg CO2 saving. \
+When a result includes live_data_hint, pass it on: it says why the data isn't live and how to turn \
+live data on. If a call fails or output is missing, say so rather than describing \
 what the tool would return. GreenPick estimates; it does not measure running systems or report model \
 accuracy. Use explain_methodology_and_limits when asked how a number was produced.\
 """
@@ -73,7 +76,7 @@ async def compare_regions_tri_axis(
         baseline_region=baseline_region,
         regions=[r for r in (regions or [])] or None,
     )
-    return rec.model_dump()
+    return with_hint(rec.model_dump())
 
 
 @mcp.tool()
@@ -103,7 +106,7 @@ async def greener_alternative_to(
         baseline_region=current_region,
         regions=[r for r in (regions or [])] or None,
     )
-    return rec.model_dump()
+    return with_hint(rec.model_dump())
 
 
 @mcp.tool()
@@ -119,7 +122,7 @@ async def estimate_workload_carbon(
     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 {
+    return with_hint({
         "provider": provider,
         "region": region,
         "estimated_kg_co2_per_month": kg,
@@ -127,14 +130,14 @@ async def estimate_workload_carbon(
         "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()
+    return with_hint(reading.model_dump())
 
 
 @mcp.tool()
@@ -149,7 +152,7 @@ async def cleanest_hours_to_run(
     advice = await scheduling_service.cleanest_hours(
         _repo, provider, region, top_n, window_hours=window_hours,  # type: ignore[arg-type]
     )
-    return advice.model_dump()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -177,7 +180,7 @@ async def 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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -199,7 +202,7 @@ async def 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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -222,7 +225,7 @@ async def 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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -245,7 +248,7 @@ async def carbon_metric_scaffold(
         _repo, language=language, region=region, provider=provider,  # type: ignore[arg-type]
         vcpu=vcpu, ram_gb=ram_gb,
     )
-    return scaffold.model_dump()
+    return with_hint(scaffold.model_dump())
 
 
 @mcp.tool()
@@ -275,7 +278,7 @@ async def serving_pattern_advice(
         _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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -297,7 +300,7 @@ async def data_locality_egress_check(
         monthly_cross_boundary_gb=monthly_cross_boundary_gb,
         carbon_saving_kg_co2_from_move=carbon_saving_kg_co2_from_move,
     )
-    return advice.model_dump()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -312,7 +315,7 @@ async def carbon_forecast(
     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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -322,7 +325,7 @@ async def cleanest_time_of_day(provider: str, region: str) -> dict:
     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()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -349,7 +352,7 @@ async def estimate_training_carbon(
         region=region, provider=provider, utilization=utilization,  # type: ignore[arg-type]
         top_n_regions=top_n_regions,
     )
-    return advice.model_dump()
+    return with_hint(advice.model_dump())
 
 
 @mcp.tool()
@@ -369,5 +372,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.",
+        "mock_data": "Used when live data isn't available (no key, an uncovered region, or the source didn't respond). Each grid gets a fixed typical value — illustrative, not a current reading — and an illustrative hourly pattern, so timing advice on mock data isn't meaningful. Results that use it are labelled 'mock' and carry a live_data_hint saying why 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, live); other regions, or any region without a key, use clearly-labelled mock data. Electricity Maps is available when selected explicitly (GREENPICK_CARBON_SOURCE=electricitymaps).",
     }

greenpick-0.1.8/src/greenpick/services/data_hint.py

@@ -0,0 +1,147 @@
+"""Tell the user WHY a result isn't live, and how to turn live data on.
+
+A tool result labelled `quality: "mock"` is honest, but on its own it reads like "this is all
+GreenPick does". The server log explains the cause ("No EIA_API_KEY set ..."), but MCP clients
+don't show server logs to users. So any result that leans on mock data gets a top-level
+`live_data_hint`, worded for the actual cause:
+
+- GreenPick is configured for mock data (the default)      -> how to switch on live data
+- the region's source needs a key that isn't set            -> which key, where to get it free
+- the key is set but the source didn't answer / refused it  -> try later or check the key
+- no free live source covers the region                     -> mock is the best available
+
+Mock values are a typical figure per grid, not a current reading; mock HOURLY patterns are
+illustrative, so timing advice built on them isn't meaningful. The hint says so.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterator, Optional
+
+from .. import config
+from ..data.static_data import region_meta
+
+TURN_ON_URL = "https://github.com/bithug01/greenpick#turn-on-live-data"
+_KEYS = {
+    "EIA_API_KEY": "https://www.eia.gov/opendata/register.php",
+    "ENTSOE_TOKEN": "https://transparency.entsoe.eu/",
+    "ELECTRICITYMAPS_TOKEN": "https://www.electricitymaps.com/",
+}
+_QUALITY_KEYS = ("quality", "carbon_quality", "timing_quality", "transfer_carbon_quality")
+_TIMING_KEYS = ("cleanest", "by_hour_of_day", "cleanest_hours", "cleanest_window", "cleanest_upcoming")
+
+
+def _location(d: dict) -> Optional[tuple[str, str]]:
+    """(provider, region) for a result dict, from provider/region fields or a 'prov/region' string."""
+    if isinstance(d.get("provider"), str) and isinstance(d.get("region"), str):
+        return d["provider"], d["region"]
+    for key in ("recommended_region", "data_location"):
+        v = d.get(key)
+        if isinstance(v, str) and "/" in v:
+            prov, reg = v.split("/", 1)
+            return prov, reg
+    return None
+
+
+def _walk(obj: Any) -> Iterator[dict]:
+    if isinstance(obj, dict):
+        yield obj
+        for v in obj.values():
+            yield from _walk(v)
+    elif isinstance(obj, list):
+        for v in obj:
+            yield from _walk(v)
+
+
+def _scan(result: dict) -> tuple[set[tuple[str, str]], bool, bool]:
+    """Regions whose figures are mock, whether any mock figure had no locatable region, and
+    whether mock data fed timing advice."""
+    regions: set[tuple[str, str]] = set()
+    unlocated = False
+    timing = False
+    for d in _walk(result):
+        mock_keys = [k for k in _QUALITY_KEYS if d.get(k) == "mock"]
+        if not mock_keys:
+            continue
+        loc = _location(d)
+        if loc:
+            regions.add(loc)
+        else:
+            unlocated = True
+        if "timing_quality" in mock_keys or any(k in d for k in _TIMING_KEYS):
+            timing = True
+    return regions, unlocated, timing
+
+
+def _reason(provider: str, region: str) -> tuple[str, str]:
+    """(reason, detail) for why this region's data is mock under the current settings."""
+    s = config.SETTINGS
+    meta = region_meta(provider, region) or {}  # type: ignore[arg-type]
+    src = s.carbon_source
+
+    def needs(key_name: str, have: str, source_label: str) -> tuple[str, str]:
+        return ("no_key", key_name) if not have else ("unavailable", source_label)
+
+    if src == "auto":
+        if meta.get("eia_ba"):
+            return needs("EIA_API_KEY", s.eia_api_key, "EIA")
+        if meta.get("entsoe_eic"):
+            return needs("ENTSOE_TOKEN", s.entsoe_token, "ENTSO-E")
+        return "uncovered", ""
+    if src == "eia":
+        return needs("EIA_API_KEY", s.eia_api_key, "EIA") if meta.get("eia_ba") else ("wrong_source", "EIA (US only)")
+    if src == "entsoe":
+        return (needs("ENTSOE_TOKEN", s.entsoe_token, "ENTSO-E") if meta.get("entsoe_eic")
+                else ("wrong_source", "ENTSO-E (EU only)"))
+    if src == "electricitymaps":
+        return needs("ELECTRICITYMAPS_TOKEN", s.electricitymaps_token, "Electricity Maps")
+    return "setting", ""
+
+
+def _names(locs: list[tuple[str, str]]) -> str:
+    return ", ".join(f"{p}/{r}" for p, r in sorted(locs))
+
+
+def build_hint(result: dict) -> Optional[str]:
+    regions, unlocated, timing = _scan(result)
+    if not regions and not unlocated:
+        return None
+
+    parts = ["Mock carbon figures here are a typical value for each grid, not a current reading."]
+    groups: dict[tuple[str, str], list[tuple[str, str]]] = {}
+    for loc in regions:
+        groups.setdefault(_reason(*loc), []).append(loc)
+    if unlocated and not groups:
+        groups[_reason("", "")] = []
+
+    for (reason, detail), locs in sorted(groups.items()):
+        where = f" for {_names(locs)}" if locs else ""
+        if reason == "setting":
+            parts.append(
+                "GreenPick is set to mock data (GREENPICK_CARBON_SOURCE is unset or 'mock'). For live "
+                "data, set GREENPICK_CARBON_SOURCE=auto plus a free EIA_API_KEY (US) and/or "
+                f"ENTSOE_TOKEN (EU) in the server's environment: {TURN_ON_URL}")
+        elif reason == "no_key":
+            parts.append(f"For live data{where}, set {detail} (free: {_KEYS[detail]}) in the server's "
+                         f"environment: {TURN_ON_URL}")
+        elif reason == "unavailable":
+            parts.append(f"{detail} didn't return data{where} just now, so GreenPick used its fallback. "
+                         "Try again later, or check that the key is valid.")
+        elif reason == "wrong_source":
+            parts.append(f"GREENPICK_CARBON_SOURCE is set to {detail}, which doesn't cover "
+                         f"{_names(locs) or 'this region'}. Use GREENPICK_CARBON_SOURCE=auto to route "
+                         "each region to its own live source.")
+        elif reason == "uncovered":
+            parts.append(f"No free live source covers {_names(locs)} yet, so mock is the best "
+                         "available there.")
+    if timing:
+        parts.append("The hourly pattern in mock data is illustrative, so timing advice (cleanest "
+                     "hours, start windows, % reductions) isn't meaningful until live data is on.")
+    return " ".join(parts)
+
+
+def with_hint(result: dict) -> dict:
+    """Add `live_data_hint` to a tool result that uses mock data; leave others unchanged."""
+    hint = build_hint(result)
+    if hint:
+        result["live_data_hint"] = hint
+    return result

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/forecast_service.py

@@ -58,15 +58,27 @@ async def carbon_forecast(
 
     # --- 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.")
+    if 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.
+        source, quality = "mock", "mock"
+        note = ("No day-ahead forecast or live history is available for this region, so there's "
+                "no real timing signal here. ")
+        if pattern.cleanest_hour_of_day is not None:
+            note += (f"GreenPick's illustrative mock pattern is cleanest around "
+                     f"{pattern.cleanest_hour_of_day:02d}:00, but that's not meaningful for scheduling.")
     else:
-        note += "No usable recent history either."
+        source, quality = "historical_fallback", "historical"
+        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 UTC - a reasonable default for a "
+                     f"recurring job.")
+        else:
+            note += "No usable recent history either."
     return ForecastAdvice(
-        region=region, provider=provider, source="historical_fallback", quality="historical",
+        region=region, provider=provider, source=source, quality=quality,
         hours_ahead=hours_ahead, cleanest_upcoming=[],
         note=note, limitations=LIMITATIONS,
     )

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/locality_service.py

@@ -158,6 +158,7 @@ async def data_locality_check(
         egress_rate_usd_per_gb_low=rate_low, egress_rate_usd_per_gb_high=rate_high,
         est_monthly_egress_usd_low=cost_low, est_monthly_egress_usd_high=cost_high,
         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,
         warning=warning, recommendation=rec, limitations=LIMITATIONS,

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/rightsizing_service.py

@@ -83,13 +83,19 @@ async def rightsizing_check(
 
     is_oversized = saving_pct is not None and saving_pct >= _MIN_SAVING_PCT
 
+    # Separate, labelled percentages: cost and carbon shrink by different fractions (price and power
+    # scale differently with vCPU vs RAM), so one unlabelled % beside a dollar figure misleads.
+    cost_pct = (round(usd_saving / cost_now * 100, 1)
+                if usd_saving is not None and cost_now else None)
+
     if is_oversized:
-        usd_txt = f"~${usd_saving:,.0f}/mo" if usd_saving is not None else "cost"
+        cost_txt = (f"~{cost_pct:.0f}% cheaper (~${usd_saving:,.0f}/mo saved)"
+                    if cost_pct is not None else "a lower bill")
         rationale = (
             f"Over-provisioned: at ~{cpu_utilization*100:.0f}% CPU use, {vcpu:g} vCPU / {ram_gb:g} GB "
             f"is bigger than you need. Right-size to {rec_vcpu:g} vCPU / {rec_ram:g} GB (the smallest "
-            f"standard size that keeps ~40% headroom) to cut ~{saving_pct:.0f}% - {usd_txt} AND "
-            f"~{kg_saving:.1f} kg CO2/mo. "
+            f"standard size that keeps ~40% headroom): {cost_txt} AND ~{saving_pct:.0f}% less carbon "
+            f"(~{kg_saving:.1f} kg CO2/mo, {reading.quality} grid data). "
             f"Same work, less waste: the cost and carbon win here are the same action.")
     else:
         rationale = (
@@ -105,7 +111,8 @@ async def rightsizing_check(
         cost_now_usd_per_month=cost_now, cost_rightsized_usd_per_month=cost_rs,
         monthly_usd_saving=usd_saving,
         carbon_now_kg_per_month=carbon_now, carbon_rightsized_kg_per_month=carbon_rs,
-        monthly_kg_co2_saving=kg_saving, saving_pct=saving_pct,
+        monthly_kg_co2_saving=kg_saving,
+        cost_saving_pct=cost_pct, carbon_saving_pct=saving_pct, saving_pct=saving_pct,
         carbon_source=reading.source, carbon_quality=reading.quality,
         rationale=rationale,
         limitations=("Directional, design-time estimate from the utilisation YOU report — not a "

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/scheduling_service.py

@@ -37,6 +37,22 @@ def _hour_index(period: str) -> Optional[int]:
     return int(dt.timestamp() // 3600)          # absolute hours since epoch
 
 
+def hour_of_day(period: str) -> Optional[int]:
+    """0..23 hour-of-day for a period label (UTC for live ISO timestamps; mock 'H15' -> 15)."""
+    idx = _hour_index(period)
+    return None if idx is None else idx % 24
+
+
+def clock_label(period: str) -> str:
+    """Turn a past period into advice you can act on: '15:00 UTC' (live) or '15:00' (mock hours
+    carry no timezone). Recent history says WHEN IN THE DAY is cleanest — the date it happened on
+    is evidence, not a start date, so it's never the headline."""
+    hod = hour_of_day(period)
+    if hod is None:
+        return period
+    return f"{hod:02d}:00" if period.strip().startswith("H") else f"{hod:02d}:00 UTC"
+
+
 def _best_and_worst_window(series: list[HourlyCarbon], window_hours: int
                            ) -> tuple[Optional[list[HourlyCarbon]], Optional[float]]:
     """Slide a window of `window_hours` over the CHRONOLOGICALLY ordered series, considering only
@@ -114,20 +130,22 @@ async def cleanest_hours(
         win_hours, win_reduction = _best_and_worst_window(history, window_hours)
         if win_hours:
             avg = round(sum(h.g_co2_per_kwh for h in win_hours) / len(win_hours), 1)
+            start = win_hours[0].period
             advice.window = CleanestWindow(
-                window_hours=window_hours,
-                start_period=win_hours[0].period, end_period=win_hours[-1].period,
+                window_hours=window_hours, start_hour_of_day=hour_of_day(start),
+                start_period=start, end_period=win_hours[-1].period,
                 avg_g_co2_per_kwh=avg, hours=win_hours,
             )
             advice.window_reduction_pct = win_reduction
+            seen = f"(the cleanest {window_hours}h window in the recent data began {start})"
             if win_reduction is not None and win_reduction >= 10:
-                advice.note = (f"For a ~{window_hours}h job, start it at {win_hours[0].period}: that's "
-                               f"the cleanest {window_hours}h window (avg ~{avg:.0f} gCO2/kWh), "
-                               f"~{win_reduction:.0f}% cleaner than the worst {window_hours}h window.")
+                advice.note = (f"For a ~{window_hours}h job, start around {clock_label(start)} "
+                               f"{seen}: avg ~{avg:.0f} gCO2/kWh, ~{win_reduction:.0f}% cleaner than "
+                               f"the worst {window_hours}h window. A recent pattern, not a forecast.")
             else:
-                advice.note = (f"For a ~{window_hours}h job, the cleanest window starts at "
-                               f"{win_hours[0].period} (avg ~{avg:.0f} gCO2/kWh), but the grid is "
-                               f"fairly flat — timing won't help much here.")
+                advice.note = (f"For a ~{window_hours}h job, the cleanest start is around "
+                               f"{clock_label(start)} {seen}, avg ~{avg:.0f} gCO2/kWh, but the grid "
+                               f"is fairly flat — timing won't help much here.")
         else:
             advice.note = (f"Not enough contiguous history to find a {window_hours}h window; "
                            f"showing cleanest individual hours instead. " + advice.note)

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/serving_service.py

@@ -123,9 +123,11 @@ async def serving_pattern(
         nearby = [s for s in scored if s[0] <= near_min]
         nearby.sort(key=lambda t: t[1])   # greenest among the near-latency options
         l, g, p, r = nearby[0]
+        reading = carbon_cache[(p, r)]
         per_hub.append(ServingPerHubChoice(
             hub=h.name, provider=p, region=r, latency_ms=round(l, 1),
             carbon_g_co2_per_kwh=g,
+            carbon_source=reading.source, carbon_quality=reading.quality,  # type: ignore[attr-defined]
         ))
 
     multi_wlat = None

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick/services/training_service.py

@@ -170,12 +170,14 @@ async def estimate_training_carbon(
 
     if advice.window and advice.window_reduction_pct and advice.window_reduction_pct >= 10:
         w = advice.window
-        time_txt = (f" It runs ~{wall_clock_h}h wall-clock; the cleanest {w.window_hours}h window to "
-                    f"start is {w.start_period} (avg ~{w.avg_g_co2_per_kwh:.0f} gCO2/kWh), "
-                    f"~{advice.window_reduction_pct:.0f}% cleaner than the worst same-length window - "
-                    f"training is deferrable, so this stacks on the region choice.")
+        time_txt = (f" It runs ~{wall_clock_h}h wall-clock; start it around "
+                    f"{scheduling_service.clock_label(w.start_period)} (the cleanest {w.window_hours}h "
+                    f"window in the recent data began {w.start_period}, avg ~{w.avg_g_co2_per_kwh:.0f} "
+                    f"gCO2/kWh), ~{advice.window_reduction_pct:.0f}% cleaner than the worst same-length "
+                    f"window - training is deferrable, so this stacks on the region choice. "
+                    f"A recent pattern, not a forecast.")
     elif advice.potential_reduction_pct and advice.potential_reduction_pct >= 10 and advice.cleanest:
-        best = advice.cleanest[0].period
+        best = scheduling_service.clock_label(advice.cleanest[0].period)
         time_txt = (f" Timing it to the cleanest hours in that region (around {best}) cuts a further "
                     f"~{advice.potential_reduction_pct:.0f}% vs the dirtiest hour - training is "
                     f"deferrable, so this stacks on the region choice.")

{greenpick-0.1.6 → greenpick-0.1.8/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.6
+Version: 0.1.8
 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
@@ -260,6 +260,7 @@ environment variables to it:
 
 ```python
 import sys
+# "mcp" is the MCP Python SDK (installed alongside greenpick), not a greenpick module.
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
@@ -273,7 +274,8 @@ params = StdioServerParameters(
     },
 )
 
-# In Jupyter, errlog must be a real file (the notebook's stderr has no fileno()).
+# Keep errlog=: in Jupyter it must be a real file, because the notebook's stderr has no fileno()
+# (without it you get "UnsupportedOperation: fileno").
 with open("greenpick-server.log", "w") as errlog:
     async with stdio_client(params, errlog=errlog) as (read, write):
         async with ClientSession(read, write) as session:
@@ -288,7 +290,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 real grid data, `mock` means a
-fallback value. Check it to confirm live data is on.
+fallback 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.
 
 ## FAQ
 

{greenpick-0.1.6 → greenpick-0.1.8}/src/greenpick.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/greenpick/data/static_data.py
 src/greenpick/services/__init__.py
 src/greenpick/services/carbon_service.py
 src/greenpick/services/cost_service.py
+src/greenpick/services/data_hint.py
 src/greenpick/services/forecast_service.py
 src/greenpick/services/inference_service.py
 src/greenpick/services/instance_service.py

{greenpick-0.1.6 → greenpick-0.1.8}/tests/test_services.py

@@ -718,13 +718,37 @@ from greenpick.services import forecast_service
 
 
 @pytest.mark.asyncio
-async def test_forecast_degrades_to_historical_without_forecast_source():
-    # MockCarbonRepository has no renewable_forecast -> service falls back to historical pattern.
+async def test_forecast_fallback_on_mock_history_is_labelled_mock():
+    # No forecast and only mock history: the fallback pattern is synthetic, so it must say mock,
+    # not 'historical' (which would pass an illustrative curve off as real past data).
     repo = MockCarbonRepository()
     adv = await forecast_service.carbon_forecast(repo, "aws", "us-east-1", hours_ahead=24)
+    assert adv.source == "mock"
+    assert adv.quality == "mock"
+    assert adv.cleanest_upcoming == []
+    assert "not meaningful" in adv.note
+
+
+@pytest.mark.asyncio
+async def test_forecast_degrades_to_historical_with_live_history(monkeypatch):
+    # US region with live EIA history but no day-ahead forecast -> a real historical fallback.
+    def handler(request: httpx.Request) -> httpx.Response:
+        data = []
+        for day in ("2026-10-10", "2026-10-11"):
+            data += [
+                {"period": f"{day}T02", "fueltype": "NUC", "value": "1800"},
+                {"period": f"{day}T02", "fueltype": "NG", "value": "200"},
+                {"period": f"{day}T18", "fueltype": "NUC", "value": "200"},
+                {"period": f"{day}T18", "fueltype": "NG", "value": "1800"},
+            ]
+        return httpx.Response(200, json={"response": {"data": data}})
+
+    orig = httpx.AsyncClient
+    monkeypatch.setattr(httpx, "AsyncClient",
+                        lambda *a, **k: orig(transport=_mock_transport(handler)))
+    adv = await forecast_service.carbon_forecast(EIARepository(api_key="k"), "aws", "us-east-1")
     assert adv.source == "historical_fallback"
     assert adv.quality == "historical"
-    assert adv.cleanest_upcoming == []
     assert "historical" in adv.note.lower()
 
 
@@ -1248,6 +1272,180 @@ def test_server_sends_instructions_that_lead_with_rightsizing():
     assert "mock" in text and "TOTAL" in text and "data_locality_egress_check" in text
     # Every tool named in the instructions actually exists.
     import re, asyncio
-    named = set(re.findall(r"\b[a-z]+(?:_[a-z]+)+\b", text)) - {"wall_clock_hours", "gpu_hours", "residency_note"}
+    named = set(re.findall(r"\b[a-z]+(?:_[a-z]+)+\b", text)) - {"wall_clock_hours", "gpu_hours", "residency_note", "live_data_hint"}
     registered = {t.name for t in asyncio.run(server.mcp.list_tools())}
     assert named <= registered, named - registered
+
+
+# --- 0.1.7: labelled percentages; start advice as a time of day, not a past date ---
+
+@pytest.mark.asyncio
+async def test_rightsizing_labels_cost_and_carbon_percentages_separately():
+    from greenpick.services import rightsizing_service
+    repo = MockCarbonRepository()
+    adv = await rightsizing_service.rightsizing_check(
+        repo, "aws", "us-east-1", vcpu=8, ram_gb=32, cpu_utilization=0.15,
+    )
+    # Cost % is the bill saving; carbon % is the kg saving. They differ, so both are reported.
+    assert adv.cost_saving_pct == round(adv.monthly_usd_saving / adv.cost_now_usd_per_month * 100, 1)
+    assert adv.carbon_saving_pct == round(adv.monthly_kg_co2_saving / adv.carbon_now_kg_per_month * 100, 1)
+    assert adv.cost_saving_pct != adv.carbon_saving_pct
+    assert adv.saving_pct == adv.carbon_saving_pct                 # compatibility field unchanged
+    assert f"~{adv.cost_saving_pct:.0f}% cheaper" in adv.rationale
+    assert f"~{adv.carbon_saving_pct:.0f}% less carbon" in adv.rationale
+    assert "mock grid data" in adv.rationale                       # derived carbon carries its quality
+
+
+def test_clock_label_turns_past_periods_into_a_time_of_day():
+    from greenpick.services import scheduling_service as ss
+    assert ss.clock_label("2026-10-17T15") == "15:00 UTC"
+    assert ss.clock_label("2026-10-17T15:00Z") == "15:00 UTC"
+    assert ss.clock_label("H02") == "02:00"                       # mock hours have no timezone
+    assert ss.hour_of_day("2026-10-17T15") == 15
+
+
+@pytest.mark.asyncio
+async def test_window_advice_leads_with_time_of_day_not_a_date(monkeypatch):
+    from greenpick.services import scheduling_service as ss
+    from greenpick.models import HourlyCarbon
+
+    class Repo(MockCarbonRepository):
+        async def carbon_history(self, provider, region):
+            # Two past days; 15:00-19:00 is clean on the 17th.
+            out = []
+            for day in ("2026-10-17", "2026-10-18"):
+                for h in range(24):
+                    g = 60.0 if (day == "2026-10-17" and 15 <= h <= 19) else 200.0
+                    out.append(HourlyCarbon(period=f"{day}T{h:02d}", g_co2_per_kwh=g))
+            return out
+
+    adv = await ss.cleanest_hours(Repo(), "aws", "us-west-2", window_hours=5)
+    assert adv.window.start_hour_of_day == 15
+    assert adv.window.start_period == "2026-10-17T15"           # kept, as evidence
+    assert adv.note.startswith("For a ~5h job, start around 15:00 UTC")
+
+
+@pytest.mark.asyncio
+async def test_training_rationale_says_start_around_a_time():
+    from greenpick.services import training_service
+    repo = MockCarbonRepository()
+    adv = await training_service.estimate_training_carbon(
+        repo, gpu="a100", gpu_count=8, gpu_hours=40, region="us-east-1", provider="aws",
+    )
+    assert adv.cleanest_window is not None and adv.cleanest_window.start_hour_of_day is not None
+    assert f"start it around {adv.cleanest_window.start_hour_of_day:02d}:00" in adv.rationale
+
+
+def test_instructions_cover_derived_mock_figures():
+    from greenpick import server
+    assert "derived from them" in server.mcp.instructions
+
+
+# --- 0.1.8: a mock result says why it isn't live, and how to turn live data on ---
+
+from greenpick import config as _config
+from greenpick.config import Settings
+from greenpick.services import data_hint
+
+
+def _settings(source="auto", eia="", entsoe="", em=""):
+    return Settings(carbon_source=source, electricitymaps_token=em, eia_api_key=eia,
+                    entsoe_token=entsoe, cache_ttl_seconds=1800, log_level="INFO")
+
+
+def _mock(provider, region):
+    return {"provider": provider, "region": region, "g_co2_per_kwh": 350.0,
+            "source": "mock", "quality": "mock"}
+
+
+def test_hint_when_greenpick_is_set_to_mock(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="mock"))
+    hint = data_hint.with_hint(_mock("aws", "us-east-1"))["live_data_hint"]
+    assert "typical value for each grid, not a current reading" in hint
+    assert "GREENPICK_CARBON_SOURCE=auto" in hint and data_hint.TURN_ON_URL in hint
+
+
+def test_hint_names_the_missing_key(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", eia="", entsoe="tok"))
+    hint = data_hint.with_hint(_mock("aws", "us-east-1"))["live_data_hint"]
+    assert "set EIA_API_KEY" in hint and "eia.gov/opendata/register" in hint
+    assert "ENTSOE_TOKEN" not in hint
+
+
+def test_hint_when_key_is_set_but_source_did_not_answer(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", entsoe="tok"))
+    hint = data_hint.with_hint(_mock("aws", "eu-north-1"))["live_data_hint"]
+    assert "ENTSO-E didn't return data for aws/eu-north-1" in hint
+    assert "set ENTSOE_TOKEN" not in hint                       # don't tell them to add a key they have
+
+
+def test_hint_for_a_region_no_free_source_covers(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", eia="k", entsoe="t"))
+    hint = data_hint.with_hint(_mock("aws", "ap-southeast-2"))["live_data_hint"]
+    assert "No free live source covers aws/ap-southeast-2" in hint
+    assert "set EIA_API_KEY" not in hint and "set ENTSOE_TOKEN" not in hint
+
+
+def test_no_hint_on_live_results(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", eia="k"))
+    live = {"provider": "aws", "region": "us-east-1", "quality": "live", "source": "eia"}
+    assert "live_data_hint" not in data_hint.with_hint(dict(live))
+    cached = dict(live, quality="cached")
+    assert "live_data_hint" not in data_hint.with_hint(cached)
+
+
+def test_hint_covers_nested_regions_and_flags_mock_timing(monkeypatch):
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="auto", entsoe="tok"))
+    result = {
+        "recommended_region": "aws/eu-north-1", "timing_quality": "mock",
+        "options": [
+            {"provider": "aws", "region": "eu-north-1", "carbon_quality": "mock"},
+            {"provider": "aws", "region": "ap-southeast-2", "carbon_quality": "mock"},
+            {"provider": "aws", "region": "us-west-2", "carbon_quality": "live"},
+        ],
+    }
+    hint = data_hint.with_hint(result)["live_data_hint"]
+    assert "aws/eu-north-1" in hint and "aws/ap-southeast-2" in hint
+    assert "us-west-2" not in hint
+    assert "hourly pattern in mock data is illustrative" in hint
+
+
+@pytest.mark.asyncio
+async def test_every_carbon_tool_attaches_the_hint_on_mock(monkeypatch):
+    # End to end through the MCP tool functions, with the server's repo on mock data.
+    from greenpick import server
+    monkeypatch.setattr(_config, "SETTINGS", _settings(source="mock"))
+    monkeypatch.setattr(server, "_repo", MockCarbonRepository())
+
+    async def call(name, **kw):
+        f = getattr(server, name)
+        f = getattr(f, "fn", f)
+        return await f(**kw)
+
+    calls = {
+        "region_carbon_now": dict(provider="aws", region="us-east-1"),
+        "rightsizing_check": dict(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=0.15),
+        "estimate_workload_carbon": dict(provider="aws", region="us-east-1", vcpu=4, ram_gb=16),
+        "estimate_training_carbon": dict(gpu="a100", gpu_count=8, gpu_hours=40),
+        "compare_regions_tri_axis": dict(user_lat=40.7, user_lon=-74.0, vcpu=4, ram_gb=16),
+        "cleanest_time_of_day": dict(provider="aws", region="us-east-1"),
+        "carbon_forecast": dict(provider="aws", region="us-east-1"),
+        "data_locality_egress_check": dict(compute_provider="aws", compute_region="us-west-2",
+                                           data_provider="aws", data_region="us-east-1",
+                                           monthly_cross_boundary_gb=500),
+        "serving_pattern_advice": dict(hubs=[{"name": "us", "share": 0.6}, {"name": "eu", "share": 0.4}]),
+    }
+    for name, kw in calls.items():
+        r = await call(name, **kw)
+        assert "live_data_hint" in r, name
+
+
+@pytest.mark.asyncio
+async def test_egress_and_serving_label_their_carbon_quality():
+    from greenpick.services import locality_service, serving_service
+    repo = MockCarbonRepository()
+    eg = await locality_service.data_locality_check(repo, "aws", "us-west-2", "aws", "us-east-1", 500)
+    assert eg.transfer_carbon_quality == "mock" and eg.transfer_carbon_source == "mock"
+    hubs = [ServingHub(name="us", lat=0, lon=0, share=0.5), ServingHub(name="eu", lat=0, lon=0, share=0.5)]
+    sv = await serving_service.serving_pattern(repo, hubs, Workload(vcpu=1, ram_gb=2))
+    assert sv.multi_region and all(c.carbon_quality == "mock" for c in sv.multi_region)