greenpick 0.1.0__py3-none-any.whl

greenpick/services/recommender.py

@@ -0,0 +1,203 @@
+"""Assemble the tri-axis recommendation: carbon + cost + latency across candidate regions.
+
+This is the heart of GreenPick's differentiation — not just "which region is cleanest",
+but "cleanest within YOUR latency budget, and here's what it costs you".
+"""
+from __future__ import annotations
+
+from ..models import (
+    Workload, GeoPoint, Provider, RegionCandidate, Recommendation,
+)
+from ..data.repository import CarbonRepository
+from ..data.static_data import iter_regions
+from . import carbon_service, cost_service, latency_service, residency_service
+
+LIMITATIONS = (
+    "Directional guidance, not audited accounting. Grid-zone mapping is approximate; "
+    "carbon is point-in-time (not flow-traced consumption); cost is a ballpark, not a quote; "
+    "latency is a geographic estimate. 'Greener' assumes grid intensity dominates and ignores "
+    "embodied/hardware carbon and provider renewable-energy certificates. "
+    "Also: moving compute to a greener region can incur cross-region/cross-cloud EGRESS cost and "
+    "transfer carbon if your data stays put — run data_locality_egress_check before you move."
+)
+
+
+def _candidate_providers(providers: list[Provider] | None) -> set[str]:
+    return set(providers) if providers else {"aws", "gcp", "azure"}
+
+
+def _assign_ratings(candidates: list[RegionCandidate]) -> None:
+    """Relative R/Y/G per axis across the candidate set (lower is better for all three:
+    carbon intensity, latency, cost). Terciles: best third=green, middle=yellow, worst=red.
+    Transparent-by-construction — it's 'best available among your options', not an absolute
+    judgement. Candidates missing a value for an axis are left unrated for that axis."""
+    def rate(getter, setter):
+        vals = [(c, getter(c)) for c in candidates if getter(c) is not None]
+        if not vals:
+            return
+        ordered = sorted(vals, key=lambda cv: cv[1])  # ascending: lower = better
+        n = len(ordered)
+        for i, (c, _v) in enumerate(ordered):
+            frac = i / n  # 0..1 position (0 = best)
+            setter(c, "green" if frac < 1/3 else "yellow" if frac < 2/3 else "red")
+
+    rate(lambda c: c.carbon.g_co2_per_kwh,
+         lambda c, r: setattr(c, "carbon_rating", r))
+    rate(lambda c: c.latency_ms_estimate,
+         lambda c, r: setattr(c, "latency_rating", r))
+    rate(lambda c: c.est_monthly_cost_usd,
+         lambda c, r: setattr(c, "cost_rating", r))
+
+
+async def compare_regions(
+    repo: CarbonRepository,
+    providers: list[Provider] | None,
+    user_location: GeoPoint,
+    workload: Workload,
+    optimize_for: str = "carbon",       # "carbon" | "balanced"
+    max_added_latency_ms: float | None = None,
+    baseline_region: str | None = None,
+    regions: list[str] | None = None,   # restrict ranking to these region codes
+) -> Recommendation:
+    wanted = _candidate_providers(providers)
+    # Restrict to a caller-supplied candidate set, if given. Always keep the baseline region in
+    # play (you're implicitly comparing against where you are, even if you didn't list it).
+    region_filter: set[str] | None = None
+    if regions:
+        region_filter = {r for r in regions}
+        if baseline_region:
+            region_filter.add(baseline_region)
+
+    candidates: list[RegionCandidate] = []
+    for provider, region, _meta in iter_regions():
+        if provider not in wanted:
+            continue
+        if region_filter is not None and region not in region_filter:
+            continue
+        reading = await carbon_service.carbon_now(repo, provider, region)
+        cand = RegionCandidate(
+            region=region,
+            provider=provider,  # type: ignore[arg-type]
+            carbon=reading,
+            est_monthly_cost_usd=cost_service.estimate_monthly_cost_usd(provider, workload),  # type: ignore[arg-type]
+            latency_ms_estimate=latency_service.estimate_latency_ms(provider, region, user_location),  # type: ignore[arg-type]
+        )
+        candidates.append(cand)
+
+    if not candidates:
+        hint = ""
+        if region_filter is not None:
+            hint = (f" The region filter {sorted(region_filter)} matched nothing in the catalog "
+                    f"for providers {sorted(wanted)} — check the region codes.")
+        return Recommendation(candidates=[], rationale=f"No known regions matched the request.{hint}",
+                              limitations=LIMITATIONS)
+
+    # Carbon ranking across the candidate set.
+    ordered = sorted(candidates, key=lambda c: c.carbon.g_co2_per_kwh)
+    for i, c in enumerate(ordered, start=1):
+        c.carbon_rank = i
+
+    # Per-axis relative R/Y/G ratings (shown alongside raw values so the user sees tradeoffs).
+    _assign_ratings(candidates)
+
+    # Baseline selection:
+    #  - explicit baseline_region if the caller gave one (their current region), else
+    #  - the region NEAREST the user (lowest estimated latency) — the implicit "where I'd
+    #    deploy by default". (Previously fell back to the DIRTIEST region, which produced
+    #    confusing "cleaner than <a region I didn't ask about>; -272ms" tradeoff lines.)
+    baseline = next((c for c in candidates if c.region == baseline_region), None)
+    if baseline is None:
+        with_latency = [c for c in candidates if c.latency_ms_estimate is not None]
+        baseline = (min(with_latency, key=lambda c: c.latency_ms_estimate)  # type: ignore[arg-type]
+                    if with_latency else ordered[-1])
+
+    for c in candidates:
+        if baseline.carbon.g_co2_per_kwh > 0:
+            c.carbon_vs_baseline_pct = round(
+                (c.carbon.g_co2_per_kwh - baseline.carbon.g_co2_per_kwh)
+                / baseline.carbon.g_co2_per_kwh * 100, 1
+            )
+        if c.latency_ms_estimate is not None and baseline.latency_ms_estimate is not None:
+            c.added_latency_ms = round(c.latency_ms_estimate - baseline.latency_ms_estimate, 1)
+        c.tradeoff = _tradeoff_sentence(c, baseline)
+
+    # Latency budget with a tolerance band: a strict "+100ms" that excludes +105ms feels
+    # absurd to a user. Treat the cap as "~", allowing the larger of +15ms or +10% slack.
+    def within_budget(c: RegionCandidate) -> bool:
+        if max_added_latency_ms is None or c.added_latency_ms is None:
+            return True
+        slack = max(15.0, max_added_latency_ms * 0.10)
+        return c.added_latency_ms <= max_added_latency_ms + slack
+
+    eligible = [c for c in ordered if within_budget(c)]
+    pick = (eligible[0] if eligible else ordered[0])
+
+    # "No meaningful improvement" handling: if the best in-budget pick isn't materially
+    # cleaner than the baseline (>=5%), don't dress up the baseline as a win — say staying
+    # put is reasonable and surface what the greener options would cost.
+    MEANINGFUL_PCT = 5.0
+    pick_improvement = -(pick.carbon_vs_baseline_pct or 0.0)  # positive = cleaner than baseline
+    is_baseline_pick = (pick.region == baseline.region and pick.provider == baseline.provider)
+
+    if is_baseline_pick or pick_improvement < MEANINGFUL_PCT:
+        # Find the greenest option overall (ignoring budget) to describe the tradeoff on offer.
+        greenest = ordered[0]
+        greener_improvement = -(greenest.carbon_vs_baseline_pct or 0.0)
+        if greener_improvement < MEANINGFUL_PCT:
+            rationale = (
+                f"Staying on {baseline.provider}/{baseline.region} is reasonable — no candidate "
+                f"region is meaningfully greener (all within ~{MEANINGFUL_PCT:.0f}%)."
+            )
+        else:
+            extra_lat = greenest.added_latency_ms
+            lat_txt = (f", but it adds ~{extra_lat:.0f}ms latency" if extra_lat and extra_lat > 0 else "")
+            rationale = (
+                f"Within your latency budget, {baseline.provider}/{baseline.region} is about as "
+                f"good as it gets — nothing meaningfully greener fits. The greenest option overall "
+                f"is {greenest.provider}/{greenest.region} (~{greener_improvement:.0f}% cleaner{lat_txt}); "
+                f"widen the latency budget to reach it."
+            )
+        recommended = f"{baseline.provider}/{baseline.region}"
+    else:
+        budget_txt = ""
+        if max_added_latency_ms is not None:
+            budget_txt = f" within ~{max_added_latency_ms:.0f}ms added latency"
+        rationale = (
+            f"{pick.provider}/{pick.region} is ~{pick_improvement:.0f}% cleaner than "
+            f"{baseline.provider}/{baseline.region}{budget_txt} "
+            f"({pick.carbon.g_co2_per_kwh:.0f} gCO2/kWh, source={pick.carbon.source}, "
+            f"quality={pick.carbon.quality})."
+        )
+        recommended = f"{pick.provider}/{pick.region}"
+
+    # Residency heads-up: does the recommended region sit in a different jurisdiction than the
+    # baseline (where they are today)? Neutral geographic flag, never a compliance verdict.
+    rec_prov, _, rec_region = recommended.partition("/")
+    residency_note = residency_service.residency_flag(
+        baseline.provider, baseline.region, rec_prov, rec_region,
+    )
+
+    return Recommendation(
+        candidates=sorted(candidates, key=lambda c: c.carbon_rank or 999),
+        recommended_region=recommended,
+        residency_note=residency_note,
+        rationale=rationale,
+        limitations=LIMITATIONS,
+    )
+
+
+def _tradeoff_sentence(c: RegionCandidate, baseline: RegionCandidate) -> str:
+    parts: list[str] = []
+    if c.carbon_vs_baseline_pct is not None and c.region != baseline.region:
+        if c.carbon_vs_baseline_pct < 0:
+            parts.append(f"~{abs(c.carbon_vs_baseline_pct):.0f}% cleaner than {baseline.region}")
+        elif c.carbon_vs_baseline_pct > 0:
+            parts.append(f"~{c.carbon_vs_baseline_pct:.0f}% dirtier than {baseline.region}")
+        else:
+            parts.append(f"same carbon as {baseline.region}")
+    if c.added_latency_ms is not None and c.region != baseline.region:
+        sign = "+" if c.added_latency_ms >= 0 else ""
+        parts.append(f"{sign}{c.added_latency_ms:.0f}ms latency")
+    if c.est_monthly_cost_usd is not None:
+        parts.append(f"~${c.est_monthly_cost_usd:.0f}/mo")
+    return "; ".join(parts) if parts else "baseline"

