greenpick 0.5.2__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.5.2
+Version: 0.6.0
 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
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
+  <img src="https://img.shields.io/badge/MCP%20tools-19-0ea5e9" alt="MCP tools: 19" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -52,7 +52,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 19 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -143,7 +143,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-17 tools, grouped by what you're trying to do.
+19 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -178,6 +178,8 @@ See `docs/user-questions-backlog.md`.
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
 | `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
+| `migration_payoff` | Does moving the **data** to the compute's region pay off? Payback in months, one-off vs monthly egress and transfer carbon, net over 12 months. Egress only. |
+| `region_move_justification` | A short paste-ready paragraph for a pull request or decision record, with the carbon, cost, latency and egress numbers and their quality labels. Says so if the move is not an improvement. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 
 ### Instrument & understand

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

@@ -14,7 +14,7 @@
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
+  <img src="https://img.shields.io/badge/MCP%20tools-19-0ea5e9" alt="MCP tools: 19" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -22,7 +22,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 19 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -113,7 +113,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-17 tools, grouped by what you're trying to do.
+19 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -148,6 +148,8 @@ See `docs/user-questions-backlog.md`.
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
 | `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
+| `migration_payoff` | Does moving the **data** to the compute's region pay off? Payback in months, one-off vs monthly egress and transfer carbon, net over 12 months. Egress only. |
+| `region_move_justification` | A short paste-ready paragraph for a pull request or decision record, with the carbon, cost, latency and egress numbers and their quality labels. Says so if the move is not an improvement. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 
 ### Instrument & understand

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

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

@@ -1,4 +1,4 @@
-"""MCP server: exposes GreenPick's 17 tools over FastMCP.
+"""MCP server: exposes GreenPick's 19 tools over FastMCP.
 
 Thin layer — parse/validate inputs, call services, return JSON-friendly dicts. All math
 lives in services/; this file only wires tools to them.
@@ -26,6 +26,7 @@ from .services import (
     carbon_service, recommender, scheduling_service, instance_service, locality_service,
     training_service, forecast_service, serving_service, metric_scaffold_service,
     rightsizing_service, inference_service, offhours_service, typical_ranking_service,
+    justification_service, migration_service,
 )
 from .models import ServingHub
 from .services.data_hint import with_hint
@@ -48,7 +49,8 @@ all GPUs; report wall_clock_hours as the run length), estimate_inference_carbon.
 serving_pattern_advice, greenest_regions_on_average (which regions are normally cleanest in a month); \
 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.
