greenpick 0.1.5__tar.gz → 0.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.5
+Version: 0.1.7
 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
@@ -254,15 +254,41 @@ of the options below.)
 }
 ```
 
-**In a Jupyter notebook or Python script**, set them before you start (or import) the server:
+**In a Jupyter notebook or Python script**, connect with the MCP client library and pass the keys
+in `env`. The library starts GreenPick as a separate process and doesn't forward the notebook's own
+environment variables to it:
 
 ```python
-import os
-os.environ["GREENPICK_CARBON_SOURCE"] = "auto"
-os.environ["EIA_API_KEY"] = "your-eia-key"
-os.environ["ENTSOE_TOKEN"] = "your-entsoe-token"
+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
+
+params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "greenpick"],
+    env={
+        "GREENPICK_CARBON_SOURCE": "auto",
+        "EIA_API_KEY": "your-eia-key",
+        "ENTSOE_TOKEN": "your-entsoe-token",
+    },
+)
+
+# 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:
+            await session.initialize()
+            result = await session.call_tool(
+                "region_carbon_now", {"provider": "aws", "region": "us-west-2"}
+            )
+            print(result.content[0].text)
 ```
 
+Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
+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.
 

{greenpick-0.1.5 → greenpick-0.1.7}/README.md

@@ -224,15 +224,41 @@ of the options below.)
 }
 ```
 
-**In a Jupyter notebook or Python script**, set them before you start (or import) the server:
+**In a Jupyter notebook or Python script**, connect with the MCP client library and pass the keys
+in `env`. The library starts GreenPick as a separate process and doesn't forward the notebook's own
+environment variables to it:
 
 ```python
-import os
-os.environ["GREENPICK_CARBON_SOURCE"] = "auto"
-os.environ["EIA_API_KEY"] = "your-eia-key"
-os.environ["ENTSOE_TOKEN"] = "your-entsoe-token"
+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
+
+params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "greenpick"],
+    env={
+        "GREENPICK_CARBON_SOURCE": "auto",
+        "EIA_API_KEY": "your-eia-key",
+        "ENTSOE_TOKEN": "your-entsoe-token",
+    },
+)
+
+# 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:
+            await session.initialize()
+            result = await session.call_tool(
+                "region_carbon_now", {"provider": "aws", "region": "us-west-2"}
+            )
+            print(result.content[0].text)
 ```
 
+Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
+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.
 

{greenpick-0.1.5 → greenpick-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.1.5"
+version = "0.1.7"
 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.5 → greenpick-0.1.7}/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.5"
+__version__ = "0.1.7"
 
 # 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.5 → greenpick-0.1.7}/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 = ""

{greenpick-0.1.5 → greenpick-0.1.7}/src/greenpick/server.py

@@ -18,7 +18,29 @@ from .services import (
 )
 from .models import ServingHub
 
-mcp = FastMCP("greenpick")
+# 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
+# skip the most valuable one. This names the strongest uses first and the reporting rules that matter.
+INSTRUCTIONS = """\
+GreenPick advises on cloud infrastructure decisions BEFORE you deploy, weighing carbon, cost and \
+latency together. Strongest uses, in order:
+1. Right-sizing (rightsizing_check): an over-provisioned instance cut to a standard, buyable size \
+saves money and carbon in the same move. Lead with the monthly dollar saving.
+2. Scheduling deferrable jobs: cleanest_hours_to_run (one-off), cleanest_time_of_day (recurring), \
+carbon_forecast (EU day-ahead).
+3. GPU training and LLM inference footprints: estimate_training_carbon (gpu_hours is the TOTAL across \
+all GPUs; report wall_clock_hours as the run length), estimate_inference_carbon.
+4. Efficiency and placement: greener_instance_family, compare_regions_tri_axis, greener_alternative_to, \
+serving_pattern_advice; carbon_metric_scaffold for an app to track its own estimated carbon.
+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 \
+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.\
+"""
+
+mcp = FastMCP("greenpick", instructions=INSTRUCTIONS)
 _repo = get_repository()
 
 

{greenpick-0.1.5 → greenpick-0.1.7}/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.5 → greenpick-0.1.7}/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.5 → greenpick-0.1.7}/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.5 → greenpick-0.1.7/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.5
+Version: 0.1.7
 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
@@ -254,15 +254,41 @@ of the options below.)
 }
 ```
 
-**In a Jupyter notebook or Python script**, set them before you start (or import) the server:
+**In a Jupyter notebook or Python script**, connect with the MCP client library and pass the keys
+in `env`. The library starts GreenPick as a separate process and doesn't forward the notebook's own
+environment variables to it:
 
 ```python
-import os
-os.environ["GREENPICK_CARBON_SOURCE"] = "auto"
-os.environ["EIA_API_KEY"] = "your-eia-key"
-os.environ["ENTSOE_TOKEN"] = "your-entsoe-token"
+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
+
+params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "greenpick"],
+    env={
+        "GREENPICK_CARBON_SOURCE": "auto",
+        "EIA_API_KEY": "your-eia-key",
+        "ENTSOE_TOKEN": "your-entsoe-token",
+    },
+)
+
+# 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:
+            await session.initialize()
+            result = await session.call_tool(
+                "region_carbon_now", {"provider": "aws", "region": "us-west-2"}
+            )
+            print(result.content[0].text)
 ```
 
+Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
+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.
 

{greenpick-0.1.5 → greenpick-0.1.7}/tests/test_services.py

@@ -1234,3 +1234,84 @@ async def test_entsoe_remembers_an_outage(monkeypatch):
     await repo.carbon_history("aws", "eu-north-1")
     assert again.quality == "mock"
     assert calls["n"] == after_first
+
+
+# --- 0.1.6: server-level instructions steer agents (they read the tool list, not the README) ---
+
+def test_server_sends_instructions_that_lead_with_rightsizing():
+    from greenpick import server
+    text = server.mcp.instructions or ""
+    assert "rightsizing_check" in text
+    # Right-sizing is named before region-picking (the tool list itself starts with region tools).
+    assert text.index("rightsizing_check") < text.index("compare_regions_tri_axis")
+    # The reporting rules that outside agents got wrong in testing.
+    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"}
+    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