Batch 11: Environment Model — park + game-time weather + wind-direction overlay

- models/stadium_lookup.py: 30-park registry (lat/lon/cf_bearing) + resolve_stadium()
- models/weather_provider.py: Open-Meteo hourly fetch aligned to scheduled game time
- models/environment_model.py: park adj + weather adj + wind bucket → env_hr/hit/tb2p boosts
- data/schedule.py: populate venue + game_datetime_utc from MLB Stats API; WBC schema parity
- live_fair_simulator_v3.py: replace Phase C2 with additive env overlay; env_adj hoisted outside batter loop; 15 new output fields

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

data/schedule.py

@@ -182,6 +182,7 @@ def _fetch_wbc_schedule_for_date(date_str: str) -> pd.DataFrame:
                     "away_errors": None,
                     "home_errors": None,
                     "venue": "",
+                    "game_datetime_utc": "",
                     "tv": tv,
                     "start_time_et": start_time_et,
                     "sport_id": 51,
@@ -269,7 +270,8 @@ def _fetch_mlb_schedule_for_date(date_str: str) -> pd.DataFrame:
                         "home_hits": None,
                         "away_errors": None,
                         "home_errors": None,
-                        "venue": "",
+                        "venue": str((game.get("venue", {}) or {}).get("name", "") or "").strip(),
+                        "game_datetime_utc": str(game.get("gameDate", "") or "").strip(),
                         "tv": tv,
                         "start_time_et": start_time_et,
                         "sport_id": 1,

