greenpick 0.1.7__tar.gz → 0.1.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.7
+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
@@ -290,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.7 → greenpick-0.1.8}/README.md

@@ -260,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.7 → greenpick-0.1.8}/pyproject.toml

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

@@ -277,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):
@@ -311,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.7 → 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 — including figures derived from them, such as a kg CO2 saving. 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.7 → 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.7 → 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.7 → 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.7 → greenpick-0.1.8/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.7
+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
@@ -290,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.7 → 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.7 → 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,7 +1272,7 @@ 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
 
@@ -1315,3 +1339,113 @@ async def test_training_rationale_says_start_around_a_time():
 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)