Delete app/tool_agent.py

app/tool_agent.py

@@ -1,726 +0,0 @@
-# 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
-- ✅ Context-aware city detection (uses tenant_id from UI dropdown)
-"""
-
-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
-
-
-# ============================================================
-# CITY DETECTION FROM CONTEXT (NEW FUNCTION)
-# ============================================================
-
-def get_city_from_context(context: Dict[str, Any], user_input: str) -> tuple[str, str]:
-    """
-    🏙️ Extracts city name and tenant_id from context or message.
-    
-    Priority order:
-    1. tenant_id from context (from UI dropdown)
-    2. location from context
-    3. Extract from user message text
-    
-    Args:
-        context: Request context dictionary
-        user_input: User's message text
-        
-    Returns:
-        Tuple of (city_name, tenant_id)
-        Example: ("Atlanta", "atlanta_ga")
-    """
-    # Priority 1: Check tenant_id in context (from dropdown)
-    tenant_id = context.get("tenant_id", "").lower()
-    if tenant_id and tenant_id != "unknown":
-        # Convert tenant_id back to city name
-        # "atlanta" -> "Atlanta"
-        city_name = tenant_id.replace("_", " ").title()
-        # Standardize tenant_id format
-        standardized_tenant_id = f"{tenant_id}_ga" if "_" not in tenant_id else tenant_id
-        logger.info(f"✅ City from context tenant_id: {city_name} ({standardized_tenant_id})")
-        return city_name, standardized_tenant_id
-    
-    # Priority 2: Check location in context
-    location = context.get("location")
-    if location:
-        city_name = location.title()
-        tenant_id = f"{location.lower().replace(' ', '_')}_ga"
-        logger.info(f"✅ City from context location: {city_name} ({tenant_id})")
-        return city_name, tenant_id
-    
-    # Priority 3: Fall back to extracting from message
-    city_name = extract_city_name(user_input)
-    tenant_id = f"{city_name.lower().replace(' ', '_')}_ga"
-    logger.info(f"⚠️ City extracted from message: {city_name} ({tenant_id})")
-    return city_name, tenant_id
-
-
-# ============================================================
-# MAIN TOOL REQUEST HANDLER (ENHANCED)
-# ============================================================
-
-async def handle_tool_request(
-    user_input: str,
-    role: str = "unknown",
-    lat: Optional[float] = None,
-    lon: Optional[float] = None,
-    context: Optional[Dict[str, Any]] = 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)
-        context: Request context with tenant_id, location, etc. (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,
-            context={"tenant_id": "atlanta"}
-        )
-    """
-    global _tool_request_count
-    _tool_request_count += 1
-    
-    start_time = time.time()
-    
-    # Initialize context if not provided
-    if context is None:
-        context = {}
-    
-    # Sanitize input for logging (PII protection)
-    safe_input = sanitize_for_logging(user_input)
-    logger.info(f"🛠️ Tool request #{_tool_request_count}: '{safe_input[:50]}...'")
-    logger.info(f"📍 Context: {context}")
-    
-    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()
-        
-        # 🔥 NEW: Get city from context first, then fall back to message
-        city_name, tenant_id = get_city_from_context(context, user_input)
-        
-        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 with context",
-            "input": "What's the weather?",
-            "lat": 33.7490,
-            "lon": -84.3880,
-            "context": {"tenant_id": "atlanta"}
-        },
-        {
-            "name": "Events query with context",
-            "input": "show me local events",
-            "lat": None,
-            "lon": None,
-            "context": {"tenant_id": "atlanta"}
-        },
-        {
-            "name": "Trash query with context",
-            "input": "When is trash pickup?",
-            "lat": None,
-            "lon": None,
-            "context": {"tenant_id": "atlanta"}
-        }
-    ]
-    
-    async def run_tests():
-        for i, query in enumerate(test_queries, 1):
-            print(f"\n--- Test {i}: {query['name']} ---")
-            print(f"Query: {query['input']}")
-            print(f"Context: {query.get('context', {})}")
-            
-            try:
-                result = await handle_tool_request(
-                    user_input=query["input"],
-                    role="test_user",
-                    lat=query.get("lat"),
-                    lon=query.get("lon"),
-                    context=query.get("context", {})
-                )
-                
-                print(f"Tool: {result.get('tool')}")
-                print(f"City: {result.get('city')}")
-                print(f"Tenant ID: {result.get('tenant_id')}")
-                
-                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)