models/environment_model.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import logging
+
+from features.park_factors import venue_hr_factor, venue_run_factor
+from models.stadium_lookup import resolve_stadium
+from models.weather_provider import fetch_game_time_weather
+
+logger = logging.getLogger(__name__)
+
+
+def _angular_diff(a: float, b: float) -> float:
+    """Return the absolute angular difference in [0, 180]."""
+    diff = abs((a - b) % 360)
+    if diff > 180:
+        diff = 360 - diff
+    return diff
+
+
+def compute_wind_direction_bucket(wind_deg: float | None, cf_bearing: float | None) -> str:
+    """
+    Classify wind direction relative to center field.
+
+    Returns one of: "out", "in", "cross", "neutral"
+
+    Meteorological convention: wind_deg = direction FROM which wind blows.
+      - Wind blowing OUT (toward CF): wind_deg ≈ (cf_bearing + 180) % 360
+      - Wind blowing IN (from CF): wind_deg ≈ cf_bearing
+    """
+    if wind_deg is None or cf_bearing is None:
+        return "neutral"
+
+    try:
+        wind_deg = float(wind_deg)
+        cf_bearing = float(cf_bearing)
+    except (TypeError, ValueError):
+        return "neutral"
+
+    out_direction = (cf_bearing + 180.0) % 360.0
+    diff_out = _angular_diff(wind_deg, out_direction)
+    diff_in = _angular_diff(wind_deg, cf_bearing)
+
+    if diff_out < 45.0:
+        return "out"
+    elif diff_in < 45.0:
+        return "in"
+    elif diff_out < 120.0 or diff_in < 120.0:
+        return "cross"
+    else:
+        return "neutral"
+
+
+def compute_park_adjustment(stadium: dict | None) -> dict:
+    """
+    Compute additive park-factor boosts using features/park_factors.py.
+
+    Conversion from multiplicative factors:
+      park_hr_boost   = hr_fac - 1.0
+      park_hit_boost  = (run_fac - 1.0) * 0.40
+      park_tb2p_boost = (hr_fac - 1.0) * 0.60 + (run_fac - 1.0) * 0.30
+    """
+    neutral = {
+        "park_hr_boost": 0.0,
+        "park_hit_boost": 0.0,
+        "park_tb2p_boost": 0.0,
+        "park_run_env_score": 0.0,
+        "park_reason_tags": [],
+    }
+
+    if stadium is None:
+        return neutral
+
+    canonical = stadium.get("canonical_name", "")
+    if not canonical:
+        return neutral
+
+    try:
+        hr_fac = venue_hr_factor(canonical)
+        run_fac = venue_run_factor(canonical)
+
+        park_hr_boost = hr_fac - 1.0
+        park_hit_boost = (run_fac - 1.0) * 0.40
+        park_tb2p_boost = (hr_fac - 1.0) * 0.60 + (run_fac - 1.0) * 0.30
+        park_run_env_score = (park_hr_boost + park_hit_boost) / 2.0
+
+        tags = []
+        if abs(park_hr_boost) >= 0.05:
+            direction = "HR++" if park_hr_boost > 0 else "HR--"
+            tags.append(f"Park {direction} ({canonical})")
+
+        return {
+            "park_hr_boost": park_hr_boost,
+            "park_hit_boost": park_hit_boost,
+            "park_tb2p_boost": park_tb2p_boost,
+            "park_run_env_score": park_run_env_score,
+            "park_reason_tags": tags,
+        }
+
+    except Exception as e:
+        logger.debug(f"[environment_model] compute_park_adjustment error: {e}")
+        return neutral
+
+
+def compute_weather_adjustment(
+    temp_f: float | None,
+    wind_mph: float | None,
+    wind_bucket: str,
+) -> dict:
+    """
+    Compute additive weather boosts from temperature + wind speed × wind direction.
+
+    Temperature component:
+      HR:   (temp - 70) × 0.0015, clamp ±0.030
+      Hit:  (temp - 70) × 0.0004, clamp ±0.010
+      TB2P: (temp - 70) × 0.0008, clamp ±0.020
+
+    Wind speed base (neutral-direction component):
+      HR:   wind_mph × 0.0005, clamp ±0.015
+      Hit:  wind_mph × 0.0001, clamp ±0.005
+      TB2P: wind_mph × 0.0002, clamp ±0.008
+
+    Wind direction multipliers applied to wind speed component:
+      out    → HR×2.0,  Hit×0.5, TB2P×1.5
+      in     → HR×-2.0, Hit×-0.3, TB2P×-1.2
+      cross  → HR×0.2,  Hit×0.1, TB2P×0.2
+      neutral→ HR×1.0,  Hit×0.2, TB2P×0.7
+    """
+    # Temperature adjustments
+    if temp_f is not None:
+        try:
+            t = float(temp_f)
+            temp_hr = max(-0.030, min(0.030, (t - 70.0) * 0.0015))
+            temp_hit = max(-0.010, min(0.010, (t - 70.0) * 0.0004))
+            temp_tb2p = max(-0.020, min(0.020, (t - 70.0) * 0.0008))
+        except (TypeError, ValueError):
+            temp_hr = temp_hit = temp_tb2p = 0.0
+    else:
+        temp_hr = temp_hit = temp_tb2p = 0.0
+
+    # Wind speed base
+    if wind_mph is not None:
+        try:
+            w = float(wind_mph)
+            wind_base_hr = max(-0.015, min(0.015, w * 0.0005))
+            wind_base_hit = max(-0.005, min(0.005, w * 0.0001))
+            wind_base_tb2p = max(-0.008, min(0.008, w * 0.0002))
+        except (TypeError, ValueError):
+            wind_base_hr = wind_base_hit = wind_base_tb2p = 0.0
+    else:
+        wind_base_hr = wind_base_hit = wind_base_tb2p = 0.0
+
+    _multipliers = {
+        "out":     {"hr":  2.0, "hit":  0.5, "tb2p":  1.5},
+        "in":      {"hr": -2.0, "hit": -0.3, "tb2p": -1.2},
+        "cross":   {"hr":  0.2, "hit":  0.1, "tb2p":  0.2},
+        "neutral": {"hr":  1.0, "hit":  0.2, "tb2p":  0.7},
+    }
+    mult = _multipliers.get(wind_bucket, _multipliers["neutral"])
+
+    weather_hr = temp_hr + wind_base_hr * mult["hr"]
+    weather_hit = temp_hit + wind_base_hit * mult["hit"]
+    weather_tb2p = temp_tb2p + wind_base_tb2p * mult["tb2p"]
+    weather_run_env_score = (weather_hr + weather_hit) / 2.0
+
+    tags = []
+    w_val = float(wind_mph or 0)
+    if wind_bucket == "out" and w_val >= 10:
+        tags.append(f"Wind out {w_val:.0f}mph")
+    elif wind_bucket == "in" and w_val >= 10:
+        tags.append(f"Wind in {w_val:.0f}mph")
+    t_val = float(temp_f or 72)
+    if t_val >= 85:
+        tags.append(f"Hot {t_val:.0f}F")
+    elif t_val <= 50:
+        tags.append(f"Cold {t_val:.0f}F")
+
+    return {
+        "weather_hr_boost": weather_hr,
+        "weather_hit_boost": weather_hit,
+        "weather_tb2p_boost": weather_tb2p,
+        "weather_run_env_score": weather_run_env_score,
+        "weather_reason_tags": tags,
+    }
+
+
+def compute_environment_adjustment(game_row: dict, weather_row: dict | None = None) -> dict:
+    """
+    Full environment overlay: venue lookup → stadium coordinates →
+    game-time weather (Open-Meteo) → wind-direction-aware adjustments →
+    combined env dict.
+
+    Safe failure: all boosts default to 0.0 on any lookup/fetch error.
+    """
+    venue = str(game_row.get("venue", "") or "").strip()
+    game_datetime_utc = str(game_row.get("game_datetime_utc", "") or "").strip()
+
+    # Resolve stadium from venue name
+    stadium = resolve_stadium(venue) if venue else None
+
+    # Attempt live game-time weather fetch from Open-Meteo
+    live_weather = None
+    if stadium and game_datetime_utc:
+        try:
+            live_weather = fetch_game_time_weather(
+                lat=stadium["lat"],
+                lon=stadium["lon"],
+                game_datetime_utc=game_datetime_utc,
+            )
+        except Exception as e:
+            logger.debug(f"[environment_model] live weather fetch failed: {e}")
+
+    # Fall back to legacy weather_row if live fetch failed/skipped
+    wx = live_weather if live_weather is not None else (weather_row or None)
+    weather_game_time_used = live_weather is not None
+
+    # Extract weather values (with safe casting)
+    temp_f = wind_mph = wind_deg = None
+    if wx:
+        def _safe_float(val):
+            if val is None:
+                return None
+            try:
+                return float(val)
+            except (TypeError, ValueError):
+                return None
+
+        temp_f = _safe_float(wx.get("temperature_f"))
+        wind_mph = _safe_float(wx.get("wind_speed_mph"))
+        wind_deg = _safe_float(wx.get("wind_direction_deg"))
+
+    # Wind direction classification
+    cf_bearing = stadium.get("cf_bearing") if stadium else None
+    wind_bucket = compute_wind_direction_bucket(wind_deg, cf_bearing)
+
+    # Park and weather adjustments
+    park_adj = compute_park_adjustment(stadium)
+    weather_adj = compute_weather_adjustment(temp_f, wind_mph, wind_bucket)
+
+    # Combine
+    env_hr_boost = park_adj["park_hr_boost"] + weather_adj["weather_hr_boost"]
+    env_hit_boost = park_adj["park_hit_boost"] + weather_adj["weather_hit_boost"]
+    env_tb2p_boost = park_adj["park_tb2p_boost"] + weather_adj["weather_tb2p_boost"]
+    env_run_env_score = (park_adj["park_run_env_score"] + weather_adj["weather_run_env_score"]) / 2.0
+    reason_tags = park_adj["park_reason_tags"] + weather_adj["weather_reason_tags"]
+
+    # Hard clamps
+    env_hr_boost = max(-0.10, min(0.15, env_hr_boost))
+    env_hit_boost = max(-0.05, min(0.08, env_hit_boost))
+    env_tb2p_boost = max(-0.08, min(0.12, env_tb2p_boost))
+
+    return {
+        # Combined outputs
+        "env_hr_boost": env_hr_boost,
+        "env_hit_boost": env_hit_boost,
+        "env_tb2p_boost": env_tb2p_boost,
+        "env_run_env_score": env_run_env_score,
+        "env_reason_tags": reason_tags,
+        # Park sub-fields
+        "park_hr_boost": park_adj["park_hr_boost"],
+        "park_hit_boost": park_adj["park_hit_boost"],
+        "park_tb2p_boost": park_adj["park_tb2p_boost"],
+        # Weather sub-fields
+        "weather_hr_boost": weather_adj["weather_hr_boost"],
+        "weather_hit_boost": weather_adj["weather_hit_boost"],
+        "weather_tb2p_boost": weather_adj["weather_tb2p_boost"],
+        # Debug / metadata
+        "stadium_name_used": stadium.get("canonical_name") if stadium else None,
+        "stadium_lat": stadium.get("lat") if stadium else None,
+        "stadium_lon": stadium.get("lon") if stadium else None,
+        "weather_game_time_used": weather_game_time_used,
+        "wind_direction_bucket": wind_bucket,
+    }