+any residency_note. To weigh moving the data too, use migration_payoff; for a paste-ready paragraph \
+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 \
@@ -369,6 +371,58 @@ async def data_locality_egress_check(
     return with_hint(advice.model_dump())
 
 
+@mcp.tool(annotations=LIVE_DATA_TOOL)
+async def migration_payoff(
+    data_provider: str,
+    data_region: str,
+    compute_provider: str,
+    compute_region: str,
+    data_gb_to_migrate: float,
+    monthly_cross_boundary_gb: float,
+    horizon_months: float = 12,
+) -> dict:
+    """Does moving the DATA to the compute's region pay off, or should it stay? Follow-on to
+    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."""
+    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."}
+    return with_hint(await migration_service.migration_payoff(
+        _repo, data_provider, data_region, compute_provider, compute_region,
+        data_gb_to_migrate, monthly_cross_boundary_gb, horizon_months,
+    ))
+
+
+@mcp.tool(annotations=LIVE_DATA_TOOL)
+async def region_move_justification(
+    from_provider: str,
+    from_region: str,
+    to_provider: str,
+    to_region: str,
+    vcpu: float,
+    ram_gb: float,
+    hours_per_month: float = 730,
+    user_lat: Optional[float] = None,
+    user_lon: Optional[float] = None,
+    monthly_cross_boundary_gb: float = 0,
+) -> dict:
+    """A short, paste-ready paragraph justifying a region choice, for a pull request or decision record.
+    Give the current and proposed region, the service size, and optionally the users' lat/lon (for
+    latency) and the GB a month that would still cross to data left behind (for egress and the net
+    carbon). Returns `pr_text` plus the underlying `facts`. If the move is not an improvement the text
+    says so. Show the user the text and the quality labels; it formats numbers GreenPick already
+    computes, and the wording should be reviewed before it is pasted."""
+    if not 0 < hours_per_month <= 744 or monthly_cross_boundary_gb < 0:
+        return {"error": "hours_per_month must be between 0 and 744, and monthly_cross_boundary_gb >= 0."}
+    return with_hint(await justification_service.region_move_justification(
+        _repo, from_provider, from_region, to_provider, to_region, vcpu, ram_gb,
+        hours_per_month, user_lat, user_lon, monthly_cross_boundary_gb,
+    ))
+
+
 @mcp.tool(annotations=LIVE_DATA_TOOL)
 async def carbon_forecast(
     provider: str, region: str, hours_ahead: int = 24, top_n: int = 5,

greenpick-0.6.0/src/greenpick/services/justification_service.py

@@ -0,0 +1,180 @@
+"""A paste-ready justification for a region choice, for a pull request or decision record.
+
+GreenPick already computes the carbon, cost, latency and egress numbers behind a region move. What a
+team needs next is a short paragraph they can put in the PR. This turns the numbers into that
+paragraph. It adds no new data or maths, and it keeps the honesty labels attached: each carbon figure
+says what kind of reading it is (live, typical, yearly average), and the text says these are design-time
+estimates, not measurements or a quote.
+
+If the move is NOT an improvement, the text says so plainly instead of dressing it up.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..data.repository import CarbonRepository
+from ..data.static_data import network_model, region_meta
+from ..models import GeoPoint, Workload
+from . import carbon_service, cost_service, latency_service, locality_service, residency_service
+
+_QUALITY_PHRASE = {
+    "live": "live grid reading",
+    "cached": "recent cached grid reading",
+    "typical": "typical average for this time of year",
+    "annual_average": "yearly national average",
+    "historical": "recent historical average",
+    "forecast": "forecast",
+    "mock": "illustrative placeholder value",
+}
+
+
+def _phrase(quality: str) -> str:
+    return _QUALITY_PHRASE.get(quality, quality)
+
+
+def _signed_pct(new: float, old: float) -> Optional[float]:
+    if not old:
+        return None
+    return round((new - old) / old * 100, 1)
+
+
+async def region_move_justification(
+    repo: CarbonRepository,
+    from_provider: str, from_region: str,
+    to_provider: str, to_region: str,
+    vcpu: float, ram_gb: float,
+    hours_per_month: float = 730,
+    user_lat: Optional[float] = None, user_lon: Optional[float] = None,
+    monthly_cross_boundary_gb: float = 0,
+) -> dict:
+    wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=hours_per_month)
+    a = await carbon_service.carbon_now(repo, from_provider, from_region)    # type: ignore[arg-type]
+    b = await carbon_service.carbon_now(repo, to_provider, to_region)        # type: ignore[arg-type]
+    kg_a = carbon_service.estimate_kg_co2_per_month(wl, a)
+    kg_b = carbon_service.estimate_kg_co2_per_month(wl, b)
+    kg_saving = round(kg_a - kg_b, 2)
+    carbon_pct = _signed_pct(kg_b, kg_a)
+    intensity_pct = _signed_pct(b.g_co2_per_kwh, a.g_co2_per_kwh)
+
+    cost_a = cost_service.estimate_monthly_cost_usd(from_provider, wl)       # type: ignore[arg-type]
+    cost_b = cost_service.estimate_monthly_cost_usd(to_provider, wl)         # type: ignore[arg-type]
+    cost_delta = round(cost_b - cost_a, 2) if cost_a is not None and cost_b is not None else None
+
+    added_latency = None
+    if user_lat is not None and user_lon is not None:
+        user = GeoPoint(lat=user_lat, lon=user_lon)
+        la = latency_service.estimate_latency_ms(from_provider, from_region, user)   # type: ignore[arg-type]
+        lb = latency_service.estimate_latency_ms(to_provider, to_region, user)       # type: ignore[arg-type]
+        if la is not None and lb is not None:
+            added_latency = round(lb - la)
+
+    # Egress: the data is assumed to STAY in the region you are moving away from.
+    egress_low = egress_high = transfer_kg = net_kg = None
+    locality = "same_region"
+    if monthly_cross_boundary_gb > 0:
+        locality, _sev = locality_service._classify(from_provider, from_region, to_provider, to_region)
+        if locality != "same_region":
+            low, high = locality_service.egress_rate_range(locality, from_provider)
+            if low is not None and high is not None:
+                egress_low = round(monthly_cross_boundary_gb * low, 2)
+                egress_high = round(monthly_cross_boundary_gb * high, 2)
+            transfer_kg = round(monthly_cross_boundary_gb * network_model()["kwh_per_gb_transfer"]
+                                * a.g_co2_per_kwh / 1000.0, 2)
+            net_kg = round(kg_saving - transfer_kg, 2)
+
+    residency = residency_service.residency_flag(from_provider, from_region, to_provider, to_region)
+    size = f"{vcpu:g} vCPU / {ram_gb:g} GB"
+    move = f"{from_provider}/{from_region} to {to_provider}/{to_region}"
+
+    # ---- the paragraph ----
+    parts: list[str] = []
+    if kg_saving > 0:
+        parts.append(
+            f"Moving this {size} service from {from_provider}/{from_region} to "
+            f"{to_provider}/{to_region} cuts its estimated grid carbon from {kg_a:.1f} to {kg_b:.1f} kg "
+            f"CO2 a month ({carbon_pct:+.0f}%), because the grid is cleaner there "
+            f"({a.g_co2_per_kwh:.0f} to {b.g_co2_per_kwh:.0f} gCO2/kWh).")
+    elif kg_saving < 0:
+        parts.append(
+            f"Moving this {size} service from {from_provider}/{from_region} to "
+            f"{to_provider}/{to_region} would RAISE its estimated grid carbon from {kg_a:.1f} to "
+            f"{kg_b:.1f} kg CO2 a month ({carbon_pct:+.0f}%) ({a.g_co2_per_kwh:.0f} to "
+            f"{b.g_co2_per_kwh:.0f} gCO2/kWh), so this move is not justified on carbon.")
+    else:
+        parts.append(
+            f"Moving this {size} service from {from_provider}/{from_region} to "
+            f"{to_provider}/{to_region} makes no estimated difference to grid carbon.")
+    if cost_delta is None:
+        pass
+    elif cost_delta == 0:
+        parts.append("The compute list-price estimate is unchanged.")
+    elif cost_delta < 0:
+        parts.append(f"The compute list-price estimate falls by about ${abs(cost_delta):,.0f} a month.")
+    else:
+        parts.append(f"The compute list-price estimate rises by about ${cost_delta:,.0f} a month.")
+    if added_latency is not None:
+        if added_latency > 0:
+            parts.append(f"Estimated latency for the stated users rises by about {added_latency} ms.")
+        elif added_latency < 0:
+            parts.append(f"Estimated latency for the stated users falls by about {abs(added_latency)} ms.")
+        else:
+            parts.append("Estimated latency for the stated users is about the same.")
+    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:
+            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}, "
+                f"leaving a net saving of about {net_kg:.1f} kg CO2 a month.")
+        else:
+            parts.append(
+                f"But the data stays in {from_provider}/{from_region} (~{monthly_cross_boundary_gb:,.0f} GB "
+                f"a month crossing), which adds about {transfer_kg:.1f} kg CO2{cost_part}: the move "
+                f"backfires on carbon by about {abs(net_kg):.1f} kg a month unless the data moves too.")
+    elif (from_provider, from_region) != (to_provider, to_region):
+        parts.append("Data transfer between the regions was not assessed (no cross-region GB a month "
+                     "was given), so the net effect of keeping data behind is not included.")
+    if residency:
+        parts.append("Data residency: the move crosses jurisdictions, so confirm it against your "
+                     "data-governance requirements.")
+    parts.append(
+        f"Carbon is a {_phrase(a.quality)} for {from_region} and a {_phrase(b.quality)} for {to_region}. "
+        "These are design-time estimates from GreenPick, not measurements or a price quote.")
+    pr_text = " ".join(parts)
+
+    if kg_saving > 0:
+        summary = (f"{move}: about {kg_saving:.1f} kg CO2 a month less"
+                   + (f" ({net_kg:.1f} kg after data transfer)" if net_kg is not None else "")
+                   + (f", {added_latency:+d} ms latency" if added_latency is not None else "") + ".")
+    else:
+        summary = f"{move}: not an improvement on carbon ({kg_saving:+.1f} kg CO2 a month)."
+
+    return {
+        "summary": summary,
+        "pr_text": pr_text,
+        "facts": {
+            "from": f"{from_provider}/{from_region}", "to": f"{to_provider}/{to_region}",
+            "workload": size, "hours_per_month": hours_per_month,
+            "from_g_co2_per_kwh": a.g_co2_per_kwh, "to_g_co2_per_kwh": b.g_co2_per_kwh,
+            "grid_intensity_change_pct": intensity_pct,
+            "from_kg_co2_per_month": kg_a, "to_kg_co2_per_month": kg_b,
+            "monthly_kg_co2_saving": kg_saving, "carbon_change_pct": carbon_pct,
+            "from_carbon_quality": a.quality, "to_carbon_quality": b.quality,
+            "from_carbon_source": a.source, "to_carbon_source": b.source,
+            "compute_cost_change_usd_per_month": cost_delta,
+            "added_latency_ms": added_latency,
+            "locality": locality,
+            "monthly_cross_boundary_gb": monthly_cross_boundary_gb,
+            "est_monthly_egress_usd_low": egress_low, "est_monthly_egress_usd_high": egress_high,
+            "est_monthly_transfer_kg_co2": transfer_kg,
+            "net_monthly_kg_co2_saving_after_transfer": net_kg,
+            "residency_note": residency,
+        },
+        "limitations": (
+            "Formats numbers GreenPick already computes; it checks nothing new. Carbon is a grid-intensity "
+            "estimate (see each quality label), cost is a list-price ballpark that does not vary by region "
+            "within one provider, latency is a geographic estimate, and the egress figure is directional. "
+            "The text assumes the data stays in the region you are moving away from. Review the wording "
+            "before you paste it."),
+    }

{greenpick-0.5.2 → greenpick-0.6.0}/src/greenpick/services/locality_service.py

@@ -57,6 +57,17 @@ def _bump_severity_for_volume(severity: str, gb: float) -> str:
     return order[base]
 
 
+def egress_rate_range(locality: str, data_provider: str) -> tuple[float | None, float | None]:
+    """LOW-HIGH $/GB for moving bytes across the given locality tier (see _classify)."""
+    tier = pricing().get("_egress_tiers_usd_per_gb", {}).get(locality, {})
+    low, high = tier.get("low"), tier.get("high")
+    if locality == "cross_cloud":
+        prov_internet = (pricing().get(data_provider) or {}).get("egress_usd_per_gb")
+        if prov_internet is not None and high is not None:
+            high = max(high, prov_internet)   # don't under-quote this provider's internet rate
+    return low, high
+
+
 async def data_locality_check(
     repo: CarbonRepository,
     compute_provider: Provider,
@@ -89,14 +100,7 @@ async def data_locality_check(
     # Egress is a TIER LADDER by where the bytes cross — not one flat rate. Price the tier we just
     # classified, as a LOW-HIGH range (region-pair rates vary). For cross-cloud/internet the rate
     # is provider-specific, so anchor the high end to the data provider's own internet rate.
-    tiers = pricing().get("_egress_tiers_usd_per_gb", {})
-    tier = tiers.get(locality, {})
-    rate_low = tier.get("low")
-    rate_high = tier.get("high")
-    if locality == "cross_cloud":
-        prov_internet = (pricing().get(data_provider) or {}).get("egress_usd_per_gb")
-        if prov_internet is not None and rate_high is not None:
-            rate_high = max(rate_high, prov_internet)   # don't under-quote this provider's internet rate
+    rate_low, rate_high = egress_rate_range(locality, data_provider)
     cost_low = round(monthly_cross_boundary_gb * rate_low, 2) if rate_low is not None else None
     cost_high = round(monthly_cross_boundary_gb * rate_high, 2) if rate_high is not None else None
 

greenpick-0.6.0/src/greenpick/services/migration_service.py

@@ -0,0 +1,119 @@
+"""Does moving the DATA too pay off, or should it stay put?
+
+The follow-on to data_locality_egress_check. Say you move compute to a greener region but the data
+stays behind. Every month, some GB cross between them and cost egress plus a little transfer carbon.
+You can instead migrate the data once, which costs egress once, and then that traffic stops crossing.
+This works out when the one-off cost is paid back by the monthly cost you stop paying.
+
+The maths is deliberately simple. The one-off move and the monthly flow cross the same boundary, so
+they use the same $/GB rate and the same kWh/GB coefficient. That makes payback in months equal to
+GB to migrate divided by GB a month that would stop crossing, for money and for carbon alike. The
+dollar and kg figures are shown on top so the size of the numbers is visible.
+
+It only weighs egress. Storage price differences, request charges, downtime, double-running during the
+migration and the effort of doing it are NOT included.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..data.repository import CarbonRepository
+from ..data.static_data import network_model
+from . import carbon_service, locality_service, residency_service
+
+
+async def migration_payoff(
+    repo: CarbonRepository,
+    data_provider: str, data_region: str,
+    compute_provider: str, compute_region: str,
+    data_gb_to_migrate: float,
+    monthly_cross_boundary_gb: float,
+    horizon_months: float = 12,
+) -> dict:
+    locality, _sev = locality_service._classify(
+        compute_provider, compute_region, data_provider, data_region)
+    where = f"{data_provider}/{data_region} to {compute_provider}/{compute_region}"
+    if locality == "same_region":
+        return {
+            "summary": "Nothing to migrate: the data is already in the compute region.",
+            "data_location": f"{data_provider}/{data_region}",
+            "compute_location": f"{compute_provider}/{compute_region}",
+            "verdict": "already_co_located",
+        }
+
+    low, high = locality_service.egress_rate_range(locality, data_provider)
+    reading = await carbon_service.carbon_now(repo, data_provider, data_region)   # type: ignore[arg-type]
+    kwh_per_gb = network_model()["kwh_per_gb_transfer"]
+    kg_per_gb = kwh_per_gb * reading.g_co2_per_kwh / 1000.0
+
+    one_off_kg = round(data_gb_to_migrate * kg_per_gb, 2)
+    monthly_kg = round(monthly_cross_boundary_gb * kg_per_gb, 2)
+    one_off_usd = (round(data_gb_to_migrate * low, 2), round(data_gb_to_migrate * high, 2)) \
+        if low is not None and high is not None else (None, None)
+    monthly_usd = (round(monthly_cross_boundary_gb * low, 2), round(monthly_cross_boundary_gb * high, 2)) \
+        if low is not None and high is not None else (None, None)
+
+    payback_months: Optional[float] = None
+    if monthly_cross_boundary_gb > 0:
+        payback_months = round(data_gb_to_migrate / monthly_cross_boundary_gb, 1)
+
+    net_usd = None
+    net_kg = None
+    if payback_months is not None:
+        net_kg = round(horizon_months * monthly_kg - one_off_kg, 2)
+        if one_off_usd[0] is not None:
+            # worst case: pay the high rate to move and avoid only the low rate; best case: the reverse
+            net_usd = (round(horizon_months * monthly_usd[0] - one_off_usd[1], 2),
+                       round(horizon_months * monthly_usd[1] - one_off_usd[0], 2))
+
+    residency = residency_service.residency_flag(
+        data_provider, data_region, compute_provider, compute_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 "
+                   f"{where}, so the one-off migration (~{data_gb_to_migrate:,.0f} GB) has nothing to pay "
+                   "it back. Only move it for other reasons.")
+    elif payback_months <= horizon_months:
+        verdict = "pays_back"
+        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.")
+    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.")
+
+    return {
+        "summary": summary,
+        "verdict": verdict,
+        "data_location": f"{data_provider}/{data_region}",
+        "compute_location": f"{compute_provider}/{compute_region}",
+        "locality": locality,
+        "data_gb_to_migrate": data_gb_to_migrate,
+        "monthly_cross_boundary_gb": monthly_cross_boundary_gb,
+        "horizon_months": horizon_months,
+        "payback_months": payback_months,
+        "egress_rate_usd_per_gb_low": low, "egress_rate_usd_per_gb_high": high,
+        "one_off_migration_egress_usd_low": one_off_usd[0],
+        "one_off_migration_egress_usd_high": one_off_usd[1],
+        "monthly_egress_avoided_usd_low": monthly_usd[0],
+        "monthly_egress_avoided_usd_high": monthly_usd[1],
+        "one_off_transfer_kg_co2": one_off_kg,
+        "monthly_transfer_kg_co2_avoided": monthly_kg,
+        "net_over_horizon_usd_low": net_usd[0] if net_usd else None,
+        "net_over_horizon_usd_high": net_usd[1] if net_usd else None,
+        "net_over_horizon_kg_co2": net_kg,
+        "transfer_carbon_source": reading.source,
+        "transfer_carbon_quality": reading.quality,
+        "residency_note": residency,
+        "limitations": (
+            "Egress only. The cost is a dated list-price ballpark (a low-high range, no free tiers or "
+            "negotiated discounts) and the transfer carbon uses one kWh/GB coefficient that is "
+            "order-of-magnitude. Storage price differences, API/request charges, downtime, running both "
+            "copies during the migration and the work of migrating are NOT included. It assumes moving "
+            "the data stops the monthly traffic entirely. Payback is GB to migrate divided by GB a month "
+            "that stops crossing, because both use the same rate."),
+    }

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: greenpick
-Version: 0.5.2
+Version: 0.6.0
 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
@@ -44,7 +44,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT" />
   <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing" />
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
-  <img src="https://img.shields.io/badge/MCP%20tools-17-0ea5e9" alt="MCP tools: 17" />
+  <img src="https://img.shields.io/badge/MCP%20tools-19-0ea5e9" alt="MCP tools: 19" />
 </p>
 
 A **design-time sustainability co-pilot** that runs as an MCP server inside your vibe-coding
@@ -52,7 +52,7 @@ environment (Cursor / Claude Code / Kiro). Ask it where to deploy, when to run a
 right-size — and it answers with an honest **carbon + cost + latency** tradeoff, in-editor, in
 seconds. (It responds when you ask; auto-nudging on infra-code changes is on the roadmap.)
 
-> **Status: working — 17 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
+> **Status: working — 19 tools.** Live carbon for US (EIA-930), EU (ENTSO-E) and Canada (Hydro-Québec,
 > IESO — no key needed), cross-cloud cost
 > parity (Vantage-refreshed), per-axis R/Y/G ratings, carbon-aware scheduling + day-ahead forecast,
 > GPU-training **and LLM-inference** carbon, right-sizing, serving-pattern and data-locality/residency
@@ -143,7 +143,7 @@ See `docs/user-questions-backlog.md`.
 
 ## MCP tools
 
-17 tools, grouped by what you're trying to do.
+19 tools, grouped by what you're trying to do.
 
 ### Pick a region
 
@@ -178,6 +178,8 @@ See `docs/user-questions-backlog.md`.
 | `rightsizing_check` | Right-sizing (the #1 FinOps win) with a carbon twin: if you're over-provisioned, a smaller size cuts **both** cost and carbon → the right-sized target with monthly $ and kg CO₂ saving. |
 | `offhours_check` | For dev/test/staging that doesn't need to run 24/7: the monthly $ and kg CO2 saved by running it only N hours a week. Compute only, directional. |
 | `data_locality_egress_check` | Warn when running compute away from where your data lives backfires: directional egress $ + coarse transfer carbon, and whether a greener-region move is still a net win. |
+| `migration_payoff` | Does moving the **data** to the compute's region pay off? Payback in months, one-off vs monthly egress and transfer carbon, net over 12 months. Egress only. |
+| `region_move_justification` | A short paste-ready paragraph for a pull request or decision record, with the carbon, cost, latency and egress numbers and their quality labels. Says so if the move is not an improvement. |
 | `serving_pattern_advice` | For a user-facing platform: serve from one region or several? Traffic-weighted latency + carbon, with the multi-region data-sync egress and cross-jurisdiction residency catches. |
 
 ### Instrument & understand

{greenpick-0.5.2 → greenpick-0.6.0}/src/greenpick.egg-info/SOURCES.txt

@@ -40,9 +40,11 @@ src/greenpick/services/data_hint.py
 src/greenpick/services/forecast_service.py
 src/greenpick/services/inference_service.py
 src/greenpick/services/instance_service.py
+src/greenpick/services/justification_service.py
 src/greenpick/services/latency_service.py
 src/greenpick/services/locality_service.py
 src/greenpick/services/metric_scaffold_service.py
+src/greenpick/services/migration_service.py
 src/greenpick/services/offhours_service.py
 src/greenpick/services/recommender.py
 src/greenpick/services/residency_service.py

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

@@ -1802,7 +1802,7 @@ def test_every_tool_declares_all_four_annotation_hints():
     import asyncio
     from greenpick import server
     tools = asyncio.run(server.mcp.list_tools())
-    assert len(tools) == 17
+    assert len(tools) == 19
     for t in tools:
         a = t.annotations
         assert a is not None, t.name
@@ -1909,3 +1909,62 @@ async def test_locality_summary_is_first_key_and_flags_missing_verdict():
     assert "net win" in yes["summary"].lower() and not yes["summary"].startswith("NO NET VERDICT")
     same = (await ls.data_locality_check(MockCarbonRepository(), "aws", "us-east-1", "aws", "us-east-1", 100)).model_dump()
     assert next(iter(same)) == "summary" and same["summary"]
+
+
+# --- 0.6.0: region_move_justification and migration_payoff ---
+@pytest.mark.asyncio
+async def test_justification_win_with_data_left_behind():
+    from greenpick.services import justification_service as js
+    r = await js.region_move_justification(
+        MockCarbonRepository(), "aws", "us-east-1", "aws", "eu-north-1", 4, 16,
+        user_lat=40.71, user_lon=-74.01, monthly_cross_boundary_gb=100)
+    f = r["facts"]
+    assert next(iter(r)) == "summary" and f["monthly_kg_co2_saving"] > 0
+    assert f["net_monthly_kg_co2_saving_after_transfer"] == round(
+        f["monthly_kg_co2_saving"] - f["est_monthly_transfer_kg_co2"], 2)
+    assert f["added_latency_ms"] > 0 and "RESIDENCY" in f["residency_note"]
+    t = r["pr_text"]
+    assert "cuts its estimated grid carbon" in t and "net saving" in t and "not measurements" in t
+
+
+@pytest.mark.asyncio
+async def test_justification_says_so_when_move_is_worse_or_data_assessment_missing():
+    from greenpick.services import justification_service as js
+    worse = await js.region_move_justification(MockCarbonRepository(), "aws", "eu-north-1", "aws", "us-east-1", 4, 16)
+    assert worse["facts"]["monthly_kg_co2_saving"] < 0
+    assert "RAISE" in worse["pr_text"] and "not justified" in worse["pr_text"]
+    assert worse["summary"].endswith("CO2 a month).") and "not an improvement" in worse["summary"]
+    assert "was not assessed" in worse["pr_text"]          # no GB given: says what is not included
+
+
+@pytest.mark.asyncio
+async def test_justification_flags_backfire():
+    from greenpick.services import justification_service as js
+    r = await js.region_move_justification(
+        MockCarbonRepository(), "aws", "us-east-1", "aws", "eu-north-1", 1, 2, monthly_cross_boundary_gb=100000)
+    assert r["facts"]["net_monthly_kg_co2_saving_after_transfer"] < 0 and "backfires" in r["pr_text"]
+
+
+@pytest.mark.asyncio
+async def test_migration_payoff_months_equal_ratio_and_verdicts():
+    from greenpick.services import migration_service as ms
+    args = ("aws", "us-east-1", "aws", "eu-north-1")
+    ok = await ms.migration_payoff(MockCarbonRepository(), *args, 500, 250)
+    assert ok["payback_months"] == 2.0 and ok["verdict"] == "pays_back" and next(iter(ok)) == "summary"
+    assert ok["net_over_horizon_kg_co2"] == round(12 * ok["monthly_transfer_kg_co2_avoided"]
+                                                  - ok["one_off_transfer_kg_co2"], 2)
+    assert ok["net_over_horizon_usd_low"] <= ok["net_over_horizon_usd_high"]
+    slow = await ms.migration_payoff(MockCarbonRepository(), *args, 5000, 100)
+    assert slow["payback_months"] == 50.0 and slow["verdict"] == "does_not_pay_back"
+    none = await ms.migration_payoff(MockCarbonRepository(), *args, 500, 0)
+    assert none["verdict"] == "no_ongoing_traffic" and none["payback_months"] is None
+    same = await ms.migration_payoff(MockCarbonRepository(), "aws", "us-east-1", "aws", "us-east-1", 500, 10)
+    assert same["verdict"] == "already_co_located"
+
+
+@pytest.mark.asyncio
+async def test_new_tools_validate_inputs():
+    bad = await _tool("migration_payoff")("aws", "us-east-1", "aws", "eu-north-1", 0, 10)
+    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