Upload 2 files

app/location_utils.py

@@ -0,0 +1,864 @@
+# 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 7 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"
+        ]
+    )
+    
+    NORFOLK = CityInfo(
+        tenant_id="norfolk_va",
+        full_name="Norfolk, VA",
+        state="VA",
+        timezone="America/New_York",
+        lat=36.8508,
+        lon=-76.2859,
+        aliases=[
+            "norfolk", "norfolk va", "norfolk, va",
+            "city of norfolk", "757", "norfolk virginia"
+        ]
+    )
+    
+    @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,
+            cls.NORFOLK
+        ]
+    
+    @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",
+    
+    # Norfolk
+    "23510": "norfolk_va",
+    "23517": "norfolk_va",
+    "23518": "norfolk_va",
+    "23523": "norfolk_va",
+}
+
+
+# ============================================================
+# 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
+
+
+# ============================================================
+# GEOCODING FUNCTIONS (Azure Maps Integration)
+# ============================================================
+
+AZURE_MAPS_KEY = os.getenv("AZURE_MAPS_KEY")
+
+
+async def geocode_address(address: str) -> Dict[str, Any]:
+    """
+    🗺️ Convert address to coordinates using Azure Maps Search API.
+    
+    Args:
+        address: Human-readable address or city name
+        
+    Returns:
+        Dictionary with lat/lon or error
+        
+    Example:
+        result = await geocode_address("Atlanta, GA")
+        # Returns: {"lat": 33.749, "lon": -84.388}
+    """
+    if not AZURE_MAPS_KEY:
+        logger.error("AZURE_MAPS_KEY not configured")
+        return {"error": "Azure Maps key not configured"}
+    
+    url = "https://atlas.microsoft.com/search/address/json"
+    params = {
+        "api-version": "1.0",
+        "subscription-key": AZURE_MAPS_KEY,
+        "query": address,
+        "limit": 1
+    }
+    
+    try:
+        import httpx
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+        
+        if data.get("results") and len(data["results"]) > 0:
+            position = data["results"][0]["position"]
+            logger.info(f"Geocoded '{address}' to ({position['lat']}, {position['lon']})")
+            return {
+                "lat": position["lat"],
+                "lon": position["lon"]
+            }
+        else:
+            logger.warning(f"No results found for address: {address}")
+            return {"error": "Address not found"}
+            
+    except Exception as e:
+        logger.error(f"Geocoding error: {e}", exc_info=True)
+        return {"error": f"Geocoding failed: {str(e)}"}
+
+
+def get_user_location(city: str) -> Dict[str, Any]:
+    """
+    🌍 Simple wrapper to geocode a city name.
+    
+    Args:
+        city: City name (e.g., "Atlanta")
+        
+    Returns:
+        Dictionary with lat/lon or error
+        
+    Note: This is a synchronous wrapper for backward compatibility.
+    Consider using geocode_address() directly for async code.
+    """
+    import asyncio
+    
+    try:
+        # Run the async geocode_address in a new event loop
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        result = loop.run_until_complete(geocode_address(city))
+        loop.close()
+        return result
+    except Exception as e:
+        logger.error(f"get_user_location error: {e}", exc_info=True)
+        return {"error": str(e)}
+
+
+# ============================================================
+# TESTING
+# ============================================================
+
+if __name__ == "__main__":
+    """🧪 Test location utilities"""
+    
+    print("=" * 60)
+    print("🧪 Testing Location Utils")
+    print("=" * 60)
+    
+    # Initialize system
+    print("\n--- System Initialization ---")
+    initialize_location_system()
+    
+    # Test location extraction
+    print("\n--- Location Extraction Tests ---")
+    test_inputs = [
+        "What's the weather in Atlanta?",
+        "Events near me",
+        "Seattle, WA",
+        "30303",
+        "Show me Birmingham",
+        "Norfolk events this weekend",
+        "What's happening in 757?"
+    ]
+    
+    for test in test_inputs:
+        result = extract_location_detailed(test)
+        print(f"\nInput: '{test}'")
+        print(f"Status: {result.status.value}")
+        print(f"Tenant: {result.tenant_id}")
+        print(f"Confidence: {result.confidence:.2f}")
+    
+    # Test coordinate lookup
+    print("\n--- Coordinate Lookup Tests ---")
+    for city in ["atlanta_ga", "norfolk_va", "seattle_wa"]:
+        coords = get_city_coordinates(city)
+        print(f"{city}: {coords}")
+    
+    print("\n" + "=" * 60)
+    print("✅ Tests complete")

app/orchestrator.py