greenpick/services/residency_service.py

@@ -0,0 +1,53 @@
+"""Data-residency AWARENESS — a geographic flag, NEVER a compliance verdict.
+
+GreenPick's recommendations move compute between regions. If a move crosses a data-residency
+boundary (most importantly, leaving the EEA), a builder handling regulated or personal data needs
+to KNOW — but GreenPick is not qualified to rule on legality, and the legal landscape (adequacy
+decisions, frameworks) shifts constantly. So we encode only the STABLE geographic fact — which
+jurisdiction a region sits in — and raise a neutral heads-up when a move crosses one, with a hard
+disclaimer pointing the user to their own data governance.
+
+What this is:    "this move leaves the EEA — residency rules MAY apply; check your governance."
+What this isNOT: "this move is / isn't GDPR-compliant." We never say that.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..data.static_data import region_meta
+
+# Human labels for the stable jurisdiction tags in regions.json.
+_LABEL = {
+    "EEA": "the EEA (EU + Norway/Iceland/Liechtenstein)",
+    "US": "the United States",
+    "AU": "Australia",
+}
+
+DISCLAIMER = ("GreenPick does NOT assess legal compliance - this is a geographic heads-up only. "
+              "Confirm against your own data-residency / data-governance requirements.")
+
+
+def jurisdiction_of(provider: str, region: str) -> Optional[str]:
+    meta = region_meta(provider, region) or {}
+    return meta.get("jurisdiction")
+
+
+def residency_flag(from_provider: str, from_region: str,
+                   to_provider: str, to_region: str) -> Optional[str]:
+    """Return a neutral residency heads-up if moving from one region to another crosses a
+    jurisdiction boundary, else None. States only geography + the category of concern + the
+    disclaimer. Leaving the EEA is called out specifically (the GDPR transfer trigger)."""
+    j_from = jurisdiction_of(from_provider, from_region)
+    j_to = jurisdiction_of(to_provider, to_region)
+    if not j_from or not j_to or j_from == j_to:
+        return None   # same jurisdiction (or unknown) -> no residency crossing to flag
+
+    to_label = _LABEL.get(j_to, j_to)
+    from_label = _LABEL.get(j_from, j_from)
+    if j_from == "EEA":
+        # The high-stakes direction: data leaving the EEA.
+        return (f"RESIDENCY: this move takes compute from {from_label} to {to_label} - i.e. OUT of "
+                f"the EEA. If the workload handles personal or regulated data, GDPR transfer rules "
+                f"may constrain or prohibit this. {DISCLAIMER}")
+    return (f"RESIDENCY: this move crosses jurisdictions ({from_label} → {to_label}). If the workload "
+            f"handles regulated or personal data, residency rules may apply. {DISCLAIMER}")

greenpick/services/rightsizing_service.py

@@ -0,0 +1,93 @@
+"""Right-sizing — the #1 FinOps finding, with a carbon twin.
+
+Over-provisioning is the most common cloud waste: you pay for (and emit carbon for) capacity you
+don't use. This is a PURE efficiency dual-benefit — dropping to a size that still fits your real
+utilisation cuts BOTH the bill and the carbon, no tradeoff. GreenPick reuses its cost coefficients
+and power model; the user/agent supplies observed utilisation (no billing-account access needed).
+
+Design-time and directional: it's an estimate from the utilisation you report, not a reading of
+your running fleet. We keep sensible headroom so the recommendation never under-provisions.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import Workload, Provider, RightsizingAdvice
+from ..data.repository import CarbonRepository
+from . import carbon_service, cost_service
+
+# Keep this much headroom above observed peak so we don't right-size into a cliff.
+_HEADROOM = 1.4
+# Don't recommend a change unless it saves at least this fraction — avoids noisy micro-advice.
+_MIN_SAVING_PCT = 10.0
+
+
+def _rightsized_dimension(provisioned: float, utilization: Optional[float]) -> float:
+    """Target = observed usage x headroom, floored at a small minimum, never above provisioned
+    (right-sizing only shrinks here). If utilisation is unknown, leave the dimension unchanged."""
+    if utilization is None:
+        return provisioned
+    u = max(0.0, min(1.0, utilization))
+    target = provisioned * u * _HEADROOM
+    target = max(0.5, target)              # floor: don't suggest sub-0.5 vCPU/GB
+    return min(provisioned, round(target, 1))
+
+
+async def rightsizing_check(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+    vcpu: float,
+    ram_gb: float,
+    cpu_utilization: float,
+    ram_utilization: Optional[float] = None,
+    hours_per_month: float = 730,
+) -> RightsizingAdvice:
+    rec_vcpu = _rightsized_dimension(vcpu, cpu_utilization)
+    rec_ram = _rightsized_dimension(ram_gb, ram_utilization)
+
+    now_wl = Workload(vcpu=vcpu, ram_gb=ram_gb, hours_per_month=hours_per_month)
+    rs_wl = Workload(vcpu=rec_vcpu, ram_gb=rec_ram, hours_per_month=hours_per_month)
+
+    reading = await carbon_service.carbon_now(repo, provider, region)
+    cost_now = cost_service.estimate_monthly_cost_usd(provider, now_wl)
+    cost_rs = cost_service.estimate_monthly_cost_usd(provider, rs_wl)
+    carbon_now = carbon_service.estimate_kg_co2_per_month(now_wl, reading)
+    carbon_rs = carbon_service.estimate_kg_co2_per_month(rs_wl, reading)
+
+    usd_saving = round(cost_now - cost_rs, 2) if (cost_now is not None and cost_rs is not None) else None
+    kg_saving = round(carbon_now - carbon_rs, 2)
+    saving_pct = (round((carbon_now - carbon_rs) / carbon_now * 100, 1)
+                  if carbon_now > 0 else None)
+
+    is_oversized = saving_pct is not None and saving_pct >= _MIN_SAVING_PCT
+
+    if is_oversized:
+        usd_txt = f"~${usd_saving:,.0f}/mo" if usd_saving is not None else "cost"
+        rationale = (
+            f"Over-provisioned: at ~{cpu_utilization*100:.0f}% CPU use, {vcpu:g} vCPU / {ram_gb:g} GB "
+            f"is bigger than you need. Right-size to ~{rec_vcpu:g} vCPU / {rec_ram:g} GB (keeps ~40% "
+            f"headroom) to cut ~{saving_pct:.0f}% - {usd_txt} AND ~{kg_saving:.1f} kg CO2/mo. "
+            f"Same work, less waste: the cost and carbon win here are the same action.")
+    else:
+        rationale = (
+            f"Already reasonably sized: at ~{cpu_utilization*100:.0f}% CPU use, {vcpu:g} vCPU / "
+            f"{ram_gb:g} GB has sensible headroom. No material right-sizing saving (< "
+            f"{_MIN_SAVING_PCT:.0f}%) — look to region choice or scheduling instead.")
+
+    return RightsizingAdvice(
+        provider=provider, region=region,
+        provisioned_vcpu=vcpu, provisioned_ram_gb=ram_gb,
+        observed_cpu_utilization=cpu_utilization, observed_ram_utilization=ram_utilization,
+        recommended_vcpu=rec_vcpu, recommended_ram_gb=rec_ram, is_oversized=is_oversized,
+        cost_now_usd_per_month=cost_now, cost_rightsized_usd_per_month=cost_rs,
+        monthly_usd_saving=usd_saving,
+        carbon_now_kg_per_month=carbon_now, carbon_rightsized_kg_per_month=carbon_rs,
+        monthly_kg_co2_saving=kg_saving, saving_pct=saving_pct,
+        carbon_source=reading.source, carbon_quality=reading.quality,
+        rationale=rationale,
+        limitations=("Directional, design-time estimate from the utilisation YOU report — not a "
+                     "reading of your running fleet, and not a quote. Keeps ~40% headroom above "
+                     "observed peak; validate against real load before resizing production. Cost "
+                     "uses the dated static table; carbon = power model x live grid intensity."),
+    )

