Upload 9 files

app/__init__.py

@@ -0,0 +1,10 @@
+# PENNY app package initialization
+"""
+PENNY Application Package
+
+This package contains the core orchestration, routing, and agent logic
+for the PENNY civic engagement assistant.
+"""
+
+__version__ = "2.2.0"
+__author__ = "CyberShawties"

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)

app/intents.py

@@ -0,0 +1,481 @@
+# app/intents.py
+"""
+🎯 Penny's Intent Classification System
+Rule-based intent classifier designed for civic engagement queries.
+
+CURRENT: Simple keyword matching (fast, predictable, debuggable)
+FUTURE: Will upgrade to ML/embedding-based classification (Gemma/LayoutLM)
+
+This approach allows Penny to understand resident needs and route them
+to the right civic systems — weather, resources, events, translation, etc.
+"""
+
+import logging
+from typing import Dict, List, Optional
+from dataclasses import dataclass, field
+from enum import Enum
+
+# --- LOGGING SETUP (Azure-friendly) ---
+logger = logging.getLogger(__name__)
+
+
+# --- INTENT CATEGORIES (Enumerated for type safety) ---
+class IntentType(str, Enum):
+    """
+    Penny's supported intent categories.
+    Each maps to a specific civic assistance pathway.
+    """
+    WEATHER = "weather"
+    GREETING = "greeting"
+    LOCAL_RESOURCES = "local_resources"
+    EVENTS = "events"
+    TRANSLATION = "translation"
+    SENTIMENT_ANALYSIS = "sentiment_analysis"
+    BIAS_DETECTION = "bias_detection"
+    DOCUMENT_PROCESSING = "document_processing"
+    HELP = "help"
+    EMERGENCY = "emergency"  # Critical safety routing
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class IntentMatch:
+    """
+    Structured intent classification result.
+    Includes confidence score and matched keywords for debugging.
+    """
+    intent: IntentType
+    confidence: float  # 0.0 - 1.0
+    matched_keywords: List[str]
+    is_compound: bool = False  # True if query spans multiple intents
+    secondary_intents: List[IntentType] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for logging and API responses."""
+        return {
+            "intent": self.intent.value,
+            "confidence": self.confidence,
+            "matched_keywords": self.matched_keywords,
+            "is_compound": self.is_compound,
+            "secondary_intents": [intent.value for intent in self.secondary_intents]
+        }
+
+
+# --- INTENT KEYWORD PATTERNS (Organized by priority) ---
+class IntentPatterns:
+    """
+    Penny's keyword patterns for intent matching.
+    Organized by priority — critical intents checked first.
+    """
+    
+    # 🚨 PRIORITY 1: EMERGENCY & SAFETY (Always check first)
+    EMERGENCY = [
+        "911", "emergency", "urgent", "crisis", "danger", "help me",
+        "suicide", "overdose", "assault", "abuse", "threatening",
+        "hurt myself", "hurt someone", "life threatening"
+    ]
+    
+    # 🌍 PRIORITY 2: TRANSLATION (High civic value)
+    TRANSLATION = [
+        "translate", "in spanish", "in french", "in portuguese", 
+        "in german", "in chinese", "in arabic", "in vietnamese",
+        "in russian", "in korean", "in japanese", "in tagalog",
+        "convert to", "say this in", "how do i say", "what is", "in hindi"
+    ]
+    
+    # 📄 PRIORITY 3: DOCUMENT PROCESSING (Forms, PDFs)
+    DOCUMENT_PROCESSING = [
+        "process this document", "extract data", "analyze pdf",
+        "upload form", "read this file", "scan this", "form help",
+        "fill out", "document", "pdf", "application", "permit"
+    ]
+    
+    # 🔍 PRIORITY 4: ANALYSIS TOOLS
+    SENTIMENT_ANALYSIS = [
+        "how does this sound", "is this positive", "is this negative",
+        "analyze", "sentiment", "feel about", "mood", "tone"
+    ]
+    
+    BIAS_DETECTION = [
+        "is this biased", "check bias", "check fairness", "is this neutral",
+        "biased", "objective", "subjective", "fair", "discriminatory"
+    ]
+    
+    # 🌤️ PRIORITY 5: WEATHER + EVENTS (Compound intent handling)
+    WEATHER = [
+        "weather", "rain", "snow", "sunny", "forecast", "temperature",
+        "hot", "cold", "storm", "wind", "outside", "climate",
+        "degrees", "celsius", "fahrenheit"
+    ]
+    
+    # Specific date/time keywords that suggest event context
+    DATE_TIME = [
+        "today", "tomorrow", "this weekend", "next week",
+        "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday",
+        "tonight", "this morning", "this afternoon", "this evening"
+    ]
+    
+    EVENTS = [
+        "event", "things to do", "what's happening", "activities",
+        "festival", "concert", "activity", "community event",
+        "show", "performance", "gathering", "meetup", "celebration"
+    ]
+    
+    # 🏛️ PRIORITY 6: LOCAL RESOURCES (Core civic mission)
+    LOCAL_RESOURCES = [
+        "resource", "shelter", "library", "help center",
+        "food bank", "warming center", "cooling center", "csb",
+        "mental health", "housing", "community service",
+        "trash", "recycling", "transit", "bus", "schedule",
+        "clinic", "hospital", "pharmacy", "assistance",
+        "utility", "water", "electric", "gas", "bill"
+    ]
+    
+    # 💬 PRIORITY 7: CONVERSATIONAL
+    GREETING = [
+        "hi", "hello", "hey", "what's up", "good morning",
+        "good afternoon", "good evening", "howdy", "yo",
+        "greetings", "sup", "hiya"
+    ]
+    
+    HELP = [
+        "help", "how do i", "can you help", "i need help",
+        "what can you do", "how does this work", "instructions",
+        "guide", "tutorial", "show me how"
+    ]
+
+
+def classify_intent(message: str) -> str:
+    """
+    🎯 Main classification function (backward-compatible).
+    Returns intent as string for existing API compatibility.
+    
+    Args:
+        message: User's query text
+        
+    Returns:
+        Intent string (e.g., "weather", "events", "translation")
+    """
+    try:
+        result = classify_intent_detailed(message)
+        return result.intent.value
+    except Exception as e:
+        logger.error(f"Intent classification failed: {e}", exc_info=True)
+        return IntentType.UNKNOWN.value
+
+
+def classify_intent_detailed(message: str) -> IntentMatch:
+    """
+    🧠 Enhanced classification with confidence scores and metadata.
+    
+    This function:
+    1. Checks for emergency keywords FIRST (safety routing)
+    2. Detects compound intents (e.g., "weather + events")
+    3. Returns structured result with confidence + matched keywords
+    
+    Args:
+        message: User's query text
+        
+    Returns:
+        IntentMatch object with full classification details
+    """
+    
+    if not message or not message.strip():
+        logger.warning("Empty message received for intent classification")
+        return IntentMatch(
+            intent=IntentType.UNKNOWN,
+            confidence=0.0,
+            matched_keywords=[]
+        )
+    
+    try:
+        text = message.lower().strip()
+        logger.debug(f"Classifying intent for: '{text[:50]}...'")
+        
+        # --- PRIORITY 1: EMERGENCY (Critical safety routing) ---
+        emergency_matches = _find_keyword_matches(text, IntentPatterns.EMERGENCY)
+        if emergency_matches:
+            logger.warning(f"🚨 EMERGENCY intent detected: {emergency_matches}")
+            return IntentMatch(
+                intent=IntentType.EMERGENCY,
+                confidence=1.0,  # Always high confidence for safety
+                matched_keywords=emergency_matches
+            )
+        
+        # --- PRIORITY 2: TRANSLATION ---
+        translation_matches = _find_keyword_matches(text, IntentPatterns.TRANSLATION)
+        if translation_matches:
+            return IntentMatch(
+                intent=IntentType.TRANSLATION,
+                confidence=0.9,
+                matched_keywords=translation_matches
+            )
+        
+        # --- PRIORITY 3: DOCUMENT PROCESSING ---
+        doc_matches = _find_keyword_matches(text, IntentPatterns.DOCUMENT_PROCESSING)
+        if doc_matches:
+            return IntentMatch(
+                intent=IntentType.DOCUMENT_PROCESSING,
+                confidence=0.9,
+                matched_keywords=doc_matches
+            )
+        
+        # --- PRIORITY 4: ANALYSIS TOOLS ---
+        sentiment_matches = _find_keyword_matches(text, IntentPatterns.SENTIMENT_ANALYSIS)
+        if sentiment_matches:
+            return IntentMatch(
+                intent=IntentType.SENTIMENT_ANALYSIS,
+                confidence=0.85,
+                matched_keywords=sentiment_matches
+            )
+        
+        bias_matches = _find_keyword_matches(text, IntentPatterns.BIAS_DETECTION)
+        if bias_matches:
+            return IntentMatch(
+                intent=IntentType.BIAS_DETECTION,
+                confidence=0.85,
+                matched_keywords=bias_matches
+            )
+        
+        # --- PRIORITY 5: COMPOUND INTENT HANDLING (Weather + Events) ---
+        weather_matches = _find_keyword_matches(text, IntentPatterns.WEATHER)
+        event_matches = _find_keyword_matches(text, IntentPatterns.EVENTS)
+        date_matches = _find_keyword_matches(text, IntentPatterns.DATE_TIME)
+        
+        # Compound detection: "What events are happening this weekend?"
+        # or "What's the weather like for Sunday's festival?"
+        if event_matches and (weather_matches or date_matches):
+            logger.info("Compound intent detected: events + weather/date")
+            return IntentMatch(
+                intent=IntentType.EVENTS,  # Primary intent
+                confidence=0.85,
+                matched_keywords=event_matches + weather_matches + date_matches,
+                is_compound=True,
+                secondary_intents=[IntentType.WEATHER]
+            )
+        
+        # --- PRIORITY 6: SIMPLE WEATHER INTENT ---
+        if weather_matches:
+            return IntentMatch(
+                intent=IntentType.WEATHER,
+                confidence=0.9,
+                matched_keywords=weather_matches
+            )
+        
+        # --- PRIORITY 7: LOCAL RESOURCES ---
+        resource_matches = _find_keyword_matches(text, IntentPatterns.LOCAL_RESOURCES)
+        if resource_matches:
+            return IntentMatch(
+                intent=IntentType.LOCAL_RESOURCES,
+                confidence=0.9,
+                matched_keywords=resource_matches
+            )
+        
+        # --- PRIORITY 8: EVENTS (Simple check) ---
+        if event_matches:
+            return IntentMatch(
+                intent=IntentType.EVENTS,
+                confidence=0.85,
+                matched_keywords=event_matches
+            )
+        
+        # --- PRIORITY 9: CONVERSATIONAL ---
+        greeting_matches = _find_keyword_matches(text, IntentPatterns.GREETING)
+        if greeting_matches:
+            return IntentMatch(
+                intent=IntentType.GREETING,
+                confidence=0.8,
+                matched_keywords=greeting_matches
+            )
+        
+        help_matches = _find_keyword_matches(text, IntentPatterns.HELP)
+        if help_matches:
+            return IntentMatch(
+                intent=IntentType.HELP,
+                confidence=0.9,
+                matched_keywords=help_matches
+            )
+        
+        # --- FALLBACK: UNKNOWN ---
+        logger.info(f"No clear intent match for: '{text[:50]}...'")
+        return IntentMatch(
+            intent=IntentType.UNKNOWN,
+            confidence=0.0,
+            matched_keywords=[]
+        )
+        
+    except Exception as e:
+        logger.error(f"Error during intent classification: {e}", exc_info=True)
+        return IntentMatch(
+            intent=IntentType.UNKNOWN,
+            confidence=0.0,
+            matched_keywords=[],
+        )
+
+
+# --- HELPER FUNCTIONS ---
+
+def _find_keyword_matches(text: str, keywords: List[str]) -> List[str]:
+    """
+    Finds which keywords from a pattern list appear in the user's message.
+    
+    Args:
+        text: Normalized user message (lowercase)
+        keywords: List of keywords to search for
+        
+    Returns:
+        List of matched keywords (for debugging/logging)
+    """
+    try:
+        matches = []
+        for keyword in keywords:
+            if keyword in text:
+                matches.append(keyword)
+        return matches
+    except Exception as e:
+        logger.error(f"Error finding keyword matches: {e}", exc_info=True)
+        return []
+
+
+def get_intent_description(intent: IntentType) -> str:
+    """
+    🗣️ Penny's plain-English explanation of what each intent does.
+    Useful for help systems and debugging.
+    
+    Args:
+        intent: IntentType enum value
+        
+    Returns:
+        Human-readable description of the intent
+    """
+    descriptions = {
+        IntentType.WEATHER: "Get current weather conditions and forecasts for your area",
+        IntentType.GREETING: "Start a conversation with Penny",
+        IntentType.LOCAL_RESOURCES: "Find community resources like shelters, libraries, and services",
+        IntentType.EVENTS: "Discover local events and activities happening in your city",
+        IntentType.TRANSLATION: "Translate text between 27 languages",
+        IntentType.SENTIMENT_ANALYSIS: "Analyze the emotional tone of text",
+        IntentType.BIAS_DETECTION: "Check text for potential bias or fairness issues",
+        IntentType.DOCUMENT_PROCESSING: "Process PDFs and forms to extract information",
+        IntentType.HELP: "Learn how to use Penny's features",
+        IntentType.EMERGENCY: "Connect with emergency services and crisis support",
+        IntentType.UNKNOWN: "I'm not sure what you're asking — can you rephrase?"
+    }
+    return descriptions.get(intent, "Unknown intent type")
+
+
+def get_all_supported_intents() -> Dict[str, str]:
+    """
+    📋 Returns all supported intents with descriptions.
+    Useful for /help endpoints and documentation.
+    
+    Returns:
+        Dictionary mapping intent values to descriptions
+    """
+    try:
+        return {
+            intent.value: get_intent_description(intent)
+            for intent in IntentType
+            if intent != IntentType.UNKNOWN
+        }
+    except Exception as e:
+        logger.error(f"Error getting supported intents: {e}", exc_info=True)
+        return {}
+
+
+# --- FUTURE ML UPGRADE HOOK ---
+def classify_intent_ml(message: str, use_embedding_model: bool = False) -> IntentMatch:
+    """
+    🔮 PLACEHOLDER for future ML-based classification.
+    
+    When ready to upgrade from keyword matching to embeddings:
+    1. Load Gemma-7B or sentence-transformers model
+    2. Generate message embeddings
+    3. Compare to intent prototype embeddings
+    4. Return top match with confidence score
+    
+    Args:
+        message: User's query
+        use_embedding_model: If True, use ML model (not implemented yet)
+        
+    Returns:
+        IntentMatch object (currently falls back to rule-based)
+    """
+    
+    if use_embedding_model:
+        logger.warning("ML-based classification not yet implemented. Falling back to rules.")
+    
+    # Fallback to rule-based for now
+    return classify_intent_detailed(message)
+
+
+# --- TESTING & VALIDATION ---
+def validate_intent_patterns() -> Dict[str, List[str]]:
+    """
+    🧪 Validates that all intent patterns are properly configured.
+    Returns any overlapping keywords that might cause conflicts.
+    
+    Returns:
+        Dictionary of overlapping keywords between intent pairs
+    """
+    try:
+        all_patterns = {
+            "emergency": IntentPatterns.EMERGENCY,
+            "translation": IntentPatterns.TRANSLATION,
+            "document": IntentPatterns.DOCUMENT_PROCESSING,
+            "sentiment": IntentPatterns.SENTIMENT_ANALYSIS,
+            "bias": IntentPatterns.BIAS_DETECTION,
+            "weather": IntentPatterns.WEATHER,
+            "events": IntentPatterns.EVENTS,
+            "resources": IntentPatterns.LOCAL_RESOURCES,
+            "greeting": IntentPatterns.GREETING,
+            "help": IntentPatterns.HELP
+        }
+        
+        overlaps = {}
+        
+        # Check for keyword overlap between different intents
+        for intent1, keywords1 in all_patterns.items():
+            for intent2, keywords2 in all_patterns.items():
+                if intent1 >= intent2:  # Avoid duplicate comparisons
+                    continue
+                
+                overlap = set(keywords1) & set(keywords2)
+                if overlap:
+                    key = f"{intent1}_vs_{intent2}"
+                    overlaps[key] = list(overlap)
+        
+        if overlaps:
+            logger.warning(f"Found keyword overlaps between intents: {overlaps}")
+        
+        return overlaps
+        
+    except Exception as e:
+        logger.error(f"Error validating intent patterns: {e}", exc_info=True)
+        return {}
+
+
+# --- LOGGING SAMPLE CLASSIFICATIONS (For monitoring) ---
+def log_intent_classification(message: str, result: IntentMatch) -> None:
+    """
+    📊 Logs classification results for Azure Application Insights.
+    Helps track intent distribution and confidence patterns.
+    
+    Args:
+        message: Original user message (truncated for PII safety)
+        result: IntentMatch classification result
+    """
+    try:
+        # Truncate message for PII safety
+        safe_message = message[:50] + "..." if len(message) > 50 else message
+        
+        logger.info(
+            f"Intent classified | "
+            f"intent={result.intent.value} | "
+            f"confidence={result.confidence:.2f} | "
+            f"compound={result.is_compound} | "
+            f"keywords={result.matched_keywords[:5]} | "  # Limit logged keywords
+            f"message_preview='{safe_message}'"
+        )
+    except Exception as e:
+        logger.error(f"Error logging intent classification: {e}", exc_info=True)

app/location_utils.py

@@ -0,0 +1,717 @@
+# app/location_utils.py
+"""
+🗺️ Penny's Location Intelligence System
+Handles city detection, tenant routing, and geographic data loading.
+
+MISSION: Connect residents to the right local resources, regardless of how
+they describe their location — whether it's "Atlanta", "ATL", "30303", or "near me".
+
+CURRENT: Rule-based city matching with 6 supported cities
+FUTURE: Will add ZIP→city mapping, geocoding API, and user location preferences
+"""
+
+import re
+import json
+import os
+import logging
+from typing import Dict, Any, Optional, List, Tuple
+from pathlib import Path
+from dataclasses import dataclass
+from enum import Enum
+
+# --- LOGGING SETUP (Azure-friendly) ---
+logger = logging.getLogger(__name__)
+
+# --- BASE PATHS (OS-agnostic for Azure/Windows/Linux) ---
+BASE_DIR = Path(__file__).parent.parent.resolve()
+DATA_PATH = BASE_DIR / "data"
+EVENTS_PATH = DATA_PATH / "events"
+RESOURCES_PATH = DATA_PATH / "resources"
+
+# Ensure critical directories exist (Azure deployment safety)
+for path in [DATA_PATH, EVENTS_PATH, RESOURCES_PATH]:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+# ============================================================
+# CITY REGISTRY (Penny's Supported Cities)
+# ============================================================
+
+@dataclass
+class CityInfo:
+    """
+    Structured information about a city Penny supports.
+    Makes it easy to add new cities with metadata.
+    """
+    tenant_id: str          # Standard format: cityname_state (e.g., "atlanta_ga")
+    full_name: str          # Display name: "Atlanta, GA"
+    state: str              # Two-letter state code
+    aliases: List[str]      # Common variations users might say
+    timezone: str           # IANA timezone (e.g., "America/New_York")
+    lat: Optional[float] = None  # For weather API fallback
+    lon: Optional[float] = None
+    
+    def __post_init__(self):
+        # Normalize all aliases to lowercase for matching
+        self.aliases = [alias.lower().strip() for alias in self.aliases]
+
+
+class SupportedCities:
+    """
+    🏙️ Penny's city registry.
+    Each city gets standardized metadata for consistent routing.
+    """
+    
+    ATLANTA = CityInfo(
+        tenant_id="atlanta_ga",
+        full_name="Atlanta, GA",
+        state="GA",
+        timezone="America/New_York",
+        lat=33.7490,
+        lon=-84.3880,
+        aliases=[
+            "atlanta", "atl", "atlanta ga", "atlanta, ga",
+            "city of atlanta", "hotlanta", "the atl"
+        ]
+    )
+    
+    BIRMINGHAM = CityInfo(
+        tenant_id="birmingham_al",
+        full_name="Birmingham, AL",
+        state="AL",
+        timezone="America/Chicago",
+        lat=33.5207,
+        lon=-86.8025,
+        aliases=[
+            "birmingham", "birmingham al", "birmingham, al",
+            "city of birmingham", "bham"
+        ]
+    )
+    
+    CHESTERFIELD = CityInfo(
+        tenant_id="chesterfield_va",
+        full_name="Chesterfield, VA",
+        state="VA",
+        timezone="America/New_York",
+        lat=37.3771,
+        lon=-77.5047,
+        aliases=[
+            "chesterfield", "chesterfield va", "chesterfield, va",
+            "chesterfield county"
+        ]
+    )
+    
+    EL_PASO = CityInfo(
+        tenant_id="el_paso_tx",
+        full_name="El Paso, TX",
+        state="TX",
+        timezone="America/Denver",
+        lat=31.7619,
+        lon=-106.4850,
+        aliases=[
+            "el paso", "el paso tx", "el paso, tx",
+            "city of el paso", "elpaso"
+        ]
+    )
+    
+    PROVIDENCE = CityInfo(
+        tenant_id="providence_ri",
+        full_name="Providence, RI",
+        state="RI",
+        timezone="America/New_York",
+        lat=41.8240,
+        lon=-71.4128,
+        aliases=[
+            "providence", "providence ri", "providence, ri",
+            "city of providence", "pvd"
+        ]
+    )
+    
+    SEATTLE = CityInfo(
+        tenant_id="seattle_wa",
+        full_name="Seattle, WA",
+        state="WA",
+        timezone="America/Los_Angeles",
+        lat=47.6062,
+        lon=-122.3321,
+        aliases=[
+            "seattle", "seattle wa", "seattle, wa",
+            "city of seattle", "emerald city", "sea"
+        ]
+    )
+    
+    @classmethod
+    def get_all_cities(cls) -> List[CityInfo]:
+        """Returns list of all supported cities."""
+        return [
+            cls.ATLANTA,
+            cls.BIRMINGHAM,
+            cls.CHESTERFIELD,
+            cls.EL_PASO,
+            cls.PROVIDENCE,
+            cls.SEATTLE
+        ]
+    
+    @classmethod
+    def get_city_by_tenant_id(cls, tenant_id: str) -> Optional[CityInfo]:
+        """Lookup city info by tenant ID."""
+        for city in cls.get_all_cities():
+            if city.tenant_id == tenant_id:
+                return city
+        return None
+
+
+# ============================================================
+# BUILD DYNAMIC CITY PATTERNS (from CityInfo registry)
+# ============================================================
+
+def _build_city_patterns() -> Dict[str, str]:
+    """
+    Generates city matching dictionary from the CityInfo registry.
+    This keeps the pattern matching backward-compatible with existing code.
+    """
+    patterns = {}
+    for city in SupportedCities.get_all_cities():
+        for alias in city.aliases:
+            patterns[alias] = city.tenant_id
+    return patterns
+
+
+# Dynamic pattern dictionary (auto-generated from city registry)
+REAL_CITY_PATTERNS = _build_city_patterns()
+
+
+# ============================================================
+# LOCATION DETECTION ENUMS
+# ============================================================
+
+class LocationStatus(str, Enum):
+    """
+    Status codes for location detection results.
+    """
+    FOUND = "found"                      # Valid city matched
+    ZIP_DETECTED = "zip_detected"        # ZIP code found (needs mapping)
+    USER_LOCATION_NEEDED = "user_location_needed"  # "near me" detected
+    UNKNOWN = "unknown"                  # No match found
+    AMBIGUOUS = "ambiguous"              # Multiple possible matches
+
+
+@dataclass
+class LocationMatch:
+    """
+    Structured result from location detection.
+    Includes confidence and matched patterns for debugging.
+    """
+    status: LocationStatus
+    tenant_id: Optional[str] = None
+    city_info: Optional[CityInfo] = None
+    confidence: float = 0.0  # 0.0 - 1.0
+    matched_pattern: Optional[str] = None
+    alternatives: List[str] = None
+    
+    def __post_init__(self):
+        if self.alternatives is None:
+            self.alternatives = []
+
+
+# ============================================================
+# ZIP CODE PATTERNS (for future expansion)
+# ============================================================
+
+ZIP_PATTERN = re.compile(r"\b\d{5}(?:-\d{4})?\b")  # Matches 12345 or 12345-6789
+
+# Future ZIP → City mapping (placeholder)
+ZIP_TO_CITY_MAP: Dict[str, str] = {
+    # Atlanta metro
+    "30303": "atlanta_ga",
+    "30318": "atlanta_ga",
+    "30309": "atlanta_ga",
+    
+    # Birmingham metro
+    "35203": "birmingham_al",
+    "35233": "birmingham_al",
+    
+    # Chesterfield County
+    "23832": "chesterfield_va",
+    "23838": "chesterfield_va",
+    
+    # El Paso
+    "79901": "el_paso_tx",
+    "79936": "el_paso_tx",
+    
+    # Providence
+    "02903": "providence_ri",
+    "02904": "providence_ri",
+    
+    # Seattle metro
+    "98101": "seattle_wa",
+    "98104": "seattle_wa",
+    "98122": "seattle_wa",
+}
+
+
+# ============================================================
+# MAIN CITY EXTRACTION LOGIC (Enhanced)
+# ============================================================
+
+def extract_city_name(text: str) -> str:
+    """
+    🎯 BACKWARD-COMPATIBLE location extraction (returns tenant_id string).
+    
+    Extracts tenant ID (e.g., 'atlanta_ga') from user input.
+    
+    Args:
+        text: User's location input (e.g., "Atlanta", "30303", "near me")
+        
+    Returns:
+        Tenant ID string or status code:
+        - Valid tenant_id (e.g., "atlanta_ga")
+        - "zip_detected" (ZIP code found, needs mapping)
+        - "user_location_needed" ("near me" detected)
+        - "unknown" (no match)
+    """
+    result = extract_location_detailed(text)
+    return result.tenant_id or result.status.value
+
+
+def extract_location_detailed(text: str) -> LocationMatch:
+    """
+    🧠 ENHANCED location extraction with confidence scoring.
+    
+    This function intelligently parses location references and returns
+    structured results with metadata for better error handling.
+    
+    Args:
+        text: User's location input
+        
+    Returns:
+        LocationMatch object with full detection details
+    """
+    
+    if not text or not text.strip():
+        logger.warning("Empty text provided to location extraction")
+        return LocationMatch(
+            status=LocationStatus.UNKNOWN,
+            confidence=0.0
+        )
+    
+    lowered = text.lower().strip()
+    logger.debug(f"Extracting location from: '{lowered}'")
+    
+    # --- STEP 1: Check for "near me" / location services needed ---
+    near_me_phrases = [
+        "near me", "my area", "my city", "my neighborhood",
+        "where i am", "current location", "my location",
+        "around here", "locally", "in my town"
+    ]
+    
+    if any(phrase in lowered for phrase in near_me_phrases):
+        logger.info("User location services required")
+        return LocationMatch(
+            status=LocationStatus.USER_LOCATION_NEEDED,
+            confidence=1.0,
+            matched_pattern="near_me_detected"
+        )
+    
+    # --- STEP 2: Check for ZIP codes ---
+    zip_matches = ZIP_PATTERN.findall(text)
+    if zip_matches:
+        zip_code = zip_matches[0]  # Take first ZIP if multiple
+        
+        # Try to map ZIP to known city
+        if zip_code in ZIP_TO_CITY_MAP:
+            tenant_id = ZIP_TO_CITY_MAP[zip_code]
+            city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+            logger.info(f"ZIP {zip_code} mapped to {tenant_id}")
+            return LocationMatch(
+                status=LocationStatus.FOUND,
+                tenant_id=tenant_id,
+                city_info=city_info,
+                confidence=0.95,
+                matched_pattern=f"zip:{zip_code}"
+            )
+        else:
+            logger.info(f"ZIP code detected but not mapped: {zip_code}")
+            return LocationMatch(
+                status=LocationStatus.ZIP_DETECTED,
+                confidence=0.5,
+                matched_pattern=f"zip:{zip_code}"
+            )
+    
+    # --- STEP 3: Match against city patterns ---
+    matches = []
+    for pattern, tenant_id in REAL_CITY_PATTERNS.items():
+        if pattern in lowered:
+            matches.append((pattern, tenant_id))
+    
+    if not matches:
+        logger.info(f"No city match found for: '{lowered}'")
+        return LocationMatch(
+            status=LocationStatus.UNKNOWN,
+            confidence=0.0
+        )
+    
+    # If multiple matches, pick the longest pattern (most specific)
+    # Example: "atlanta" vs "city of atlanta" — pick the longer one
+    matches.sort(key=lambda x: len(x[0]), reverse=True)
+    best_pattern, best_tenant_id = matches[0]
+    
+    city_info = SupportedCities.get_city_by_tenant_id(best_tenant_id)
+    
+    # Calculate confidence based on match specificity
+    confidence = min(len(best_pattern) / len(lowered), 1.0)
+    
+    result = LocationMatch(
+        status=LocationStatus.FOUND,
+        tenant_id=best_tenant_id,
+        city_info=city_info,
+        confidence=confidence,
+        matched_pattern=best_pattern
+    )
+    
+    # Check for ambiguity (multiple different cities matched)
+    unique_tenant_ids = set(tid for _, tid in matches)
+    if len(unique_tenant_ids) > 1:
+        result.status = LocationStatus.AMBIGUOUS
+        result.alternatives = [tid for _, tid in matches if tid != best_tenant_id]
+        logger.warning(f"Ambiguous location match: {unique_tenant_ids}")
+    
+    logger.info(f"Location matched: {best_tenant_id} (confidence: {confidence:.2f})")
+    return result
+
+
+# ============================================================
+# DATA LOADING UTILITIES (Enhanced with error handling)
+# ============================================================
+
+def load_city_data(directory: Path, tenant_id: str) -> Dict[str, Any]:
+    """
+    🗄️ Generic utility to load JSON data for a given tenant ID.
+    
+    Args:
+        directory: Base path (EVENTS_PATH or RESOURCES_PATH)
+        tenant_id: City identifier (e.g., 'atlanta_ga')
+        
+    Returns:
+        Parsed JSON content as dictionary
+        
+    Raises:
+        FileNotFoundError: If the JSON file doesn't exist
+        json.JSONDecodeError: If the file is malformed
+    """
+    
+    file_path = directory / f"{tenant_id}.json"
+    
+    if not file_path.exists():
+        logger.error(f"Data file not found: {file_path}")
+        raise FileNotFoundError(f"Data file not found: {file_path}")
+    
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            logger.debug(f"Loaded data from {file_path}")
+            return data
+    except json.JSONDecodeError as e:
+        logger.error(f"Invalid JSON in {file_path}: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Error reading {file_path}: {e}", exc_info=True)
+        raise
+
+
+def load_city_events(tenant_id: str) -> Dict[str, Any]:
+    """
+    📅 Loads structured event data for a given city.
+    
+    Args:
+        tenant_id: City identifier (e.g., 'atlanta_ga')
+        
+    Returns:
+        Event data structure with 'events' key containing list of events
+        
+    Example:
+        {
+            "city": "Atlanta, GA",
+            "events": [
+                {"name": "Jazz Festival", "category": "outdoor", ...},
+                ...
+            ]
+        }
+    """
+    logger.info(f"Loading events for {tenant_id}")
+    return load_city_data(EVENTS_PATH, tenant_id)
+
+
+def load_city_resources(tenant_id: str) -> Dict[str, Any]:
+    """
+    🏛️ Loads civic resource data for a given city.
+    
+    Args:
+        tenant_id: City identifier (e.g., 'atlanta_ga')
+        
+    Returns:
+        Resource data structure with categorized resources
+        
+    Example:
+        {
+            "city": "Atlanta, GA",
+            "resources": {
+                "shelters": [...],
+                "food_banks": [...],
+                "libraries": [...]
+            }
+        }
+    """
+    logger.info(f"Loading resources for {tenant_id}")
+    return load_city_data(RESOURCES_PATH, tenant_id)
+
+
+# ============================================================
+# UTILITY FUNCTIONS
+# ============================================================
+
+def normalize_location_name(text: str) -> str:
+    """
+    🧹 Normalize location names into consistent format.
+    Removes spaces, hyphens, and special characters.
+    
+    Example:
+        "El Paso, TX" → "elpasotx"
+        "Chesterfield County" → "chesterfieldcounty"
+    """
+    if not text:
+        return ""
+    
+    # Remove punctuation and spaces
+    normalized = re.sub(r"[\s\-,\.]+", "", text.lower().strip())
+    return normalized
+
+
+def get_city_coordinates(tenant_id: str) -> Optional[Dict[str, float]]:
+    """
+    🗺️ Returns coordinates for a city as a dictionary.
+    Useful for weather API calls.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Dictionary with "lat" and "lon" keys, or None if not found
+        
+    Note: This function returns a dict for consistency with orchestrator usage.
+    Use tuple unpacking: coords = get_city_coordinates(tenant_id); lat, lon = coords["lat"], coords["lon"]
+    """
+    city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+    if city_info and city_info.lat is not None and city_info.lon is not None:
+        return {"lat": city_info.lat, "lon": city_info.lon}
+    return None
+
+
+def get_city_info(tenant_id: str) -> Optional[Dict[str, Any]]:
+    """
+    🏙️ Returns city information dictionary.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Dictionary with city information (name, state, coordinates, etc.) or None
+    """
+    city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+    if city_info:
+        return {
+            "tenant_id": city_info.tenant_id,
+            "full_name": city_info.full_name,
+            "state": city_info.state,
+            "timezone": city_info.timezone,
+            "lat": city_info.lat,
+            "lon": city_info.lon,
+            "aliases": city_info.aliases
+        }
+    return None
+
+
+def detect_location_from_text(text: str) -> Dict[str, Any]:
+    """
+    🔍 Detects location from text input.
+    
+    Args:
+        text: User input text
+        
+    Returns:
+        Dictionary with keys:
+        - found: bool (whether location was detected)
+        - tenant_id: str (if found)
+        - city_info: dict (if found)
+        - confidence: float (0.0-1.0)
+    """
+    result = extract_location_detailed(text)
+    
+    return {
+        "found": result.status == LocationStatus.FOUND,
+        "tenant_id": result.tenant_id,
+        "city_info": {
+            "tenant_id": result.city_info.tenant_id,
+            "full_name": result.city_info.full_name,
+            "state": result.city_info.state
+        } if result.city_info else None,
+        "confidence": result.confidence,
+        "status": result.status.value
+    }
+
+
+def validate_coordinates(lat: float, lon: float) -> Tuple[bool, Optional[str]]:
+    """
+    ✅ Validates latitude and longitude coordinates.
+    
+    Args:
+        lat: Latitude (-90 to 90)
+        lon: Longitude (-180 to 180)
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+        - is_valid: True if coordinates are valid
+        - error_message: None if valid, error description if invalid
+    """
+    if not isinstance(lat, (int, float)) or not isinstance(lon, (int, float)):
+        return False, "Coordinates must be numeric values"
+    
+    if not (-90 <= lat <= 90):
+        return False, f"Latitude must be between -90 and 90, got {lat}"
+    
+    if not (-180 <= lon <= 180):
+        return False, f"Longitude must be between -180 and 180, got {lon}"
+    
+    return True, None
+
+
+def get_city_timezone(tenant_id: str) -> Optional[str]:
+    """
+    🕐 Returns IANA timezone string for a city.
+    Useful for time-sensitive features (events, business hours).
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        IANA timezone string (e.g., "America/New_York") or None
+    """
+    city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+    return city_info.timezone if city_info else None
+
+
+def validate_tenant_id(tenant_id: str) -> bool:
+    """
+    ✅ Checks if a tenant_id is valid and supported.
+    
+    Args:
+        tenant_id: City identifier to validate
+        
+    Returns:
+        True if valid and supported, False otherwise
+    """
+    city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+    return city_info is not None
+
+
+def get_all_supported_cities() -> List[Dict[str, str]]:
+    """
+    📋 Returns list of all supported cities for API responses.
+    
+    Returns:
+        List of city info dictionaries with tenant_id and display name
+        
+    Example:
+        [
+            {"tenant_id": "atlanta_ga", "name": "Atlanta, GA"},
+            {"tenant_id": "seattle_wa", "name": "Seattle, WA"},
+            ...
+        ]
+    """
+    return [
+        {
+            "tenant_id": city.tenant_id,
+            "name": city.full_name,
+            "state": city.state
+        }
+        for city in SupportedCities.get_all_cities()
+    ]
+
+
+# ============================================================
+# DATA VALIDATION (For startup checks)
+# ============================================================
+
+def validate_city_data_files() -> Dict[str, Dict[str, bool]]:
+    """
+    🧪 Validates that all expected data files exist.
+    Useful for startup checks and deployment verification.
+    
+    Returns:
+        Dictionary mapping tenant_id to file existence status
+        
+    Example:
+        {
+            "atlanta_ga": {"events": True, "resources": True},
+            "seattle_wa": {"events": False, "resources": True}
+        }
+    """
+    validation_results = {}
+    
+    for city in SupportedCities.get_all_cities():
+        tenant_id = city.tenant_id
+        events_file = EVENTS_PATH / f"{tenant_id}.json"
+        resources_file = RESOURCES_PATH / f"{tenant_id}.json"
+        
+        validation_results[tenant_id] = {
+            "events": events_file.exists(),
+            "resources": resources_file.exists()
+        }
+        
+        if not events_file.exists():
+            logger.warning(f"Missing events file for {tenant_id}")
+        if not resources_file.exists():
+            logger.warning(f"Missing resources file for {tenant_id}")
+    
+    return validation_results
+
+
+# ============================================================
+# INITIALIZATION CHECK (Call on app startup)
+# ============================================================
+
+def initialize_location_system() -> bool:
+    """
+    🚀 Validates location system is ready.
+    Should be called during app startup.
+    
+    Returns:
+        True if system is ready, False if critical files missing
+    """
+    logger.info("🗺️ Initializing Penny's location system...")
+    
+    # Check directories exist
+    if not DATA_PATH.exists():
+        logger.error(f"Data directory not found: {DATA_PATH}")
+        return False
+    
+    # Validate city data files
+    validation = validate_city_data_files()
+    
+    total_cities = len(SupportedCities.get_all_cities())
+    cities_with_events = sum(1 for v in validation.values() if v["events"])
+    cities_with_resources = sum(1 for v in validation.values() if v["resources"])
+    
+    logger.info(f"✅ {total_cities} cities registered")
+    logger.info(f"✅ {cities_with_events}/{total_cities} cities have event data")
+    logger.info(f"✅ {cities_with_resources}/{total_cities} cities have resource data")
+    
+    # Warn about missing data but don't fail
+    missing_data = [tid for tid, status in validation.items() 
+                   if not status["events"] or not status["resources"]]
+    
+    if missing_data:
+        logger.warning(f"⚠️ Incomplete data for cities: {missing_data}")
+    
+    logger.info("🗺️ Location system initialized successfully")
+    return True

app/logging_utils.py

@@ -0,0 +1,778 @@
+# app/logging_utils.py
+"""
+📊 Penny's Logging & Analytics System
+Tracks user interactions, system performance, and civic engagement patterns.
+
+MISSION: Create an audit trail that helps improve Penny's service while
+respecting user privacy and meeting compliance requirements.
+
+FEATURES:
+- Structured JSON logging for Azure Application Insights
+- Daily log rotation for long-term storage
+- Privacy-safe request/response tracking
+- Performance monitoring
+- Error tracking with context
+- Optional Azure Blob Storage integration
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+import os
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass, asdict
+from enum import Enum
+import hashlib
+
+# --- LOGGING SETUP ---
+logger = logging.getLogger(__name__)
+
+# ============================================================
+# LOG PATH CONFIGURATION (Environment-aware)
+# ============================================================
+
+# Base directories (use pathlib for OS compatibility)
+PROJECT_ROOT = Path(__file__).parent.parent.resolve()
+LOGS_BASE_DIR = PROJECT_ROOT / "data" / "logs"
+DEFAULT_LOG_PATH = LOGS_BASE_DIR / "penny_combined.jsonl"
+
+# Environment-configurable log path
+LOG_PATH = Path(os.getenv("PENNY_LOG_PATH", str(DEFAULT_LOG_PATH)))
+
+# Ensure log directory exists on import
+LOGS_BASE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+# ============================================================
+# LOG LEVEL ENUM (For categorizing log entries)
+# ============================================================
+
+class LogLevel(str, Enum):
+    """
+    Categorizes the importance/type of log entries.
+    Maps to Azure Application Insights severity levels.
+    """
+    DEBUG = "debug"           # Detailed diagnostic info
+    INFO = "info"             # General informational messages
+    WARNING = "warning"       # Potential issues
+    ERROR = "error"           # Error events
+    CRITICAL = "critical"     # Critical failures
+    AUDIT = "audit"           # Compliance/audit trail
+
+
+class InteractionType(str, Enum):
+    """
+    Categorizes the type of user interaction.
+    Helps track which features residents use most.
+    """
+    QUERY = "query"                    # General question
+    RESOURCE_LOOKUP = "resource_lookup"  # Finding civic resources
+    TRANSLATION = "translation"        # Language translation
+    EVENT_SEARCH = "event_search"      # Looking for events
+    WEATHER = "weather"                # Weather inquiry
+    DOCUMENT = "document_processing"   # PDF/form processing
+    EMERGENCY = "emergency"            # Crisis/emergency routing
+    GREETING = "greeting"              # Conversational greeting
+    HELP = "help"                      # Help request
+    UNKNOWN = "unknown"                # Unclassified
+
+
+# ============================================================
+# STRUCTURED LOG ENTRY (Type-safe logging)
+# ============================================================
+
+@dataclass
+class PennyLogEntry:
+    """
+    📋 Structured log entry for Penny interactions.
+    
+    This format is:
+    - Azure Application Insights compatible
+    - Privacy-safe (no PII unless explicitly needed)
+    - Analytics-ready
+    - Compliance-friendly
+    """
+    # Timestamp
+    timestamp: str
+    
+    # Request Context
+    input: str
+    input_length: int
+    tenant_id: str
+    user_role: str
+    interaction_type: InteractionType
+    
+    # Response Context
+    intent: str
+    tool_used: Optional[str]
+    model_id: Optional[str]
+    response_summary: str
+    response_length: int
+    response_time_ms: Optional[float]
+    
+    # Technical Context
+    log_level: LogLevel
+    success: bool
+    error_message: Optional[str] = None
+    
+    # Location Context (Optional)
+    lat: Optional[float] = None
+    lon: Optional[float] = None
+    location_detected: Optional[str] = None
+    
+    # Privacy & Compliance
+    session_id: Optional[str] = None  # Hashed session identifier
+    contains_pii: bool = False
+    
+    # Performance Metrics
+    tokens_used: Optional[int] = None
+    cache_hit: bool = False
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts to dictionary for JSON serialization."""
+        return {k: v.value if isinstance(v, Enum) else v 
+                for k, v in asdict(self).items()}
+
+
+# ============================================================
+# DAILY LOG ROTATION
+# ============================================================
+
+def get_daily_log_path() -> Path:
+    """
+    🗓️ Returns a daily unique path for log rotation.
+    
+    Creates files like:
+        data/logs/2025-02-01.jsonl
+        data/logs/2025-02-02.jsonl
+    
+    This helps with:
+    - Log management (archive old logs)
+    - Azure Blob Storage uploads (one file per day)
+    - Performance (smaller files)
+    """
+    date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    daily_path = LOGS_BASE_DIR / f"{date_str}.jsonl"
+    
+    # Ensure directory exists
+    daily_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    return daily_path
+
+
+# ============================================================
+# MAIN LOGGING FUNCTION (Enhanced)
+# ============================================================
+
+def log_request(
+    payload: Dict[str, Any],
+    response: Dict[str, Any],
+    rotate_daily: bool = True,
+    log_level: LogLevel = LogLevel.INFO
+) -> None:
+    """
+    📝 Logs a user interaction with Penny.
+    
+    This is the primary logging function called by router.py after
+    processing each request. It creates a structured, privacy-safe
+    record of the interaction.
+    
+    Args:
+        payload: Incoming request data from router.py
+        response: Final response dictionary from orchestrator
+        rotate_daily: If True, uses daily log files
+        log_level: Severity level for this log entry
+    
+    Example:
+        log_request(
+            payload={"input": "What's the weather?", "tenant_id": "atlanta_ga"},
+            response={"intent": "weather", "response": "..."}
+        )
+    """
+    
+    try:
+        # --- Extract Core Fields ---
+        user_input = payload.get("input", "")
+        tenant_id = payload.get("tenant_id", "unknown")
+        user_role = payload.get("role", "resident")
+        
+        # --- Determine Interaction Type ---
+        intent = response.get("intent", "unknown")
+        interaction_type = _classify_interaction(intent)
+        
+        # --- Privacy: Hash Session ID (if provided) ---
+        session_id = payload.get("session_id")
+        if session_id:
+            session_id = _hash_identifier(session_id)
+        
+        # --- Detect PII (Simple check - can be enhanced) ---
+        contains_pii = _check_for_pii(user_input)
+        
+        # --- Create Structured Log Entry ---
+        log_entry = PennyLogEntry(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            input=_sanitize_input(user_input, contains_pii),
+            input_length=len(user_input),
+            tenant_id=tenant_id,
+            user_role=user_role,
+            interaction_type=interaction_type,
+            intent=intent,
+            tool_used=response.get("tool", "none"),
+            model_id=response.get("model_id"),
+            response_summary=_summarize_response(response.get("response")),
+            response_length=len(str(response.get("response", ""))),
+            response_time_ms=response.get("response_time_ms"),
+            log_level=log_level,
+            success=response.get("success", True),
+            error_message=response.get("error"),
+            lat=payload.get("lat"),
+            lon=payload.get("lon"),
+            location_detected=response.get("location_detected"),
+            session_id=session_id,
+            contains_pii=contains_pii,
+            tokens_used=response.get("tokens_used"),
+            cache_hit=response.get("cache_hit", False)
+        )
+        
+        # --- Write to File ---
+        log_path = get_daily_log_path() if rotate_daily else LOG_PATH
+        _write_log_entry(log_path, log_entry)
+        
+        # --- Optional: Send to Azure (if enabled) ---
+        if os.getenv("AZURE_LOGS_ENABLED", "false").lower() == "true":
+            _send_to_azure(log_entry)
+        
+        # --- Log to console (for Azure Application Insights) ---
+        logger.info(
+            f"Request logged | "
+            f"tenant={tenant_id} | "
+            f"intent={intent} | "
+            f"interaction={interaction_type.value} | "
+            f"success={log_entry.success}"
+        )
+        
+    except Exception as e:
+        # Failsafe: Never let logging failures crash the application
+        logger.error(f"Failed to log request: {e}", exc_info=True)
+        _emergency_log(payload, response, str(e))
+
+
+# ============================================================
+# LOG WRITING (With error handling)
+# ============================================================
+
+def _write_log_entry(log_path: Path, log_entry: PennyLogEntry) -> None:
+    """
+    📁 Writes log entry to JSONL file.
+    Handles file I/O errors gracefully.
+    """
+    try:
+        # Ensure parent directory exists
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Write as JSON Lines (append mode)
+        with open(log_path, "a", encoding="utf-8") as f:
+            json_str = json.dumps(log_entry.to_dict(), ensure_ascii=False)
+            f.write(json_str + "\n")
+            
+    except IOError as e:
+        logger.error(f"Failed to write to log file {log_path}: {e}")
+        _emergency_log_to_console(log_entry)
+    except Exception as e:
+        logger.error(f"Unexpected error writing log: {e}", exc_info=True)
+        _emergency_log_to_console(log_entry)
+
+
+def _emergency_log_to_console(log_entry: PennyLogEntry) -> None:
+    """
+    🚨 Emergency fallback: Print log to console if file writing fails.
+    Azure Application Insights will capture console output.
+    """
+    print(f"[EMERGENCY LOG] {json.dumps(log_entry.to_dict())}")
+
+
+def _emergency_log(payload: Dict, response: Dict, error: str) -> None:
+    """
+    🚨 Absolute fallback for when structured logging fails entirely.
+    """
+    emergency_entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "level": "CRITICAL",
+        "message": "Logging system failure",
+        "error": error,
+        "input_preview": str(payload.get("input", ""))[:100],
+        "response_preview": str(response.get("response", ""))[:100]
+    }
+    print(f"[LOGGING FAILURE] {json.dumps(emergency_entry)}")
+
+
+# ============================================================
+# HELPER FUNCTIONS
+# ============================================================
+
+def _classify_interaction(intent: str) -> InteractionType:
+    """
+    🏷️ Maps intent to interaction type for analytics.
+    """
+    intent_mapping = {
+        "weather": InteractionType.WEATHER,
+        "events": InteractionType.EVENT_SEARCH,
+        "local_resources": InteractionType.RESOURCE_LOOKUP,
+        "translation": InteractionType.TRANSLATION,
+        "document_processing": InteractionType.DOCUMENT,
+        "emergency": InteractionType.EMERGENCY,
+        "greeting": InteractionType.GREETING,
+        "help": InteractionType.HELP,
+    }
+    return intent_mapping.get(intent.lower(), InteractionType.UNKNOWN)
+
+
+def _summarize_response(resp: Optional[Any]) -> str:
+    """
+    ✂️ Creates a truncated summary of the response for logging.
+    Prevents log files from becoming bloated with full responses.
+    """
+    if resp is None:
+        return "No response content"
+    
+    if isinstance(resp, dict):
+        # Try to extract the most meaningful part
+        summary = (
+            resp.get("response") or
+            resp.get("summary") or
+            resp.get("message") or
+            str(resp)
+        )
+        return str(summary)[:250]
+    
+    return str(resp)[:250]
+
+
+def _hash_identifier(identifier: str) -> str:
+    """
+    🔒 Creates a privacy-safe hash of identifiers (session IDs, user IDs).
+    
+    Uses SHA256 for one-way hashing. This allows:
+    - Session tracking without storing raw IDs
+    - Privacy compliance (GDPR, CCPA)
+    - Anonymized analytics
+    """
+    return hashlib.sha256(identifier.encode()).hexdigest()[:16]
+
+
+def _check_for_pii(text: str) -> bool:
+    """
+    🔍 Simple PII detection (can be enhanced with NER models).
+    
+    Checks for common PII patterns:
+    - Social Security Numbers
+    - Email addresses
+    - Phone numbers
+    
+    Returns True if potential PII detected.
+    """
+    import re
+    
+    # SSN pattern: XXX-XX-XXXX
+    ssn_pattern = r'\b\d{3}-\d{2}-\d{4}\b'
+    
+    # Email pattern
+    email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
+    
+    # Phone pattern: various formats
+    phone_pattern = r'\b\d{3}[-.\s]?\d{3}[-.\s]?\d{4}\b'
+    
+    patterns = [ssn_pattern, email_pattern, phone_pattern]
+    
+    for pattern in patterns:
+        if re.search(pattern, text):
+            return True
+    
+    return False
+
+
+def _sanitize_input(text: str, contains_pii: bool) -> str:
+    """
+    🧹 Sanitizes user input for logging.
+    
+    If PII detected:
+    - Masks the input for privacy
+    - Keeps first/last few characters for debugging
+    
+    Args:
+        text: Original user input
+        contains_pii: Whether PII was detected
+        
+    Returns:
+        Sanitized text safe for logging
+    """
+    if not contains_pii:
+        return text
+    
+    # Mask middle portion if PII detected
+    if len(text) <= 20:
+        return "[PII_DETECTED]"
+    
+    # Keep first 10 and last 10 chars, mask middle
+    return f"{text[:10]}...[PII_MASKED]...{text[-10:]}"
+
+
+# ============================================================
+# AZURE INTEGRATION (Placeholder for future)
+# ============================================================
+
+def _send_to_azure(log_entry: PennyLogEntry) -> None:
+    """
+    ☁️ Sends log entry to Azure services.
+    
+    Options:
+    1. Azure Application Insights (custom events)
+    2. Azure Blob Storage (long-term archival)
+    3. Azure Table Storage (queryable logs)
+    
+    TODO: Implement when Azure integration is ready
+    """
+    try:
+        # Example: Send to Application Insights
+        # from applicationinsights import TelemetryClient
+        # tc = TelemetryClient(os.getenv("APPINSIGHTS_INSTRUMENTATION_KEY"))
+        # tc.track_event(
+        #     "PennyInteraction",
+        #     properties=log_entry.to_dict()
+        # )
+        # tc.flush()
+        
+        logger.debug("Azure logging not yet implemented")
+        
+    except Exception as e:
+        logger.error(f"Failed to send log to Azure: {e}")
+        # Don't raise - logging failures should never crash the app
+
+
+# ============================================================
+# LOG ANALYSIS UTILITIES
+# ============================================================
+
+def get_logs_for_date(date: str) -> List[Dict[str, Any]]:
+    """
+    📊 Retrieves all log entries for a specific date.
+    
+    Args:
+        date: Date string in YYYY-MM-DD format
+        
+    Returns:
+        List of log entry dictionaries
+        
+    Example:
+        logs = get_logs_for_date("2025-02-01")
+    """
+    log_file = LOGS_BASE_DIR / f"{date}.jsonl"
+    
+    if not log_file.exists():
+        logger.warning(f"No logs found for date: {date}")
+        return []
+    
+    logs = []
+    try:
+        with open(log_file, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    logs.append(json.loads(line))
+    except Exception as e:
+        logger.error(f"Error reading logs for {date}: {e}")
+    
+    return logs
+
+
+def get_interaction_stats(date: str) -> Dict[str, Any]:
+    """
+    📈 Generates usage statistics for a given date.
+    
+    Returns metrics like:
+    - Total interactions
+    - Interactions by type
+    - Average response time
+    - Success rate
+    - Most common intents
+    
+    Args:
+        date: Date string in YYYY-MM-DD format
+        
+    Returns:
+        Statistics dictionary
+    """
+    logs = get_logs_for_date(date)
+    
+    if not logs:
+        return {"error": "No logs found for date", "date": date}
+    
+    # Calculate statistics
+    total = len(logs)
+    successful = sum(1 for log in logs if log.get("success", False))
+    
+    # Response time statistics
+    response_times = [
+        log["response_time_ms"] 
+        for log in logs 
+        if log.get("response_time_ms") is not None
+    ]
+    avg_response_time = sum(response_times) / len(response_times) if response_times else 0
+    
+    # Interaction type breakdown
+    interaction_counts = {}
+    for log in logs:
+        itype = log.get("interaction_type", "unknown")
+        interaction_counts[itype] = interaction_counts.get(itype, 0) + 1
+    
+    # Intent breakdown
+    intent_counts = {}
+    for log in logs:
+        intent = log.get("intent", "unknown")
+        intent_counts[intent] = intent_counts.get(intent, 0) + 1
+    
+    return {
+        "date": date,
+        "total_interactions": total,
+        "successful_interactions": successful,
+        "success_rate": f"{(successful/total*100):.1f}%",
+        "avg_response_time_ms": round(avg_response_time, 2),
+        "interactions_by_type": interaction_counts,
+        "top_intents": dict(sorted(
+            intent_counts.items(),
+            key=lambda x: x[1],
+            reverse=True
+        )[:5])
+    }
+
+
+# ============================================================
+# LOG CLEANUP (For maintenance)
+# ============================================================
+
+def cleanup_old_logs(days_to_keep: int = 90) -> int:
+    """
+    🧹 Removes log files older than specified days.
+    
+    Args:
+        days_to_keep: Number of days to retain logs
+        
+    Returns:
+        Number of files deleted
+        
+    Example:
+        # Delete logs older than 90 days
+        deleted = cleanup_old_logs(90)
+    """
+    from datetime import timedelta
+    
+    cutoff_date = datetime.now(timezone.utc) - timedelta(days=days_to_keep)
+    deleted_count = 0
+    
+    try:
+        for log_file in LOGS_BASE_DIR.glob("*.jsonl"):
+            try:
+                # Parse date from filename (YYYY-MM-DD.jsonl)
+                date_str = log_file.stem
+                file_date = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+                
+                if file_date < cutoff_date:
+                    log_file.unlink()
+                    deleted_count += 1
+                    logger.info(f"Deleted old log file: {log_file.name}")
+                    
+            except ValueError:
+                # Skip files that don't match date format
+                continue
+                
+    except Exception as e:
+        logger.error(f"Error during log cleanup: {e}")
+    
+    logger.info(f"Log cleanup complete: {deleted_count} files deleted")
+    return deleted_count
+
+
+# ============================================================
+# PUBLIC API FUNCTIONS (Used by other modules)
+# ============================================================
+
+def log_interaction(
+    tenant_id: Optional[str] = None,
+    interaction_type: Optional[str] = None,
+    intent: Optional[str] = None,
+    response_time_ms: Optional[float] = None,
+    success: Optional[bool] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> None:
+    """
+    📝 Simplified logging function used throughout Penny's codebase.
+    
+    This is the main logging function called by orchestrator, router, agents, and model utils.
+    It creates a structured log entry and writes it to the log file.
+    
+    Args:
+        tenant_id: City/location identifier (optional)
+        interaction_type: Type of interaction (e.g., "weather", "events", "orchestration") (optional)
+        intent: Detected intent (e.g., "weather", "emergency") (optional)
+        response_time_ms: Response time in milliseconds (optional)
+        success: Whether the operation succeeded (optional)
+        metadata: Optional additional metadata dictionary
+        **kwargs: Additional fields to include in log entry (e.g., error, details, fallback_used)
+        
+    Example:
+        log_interaction(
+            tenant_id="atlanta_ga",
+            interaction_type="weather",
+            intent="weather",
+            response_time_ms=150.5,
+            success=True,
+            metadata={"temperature": 72, "condition": "sunny"}
+        )
+        
+        # Or with keyword arguments:
+        log_interaction(
+            intent="translation_initialization",
+            success=False,
+            error="model_loader unavailable"
+        )
+    """
+    try:
+        # Build log entry dictionary from provided parameters
+        log_entry_dict = {
+            "timestamp": datetime.now(timezone.utc).isoformat()
+        }
+        
+        # Add standard fields if provided
+        if tenant_id is not None:
+            log_entry_dict["tenant_id"] = sanitize_for_logging(tenant_id)
+        if interaction_type is not None:
+            log_entry_dict["interaction_type"] = interaction_type
+        if intent is not None:
+            log_entry_dict["intent"] = intent
+        if response_time_ms is not None:
+            log_entry_dict["response_time_ms"] = round(response_time_ms, 2)
+        if success is not None:
+            log_entry_dict["success"] = success
+        
+        # Add metadata if provided
+        if metadata:
+            # Sanitize metadata values
+            sanitized_metadata = {}
+            for key, value in metadata.items():
+                if isinstance(value, str):
+                    sanitized_metadata[key] = sanitize_for_logging(value)
+                else:
+                    sanitized_metadata[key] = value
+            log_entry_dict["metadata"] = sanitized_metadata
+        
+        # Add any additional kwargs (for backward compatibility with model utils)
+        for key, value in kwargs.items():
+            if key not in log_entry_dict:  # Don't overwrite standard fields
+                if isinstance(value, str):
+                    log_entry_dict[key] = sanitize_for_logging(value)
+                else:
+                    log_entry_dict[key] = value
+        
+        # Write to log file
+        log_path = get_daily_log_path()
+        _write_log_entry_dict(log_path, log_entry_dict)
+        
+    except Exception as e:
+        # Failsafe: Never let logging failures crash the application
+        logger.error(f"Failed to log interaction: {e}", exc_info=True)
+        _emergency_log_to_console_dict(log_entry_dict if 'log_entry_dict' in locals() else {})
+
+
+def sanitize_for_logging(text: str) -> str:
+    """
+    🧹 Sanitizes text for safe logging (removes PII).
+    
+    This function is used throughout Penny to ensure sensitive information
+    is not logged. It checks for PII and masks it appropriately.
+    
+    Args:
+        text: Text to sanitize
+        
+    Returns:
+        Sanitized text safe for logging
+        
+    Example:
+        safe_text = sanitize_for_logging("My email is user@example.com")
+        # Returns: "My email is [PII_DETECTED]"
+    """
+    if not text or not isinstance(text, str):
+        return str(text) if text else ""
+    
+    # Check for PII
+    contains_pii = _check_for_pii(text)
+    
+    if contains_pii:
+        # Mask PII
+        if len(text) <= 20:
+            return "[PII_DETECTED]"
+        return f"{text[:10]}...[PII_MASKED]...{text[-10:]}"
+    
+    return text
+
+
+def _write_log_entry_dict(log_path: Path, log_entry_dict: Dict[str, Any]) -> None:
+    """
+    📁 Writes log entry dictionary to JSONL file.
+    Helper function for simplified logging.
+    """
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as f:
+            json_str = json.dumps(log_entry_dict, ensure_ascii=False)
+            f.write(json_str + "\n")
+    except Exception as e:
+        logger.error(f"Failed to write log entry: {e}")
+        _emergency_log_to_console_dict(log_entry_dict)
+
+
+def _emergency_log_to_console_dict(log_entry_dict: Dict[str, Any]) -> None:
+    """
+    🚨 Emergency fallback: Print log to console if file writing fails.
+    """
+    print(f"[EMERGENCY LOG] {json.dumps(log_entry_dict)}")
+
+
+# ============================================================
+# INITIALIZATION
+# ============================================================
+
+def initialize_logging_system() -> bool:
+    """
+    🚀 Initializes the logging system.
+    Should be called during app startup.
+    
+    Returns:
+        True if initialization successful
+    """
+    logger.info("📊 Initializing Penny's logging system...")
+    
+    try:
+        # Ensure log directory exists
+        LOGS_BASE_DIR.mkdir(parents=True, exist_ok=True)
+        
+        # Test write permissions
+        test_file = LOGS_BASE_DIR / ".write_test"
+        test_file.write_text("test")
+        test_file.unlink()
+        
+        logger.info(f"✅ Logging system initialized")
+        logger.info(f"📁 Log directory: {LOGS_BASE_DIR}")
+        logger.info(f"🔄 Daily rotation: Enabled")
+        
+        # Log Azure status
+        if os.getenv("AZURE_LOGS_ENABLED") == "true":
+            logger.info("☁️ Azure logging: Enabled")
+        else:
+            logger.info("💾 Azure logging: Disabled (local only)")
+        
+        return True
+        
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize logging system: {e}")
+        return False

app/main.py

@@ -0,0 +1,660 @@
+# app/main.py
+"""
+🤖 PENNY - People's Engagement Network Navigator for You
+FastAPI Entry Point with Azure-Ready Configuration
+
+This is Penny's front door. She loads her environment, registers all her endpoints,
+and makes sure she's ready to help residents find what they need.
+
+MISSION: Connect residents to civic resources through a warm, multilingual interface
+that removes barriers and empowers communities.
+"""
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+import logging
+import sys
+import os
+from dotenv import load_dotenv
+import pathlib
+from typing import Dict, Any, Optional, List
+from datetime import datetime, timedelta
+
+# --- LOGGING CONFIGURATION (Must be set up before other imports) ---
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+logger = logging.getLogger(__name__)
+
+# --- CRITICAL: FORCE .ENV LOADING BEFORE ANY OTHER IMPORTS ---
+# Determine the absolute path to the project root
+PROJECT_ROOT = pathlib.Path(__file__).parent.parent
+
+# Load environment variables into the active Python session IMMEDIATELY
+# This ensures Azure Maps keys, API tokens, and model paths are available
+try:
+    load_dotenv(PROJECT_ROOT / ".env")
+    
+    # Verify critical environment variables are loaded
+    REQUIRED_ENV_VARS = ["AZURE_MAPS_KEY"]
+    missing_vars = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]
+    if missing_vars:
+        logger.warning(f"⚠️  WARNING: Missing required environment variables: {missing_vars}")
+        logger.warning(f"📁 Looking for .env file at: {PROJECT_ROOT / '.env'}")
+    else:
+        logger.info("✅ Environment variables loaded successfully")
+except Exception as e:
+    logger.error(f"❌ Error loading environment variables: {e}")
+    logger.error(f"📁 Expected .env location: {PROJECT_ROOT / '.env'}")
+
+# --- NOW SAFE TO IMPORT MODULES THAT DEPEND ON ENV VARS ---
+try:
+    from app.weather_agent import get_weather_for_location
+    from app.router import router as api_router
+    from app.location_utils import (
+        initialize_location_system,
+        get_all_supported_cities,
+        validate_city_data_files,
+        SupportedCities,
+        get_city_coordinates
+    )
+except ImportError as e:
+    logger.error(f"❌ Critical import error: {e}")
+    logger.error("⚠️  Penny cannot start without core modules")
+    sys.exit(1)
+
+# --- FASTAPI APP INITIALIZATION ---
+app = FastAPI(
+    title="PENNY - Civic Engagement Assistant",
+    description=(
+        "💛 Multilingual civic chatbot connecting residents with local services, "
+        "government programs, and community resources.\n\n"
+        "**Powered by:**\n"
+        "- Transformer models for natural language understanding\n"
+        "- Azure ML infrastructure for scalable deployment\n"
+        "- 27-language translation support\n"
+        "- Real-time weather integration\n"
+        "- Multi-city civic resource databases\n\n"
+        "**Supported Cities:** Atlanta, Birmingham, Chesterfield, El Paso, Providence, Seattle"
+    ),
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    contact={
+        "name": "Penny Support",
+        "email": "support@pennyai.example"
+    },
+    license_info={
+        "name": "Proprietary",
+    }
+)
+
+# --- CORS MIDDLEWARE (Configure for your deployment) ---
+# Production: Update allowed_origins to restrict to specific domains
+allowed_origins = os.getenv("ALLOWED_ORIGINS", "*").split(",")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# --- APPLICATION STATE (For health checks and monitoring) ---
+app.state.location_system_healthy = False
+app.state.startup_time = None
+app.state.startup_errors: List[str] = []
+
+# --- GLOBAL EXCEPTION HANDLER ---
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """
+    🛡️ Catches any unhandled exceptions and returns a user-friendly response.
+    Logs full error details for debugging while keeping responses safe for users.
+    
+    Penny stays helpful even when things go wrong!
+    
+    Args:
+        request: FastAPI request object
+        exc: The unhandled exception
+        
+    Returns:
+        JSONResponse with error details (sanitized for production)
+    """
+    logger.error(
+        f"Unhandled exception on {request.url.path} | "
+        f"method={request.method} | "
+        f"error={exc}",
+        exc_info=True
+    )
+    
+    # Check if debug mode is enabled
+    debug_mode = os.getenv("DEBUG_MODE", "false").lower() == "true"
+    
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "error": "An unexpected error occurred. Penny's on it!",
+            "message": "Our team has been notified and we're working to fix this.",
+            "detail": str(exc) if debug_mode else None,
+            "request_path": str(request.url.path),
+            "timestamp": datetime.utcnow().isoformat()
+        }
+    )
+
+# --- STARTUP EVENT ---
+@app.on_event("startup")
+async def startup_event() -> None:
+    """
+    🚀 Runs when Penny wakes up.
+    
+    Responsibilities:
+    1. Validate environment configuration
+    2. Initialize location/city systems
+    3. Verify data files exist
+    4. Log system status
+    """
+    try:
+        app.state.startup_time = datetime.utcnow()
+        app.state.startup_errors = []
+        
+        logger.info("=" * 60)
+        logger.info("🤖 PENNY STARTUP INITIALIZED")
+        logger.info("=" * 60)
+        
+        # --- Environment Info ---
+        logger.info(f"📂 Project Root: {PROJECT_ROOT}")
+        logger.info(f"🌍 Environment: {os.getenv('ENVIRONMENT', 'development')}")
+        logger.info(f"🐍 Python Version: {sys.version.split()[0]}")
+        
+        # --- Azure Configuration Check ---
+        azure_maps_key = os.getenv("AZURE_MAPS_KEY")
+        if azure_maps_key:
+            logger.info("🗺️  Azure Maps: ✅ Configured")
+        else:
+            error_msg = "Azure Maps key missing - weather features will be limited"
+            logger.warning(f"🗺️  Azure Maps: ⚠️  {error_msg}")
+            app.state.startup_errors.append(error_msg)
+        
+        # --- Initialize Location System ---
+        logger.info("🗺️  Initializing location system...")
+        try:
+            location_system_ready = initialize_location_system()
+            app.state.location_system_healthy = location_system_ready
+            
+            if location_system_ready:
+                logger.info("✅ Location system initialized successfully")
+                
+                # Log supported cities
+                cities = SupportedCities.get_all_cities()
+                logger.info(f"📍 Supported cities: {len(cities)}")
+                for city in cities:
+                    logger.info(f"   - {city.full_name} ({city.tenant_id})")
+                
+                # Validate data files
+                validation = validate_city_data_files()
+                missing_data = [
+                    tid for tid, status in validation.items()
+                    if not status["events"] or not status["resources"]
+                ]
+                if missing_data:
+                    error_msg = f"Incomplete data for cities: {missing_data}"
+                    logger.warning(f"⚠️  {error_msg}")
+                    app.state.startup_errors.append(error_msg)
+            else:
+                error_msg = "Location system initialization failed"
+                logger.error(f"❌ {error_msg}")
+                app.state.startup_errors.append(error_msg)
+                
+        except Exception as e:
+            error_msg = f"Error initializing location system: {e}"
+            logger.error(f"❌ {error_msg}", exc_info=True)
+            app.state.location_system_healthy = False
+            app.state.startup_errors.append(error_msg)
+        
+        # --- Startup Summary ---
+        logger.info("=" * 60)
+        if app.state.startup_errors:
+            logger.warning(f"⚠️  PENNY STARTED WITH {len(app.state.startup_errors)} WARNING(S)")
+            for error in app.state.startup_errors:
+                logger.warning(f"   - {error}")
+        else:
+            logger.info("🎉 PENNY IS READY TO HELP RESIDENTS!")
+        logger.info("📖 API Documentation: http://localhost:8000/docs")
+        logger.info("=" * 60)
+        
+    except Exception as e:
+        logger.error(f"❌ Critical startup error: {e}", exc_info=True)
+        app.state.startup_errors.append(f"Critical startup failure: {e}")
+
+# --- SHUTDOWN EVENT ---
+@app.on_event("shutdown")
+async def shutdown_event() -> None:
+    """
+    👋 Cleanup tasks when Penny shuts down.
+    """
+    try:
+        logger.info("=" * 60)
+        logger.info("👋 PENNY SHUTTING DOWN")
+        logger.info("=" * 60)
+        
+        # Calculate uptime
+        if app.state.startup_time:
+            uptime = datetime.utcnow() - app.state.startup_time
+            logger.info(f"⏱️  Total uptime: {uptime}")
+        
+        # TODO: Add cleanup tasks here
+        # - Close database connections
+        # - Save state if needed
+        # - Release model resources
+        
+        logger.info("✅ Shutdown complete. Goodbye for now!")
+    except Exception as e:
+        logger.error(f"Error during shutdown: {e}", exc_info=True)
+
+# --- ROUTER INCLUSION ---
+# All API endpoints defined in router.py are registered here
+try:
+    app.include_router(api_router)
+    logger.info("✅ API router registered successfully")
+except Exception as e:
+    logger.error(f"❌ Failed to register API router: {e}", exc_info=True)
+
+# ============================================================
+# CORE HEALTH & STATUS ENDPOINTS
+# ============================================================
+
+@app.get("/", tags=["Health"])
+async def root() -> Dict[str, Any]:
+    """
+    🏠 Root endpoint - confirms Penny is alive and running.
+    
+    This is the first thing users/load balancers will hit.
+    Penny always responds with warmth, even to bots! 💛
+    
+    Returns:
+        Basic status and feature information
+    """
+    try:
+        return {
+            "message": "💛 Hi! I'm Penny, your civic engagement assistant.",
+            "status": "operational",
+            "tagline": "Connecting residents to community resources since 2024",
+            "docs": "/docs",
+            "api_version": "1.0.0",
+            "supported_cities": len(SupportedCities.get_all_cities()),
+            "features": [
+                "27-language translation",
+                "Real-time weather",
+                "Community events",
+                "Local resource finder",
+                "Document processing"
+            ],
+            "timestamp": datetime.utcnow().isoformat()
+        }
+    except Exception as e:
+        logger.error(f"Error in root endpoint: {e}", exc_info=True)
+        return {
+            "message": "💛 Hi! I'm Penny, your civic engagement assistant.",
+            "status": "degraded",
+            "error": "Some features may be unavailable"
+        }
+
+@app.get("/health", tags=["Health"])
+async def health_check() -> JSONResponse:
+    """
+    🏥 Comprehensive health check for Azure load balancers and monitoring.
+    
+    Returns detailed status of all critical components:
+    - Environment configuration
+    - Location system
+    - Data availability
+    - API components
+    
+    Returns:
+        JSONResponse with health status (200 = healthy, 503 = degraded)
+    """
+    try:
+        # Calculate uptime
+        uptime = None
+        if app.state.startup_time:
+            uptime_delta = datetime.utcnow() - app.state.startup_time
+            uptime = str(uptime_delta).split('.')[0]  # Remove microseconds
+        
+        # Validate data files
+        validation = validate_city_data_files()
+        cities_with_full_data = sum(
+            1 for v in validation.values()
+            if v.get("events", False) and v.get("resources", False)
+        )
+        total_cities = len(SupportedCities.get_all_cities())
+        
+        health_status = {
+            "status": "healthy",
+            "timestamp": datetime.utcnow().isoformat(),
+            "uptime": uptime,
+            "environment": {
+                "azure_maps_configured": bool(os.getenv("AZURE_MAPS_KEY")),
+                "debug_mode": os.getenv("DEBUG_MODE", "false").lower() == "true",
+                "environment_type": os.getenv("ENVIRONMENT", "development")
+            },
+            "location_system": {
+                "status": "operational" if app.state.location_system_healthy else "degraded",
+                "supported_cities": total_cities,
+                "cities_with_full_data": cities_with_full_data
+            },
+            "api_components": {
+                "router": "operational",
+                "weather_agent": "operational" if os.getenv("AZURE_MAPS_KEY") else "degraded",
+                "translation": "operational",
+                "document_processing": "operational"
+            },
+            "startup_errors": app.state.startup_errors if app.state.startup_errors else None,
+            "api_version": "1.0.0"
+        }
+        
+        # Determine overall health status
+        critical_checks = [
+            app.state.location_system_healthy,
+            bool(os.getenv("AZURE_MAPS_KEY"))
+        ]
+        
+        all_healthy = all(critical_checks)
+        
+        if not all_healthy:
+            health_status["status"] = "degraded"
+            logger.warning(f"Health check: System degraded - {health_status}")
+            return JSONResponse(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                content=health_status
+            )
+        
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content=health_status
+        )
+        
+    except Exception as e:
+        logger.error(f"Health check failed: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content={
+                "status": "error",
+                "timestamp": datetime.utcnow().isoformat(),
+                "error": "Health check failed",
+                "detail": str(e) if os.getenv("DEBUG_MODE", "false").lower() == "true" else None
+            }
+        )
+
+@app.get("/cities", tags=["Location"])
+async def list_supported_cities() -> JSONResponse:
+    """
+    📍 Lists all cities Penny currently supports.
+    
+    Returns:
+        List of city information including tenant_id and display name.
+        Useful for frontend dropdowns and API clients.
+    
+    Example Response:
+        {
+            "total": 6,
+            "cities": [
+                {
+                    "tenant_id": "atlanta_ga",
+                    "name": "Atlanta, GA",
+                    "state": "GA",
+                    "data_status": {"events": true, "resources": true}
+                }
+            ]
+        }
+    """
+    try:
+        cities = get_all_supported_cities()
+        
+        # Add validation status for each city
+        validation = validate_city_data_files()
+        for city in cities:
+            tenant_id = city["tenant_id"]
+            city["data_status"] = validation.get(tenant_id, {
+                "events": False,
+                "resources": False
+            })
+        
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content={
+                "total": len(cities),
+                "cities": cities,
+                "message": "These are the cities where Penny can help you find resources!",
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    except Exception as e:
+        logger.error(f"Error listing cities: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "error": "Unable to retrieve city list",
+                "message": "I'm having trouble loading the city list right now. Please try again in a moment!",
+                "detail": str(e) if os.getenv("DEBUG_MODE", "false").lower() == "true" else None,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+
+# ============================================================
+# WEATHER ENDPOINTS
+# ============================================================
+
+@app.get("/weather_direct", tags=["Weather"])
+async def weather_direct_endpoint(lat: float, lon: float) -> JSONResponse:
+    """
+    🌤️ Direct weather lookup by coordinates.
+    
+    Args:
+        lat: Latitude (-90 to 90)
+        lon: Longitude (-180 to 180)
+    
+    Returns:
+        Current weather conditions for the specified location
+    
+    Example:
+        GET /weather_direct?lat=36.8508&lon=-76.2859  (Norfolk, VA)
+    """
+    # Validate coordinates
+    if not (-90 <= lat <= 90):
+        return JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content={
+                "error": "Invalid latitude",
+                "message": "Latitude must be between -90 and 90",
+                "provided_value": lat
+            }
+        )
+    if not (-180 <= lon <= 180):
+        return JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content={
+                "error": "Invalid longitude",
+                "message": "Longitude must be between -180 and 180",
+                "provided_value": lon
+            }
+        )
+    
+    try:
+        weather = await get_weather_for_location(lat=lat, lon=lon)
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content={
+                "latitude": lat,
+                "longitude": lon,
+                "weather": weather,
+                "source": "Azure Maps Weather API",
+                "message": "Current weather conditions at your location",
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    except Exception as e:
+        logger.error(f"Weather lookup failed for ({lat}, {lon}): {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content={
+                "error": "Weather service temporarily unavailable",
+                "message": "We're having trouble reaching the weather service. Please try again in a moment.",
+                "latitude": lat,
+                "longitude": lon,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+
+@app.get("/weather/{tenant_id}", tags=["Weather"])
+async def weather_by_city(tenant_id: str) -> JSONResponse:
+    """
+    🌤️ Get weather for a supported city by tenant ID.
+    
+    Args:
+        tenant_id: City identifier (e.g., 'atlanta_ga', 'seattle_wa')
+    
+    Returns:
+        Current weather conditions for the specified city
+    
+    Example:
+        GET /weather/atlanta_ga
+    """
+    try:
+        # Get city info
+        city_info = SupportedCities.get_city_by_tenant_id(tenant_id)
+        if not city_info:
+            supported = [c["tenant_id"] for c in get_all_supported_cities()]
+            return JSONResponse(
+                status_code=status.HTTP_404_NOT_FOUND,
+                content={
+                    "error": f"City not found: {tenant_id}",
+                    "message": f"I don't have data for '{tenant_id}' yet. Try one of the supported cities!",
+                    "supported_cities": supported,
+                    "timestamp": datetime.utcnow().isoformat()
+                }
+            )
+        
+        # Get coordinates
+        coords = get_city_coordinates(tenant_id)
+        if not coords:
+            return JSONResponse(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                content={
+                    "error": "City coordinates not available",
+                    "city": city_info.full_name,
+                    "tenant_id": tenant_id,
+                    "timestamp": datetime.utcnow().isoformat()
+                }
+            )
+        
+        lat, lon = coords["lat"], coords["lon"]
+        
+        weather = await get_weather_for_location(lat=lat, lon=lon)
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content={
+                "city": city_info.full_name,
+                "tenant_id": tenant_id,
+                "coordinates": {"latitude": lat, "longitude": lon},
+                "weather": weather,
+                "source": "Azure Maps Weather API",
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    except Exception as e:
+        logger.error(f"Weather lookup failed for {tenant_id}: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content={
+                "error": "Weather service temporarily unavailable",
+                "message": "We're having trouble getting the weather right now. Please try again in a moment!",
+                "tenant_id": tenant_id,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+
+# ============================================================
+# DEBUG ENDPOINTS (Only available in debug mode)
+# ============================================================
+
+@app.get("/debug/validation", tags=["Debug"], include_in_schema=False)
+async def debug_validation() -> JSONResponse:
+    """
+    🧪 Debug endpoint: Shows data file validation status.
+    Only available when DEBUG_MODE=true
+    """
+    if os.getenv("DEBUG_MODE", "false").lower() != "true":
+        return JSONResponse(
+            status_code=status.HTTP_403_FORBIDDEN,
+            content={"error": "Debug endpoints are disabled in production"}
+        )
+    
+    try:
+        validation = validate_city_data_files()
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content={
+                "validation": validation,
+                "summary": {
+                    "total_cities": len(validation),
+                    "cities_with_events": sum(1 for v in validation.values() if v.get("events", False)),
+                    "cities_with_resources": sum(1 for v in validation.values() if v.get("resources", False))
+                },
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    except Exception as e:
+        logger.error(f"Debug validation failed: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={"error": str(e)}
+        )
+
+@app.get("/debug/env", tags=["Debug"], include_in_schema=False)
+async def debug_environment() -> JSONResponse:
+    """
+    🧪 Debug endpoint: Shows environment configuration.
+    Sensitive values are masked. Only available when DEBUG_MODE=true
+    """
+    if os.getenv("DEBUG_MODE", "false").lower() != "true":
+        return JSONResponse(
+            status_code=status.HTTP_403_FORBIDDEN,
+            content={"error": "Debug endpoints are disabled in production"}
+        )
+    
+    def mask_sensitive(key: str, value: str) -> str:
+        """Masks sensitive environment variables."""
+        sensitive_keys = ["key", "secret", "password", "token"]
+        if any(s in key.lower() for s in sensitive_keys):
+            return f"{value[:4]}...{value[-4:]}" if len(value) > 8 else "***"
+        return value
+    
+    try:
+        env_vars = {
+            key: mask_sensitive(key, value)
+            for key, value in os.environ.items()
+            if key.startswith(("AZURE_", "PENNY_", "DEBUG_", "ENVIRONMENT"))
+        }
+        
+        return JSONResponse(
+            status_code=status.HTTP_200_OK,
+            content={
+                "environment_variables": env_vars,
+                "project_root": str(PROJECT_ROOT),
+                "location_system_healthy": app.state.location_system_healthy,
+                "startup_errors": app.state.startup_errors,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    except Exception as e:
+        logger.error(f"Debug environment check failed: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={"error": str(e)}
+        )

app/model_loader.py

@@ -0,0 +1,861 @@
+# app/model_loader.py
+"""
+🧠 PENNY Model Loader - Azure-Ready Multi-Model Orchestration
+
+This is Penny's brain loader. She manages multiple specialized models:
+- Gemma 7B for conversational reasoning
+- NLLB-200 for 27-language translation
+- Sentiment analysis for resident wellbeing
+- Bias detection for equitable service
+- LayoutLM for civic document processing
+
+MISSION: Load AI models efficiently in memory-constrained environments while
+maintaining Penny's warm, civic-focused personality across all interactions.
+
+FEATURES:
+- Lazy loading (models only load when needed)
+- 8-bit quantization for memory efficiency
+- GPU/CPU auto-detection
+- Model caching and reuse
+- Graceful fallbacks for Azure ML deployment
+- Memory monitoring and cleanup
+"""
+
+import json
+import os
+import torch
+from typing import Dict, Any, Callable, Optional, Union, List
+from pathlib import Path
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from datetime import datetime
+
+from transformers import (
+    AutoTokenizer, 
+    AutoModelForCausalLM, 
+    AutoModelForSeq2SeqLM,
+    pipeline,
+    PreTrainedModel,
+    PreTrainedTokenizer
+)
+
+# --- LOGGING SETUP ---
+logger = logging.getLogger(__name__)
+
+# --- PATH CONFIGURATION (Environment-Aware) ---
+# Support both local development and Azure ML deployment
+if os.getenv("AZUREML_MODEL_DIR"):
+    # Azure ML deployment - models are in AZUREML_MODEL_DIR
+    MODEL_ROOT = Path(os.getenv("AZUREML_MODEL_DIR"))
+    CONFIG_PATH = MODEL_ROOT / "model_config.json"
+    logger.info("☁️ Running in Azure ML environment")
+else:
+    # Local development - models are in project structure
+    PROJECT_ROOT = Path(__file__).parent.parent
+    MODEL_ROOT = PROJECT_ROOT / "models"
+    CONFIG_PATH = MODEL_ROOT / "model_config.json"
+    logger.info("💻 Running in local development environment")
+
+logger.info(f"📂 Model config path: {CONFIG_PATH}")
+
+# ============================================================
+# PENNY'S CIVIC IDENTITY & PERSONALITY
+# ============================================================
+
+PENNY_SYSTEM_PROMPT = (
+    "You are Penny, a smart, civic-focused AI assistant serving local communities. "
+    "You help residents navigate city services, government programs, and community resources. "
+    "You're warm, professional, accurate, and always stay within your civic mission.\n\n"
+    
+    "Your expertise includes:\n"
+    "- Connecting people with local services (food banks, shelters, libraries)\n"
+    "- Translating information into 27 languages\n"
+    "- Explaining public programs and eligibility\n"
+    "- Guiding residents through civic processes\n"
+    "- Providing emergency resources when needed\n\n"
+    
+    "YOUR PERSONALITY:\n"
+    "- Warm and approachable, like a helpful community center staff member\n"
+    "- Clear and practical, avoiding jargon\n"
+    "- Culturally sensitive and inclusive\n"
+    "- Patient with repetition or clarification\n"
+    "- Funny when appropriate, but never at anyone's expense\n\n"
+    
+    "CRITICAL RULES:\n"
+    "- When residents greet you by name (e.g., 'Hi Penny'), respond warmly and personally\n"
+    "- You are ALWAYS Penny - never ChatGPT, Assistant, Claude, or any other name\n"
+    "- If you don't know something, say so clearly and help find the right resource\n"
+    "- NEVER make up information about services, eligibility, or contacts\n"
+    "- Stay within your civic mission - you don't provide legal, medical, or financial advice\n"
+    "- For emergencies, immediately connect to appropriate services (911, crisis lines)\n\n"
+)
+
+# --- GLOBAL STATE ---
+_MODEL_CACHE: Dict[str, Any] = {}  # Memory-efficient model reuse
+_LOAD_TIMES: Dict[str, float] = {}  # Track model loading performance
+
+
+# ============================================================
+# DEVICE MANAGEMENT
+# ============================================================
+
+class DeviceType(str, Enum):
+    """Supported compute devices."""
+    CUDA = "cuda"
+    CPU = "cpu"
+    MPS = "mps"  # Apple Silicon
+
+
+def get_optimal_device() -> str:
+    """
+    🎮 Determines the best device for model inference.
+    
+    Priority:
+    1. CUDA GPU (NVIDIA)
+    2. MPS (Apple Silicon)
+    3. CPU (fallback)
+    
+    Returns:
+        Device string ("cuda", "mps", or "cpu")
+    """
+    if torch.cuda.is_available():
+        device = DeviceType.CUDA.value
+        gpu_name = torch.cuda.get_device_name(0)
+        gpu_memory = torch.cuda.get_device_properties(0).total_memory / 1e9
+        logger.info(f"🎮 GPU detected: {gpu_name} ({gpu_memory:.1f}GB)")
+        return device
+    
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        device = DeviceType.MPS.value
+        logger.info("🍎 Apple Silicon (MPS) detected")
+        return device
+    
+    else:
+        device = DeviceType.CPU.value
+        logger.info("💻 Using CPU for inference")
+        logger.warning("⚠️ GPU not available - inference will be slower")
+        return device
+
+
+def get_memory_stats() -> Dict[str, float]:
+    """
+    📊 Returns current GPU/CPU memory statistics.
+    
+    Returns:
+        Dict with memory stats in GB
+    """
+    stats = {}
+    
+    if torch.cuda.is_available():
+        stats["gpu_allocated_gb"] = torch.cuda.memory_allocated() / 1e9
+        stats["gpu_reserved_gb"] = torch.cuda.memory_reserved() / 1e9
+        stats["gpu_total_gb"] = torch.cuda.get_device_properties(0).total_memory / 1e9
+    
+    # CPU memory (requires psutil)
+    try:
+        import psutil
+        mem = psutil.virtual_memory()
+        stats["cpu_used_gb"] = mem.used / 1e9
+        stats["cpu_total_gb"] = mem.total / 1e9
+        stats["cpu_percent"] = mem.percent
+    except ImportError:
+        pass
+    
+    return stats
+
+
+# ============================================================
+# MODEL CLIENT (Individual Model Handler)
+# ============================================================
+
+@dataclass
+class ModelMetadata:
+    """
+    📋 Metadata about a loaded model.
+    Tracks performance and resource usage.
+    """
+    name: str
+    task: str
+    model_name: str
+    device: str
+    loaded_at: Optional[datetime] = None
+    load_time_seconds: Optional[float] = None
+    memory_usage_gb: Optional[float] = None
+    inference_count: int = 0
+    total_inference_time_ms: float = 0.0
+    
+    @property
+    def avg_inference_time_ms(self) -> float:
+        """Calculate average inference time."""
+        if self.inference_count == 0:
+            return 0.0
+        return self.total_inference_time_ms / self.inference_count
+
+
+class ModelClient:
+    """
+    🤖 Manages a single HuggingFace model with optimized loading and inference.
+    
+    Features:
+    - Lazy loading (load on first use)
+    - Memory optimization (8-bit quantization)
+    - Performance tracking
+    - Graceful error handling
+    - Automatic device placement
+    """
+    
+    def __init__(
+        self, 
+        name: str, 
+        model_name: str, 
+        task: str, 
+        device: str = None,
+        config: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize model client (doesn't load the model yet).
+        
+        Args:
+            name: Model identifier (e.g., "penny-core-agent")
+            model_name: HuggingFace model ID
+            task: Task type (text-generation, translation, etc.)
+            device: Target device (auto-detected if None)
+            config: Additional model configuration
+        """
+        self.name = name
+        self.model_name = model_name
+        self.task = task
+        self.device = device or get_optimal_device()
+        self.config = config or {}
+        self.pipeline = None
+        self._load_attempted = False
+        self.metadata = ModelMetadata(
+            name=name,
+            task=task,
+            model_name=model_name,
+            device=self.device
+        )
+        
+        logger.info(f"📦 Initialized ModelClient: {name}")
+        logger.debug(f"   Model: {model_name}")
+        logger.debug(f"   Task: {task}")
+        logger.debug(f"   Device: {self.device}")
+    
+    def load_pipeline(self) -> bool:
+        """
+        🔄 Loads the HuggingFace pipeline with Azure-optimized settings.
+        
+        Features:
+        - 8-bit quantization for large models (saves ~50% memory)
+        - Automatic device placement
+        - Memory monitoring
+        - Cache checking
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        if self.pipeline is not None:
+            logger.debug(f"✅ {self.name} already loaded")
+            return True
+        
+        if self._load_attempted:
+            logger.warning(f"⚠️ Previous load attempt failed for {self.name}")
+            return False
+        
+        global _MODEL_CACHE, _LOAD_TIMES
+        
+        # Check cache first
+        if self.name in _MODEL_CACHE:
+            logger.info(f"♻️ Using cached pipeline for {self.name}")
+            self.pipeline = _MODEL_CACHE[self.name]
+            return True
+        
+        logger.info(f"🔄 Loading {self.name} from HuggingFace...")
+        self._load_attempted = True
+        
+        start_time = datetime.now()
+        
+        try:
+            # === TEXT GENERATION (Gemma 7B, GPT-2, etc.) ===
+            if self.task == "text-generation":
+                logger.info("   Using 8-bit quantization for memory efficiency...")
+                
+                # Check if model supports 8-bit loading
+                use_8bit = self.device == DeviceType.CUDA.value
+                
+                if use_8bit:
+                    self.pipeline = pipeline(
+                        "text-generation",
+                        model=self.model_name,
+                        tokenizer=self.model_name,
+                        device_map="auto",
+                        load_in_8bit=True,  # Reduces ~14GB to ~7GB
+                        trust_remote_code=True,
+                        torch_dtype=torch.float16
+                    )
+                else:
+                    # CPU fallback
+                    self.pipeline = pipeline(
+                        "text-generation",
+                        model=self.model_name,
+                        tokenizer=self.model_name,
+                        device=-1,  # CPU
+                        trust_remote_code=True,
+                        torch_dtype=torch.float32
+                    )
+            
+            # === TRANSLATION (NLLB-200, M2M-100, etc.) ===
+            elif self.task == "translation":
+                self.pipeline = pipeline(
+                    "translation",
+                    model=self.model_name,
+                    device=0 if self.device == DeviceType.CUDA.value else -1,
+                    src_lang=self.config.get("default_src_lang", "eng_Latn"),
+                    tgt_lang=self.config.get("default_tgt_lang", "spa_Latn")
+                )
+            
+            # === SENTIMENT ANALYSIS ===
+            elif self.task == "sentiment-analysis":
+                self.pipeline = pipeline(
+                    "sentiment-analysis",
+                    model=self.model_name,
+                    device=0 if self.device == DeviceType.CUDA.value else -1,
+                    truncation=True,
+                    max_length=512
+                )
+            
+            # === BIAS DETECTION (Zero-Shot Classification) ===
+            elif self.task == "bias-detection":
+                self.pipeline = pipeline(
+                    "zero-shot-classification",
+                    model=self.model_name,
+                    device=0 if self.device == DeviceType.CUDA.value else -1
+                )
+            
+            # === TEXT CLASSIFICATION (Generic) ===
+            elif self.task == "text-classification":
+                self.pipeline = pipeline(
+                    "text-classification",
+                    model=self.model_name,
+                    device=0 if self.device == DeviceType.CUDA.value else -1,
+                    truncation=True
+                )
+            
+            # === PDF/DOCUMENT EXTRACTION (LayoutLMv3) ===
+            elif self.task == "pdf-extraction":
+                logger.warning("⚠️ PDF extraction requires additional OCR setup")
+                logger.info("   Consider using Azure Form Recognizer as alternative")
+                # Placeholder - requires pytesseract/OCR infrastructure
+                self.pipeline = None
+                return False
+            
+            else:
+                raise ValueError(f"Unknown task type: {self.task}")
+            
+            # === SUCCESS HANDLING ===
+            if self.pipeline is not None:
+                # Calculate load time
+                load_time = (datetime.now() - start_time).total_seconds()
+                self.metadata.loaded_at = datetime.now()
+                self.metadata.load_time_seconds = load_time
+                
+                # Cache the pipeline
+                _MODEL_CACHE[self.name] = self.pipeline
+                _LOAD_TIMES[self.name] = load_time
+                
+                # Log memory usage
+                mem_stats = get_memory_stats()
+                self.metadata.memory_usage_gb = mem_stats.get("gpu_allocated_gb", 0)
+                
+                logger.info(f"✅ {self.name} loaded successfully!")
+                logger.info(f"   Load time: {load_time:.2f}s")
+                
+                if "gpu_allocated_gb" in mem_stats:
+                    logger.info(
+                        f"   GPU Memory: {mem_stats['gpu_allocated_gb']:.2f}GB / "
+                        f"{mem_stats['gpu_total_gb']:.2f}GB"
+                    )
+                
+                return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to load {self.name}: {e}", exc_info=True)
+            self.pipeline = None
+            return False
+    
+    def predict(
+        self, 
+        input_data: Union[str, Dict[str, Any]], 
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        🎯 Runs inference with the loaded model pipeline.
+        
+        Features:
+        - Automatic pipeline loading
+        - Error handling with fallback responses
+        - Performance tracking
+        - Penny's personality injection (for text-generation)
+        
+        Args:
+            input_data: Text or structured input for the model
+            **kwargs: Task-specific parameters
+            
+        Returns:
+            Model output dict with results or error information
+        """
+        # Track inference start time
+        start_time = datetime.now()
+        
+        # Ensure pipeline is loaded
+        if self.pipeline is None:
+            success = self.load_pipeline()
+            if not success:
+                return {
+                    "error": f"{self.name} pipeline unavailable",
+                    "detail": "Model failed to load. Check logs for details.",
+                    "model": self.name
+                }
+        
+        try:
+            # === TEXT GENERATION ===
+            if self.task == "text-generation":
+                # Inject Penny's civic identity
+                if not kwargs.get("skip_system_prompt", False):
+                    full_prompt = PENNY_SYSTEM_PROMPT + input_data
+                else:
+                    full_prompt = input_data
+                
+                # Extract generation parameters with safe defaults
+                max_new_tokens = kwargs.get("max_new_tokens", 256)
+                temperature = kwargs.get("temperature", 0.7)
+                top_p = kwargs.get("top_p", 0.9)
+                do_sample = kwargs.get("do_sample", temperature > 0.0)
+                
+                result = self.pipeline(
+                    full_prompt,
+                    max_new_tokens=max_new_tokens,
+                    temperature=temperature,
+                    top_p=top_p,
+                    do_sample=do_sample,
+                    return_full_text=False,
+                    pad_token_id=self.pipeline.tokenizer.eos_token_id,
+                    truncation=True
+                )
+                
+                output = {
+                    "generated_text": result[0]["generated_text"],
+                    "model": self.name,
+                    "success": True
+                }
+            
+            # === TRANSLATION ===
+            elif self.task == "translation":
+                src_lang = kwargs.get("source_lang", "eng_Latn")
+                tgt_lang = kwargs.get("target_lang", "spa_Latn")
+                
+                result = self.pipeline(
+                    input_data,
+                    src_lang=src_lang,
+                    tgt_lang=tgt_lang,
+                    max_length=512
+                )
+                
+                output = {
+                    "translation": result[0]["translation_text"],
+                    "source_lang": src_lang,
+                    "target_lang": tgt_lang,
+                    "model": self.name,
+                    "success": True
+                }
+            
+            # === SENTIMENT ANALYSIS ===
+            elif self.task == "sentiment-analysis":
+                result = self.pipeline(input_data)
+                
+                output = {
+                    "sentiment": result[0]["label"],
+                    "confidence": result[0]["score"],
+                    "model": self.name,
+                    "success": True
+                }
+            
+            # === BIAS DETECTION ===
+            elif self.task == "bias-detection":
+                candidate_labels = kwargs.get("candidate_labels", [
+                    "neutral and objective",
+                    "contains political bias",
+                    "uses emotional language",
+                    "culturally insensitive"
+                ])
+                
+                result = self.pipeline(
+                    input_data,
+                    candidate_labels=candidate_labels,
+                    multi_label=True
+                )
+                
+                output = {
+                    "labels": result["labels"],
+                    "scores": result["scores"],
+                    "model": self.name,
+                    "success": True
+                }
+            
+            # === TEXT CLASSIFICATION ===
+            elif self.task == "text-classification":
+                result = self.pipeline(input_data)
+                
+                output = {
+                    "label": result[0]["label"],
+                    "confidence": result[0]["score"],
+                    "model": self.name,
+                    "success": True
+                }
+            
+            else:
+                output = {
+                    "error": f"Task '{self.task}' not implemented",
+                    "model": self.name,
+                    "success": False
+                }
+            
+            # Track performance
+            inference_time = (datetime.now() - start_time).total_seconds() * 1000
+            self.metadata.inference_count += 1
+            self.metadata.total_inference_time_ms += inference_time
+            output["inference_time_ms"] = round(inference_time, 2)
+            
+            return output
+        
+        except Exception as e:
+            logger.error(f"❌ Inference error in {self.name}: {e}", exc_info=True)
+            return {
+                "error": "Inference failed",
+                "detail": str(e),
+                "model": self.name,
+                "success": False
+            }
+    
+    def unload(self) -> None:
+        """
+        🗑️ Unloads the model to free memory.
+        Critical for Azure environments with limited resources.
+        """
+        if self.pipeline is not None:
+            logger.info(f"🗑️ Unloading {self.name}...")
+            
+            # Delete pipeline
+            del self.pipeline
+            self.pipeline = None
+            
+            # Remove from cache
+            if self.name in _MODEL_CACHE:
+                del _MODEL_CACHE[self.name]
+            
+            # Force GPU memory release
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            
+            logger.info(f"✅ {self.name} unloaded successfully")
+            
+            # Log memory stats after unload
+            mem_stats = get_memory_stats()
+            if "gpu_allocated_gb" in mem_stats:
+                logger.info(f"   GPU Memory: {mem_stats['gpu_allocated_gb']:.2f}GB remaining")
+    
+    def get_metadata(self) -> Dict[str, Any]:
+        """
+        📊 Returns model metadata and performance stats.
+        """
+        return {
+            "name": self.metadata.name,
+            "task": self.metadata.task,
+            "model_name": self.metadata.model_name,
+            "device": self.metadata.device,
+            "loaded": self.pipeline is not None,
+            "loaded_at": self.metadata.loaded_at.isoformat() if self.metadata.loaded_at else None,
+            "load_time_seconds": self.metadata.load_time_seconds,
+            "memory_usage_gb": self.metadata.memory_usage_gb,
+            "inference_count": self.metadata.inference_count,
+            "avg_inference_time_ms": round(self.metadata.avg_inference_time_ms, 2)
+        }
+
+
+# ============================================================
+# MODEL LOADER (Singleton Manager)
+# ============================================================
+
+class ModelLoader:
+    """
+    🎛️ Singleton manager for all Penny's specialized models.
+    
+    Features:
+    - Centralized model configuration
+    - Lazy loading (models only load when needed)
+    - Memory management
+    - Health monitoring
+    - Unified access interface
+    """
+    
+    _instance: Optional['ModelLoader'] = None
+
+    def __new__(cls, *args, **kwargs):
+        """Singleton pattern - only one ModelLoader instance."""
+        if cls._instance is None:
+            cls._instance = super(ModelLoader, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self, config_path: Optional[str] = None):
+        """
+        Initialize ModelLoader (only runs once due to singleton).
+        
+        Args:
+            config_path: Path to model_config.json (optional)
+        """
+        if not hasattr(self, '_models_loaded'):
+            self.models: Dict[str, ModelClient] = {}
+            self._models_loaded = True
+            self._initialization_time = datetime.now()
+            
+            # Use provided path or default
+            config_file = Path(config_path) if config_path else CONFIG_PATH
+            
+            try:
+                logger.info(f"📖 Loading model configuration from {config_file}")
+                
+                if not config_file.exists():
+                    logger.warning(f"⚠️ Configuration file not found: {config_file}")
+                    logger.info("   Create model_config.json with your model definitions")
+                    return
+                
+                with open(config_file, "r") as f:
+                    config = json.load(f)
+
+                # Initialize ModelClients (doesn't load models yet)
+                for model_id, model_info in config.items():
+                    self.models[model_id] = ModelClient(
+                        name=model_id,
+                        model_name=model_info["model_name"],
+                        task=model_info["task"],
+                        config=model_info.get("config", {})
+                    )
+                
+                logger.info(f"✅ ModelLoader initialized with {len(self.models)} models:")
+                for model_id in self.models.keys():
+                    logger.info(f"   - {model_id}")
+
+            except json.JSONDecodeError as e:
+                logger.error(f"❌ Invalid JSON in model_config.json: {e}")
+            except Exception as e:
+                logger.error(f"❌ Failed to initialize ModelLoader: {e}", exc_info=True)
+
+    def get(self, model_id: str) -> Optional[ModelClient]:
+        """
+        🎯 Retrieves a configured ModelClient by ID.
+        
+        Args:
+            model_id: Model identifier from config
+            
+        Returns:
+            ModelClient instance or None if not found
+        """
+        return self.models.get(model_id)
+
+    def list_models(self) -> List[str]:
+        """📋 Returns list of all available model IDs."""
+        return list(self.models.keys())
+    
+    def get_loaded_models(self) -> List[str]:
+        """📋 Returns list of currently loaded model IDs."""
+        return [
+            model_id 
+            for model_id, client in self.models.items()
+            if client.pipeline is not None
+        ]
+    
+    def unload_all(self) -> None:
+        """
+        🗑️ Unloads all models to free memory.
+        Useful for Azure environments when switching workloads.
+        """
+        logger.info("🗑️ Unloading all models...")
+        for model_client in self.models.values():
+            model_client.unload()
+        logger.info("✅ All models unloaded")
+    
+    def get_status(self) -> Dict[str, Any]:
+        """
+        📊 Returns comprehensive status of all models.
+        Useful for health checks and monitoring.
+        """
+        status = {
+            "initialization_time": self._initialization_time.isoformat(),
+            "total_models": len(self.models),
+            "loaded_models": len(self.get_loaded_models()),
+            "device": get_optimal_device(),
+            "memory": get_memory_stats(),
+            "models": {}
+        }
+        
+        for model_id, client in self.models.items():
+            status["models"][model_id] = client.get_metadata()
+        
+        return status
+
+
+# ============================================================
+# PUBLIC INTERFACE (Used by all *_utils.py modules)
+# ============================================================
+
+def load_model_pipeline(agent_name: str) -> Callable[..., Dict[str, Any]]:
+    """
+    🚀 Loads a model client and returns its inference function.
+    
+    This is the main function used by other modules (translation_utils.py,
+    sentiment_utils.py, etc.) to access Penny's models.
+    
+    Args:
+        agent_name: Model ID from model_config.json
+        
+    Returns:
+        Callable inference function
+        
+    Raises:
+        ValueError: If agent_name not found in configuration
+        
+    Example:
+        >>> translator = load_model_pipeline("penny-translate-agent")
+        >>> result = translator("Hello world", target_lang="spa_Latn")
+    """
+    loader = ModelLoader()
+    client = loader.get(agent_name)
+    
+    if client is None:
+        available = loader.list_models()
+        raise ValueError(
+            f"Agent ID '{agent_name}' not found in model configuration. "
+            f"Available models: {available}"
+        )
+    
+    # Load the pipeline (lazy loading)
+    client.load_pipeline()
+    
+    # Return a callable wrapper
+    def inference_wrapper(input_data, **kwargs):
+        return client.predict(input_data, **kwargs)
+    
+    return inference_wrapper
+
+
+# === CONVENIENCE FUNCTIONS ===
+
+def get_model_status() -> Dict[str, Any]:
+    """
+    📊 Returns status of all configured models.
+    Useful for health checks and monitoring endpoints.
+    """
+    loader = ModelLoader()
+    return loader.get_status()
+
+
+def preload_models(model_ids: Optional[List[str]] = None) -> None:
+    """
+    🚀 Preloads specified models during startup.
+    
+    Args:
+        model_ids: List of model IDs to preload (None = all models)
+    """
+    loader = ModelLoader()
+    
+    if model_ids is None:
+        model_ids = loader.list_models()
+    
+    logger.info(f"🚀 Preloading {len(model_ids)} models...")
+    
+    for model_id in model_ids:
+        client = loader.get(model_id)
+        if client:
+            logger.info(f"   Loading {model_id}...")
+            client.load_pipeline()
+    
+    logger.info("✅ Model preloading complete")
+
+
+def initialize_model_system() -> bool:
+    """
+    🏁 Initializes the model system.
+    Should be called during app startup.
+    
+    Returns:
+        True if initialization successful
+    """
+    logger.info("🧠 Initializing Penny's model system...")
+    
+    try:
+        # Initialize singleton
+        loader = ModelLoader()
+        
+        # Log device info
+        device = get_optimal_device()
+        mem_stats = get_memory_stats()
+        
+        logger.info(f"✅ Model system initialized")
+        logger.info(f"🎮 Compute device: {device}")
+        
+        if "gpu_total_gb" in mem_stats:
+            logger.info(
+                f"💾 GPU Memory: {mem_stats['gpu_total_gb']:.1f}GB total"
+            )
+        
+        logger.info(f"📦 {len(loader.models)} models configured")
+        
+        # Optional: Preload critical models
+        # Uncomment to preload models at startup
+        # preload_models(["penny-core-agent"])
+        
+        return True
+        
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize model system: {e}", exc_info=True)
+        return False
+
+
+# ============================================================
+# CLI TESTING & DEBUGGING
+# ============================================================
+
+if __name__ == "__main__":
+    """
+    🧪 Test script for model loading and inference.
+    Run with: python -m app.model_loader
+    """
+    print("=" * 60)
+    print("🧪 Testing Penny's Model System")
+    print("=" * 60)
+    
+    # Initialize
+    loader = ModelLoader()
+    print(f"\n📋 Available models: {loader.list_models()}")
+    
+    # Get status
+    status = get_model_status()
+    print(f"\n📊 System status:")
+    print(json.dumps(status, indent=2, default=str))
+    
+    # Test model loading (if models configured)
+    if loader.models:
+        test_model_id = list(loader.models.keys())[0]
+        print(f"\n🧪 Testing model: {test_model_id}")
+        
+        client = loader.get(test_model_id)
+        if client:
+            print(f"   Loading pipeline...")
+            success = client.load_pipeline()
+            
+            if success:
+                print(f"   ✅ Model loaded successfully!")
+                print(f"   Metadata: {json.dumps(client.get_metadata(), indent=2, default=str)}")
+            else:
+                print(f"   ❌ Model loading failed")

