greenpick 0.6.1__tar.gz → 0.6.3__tar.gz

{greenpick-0.6.1/src/greenpick.egg-info → greenpick-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.6.1
+Version: 0.6.3
 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
@@ -226,6 +226,8 @@ flow-traced consumption. Cost is a ballpark, not a quote. Latency is a geographi
 
 ## Quick start
 
+<a href="https://mcprush.com/bithug01/greenpick-mcp"><img src="https://mcprush.com/badge/greenpick-mcp/card.svg" width="220" alt="GreenPick MCP server on mcprush" /></a>
+
 ```bash
 # Python 3.11+
 pip install greenpick          # from PyPI
@@ -308,6 +310,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.1 → greenpick-0.6.3}/README.md

@@ -196,6 +196,8 @@ flow-traced consumption. Cost is a ballpark, not a quote. Latency is a geographi
 
 ## Quick start
 
+<a href="https://mcprush.com/bithug01/greenpick-mcp"><img src="https://mcprush.com/badge/greenpick-mcp/card.svg" width="220" alt="GreenPick MCP server on mcprush" /></a>
+
 ```bash
 # Python 3.11+
 pip install greenpick          # from PyPI
@@ -278,6 +280,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.1 → greenpick-0.6.3}/pyproject.toml

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

@@ -30,6 +30,7 @@ from .services import (
 )
 from .models import ServingHub
 from .services.data_hint import with_hint
+from .services.sources import with_sources
 from .data.typical_repository import typical_context
 
 # Sent to every MCP client at connect. Agents learn a server from its tool list, not its README, and
@@ -54,12 +55,25 @@ for a pull request, use region_move_justification.
 Every carbon figure carries source and quality fields. Report 'typical', 'mock', 'cached' or \
 'historical' values 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 \
