greenpick 0.6.0__tar.gz → 0.6.2__tar.gz

{greenpick-0.6.0/src/greenpick.egg-info → greenpick-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -308,6 +308,10 @@ with open("greenpick-server.log", "w") as errlog:
 Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
 and run it with `asyncio.run(...)`.
 
+Using an AI assistant inside a notebook? Paste the
+[starter prompt](https://github.com/bithug01/greenpick/blob/master/docs/using-from-a-notebook.md)
+as your first message: it sets up the connection and points the assistant at the right tool for each question.
+
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
 this month's average from last year's real data, `annual_average` means a sourced yearly national
 figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm

{greenpick-0.6.0 → greenpick-0.6.2}/README.md

@@ -278,6 +278,10 @@ with open("greenpick-server.log", "w") as errlog:
 Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
 and run it with `asyncio.run(...)`.
 
+Using an AI assistant inside a notebook? Paste the
+[starter prompt](https://github.com/bithug01/greenpick/blob/master/docs/using-from-a-notebook.md)
+as your first message: it sets up the connection and points the assistant at the right tool for each question.
+
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
 this month's average from last year's real data, `annual_average` means a sourced yearly national
 figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm

{greenpick-0.6.0 → greenpick-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "greenpick"
-version = "0.6.0"
+version = "0.6.2"
 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.6.0 → greenpick-0.6.2}/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.6.0"
+__version__ = "0.6.2"
 
 # 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.6.0 → greenpick-0.6.2}/src/greenpick/server.py

@@ -60,6 +60,18 @@ accuracy. Use explain_methodology_and_limits when asked how a number was produce
 """
 
 mcp = FastMCP("greenpick", instructions=INSTRUCTIONS)
+
+
+def _fraction_error(name: str, value: Optional[float], allow_zero: bool = False) -> Optional[str]:
+    """Utilisation inputs are fractions (0.15 = 15%). A value like 15 is almost always a percentage;
+    say so rather than silently reading it as 1,500%."""
+    if value is None:
+        return None
+    low_ok = value >= 0 if allow_zero else value > 0
+    if low_ok and value <= 1:
+        return None
+    hint = f" Did you mean {value / 100:g}?" if 1 < value <= 100 else ""
+    return (f"{name} must be a fraction between 0 and 1 (0.15 means 15%); got {value:g}.{hint}")
 _repo = get_repository()
 
 
@@ -81,7 +93,8 @@ async def compare_regions_tri_axis(
     (e.g. ["us-east-1","us-west-2","eu-west-1"]) to rank ONLY those you'd actually consider,
     instead of the whole catalog — your baseline is always kept in the comparison. If the pick is
     in a different region from where your data lives, run data_locality_egress_check before moving:
-    cross-region/cross-cloud egress can erase the carbon/cost win."""
+    cross-region/cross-cloud egress can erase the carbon/cost win. To write a chosen move up for a pull
+    request or decision record, use region_move_justification (do not draft the text from this result)."""
     rec = await recommender.compare_regions(
         _repo,
         providers=[p for p in (providers or [])] or None,  # type: ignore[list-item]
@@ -111,7 +124,8 @@ async def greener_alternative_to(
     with the carbon/cost/latency delta vs. your current choice. The core 'nudge' tool. Pass
     `regions` to limit the search to options you'd actually move to; your current region is
     always included. Before accepting a move, run data_locality_egress_check if your data stays in
-    the current region — the egress to feed compute from afar can outweigh the greener-region win."""
+    the current region — the egress to feed compute from afar can outweigh the greener-region win.
+    To write a chosen move up for a pull request or decision record, use region_move_justification."""
     rec = await recommender.compare_regions(
         _repo,
         providers=[p for p in (providers or [])] or None,  # type: ignore[list-item]
@@ -245,6 +259,11 @@ async def rightsizing_check(
     Returns the right-sized target (keeps ~40% headroom) with the monthly $ AND kg CO2 saving. Lead
     with the cost number, carbon is the twin. Directional, design-time — uses the utilisation you
     report, not a reading of your fleet."""
+    for name, value, zero in (("cpu_utilization", cpu_utilization, False),
+                              ("ram_utilization", ram_utilization, True)):
+        err = _fraction_error(name, value, allow_zero=zero)
+        if err:
+            return {"provider": provider, "region": region, "error": err}
     advice = await rightsizing_service.rightsizing_check(
         _repo, provider, region, vcpu, ram_gb, cpu_utilization,  # type: ignore[arg-type]
         ram_utilization=ram_utilization, hours_per_month=hours_per_month,
@@ -385,8 +404,10 @@ async def migration_payoff(
     data_locality_egress_check. Give where the data is now, where compute runs, how many GB you would
     migrate once, and how many GB a month cross between them today. Returns the payback in months, the
     one-off vs monthly egress cost and transfer carbon, and the net over the horizon (default 12 months).
-    Egress only: storage prices, request charges, downtime and effort are not included. Ask the user for
-    the GB figures rather than assuming them."""
+    Egress only: storage prices, request charges, downtime and effort are not included, and it does NOT
+    judge whether the compute should be in that region (use region_move_justification for that). Quote the
+    FULL dollar range (low and high), not just the high end; it can straddle zero. Ask the user for the GB
+    figures rather than assuming them."""
     if data_gb_to_migrate <= 0 or monthly_cross_boundary_gb < 0 or not 0 < horizon_months <= 120:
         return {"error": "data_gb_to_migrate must be > 0, monthly_cross_boundary_gb >= 0, and "
                          "horizon_months between 0 and 120."}
@@ -466,7 +487,11 @@ async def estimate_training_carbon(
     portable and deferrable, so this combines region choice with cleanest-hours timing. Directional
     (TDP-based energy); GPU availability per region is NOT checked - verify your card is offered there.
     Training data is often large: if your dataset lives in another region, run data_locality_egress_check
-    before shipping the job to the greenest region - the data egress can outweigh the carbon saving."""
+    before shipping the job to the greenest region - the data egress can outweigh the carbon saving.
+    `utilization` is an optional fraction of TDP (0..1, e.g. 0.6 for 60%)."""
+    err = _fraction_error("utilization", utilization)
+    if err:
+        return {"gpu": gpu, "error": err}
     advice = await training_service.estimate_training_carbon(
         _repo, gpu, gpu_count, gpu_hours,  # type: ignore[arg-type]
         region=region, provider=provider, utilization=utilization,  # type: ignore[arg-type]

{greenpick-0.6.0 → greenpick-0.6.2}/src/greenpick/services/migration_service.py

@@ -22,6 +22,10 @@ from ..data.static_data import network_model
 from . import carbon_service, locality_service, residency_service
 
 
+def _usd(x: float) -> str:
+    return f"-${abs(x):,.0f}" if x < 0 else f"${x:,.0f}"
+
+
 async def migration_payoff(
     repo: CarbonRepository,
     data_provider: str, data_region: str,
@@ -69,6 +73,8 @@ async def migration_payoff(
     residency = residency_service.residency_flag(
         data_provider, data_region, compute_provider, compute_region)
 
+    straddle = (net_usd is not None and net_usd[0] < 0 < net_usd[1])
+    egress_only = " Egress only: this does not judge whether the compute should be in that region."
     if monthly_cross_boundary_gb <= 0:
         verdict = "no_ongoing_traffic"
         summary = (f"Moving the data buys no egress saving: no GB a month cross between "
@@ -79,12 +85,17 @@ async def migration_payoff(
         summary = (f"Moving the data too pays back in about {payback_months:g} months "
                    f"(~{data_gb_to_migrate:,.0f} GB once vs ~{monthly_cross_boundary_gb:,.0f} GB a month "
                    f"no longer crossing), within your {horizon_months:g}-month horizon.")
+        if straddle:
+            summary += (f" In dollars it could land either side of zero over the horizon "
+                        f"(net {_usd(net_usd[0])} to {_usd(net_usd[1])}); the carbon saving is "
+                        f"{'positive' if net_kg and net_kg > 0 else 'not positive'} (~{net_kg:,.1f} kg).")
+        summary += egress_only
     else:
         verdict = "does_not_pay_back"
         summary = (f"Moving the data too does NOT pay back within {horizon_months:g} months: it takes "
                    f"about {payback_months:g} months (~{data_gb_to_migrate:,.0f} GB once vs "
                    f"~{monthly_cross_boundary_gb:,.0f} GB a month no longer crossing). Leave the data "
-                   "where it is, or re-check the volumes.")
+                   "where it is, or re-check the volumes.") + egress_only
 
     return {
         "summary": summary,

{greenpick-0.6.0 → greenpick-0.6.2/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -308,6 +308,10 @@ with open("greenpick-server.log", "w") as errlog:
 Top-level `await` works in Jupyter. In a plain script, put the `with` block inside an `async def`
 and run it with `asyncio.run(...)`.
 
+Using an AI assistant inside a notebook? Paste the
+[starter prompt](https://github.com/bithug01/greenpick/blob/master/docs/using-from-a-notebook.md)
+as your first message: it sets up the connection and points the assistant at the right tool for each question.
+
 Every carbon figure includes a `quality` field: `live` means a current reading, `typical` means
 this month's average from last year's real data, `annual_average` means a sourced yearly national
 figure (regions with no free hourly data), and `mock` means a hand-set value. Check it to confirm

{greenpick-0.6.0 → greenpick-0.6.2}/tests/test_services.py

@@ -1968,3 +1968,68 @@ async def test_new_tools_validate_inputs():
     assert "error" in bad
     bad2 = await _tool("region_move_justification")("aws", "us-east-1", "aws", "eu-north-1", 4, 16, hours_per_month=0)
     assert "error" in bad2
+
+
+# --- 0.6.1: migration summary is honest about a dollar range that straddles zero ---
+@pytest.mark.asyncio
+async def test_migration_summary_flags_dollar_range_straddling_zero():
+    from greenpick.services import migration_service as ms
+    args = ("aws", "us-east-1", "aws", "eu-north-1")
+    r = await ms.migration_payoff(MockCarbonRepository(), *args, 2000, 300)
+    assert r["verdict"] == "pays_back" and r["net_over_horizon_usd_low"] < 0 < r["net_over_horizon_usd_high"]
+    assert "either side of zero" in r["summary"] and "Egress only" in r["summary"]
+    clear = await ms.migration_payoff(MockCarbonRepository(), *args, 500, 300)
+    assert "either side of zero" not in clear["summary"] and "Egress only" in clear["summary"]
+    assert "Egress only" in (await ms.migration_payoff(MockCarbonRepository(), *args, 8000, 300))["summary"]
+
+
+def test_move_tools_point_to_the_justification_tool():
+    import asyncio
+    from greenpick import server
+    desc = {t.name: t.description for t in asyncio.run(server.mcp.list_tools())}
+    assert "region_move_justification" in desc["compare_regions_tri_axis"]
+    assert "region_move_justification" in desc["greener_alternative_to"]
+    assert "FULL dollar range" in desc["migration_payoff"]
+
+
+# --- docs/using-from-a-notebook.md stays in step with the real tool list ---
+def test_notebook_prompt_lists_every_tool_and_no_unknown_ones():
+    import asyncio, re
+    from pathlib import Path
+    from greenpick import server
+    names = {t.name for t in asyncio.run(server.mcp.list_tools())}
+    text = (Path(__file__).resolve().parent.parent / "docs" / "using-from-a-notebook.md").read_text(encoding="utf-8")
+    missing = sorted(n for n in names if n not in text)
+    assert not missing, f"add these tools to docs/using-from-a-notebook.md: {missing}"
+    routed = set()
+    for line in text.splitlines():
+        if line.startswith("- ") and " -> " in line:
+            routed |= set(re.findall(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)+", line.split(" -> ", 1)[1]))
+    assert routed and routed <= names, f"unknown tool names in the routing list: {sorted(routed - names)}"
+
+
+# --- 0.6.2: a percentage passed as a utilisation fraction is rejected, not read as 1,500% ---
+@pytest.mark.asyncio
+@pytest.mark.parametrize("bad", [15, 1.5, 0, -0.1, 150])
+async def test_rightsizing_rejects_non_fraction_cpu_utilization(bad):
+    r = await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=bad)
+    assert "error" in r and "fraction" in r["error"]
+    if bad == 15:
+        assert "Did you mean 0.15?" in r["error"]
+
+
+@pytest.mark.asyncio
+async def test_rightsizing_fraction_still_works_and_ram_is_checked(monkeypatch):
+    from greenpick import server
+    monkeypatch.setattr(server, "_repo", MockCarbonRepository())
+    ok = await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=0.15)
+    assert "error" not in ok and ok["recommended_vcpu"] == 4
+    bad = await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32,
+                                           cpu_utilization=0.15, ram_utilization=20)
+    assert "ram_utilization" in bad["error"] and "0.2" in bad["error"]
+
+
+@pytest.mark.asyncio
+async def test_training_rejects_percentage_utilization():
+    r = await _tool("estimate_training_carbon")(gpu="a100", gpu_count=8, gpu_hours=40, utilization=60)
+    assert "error" in r and "Did you mean 0.6?" in r["error"]