app/router.py

@@ -0,0 +1,802 @@
+"""
+🚦 PENNY Request Router - Enhanced for Azure ML Production
+Routes incoming requests to appropriate agents and tools based on intent classification.
+Integrates with enhanced logging, location detection, and intent classification.
+
+Mission: Ensure every resident request reaches the right civic service with proper tracking.
+"""
+
+import logging
+import time
+import asyncio
+import os
+from typing import Dict, Any, Optional, List
+from pathlib import Path
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import JSONResponse
+
+from app.model_loader import ModelLoader
+from app.tool_agent import handle_tool_request
+from app.weather_agent import (
+    get_weather_for_location,
+    weather_to_event_recommendations,
+    recommend_outfit
+)
+from app.intents import classify_intent_detailed, IntentType
+from app.event_weather import get_event_recommendations_with_weather
+from app.location_utils import (
+    detect_location_from_text,
+    get_city_info,
+    validate_coordinates
+)
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+logger = logging.getLogger(__name__)
+
+# Initialize FastAPI router
+router = APIRouter(prefix="/api", tags=["Penny API"])
+
+# Initialize model loader
+models = ModelLoader()
+
+# Supported languages for translation routing
+SUPPORTED_LANGUAGES = [
+    "arabic", "french", "german", "hindi", "mandarin",
+    "portuguese", "russian", "spanish", "swahili",
+    "tagalog", "urdu", "vietnamese", "translate", "translation"
+]
+
+def validate_request_payload(payload: dict) -> tuple[bool, Optional[str]]:
+    """
+    Validate incoming request payload for required fields and data types.
+    
+    Args:
+        payload: Request payload dictionary
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not isinstance(payload, dict):
+        return False, "Payload must be a dictionary"
+    
+    # Check for required input field
+    if "input" not in payload:
+        return False, "Missing required field: 'input'"
+    
+    user_input = payload.get("input")
+    if not isinstance(user_input, str):
+        return False, "Field 'input' must be a string"
+    
+    if not user_input.strip():
+        return False, "Input cannot be empty"
+    
+    # Validate coordinates if provided
+    lat = payload.get("lat")
+    lon = payload.get("lon")
+    
+    if lat is not None or lon is not None:
+        if lat is None or lon is None:
+            return False, "Both 'lat' and 'lon' must be provided together"
+        
+        try:
+            lat = float(lat)
+            lon = float(lon)
+            is_valid, error = validate_coordinates(lat, lon)
+            if not is_valid:
+                return False, f"Invalid coordinates: {error}"
+        except (ValueError, TypeError):
+            return False, "Coordinates must be numeric values"
+    
+    # Validate tenant_id if provided
+    tenant_id = payload.get("tenant_id")
+    if tenant_id is not None:
+        if not isinstance(tenant_id, str):
+            return False, "Field 'tenant_id' must be a string"
+        if not tenant_id.strip():
+            return False, "Field 'tenant_id' cannot be empty"
+    
+    return True, None
+
+
+def extract_location_info(payload: dict, user_input: str) -> Dict[str, Any]:
+    """
+    Extract and validate location information from payload or user input.
+    
+    Args:
+        payload: Request payload
+        user_input: User's input text
+        
+    Returns:
+        Dictionary with location info: {lat, lon, tenant_id, city_info, location_source}
+    """
+    location_info = {
+        "lat": payload.get("lat"),
+        "lon": payload.get("lon"),
+        "tenant_id": payload.get("tenant_id", "default"),
+        "city_info": None,
+        "location_source": "none"
+    }
+    
+    try:
+        # Try to get location from coordinates
+        if location_info["lat"] is not None and location_info["lon"] is not None:
+            location_info["location_source"] = "coordinates"
+            
+            # Try to map coordinates to a tenant city
+            if location_info["tenant_id"] == "default":
+                city_info = get_city_info(location_info["tenant_id"])
+                if city_info:
+                    location_info["city_info"] = city_info
+        
+        # Try to detect location from text if not provided
+        elif "near me" in user_input.lower() or any(
+            keyword in user_input.lower() 
+            for keyword in ["in", "at", "near", "around"]
+        ):
+            detected = detect_location_from_text(user_input)
+            if detected.get("found"):
+                location_info["tenant_id"] = detected.get("tenant_id", "default")
+                location_info["city_info"] = detected.get("city_info")
+                location_info["location_source"] = "text_detection"
+                logger.info(
+                    f"Detected location from text: {location_info['tenant_id']}"
+                )
+        
+        # Get city info for tenant_id if we have it
+        if not location_info["city_info"] and location_info["tenant_id"] != "default":
+            location_info["city_info"] = get_city_info(location_info["tenant_id"])
+            
+    except Exception as e:
+        logger.warning(f"Error extracting location info: {e}")
+    
+    return location_info
+
+
+def route_request(payload: dict) -> dict:
+    """
+    Main routing function for PENNY requests.
+    Routes requests to appropriate agents based on intent classification.
+    
+    Args:
+        payload: Request payload with user input and metadata
+        
+    Returns:
+        Response dictionary with agent output and metadata
+    """
+    start_time = time.time()
+    
+    try:
+        # Validate request payload
+        is_valid, error_msg = validate_request_payload(payload)
+        if not is_valid:
+            logger.warning(f"Invalid request payload: {error_msg}")
+            return {
+                "error": "Oops! I couldn't understand that request. " + error_msg,
+                "status": "validation_error",
+                "response_time_ms": round((time.time() - start_time) * 1000)
+            }
+        
+        # Extract basic request info
+        user_input = payload.get("input", "").strip()
+        role = payload.get("role", "unknown")
+        
+        # Sanitize input for logging (remove PII)
+        sanitized_input = sanitize_for_logging(user_input)
+        
+        # Extract location information
+        location_info = extract_location_info(payload, user_input)
+        tenant_id = location_info["tenant_id"]
+        lat = location_info["lat"]
+        lon = location_info["lon"]
+        
+        logger.info(
+            f"Routing request from tenant '{tenant_id}', role '{role}', "
+            f"location_source: {location_info['location_source']}"
+        )
+        
+        # Classify intent using enhanced intent classifier
+        try:
+            intent_result = classify_intent_detailed(user_input)
+            intent = intent_result["intent"]
+            confidence = intent_result["confidence"]
+            is_compound = intent_result["is_compound"]
+            
+            logger.info(
+                f"Intent classified: {intent} (confidence: {confidence:.2f}, "
+                f"compound: {is_compound})"
+            )
+            
+        except Exception as e:
+            logger.error(f"Intent classification failed: {e}")
+            intent = IntentType.GENERAL
+            confidence = 0.0
+            is_compound = False
+        
+        # EMERGENCY ROUTING - Highest priority
+        if intent == IntentType.EMERGENCY:
+            logger.critical(
+                f"EMERGENCY intent detected from tenant '{tenant_id}'. "
+                f"Routing to safety protocols."
+            )
+            
+            # Log emergency interaction for compliance
+            log_interaction(
+                tenant_id=tenant_id,
+                interaction_type="emergency",
+                intent="emergency",
+                response_time_ms=round((time.time() - start_time) * 1000),
+                success=True,
+                metadata={
+                    "sanitized_input": sanitized_input,
+                    "requires_followup": True,
+                    "escalation_level": "critical"
+                }
+            )
+            
+            return {
+                "response": (
+                    "I can see you might need urgent help. Please contact:\n\n"
+                    "🚨 **Emergency Services**: 911\n"
+                    "💚 **National Crisis Hotline**: 988\n"
+                    "💬 **Crisis Text Line**: Text HOME to 741741\n\n"
+                    "You're not alone, and help is available 24/7."
+                ),
+                "intent": "emergency",
+                "model_id": "safety-agent",
+                "tenant_id": tenant_id,
+                "user_role": role,
+                "response_time_ms": round((time.time() - start_time) * 1000),
+                "escalation_required": True
+            }
+        
+        # WEATHER ROUTING
+        if intent == IntentType.WEATHER:
+            return handle_weather_request(
+                user_input, lat, lon, tenant_id, role, start_time
+            )
+        
+        # WEATHER + EVENTS ROUTING (compound intent)
+        if intent == IntentType.WEATHER_EVENTS or (
+            is_compound and "weather" in intent_result.get("components", [])
+        ):
+            return handle_weather_events_request(
+                user_input, lat, lon, tenant_id, role, start_time
+            )
+        
+        # EVENTS ROUTING
+        if intent == IntentType.EVENTS:
+            return handle_events_request(
+                user_input, tenant_id, role, start_time
+            )
+        
+        # TOOL-BASED ROUTING (transit, alerts, resources, etc.)
+        if intent in [
+            IntentType.TRANSIT, IntentType.ALERTS, IntentType.RESOURCES,
+            IntentType.PUBLIC_WORKS
+        ]:
+            return handle_tool_based_request(
+                user_input, intent, tenant_id, role, start_time
+            )
+        
+        # TRANSLATION ROUTING
+        if intent == IntentType.TRANSLATION or any(
+            lang in user_input.lower() for lang in SUPPORTED_LANGUAGES
+        ):
+            return handle_translation_request(
+                user_input, tenant_id, role, start_time
+            )
+        
+        # DOCUMENT/PDF ROUTING
+        if any(term in user_input.lower() for term in ["form", "upload", "document", "pdf"]):
+            return handle_document_request(
+                user_input, tenant_id, role, start_time
+            )
+        
+        # SENTIMENT ANALYSIS ROUTING
+        if any(term in user_input.lower() for term in ["angry", "sentiment", "how do i feel"]):
+            return handle_sentiment_request(
+                user_input, tenant_id, role, start_time
+            )
+        
+        # BIAS DETECTION ROUTING
+        if any(term in user_input.lower() for term in ["bias", "is this fair", "offensive"]):
+            return handle_bias_request(
+                user_input, tenant_id, role, start_time
+            )
+        
+        # GENERAL/FALLBACK ROUTING
+        return handle_general_request(
+            user_input, tenant_id, role, start_time
+        )
+        
+    except Exception as e:
+        logger.error(f"Unexpected error in route_request: {e}", exc_info=True)
+        
+        return {
+            "error": (
+                "I'm having trouble processing that right now. "
+                "Could you try rephrasing your question? 💛"
+            ),
+            "status": "server_error",
+            "response_time_ms": round((time.time() - start_time) * 1000)
+        }
+
+
+def handle_weather_request(
+    user_input: str, lat: Optional[float], lon: Optional[float],
+    tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle weather-specific requests."""
+    try:
+        if lat is None or lon is None:
+            return {
+                "response": (
+                    "I'd love to help with the weather! To give you accurate info, "
+                    "I need your location. Can you share your coordinates or tell me "
+                    "what city you're in? 🌤️"
+                ),
+                "intent": "weather",
+                "model_id": "weather-agent",
+                "tenant_id": tenant_id,
+                "user_role": role,
+                "response_time_ms": round((time.time() - start_time) * 1000),
+                "location_required": True
+            }
+        
+        # Get weather data
+        weather = asyncio.run(get_weather_for_location(lat, lon))
+        
+        # Generate recommendations
+        recs = weather_to_event_recommendations(weather)
+        outfit = recommend_outfit(
+            weather.get("temperature", {}).get("value"),
+            weather.get("phrase", "")
+        )
+        
+        end_time = time.time()
+        response_time = round((end_time - start_time) * 1000)
+        
+        # Log successful interaction
+        log_interaction(
+            tenant_id=tenant_id,
+            interaction_type="weather",
+            intent="weather",
+            response_time_ms=response_time,
+            success=True
+        )
+        
+        return {
+            "response": {
+                "weather": weather,
+                "recommendations": recs,
+                "outfit": outfit
+            },
+            "intent": "weather",
+            "model_id": "weather-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": response_time
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling weather request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble getting the weather right now. "
+                "The weather service might be down. Want to try again in a moment? 🌦️"
+            ),
+            "intent": "weather",
+            "model_id": "weather-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "weather_service_unavailable"
+        }
+
+
+def handle_weather_events_request(
+    user_input: str, lat: Optional[float], lon: Optional[float],
+    tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle combined weather and events requests."""
+    try:
+        if lat is None or lon is None:
+            return {
+                "response": (
+                    "I can suggest events based on the weather! "
+                    "To do that, I need your location. Can you share your coordinates "
+                    "or tell me what city you're in? 🎉☀️"
+                ),
+                "intent": "weather_events",
+                "model_id": "event-weather-agent",
+                "tenant_id": tenant_id,
+                "user_role": role,
+                "response_time_ms": round((time.time() - start_time) * 1000),
+                "location_required": True
+            }
+        
+        # Get combined weather and event recommendations
+        combined = asyncio.run(
+            get_event_recommendations_with_weather(tenant_id, lat, lon)
+        )
+        
+        end_time = time.time()
+        response_time = round((end_time - start_time) * 1000)
+        
+        # Log successful interaction
+        log_interaction(
+            tenant_id=tenant_id,
+            interaction_type="weather_events",
+            intent="weather_events",
+            response_time_ms=response_time,
+            success=True
+        )
+        
+        return {
+            "response": combined,
+            "intent": "weather_events",
+            "model_id": "event-weather-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": response_time
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling weather_events request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble combining weather and events right now. "
+                "Let me try to help you with just one or the other! 🤔"
+            ),
+            "intent": "weather_events",
+            "model_id": "event-weather-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "combined_service_unavailable"
+        }
+
+
+def handle_events_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle events-only requests."""
+    try:
+        tool_response = handle_tool_request(user_input, role, tenant_id, "events")
+        end_time = time.time()
+        
+        return {
+            "response": tool_response.get("response"),
+            "intent": "events",
+            "model_id": "event-agent",
+            "tenant_id": tool_response.get("city", tenant_id),
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling events request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble finding events right now. "
+                "Let me know what you're interested in and I'll do my best! 🎭"
+            ),
+            "intent": "events",
+            "model_id": "event-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "events_service_unavailable"
+        }
+
+
+def handle_tool_based_request(
+    user_input: str, intent: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle tool-based requests (transit, alerts, resources, etc.)."""
+    try:
+        tool_response = handle_tool_request(user_input, role, tenant_id, intent)
+        end_time = time.time()
+        
+        return {
+            "response": tool_response.get("response"),
+            "intent": str(intent),
+            "model_id": tool_response.get("tool", "tool-agent"),
+            "tenant_id": tool_response.get("city", tenant_id),
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling tool request for {intent}: {e}")
+        
+        return {
+            "response": (
+                f"I'm having trouble with that {intent} request right now. "
+                "Could you try again or ask me something else? 💛"
+            ),
+            "intent": str(intent),
+            "model_id": "tool-agent",
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": f"{intent}_service_unavailable"
+        }
+
+
+def handle_translation_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle translation requests."""
+    model_id = "penny-translate-agent"
+    
+    try:
+        model = models.get(model_id)
+        if not model:
+            raise ValueError(f"Translation model not found: {model_id}")
+        
+        result = model.predict(user_input)
+        end_time = time.time()
+        
+        return {
+            "response": result,
+            "intent": "translation",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling translation request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble with translation right now. "
+                "Which language would you like help with? 🌍"
+            ),
+            "intent": "translation",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "translation_service_unavailable"
+        }
+
+
+def handle_document_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle document/PDF processing requests."""
+    model_id = "penny-doc-agent"
+    
+    try:
+        model = models.get(model_id)
+        if not model:
+            raise ValueError(f"Document model not found: {model_id}")
+        
+        result = model.predict(user_input)
+        end_time = time.time()
+        
+        return {
+            "response": result,
+            "intent": "document",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling document request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble processing documents right now. "
+                "What kind of form or document do you need help with? 📄"
+            ),
+            "intent": "document",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "document_service_unavailable"
+        }
+
+
+def handle_sentiment_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle sentiment analysis requests."""
+    model_id = "penny-sentiment-agent"
+    
+    try:
+        model = models.get(model_id)
+        if not model:
+            raise ValueError(f"Sentiment model not found: {model_id}")
+        
+        result = model.predict(user_input)
+        end_time = time.time()
+        
+        return {
+            "response": result,
+            "intent": "sentiment",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling sentiment request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble analyzing sentiment right now. "
+                "How are you feeling about things? 💭"
+            ),
+            "intent": "sentiment",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "sentiment_service_unavailable"
+        }
+
+
+def handle_bias_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle bias detection requests."""
+    model_id = "penny-bias-checker"
+    
+    try:
+        model = models.get(model_id)
+        if not model:
+            raise ValueError(f"Bias model not found: {model_id}")
+        
+        result = model.predict(user_input)
+        end_time = time.time()
+        
+        return {
+            "response": result,
+            "intent": "bias_check",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling bias request: {e}")
+        
+        return {
+            "response": (
+                "I'm having trouble checking for bias right now. "
+                "What content would you like me to review? ⚖️"
+            ),
+            "intent": "bias_check",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "bias_service_unavailable"
+        }
+
+
+def handle_general_request(
+    user_input: str, tenant_id: str, role: str, start_time: float
+) -> dict:
+    """Handle general/fallback requests."""
+    model_id = "penny-core-agent"
+    
+    try:
+        model = models.get(model_id)
+        if not model:
+            raise ValueError(f"Core model not found: {model_id}")
+        
+        result = model.predict(user_input)
+        end_time = time.time()
+        
+        return {
+            "response": result,
+            "intent": "general",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((end_time - start_time) * 1000)
+        }
+        
+    except Exception as e:
+        logger.error(f"Error handling general request: {e}")
+        
+        return {
+            "response": (
+                "I'm having some technical difficulties right now. "
+                "Can you try asking your question in a different way? "
+                "Or let me know if you need help with weather, events, or services! 💛"
+            ),
+            "intent": "general",
+            "model_id": model_id,
+            "tenant_id": tenant_id,
+            "user_role": role,
+            "response_time_ms": round((time.time() - start_time) * 1000),
+            "error": "general_service_unavailable"
+        }
+
+
+@router.post("/chat", response_model=Dict[str, Any])
+async def chat_endpoint(payload: Dict[str, Any]) -> JSONResponse:
+    """
+    💬 Main chat endpoint for Penny.
+    
+    Processes user requests and routes them to appropriate handlers.
+    
+    Args:
+        payload: Request payload with 'input', 'tenant_id', 'lat', 'lon', etc.
+        
+    Returns:
+        JSONResponse with Penny's response
+    """
+    try:
+        result = route_request(payload)
+        return JSONResponse(status_code=200, content=result)
+    except Exception as e:
+        logger.error(f"Error in chat endpoint: {e}", exc_info=True)
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "I'm having trouble processing that right now. Please try again! 💛",
+                "detail": str(e) if os.getenv("DEBUG_MODE", "false").lower() == "true" else None
+            }
+        )
+
+
+@router.get("/health/router", response_model=Dict[str, Any])
+async def router_health_endpoint() -> JSONResponse:
+    """
+    📊 Router health check endpoint.
+    
+    Returns:
+        Health status of the router component
+    """
+    try:
+        health = get_router_health()
+        return JSONResponse(status_code=200, content=health)
+    except Exception as e:
+        logger.error(f"Router health check failed: {e}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "status": "degraded",
+                "error": str(e)
+            }
+        )
+
+
+def get_router_health() -> dict:
+    """
+    Check router health status.
+    
+    Returns:
+        Health status dictionary
+    """
+    try:
+        return {
+            "status": "operational",
+            "model_loader": "initialized" if models else "not_initialized",
+            "supported_languages": len(SUPPORTED_LANGUAGES),
+            "routing_capabilities": [
+                "weather", "events", "weather_events", "translation",
+                "documents", "sentiment", "bias_detection", "general"
+            ]
+        }
+    except Exception as e:
+        logger.error(f"Router health check failed: {e}")
+        return {
+            "status": "degraded",
+            "error": str(e)
+        }

app/tool_agent.py

@@ -0,0 +1,666 @@
+# app/tool_agent.py
+"""
+🛠️ PENNY Tool Agent - Civic Data & Services Handler
+
+Routes requests to civic data sources (events, resources, transit, etc.)
+and integrates with real-time weather information.
+
+MISSION: Connect residents to local civic services by intelligently
+processing their requests and returning relevant, actionable information.
+
+FEATURES:
+- Real-time weather integration with outfit recommendations
+- Event discovery with weather-aware suggestions
+- Resource lookup (trash, transit, emergency services)
+- City-specific data routing
+- Graceful fallback for missing data
+
+ENHANCEMENTS (Phase 1):
+- ✅ Structured logging with performance tracking
+- ✅ Enhanced error handling with user-friendly messages
+- ✅ Type hints for all functions
+- ✅ Health check integration
+- ✅ Service availability tracking
+- ✅ Integration with enhanced modules
+- ✅ Penny's friendly voice throughout
+"""
+
+import logging
+import time
+from typing import Optional, Dict, Any
+
+# --- ENHANCED MODULE IMPORTS ---
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- AGENT IMPORTS (with availability tracking) ---
+try:
+    from app.weather_agent import (
+        get_weather_for_location,
+        weather_to_event_recommendations,
+        recommend_outfit,
+        format_weather_summary
+    )
+    WEATHER_AGENT_AVAILABLE = True
+except ImportError as e:
+    logging.getLogger(__name__).warning(f"Weather agent not available: {e}")
+    WEATHER_AGENT_AVAILABLE = False
+
+# --- UTILITY IMPORTS (with availability tracking) ---
+try:
+    from app.location_utils import (
+        extract_city_name,
+        load_city_events,
+        load_city_resources,
+        get_city_coordinates
+    )
+    LOCATION_UTILS_AVAILABLE = True
+except ImportError as e:
+    logging.getLogger(__name__).warning(f"Location utils not available: {e}")
+    LOCATION_UTILS_AVAILABLE = False
+
+# --- LOGGING SETUP ---
+logger = logging.getLogger(__name__)
+
+# --- TRACKING COUNTERS ---
+_tool_request_count = 0
+_weather_request_count = 0
+_event_request_count = 0
+_resource_request_count = 0
+
+
+# ============================================================
+# MAIN TOOL REQUEST HANDLER (ENHANCED)
+# ============================================================
+
+async def handle_tool_request(
+    user_input: str,
+    role: str = "unknown",
+    lat: Optional[float] = None,
+    lon: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    🛠️ Handles tool-based actions for civic services.
+    
+    Routes user requests to appropriate civic data sources and real-time
+    services, including weather, events, transit, trash, and emergency info.
+    
+    Args:
+        user_input: User's request text
+        role: User's role (resident, official, etc.)
+        lat: Latitude coordinate (optional)
+        lon: Longitude coordinate (optional)
+        
+    Returns:
+        Dictionary containing:
+        - tool: str (which tool was used)
+        - city: str (detected city name)
+        - response: str or dict (user-facing response)
+        - data: dict (optional, raw data)
+        - tenant_id: str (optional, standardized city identifier)
+        
+    Example:
+        result = await handle_tool_request(
+            user_input="What's the weather in Atlanta?",
+            role="resident",
+            lat=33.7490,
+            lon=-84.3880
+        )
+    """
+    global _tool_request_count
+    _tool_request_count += 1
+    
+    start_time = time.time()
+    
+    # Sanitize input for logging (PII protection)
+    safe_input = sanitize_for_logging(user_input)
+    logger.info(f"🛠️ Tool request #{_tool_request_count}: '{safe_input[:50]}...'")
+    
+    try:
+        # Check if location utilities are available
+        if not LOCATION_UTILS_AVAILABLE:
+            logger.error("Location utilities not available")
+            return {
+                "tool": "error",
+                "response": (
+                    "I'm having trouble accessing city data right now. "
+                    "Try again in a moment! 💛"
+                ),
+                "error": "Location utilities not loaded"
+            }
+        
+        lowered = user_input.lower()
+        city_name = extract_city_name(user_input)
+        
+        # Standardize tenant ID (e.g., "Atlanta" -> "atlanta_ga")
+        # TODO: Enhance city_name extraction to detect state
+        tenant_id = f"{city_name.lower().replace(' ', '_')}_ga"
+        
+        logger.info(f"Detected city: {city_name} (tenant_id: {tenant_id})")
+        
+        # Route to appropriate handler
+        result = None
+        
+        # Weather queries
+        if any(keyword in lowered for keyword in ["weather", "forecast", "temperature", "rain", "sunny"]):
+            result = await _handle_weather_query(
+                user_input=user_input,
+                city_name=city_name,
+                tenant_id=tenant_id,
+                lat=lat,
+                lon=lon
+            )
+        
+        # Event queries
+        elif any(keyword in lowered for keyword in ["events", "meetings", "city hall", "happening", "activities"]):
+            result = await _handle_events_query(
+                user_input=user_input,
+                city_name=city_name,
+                tenant_id=tenant_id,
+                lat=lat,
+                lon=lon
+            )
+        
+        # Resource queries (trash, transit, emergency)
+        elif any(keyword in lowered for keyword in ["trash", "recycling", "garbage", "bus", "train", "schedule", "alert", "warning", "non emergency"]):
+            result = await _handle_resource_query(
+                user_input=user_input,
+                city_name=city_name,
+                tenant_id=tenant_id,
+                lowered=lowered
+            )
+        
+        # Unknown/fallback
+        else:
+            result = _handle_unknown_query(city_name)
+        
+        # Add metadata and log interaction
+        response_time = (time.time() - start_time) * 1000
+        result["response_time_ms"] = round(response_time, 2)
+        result["role"] = role
+        
+        log_interaction(
+            tenant_id=tenant_id,
+            interaction_type="tool_request",
+            intent=result.get("tool", "unknown"),
+            response_time_ms=response_time,
+            success=result.get("error") is None,
+            metadata={
+                "city": city_name,
+                "tool": result.get("tool"),
+                "role": role,
+                "has_location": lat is not None and lon is not None
+            }
+        )
+        
+        logger.info(
+            f"✅ Tool request complete: {result.get('tool')} "
+            f"({response_time:.0f}ms)"
+        )
+        
+        return result
+    
+    except Exception as e:
+        response_time = (time.time() - start_time) * 1000
+        logger.error(f"❌ Tool agent error: {e}", exc_info=True)
+        
+        log_interaction(
+            tenant_id="unknown",
+            interaction_type="tool_error",
+            intent="error",
+            response_time_ms=response_time,
+            success=False,
+            metadata={
+                "error": str(e),
+                "error_type": type(e).__name__
+            }
+        )
+        
+        return {
+            "tool": "error",
+            "response": (
+                "I ran into trouble processing that request. "
+                "Could you try rephrasing? 💛"
+            ),
+            "error": str(e),
+            "response_time_ms": round(response_time, 2)
+        }
+
+
+# ============================================================
+# WEATHER QUERY HANDLER (ENHANCED)
+# ============================================================
+
+async def _handle_weather_query(
+    user_input: str,
+    city_name: str,
+    tenant_id: str,
+    lat: Optional[float],
+    lon: Optional[float]
+) -> Dict[str, Any]:
+    """
+    🌤️ Handles weather-related queries with outfit recommendations.
+    """
+    global _weather_request_count
+    _weather_request_count += 1
+    
+    logger.info(f"🌤️ Weather query #{_weather_request_count} for {city_name}")
+    
+    # Check weather agent availability
+    if not WEATHER_AGENT_AVAILABLE:
+        logger.warning("Weather agent not available")
+        return {
+            "tool": "weather",
+            "city": city_name,
+            "response": "Weather service isn't available right now. Try again soon! 🌤️"
+        }
+    
+    # Get coordinates if not provided
+    if lat is None or lon is None:
+        coords = get_city_coordinates(tenant_id)
+        if coords:
+            lat, lon = coords["lat"], coords["lon"]
+            logger.info(f"Using city coordinates: {lat}, {lon}")
+    
+    if lat is None or lon is None:
+        return {
+            "tool": "weather",
+            "city": city_name,
+            "response": (
+                f"To get weather for {city_name}, I need location coordinates. "
+                f"Can you share your location? 📍"
+            )
+        }
+    
+    try:
+        # Fetch weather data
+        weather = await get_weather_for_location(lat, lon)
+        
+        # Get weather-based event recommendations
+        recommendations = weather_to_event_recommendations(weather)
+        
+        # Get outfit recommendation
+        temp = weather.get("temperature", {}).get("value", 70)
+        phrase = weather.get("phrase", "Clear")
+        outfit = recommend_outfit(temp, phrase)
+        
+        # Format weather summary
+        weather_summary = format_weather_summary(weather)
+        
+        # Build user-friendly response
+        response_text = (
+            f"🌤️ **Weather for {city_name}:**\n"
+            f"{weather_summary}\n\n"
+            f"���� **What to wear:** {outfit}"
+        )
+        
+        # Add event recommendations if available
+        if recommendations:
+            rec = recommendations[0]  # Get top recommendation
+            response_text += f"\n\n📅 **Activity suggestion:** {rec['reason']}"
+        
+        return {
+            "tool": "weather",
+            "city": city_name,
+            "tenant_id": tenant_id,
+            "response": response_text,
+            "data": {
+                "weather": weather,
+                "recommendations": recommendations,
+                "outfit": outfit
+            }
+        }
+    
+    except Exception as e:
+        logger.error(f"Weather query error: {e}", exc_info=True)
+        return {
+            "tool": "weather",
+            "city": city_name,
+            "response": (
+                f"I couldn't get the weather for {city_name} right now. "
+                f"Try again in a moment! 🌤️"
+            ),
+            "error": str(e)
+        }
+
+
+# ============================================================
+# EVENTS QUERY HANDLER (ENHANCED)
+# ============================================================
+
+async def _handle_events_query(
+    user_input: str,
+    city_name: str,
+    tenant_id: str,
+    lat: Optional[float],
+    lon: Optional[float]
+) -> Dict[str, Any]:
+    """
+    📅 Handles event discovery queries.
+    """
+    global _event_request_count
+    _event_request_count += 1
+    
+    logger.info(f"📅 Event query #{_event_request_count} for {city_name}")
+    
+    try:
+        # Load structured event data
+        event_data = load_city_events(tenant_id)
+        events = event_data.get("events", [])
+        num_events = len(events)
+        
+        if num_events == 0:
+            return {
+                "tool": "civic_events",
+                "city": city_name,
+                "tenant_id": tenant_id,
+                "response": (
+                    f"I don't have any upcoming events for {city_name} right now. "
+                    f"Check back soon! 📅"
+                )
+            }
+        
+        # Get top event
+        top_event = events[0]
+        top_event_name = top_event.get("name", "Upcoming event")
+        
+        # Build response
+        if num_events == 1:
+            response_text = (
+                f"📅 **Upcoming event in {city_name}:**\n"
+                f"• {top_event_name}\n\n"
+                f"Check the full details in the attached data!"
+            )
+        else:
+            response_text = (
+                f"📅 **Found {num_events} upcoming events in {city_name}!**\n"
+                f"Top event: {top_event_name}\n\n"
+                f"Check the full list in the attached data!"
+            )
+        
+        return {
+            "tool": "civic_events",
+            "city": city_name,
+            "tenant_id": tenant_id,
+            "response": response_text,
+            "data": event_data
+        }
+    
+    except FileNotFoundError:
+        logger.warning(f"Event data file not found for {tenant_id}")
+        return {
+            "tool": "civic_events",
+            "city": city_name,
+            "response": (
+                f"Event data for {city_name} isn't available yet. "
+                f"I'm still learning about events in your area! 📅"
+            ),
+            "error": "Event data file not found"
+        }
+    
+    except Exception as e:
+        logger.error(f"Events query error: {e}", exc_info=True)
+        return {
+            "tool": "civic_events",
+            "city": city_name,
+            "response": (
+                f"I had trouble loading events for {city_name}. "
+                f"Try again soon! 📅"
+            ),
+            "error": str(e)
+        }
+
+
+# ============================================================
+# RESOURCE QUERY HANDLER (ENHANCED)
+# ============================================================
+
+async def _handle_resource_query(
+    user_input: str,
+    city_name: str,
+    tenant_id: str,
+    lowered: str
+) -> Dict[str, Any]:
+    """
+    ♻️ Handles resource queries (trash, transit, emergency).
+    """
+    global _resource_request_count
+    _resource_request_count += 1
+    
+    logger.info(f"♻️ Resource query #{_resource_request_count} for {city_name}")
+    
+    # Map keywords to resource types
+    resource_query_map = {
+        "trash": "trash_and_recycling",
+        "recycling": "trash_and_recycling",
+        "garbage": "trash_and_recycling",
+        "bus": "transit",
+        "train": "transit",
+        "schedule": "transit",
+        "alert": "emergency",
+        "warning": "emergency",
+        "non emergency": "emergency"
+    }
+    
+    # Find matching resource type
+    resource_key = next(
+        (resource_query_map[key] for key in resource_query_map if key in lowered),
+        None
+    )
+    
+    if not resource_key:
+        return {
+            "tool": "unknown",
+            "city": city_name,
+            "response": (
+                "I'm not sure which resource you're asking about. "
+                "Try asking about trash, transit, or emergency services! 💬"
+            )
+        }
+    
+    try:
+        # Load structured resource data
+        resource_data = load_city_resources(tenant_id)
+        service_info = resource_data["services"].get(resource_key, {})
+        
+        if not service_info:
+            return {
+                "tool": resource_key,
+                "city": city_name,
+                "response": (
+                    f"I don't have {resource_key.replace('_', ' ')} information "
+                    f"for {city_name} yet. Check the city's official website! 🏛️"
+                )
+            }
+        
+        # Build resource-specific response
+        if resource_key == "trash_and_recycling":
+            pickup_days = service_info.get('pickup_days', 'Varies by address')
+            response_text = (
+                f"♻️ **Trash & Recycling for {city_name}:**\n"
+                f"Pickup days: {pickup_days}\n\n"
+                f"Check the official link for your specific schedule!"
+            )
+        
+        elif resource_key == "transit":
+            provider = service_info.get('provider', 'The local transit authority')
+            response_text = (
+                f"🚌 **Transit for {city_name}:**\n"
+                f"Provider: {provider}\n\n"
+                f"Use the provided links to find routes and schedules!"
+            )
+        
+        elif resource_key == "emergency":
+            non_emergency = service_info.get('non_emergency_phone', 'N/A')
+            response_text = (
+                f"🚨 **Emergency Info for {city_name}:**\n"
+                f"Non-emergency: {non_emergency}\n\n"
+                f"**For life-threatening emergencies, always call 911.**"
+            )
+        
+        else:
+            response_text = f"Information found for {resource_key.replace('_', ' ')}, but details aren't available yet."
+        
+        return {
+            "tool": resource_key,
+            "city": city_name,
+            "tenant_id": tenant_id,
+            "response": response_text,
+            "data": service_info
+        }
+    
+    except FileNotFoundError:
+        logger.warning(f"Resource data file not found for {tenant_id}")
+        return {
+            "tool": "resource_loader",
+            "city": city_name,
+            "response": (
+                f"Resource data for {city_name} isn't available yet. "
+                f"Check back soon! 🏛️"
+            ),
+            "error": "Resource data file not found"
+        }
+    
+    except Exception as e:
+        logger.error(f"Resource query error: {e}", exc_info=True)
+        return {
+            "tool": "resource_loader",
+            "city": city_name,
+            "response": (
+                f"I had trouble loading resource data for {city_name}. "
+                f"Try again soon! 🏛️"
+            ),
+            "error": str(e)
+        }
+
+
+# ============================================================
+# UNKNOWN QUERY HANDLER
+# ============================================================
+
+def _handle_unknown_query(city_name: str) -> Dict[str, Any]:
+    """
+    ❓ Fallback for queries that don't match any tool.
+    """
+    logger.info(f"❓ Unknown query for {city_name}")
+    
+    return {
+        "tool": "unknown",
+        "city": city_name,
+        "response": (
+            "I'm not sure which civic service you're asking about. "
+            "Try asking about weather, events, trash, or transit! 💬"
+        )
+    }
+
+
+# ============================================================
+# HEALTH CHECK & DIAGNOSTICS
+# ============================================================
+
+def get_tool_agent_health() -> Dict[str, Any]:
+    """
+    📊 Returns tool agent health status.
+    
+    Used by the main application health check endpoint.
+    """
+    return {
+        "status": "operational",
+        "service_availability": {
+            "weather_agent": WEATHER_AGENT_AVAILABLE,
+            "location_utils": LOCATION_UTILS_AVAILABLE
+        },
+        "statistics": {
+            "total_requests": _tool_request_count,
+            "weather_requests": _weather_request_count,
+            "event_requests": _event_request_count,
+            "resource_requests": _resource_request_count
+        },
+        "supported_queries": [
+            "weather",
+            "events",
+            "trash_and_recycling",
+            "transit",
+            "emergency"
+        ]
+    }
+
+
+# ============================================================
+# TESTING
+# ============================================================
+
+if __name__ == "__main__":
+    """🧪 Test tool agent functionality"""
+    import asyncio
+    
+    print("=" * 60)
+    print("🧪 Testing Tool Agent")
+    print("=" * 60)
+    
+    # Display service availability
+    print("\n📊 Service Availability:")
+    print(f"  Weather Agent: {'✅' if WEATHER_AGENT_AVAILABLE else '❌'}")
+    print(f"  Location Utils: {'✅' if LOCATION_UTILS_AVAILABLE else '❌'}")
+    
+    print("\n" + "=" * 60)
+    
+    test_queries = [
+        {
+            "name": "Weather query",
+            "input": "What's the weather in Atlanta?",
+            "lat": 33.7490,
+            "lon": -84.3880
+        },
+        {
+            "name": "Events query",
+            "input": "Events in Atlanta",
+            "lat": None,
+            "lon": None
+        },
+        {
+            "name": "Trash query",
+            "input": "When is trash pickup?",
+            "lat": None,
+            "lon": None
+        }
+    ]
+    
+    async def run_tests():
+        for i, query in enumerate(test_queries, 1):
+            print(f"\n--- Test {i}: {query['name']} ---")
+            print(f"Query: {query['input']}")
+            
+            try:
+                result = await handle_tool_request(
+                    user_input=query["input"],
+                    role="test_user",
+                    lat=query["lat"],
+                    lon=query["lon"]
+                )
+                
+                print(f"Tool: {result.get('tool')}")
+                print(f"City: {result.get('city')}")
+                
+                response = result.get('response')
+                if isinstance(response, str):
+                    print(f"Response: {response[:150]}...")
+                else:
+                    print(f"Response: [Dict with {len(response)} keys]")
+                
+                if result.get('response_time_ms'):
+                    print(f"Response time: {result['response_time_ms']:.0f}ms")
+                
+            except Exception as e:
+                print(f"❌ Error: {e}")
+    
+    asyncio.run(run_tests())
+    
+    print("\n" + "=" * 60)
+    print("📊 Final Statistics:")
+    health = get_tool_agent_health()
+    for key, value in health["statistics"].items():
+        print(f"  {key}: {value}")
+    
+    print("\n" + "=" * 60)
+    print("✅ Tests complete")
+    print("=" * 60)