Upload weather_agent.py

app/weather_agent.py

@@ -0,0 +1,535 @@
+# app/weather_agent.py
+"""
+🌤️ PENNY Weather Agent - Azure Maps Integration
+
+Provides real-time weather information and weather-aware recommendations
+for civic engagement activities.
+
+MISSION: Help residents plan their day with accurate weather data and
+smart suggestions for indoor/outdoor activities based on conditions.
+
+ENHANCEMENTS (Phase 1 Complete):
+- ✅ Structured logging with performance tracking
+- ✅ Enhanced error handling with graceful degradation
+- ✅ Type hints for all functions
+- ✅ Health check integration
+- ✅ Response caching for performance
+- ✅ Detailed weather parsing with validation
+- ✅ Penny's friendly voice in all responses
+
+Production-ready for Azure ML deployment.
+"""
+
+import os
+import logging
+import time
+from typing import Dict, Any, Optional, List, Tuple
+from datetime import datetime, timedelta
+import httpx
+
+# --- ENHANCED MODULE IMPORTS ---
+from app.logging_utils import log_interaction
+
+# --- LOGGING SETUP ---
+logger = logging.getLogger(__name__)
+
+# --- CONFIGURATION ---
+AZURE_WEATHER_URL = "https://atlas.microsoft.com/weather/currentConditions/json"
+DEFAULT_TIMEOUT = 10.0  # seconds
+CACHE_TTL_SECONDS = 300  # 5 minutes - weather doesn't change that fast
+
+# --- CHECK API KEY AVAILABILITY AT MODULE LOAD (NEW - PREVENTS IMPORT FAILURES) ---
+AZURE_MAPS_KEY = os.getenv("AZURE_WEATHER_KEY") or os.getenv("AZURE_MAPS_KEY")
+
+if not AZURE_MAPS_KEY:
+    logger.warning("⚠️ AZURE_MAPS_KEY not configured - weather features will be limited")
+    _WEATHER_SERVICE_AVAILABLE = False
+else:
+    logger.info("✅ AZURE_MAPS_KEY configured")
+    _WEATHER_SERVICE_AVAILABLE = True
+
+# --- WEATHER CACHE ---
+_weather_cache: Dict[str, Tuple[Dict[str, Any], datetime]] = {}
+
+
+# ============================================================
+# WEATHER DATA RETRIEVAL
+# ============================================================
+
+async def get_weather_for_location(
+    lat: float, 
+    lon: float,
+    use_cache: bool = True
+) -> Dict[str, Any]:
+    """
+    🌤️ Fetches real-time weather from Azure Maps.
+    
+    Retrieves current weather conditions for a specific location using
+    Azure Maps Weather API. Includes caching to reduce API calls and
+    improve response times.
+    
+    Args:
+        lat: Latitude coordinate
+        lon: Longitude coordinate
+        use_cache: Whether to use cached data if available (default: True)
+        
+    Returns:
+        Dictionary containing weather data with keys:
+        - temperature: {value: float, unit: str}
+        - phrase: str (weather description)
+        - iconCode: int
+        - hasPrecipitation: bool
+        - isDayTime: bool
+        - relativeHumidity: int
+        - cloudCover: int
+        - etc.
+        
+    Raises:
+        RuntimeError: If AZURE_MAPS_KEY is not configured
+        httpx.HTTPError: If API request fails
+        
+    Example:
+        weather = await get_weather_for_location(33.7490, -84.3880)
+        temp = weather.get("temperature", {}).get("value")
+        condition = weather.get("phrase", "Unknown")
+    """
+    start_time = time.time()
+    
+    # Create cache key
+    cache_key = f"{lat:.4f},{lon:.4f}"
+    
+    # Check cache first
+    if use_cache and cache_key in _weather_cache:
+        cached_data, cached_time = _weather_cache[cache_key]
+        age = (datetime.now() - cached_time).total_seconds()
+        
+        if age < CACHE_TTL_SECONDS:
+            logger.info(
+                f"🌤️ Weather cache hit (age: {age:.0f}s, "
+                f"location: {cache_key})"
+            )
+            return cached_data
+    
+    # Check if service is available (MODIFIED - USES FLAG INSTEAD OF CHECKING ENV VAR)
+    if not _WEATHER_SERVICE_AVAILABLE:
+        logger.error("❌ AZURE_MAPS_KEY not configured")
+        raise RuntimeError(
+            "AZURE_MAPS_KEY is required and not set in environment variables."
+        )
+    
+    # Build request parameters
+    params = {
+        "api-version": "1.0",
+        "query": f"{lat},{lon}",
+        "subscription-key": AZURE_MAPS_KEY,
+        "details": "true",
+        "language": "en-US",
+    }
+    
+    try:
+        logger.info(f"🌤️ Fetching weather for location: {cache_key}")
+        
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.get(AZURE_WEATHER_URL, params=params)
+            response.raise_for_status()
+            data = response.json()
+        
+        # Parse response
+        if "results" in data and len(data["results"]) > 0:
+            weather_data = data["results"][0]
+        else:
+            weather_data = data  # Fallback if structure changes
+        
+        # Validate essential fields
+        weather_data = _validate_weather_data(weather_data)
+        
+        # Cache the result
+        _weather_cache[cache_key] = (weather_data, datetime.now())
+        
+        # Calculate response time
+        response_time = (time.time() - start_time) * 1000
+        
+        # Log successful retrieval
+        log_interaction(
+            tenant_id="weather_service",
+            interaction_type="weather_fetch",
+            intent="weather",
+            response_time_ms=response_time,
+            success=True,
+            metadata={
+                "location": cache_key,
+                "cached": False,
+                "temperature": weather_data.get("temperature", {}).get("value"),
+                "condition": weather_data.get("phrase")
+            }
+        )
+        
+        logger.info(
+            f"✅ Weather fetched successfully ({response_time:.0f}ms, "
+            f"location: {cache_key})"
+        )
+        
+        return weather_data
+    
+    except httpx.TimeoutException as e:
+        logger.error(f"⏱️ Weather API timeout: {e}")
+        raise
+    
+    except httpx.HTTPStatusError as e:
+        logger.error(f"❌ Weather API HTTP error: {e.response.status_code}")
+        raise
+    
+    except Exception as e:
+        logger.error(f"❌ Weather API error: {e}", exc_info=True)
+        raise
+
+
+def _validate_weather_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Validates and normalizes weather data from Azure Maps.
+    
+    Ensures essential fields are present with sensible defaults.
+    """
+    # Ensure temperature exists
+    if "temperature" not in data:
+        data["temperature"] = {"value": None, "unit": "F"}
+    elif isinstance(data["temperature"], (int, float)):
+        # Handle case where temperature is just a number
+        data["temperature"] = {"value": data["temperature"], "unit": "F"}
+    
+    # Ensure phrase exists
+    if "phrase" not in data or not data["phrase"]:
+        data["phrase"] = "Conditions unavailable"
+    
+    # Ensure boolean flags exist
+    data.setdefault("hasPrecipitation", False)
+    data.setdefault("isDayTime", True)
+    
+    # Ensure numeric fields exist
+    data.setdefault("relativeHumidity", None)
+    data.setdefault("cloudCover", None)
+    data.setdefault("iconCode", None)
+    
+    return data
+
+
+# ============================================================
+# OUTFIT RECOMMENDATIONS
+# ============================================================
+
+def recommend_outfit(high_temp: float, condition: str) -> str:
+    """
+    👕 Recommends what to wear based on weather conditions.
+    
+    Provides friendly, practical clothing suggestions based on
+    temperature and weather conditions.
+    
+    Args:
+        high_temp: Expected high temperature in Fahrenheit
+        condition: Weather condition description (e.g., "Sunny", "Rainy")
+        
+    Returns:
+        Friendly outfit recommendation string
+        
+    Example:
+        outfit = recommend_outfit(85, "Sunny")
+        # Returns: "Light clothes, sunscreen, and stay hydrated! ☀️"
+    """
+    condition_lower = condition.lower()
+    
+    # Check for precipitation first
+    if "rain" in condition_lower or "storm" in condition_lower:
+        logger.debug(f"Outfit rec: Rain/Storm (temp: {high_temp}°F)")
+        return "Bring an umbrella or rain jacket! ☔"
+    
+    # Temperature-based recommendations
+    if high_temp >= 85:
+        logger.debug(f"Outfit rec: Hot (temp: {high_temp}°F)")
+        return "Light clothes, sunscreen, and stay hydrated! ☀️"
+    
+    if high_temp >= 72:
+        logger.debug(f"Outfit rec: Warm (temp: {high_temp}°F)")
+        return "T-shirt and jeans or a casual dress. 👕"
+    
+    if high_temp >= 60:
+        logger.debug(f"Outfit rec: Mild (temp: {high_temp}°F)")
+        return "A hoodie or light jacket should do! 🧥"
+    
+    logger.debug(f"Outfit rec: Cold (temp: {high_temp}°F)")
+    return "Bundle up — sweater or coat recommended! 🧣"
+
+
+# ============================================================
+# EVENT RECOMMENDATIONS BASED ON WEATHER
+# ============================================================
+
+def weather_to_event_recommendations(
+    weather: Dict[str, Any]
+) -> List[Dict[str, Any]]:
+    """
+    📅 Suggests activity types based on current weather conditions.
+    
+    Analyzes weather data to provide smart recommendations for
+    indoor vs outdoor activities, helping residents plan their day.
+    
+    Args:
+        weather: Weather data dictionary from get_weather_for_location()
+        
+    Returns:
+        List of recommendation dictionaries with keys:
+        - type: str ("indoor", "outdoor", "neutral")
+        - suggestions: List[str] (specific activity ideas)
+        - reason: str (explanation for recommendation)
+        - priority: int (1-3, added for sorting)
+        
+    Example:
+        weather = await get_weather_for_location(33.7490, -84.3880)
+        recs = weather_to_event_recommendations(weather)
+        for rec in recs:
+            print(f"{rec['type']}: {rec['suggestions']}")
+    """
+    condition = (weather.get("phrase") or "").lower()
+    temp = weather.get("temperature", {}).get("value")
+    has_precipitation = weather.get("hasPrecipitation", False)
+    
+    recs = []
+    
+    # Check for rain or storms (highest priority)
+    if "rain" in condition or "storm" in condition or has_precipitation:
+        logger.debug("Event rec: Indoor (precipitation)")
+        recs.append({
+            "type": "indoor",
+            "suggestions": [
+                "Visit a library 📚",
+                "Check out a community center event 🏛️",
+                "Find an indoor workshop or class 🎨",
+                "Explore a local museum 🖼️"
+            ],
+            "reason": "Rainy weather makes indoor events ideal!",
+            "priority": 1
+        })
+    
+    # Warm weather outdoor activities
+    elif temp is not None and temp >= 75:
+        logger.debug(f"Event rec: Outdoor (warm: {temp}°F)")
+        recs.append({
+            "type": "outdoor",
+            "suggestions": [
+                "Visit a park 🌳",
+                "Check out a farmers market 🥕",
+                "Look for outdoor concerts or festivals 🎵",
+                "Enjoy a community picnic or BBQ 🍔"
+            ],
+            "reason": "Beautiful weather for outdoor activities!",
+            "priority": 1
+        })
+    
+    # Cold weather considerations
+    elif temp is not None and temp < 50:
+        logger.debug(f"Event rec: Indoor (cold: {temp}°F)")
+        recs.append({
+            "type": "indoor",
+            "suggestions": [
+                "Browse local events at community centers 🏛️",
+                "Visit a museum or art gallery 🖼️",
+                "Check out indoor markets or shopping 🛍️",
+                "Warm up at a local café or restaurant ☕"
+            ],
+            "reason": "Chilly weather — indoor activities are cozy!",
+            "priority": 1
+        })
+    
+    # Mild/neutral weather
+    else:
+        logger.debug(f"Event rec: Neutral (mild: {temp}°F if temp else 'unknown')")
+        recs.append({
+            "type": "neutral",
+            "suggestions": [
+                "Browse local events 📅",
+                "Visit a museum or cultural center 🏛️",
+                "Walk around a local plaza or downtown 🚶",
+                "Check out both indoor and outdoor activities 🌍"
+            ],
+            "reason": "Mild weather gives you flexible options!",
+            "priority": 2
+        })
+    
+    return recs
+
+
+# ============================================================
+# HELPER FUNCTIONS
+# ============================================================
+
+def format_weather_summary(weather: Dict[str, Any]) -> str:
+    """
+    📝 Formats weather data into a human-readable summary.
+    
+    Args:
+        weather: Weather data dictionary
+        
+    Returns:
+        Formatted weather summary string with Penny's friendly voice
+        
+    Example:
+        summary = format_weather_summary(weather_data)
+        # "Currently 72°F and Partly Cloudy. Humidity: 65%"
+    """
+    temp_data = weather.get("temperature", {})
+    temp = temp_data.get("value")
+    unit = temp_data.get("unit", "F")
+    phrase = weather.get("phrase", "Conditions unavailable")
+    humidity = weather.get("relativeHumidity")
+    
+    # Build summary
+    parts = []
+    
+    if temp is not None:
+        parts.append(f"Currently {int(temp)}°{unit}")
+    
+    parts.append(phrase)
+    
+    if humidity is not None:
+        parts.append(f"Humidity: {humidity}%")
+    
+    summary = " and ".join(parts[:2])
+    if len(parts) > 2:
+        summary += f". {parts[2]}"
+    
+    return summary
+
+
+def clear_weather_cache():
+    """
+    🧹 Clears the weather cache.
+    
+    Useful for testing or if fresh data is needed immediately.
+    """
+    global _weather_cache
+    cache_size = len(_weather_cache)
+    _weather_cache.clear()
+    logger.info(f"🧹 Weather cache cleared ({cache_size} entries removed)")
+
+
+def get_cache_stats() -> Dict[str, Any]:
+    """
+    📊 Returns weather cache statistics.
+    
+    Returns:
+        Dictionary with cache statistics:
+        - entries: int (number of cached locations)
+        - oldest_entry_age_seconds: float
+        - newest_entry_age_seconds: float
+    """
+    if not _weather_cache:
+        return {
+            "entries": 0,
+            "oldest_entry_age_seconds": None,
+            "newest_entry_age_seconds": None
+        }
+    
+    now = datetime.now()
+    ages = [
+        (now - cached_time).total_seconds()
+        for _, cached_time in _weather_cache.values()
+    ]
+    
+    return {
+        "entries": len(_weather_cache),
+        "oldest_entry_age_seconds": max(ages) if ages else None,
+        "newest_entry_age_seconds": min(ages) if ages else None
+    }
+
+
+# ============================================================
+# HEALTH CHECK
+# ============================================================
+
+def get_weather_agent_health() -> Dict[str, Any]:
+    """
+    📊 Returns weather agent health status.
+    
+    Used by the main application health check endpoint to monitor
+    the weather service availability and performance.
+    
+    Returns:
+        Dictionary with health information
+    """
+    cache_stats = get_cache_stats()
+    
+    # MODIFIED - USES FLAG INSTEAD OF CHECKING ENV VAR
+    return {
+        "status": "operational" if _WEATHER_SERVICE_AVAILABLE else "degraded",
+        "service": "azure_maps_weather",
+        "api_key_configured": _WEATHER_SERVICE_AVAILABLE,
+        "cache": cache_stats,
+        "cache_ttl_seconds": CACHE_TTL_SECONDS,
+        "default_timeout_seconds": DEFAULT_TIMEOUT,
+        "features": {
+            "real_time_weather": True,
+            "outfit_recommendations": True,
+            "event_recommendations": True,
+            "response_caching": True
+        }
+    }
+
+
+# ============================================================
+# TESTING
+# ============================================================
+
+if __name__ == "__main__":
+    """🧪 Test weather agent functionality"""
+    import asyncio
+    
+    print("=" * 60)
+    print("🧪 Testing Weather Agent")
+    print("=" * 60)
+    
+    async def run_tests():
+        # Test location: Atlanta, GA
+        lat, lon = 33.7490, -84.3880
+        
+        print(f"\n--- Test 1: Fetch Weather ---")
+        print(f"Location: {lat}, {lon} (Atlanta, GA)")
+        
+        try:
+            weather = await get_weather_for_location(lat, lon)
+            print(f"✅ Weather fetched successfully")
+            print(f"Temperature: {weather.get('temperature', {}).get('value')}°F")
+            print(f"Condition: {weather.get('phrase')}")
+            print(f"Precipitation: {weather.get('hasPrecipitation')}")
+            
+            print(f"\n--- Test 2: Weather Summary ---")
+            summary = format_weather_summary(weather)
+            print(f"Summary: {summary}")
+            
+            print(f"\n--- Test 3: Outfit Recommendation ---")
+            temp = weather.get('temperature', {}).get('value', 70)
+            condition = weather.get('phrase', 'Clear')
+            outfit = recommend_outfit(temp, condition)
+            print(f"Outfit: {outfit}")
+            
+            print(f"\n--- Test 4: Event Recommendations ---")
+            recs = weather_to_event_recommendations(weather)
+            for rec in recs:
+                print(f"Type: {rec['type']}")
+                print(f"Reason: {rec['reason']}")
+                print(f"Suggestions: {', '.join(rec['suggestions'][:2])}")
+            
+            print(f"\n--- Test 5: Cache Test ---")
+            weather2 = await get_weather_for_location(lat, lon, use_cache=True)
+            print(f"✅ Cache working (should be instant)")
+            
+            print(f"\n--- Test 6: Health Check ---")
+            health = get_weather_agent_health()
+            print(f"Status: {health['status']}")
+            print(f"Cache entries: {health['cache']['entries']}")
+            
+        except Exception as e:
+            print(f"❌ Error: {e}")
+    
+    asyncio.run(run_tests())
+    
+    print("\n" + "=" * 60)
+    print("✅ Tests complete")