greenpick 0.1.6__tar.gz → 0.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.6
+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
@@ -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:

{greenpick-0.1.6 → greenpick-0.1.7}/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:

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

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

@@ -35,7 +35,7 @@ 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. 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.\
 """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.1.6
+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
@@ -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:

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

@@ -1251,3 +1251,67 @@ def test_server_sends_instructions_that_lead_with_rightsizing():
     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