@@ -0,0 +1,1442 @@
+"""
+🎭 PENNY Orchestrator - Request Routing & Coordination Engine
+
+This is Penny's decision-making brain. She analyzes each request, determines
+the best way to help, and coordinates between her specialized AI models and
+civic data tools.
+
+MISSION: Route every resident request to the right resource while maintaining
+Penny's warm, helpful personality and ensuring fast, accurate responses.
+
+FEATURES:
+- Enhanced intent classification with confidence scoring
+- Compound intent handling (weather + events)
+- Graceful fallbacks when services are unavailable
+- Performance tracking for all operations
+- Context-aware responses
+- Emergency routing with immediate escalation
+
+ENHANCEMENTS (Phase 1):
+- ✅ Structured logging with performance tracking
+- ✅ Safe imports with availability flags
+- ✅ Result format checking helper
+- ✅ Enhanced error handling patterns
+- ✅ Service availability tracking
+- ✅ Fixed function signature mismatches
+- ✅ Integration with enhanced modules
+"""
+
+import logging
+import time
+from typing import Dict, Any, Optional, List, Tuple
+from datetime import datetime
+from dataclasses import dataclass, field
+from enum import Enum
+
+# --- ENHANCED MODULE IMPORTS ---
+from app.intents import classify_intent_detailed, IntentType, IntentMatch
+from app.location_utils import (
+    extract_location_detailed,
+    LocationMatch,
+    LocationStatus,
+    get_city_coordinates
+)
+from app.logging_utils import (
+    log_interaction,
+    sanitize_for_logging,
+    LogLevel
+)
+
+# --- AGENT IMPORTS (with availability tracking) ---
+try:
+    from app.weather_agent import (
+        get_weather_for_location,
+        recommend_outfit,
+        weather_to_event_recommendations,
+        format_weather_summary
+    )
+    WEATHER_AGENT_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Weather agent not available: {e}")
+    WEATHER_AGENT_AVAILABLE = False
+
+try:
+    from app.event_weather import get_event_recommendations_with_weather
+    EVENT_WEATHER_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Event weather integration not available: {e}")
+    EVENT_WEATHER_AVAILABLE = False
+
+try:
+    from app.tool_agent import handle_tool_request
+    TOOL_AGENT_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Tool agent not available: {e}")
+    TOOL_AGENT_AVAILABLE = False
+
+# --- MODEL IMPORTS (with availability tracking) ---
+try:
+    from models.translation.translation_utils import translate_text
+    TRANSLATION_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Translation service not available: {e}")
+    TRANSLATION_AVAILABLE = False
+
+try:
+    from models.sentiment.sentiment_utils import get_sentiment_analysis
+    SENTIMENT_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Sentiment service not available: {e}")
+    SENTIMENT_AVAILABLE = False
+
+try:
+    from models.bias.bias_utils import check_bias
+    BIAS_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"Bias detection service not available: {e}")
+    BIAS_AVAILABLE = False
+
+try:
+    from models.gemma.gemma_utils import generate_response
+    LLM_AVAILABLE = True
+except ImportError as e:
+    logger = logging.getLogger(__name__)
+    logger.warning(f"LLM service not available: {e}")
+    LLM_AVAILABLE = False
+
+# --- LOGGING SETUP ---
+logger = logging.getLogger(__name__)
+
+# --- CONFIGURATION ---
+CORE_MODEL_ID = "penny-core-agent"
+MAX_RESPONSE_TIME_MS = 5000  # 5 seconds - log if exceeded
+
+# --- TRACKING COUNTERS ---
+_orchestration_count = 0
+_emergency_count = 0
+
+
+# ============================================================
+# COMPATIBILITY HELPER - Result Format Checking
+# ============================================================
+
+def _check_result_success(
+    result: Dict[str, Any],
+    expected_keys: List[str]
+) -> Tuple[bool, Optional[str]]:
+    """
+    ✅ Check if a utility function result indicates success.
+    
+    Handles multiple return format patterns:
+    - Explicit "success" key (preferred)
+    - Presence of expected data keys (implicit success)
+    - Presence of "error" key (explicit failure)
+    
+    This helper fixes compatibility issues where different utility
+    functions return different result formats.
+    
+    Args:
+        result: Dictionary returned from utility function
+        expected_keys: List of keys that indicate successful data
+        
+    Returns:
+        Tuple of (is_success, error_message)
+        
+    Example:
+        result = await translate_text(message, "en", "es")
+        success, error = _check_result_success(result, ["translated_text"])
+        if success:
+            text = result.get("translated_text")
+    """
+    # Check for explicit success key
+    if "success" in result:
+        return result["success"], result.get("error")
+    
+    # Check for explicit error (presence = failure)
+    if "error" in result and result["error"]:
+        return False, result["error"]
+    
+    # Check for expected data keys (implicit success)
+    has_data = any(key in result for key in expected_keys)
+    if has_data:
+        return True, None
+    
+    # Unknown format - assume failure
+    return False, "Unexpected response format"
+
+
+# ============================================================
+# SERVICE AVAILABILITY CHECK
+# ============================================================
+
+def get_service_availability() -> Dict[str, bool]:
+    """
+    📊 Returns which services are currently available.
+    
+    Used for health checks, debugging, and deciding whether
+    to attempt service calls or use fallbacks.
+    
+    Returns:
+        Dictionary mapping service names to availability status
+    """
+    return {
+        "translation": TRANSLATION_AVAILABLE,
+        "sentiment": SENTIMENT_AVAILABLE,
+        "bias_detection": BIAS_AVAILABLE,
+        "llm": LLM_AVAILABLE,
+        "tool_agent": TOOL_AGENT_AVAILABLE,
+        "weather": WEATHER_AGENT_AVAILABLE,
+        "event_weather": EVENT_WEATHER_AVAILABLE
+    }
+
+
+# ============================================================
+# ORCHESTRATION RESULT STRUCTURE
+# ============================================================
+
+@dataclass
+class OrchestrationResult:
+    """
+    📦 Structured result from orchestration pipeline.
+    
+    This format is used throughout the system for consistency
+    and makes it easy to track what happened during request processing.
+    """
+    intent: str                                  # Detected intent
+    reply: str                                   # User-facing response
+    success: bool                                # Whether request succeeded
+    tenant_id: Optional[str] = None              # City/location identifier
+    data: Optional[Dict[str, Any]] = None        # Raw data from services
+    model_id: Optional[str] = None               # Which model/service was used
+    error: Optional[str] = None                  # Error message if failed
+    response_time_ms: Optional[float] = None
+    confidence: Optional[float] = None           # Intent confidence score
+    fallback_used: bool = False                  # True if fallback logic triggered
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts to dictionary for API responses."""
+        return {
+            "intent": self.intent,
+            "reply": self.reply,
+            "success": self.success,
+            "tenant_id": self.tenant_id,
+            "data": self.data,
+            "model_id": self.model_id,
+            "error": self.error,
+            "response_time_ms": self.response_time_ms,
+            "confidence": self.confidence,
+            "fallback_used": self.fallback_used
+        }
+
+
+# ============================================================
+# MAIN ORCHESTRATOR FUNCTION (ENHANCED)
+# ============================================================
+
+async def run_orchestrator(
+    message: str,
+    context: Dict[str, Any] = None
+) -> Dict[str, Any]:
+    """
+    🧠 Main decision-making brain of Penny.
+    
+    This function:
+    1. Analyzes the user's message to determine intent
+    2. Extracts location/city information
+    3. Routes to the appropriate specialized service
+    4. Handles errors gracefully with helpful fallbacks
+    5. Tracks performance and logs the interaction
+    
+    Args:
+        message: User's input text
+        context: Additional context (tenant_id, lat, lon, session_id, etc.)
+        
+    Returns:
+        Dictionary with response and metadata
+        
+    Example:
+        result = await run_orchestrator(
+            message="What's the weather in Atlanta?",
+            context={"lat": 33.7490, "lon": -84.3880}
+        )
+    """
+    global _orchestration_count
+    _orchestration_count += 1
+    
+    start_time = time.time()
+    
+    # Initialize context if not provided
+    if context is None:
+        context = {}
+    
+    # Sanitize message for logging (PII protection)
+    safe_message = sanitize_for_logging(message)
+    logger.info(f"🎭 Orchestrator processing: '{safe_message[:50]}...'")
+    
+    try:
+        # === STEP 1: CLASSIFY INTENT (Enhanced) ===
+        intent_result = classify_intent_detailed(message)
+        intent = intent_result.intent
+        confidence = intent_result.confidence
+        
+        logger.info(
+            f"Intent detected: {intent.value} "
+            f"(confidence: {confidence:.2f})"
+        )
+        
+        # === STEP 2: EXTRACT LOCATION ===
+        tenant_id = context.get("tenant_id")
+        lat = context.get("lat")
+        lon = context.get("lon")
+        
+        # If tenant_id not provided, try to extract from message
+        if not tenant_id or tenant_id == "unknown":
+            location_result = extract_location_detailed(message)
+            
+            if location_result.status == LocationStatus.FOUND:
+                tenant_id = location_result.tenant_id
+                logger.info(f"Location extracted: {tenant_id}")
+                
+                # Get coordinates for this tenant if available
+                coords = get_city_coordinates(tenant_id)
+                if coords and lat is None and lon is None:
+                    lat, lon = coords["lat"], coords["lon"]
+                    logger.info(f"Coordinates loaded: {lat}, {lon}")
+                    
+            elif location_result.status == LocationStatus.USER_LOCATION_NEEDED:
+                logger.info("User location services needed")
+            else:
+                logger.info(f"No location detected: {location_result.status}")
+        
+        # === STEP 3: HANDLE EMERGENCY INTENTS (CRITICAL) ===
+        if intent == IntentType.EMERGENCY:
+            return await _handle_emergency(
+                message=message,
+                context=context,
+                start_time=start_time
+            )
+        
+        # === STEP 4: ROUTE TO APPROPRIATE HANDLER ===
+        
+        # Translation
+        if intent == IntentType.TRANSLATION:
+            result = await _handle_translation(message, context)
+        
+        # Sentiment Analysis
+        elif intent == IntentType.SENTIMENT_ANALYSIS:
+            result = await _handle_sentiment(message, context)
+        
+        # Bias Detection
+        elif intent == IntentType.BIAS_DETECTION:
+            result = await _handle_bias(message, context)
+        
+        # Document Processing
+        elif intent == IntentType.DOCUMENT_PROCESSING:
+            result = await _handle_document(message, context)
+        
+        # Weather (includes compound weather+events handling)
+       async def _handle_weather(
+    message: str,
+    context: Dict[str, Any],
+    tenant_id: Optional[str],
+    lat: Optional[float],
+    lon: Optional[float],
+    intent_result: IntentMatch
+) -> OrchestrationResult:
+    """
+    🌤️ Weather handler with compound intent support.
+    
+    Handles both simple weather queries and compound weather+events queries.
+    Uses enhanced weather_agent.py with caching and performance tracking.
+    """
+    logger.info("🌤️ Processing weather request")
+    
+    # Check service availability first
+    if not WEATHER_AGENT_AVAILABLE:
+        logger.warning("Weather agent not available")
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply="Weather service isn't available right now. Try again soon! 🌤️",
+            success=False,
+            error="Weather agent not loaded",
+            fallback_used=True
+        )
+    
+    # Check for compound intent (weather + events)
+    is_compound = intent_result.is_compound or IntentType.EVENTS in intent_result.secondary_intents
+    
+    # === ENHANCED LOCATION RESOLUTION ===
+    
+    # Step 1: Try to extract location from the query itself
+    if not tenant_id or (lat is None or lon is None):
+        location_result = extract_location_detailed(message)
+        
+        if location_result.status == LocationStatus.FOUND:
+            tenant_id = location_result.tenant_id
+            logger.info(f"📍 Location extracted from query: {tenant_id}")
+            
+            # Get coordinates for extracted location
+            coords = get_city_coordinates(tenant_id)
+            if coords:
+                lat, lon = coords["lat"], coords["lon"]
+                logger.info(f"✅ Coordinates found: {lat}, {lon}")
+    
+    # Step 2: If still no coordinates, try to get from tenant_id
+    if (lat is None or lon is None) and tenant_id:
+        coords = get_city_coordinates(tenant_id)
+        if coords:
+            lat, lon = coords["lat"], coords["lon"]
+            logger.info(f"✅ Coordinates from tenant_id: {lat}, {lon}")
+    
+    # Step 3: If still no coordinates, ask for location
+    if lat is None or lon is None:
+        logger.warning("❌ No coordinates available for weather request")
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply=(
+                "I need to know your location to check the weather! 📍 "
+                "You can tell me your city, or share your location."
+            ),
+            success=False,
+            error="Location required"
+        )
+    
+    try:
+        # Use combined weather + events if compound intent detected
+        if is_compound and tenant_id and EVENT_WEATHER_AVAILABLE:
+            logger.info("Using weather+events combined handler")
+            result = await get_event_recommendations_with_weather(tenant_id, lat, lon)
+            
+            # Build response
+            weather = result.get("weather", {})
+            weather_summary = result.get("weather_summary", "Weather unavailable")
+            suggestions = result.get("suggestions", [])
+            
+            reply_lines = [f"🌤️ **Weather Update:**\n{weather_summary}\n"]
+            
+            if suggestions:
+                reply_lines.append("\n📅 **Event Suggestions Based on Weather:**")
+                for suggestion in suggestions[:5]:  # Top 5 suggestions
+                    reply_lines.append(f"• {suggestion}")
+            
+            reply = "\n".join(reply_lines)
+            
+            return OrchestrationResult(
+                intent=IntentType.WEATHER.value,
+                reply=reply,
+                success=True,
+                data=result,
+                model_id="weather_events_combined"
+            )
+        
+        else:
+            # Simple weather query using enhanced weather_agent
+            logger.info(f"🌤️ Fetching weather for coordinates: {lat}, {lon}")
+            weather = await get_weather_for_location(lat, lon)
+            
+            # Use enhanced weather_agent's format_weather_summary
+            weather_text = format_weather_summary(weather)
+            
+            # Get outfit recommendation from enhanced weather_agent
+            temp = weather.get("temperature", {}).get("value", 70)
+            condition = weather.get("phrase", "Clear")
+            outfit = recommend_outfit(temp, condition)
+            
+            # Build friendly response with location name if available
+            location_name = tenant_id.replace("_", " ").title() if tenant_id else "your location"
+            reply = f"🌤️ **Weather for {location_name}:**\n\n{weather_text}\n\n👕 {outfit}"
+            
+            logger.info(f"✅ Weather fetched successfully for {location_name}")
+            
+            return OrchestrationResult(
+                intent=IntentType.WEATHER.value,
+                reply=reply,
+                success=True,
+                data=weather,
+                model_id="azure-maps-weather",
+                tenant_id=tenant_id
+            )
+    
+    except Exception as e:
+        logger.error(f"❌ Weather error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply=(
+                "I'm having trouble getting weather data right now. "
+                "Can I help you with something else? 💛"
+            ),
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+        
+        # Events
+        elif intent == IntentType.EVENTS:
+            result = await _handle_events(
+                message=message,
+                context=context,
+                tenant_id=tenant_id,
+                lat=lat,
+                lon=lon,
+                intent_result=intent_result
+            )
+
+        # Local Resources
+        elif intent == IntentType.LOCAL_RESOURCES:
+            result = await _handle_local_resources(
+                message=message,
+                context=context,
+                tenant_id=tenant_id,
+                lat=lat,
+                lon=lon
+            )
+        
+        # Greeting, Help, Unknown
+        elif intent in [IntentType.GREETING, IntentType.HELP, IntentType.UNKNOWN]:
+            result = await _handle_conversational(
+                message=message,
+                intent=intent,
+                context=context
+            )
+        
+        else:
+            # Unhandled intent type (shouldn't happen, but safety net)
+            result = await _handle_fallback(message, intent, context)
+        
+        # === STEP 5: ADD METADATA & LOG INTERACTION ===
+        response_time = (time.time() - start_time) * 1000
+        result.response_time_ms = round(response_time, 2)
+        result.confidence = confidence
+        result.tenant_id = tenant_id
+        
+        # Log the interaction with structured logging
+        log_interaction(
+            tenant_id=tenant_id or "unknown",
+            interaction_type="orchestration",
+            intent=intent.value,
+            response_time_ms=response_time,
+            success=result.success,
+            metadata={
+                "confidence": confidence,
+                "fallback_used": result.fallback_used,
+                "model_id": result.model_id,
+                "orchestration_count": _orchestration_count
+            }
+        )
+        
+        # Log slow responses
+        if response_time > MAX_RESPONSE_TIME_MS:
+            logger.warning(
+                f"⚠️ Slow response: {response_time:.0f}ms "
+                f"(intent: {intent.value})"
+            )
+        
+        logger.info(
+            f"✅ Orchestration complete: {intent.value} "
+            f"({response_time:.0f}ms)"
+        )
+        
+        return result.to_dict()
+    
+    except Exception as e:
+        # === CATASTROPHIC FAILURE HANDLER ===
+        response_time = (time.time() - start_time) * 1000
+        logger.error(
+            f"❌ Orchestrator error: {e} "
+            f"(response_time: {response_time:.0f}ms)",
+            exc_info=True
+        )
+        
+        # Log failed interaction
+        log_interaction(
+            tenant_id=context.get("tenant_id", "unknown"),
+            interaction_type="orchestration_error",
+            intent="error",
+            response_time_ms=response_time,
+            success=False,
+            metadata={
+                "error": str(e),
+                "error_type": type(e).__name__
+            }
+        )
+        
+        error_result = OrchestrationResult(
+            intent="error",
+            reply=(
+                "I'm having trouble processing your request right now. "
+                "Please try again in a moment, or let me know if you need "
+                "immediate assistance! 💛"
+            ),
+            success=False,
+            error=str(e),
+            model_id="orchestrator",
+            fallback_used=True,
+            response_time_ms=round(response_time, 2)
+        )
+        
+        return error_result.to_dict()
+
+
+# ============================================================
+# SPECIALIZED INTENT HANDLERS (ENHANCED)
+# ============================================================
+
+async def _handle_emergency(
+    message: str,
+    context: Dict[str, Any],
+    start_time: float
+) -> OrchestrationResult:
+    """
+    🚨 CRITICAL: Emergency intent handler.
+    
+    This function handles crisis situations with immediate routing
+    to appropriate services. All emergency interactions are logged
+    for compliance and safety tracking.
+    
+    IMPORTANT: This is a compliance-critical function. All emergency
+    interactions must be logged and handled with priority.
+    """
+    global _emergency_count
+    _emergency_count += 1
+    
+    # Sanitize message for logging (but keep full context for safety review)
+    safe_message = sanitize_for_logging(message)
+    logger.warning(f"🚨 EMERGENCY INTENT DETECTED (#{_emergency_count}): {safe_message[:100]}")
+    
+    # TODO: Integrate with safety_utils.py when enhanced
+    # from app.safety_utils import route_emergency
+    # result = await route_emergency(message, context)
+    
+    # For now, provide crisis resources
+    reply = (
+        "🚨 **If this is a life-threatening emergency, please call 911 immediately.**\n\n"
+        "For crisis support:\n"
+        "- **National Suicide Prevention Lifeline:** 988\n"
+        "- **Crisis Text Line:** Text HOME to 741741\n"
+        "- **National Domestic Violence Hotline:** 1-800-799-7233\n\n"
+        "I'm here to help connect you with local resources. "
+        "What kind of support do you need right now?"
+    )
+    
+    # Log emergency interaction for compliance (CRITICAL)
+    response_time = (time.time() - start_time) * 1000
+    log_interaction(
+        tenant_id=context.get("tenant_id", "emergency"),
+        interaction_type="emergency",
+        intent=IntentType.EMERGENCY.value,
+        response_time_ms=response_time,
+        success=True,
+        metadata={
+            "emergency_number": _emergency_count,
+            "message_length": len(message),
+            "timestamp": datetime.now().isoformat(),
+            "action": "crisis_resources_provided"
+        }
+    )
+    
+    logger.critical(
+        f"EMERGENCY LOG #{_emergency_count}: Resources provided "
+        f"({response_time:.0f}ms)"
+    )
+    
+    return OrchestrationResult(
+        intent=IntentType.EMERGENCY.value,
+        reply=reply,
+        success=True,
+        model_id="emergency_router",
+        data={"crisis_resources_provided": True},
+        response_time_ms=round(response_time, 2)
+    )
+
+
+async def _handle_translation(
+    message: str,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    🌍 Translation handler - 27 languages supported.
+    
+    Handles translation requests with graceful fallback if service
+    is unavailable.
+    """
+    logger.info("🌍 Processing translation request")
+    
+    # Check service availability first
+    if not TRANSLATION_AVAILABLE:
+        logger.warning("Translation service not available")
+        return OrchestrationResult(
+            intent=IntentType.TRANSLATION.value,
+            reply="Translation isn't available right now. Try again soon! 🌍",
+            success=False,
+            error="Service not loaded",
+            fallback_used=True
+        )
+    
+    try:
+        # Extract language parameters from context
+        source_lang = context.get("source_lang", "eng_Latn")
+        target_lang = context.get("target_lang", "spa_Latn")
+        
+        # TODO: Parse languages from message when enhanced
+        # Example: "Translate 'hello' to Spanish"
+        
+        result = await translate_text(message, source_lang, target_lang)
+        
+        # Use compatibility helper to check result
+        success, error = _check_result_success(result, ["translated_text"])
+        
+        if success:
+            translated = result.get("translated_text", "")
+            reply = (
+                f"Here's the translation:\n\n"
+                f"**{translated}**\n\n"
+                f"(Translated from {source_lang} to {target_lang})"
+            )
+            
+            return OrchestrationResult(
+                intent=IntentType.TRANSLATION.value,
+                reply=reply,
+                success=True,
+                data=result,
+                model_id="penny-translate-agent"
+            )
+        else:
+            raise Exception(error or "Translation failed")
+    
+    except Exception as e:
+        logger.error(f"Translation error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.TRANSLATION.value,
+            reply=(
+                "I had trouble translating that. Could you rephrase? 💬"
+            ),
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+
+async def _handle_sentiment(
+    message: str,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    😊 Sentiment analysis handler.
+    
+    Analyzes the emotional tone of text with graceful fallback
+    if service is unavailable.
+    """
+    logger.info("😊 Processing sentiment analysis")
+    
+    # Check service availability first
+    if not SENTIMENT_AVAILABLE:
+        logger.warning("Sentiment service not available")
+        return OrchestrationResult(
+            intent=IntentType.SENTIMENT_ANALYSIS.value,
+            reply="Sentiment analysis isn't available right now. Try again soon! 😊",
+            success=False,
+            error="Service not loaded",
+            fallback_used=True
+        )
+    
+    try:
+        result = await get_sentiment_analysis(message)
+        
+        # Use compatibility helper to check result
+        success, error = _check_result_success(result, ["label", "score"])
+        
+        if success:
+            sentiment = result.get("label", "neutral")
+            confidence = result.get("score", 0.0)
+            
+            reply = (
+                f"The overall sentiment detected is: **{sentiment}**\n"
+                f"Confidence: {confidence:.1%}"
+            )
+            
+            return OrchestrationResult(
+                intent=IntentType.SENTIMENT_ANALYSIS.value,
+                reply=reply,
+                success=True,
+                data=result,
+                model_id="penny-sentiment-agent"
+            )
+        else:
+            raise Exception(error or "Sentiment analysis failed")
+    
+    except Exception as e:
+        logger.error(f"Sentiment analysis error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.SENTIMENT_ANALYSIS.value,
+            reply="I couldn't analyze the sentiment right now. Try again? 😊",
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+async def _handle_bias(
+    message: str,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    ⚖️ Bias detection handler.
+    
+    Analyzes text for potential bias patterns with graceful fallback
+    if service is unavailable.
+    """
+    logger.info("⚖️ Processing bias detection")
+    
+    # Check service availability first
+    if not BIAS_AVAILABLE:
+        logger.warning("Bias detection service not available")
+        return OrchestrationResult(
+            intent=IntentType.BIAS_DETECTION.value,
+            reply="Bias detection isn't available right now. Try again soon! ⚖️",
+            success=False,
+            error="Service not loaded",
+            fallback_used=True
+        )
+    
+    try:
+        result = await check_bias(message)
+        
+        # Use compatibility helper to check result
+        success, error = _check_result_success(result, ["analysis"])
+        
+        if success:
+            analysis = result.get("analysis", [])
+            
+            if analysis:
+                top_result = analysis[0]
+                label = top_result.get("label", "unknown")
+                score = top_result.get("score", 0.0)
+                
+                reply = (
+                    f"Bias analysis complete:\n\n"
+                    f"**Most likely category:** {label}\n"
+                    f"**Confidence:** {score:.1%}"
+                )
+            else:
+                reply = "The text appears relatively neutral. ⚖️"
+            
+            return OrchestrationResult(
+                intent=IntentType.BIAS_DETECTION.value,
+                reply=reply,
+                success=True,
+                data=result,
+                model_id="penny-bias-checker"
+            )
+        else:
+            raise Exception(error or "Bias detection failed")
+    
+    except Exception as e:
+        logger.error(f"Bias detection error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.BIAS_DETECTION.value,
+            reply="I couldn't check for bias right now. Try again? ⚖️",
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+
+async def _handle_document(
+    message: str,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    📄 Document processing handler.
+    
+    Note: Actual file upload happens in router.py via FastAPI.
+    This handler just provides instructions.
+    """
+    logger.info("📄 Document processing requested")
+    
+    reply = (
+        "I can help you process documents! 📄\n\n"
+        "Please upload your document (PDF or image) using the "
+        "`/upload-document` endpoint. I can extract text, analyze forms, "
+        "and help you understand civic documents.\n\n"
+        "What kind of document do you need help with?"
+    )
+    
+    return OrchestrationResult(
+        intent=IntentType.DOCUMENT_PROCESSING.value,
+        reply=reply,
+        success=True,
+        model_id="document_router"
+    )
+
+
+async def _handle_weather(
+    message: str,
+    context: Dict[str, Any],
+    tenant_id: Optional[str],
+    lat: Optional[float],
+    lon: Optional[float],
+    intent_result: IntentMatch
+) -> OrchestrationResult:
+    """
+    🌤️ Weather handler with compound intent support.
+    
+    Handles both simple weather queries and compound weather+events queries.
+    Uses enhanced weather_agent.py with caching and performance tracking.
+    """
+    logger.info("🌤️ Processing weather request")
+    
+    # Check service availability first
+    if not WEATHER_AGENT_AVAILABLE:
+        logger.warning("Weather agent not available")
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply="Weather service isn't available right now. Try again soon! 🌤️",
+            success=False,
+            error="Weather agent not loaded",
+            fallback_used=True
+        )
+    
+    # Check for compound intent (weather + events)
+    is_compound = intent_result.is_compound or IntentType.EVENTS in intent_result.secondary_intents
+    
+    # Validate location
+    if lat is None or lon is None:
+        # Try to get coordinates from tenant_id
+        if tenant_id:
+            coords = get_city_coordinates(tenant_id)
+            if coords and lat is None and lon is None:
+                lat, lon = coords["lat"], coords["lon"]
+                logger.info(f"Using city coordinates for {tenant_id}: {lat}, {lon}")
+    
+    if lat is None or lon is None:
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply=(
+                "I need to know your location to check the weather! 📍 "
+                "You can tell me your city, or share your location."
+            ),
+            success=False,
+            error="Location required"
+        )
+    
+    try:
+        # Use combined weather + events if compound intent detected
+        if is_compound and tenant_id and EVENT_WEATHER_AVAILABLE:
+            logger.info("Using weather+events combined handler")
+            result = await get_event_recommendations_with_weather(tenant_id, lat, lon)
+            
+            # Build response
+            weather = result.get("weather", {})
+            weather_summary = result.get("weather_summary", "Weather unavailable")
+            suggestions = result.get("suggestions", [])
+            
+            reply_lines = [f"🌤️ **Weather Update:**\n{weather_summary}\n"]
+            
+            if suggestions:
+                reply_lines.append("\n📅 **Event Suggestions Based on Weather:**")
+                for suggestion in suggestions[:5]:  # Top 5 suggestions
+                    reply_lines.append(f"• {suggestion}")
+            
+            reply = "\n".join(reply_lines)
+            
+            return OrchestrationResult(
+                intent=IntentType.WEATHER.value,
+                reply=reply,
+                success=True,
+                data=result,
+                model_id="weather_events_combined"
+            )
+        
+        else:
+            # Simple weather query using enhanced weather_agent
+            weather = await get_weather_for_location(lat, lon)
+            
+            # Use enhanced weather_agent's format_weather_summary
+            if format_weather_summary:
+                weather_text = format_weather_summary(weather)
+            else:
+                # Fallback formatting
+                temp = weather.get("temperature", {}).get("value")
+                phrase = weather.get("phrase", "Conditions unavailable")
+                if temp:
+                    weather_text = f"{phrase}, {int(temp)}°F"
+                else:
+                    weather_text = phrase
+            
+            # Get outfit recommendation from enhanced weather_agent
+            if recommend_outfit:
+                temp = weather.get("temperature", {}).get("value", 70)
+                condition = weather.get("phrase", "Clear")
+                outfit = recommend_outfit(temp, condition)
+                reply = f"🌤️ {weather_text}\n\n👕 {outfit}"
+            else:
+                reply = f"🌤️ {weather_text}"
+            
+            return OrchestrationResult(
+                intent=IntentType.WEATHER.value,
+                reply=reply,
+                success=True,
+                data=weather,
+                model_id="azure-maps-weather"
+            )
+    
+    except Exception as e:
+        logger.error(f"Weather error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.WEATHER.value,
+            reply=(
+                "I'm having trouble getting weather data right now. "
+                "Can I help you with something else? 💛"
+            ),
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+
+async def _handle_events(
+    message: str,
+    context: Dict[str, Any],
+    tenant_id: Optional[str],
+    lat: Optional[float],
+    lon: Optional[float],
+    intent_result: IntentMatch
+) -> OrchestrationResult:
+    """
+    📅 Events handler.
+    
+    Routes event queries to tool_agent with proper error handling
+    and graceful degradation.
+    """
+    logger.info("📅 Processing events request")
+    
+    if not tenant_id:
+        return OrchestrationResult(
+            intent=IntentType.EVENTS.value,
+            reply=(
+                "I'd love to help you find events! 📅 "
+                "Which city are you interested in? "
+                "I have information for Atlanta, Birmingham, Chesterfield, "
+                "El Paso, Providence, and Seattle."
+            ),
+            success=False,
+            error="City required"
+        )
+    
+    # Check tool agent availability
+    if not TOOL_AGENT_AVAILABLE:
+        logger.warning("Tool agent not available")
+        return OrchestrationResult(
+            intent=IntentType.EVENTS.value,
+            reply=(
+                "Event information isn't available right now. "
+                "Try again soon! 📅"
+            ),
+            success=False,
+            error="Tool agent not loaded",
+            fallback_used=True
+        )
+    
+    try:
+        # FIXED: Add role parameter (compatibility fix)
+        tool_response = await handle_tool_request(
+            user_input=message,
+            role=context.get("role", "resident"),  # ← ADDED
+            lat=lat,
+            lon=lon,
+            context=context
+        )
+        
+        reply = tool_response.get("response", "Events information retrieved.")
+        
+        return OrchestrationResult(
+            intent=IntentType.EVENTS.value,
+            reply=reply,
+            success=True,
+            data=tool_response,
+            model_id="events_tool"
+        )
+    
+    except Exception as e:
+        logger.error(f"Events error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.EVENTS.value,
+            reply=(
+                "I'm having trouble loading event information right now. "
+                "Check back soon! 📅"
+            ),
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+async def _handle_local_resources(
+    message: str,
+    context: Dict[str, Any],
+    tenant_id: Optional[str],
+    lat: Optional[float],
+    lon: Optional[float]
+) -> OrchestrationResult:
+    """
+    🏛️ Local resources handler (shelters, libraries, food banks, etc.).
+    
+    Routes resource queries to tool_agent with proper error handling.
+    """
+    logger.info("🏛️ Processing local resources request")
+    
+    if not tenant_id:
+        return OrchestrationResult(
+            intent=IntentType.LOCAL_RESOURCES.value,
+            reply=(
+                "I can help you find local resources! 🏛️ "
+                "Which city do you need help in? "
+                "I cover Atlanta, Birmingham, Chesterfield, El Paso, "
+                "Providence, and Seattle."
+            ),
+            success=False,
+            error="City required"
+        )
+    
+    # Check tool agent availability
+    if not TOOL_AGENT_AVAILABLE:
+        logger.warning("Tool agent not available")
+        return OrchestrationResult(
+            intent=IntentType.LOCAL_RESOURCES.value,
+            reply=(
+                "Resource information isn't available right now. "
+                "Try again soon! 🏛️"
+            ),
+            success=False,
+            error="Tool agent not loaded",
+            fallback_used=True
+        )
+    
+    try:
+        # FIXED: Add role parameter (compatibility fix)
+        tool_response = await handle_tool_request(
+            user_input=message,
+            role=context.get("role", "resident"),  # ← ADDED
+            lat=lat,
+            lon=lon,
+            context=context
+        )
+        
+        reply = tool_response.get("response", "Resource information retrieved.")
+        
+        return OrchestrationResult(
+            intent=IntentType.LOCAL_RESOURCES.value,
+            reply=reply,
+            success=True,
+            data=tool_response,
+            model_id="resources_tool"
+        )
+    
+    except Exception as e:
+        logger.error(f"Resources error: {e}", exc_info=True)
+        return OrchestrationResult(
+            intent=IntentType.LOCAL_RESOURCES.value,
+            reply=(
+                "I'm having trouble finding resource information right now. "
+                "Would you like to try a different search? 💛"
+            ),
+            success=False,
+            error=str(e),
+            fallback_used=True
+        )
+
+
+async def _handle_conversational(
+    message: str,
+    intent: IntentType,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    💬 Handles conversational intents (greeting, help, unknown).
+    Uses Penny's core LLM for natural responses with graceful fallback.
+    """
+    logger.info(f"💬 Processing conversational intent: {intent.value}")
+    
+    # Check LLM availability
+    use_llm = LLM_AVAILABLE
+    
+    try:
+        if use_llm:
+            # Build prompt based on intent
+            if intent == IntentType.GREETING:
+                prompt = (
+                    f"The user greeted you with: '{message}'\n\n"
+                    "Respond warmly as Penny, introduce yourself briefly, "
+                    "and ask how you can help them with civic services today."
+                )
+            
+            elif intent == IntentType.HELP:
+                prompt = (
+                    f"The user asked for help: '{message}'\n\n"
+                    "Explain Penny's main features:\n"
+                    "- Finding local resources (shelters, libraries, food banks)\n"
+                    "- Community events and activities\n"
+                    "- Weather information\n"
+                    "- 27-language translation\n"
+                    "- Document processing help\n\n"
+                    "Ask which city they need assistance in."
+                )
+            
+            else:  # UNKNOWN
+                prompt = (
+                    f"The user said: '{message}'\n\n"
+                    "You're not sure what they need help with. "
+                    "Respond kindly, acknowledge their request, and ask them to "
+                    "clarify or rephrase. Mention a few things you can help with."
+                )
+            
+            # Call Penny's core LLM
+            llm_result = await generate_response(prompt=prompt, max_new_tokens=200)
+            
+            # Use compatibility helper to check result
+            success, error = _check_result_success(llm_result, ["response"])
+            
+            if success:
+                reply = llm_result.get("response", "")
+                
+                return OrchestrationResult(
+                    intent=intent.value,
+                    reply=reply,
+                    success=True,
+                    data=llm_result,
+                    model_id=CORE_MODEL_ID
+                )
+            else:
+                raise Exception(error or "LLM generation failed")
+        
+        else:
+            # LLM not available, use fallback directly
+            logger.info("LLM not available, using fallback responses")
+            raise Exception("LLM service not loaded")
+    
+    except Exception as e:
+        logger.warning(f"Conversational handler using fallback: {e}")
+        
+        # Hardcoded fallback responses (Penny's friendly voice)
+        fallback_replies = {
+            IntentType.GREETING: (
+                "Hi there! 👋 I'm Penny, your civic assistant. "
+                "I can help you find local resources, events, weather, and more. "
+                "What city are you in?"
+            ),
+            IntentType.HELP: (
+                "I'm Penny! 💛 I can help you with:\n\n"
+                "🏛️ Local resources (shelters, libraries, food banks)\n"
+                "📅 Community events\n"
+                "🌤️ Weather updates\n"
+                "🌍 Translation (27 languages)\n"
+                "📄 Document help\n\n"
+                "What would you like to know about?"
+            ),
+            IntentType.UNKNOWN: (
+                "I'm not sure I understood that. Could you rephrase? "
+                "I'm best at helping with local services, events, weather, "
+                "and translation! 💬"
+            )
+        }
+        
+        return OrchestrationResult(
+            intent=intent.value,
+            reply=fallback_replies.get(intent, "How can I help you today? 💛"),
+            success=True,
+            model_id="fallback",
+            fallback_used=True
+        )
+
+
+async def _handle_fallback(
+    message: str,
+    intent: IntentType,
+    context: Dict[str, Any]
+) -> OrchestrationResult:
+    """
+    🆘 Ultimate fallback handler for unhandled intents.
+    
+    This is a safety net that should rarely trigger, but ensures
+    users always get a helpful response.
+    """
+    logger.warning(f"⚠️ Fallback triggered for intent: {intent.value}")
+    
+    reply = (
+        "I've processed your request, but I'm not sure how to help with that yet. "
+        "I'm still learning! 🤖\n\n"
+        "I'm best at:\n"
+        "🏛️ Finding local resources\n"
+        "📅 Community events\n"
+        "🌤️ Weather updates\n"
+        "🌍 Translation\n\n"
+        "Could you rephrase your question? 💛"
+    )
+    
+    return OrchestrationResult(
+        intent=intent.value,
+        reply=reply,
+        success=False,
+        error="Unhandled intent",
+        fallback_used=True
+    )
+
+
+# ============================================================
+# HEALTH CHECK & DIAGNOSTICS (ENHANCED)
+# ============================================================
+
+def get_orchestrator_health() -> Dict[str, Any]:
+    """
+    📊 Returns comprehensive orchestrator health status.
+    
+    Used by the main application health check endpoint to monitor
+    the orchestrator and all its service dependencies.
+    
+    Returns:
+        Dictionary with health information including:
+        - status: operational/degraded
+        - service_availability: which services are loaded
+        - statistics: orchestration counts
+        - supported_intents: list of all intent types
+        - features: available orchestrator features
+    """
+    # Get service availability
+    services = get_service_availability()
+    
+    # Determine overall status
+    # Orchestrator is operational even if some services are down (graceful degradation)
+    critical_services = ["weather", "tool_agent"]  # Must have these
+    critical_available = all(services.get(svc, False) for svc in critical_services)
+    
+    status = "operational" if critical_available else "degraded"
+    
+    return {
+        "status": status,
+        "core_model": CORE_MODEL_ID,
+        "max_response_time_ms": MAX_RESPONSE_TIME_MS,
+        "statistics": {
+            "total_orchestrations": _orchestration_count,
+            "emergency_interactions": _emergency_count
+        },
+        "service_availability": services,
+        "supported_intents": [intent.value for intent in IntentType],
+        "features": {
+            "emergency_routing": True,
+            "compound_intents": True,
+            "fallback_handling": True,
+            "performance_tracking": True,
+            "context_aware": True,
+            "multi_language": TRANSLATION_AVAILABLE,
+            "sentiment_analysis": SENTIMENT_AVAILABLE,
+            "bias_detection": BIAS_AVAILABLE,
+            "weather_integration": WEATHER_AGENT_AVAILABLE,
+            "event_recommendations": EVENT_WEATHER_AVAILABLE
+        }
+    }
+
+
+def get_orchestrator_stats() -> Dict[str, Any]:
+    """
+    📈 Returns orchestrator statistics.
+    
+    Useful for monitoring and analytics.
+    """
+    return {
+        "total_orchestrations": _orchestration_count,
+        "emergency_interactions": _emergency_count,
+        "services_available": sum(1 for v in get_service_availability().values() if v),
+        "services_total": len(get_service_availability())
+    }
+
+
+# ============================================================
+# TESTING & DEBUGGING (ENHANCED)
+# ============================================================
+
+if __name__ == "__main__":
+    """
+    🧪 Test the orchestrator with sample queries.
+    Run with: python -m app.orchestrator
+    """
+    import asyncio
+    
+    print("=" * 60)
+    print("🧪 Testing Penny's Orchestrator")
+    print("=" * 60)
+    
+    # Display service availability first
+    print("\n📊 Service Availability Check:")
+    services = get_service_availability()
+    for service, available in services.items():
+        status = "✅" if available else "❌"
+        print(f"  {status} {service}: {'Available' if available else 'Not loaded'}")
+    
+    print("\n" + "=" * 60)
+    
+    test_queries = [
+        {
+            "name": "Greeting",
+            "message": "Hi Penny!",
+            "context": {}
+        },
+        {
+            "name": "Weather with location",
+            "message": "What's the weather?",
+            "context": {"lat": 33.7490, "lon": -84.3880}
+        },
+        {
+            "name": "Events in city",
+            "message": "Events in Atlanta",
+            "context": {"tenant_id": "atlanta_ga"}
+        },
+        {
+            "name": "Help request",
+            "message": "I need help",
+            "context": {}
+        },
+        {
+            "name": "Translation",
+            "message": "Translate hello",
+            "context": {"source_lang": "eng_Latn", "target_lang": "spa_Latn"}
+        }
+    ]
+    
+    async def run_tests():
+        for i, query in enumerate(test_queries, 1):
+            print(f"\n--- Test {i}: {query['name']} ---")
+            print(f"Query: {query['message']}")
+            
+            try:
+                result = await run_orchestrator(query["message"], query["context"])
+                print(f"Intent: {result['intent']}")
+                print(f"Success: {result['success']}")
+                print(f"Fallback: {result.get('fallback_used', False)}")
+                
+                # Truncate long replies
+                reply = result['reply']
+                if len(reply) > 150:
+                    reply = reply[:150] + "..."
+                print(f"Reply: {reply}")
+                
+                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:")
+    stats = get_orchestrator_stats()
+    for key, value in stats.items():
+        print(f"  {key}: {value}")
+    
+    print("\n" + "=" * 60)
+    print("✅ Tests complete")
+    print("=" * 60)