greenpick 0.1.0__py3-none-any.whl

greenpick/__init__.py

@@ -0,0 +1,7 @@
+"""GreenPick — design-time sustainability co-pilot (MCP server).
+
+Greener cloud-region choices with honest carbon + cost + latency tradeoffs,
+delivered inside the vibe-coding loop. Directional guidance, not audited accounting.
+"""
+
+__version__ = "0.1.0"

greenpick/__main__.py

@@ -0,0 +1,18 @@
+"""Entry point: run the GreenPick MCP server over stdio.
+
+    python -m greenpick
+"""
+from __future__ import annotations
+
+import logging
+from .config import SETTINGS
+from .server import mcp
+
+
+def main() -> None:
+    logging.basicConfig(level=getattr(logging, SETTINGS.log_level, logging.INFO))
+    mcp.run()  # stdio transport by default — what MCP clients expect
+
+
+if __name__ == "__main__":
+    main()

greenpick/config.py

@@ -0,0 +1,58 @@
+"""Runtime configuration, read from environment (see .env.example).
+
+Kept tiny and dependency-light: just os.environ, no settings framework.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# Load the project-root .env BEFORE reading settings, with NO third-party dependency.
+# Why not python-dotenv: the MCP client may launch the server with an interpreter where the
+# ambiguous `dotenv` import resolves to the wrong package (collision between python-dotenv and
+# the unrelated `dotenv` pkg), silently skipping the load -> everything defaults to mock. A .env
+# is just KEY=value lines, so we parse it ourselves, deterministically by path. A real environment
+# variable (e.g. set in the MCP server's `env` block) still WINS — we don't overwrite os.environ.
+def _load_project_dotenv() -> None:
+    from pathlib import Path
+    env_path = Path(__file__).resolve().parents[2] / ".env"   # src/greenpick/config.py -> project root
+    try:
+        text = env_path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key = key.strip()
+        val = val.strip().strip('"').strip("'")
+        if key and key not in os.environ:   # real env wins; don't clobber
+            os.environ[key] = val
+
+
+_load_project_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    carbon_source: str          # mock | eia | entsoe | electricitymaps | auto
+    electricitymaps_token: str
+    eia_api_key: str
+    entsoe_token: str
+    cache_ttl_seconds: int
+    log_level: str
+
+    @staticmethod
+    def from_env() -> "Settings":
+        return Settings(
+            carbon_source=os.environ.get("GREENPICK_CARBON_SOURCE", "mock").strip().lower(),
+            electricitymaps_token=os.environ.get("ELECTRICITYMAPS_TOKEN", "").strip(),
+            eia_api_key=os.environ.get("EIA_API_KEY", "").strip(),
+            entsoe_token=os.environ.get("ENTSOE_TOKEN", "").strip(),
+            cache_ttl_seconds=int(os.environ.get("GREENPICK_CACHE_TTL_SECONDS", "1800")),
+            log_level=os.environ.get("GREENPICK_LOG_LEVEL", "INFO").strip().upper(),
+        )
+
+
+SETTINGS = Settings.from_env()

greenpick/data/__init__.py

@@ -0,0 +1,28 @@
+"""Data layer: swappable carbon sources behind one repository interface.
+
+`get_repository()` is the single place that reads config and picks a source, so the rest
+of the app never hard-codes a provider.
+"""
+from __future__ import annotations
+
+from ..config import SETTINGS
+from .repository import CarbonRepository
+from .mock_repository import MockCarbonRepository
+
+
+def get_repository() -> CarbonRepository:
+    source = SETTINGS.carbon_source
+    if source == "electricitymaps":
+        from .electricitymaps_repository import ElectricityMapsRepository
+        return ElectricityMapsRepository(SETTINGS.electricitymaps_token, SETTINGS.cache_ttl_seconds)
+    if source == "eia":
+        from .eia_repository import EIARepository
+        return EIARepository(SETTINGS.eia_api_key, SETTINGS.cache_ttl_seconds)
+    if source == "entsoe":
+        from .entsoe_repository import ENTSOERepository
+        return ENTSOERepository(SETTINGS.entsoe_token, SETTINGS.cache_ttl_seconds)
+    if source == "auto":
+        # Route per region: EIA for US (eia_ba), ENTSO-E for EU (entsoe_eic), else mock.
+        from .auto_repository import AutoRepository
+        return AutoRepository(SETTINGS.eia_api_key, SETTINGS.entsoe_token, SETTINGS.cache_ttl_seconds)
+    return MockCarbonRepository()

greenpick/data/auto_repository.py

@@ -0,0 +1,47 @@
+"""Auto router: pick the right live source per region.
+
+- US regions (have an `eia_ba`)      -> EIA
+- EU regions (have an `entsoe_eic`)  -> ENTSO-E
+- anything else                      -> mock (honestly labelled)
+
+Lets a single GREENPICK_CARBON_SOURCE=auto give live data on both continents.
+"""
+from __future__ import annotations
+
+from ..models import CarbonReading, Provider, HourlyCarbon, ForecastHour
+from .mock_repository import MockCarbonRepository
+from .eia_repository import EIARepository
+from .entsoe_repository import ENTSOERepository
+from .static_data import region_meta
+
+
+class AutoRepository:
+    def __init__(self, eia_key: str, entsoe_token: str, cache_ttl_seconds: int = 1800) -> None:
+        self._eia = EIARepository(eia_key, cache_ttl_seconds)
+        self._entsoe = ENTSOERepository(entsoe_token, cache_ttl_seconds)
+        self._mock = MockCarbonRepository()
+
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        meta = region_meta(provider, region) or {}
+        if meta.get("eia_ba"):
+            return await self._eia.carbon_now(provider, region)
+        if meta.get("entsoe_eic"):
+            return await self._entsoe.carbon_now(provider, region)
+        return await self._mock.carbon_now(provider, region)
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        meta = region_meta(provider, region) or {}
+        if meta.get("eia_ba"):
+            return await self._eia.carbon_history(provider, region)
+        if meta.get("entsoe_eic"):
+            return await self._entsoe.carbon_history(provider, region)
+        return await self._mock.carbon_history(provider, region)
+
+    async def renewable_forecast(self, provider: Provider, region: str, hours_ahead: int = 24
+                                 ) -> list[ForecastHour]:
+        """Forward renewable forecast — only EU (ENTSO-E A69) has a free one. US/other -> []
+        so the scheduling layer degrades to the historical pattern, labelled honestly."""
+        meta = region_meta(provider, region) or {}
+        if meta.get("entsoe_eic"):
+            return await self._entsoe.renewable_forecast(provider, region, hours_ahead)
+        return []

greenpick/data/eia_repository.py

@@ -0,0 +1,156 @@
+"""EIA-930 carbon source (US balancing authorities).
+
+Free US government data — no license tiers or activation gating (unlike Electricity Maps'
+free tier). We pull the latest hourly generation mix by fuel type for a region's balancing
+authority, then weight by per-fuel emission factors to get a directional gCO2/kWh.
+
+Key (free, instant): https://www.eia.gov/opendata/  -> Register.
+Endpoint: GET https://api.eia.gov/v2/electricity/rto/fuel-type-data/data/
+  params: api_key, frequency=hourly, data[0]=value, facets[respondent][]=<BA>,
+          sort by period desc, length=... (we grab the most recent hour's fuels)
+  rows:   { period, respondent, fueltype (COL/NG/NUC/WAT/WND/SUN/...), value (MWh), ... }
+
+Carbon intensity = sum(gen_fuel * factor_fuel) / sum(gen_fuel).  Directional, not audited.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timezone
+
+import httpx
+
+from ..models import CarbonReading, Provider, HourlyCarbon
+from .mock_repository import MockCarbonRepository
+from .static_data import region_meta, emission_factors
+
+log = logging.getLogger("greenpick.eia")
+
+_URL = "https://api.eia.gov/v2/electricity/rto/fuel-type-data/data/"
+
+
+class EIARepository:
+    def __init__(self, api_key: str, cache_ttl_seconds: int = 1800) -> None:
+        self._key = api_key
+        self._ttl = cache_ttl_seconds
+        self._cache: dict[str, tuple[float, CarbonReading]] = {}  # BA -> (fetched_at, reading)
+        self._fallback = MockCarbonRepository()
+        self._warned_no_key = False
+
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        meta = region_meta(provider, region) or {}
+        ba = meta.get("eia_ba")
+
+        if not self._key:
+            if not self._warned_no_key:
+                log.warning("No EIA_API_KEY set — falling back to mock. Register free at "
+                            "https://www.eia.gov/opendata/")
+                self._warned_no_key = True
+            return await self._fallback.carbon_now(provider, region)
+        if not ba:
+            # Non-US region (no balancing authority) -> EIA can't help; mock, labelled.
+            return await self._fallback.carbon_now(provider, region)
+
+        hit = self._cache.get(ba)
+        if hit and (time.time() - hit[0]) < self._ttl:
+            cached = hit[1]
+            return cached.model_copy(update={"region": region, "provider": provider, "quality": "cached"})
+
+        rows = await self._fetch_rows(ba)
+        if rows is None:
+            return await self._fallback.carbon_now(provider, region)
+        reading = self._mix_to_reading(provider, region, ba, rows)
+        if reading is None:
+            return await self._fallback.carbon_now(provider, region)
+        self._cache[ba] = (time.time(), reading)
+        return reading
+
+    async def _fetch_rows(self, ba: str) -> list | None:
+        """Fetch recent hourly fuel rows for a BA. Returns None on auth/network error
+        (caller falls back to mock)."""
+        try:
+            params = {
+                "api_key": self._key,
+                "frequency": "hourly",
+                "data[0]": "value",
+                "facets[respondent][]": ba,
+                "sort[0][column]": "period",
+                "sort[0][direction]": "desc",
+                "length": "2000",   # ~5-7 days of hourly rows x fuels — enough for a daily pattern
+            }
+            async with httpx.AsyncClient(timeout=12) as client:
+                resp = await client.get(_URL, params=params)
+            if resp.status_code in (401, 403):
+                log.warning("EIA rejected the key (HTTP %s) — using mock. Check EIA_API_KEY.",
+                            resp.status_code)
+                return None
+            resp.raise_for_status()
+            return resp.json().get("response", {}).get("data", [])
+        except Exception as e:
+            log.debug("EIA call failed for BA %s (%s) — mock fallback", ba, e)
+            return None
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        """Per-hour carbon intensity from the recent EIA window (same call as carbon_now)."""
+        meta = region_meta(provider, region) or {}
+        ba = meta.get("eia_ba")
+        if not self._key or not ba:
+            return await self._fallback.carbon_history(provider, region)
+        rows = await self._fetch_rows(ba)
+        if not rows:
+            return await self._fallback.carbon_history(provider, region)
+        factors = emission_factors()["factors_g_co2_per_kwh"]
+        # Group fuel rows by hour, compute weighted intensity per hour.
+        by_hour: dict[str, list] = {}
+        for r in rows:
+            by_hour.setdefault(r.get("period"), []).append(r)
+        out: list[HourlyCarbon] = []
+        for period, hour_rows in by_hour.items():
+            total = weighted = 0.0
+            for r in hour_rows:
+                fuel = r.get("fueltype")
+                try:
+                    mwh = float(r.get("value") or 0)
+                except (TypeError, ValueError):
+                    continue
+                if mwh > 0 and fuel in factors:
+                    total += mwh
+                    weighted += mwh * factors[fuel]
+            if total > 0:
+                out.append(HourlyCarbon(period=period, g_co2_per_kwh=round(weighted / total, 1)))
+        return out or await self._fallback.carbon_history(provider, region)
+
+    def _mix_to_reading(self, provider: Provider, region: str, ba: str, rows: list) -> CarbonReading | None:
+        """Take the most recent hour's fuel rows, weight by emission factors -> gCO2/kWh."""
+        if not rows:
+            return None
+        # Rows are sorted period desc; the first row's period is the latest available hour.
+        latest_period = rows[0].get("period")
+        factors = emission_factors()["factors_g_co2_per_kwh"]
+
+        total_mwh = 0.0
+        weighted = 0.0
+        for r in rows:
+            if r.get("period") != latest_period:
+                break  # only the most recent hour
+            fuel = r.get("fueltype")
+            try:
+                mwh = float(r.get("value") or 0)
+            except (TypeError, ValueError):
+                continue
+            if mwh <= 0 or fuel not in factors:
+                continue
+            total_mwh += mwh
+            weighted += mwh * factors[fuel]
+
+        if total_mwh <= 0:
+            return None
+        intensity = weighted / total_mwh
+        return CarbonReading(
+            region=region,
+            provider=provider,
+            g_co2_per_kwh=round(intensity, 1),
+            source="eia",
+            timestamp=str(latest_period or datetime.now(timezone.utc).isoformat()),
+            quality="live",
+        )

greenpick/data/electricitymaps_repository.py

@@ -0,0 +1,104 @@
+"""Electricity Maps free-tier carbon source.
+
+Live grid carbon intensity per zone, with honest degradation:
+  - zone not on the free tier / not mapped  -> mock fallback (labelled quality="mock")
+  - network / rate-limit error              -> mock fallback
+  - bad or missing token                    -> mock fallback (warned once; it's a config issue)
+  - value flagged isEstimated by the API    -> quality="live_estimated" (still real, but modelled)
+
+Free tier + token: https://electricitymaps.com/free-tier
+API: GET https://api.electricitymap.org/v3/carbon-intensity/latest?zone=XX
+     header: auth-token: <token>
+     -> { "carbonIntensity": <gCO2/kWh>, "datetime": "...", "isEstimated": bool, ... }
+"""
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timezone
+
+import httpx
+
+from ..models import CarbonReading, Provider, HourlyCarbon
+from .mock_repository import MockCarbonRepository
+from .static_data import region_meta
+
+log = logging.getLogger("greenpick.electricitymaps")
+
+_BASE = "https://api.electricitymap.org/v3/carbon-intensity/latest"
+
+
+class ElectricityMapsRepository:
+    def __init__(self, token: str, cache_ttl_seconds: int = 1800) -> None:
+        self._token = token
+        self._ttl = cache_ttl_seconds
+        self._cache: dict[str, tuple[float, CarbonReading]] = {}  # zone -> (fetched_at, reading)
+        self._fallback = MockCarbonRepository()
+        self._token_rejected = False   # once a 401/403 is seen, stop calling with a bad key
+        self._warned_no_token = False
+
+    async def carbon_history(self, provider: Provider, region: str) -> list[HourlyCarbon]:
+        # Not implemented for this (unused) source; degrade to the fallback curve.
+        return await self._fallback.carbon_history(provider, region)
+
+    async def carbon_now(self, provider: Provider, region: str) -> CarbonReading:
+        meta = region_meta(provider, region)
+        zone = (meta or {}).get("zone")
+
+        if not self._token:
+            if not self._warned_no_token:
+                log.warning("No ELECTRICITYMAPS_TOKEN set — falling back to mock data. "
+                            "Get a free key at https://electricitymaps.com/free-tier")
+                self._warned_no_token = True
+            return await self._fallback.carbon_now(provider, region)
+
+        if self._token_rejected or not zone:
+            # Bad key already seen, or no zone mapping for this region -> mock, labelled.
+            return await self._fallback.carbon_now(provider, region)
+
+        # Fresh cache hit?
+        hit = self._cache.get(zone)
+        if hit and (time.time() - hit[0]) < self._ttl:
+            cached = hit[1]
+            return cached.model_copy(update={
+                "region": region, "provider": provider,
+                "quality": "cached" if cached.quality in ("live", "live_estimated", "cached") else cached.quality,
+            })
+
+        try:
+            async with httpx.AsyncClient(timeout=8) as client:
+                resp = await client.get(_BASE, params={"zone": zone},
+                                        headers={"auth-token": self._token})
+
+            if resp.status_code in (401, 403):
+                # Config problem, not a per-region issue. Warn once, then stop trying.
+                self._token_rejected = True
+                log.warning("Electricity Maps rejected the token (HTTP %s) — using mock data. "
+                            "Check ELECTRICITYMAPS_TOKEN.", resp.status_code)
+                return await self._fallback.carbon_now(provider, region)
+            if resp.status_code == 404:
+                # Zone not covered on this plan/mapping. Silent per-region fallback.
+                log.debug("Zone %s not available (404) — mock fallback for %s/%s", zone, provider, region)
+                return await self._fallback.carbon_now(provider, region)
+            resp.raise_for_status()
+
+            payload = resp.json()
+            intensity = payload.get("carbonIntensity")
+            if intensity is None:
+                return await self._fallback.carbon_now(provider, region)
+
+            reading = CarbonReading(
+                region=region,
+                provider=provider,
+                g_co2_per_kwh=float(intensity),
+                source="electricitymaps",
+                timestamp=str(payload.get("datetime", datetime.now(timezone.utc).isoformat())),
+                quality="live_estimated" if payload.get("isEstimated") else "live",
+            )
+            self._cache[zone] = (time.time(), reading)
+            return reading
+
+        except Exception as e:
+            # Network/parse/rate-limit -> mock fallback rather than erroring the tool.
+            log.debug("Electricity Maps call failed for zone %s (%s) — mock fallback", zone, e)
+            return await self._fallback.carbon_now(provider, region)

greenpick/data/emission_factors.json

@@ -0,0 +1,35 @@
+{
+  "_comment": "Per-fuel carbon intensity (gCO2eq/kWh), used to turn an EIA fuel-generation mix into a weighted grid carbon intensity. Order-of-magnitude lifecycle-style figures consistent with public literature (IPCC AR5 medians etc.). DIRECTIONAL estimates, not audited factors. Keys are EIA fueltype codes.",
+  "_source": "IPCC AR5 lifecycle emissions medians (approx), rounded. Replace with cited values before any non-directional use.",
+  "factors_g_co2_per_kwh": {
+    "COL": 820,
+    "NG":  490,
+    "OIL": 650,
+    "OTH": 700,
+    "NUC": 12,
+    "WAT": 24,
+    "WND": 11,
+    "SUN": 48,
+    "GEO": 38,
+    "BIO": 230
+  },
+  "_fuel_names": {
+    "COL": "Coal", "NG": "Natural gas", "OIL": "Petroleum", "OTH": "Other",
+    "NUC": "Nuclear", "WAT": "Hydro", "WND": "Wind", "SUN": "Solar",
+    "GEO": "Geothermal", "BIO": "Biomass"
+  },
+  "_comment_entsoe": "Maps ENTSO-E A75 psrType codes to the same per-fuel factors above, so the EU source reuses one emission-factor table. B-codes per ENTSO-E standard.",
+  "entsoe_psrtype_to_factor": {
+    "B01": 230, "B02": 820, "B03": 490, "B04": 490, "B05": 820, "B06": 650,
+    "B07": 650, "B08": 650, "B09": 38, "B10": 24, "B11": 24, "B12": 24,
+    "B14": 12, "B15": 230, "B16": 48, "B17": 230, "B18": 11, "B19": 11, "B20": 24
+  },
+  "_entsoe_psrtype_names": {
+    "B01": "Biomass", "B02": "Lignite", "B03": "Coal gas", "B04": "Natural gas",
+    "B05": "Hard coal", "B06": "Oil", "B07": "Oil shale", "B08": "Peat",
+    "B09": "Geothermal", "B10": "Hydro pumped storage", "B11": "Hydro run-of-river",
+    "B12": "Hydro reservoir", "B14": "Nuclear", "B15": "Other renewable",
+    "B16": "Solar", "B17": "Waste", "B18": "Wind offshore", "B19": "Wind onshore",
+    "B20": "Other"
+  }
+}