Delete app/intents.py

app/intents.py

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