Upload event_weather.py

app/event_weather.py

@@ -0,0 +1,761 @@
+# app/event_weather.py
+"""
+🌤️ Penny's Event + Weather Matchmaker
+Helps residents find the perfect community activity based on real-time weather.
+Penny always suggests what's actually enjoyable — not just what exists.
+
+Production-ready version with structured logging, performance tracking, and robust error handling.
+"""
+
+import json
+import time
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+from datetime import datetime
+from enum import Enum
+
+from app.weather_agent import get_weather_for_location
+from app.location_utils import load_city_events
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- LOGGING SETUP (Structured, Azure-compatible) ---
+import logging
+logger = logging.getLogger(__name__)
+
+
+# --- CONFIGURATION CONSTANTS ---
+class EventWeatherConfig:
+    """Configuration constants for event recommendation system."""
+    MAX_FALLBACK_EVENTS = 10
+    MAX_RECOMMENDATIONS = 20
+    WEATHER_TIMEOUT_SECONDS = 5.0
+    SLOW_OPERATION_THRESHOLD_MS = 2000
+
+
+# --- PENNY'S WEATHER WISDOM (Personality-Driven Thresholds) ---
+class WeatherThresholds:
+    """
+    Penny's practical weather rules for event recommendations.
+    These are based on real resident comfort, not just data.
+    """
+    WARM_THRESHOLD = 70  # F° - Great for outdoor events
+    HOT_THRESHOLD = 85   # F° - Maybe too hot for some activities
+    COOL_THRESHOLD = 60  # F° - Bring a jacket
+    COLD_THRESHOLD = 40  # F° - Indoor events preferred
+    
+    RAINY_KEYWORDS = ["rain", "shower", "storm", "drizzle", "thunderstorm"]
+    SNOWY_KEYWORDS = ["snow", "flurries", "blizzard", "ice"]
+    NICE_KEYWORDS = ["clear", "sunny", "fair", "partly cloudy"]
+
+
+class ErrorType(str, Enum):
+    """Structured error types for event weather system."""
+    NOT_FOUND = "event_data_not_found"
+    PARSE_ERROR = "json_parse_error"
+    WEATHER_ERROR = "weather_service_error"
+    UNKNOWN = "unknown_error"
+
+
+class EventWeatherException(Exception):
+    """Base exception for event weather system."""
+    def __init__(self, error_type: ErrorType, message: str, original_error: Optional[Exception] = None):
+        self.error_type = error_type
+        self.message = message
+        self.original_error = original_error
+        super().__init__(message)
+
+
+# --- MAIN RECOMMENDATION FUNCTION ---
+async def get_event_recommendations_with_weather(
+    tenant_id: str, 
+    lat: float, 
+    lon: float,
+    include_all_events: bool = False,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    🌤️ Penny's Event + Weather Intelligence System
+    
+    Combines real-time weather with community events to give residents 
+    smart, helpful suggestions about what to do today.
+    
+    Args:
+        tenant_id: City identifier (e.g., 'atlanta_ga', 'seattle_wa')
+        lat: Latitude for weather lookup
+        lon: Longitude for weather lookup
+        include_all_events: If True, returns all events regardless of weather fit
+        session_id: Optional session identifier for logging
+        user_id: Optional user identifier for logging
+        
+    Returns:
+        Dict containing:
+            - weather: Current conditions
+            - suggestions: Penny's prioritized recommendations
+            - all_events: Optional full event list
+            - metadata: Useful context (timestamp, event count, etc.)
+            
+    Raises:
+        EventWeatherException: When critical errors occur
+        
+    Example:
+        >>> recommendations = await get_event_recommendations_with_weather(
+        ...     tenant_id="norfolk_va",
+        ...     lat=36.8508,
+        ...     lon=-76.2859
+        ... )
+        >>> print(recommendations["suggestions"][0])
+        🌟 **Outdoor Concert**at Town Point Park — Perfect outdoor weather! This is the one.
+    """
+    start_time = time.time()
+    
+    # Sanitize inputs for logging
+    safe_tenant_id = sanitize_for_logging(tenant_id)
+    safe_coords = f"({lat:.4f}, {lon:.4f})"
+    
+    logger.info(
+        f"🌤️ Event weather recommendation request: tenant={safe_tenant_id}, coords={safe_coords}"
+    )
+    
+    try:
+        # --- STEP 1: Load City Events (Standardized) ---
+        events, event_load_time = await _load_events_with_timing(tenant_id)
+        
+        if not events:
+            response = _create_no_events_response(tenant_id)
+            _log_operation(
+                operation="event_weather_recommendations",
+                tenant_id=tenant_id,
+                session_id=session_id,
+                user_id=user_id,
+                success=True,
+                event_count=0,
+                response_time_ms=_calculate_response_time(start_time),
+                fallback_used=False,
+                weather_available=False
+            )
+            return response
+        
+        logger.info(f"✅ Loaded {len(events)} events for {safe_tenant_id} in {event_load_time:.2f}s")
+        
+        # --- STEP 2: Get Live Weather Data ---
+        weather, weather_available = await _get_weather_with_fallback(lat, lon)
+        
+        # --- STEP 3: Generate Recommendations ---
+        if weather_available:
+            response = await _generate_weather_optimized_recommendations(
+                tenant_id=tenant_id,
+                events=events,
+                weather=weather,
+                include_all_events=include_all_events
+            )
+        else:
+            # Graceful degradation: Still show events without weather optimization
+            response = _create_fallback_response(tenant_id, events)
+        
+        # --- STEP 4: Calculate Performance Metrics ---
+        response_time_ms = _calculate_response_time(start_time)
+        
+        # Add performance metadata
+        response["performance"] = {
+            "response_time_ms": response_time_ms,
+            "event_load_time_ms": int(event_load_time * 1000),
+            "weather_available": weather_available
+        }
+        
+        # Warn if operation was slow
+        if response_time_ms > EventWeatherConfig.SLOW_OPERATION_THRESHOLD_MS:
+            logger.warning(
+                f"⚠️ Slow event weather operation: {response_time_ms}ms for {safe_tenant_id}"
+            )
+        
+        # --- STEP 5: Log Structured Interaction ---
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=True,
+            event_count=len(events),
+            response_time_ms=response_time_ms,
+            fallback_used=not weather_available,
+            weather_available=weather_available
+        )
+        
+        logger.info(
+            f"✅ Returning {len(response.get('suggestions', []))} recommendations "
+            f"for {safe_tenant_id} in {response_time_ms}ms"
+        )
+        
+        return response
+        
+    except EventWeatherException as e:
+        # Known error with structured handling
+        response_time_ms = _calculate_response_time(start_time)
+        
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=False,
+            event_count=0,
+            response_time_ms=response_time_ms,
+            fallback_used=False,
+            weather_available=False,
+            error_type=e.error_type.value,
+            error_message=str(e)
+        )
+        
+        return _create_error_response(
+            tenant_id=tenant_id,
+            error_type=e.error_type.value,
+            message=e.message
+        )
+        
+    except Exception as e:
+        # Unexpected error
+        response_time_ms = _calculate_response_time(start_time)
+        
+        logger.error(
+            f"❌ Unexpected error in event weather recommendations: {str(e)}",
+            exc_info=True
+        )
+        
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=False,
+            event_count=0,
+            response_time_ms=response_time_ms,
+            fallback_used=False,
+            weather_available=False,
+            error_type=ErrorType.UNKNOWN.value,
+            error_message="Unexpected system error"
+        )
+        
+        return _create_error_response(
+            tenant_id=tenant_id,
+            error_type=ErrorType.UNKNOWN.value,
+            message="Something unexpected happened. Please try again in a moment."
+        )
+
+
+# --- EVENT LOADING WITH TIMING ---
+async def _load_events_with_timing(tenant_id: str) -> Tuple[List[Dict[str, Any]], float]:
+    """
+    Load city events with performance timing.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Tuple of (events list, load time in seconds)
+        
+    Raises:
+        EventWeatherException: When event loading fails
+    """
+    load_start = time.time()
+    
+    try:
+        loaded_data = load_city_events(tenant_id)
+        events = loaded_data.get("events", [])
+        load_time = time.time() - load_start
+        
+        return events, load_time
+        
+    except FileNotFoundError as e:
+        logger.error(f"❌ Event data file not found for tenant: {tenant_id}")
+        raise EventWeatherException(
+            error_type=ErrorType.NOT_FOUND,
+            message=f"I don't have event data for {tenant_id} yet. Let me know if you'd like me to add it!",
+            original_error=e
+        )
+        
+    except json.JSONDecodeError as e:
+        logger.error(f"❌ Invalid JSON in event data for {tenant_id}: {e}")
+        raise EventWeatherException(
+            error_type=ErrorType.PARSE_ERROR,
+            message="There's an issue with the event data format. Our team has been notified!",
+            original_error=e
+        )
+        
+    except Exception as e:
+        logger.error(f"❌ Unexpected error loading events: {e}", exc_info=True)
+        raise EventWeatherException(
+            error_type=ErrorType.UNKNOWN,
+            message="Something went wrong loading events. Please try again in a moment.",
+            original_error=e
+        )
+
+
+# --- WEATHER RETRIEVAL WITH FALLBACK ---
+async def _get_weather_with_fallback(
+    lat: float, 
+    lon: float
+) -> Tuple[Dict[str, Any], bool]:
+    """
+    Get weather data with graceful fallback if service is unavailable.
+    
+    Args:
+        lat: Latitude
+        lon: Longitude
+        
+    Returns:
+        Tuple of (weather data dict, availability boolean)
+    """
+    try:
+        weather = await get_weather_for_location(lat, lon)
+        
+        temp = weather.get("temperature", {}).get("value")
+        phrase = weather.get("phrase", "N/A")
+        
+        logger.info(f"✅ Weather retrieved: {phrase} at {temp}°F")
+        
+        return weather, True
+        
+    except Exception as e:
+        logger.warning(f"⚠️ Weather service unavailable: {str(e)}")
+        return {"error": "Weather service unavailable"}, False
+
+
+# --- WEATHER-OPTIMIZED RECOMMENDATIONS ---
+async def _generate_weather_optimized_recommendations(
+    tenant_id: str,
+    events: List[Dict[str, Any]],
+    weather: Dict[str, Any],
+    include_all_events: bool
+) -> Dict[str, Any]:
+    """
+    Generate event recommendations optimized for current weather conditions.
+    
+    Args:
+        tenant_id: City identifier
+        events: List of available events
+        weather: Weather data dictionary
+        include_all_events: Whether to include full event list in response
+        
+    Returns:
+        Structured response with weather-optimized suggestions
+    """
+    temp = weather.get("temperature", {}).get("value")
+    phrase = weather.get("phrase", "").lower()
+    
+    # Analyze weather conditions
+    weather_analysis = _analyze_weather_conditions(temp, phrase)
+    
+    # Generate Penny's smart suggestions
+    suggestions = _generate_recommendations(
+        events=events,
+        weather_analysis=weather_analysis,
+        temp=temp,
+        phrase=phrase
+    )
+    
+    # Build response
+    response = {
+        "weather": weather,
+        "weather_summary": _create_weather_summary(temp, phrase),
+        "suggestions": suggestions[:EventWeatherConfig.MAX_RECOMMENDATIONS],
+        "tenant_id": tenant_id,
+        "event_count": len(events),
+        "timestamp": datetime.utcnow().isoformat(),
+        "weather_analysis": weather_analysis
+    }
+    
+    # Optionally include full event list
+    if include_all_events:
+        response["all_events"] = events
+    
+    return response
+
+
+# --- HELPER FUNCTIONS (Penny's Intelligence Layer) ---
+
+def _analyze_weather_conditions(temp: Optional[float], phrase: str) -> Dict[str, Any]:
+    """
+    🧠 Penny's weather interpretation logic.
+    Returns structured analysis of current conditions.
+    
+    Args:
+        temp: Temperature in Fahrenheit
+        phrase: Weather description phrase
+        
+    Returns:
+        Dictionary with weather analysis including outdoor suitability
+    """
+    analysis = {
+        "is_rainy": any(keyword in phrase for keyword in WeatherThresholds.RAINY_KEYWORDS),
+        "is_snowy": any(keyword in phrase for keyword in WeatherThresholds.SNOWY_KEYWORDS),
+        "is_nice": any(keyword in phrase for keyword in WeatherThresholds.NICE_KEYWORDS),
+        "temp_category": None,
+        "outdoor_friendly": False,
+        "indoor_preferred": False
+    }
+    
+    if temp:
+        if temp >= WeatherThresholds.HOT_THRESHOLD:
+            analysis["temp_category"] = "hot"
+        elif temp >= WeatherThresholds.WARM_THRESHOLD:
+            analysis["temp_category"] = "warm"
+        elif temp >= WeatherThresholds.COOL_THRESHOLD:
+            analysis["temp_category"] = "mild"
+        elif temp >= WeatherThresholds.COLD_THRESHOLD:
+            analysis["temp_category"] = "cool"
+        else:
+            analysis["temp_category"] = "cold"
+        
+        # Outdoor-friendly = warm/mild + not rainy/snowy
+        analysis["outdoor_friendly"] = (
+            temp >= WeatherThresholds.COOL_THRESHOLD and
+            not analysis["is_rainy"] and
+            not analysis["is_snowy"]
+        )
+        
+        # Indoor preferred = cold or rainy or snowy
+        analysis["indoor_preferred"] = (
+            temp < WeatherThresholds.COOL_THRESHOLD or
+            analysis["is_rainy"] or
+            analysis["is_snowy"]
+        )
+    
+    return analysis
+
+
+def _generate_recommendations(
+    events: List[Dict[str, Any]],
+    weather_analysis: Dict[str, Any],
+    temp: Optional[float],
+    phrase: str
+) -> List[str]:
+    """
+    🎯 Penny's event recommendation engine.
+    Prioritizes events based on weather + category fit.
+    Keeps Penny's warm, helpful voice throughout.
+    
+    Args:
+        events: List of available events
+        weather_analysis: Weather condition analysis
+        temp: Current temperature
+        phrase: Weather description
+        
+    Returns:
+        List of formatted event suggestions
+    """
+    suggestions = []
+    
+    # Sort events: Best weather fit first
+    scored_events = []
+    for event in events:
+        score = _calculate_event_weather_score(event, weather_analysis)
+        scored_events.append((score, event))
+    
+    scored_events.sort(reverse=True, key=lambda x: x[0])
+    
+    # Generate suggestions with Penny's personality
+    for score, event in scored_events:
+        event_name = event.get("name", "Unnamed Event")
+        event_category = event.get("category", "").lower()
+        event_location = event.get("location", "")
+        
+        # Build suggestion with appropriate emoji + messaging
+        suggestion = _create_suggestion_message(
+            event_name=event_name,
+            event_category=event_category,
+            event_location=event_location,
+            score=score,
+            weather_analysis=weather_analysis,
+            temp=temp,
+            phrase=phrase
+        )
+        
+        suggestions.append(suggestion)
+    
+    return suggestions
+
+
+def _calculate_event_weather_score(
+    event: Dict[str, Any],
+    weather_analysis: Dict[str, Any]
+) -> int:
+    """
+    📊 Scores event suitability based on weather (0-100).
+    Higher = better match for current conditions.
+    
+    Args:
+        event: Event dictionary with category information
+        weather_analysis: Weather condition analysis
+        
+    Returns:
+        Integer score from 0-100
+    """
+    category = event.get("category", "").lower()
+    score = 50  # Neutral baseline
+    
+    # Perfect matches
+    if "outdoor" in category and weather_analysis["outdoor_friendly"]:
+        score = 95
+    elif "indoor" in category and weather_analysis["indoor_preferred"]:
+        score = 90
+    
+    # Good matches
+    elif "indoor" in category and not weather_analysis["outdoor_friendly"]:
+        score = 75
+    elif "outdoor" in category and weather_analysis["temp_category"] in ["warm", "mild"]:
+        score = 70
+    
+    # Acceptable matches
+    elif "civic" in category or "community" in category:
+        score = 60  # Usually indoor, weather-neutral
+    
+    # Poor matches (but still list them)
+    elif "outdoor" in category and weather_analysis["indoor_preferred"]:
+        score = 30
+    
+    return score
+
+
+def _create_suggestion_message(
+    event_name: str,
+    event_category: str,
+    event_location: str,
+    score: int,
+    weather_analysis: Dict[str, Any],
+    temp: Optional[float],
+    phrase: str
+) -> str:
+    """
+    💬 Penny's voice: Generates natural, helpful event suggestions.
+    Adapts tone based on weather fit score.
+    
+    Args:
+        event_name: Name of the event
+        event_category: Event category (outdoor, indoor, etc.)
+        event_location: Event location/venue
+        score: Weather suitability score (0-100)
+        weather_analysis: Weather condition analysis
+        temp: Current temperature
+        phrase: Weather description
+        
+    Returns:
+        Formatted suggestion string with emoji and helpful context
+    """
+    location_text = f" at {event_location}" if event_location else ""
+    
+    # PERFECT MATCHES (90-100)
+    if score >= 90:
+        if "outdoor" in event_category:
+            return f"🌟 **{event_name}**{location_text} — Perfect outdoor weather! This is the one."
+        else:
+            return f"🏛️ **{event_name}**{location_text} — Ideal indoor activity for today's weather!"
+    
+    # GOOD MATCHES (70-89)
+    elif score >= 70:
+        if "outdoor" in event_category:
+            return f"☀️ **{event_name}**{location_text} — Great day for outdoor activities!"
+        else:
+            return f"🔵 **{event_name}**{location_text} — Solid indoor option!"
+    
+    # DECENT MATCHES (50-69)
+    elif score >= 50:
+        if "outdoor" in event_category:
+            temp_text = f" (It's {int(temp)}°F)" if temp else ""
+            return f"🌤️ **{event_name}**{location_text} — Weather's okay for outdoor events{temp_text}."
+        else:
+            return f"⚪ **{event_name}**{location_text} — Weather-neutral activity."
+    
+    # POOR MATCHES (Below 50)
+    else:
+        if "outdoor" in event_category and weather_analysis["is_rainy"]:
+            return f"🌧️ **{event_name}**{location_text} — Outdoor event, but it's rainy. Bring an umbrella or check if it's postponed!"
+        elif "outdoor" in event_category and weather_analysis.get("temp_category") == "cold":
+            return f"❄️ **{event_name}**{location_text} — Outdoor event, but bundle up — it's chilly!"
+        else:
+            return f"⚪ **{event_name}**{location_text} — Check weather before heading out."
+
+
+def _create_weather_summary(temp: Optional[float], phrase: str) -> str:
+    """
+    🌤️ Penny's plain-English weather summary.
+    
+    Args:
+        temp: Temperature in Fahrenheit
+        phrase: Weather description phrase
+        
+    Returns:
+        Human-readable weather summary
+    """
+    if not temp:
+        return f"Current conditions: {phrase.title()}"
+    
+    temp_desc = ""
+    if temp >= 85:
+        temp_desc = "hot"
+    elif temp >= 70:
+        temp_desc = "warm"
+    elif temp >= 60:
+        temp_desc = "mild"
+    elif temp >= 40:
+        temp_desc = "cool"
+    else:
+        temp_desc = "cold"
+    
+    return f"It's {temp_desc} at {int(temp)}°F — {phrase.lower()}."
+
+
+# --- ERROR RESPONSE HELPERS (Penny stays helpful even in failures) ---
+
+def _create_no_events_response(tenant_id: str) -> Dict[str, Any]:
+    """
+    Returns friendly response when no events are found.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Structured response with helpful message
+    """
+    return {
+        "weather": {},
+        "suggestions": [
+            f"🤔 I don't have any events loaded for {tenant_id} right now. "
+            "Let me know if you'd like me to check again or add some!"
+        ],
+        "tenant_id": tenant_id,
+        "event_count": 0,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+
+def _create_error_response(
+    tenant_id: str, 
+    error_type: str, 
+    message: str
+) -> Dict[str, Any]:
+    """
+    Returns structured error with Penny's helpful tone.
+    
+    Args:
+        tenant_id: City identifier
+        error_type: Structured error type code
+        message: User-friendly error message
+        
+    Returns:
+        Error response dictionary
+    """
+    logger.error(f"Error in event_weather: {error_type} - {message}")
+    return {
+        "weather": {},
+        "suggestions": [f"⚠️ {message}"],
+        "tenant_id": tenant_id,
+        "event_count": 0,
+        "error_type": error_type,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+
+def _create_fallback_response(
+    tenant_id: str, 
+    events: List[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """
+    Graceful degradation: Shows events even if weather service is down.
+    Penny stays helpful!
+    
+    Args:
+        tenant_id: City identifier
+        events: List of available events
+        
+    Returns:
+        Fallback response with events but no weather optimization
+    """
+    # Limit to configured maximum
+    display_events = events[:EventWeatherConfig.MAX_FALLBACK_EVENTS]
+    
+    suggestions = [
+        f"📅 **{event.get('name', 'Event')}** — {event.get('category', 'Community event')}"
+        for event in display_events
+    ]
+    
+    suggestions.insert(0, "⚠️ Weather service is temporarily unavailable, but here are today's events:")
+    
+    return {
+        "weather": {"error": "Weather service unavailable"},
+        "suggestions": suggestions,
+        "tenant_id": tenant_id,
+        "event_count": len(events),
+        "timestamp": datetime.utcnow().isoformat(),
+        "fallback_mode": True
+    }
+
+
+# --- STRUCTURED LOGGING HELPER ---
+
+def _log_operation(
+    operation: str,
+    tenant_id: str,
+    success: bool,
+    event_count: int,
+    response_time_ms: int,
+    fallback_used: bool,
+    weather_available: bool,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    error_type: Optional[str] = None,
+    error_message: Optional[str] = None
+) -> None:
+    """
+    Log event weather operation with structured data.
+    
+    Args:
+        operation: Operation name
+        tenant_id: City identifier
+        success: Whether operation succeeded
+        event_count: Number of events processed
+        response_time_ms: Total response time in milliseconds
+        fallback_used: Whether fallback mode was used
+        weather_available: Whether weather data was available
+        session_id: Optional session identifier
+        user_id: Optional user identifier
+        error_type: Optional error type if failed
+        error_message: Optional error message if failed
+    """
+    log_data = {
+        "operation": operation,
+        "tenant_id": sanitize_for_logging(tenant_id),
+        "success": success,
+        "event_count": event_count,
+        "response_time_ms": response_time_ms,
+        "fallback_used": fallback_used,
+        "weather_available": weather_available,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+    
+    if session_id:
+        log_data["session_id"] = sanitize_for_logging(session_id)
+    
+    if user_id:
+        log_data["user_id"] = sanitize_for_logging(user_id)
+    
+    if error_type:
+        log_data["error_type"] = error_type
+    
+    if error_message:
+        log_data["error_message"] = sanitize_for_logging(error_message)
+    
+    log_interaction(log_data)
+
+
+def _calculate_response_time(start_time: float) -> int:
+    """
+    Calculate response time in milliseconds.
+    
+    Args:
+        start_time: Operation start time from time.time()
+        
+    Returns:
+        Response time in milliseconds
+    """
+    return int((time.time() - start_time) * 1000)