models/live_fair_simulator_v3.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 
 import pandas as pd
-from features.park_factors import venue_hr_factor, weather_hr_adjustment
+from models.environment_model import compute_environment_adjustment
 from models.family_zone_profile_store import (
     build_batter_family_zone_feature_row,
     build_pitcher_family_zone_feature_row,
@@ -62,6 +62,12 @@ def build_upcoming_simulated_rows(
     bullpen_context = build_bullpen_context(game_row, pitcher_row)
     bullpen_adj = compute_bullpen_adjustment(bullpen_context)
 
+    # Batch 11: Environment overlay — computed once per game (venue/datetime don't change per batter)
+    env_adj = compute_environment_adjustment(game_row=game_row, weather_row=weather_row)
+    env_hr_boost   = float(env_adj.get("env_hr_boost",   0.0) or 0.0)
+    env_hit_boost  = float(env_adj.get("env_hit_boost",  0.0) or 0.0)
+    env_tb2p_boost = float(env_adj.get("env_tb2p_boost", 0.0) or 0.0)
+
     rows: list[dict] = []
 
     for slot, batter_name in slots:
@@ -351,29 +357,14 @@ def build_upcoming_simulated_rows(
             except Exception as e:
                 logger.debug(f"[simulator] pull_air_rate adjustment skipped: {e}")
 
-        # Phase C2: Park factor + weather HR/hit adjustment
-        venue = str(game_row.get("venue", "") or "").strip().lower()
-        temp_f = float(weather_row.get("temperature_f", 72.0) or 72.0) if weather_row else None
-        wind_mph = float(weather_row.get("wind_speed_mph", 0.0) or 0.0) if weather_row else None
-        park_hr_fac = venue_hr_factor(venue)
-        weather_adj_factor = weather_hr_adjustment(temp_f, wind_mph)
-        combined_park_factor = park_hr_fac * weather_adj_factor
-
-        batter_baseline["hr_prob_base"] = min(
-            0.30,
-            max(
-                0.005,
-                float(batter_baseline.get("hr_prob_base", 0.03) or 0.03) * combined_park_factor,
-            ),
-        )
-        tb2p_fac = 1.0 + (combined_park_factor - 1.0) * 0.60
-        batter_baseline["tb2p_prob_base"] = min(
-            0.45,
-            max(
-                0.03,
-                float(batter_baseline.get("tb2p_prob_base", 0.10) or 0.10) * tb2p_fac,
-            ),
-        )
+        # Batch 11: Apply environment overlay (env_adj computed once per game before loop)
+        batter_baseline["hit_prob_base"] = min(0.55, max(0.05,
+            float(batter_baseline.get("hit_prob_base", 0.15) or 0.15) + env_hit_boost))
+        batter_baseline["hr_prob_base"] = min(0.30, max(0.005,
+            float(batter_baseline.get("hr_prob_base", 0.03) or 0.03) + env_hr_boost))
+        tb2p_fac = 1.0 + env_tb2p_boost
+        batter_baseline["tb2p_prob_base"] = min(0.45, max(0.03,
+            float(batter_baseline.get("tb2p_prob_base", 0.10) or 0.10) * tb2p_fac))
 
         # Phase E4: Platoon (handedness) adjustment
         batter_stand = batter_features.get("batter_stand", "R")
@@ -461,6 +452,7 @@ def build_upcoming_simulated_rows(
             + context_adj["reason_tags"][:2]
             + bullpen_adj["reason_tags"][:2]
             + traj_adj.get("reason_tags", [])[:1]
+            + env_adj.get("env_reason_tags", [])[:1]
         )
 
         if batter_features.get("ev90") is not None:
@@ -543,6 +535,22 @@ def build_upcoming_simulated_rows(
                 "traj_hit_boost": traj_adj.get("hit_adj"),
                 "traj_hr_boost": traj_adj.get("hr_adj"),
                 "traj_tb2p_boost": traj_adj.get("tb2p_adj"),
+
+                "weather_hr_boost": env_adj.get("weather_hr_boost"),
+                "weather_hit_boost": env_adj.get("weather_hit_boost"),
+                "weather_tb2p_boost": env_adj.get("weather_tb2p_boost"),
+                "park_hr_boost": env_adj.get("park_hr_boost"),
+                "park_hit_boost": env_adj.get("park_hit_boost"),
+                "park_tb2p_boost": env_adj.get("park_tb2p_boost"),
+                "env_hr_boost": env_adj.get("env_hr_boost"),
+                "env_hit_boost": env_adj.get("env_hit_boost"),
+                "env_tb2p_boost": env_adj.get("env_tb2p_boost"),
+                "env_run_env_score": env_adj.get("env_run_env_score"),
+                "stadium_name_used": env_adj.get("stadium_name_used"),
+                "stadium_lat": env_adj.get("stadium_lat"),
+                "stadium_lon": env_adj.get("stadium_lon"),
+                "weather_game_time_used": env_adj.get("weather_game_time_used"),
+                "wind_direction_bucket": env_adj.get("wind_direction_bucket"),
             }
         )
 

models/stadium_lookup.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+# All 30 MLB stadiums + special international venues.
+# Keys are canonical lowercase names matching features/park_factors.py.
+# cf_bearing: compass degrees from home plate → center field (0=N, 90=E, 180=S, 270=W).
+# Meteorological note: wind_direction_deg = direction FROM which wind blows.
+
+STADIUM_REGISTRY: dict[str, dict] = {
+    # ── AL East ──────────────────────────────────────────────────────────────
+    "fenway park": {
+        "canonical_name": "fenway park",
+        "lat": 42.3467,
+        "lon": -71.0972,
+        "cf_bearing": 95.0,
+        "aliases": ["fenway", "fenway park"],
+    },
+    "yankee stadium": {
+        "canonical_name": "yankee stadium",
+        "lat": 40.8296,
+        "lon": -73.9262,
+        "cf_bearing": 230.0,
+        "aliases": ["yankee", "new yankee stadium"],
+    },
+    "oriole park at camden yards": {
+        "canonical_name": "oriole park at camden yards",
+        "lat": 39.2838,
+        "lon": -76.6218,
+        "cf_bearing": 350.0,
+        "aliases": ["camden yards", "oriole park", "camden"],
+    },
+    "rogers centre": {
+        "canonical_name": "rogers centre",
+        "lat": 43.6414,
+        "lon": -79.3894,
+        "cf_bearing": 255.0,
+        "aliases": ["rogers center", "rogers", "skydome"],
+    },
+    "tropicana field": {
+        "canonical_name": "tropicana field",
+        "lat": 27.7683,
+        "lon": -82.6534,
+        "cf_bearing": 325.0,
+        "aliases": ["tropicana", "the trop", "trop"],
+    },
+    # ── AL Central ────────────────────────────────────────────────────────────
+    "guaranteed rate field": {
+        "canonical_name": "guaranteed rate field",
+        "lat": 41.8299,
+        "lon": -87.6338,
+        "cf_bearing": 355.0,
+        "aliases": ["guaranteed rate", "comiskey park", "us cellular field", "rate field"],
+    },
+    "progressive field": {
+        "canonical_name": "progressive field",
+        "lat": 41.4955,
+        "lon": -81.6850,
+        "cf_bearing": 10.0,
+        "aliases": ["progressive", "jacobs field", "the jake"],
+    },
+    "comerica park": {
+        "canonical_name": "comerica park",
+        "lat": 42.3390,
+        "lon": -83.0485,
+        "cf_bearing": 340.0,
+        "aliases": ["comerica", "tiger stadium"],
+    },
+    "kauffman stadium": {
+        "canonical_name": "kauffman stadium",
+        "lat": 39.0517,
+        "lon": -94.4803,
+        "cf_bearing": 0.0,
+        "aliases": ["kauffman", "royals stadium", "ewing kauffman"],
+    },
+    "target field": {
+        "canonical_name": "target field",
+        "lat": 44.9817,
+        "lon": -93.2781,
+        "cf_bearing": 340.0,
+        "aliases": ["target", "twins field"],
+    },
+    # ── AL West ───────────────────────────────────────────────────────────────
+    "minute maid park": {
+        "canonical_name": "minute maid park",
+        "lat": 29.7572,
+        "lon": -95.3555,
+        "cf_bearing": 330.0,
+        "aliases": ["minute maid", "enron field", "astros park"],
+    },
+    "angel stadium": {
+        "canonical_name": "angel stadium",
+        "lat": 33.8003,
+        "lon": -117.8827,
+        "cf_bearing": 0.0,
+        "aliases": ["angel stadium of anaheim", "angels stadium", "big a"],
+    },
+    "t-mobile park": {
+        "canonical_name": "t-mobile park",
+        "lat": 47.5912,
+        "lon": -122.3321,
+        "cf_bearing": 335.0,
+        "aliases": ["t mobile park", "tmobile park", "safeco field", "t-mobile"],
+    },
+    "athletics ballpark": {
+        "canonical_name": "athletics ballpark",
+        "lat": 38.5802,
+        "lon": -121.5168,
+        "cf_bearing": 10.0,
+        "aliases": [
+            "sutter health park",
+            "oakland coliseum",
+            "oakland-alameda county coliseum",
+            "the coliseum",
+            "ringcentral coliseum",
+            "athletics",
+        ],
+    },
+    "globe life field": {
+        "canonical_name": "globe life field",
+        "lat": 32.7473,
+        "lon": -97.0824,
+        "cf_bearing": 330.0,
+        "aliases": ["globe life", "rangers ballpark", "globe life park"],
+    },
+    # ── NL East ───────────────────────────────────────────────────────────────
+    "truist park": {
+        "canonical_name": "truist park",
+        "lat": 33.8906,
+        "lon": -84.4677,
+        "cf_bearing": 315.0,
+        "aliases": ["truist", "suntrust park", "braves park"],
+    },
+    "citi field": {
+        "canonical_name": "citi field",
+        "lat": 40.7571,
+        "lon": -73.8458,
+        "cf_bearing": 355.0,
+        "aliases": ["citi", "shea stadium"],
+    },
+    "citizens bank park": {
+        "canonical_name": "citizens bank park",
+        "lat": 39.9057,
+        "lon": -75.1665,
+        "cf_bearing": 340.0,
+        "aliases": ["citizens bank", "phillies park", "cbp"],
+    },
+    "nationals park": {
+        "canonical_name": "nationals park",
+        "lat": 38.8730,
+        "lon": -77.0074,
+        "cf_bearing": 345.0,
+        "aliases": ["nationals", "nats park"],
+    },
+    "loandepot park": {
+        "canonical_name": "loandepot park",
+        "lat": 25.7781,
+        "lon": -80.2197,
+        "cf_bearing": 330.0,
+        "aliases": ["loan depot park", "loandepot", "marlins park", "miami marlins stadium"],
+    },
+    # ── NL Central ────────────────────────────────────────────────────────────
+    "wrigley field": {
+        "canonical_name": "wrigley field",
+        "lat": 41.9484,
+        "lon": -87.6553,
+        "cf_bearing": 330.0,
+        "aliases": ["wrigley", "cubs park"],
+    },
+    "great american ball park": {
+        "canonical_name": "great american ball park",
+        "lat": 39.0975,
+        "lon": -84.5068,
+        "cf_bearing": 330.0,
+        "aliases": ["great american ballpark", "great american", "gabp", "reds park"],
+    },
+    "american family field": {
+        "canonical_name": "american family field",
+        "lat": 43.0280,
+        "lon": -87.9712,
+        "cf_bearing": 340.0,
+        "aliases": ["american family", "miller park", "brewers park"],
+    },
+    "pnc park": {
+        "canonical_name": "pnc park",
+        "lat": 40.4469,
+        "lon": -80.0057,
+        "cf_bearing": 340.0,
+        "aliases": ["pnc", "pirates park"],
+    },
+    "busch stadium": {
+        "canonical_name": "busch stadium",
+        "lat": 38.6226,
+        "lon": -90.1928,
+        "cf_bearing": 330.0,
+        "aliases": ["busch", "cardinals park", "new busch"],
+    },
+    # ── NL West ───────────────────────────────────────────────────────────────
+    "chase field": {
+        "canonical_name": "chase field",
+        "lat": 33.4453,
+        "lon": -112.0667,
+        "cf_bearing": 330.0,
+        "aliases": ["chase", "bank one ballpark", "boa ballpark", "diamondbacks park"],
+    },
+    "coors field": {
+        "canonical_name": "coors field",
+        "lat": 39.7559,
+        "lon": -104.9942,
+        "cf_bearing": 335.0,
+        "aliases": ["coors", "rockies park"],
+    },
+    "dodger stadium": {
+        "canonical_name": "dodger stadium",
+        "lat": 34.0739,
+        "lon": -118.2400,
+        "cf_bearing": 335.0,
+        "aliases": ["dodger", "chavez ravine", "dodgers stadium"],
+    },
+    "oracle park": {
+        "canonical_name": "oracle park",
+        "lat": 37.7786,
+        "lon": -122.3893,
+        "cf_bearing": 25.0,
+        "aliases": ["oracle", "at&t park", "att park", "pac bell park", "giants park"],
+    },
+    "petco park": {
+        "canonical_name": "petco park",
+        "lat": 32.7076,
+        "lon": -117.1570,
+        "cf_bearing": 320.0,
+        "aliases": ["petco", "padres park"],
+    },
+    # ── Special / International venues ───────────────────────────────────────
+    "rickwood field": {
+        "canonical_name": "rickwood field",
+        "lat": 33.5186,
+        "lon": -86.8355,
+        "cf_bearing": 340.0,
+        "aliases": ["rickwood"],
+    },
+    "estadio alfredo harp helu": {
+        "canonical_name": "estadio alfredo harp helu",
+        "lat": 19.4810,
+        "lon": -99.0892,
+        "cf_bearing": 0.0,
+        "aliases": ["estadio alfredo harp helú", "alfredo harp helu", "mexico city stadium"],
+    },
+    "london stadium": {
+        "canonical_name": "london stadium",
+        "lat": 51.5386,
+        "lon": -0.0163,
+        "cf_bearing": 0.0,
+        "aliases": ["london", "olympic stadium london"],
+    },
+    "olympic stadium": {
+        "canonical_name": "olympic stadium",
+        "lat": 45.5598,
+        "lon": -73.5515,
+        "cf_bearing": 0.0,
+        "aliases": ["stade olympique", "montreal olympic", "montreal stadium"],
+    },
+}
+
+
+def resolve_stadium(venue_name: str) -> dict | None:
+    """
+    Resolve a venue name string to a STADIUM_REGISTRY entry.
+
+    Resolution order:
+    1. Direct match on lowercase key
+    2. Alias scan across all entries
+    3. Partial-match fallback (substring either direction)
+
+    Returns the registry dict on match, or None if unresolvable.
+    """
+    if not venue_name:
+        return None
+
+    normalized = venue_name.strip().lower()
+    if not normalized:
+        return None
+
+    # 1. Direct key match
+    if normalized in STADIUM_REGISTRY:
+        return STADIUM_REGISTRY[normalized]
+
+    # 2. Alias scan
+    for entry in STADIUM_REGISTRY.values():
+        for alias in entry.get("aliases", []):
+            if normalized == alias.strip().lower():
+                return entry
+
+    # 3. Partial-match fallback
+    for key, entry in STADIUM_REGISTRY.items():
+        if normalized in key or key in normalized:
+            return entry
+    # Also check aliases for partial match
+    for entry in STADIUM_REGISTRY.values():
+        for alias in entry.get("aliases", []):
+            alias_lower = alias.strip().lower()
+            if normalized in alias_lower or alias_lower in normalized:
+                return entry
+
+    return None

models/weather_provider.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+OPEN_METEO_URL = "https://api.open-meteo.com/v1/forecast"
+
+
+def fetch_game_time_weather(lat: float, lon: float, game_datetime_utc: str) -> dict | None:
+    """
+    Fetch Open-Meteo hourly weather for the given coordinates at game time.
+
+    Parses game_datetime_utc (ISO 8601 UTC, e.g. "2026-04-01T23:10:00Z"),
+    rounds to the nearest hour, and extracts temp/wind/humidity for that hour.
+
+    Returns:
+        dict with keys: temperature_f, wind_speed_mph, wind_direction_deg, humidity_pct
+        or None on any failure (network error, parse error, missing data).
+
+    No API key required — Open-Meteo is free and key-free.
+    """
+    try:
+        dt_str = str(game_datetime_utc or "").strip()
+        if not dt_str:
+            return None
+
+        # Normalize "Z" suffix for fromisoformat compatibility
+        dt_str_clean = dt_str.replace("Z", "+00:00")
+        game_dt = datetime.fromisoformat(dt_str_clean)
+        if game_dt.tzinfo is None:
+            game_dt = game_dt.replace(tzinfo=timezone.utc)
+
+        # Round to nearest hour
+        if game_dt.minute >= 30:
+            target_dt = game_dt.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)
+        else:
+            target_dt = game_dt.replace(minute=0, second=0, microsecond=0)
+
+        date_str = target_dt.strftime("%Y-%m-%d")
+        target_hour = target_dt.hour
+
+        params = {
+            "latitude": lat,
+            "longitude": lon,
+            "hourly": "temperature_2m,wind_speed_10m,wind_direction_10m,relative_humidity_2m",
+            "start_date": date_str,
+            "end_date": date_str,
+            "temperature_unit": "fahrenheit",
+            "wind_speed_unit": "mph",
+            "timezone": "UTC",
+        }
+
+        response = requests.get(OPEN_METEO_URL, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        hourly = data.get("hourly", {}) or {}
+        times = hourly.get("time", []) or []
+        temps = hourly.get("temperature_2m", []) or []
+        winds = hourly.get("wind_speed_10m", []) or []
+        wind_dirs = hourly.get("wind_direction_10m", []) or []
+        humidities = hourly.get("relative_humidity_2m", []) or []
+
+        # Find index for target hour
+        target_time_str = f"{date_str}T{target_hour:02d}:00"
+        hour_idx = None
+        for i, t in enumerate(times):
+            if str(t).startswith(target_time_str):
+                hour_idx = i
+                break
+
+        # Fallback: use hour index directly
+        if hour_idx is None and temps:
+            hour_idx = min(target_hour, len(temps) - 1)
+
+        if hour_idx is None:
+            return None
+
+        def _safe(lst: list, idx: int):
+            return lst[idx] if idx < len(lst) else None
+
+        temp_f = _safe(temps, hour_idx)
+        wind_mph = _safe(winds, hour_idx)
+        wind_dir = _safe(wind_dirs, hour_idx)
+        humidity = _safe(humidities, hour_idx)
+
+        return {
+            "temperature_f": float(temp_f) if temp_f is not None else None,
+            "wind_speed_mph": float(wind_mph) if wind_mph is not None else None,
+            "wind_direction_deg": float(wind_dir) if wind_dir is not None else None,
+            "humidity_pct": float(humidity) if humidity is not None else None,
+        }
+
+    except Exception as e:
+        logger.debug(f"[weather_provider] fetch_game_time_weather failed: {e}")
+        return None