greenpick/services/scheduling_service.py

@@ -0,0 +1,211 @@
+"""Carbon-aware scheduling: when is a region cleanest to run a deferrable job?
+
+Reuses the repository's recent hourly history. Pure logic over the returned series — the data
+layer decides live-vs-mock and labels quality honestly. Directional, design-time advice
+("set your nightly job to this hour"), not a scheduler.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..models import (
+    SchedulingAdvice, CleanestWindow, HourlyCarbon, Provider,
+    DailyPatternAdvice, HourOfDayStat,
+)
+from ..data.repository import CarbonRepository
+
+
+def _hour_index(period: str) -> Optional[int]:
+    """Map a period label to an absolute hour index so we can detect CONTIGUOUS runs.
+    Handles ISO hours ('2026-10-12T18' / '2026-10-12T18:00') and mock labels ('H18').
+    Returns None if unrecognised (such a point can't anchor a window)."""
+    p = period.strip()
+    if p.startswith("H") and p[1:].isdigit():
+        return int(p[1:])                       # mock: H00..H23, already sequential
+    iso = p if len(p) > 13 else p + ":00:00"    # '...T18' -> '...T18:00:00'
+    iso = iso.replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(iso)
+    except ValueError:
+        try:
+            dt = datetime.strptime(p[:13], "%Y-%m-%dT%H")
+        except ValueError:
+            return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return int(dt.timestamp() // 3600)          # absolute hours since epoch
+
+
+def _best_and_worst_window(series: list[HourlyCarbon], window_hours: int
+                           ) -> tuple[Optional[list[HourlyCarbon]], Optional[float]]:
+    """Slide a window of `window_hours` over the CHRONOLOGICALLY ordered series, considering only
+    runs of genuinely consecutive hours (a gap breaks a window). Returns (best_window_hours,
+    reduction_pct_best_vs_worst), or (None, None) if no contiguous run is long enough."""
+    chrono = sorted(
+        [(h, _hour_index(h.period)) for h in series if _hour_index(h.period) is not None],
+        key=lambda t: t[1],  # type: ignore[arg-type]
+    )
+    best: Optional[tuple[float, list[HourlyCarbon]]] = None
+    worst_avg: Optional[float] = None
+    for i in range(len(chrono) - window_hours + 1):
+        chunk = chrono[i:i + window_hours]
+        # Contiguity: indices must step by exactly 1 across the whole chunk.
+        idxs = [t[1] for t in chunk]
+        if any(idxs[j + 1] - idxs[j] != 1 for j in range(len(idxs) - 1)):
+            continue
+        hours = [t[0] for t in chunk]
+        avg = sum(h.g_co2_per_kwh for h in hours) / window_hours
+        if best is None or avg < best[0]:
+            best = (avg, hours)
+        if worst_avg is None or avg > worst_avg:
+            worst_avg = avg
+    if best is None:
+        return None, None
+    reduction = (round((worst_avg - best[0]) / worst_avg * 100, 1)
+                 if worst_avg and worst_avg > 0 else None)
+    return best[1], reduction
+
+
+async def cleanest_hours(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+    top_n: int = 3,
+    window_hours: Optional[int] = None,
+) -> SchedulingAdvice:
+    """Cleanest recent hours to run a deferrable job. If `window_hours` >= 2, also find the
+    lowest-average CONTIGUOUS run of that many hours — the right question for a job of known
+    duration (you can't start one job across scattered non-adjacent hours)."""
+    history = await repo.carbon_history(provider, region)
+    # Derive source/quality from a current reading (history doesn't carry it).
+    now = await repo.carbon_now(provider, region)
+
+    if not history:
+        return SchedulingAdvice(
+            region=region, provider=provider, source=now.source, quality=now.quality,
+            hours_analyzed=0, cleanest=[],
+            note="No recent hourly history available for this region — can't advise on timing.",
+        )
+
+    ordered = sorted(history, key=lambda h: h.g_co2_per_kwh)
+    cleanest = ordered[:max(1, top_n)]
+    lo = ordered[0].g_co2_per_kwh
+    hi = ordered[-1].g_co2_per_kwh
+    reduction = round((hi - lo) / hi * 100, 1) if hi > 0 else None
+
+    if reduction is not None and reduction >= 10:
+        note = (f"Running during the cleanest hour instead of the dirtiest cuts this region's grid "
+                f"carbon by ~{reduction:.0f}%. Good candidate for time-shifting deferrable work "
+                f"(batch jobs, ETL, backups, training).")
+    else:
+        note = ("This region's grid carbon is fairly flat over the window — time-shifting here "
+                "won't help much; focus on region choice instead.")
+
+    advice = SchedulingAdvice(
+        region=region, provider=provider, source=now.source, quality=now.quality,
+        hours_analyzed=len(history), cleanest=cleanest,
+        dirtiest_g_co2_per_kwh=hi, cleanest_g_co2_per_kwh=lo,
+        potential_reduction_pct=reduction, note=note,
+    )
+
+    # Window mode: the cleanest contiguous run to START a job of this duration.
+    if window_hours and window_hours >= 2:
+        win_hours, win_reduction = _best_and_worst_window(history, window_hours)
+        if win_hours:
+            avg = round(sum(h.g_co2_per_kwh for h in win_hours) / len(win_hours), 1)
+            advice.window = CleanestWindow(
+                window_hours=window_hours,
+                start_period=win_hours[0].period, end_period=win_hours[-1].period,
+                avg_g_co2_per_kwh=avg, hours=win_hours,
+            )
+            advice.window_reduction_pct = win_reduction
+            if win_reduction is not None and win_reduction >= 10:
+                advice.note = (f"For a ~{window_hours}h job, start it at {win_hours[0].period}: that's "
+                               f"the cleanest {window_hours}h window (avg ~{avg:.0f} gCO2/kWh), "
+                               f"~{win_reduction:.0f}% cleaner than the worst {window_hours}h window.")
+            else:
+                advice.note = (f"For a ~{window_hours}h job, the cleanest window starts at "
+                               f"{win_hours[0].period} (avg ~{avg:.0f} gCO2/kWh), but the grid is "
+                               f"fairly flat — timing won't help much here.")
+        else:
+            advice.note = (f"Not enough contiguous history to find a {window_hours}h window; "
+                           f"showing cleanest individual hours instead. " + advice.note)
+
+    return advice
+
+
+async def cleanest_time_of_day(
+    repo: CarbonRepository,
+    provider: Provider,
+    region: str,
+) -> DailyPatternAdvice:
+    """The recurring cleanest time-of-day for a region, for timing a RECURRING job (e.g. a nightly
+    batch you'll run every day). Averages each hour-of-day across the days in the recent window.
+
+    Honest scope: the free data windows are only a few days, so this is a DAILY pattern over N days,
+    not a 7-day day-of-week pattern. We report 'the grid is consistently cleanest around 03:00',
+    not 'Sundays are cleanest'."""
+    history = await repo.carbon_history(provider, region)
+    now = await repo.carbon_now(provider, region)
+
+    limitations = ("Daily pattern over the recent window (a few days of free data), not a 7-day "
+                   "weekly/day-of-week pattern. Hours are in the source's timezone (UTC for EIA/"
+                   "ENTSO-E). Directional — the pattern can shift with weather and season.")
+
+    if not history:
+        return DailyPatternAdvice(
+            region=region, provider=provider, source=now.source, quality=now.quality,
+            days_analyzed=0, hours_analyzed=0,
+            note="No recent hourly history available for this region — can't derive a daily pattern.",
+            limitations=limitations,
+        )
+
+    # Group by hour-of-day (index % 24); track distinct days (index // 24) for an honest count.
+    buckets: dict[int, list[float]] = {}
+    days: set[int] = set()
+    for h in history:
+        idx = _hour_index(h.period)
+        if idx is None:
+            continue
+        hod = idx % 24
+        buckets.setdefault(hod, []).append(h.g_co2_per_kwh)
+        days.add(idx // 24)
+
+    if not buckets:
+        return DailyPatternAdvice(
+            region=region, provider=provider, source=now.source, quality=now.quality,
+            days_analyzed=0, hours_analyzed=len(history),
+            note="Couldn't parse hour-of-day from the history timestamps.",
+            limitations=limitations,
+        )
+
+    stats = [
+        HourOfDayStat(hour_of_day=hod, avg_g_co2_per_kwh=round(sum(v) / len(v), 1),
+                      days_observed=len(v))
+        for hod, v in buckets.items()
+    ]
+    stats.sort(key=lambda s: s.avg_g_co2_per_kwh)   # cleanest-first
+    cleanest = stats[0]
+    dirtiest = stats[-1]
+    reduction = (round((dirtiest.avg_g_co2_per_kwh - cleanest.avg_g_co2_per_kwh)
+                       / dirtiest.avg_g_co2_per_kwh * 100, 1)
+                 if dirtiest.avg_g_co2_per_kwh > 0 else None)
+
+    n_days = max(1, len(days))
+    if reduction is not None and reduction >= 10:
+        note = (f"Over the last ~{n_days} day(s), this region is consistently cleanest around "
+                f"{cleanest.hour_of_day:02d}:00 (avg ~{cleanest.avg_g_co2_per_kwh:.0f} gCO2/kWh) and "
+                f"dirtiest around {dirtiest.hour_of_day:02d}:00 - ~{reduction:.0f}% apart. For a "
+                f"recurring job, standing it up at ~{cleanest.hour_of_day:02d}:00 captures most of it.")
+    else:
+        note = (f"Over the last ~{n_days} day(s), this region's time-of-day pattern is fairly flat; "
+                f"a fixed run-time won't help much — region choice is the bigger lever.")
+
+    return DailyPatternAdvice(
+        region=region, provider=provider, source=now.source, quality=now.quality,
+        days_analyzed=n_days, hours_analyzed=len(history),
+        by_hour_of_day=stats,   # all observed hours-of-day, cleanest first (24 small rows)
+        cleanest_hour_of_day=cleanest.hour_of_day, dirtiest_hour_of_day=dirtiest.hour_of_day,
+        potential_reduction_pct=reduction, note=note, limitations=limitations,
+    )