+live data on. Results with carbon or cost figures include verify_at: the public page behind each \
+figure, for anyone who wants to check it. 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)
+
+
+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()
 
 
@@ -247,6 +261,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,
@@ -291,9 +310,9 @@ def greenest_regions_on_average(
     norm rather than a single hour; use region_carbon_now for what the grid is doing today. Carbon only
     (no cost or latency; compare_regions_tri_axis weighs all three). Offline, needs no keys. Regions
     labelled annual_average have only a yearly national figure and are not month-specific."""
-    return typical_ranking_service.rank_regions(
+    return with_sources(typical_ranking_service.rank_regions(
         month=month, whole_year=whole_year, providers=providers, regions=regions, top_n=top_n,
-    )
+    ))
 
 
 @mcp.tool(annotations=LIVE_DATA_TOOL)
@@ -470,7 +489,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.1 → greenpick-0.6.3}/src/greenpick/services/data_hint.py

@@ -180,8 +180,10 @@ def build_hint(result: dict) -> Optional[str]:
 
 
 def with_hint(result: dict) -> dict:
-    """Add `live_data_hint` to a tool result that uses fallback data; leave others unchanged."""
+    """Add `live_data_hint` to a tool result that uses fallback data, and `verify_at` (where to check
+    its carbon and cost figures) to any result that has them. Existing fields are left unchanged."""
+    from .sources import with_sources
     hint = build_hint(result)
     if hint:
         result["live_data_hint"] = hint
-    return result
+    return with_sources(result)

{greenpick-0.6.1 → greenpick-0.6.3}/src/greenpick/services/justification_service.py

@@ -122,7 +122,11 @@ async def region_move_justification(
     if net_kg is not None:
         cost_part = (f" and about ${egress_low:,.0f}-${egress_high:,.0f} a month in egress"
                      if egress_low is not None else "")
-        if net_kg > 0:
+        if kg_saving <= 0:
+            parts.append(
+                f"The data stays in {from_provider}/{from_region} (~{monthly_cross_boundary_gb:,.0f} GB a "
+                f"month crossing), which adds about {transfer_kg:.1f} kg CO2{cost_part} on top.")
+        elif net_kg > 0:
             parts.append(
                 f"The data stays in {from_provider}/{from_region} (~{monthly_cross_boundary_gb:,.0f} GB a "
                 f"month crossing), which adds about {transfer_kg:.1f} kg CO2{cost_part}, "

greenpick-0.6.3/src/greenpick/services/sources.py

@@ -0,0 +1,101 @@
+"""Where to check a number: the primary source behind each figure GreenPick reports.
+
+GreenPick's estimates are directional, and its results say so. "Go and verify" is only useful if
+it says WHERE, so every result that contains a carbon figure or a dollar figure also gets a short
+`verify_at` list: which kind of figure, what it is based on, and the public page to check it against.
+
+Kept deliberately small and stable: top-level pages that publish the data (grid operators, the
+cloud providers' own pricing pages), not deep links that move. Additive only: it never changes or
+removes an existing field.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterator
+
+# Carbon: the base source name (after stripping "typical_") -> (what it is, where to check it).
+_CARBON = {
+    "eia": ("US grid data from EIA-930 (hourly generation by fuel)",
+            "https://www.eia.gov/electricity/gridmonitor/"),
+    "entsoe": ("EU grid data from the ENTSO-E Transparency Platform (generation by fuel)",
+               "https://transparency.entsoe.eu/"),
+    "hq": ("Québec grid data from Hydro-Québec open data", "https://donnees.hydroquebec.com/"),
+    "ieso": ("Ontario grid data from IESO", "https://www.ieso.ca/en/Power-Data"),
+    "ember_annual": ("Yearly national grid intensity from Ember, via Our World in Data",
+                     "https://ourworldindata.org/grapher/carbon-intensity-electricity"),
+    "electricitymaps": ("Grid data from Electricity Maps", "https://www.electricitymaps.com/"),
+}
+
+# Cost: provider -> (compute price page, data-transfer price page).
+_PRICING = {
+    "aws": ("https://aws.amazon.com/ec2/pricing/on-demand/",
+            "https://aws.amazon.com/ec2/pricing/on-demand/"),
+    "gcp": ("https://cloud.google.com/compute/vm-instance-pricing",
+            "https://cloud.google.com/vpc/network-pricing"),
+    "azure": ("https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/",
+              "https://azure.microsoft.com/en-us/pricing/details/bandwidth/"),
+}
+_PROVIDER_NAME = {"aws": "AWS", "gcp": "Google Cloud", "azure": "Azure"}
+
+_SOURCE_KEYS = ("source", "carbon_source", "transfer_carbon_source",
+                "from_carbon_source", "to_carbon_source")
+_PROVIDER_KEYS = ("provider", "compute_provider", "data_provider", "from_provider", "to_provider")
+_LOCATION_KEYS = ("recommended_region", "compute_location", "data_location", "from", "to")
+
+
+def _walk(obj: Any) -> Iterator[tuple[str, Any]]:
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            yield k, v
+            yield from _walk(v)
+    elif isinstance(obj, list):
+        for v in obj:
+            yield from _walk(v)
+
+
+def verify_at(result: dict) -> list[dict]:
+    """The primary sources behind the carbon and cost figures in a tool result (may be empty)."""
+    carbon: set[str] = set()
+    providers: set[str] = set()
+    has_cost = has_egress = False
+    for key, value in _walk(result):
+        if key in _SOURCE_KEYS and isinstance(value, str):
+            base = value[len("typical_"):] if value.startswith("typical_") else value
+            if base in _CARBON:
+                carbon.add(base)
+        elif key in _PROVIDER_KEYS and value in _PRICING:
+            providers.add(value)
+        elif key in _LOCATION_KEYS and isinstance(value, str) and "/" in value:
+            prov = value.split("/", 1)[0]
+            if prov in _PRICING:
+                providers.add(prov)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            if "usd" not in key:
+                continue
+            if "egress" in key:
+                has_egress = True
+            elif "cost" in key or "saving" in key:      # compute cost or a saving on it
+                has_cost = True
+
+    out: list[dict] = []
+    for base in sorted(carbon):
+        what, url = _CARBON[base]
+        out.append({"figure": "grid carbon intensity", "based_on": what, "url": url})
+    for prov in sorted(providers):
+        compute_url, transfer_url = _PRICING[prov]
+        name = _PROVIDER_NAME[prov]
+        if has_cost:
+            out.append({"figure": "compute cost", "based_on": f"{name} on-demand list prices (dated)",
+                        "url": compute_url})
+        if has_egress:
+            out.append({"figure": "data-transfer (egress) cost",
+                        "based_on": f"{name} data-transfer prices (dated)", "url": transfer_url})
+    return out
+
+
+def with_sources(result: dict) -> dict:
+    """Add `verify_at` to a result that contains carbon or cost figures; leave others unchanged."""
+    if isinstance(result, dict) and "error" not in result:
+        links = verify_at(result)
+        if links:
+            result["verify_at"] = links
+    return result

{greenpick-0.6.1 → greenpick-0.6.3/src/greenpick.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.6.1
+Version: 0.6.3
 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
@@ -226,6 +226,8 @@ flow-traced consumption. Cost is a ballpark, not a quote. Latency is a geographi
 
 ## Quick start
 
+<a href="https://mcprush.com/bithug01/greenpick-mcp"><img src="https://mcprush.com/badge/greenpick-mcp/card.svg" width="220" alt="GreenPick MCP server on mcprush" /></a>
+
 ```bash
 # Python 3.11+
 pip install greenpick          # from PyPI
@@ -308,6 +310,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.1 → greenpick-0.6.3}/src/greenpick.egg-info/SOURCES.txt

@@ -51,6 +51,7 @@ src/greenpick/services/residency_service.py
 src/greenpick/services/rightsizing_service.py
 src/greenpick/services/scheduling_service.py
 src/greenpick/services/serving_service.py
+src/greenpick/services/sources.py
 src/greenpick/services/training_service.py
 src/greenpick/services/typical_ranking_service.py
 tests/test_services.py

{greenpick-0.6.1 → greenpick-0.6.3}/tests/test_services.py

@@ -1284,7 +1284,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", "live_data_hint"}
+    named = set(re.findall(r"\b[a-z]+(?:_[a-z]+)+\b", text)) - {"wall_clock_hours", "gpu_hours", "residency_note", "live_data_hint", "verify_at"}
     registered = {t.name for t in asyncio.run(server.mcp.list_tools())}
     assert named <= registered, named - registered
 
@@ -1990,3 +1990,104 @@ def test_move_tools_point_to_the_justification_tool():
     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"]
+
+
+# --- 0.6.3: verify_at says where to check each carbon and cost figure (additive only) ---
+def test_verify_at_maps_sources_and_costs():
+    from greenpick.services.sources import verify_at
+    r = {"carbon_source": "typical_eia", "provider": "aws", "cost_now_usd_per_month": 10.0}
+    figs = {(v["figure"], v["url"]) for v in verify_at(r)}
+    assert ("grid carbon intensity", "https://www.eia.gov/electricity/gridmonitor/") in figs
+    assert ("compute cost", "https://aws.amazon.com/ec2/pricing/on-demand/") in figs
+    eg = verify_at({"data_location": "gcp/us-east4", "est_monthly_egress_usd_low": 1.0, "transfer_carbon_source": "ember_annual"})
+    assert {v["figure"] for v in eg} == {"data-transfer (egress) cost", "grid carbon intensity"}
+    assert verify_at({"provider": "aws", "net_over_horizon_usd_low": 3.0}) == []   # not a compute cost
+    assert verify_at({"note": "nothing to check"}) == []
+
+
+@pytest.mark.asyncio
+async def test_tools_add_verify_at_but_not_on_errors(monkeypatch):
+    from greenpick import server
+    monkeypatch.setattr(server, "_repo", TypicalCarbonRepository())
+    r = await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=0.15)
+    assert {v["figure"] for v in r["verify_at"]} == {"grid carbon intensity", "compute cost"}
+    rank = _tool("greenest_regions_on_average")(month=7, regions=["us-west-2", "ap-northeast-1"])
+    assert any("ourworldindata" in v["url"] for v in rank["verify_at"])
+    bad = await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=15)
+    assert "error" in bad and "verify_at" not in bad
+
+
+# --- The notebook starter prompt (docs/using-from-a-notebook.md) relies on these fields. ---
+# Testers and workshop attendees run that prompt against whatever version pip installs, so a
+# release must never rename or drop them.
+@pytest.mark.asyncio
+async def test_fields_the_notebook_prompt_relies_on(monkeypatch):
+    from greenpick import server
+    monkeypatch.setattr(server, "_repo", TypicalCarbonRepository())
+    now = await _tool("region_carbon_now")(provider="aws", region="us-east-1")
+    assert {"source", "quality", "live_data_hint"} <= set(now)
+    eg = await _tool("data_locality_egress_check")(compute_provider="aws", compute_region="eu-north-1",
+                                                   data_provider="aws", data_region="us-east-1",
+                                                   monthly_cross_boundary_gb=100)
+    assert next(iter(eg)) == "summary" and eg["summary"].startswith("NO NET VERDICT")
+    assert {"residency_note", "limitations"} <= set(eg)
+    mp = await _tool("migration_payoff")("aws", "us-east-1", "aws", "eu-north-1", 2000, 300)
+    assert next(iter(mp)) == "summary" and "net_over_horizon_usd_low" in mp and "net_over_horizon_usd_high" in mp
+    pr = await _tool("region_move_justification")("aws", "us-east-1", "aws", "eu-north-1", 4, 16)
+    assert next(iter(pr)) == "summary" and pr["pr_text"]
+    off = await _tool("offhours_check")(provider="aws", region="us-east-1", vcpu=4, ram_gb=16, hours_per_week_on=50)
+    assert {"monthly_usd_saving", "limitations"} <= set(off)
+    assert "error" in await _tool("offhours_check")(provider="aws", region="us-east-1", vcpu=4, ram_gb=16, hours_per_week_on=200)
+    assert "error" in await _tool("rightsizing_check")(provider="aws", region="us-east-1", vcpu=8, ram_gb=32, cpu_utilization=15)
+
+
+@pytest.mark.asyncio
+async def test_reverse_pr_text_does_not_repeat_backfire():
+    from greenpick.services import justification_service as js
+    r = await js.region_move_justification(MockCarbonRepository(), "aws", "eu-north-1", "aws", "us-east-1",
+                                           4, 16, monthly_cross_boundary_gb=100)
+    assert "would RAISE" in r["pr_text"] and "backfires" not in r["pr_text"]
+    assert "unless the data moves too" not in r["pr_text"] and "on top." in r["pr_text"]