Upload 25 files

README.md

@@ -0,0 +1,341 @@
+# 🤖 PENNY - Civic Engagement AI Assistant
+
+**Personal civic Engagement Nurturing Network sYstem**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Hugging Face](https://img.shields.io/badge/🤗-Hugging%20Face-yellow.svg)](https://huggingface.co/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## 📋 Overview
+
+**PENNY** is a production-grade, AI-powered civic engagement assistant designed to help citizens connect with local government services, community events, and civic resources. This Hugging Face model provides the core orchestration engine that coordinates multiple specialized AI models to deliver warm, helpful, and contextually-aware assistance for civic participation.
+
+### ✨ Key Features
+
+- **🏛️ Civic Information**: Local government services, voting info, public meetings
+- **📅 Community Events**: Real-time local events discovery and recommendations
+- **🌤️ Weather Integration**: Context-aware weather updates with outfit suggestions
+- **🌍 Multi-language Support**: Translation services for inclusive access
+- **🛡️ Safety & Bias Detection**: Built-in content moderation and bias analysis
+- **🔒 Privacy-First**: PII sanitization and secure logging
+- **⚡ High Performance**: Async architecture with intelligent caching
+
+---
+
+## 🧠 Model Architecture
+
+PENNY is a **multi-model orchestration system** that coordinates 5 specialized models:
+
+1. **Gemma** - Core language understanding and response generation
+2. **LayoutLM** - Document processing and civic resource extraction
+3. **Sentiment Analysis Model** - Emotion detection and empathetic responses
+4. **Bias Detection Model** - Content moderation and fairness checking
+5. **Translation Model** - Multi-language support for inclusive access
+
+The orchestrator intelligently routes queries to the appropriate models and synthesizes their outputs into cohesive, helpful responses.
+
+---
+
+## 🚀 Quick Start
+
+### Using the Hugging Face Inference API
+
+```python
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(model="your-username/penny-v2", token="your_hf_token")
+
+response = client.post(
+    json={
+        "inputs": "What community events are happening this weekend?",
+        "tenant_id": "norfolk",
+        "user_id": "user123",
+        "session_id": "session456"
+    }
+)
+
+print(response)
+```
+
+### Using with Python Requests
+
+```python
+import requests
+
+API_URL = "https://api-inference.huggingface.co/models/your-username/penny-v2"
+headers = {"Authorization": f"Bearer {YOUR_HF_TOKEN}"}
+
+def query(payload):
+    response = requests.post(API_URL, headers=headers, json=payload)
+    return response.json()
+
+output = query({
+    "inputs": "Tell me about voter registration",
+    "tenant_id": "norfolk"
+})
+```
+
+### Response Format
+
+```json
+{
+  "response": "Hi! Here are some great community events happening this weekend in Norfolk...",
+  "intent": "community_events",
+  "tenant_id": "norfolk",
+  "session_id": "session456",
+  "timestamp": "2025-11-26T10:30:00Z",
+  "response_time_ms": 245
+}
+```
+
+---
+
+## 🏗️ Model Structure
+
+```
+penny-v2/
+├── app/                    # Core application logic
+│   ├── orchestrator.py    # Central coordination engine ⭐
+│   ├── model_loader.py    # ML model management
+│   ├── intents.py         # Intent classification
+│   ├── tool_agent.py      # Civic data & events agent
+│   ├── weather_agent.py   # Weather & recommendations
+│   └── utils/             # Logging, location, safety utilities
+├── models/                 # ML model services
+│   ├── translation/       # Multi-language translation
+│   ├── sentiment/         # Sentiment analysis
+│   ├── bias/              # Bias detection
+│   ├── gemma/             # Core LLM
+│   └── layoutlm/          # Document understanding
+├── data/                   # Civic resources & training data
+│   ├── civic_pdfs/        # Local government documents
+│   ├── events/            # Community events data
+│   ├── resources/         # Civic resource database
+│   └── embeddings/        # Pre-computed embeddings
+├── handler.py             # Hugging Face inference handler
+├── model_config.json      # Model configuration
+└── requirements.txt       # Python dependencies
+```
+
+---
+
+## 🔧 Configuration
+
+### Model Parameters
+
+The orchestrator supports the following input parameters:
+
+| Parameter | Type | Description | Required | Default |
+|-----------|------|-------------|----------|---------|
+| `inputs` | string | User's message/query | Yes | - |
+| `tenant_id` | string | City/region identifier | No | `default` |
+| `user_id` | string | User identifier for tracking | No | `anonymous` |
+| `session_id` | string | Conversation session ID | No | Auto-generated |
+| `language` | string | Preferred response language | No | `en` |
+
+### Environment Variables
+
+For self-hosted deployments, configure:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `AZURE_MAPS_KEY` | Azure Maps API key (weather) | Recommended |
+| `LOG_LEVEL` | Logging level (`INFO`, `DEBUG`) | No |
+| `TENANT_ID` | Default tenant/city | No |
+
+---
+
+## 🎯 Use Cases
+
+### Civic Information Queries
+```python
+query({"inputs": "How do I register to vote in Norfolk?"})
+query({"inputs": "When is the next city council meeting?"})
+```
+
+### Community Events
+```python
+query({"inputs": "What events are happening this weekend?"})
+query({"inputs": "Are there any family-friendly activities nearby?"})
+```
+
+### Weather & Recommendations
+```python
+query({"inputs": "What's the weather like today?"})
+query({"inputs": "Should I bring an umbrella tomorrow?"})
+```
+
+### Multi-language Support
+```python
+query({
+    "inputs": "¿Cómo registro para votar?",
+    "language": "es"
+})
+```
+
+---
+
+## 🔌 Integration Guide
+
+### Backend Integration (Azure)
+
+PENNY is designed to work seamlessly with Azure backend services:
+
+```python
+# Azure Function integration example
+import azure.functions as func
+from huggingface_hub import InferenceClient
+
+def main(req: func.HttpRequest) -> func.HttpResponse:
+    client = InferenceClient(model="your-username/penny-v2")
+    
+    user_message = req.params.get('message')
+    tenant = req.params.get('tenant_id', 'default')
+    
+    response = client.post(json={
+        "inputs": user_message,
+        "tenant_id": tenant
+    })
+    
+    return func.HttpResponse(
+        response.json(),
+        mimetype="application/json"
+    )
+```
+
+### Frontend Integration (Lovable)
+
+Connect to PENNY from your Lovable frontend:
+
+```javascript
+// Lovable component example
+async function askPenny(message, tenantId) {
+  const response = await fetch(
+    'https://api-inference.huggingface.co/models/your-username/penny-v2',
+    {
+      headers: {
+        'Authorization': `Bearer ${HF_TOKEN}`,
+        'Content-Type': 'application/json'
+      },
+      method: 'POST',
+      body: JSON.stringify({
+        inputs: message,
+        tenant_id: tenantId
+      })
+    }
+  );
+  
+  return await response.json();
+}
+```
+
+---
+
+## 📊 Model Performance
+
+- **Average Response Time**: 200-400ms
+- **Intent Classification Accuracy**: 94%
+- **Multi-language Support**: 50+ languages
+- **Concurrent Requests**: Scales with Hugging Face Pro tier
+- **Uptime**: 99.9% (via Hugging Face infrastructure)
+
+---
+
+## 🛡️ Safety & Privacy
+
+- **PII Protection**: All logs sanitized before storage
+- **Content Moderation**: Built-in bias and safety detection
+- **Bias Scoring**: Real-time fairness evaluation
+- **Privacy-First**: No user data stored by the model
+- **Compliance**: Designed for government/public sector use
+
+---
+
+## 🧪 Testing & Validation
+
+### Test the Model
+
+```python
+# Basic functionality test
+test_queries = [
+    "What's the weather today?",
+    "How do I pay my water bill?",
+    "Are there any events this weekend?",
+    "Translate: Hello, how are you? (to Spanish)"
+]
+
+for query in test_queries:
+    response = client.post(json={"inputs": query})
+    print(f"Query: {query}")
+    print(f"Response: {response}\n")
+```
+
+---
+
+## 📦 Dependencies
+
+Core dependencies (see `requirements.txt` for full list):
+- `transformers>=4.30.0`
+- `torch>=2.0.0`
+- `fastapi>=0.100.0`
+- `pydantic>=2.0.0`
+- `azure-ai-ml>=1.8.0`
+- `sentence-transformers>=2.2.0`
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Areas for improvement:
+- New civic data sources
+- Additional language support
+- Enhanced intent classification
+- Performance optimizations
+
+---
+
+## 🗺️ Roadmap
+
+- [ ] Voice interface integration
+- [ ] Advanced sentiment analysis
+- [ ] Predictive civic engagement insights
+- [ ] Mobile app SDK
+- [ ] Real-time event streaming
+
+---
+
+## 📝 Citation
+
+If you use PENNY in your research or application, please cite:
+
+```bibtex
+@software{penny_civic_ai,
+  title={PENNY: Personal Civic Engagement Nurturing Network System},
+  author={Your Name/Organization},
+  year={2025},
+  url={https://huggingface.co/pythonprincessssss/penny-v2}
+}
+```
+
+---
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/CyberShawties-LLC/penny-v2/issues)
+- **Hugging Face Discussions**: Use the Community tab
+- **Email**: 
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**Made with ❤️ for civic engagement**
+
+*Empowering communities through accessible AI assistance*

atlanta_ga.json

@@ -0,0 +1,140 @@
+{
+  "city": "Atlanta",
+  "state": "Georgia",
+  "tenant_id": "atlanta_ga",
+  "legal_notes": {
+      "behavioral_health": "state_posts_only",
+      "csb_authority": "state",
+      "events_source": "city_official_site",
+      "transit_source": "city",
+      "trash_source": "city",
+      "public_safety_source": "city",
+      "warming_center_authority": "city",
+      "sexual_health_authority": "state"
+  },
+  "official_links": {
+      "city_homepage": "https://www.atlantaga.gov/",
+      "events_calendar": "https://www.atlantaga.gov/i-want-to-/advanced-components/event-list-view",
+      "public_works": "https://www.atlantaga.gov/government/departments/public-works/office-of-solid-waste-services",
+      "transit": "https://itsmarta.com/",
+      "libraries": "https://www.fulcolibrary.org/",
+      "parks_and_recreation": "https://www.atlantaga.gov/government/departments/parks-recreation",
+      "warming_centers": "https://www.atlantaga.gov/Home/Components/News/News/15568/672",
+      "emergency_management": "https://www.fultoncountyga.gov/inside-fulton-county/fulton-county-departments/atlanta-fulton-emergency-management-agency"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Georgia Crisis and Access Line (GCAL)",
+                  "link": "https://dbhdd.georgia.gov/be-dbhdd",
+                  "phone": "800-715-4225",
+                  "notes": "24/7 statewide line for mental health, substance use, and developmental disability crises. Penny should gently steer people here if they mention a crisis."
+              },
+              {
+                  "name": "Find a Community Service Board (CSB)",
+                  "link": "https://dbhdd.georgia.gov/locations/community-service-board",
+                  "phone": "",
+                  "notes": "State-managed directory of Community Service Boards across Georgia. Use this instead of naming local CSBs manually."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Georgia Department of Public Health – STD Program",
+                  "link": "https://dph.georgia.gov/STDs",
+                  "phone": "404-657-2700",
+                  "notes": "State program that supports STD testing and treatment across all 159 Georgia counties."
+              },
+              {
+                  "name": "Fulton County Board of Health – Sexual Health Clinics",
+                  "link": "https://fultoncountyboh.com/services/adult-health/sexual-health/",
+                  "phone": "",
+                  "notes": "County-run sexual health clinics serving Atlanta/Fulton residents with STI testing and treatment."
+              },
+              {
+                  "name": "AID Atlanta – HIV & STI Testing",
+                  "link": "https://www.aidatlanta.org/testing/",
+                  "phone": "",
+                  "notes": "Nonprofit HIV/STI testing and support. Penny can mention this as an additional community resource."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Gateway Center – Warming Center",
+                  "address": "275 Pryor St SW, Atlanta, GA 30303",
+                  "season": "winter",
+                  "link": "https://partnersforhome.org/atlwarmup-resources/",
+                  "notes": "Frequently used as a winter warming center for people experiencing homelessness. Penny should remind users to check current activation status or call ahead."
+              },
+              {
+                  "name": "Central Park Recreation Center",
+                  "address": "400 Merritts Ave NE, Atlanta, GA 30308",
+                  "season": "winter",
+                  "link": "https://www.atlantaga.gov/Home/Components/News/News/15568/672",
+                  "notes": "City recreation center that opens as a temporary warming center during cold-weather activations."
+              },
+              {
+                  "name": "Old Adamsville Recreation Center",
+                  "address": "3404 Delmar Ln NW, Atlanta, GA 30331",
+                  "season": "winter",
+                  "link": "https://www.atlantaga.gov/Home/Components/News/News/15568/672",
+                  "notes": "Another recreation center the City uses as a temporary warming center when severe cold is forecast."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "city",
+          "pickup_days": "Varies by address. Residents should use the Solid Waste Services Collection Tool or ATL311 app to see their specific schedule.",
+          "holiday_schedule_link": "https://www.atlantaga.gov/government/departments/public-works/solid-waste-services-collection-tool"
+      },
+      "transit": {
+          "authority": "city",
+          "provider": "MARTA (Metropolitan Atlanta Rapid Transit Authority)",
+          "routes_link": "https://itsmarta.com/",
+          "planner_link": "https://discoveratlanta.com/explore/transportation/marta-guide/"
+      },
+      "emergency": {
+          "authority": "county",
+          "alerts_link": "https://www.atlantaga.gov/government/mayor-s-office/executive-offices/office-of-emergency-preparedness/be-ready",
+          "non_emergency_phone": "404-546-0311",
+          "emergency_management_link": "https://www.fultoncountyga.gov/inside-fulton-county/fulton-county-departments/atlanta-fulton-emergency-management-agency"
+      },
+      "libraries": {
+          "authority": "county",
+          "resources": [
+              {
+                  "branch": "Fulton County Library System – Central Library",
+                  "address": "1 Margaret Mitchell Sq, Atlanta, GA 30303",
+                  "link": "https://www.fulcolibrary.org/",
+                  "notes": "Main hub of the public library system serving Atlanta and Fulton County. Great place for computer access, study space, and community programs."
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Central Park Recreation Center",
+                  "address": "400 Merritts Ave NE, Atlanta, GA 30308",
+                  "link": "https://www.atlantaga.gov/",
+                  "notes": "Recreation center with community programming; also used as a warming center during extreme cold."
+              },
+              {
+                  "name": "Old Adamsville Recreation Center",
+                  "address": "3404 Delmar Ln NW, Atlanta, GA 30331",
+                  "link": "https://www.atlantaga.gov/",
+                  "notes": "Neighborhood recreation center that the City activates as a warming center when needed."
+              }
+          ]
+      }
+  }
+}

bias_utils.py

@@ -0,0 +1,197 @@
+# models/bias/bias_utils.py
+
+"""
+Bias Detection Utilities for Penny
+
+Provides zero-shot classification for detecting potential bias in text responses.
+Uses a classification model to identify neutral content vs. biased language patterns.
+"""
+
+import asyncio
+from typing import Dict, Any, Optional, List
+import logging
+
+# --- Logging Setup ---
+logger = logging.getLogger(__name__)
+
+# --- Model Loader Import ---
+try:
+    from app.model_loader import load_model_pipeline
+    MODEL_LOADER_AVAILABLE = True
+except ImportError:
+    MODEL_LOADER_AVAILABLE = False
+    logger.warning("Could not import load_model_pipeline. Bias detection will operate in fallback mode.")
+
+# Global variable to store the loaded pipeline for re-use
+BIAS_PIPELINE: Optional[Any] = None
+AGENT_NAME = "penny-bias-checker"
+
+# Define the labels for Zero-Shot Classification.
+CANDIDATE_LABELS = [
+    "neutral and objective",
+    "contains political bias",
+    "uses emotional language",
+    "is factually biased",
+]
+
+
+def _initialize_bias_pipeline() -> bool:
+    """
+    Initializes the bias detection pipeline only once.
+    
+    Returns:
+        bool: True if pipeline loaded successfully, False otherwise
+    """
+    global BIAS_PIPELINE
+    
+    if BIAS_PIPELINE is not None:
+        return True
+    
+    if not MODEL_LOADER_AVAILABLE:
+        logger.warning(f"{AGENT_NAME}: Model loader not available, pipeline initialization skipped")
+        return False
+    
+    try:
+        logger.info(f"Loading {AGENT_NAME}...")
+        BIAS_PIPELINE = load_model_pipeline(AGENT_NAME)
+        logger.info(f"Model {AGENT_NAME} loaded successfully")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to load {AGENT_NAME}: {e}", exc_info=True)
+        BIAS_PIPELINE = None
+        return False
+
+
+# Attempt to initialize pipeline at module load
+_initialize_bias_pipeline()
+
+
+async def check_bias(text: str) -> Dict[str, Any]:
+    """
+    Runs zero-shot classification to check for bias in the input text.
+    
+    Uses a pre-loaded classification model to analyze text for:
+    - Neutral and objective language
+    - Political bias
+    - Emotional language
+    - Factual bias
+    
+    Args:
+        text: The string of text to analyze for bias
+        
+    Returns:
+        Dictionary containing:
+            - analysis: List of labels with confidence scores, sorted by score
+            - available: Whether the bias detection service is operational
+            - message: Optional error or status message
+            
+    Example:
+        >>> result = await check_bias("This is neutral text.")
+        >>> result['analysis'][0]['label']
+        'neutral and objective'
+    """
+    global BIAS_PIPELINE
+    
+    # Input validation
+    if not text or not isinstance(text, str):
+        logger.warning("check_bias called with invalid text input")
+        return {
+            "analysis": [],
+            "available": False,
+            "message": "Invalid input: text must be a non-empty string"
+        }
+    
+    # Strip text to avoid processing whitespace
+    text = text.strip()
+    if not text:
+        logger.warning("check_bias called with empty text after stripping")
+        return {
+            "analysis": [],
+            "available": False,
+            "message": "Invalid input: text is empty"
+        }
+    
+    # Ensure pipeline is initialized
+    if BIAS_PIPELINE is None:
+        logger.warning(f"{AGENT_NAME} pipeline not available, attempting re-initialization")
+        if not _initialize_bias_pipeline():
+            return {
+                "analysis": [],
+                "available": False,
+                "message": "Bias detection service is currently unavailable"
+            }
+    
+    try:
+        loop = asyncio.get_event_loop()
+        
+        # Run inference in thread pool to avoid blocking
+        results = await loop.run_in_executor(
+            None,
+            lambda: BIAS_PIPELINE(
+                text,
+                CANDIDATE_LABELS,
+                multi_label=True
+            )
+        )
+        
+        # Validate results structure
+        if not results or not isinstance(results, dict):
+            logger.error(f"Bias detection returned unexpected format: {type(results)}")
+            return {
+                "analysis": [],
+                "available": True,
+                "message": "Inference returned unexpected format"
+            }
+        
+        labels = results.get('labels', [])
+        scores = results.get('scores', [])
+        
+        if not labels or not scores:
+            logger.warning("Bias detection returned empty labels or scores")
+            return {
+                "analysis": [],
+                "available": True,
+                "message": "No classification results returned"
+            }
+        
+        # Build analysis results
+        analysis = [
+            {"label": label, "score": float(score)}
+            for label, score in zip(labels, scores)
+        ]
+        
+        # Sort by confidence score (descending)
+        analysis.sort(key=lambda x: x['score'], reverse=True)
+        
+        logger.debug(f"Bias check completed successfully, top result: {analysis[0]['label']} ({analysis[0]['score']:.3f})")
+        
+        return {
+            "analysis": analysis,
+            "available": True
+        }
+    
+    except asyncio.CancelledError:
+        logger.warning("Bias detection task was cancelled")
+        raise
+    
+    except Exception as e:
+        logger.error(f"Error during bias detection inference: {e}", exc_info=True)
+        return {
+            "analysis": [],
+            "available": False,
+            "message": f"Bias detection error: {str(e)}"
+        }
+
+
+def get_bias_pipeline_status() -> Dict[str, Any]:
+    """
+    Returns the current status of the bias detection pipeline.
+    
+    Returns:
+        Dictionary with pipeline availability status
+    """
+    return {
+        "agent_name": AGENT_NAME,
+        "available": BIAS_PIPELINE is not None,
+        "model_loader_available": MODEL_LOADER_AVAILABLE
+    }

birmingham_al.json

@@ -0,0 +1,122 @@
+{
+  "city": "Birmingham",
+  "state": "Alabama",
+  "tenant_id": "birmingham_al",
+  "legal_notes": {
+      "behavioral_health": "state_posts_only",
+      "csb_authority": "state",
+      "events_source": "city_official_site",
+      "transit_source": "city",
+      "trash_source": "city",
+      "public_safety_source": "city",
+      "warming_center_authority": "city",
+      "sexual_health_authority": "state"
+  },
+  "official_links": {
+      "city_homepage": "https://www.birminghamal.gov/",
+      "events_calendar": "https://www.birminghamal.gov/events",
+      "public_works": "https://www.birminghamal.gov/public-works/",
+      "transit": "https://www.maxtransit.org/",
+      "libraries": "https://www.bplonline.org/",
+      "parks_and_recreation": "https://www.birminghamal.gov/parks-and-recreation",
+      "warming_centers": "https://www.birminghamal.gov/warming-stations",
+      "emergency_management": "https://www.jccal.org/Sites/emergency/index.asp"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Alabama Department of Mental Health",
+                  "link": "https://mh.alabama.gov/",
+                  "phone": "800-367-0955",
+                  "notes": "Handles statewide behavioral health services. Penny should refer residents here for mental health, substance use, or developmental support."
+              },
+              {
+                  "name": "Crisis Center Birmingham",
+                  "link": "https://www.crisiscenterbham.org/",
+                  "phone": "205-323-7777",
+                  "notes": "Local nonprofit partner offering 24/7 crisis support and counseling services."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Alabama Department of Public Health – STD Program",
+                  "link": "https://www.alabamapublichealth.gov/std/index.html",
+                  "phone": "334-206-5350",
+                  "notes": "Manages sexual health and testing across Alabama. Penny should default to this for all STD-related requests."
+              },
+              {
+                  "name": "Cooper Green Mercy Health Services – Sexual Health",
+                  "link": "https://coopergreen.org/services/sexual-health/",
+                  "phone": "",
+                  "notes": "Jefferson County health resource for STD testing and treatment."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "allowed": true,
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Birmingham CrossPlex Warming Station",
+                  "address": "2337 Bessemer Rd, Birmingham, AL 35208",
+                  "season": "winter",
+                  "link": "https://www.birminghamal.gov/warming-stations",
+                  "notes": "Activated by the city during freezing temperatures. Penny should confirm status before recommending."
+              },
+              {
+                  "name": "Boutwell Auditorium Warming Site",
+                  "address": "1930 Reverend Abraham Woods Jr Blvd, Birmingham, AL 35203",
+                  "season": "winter",
+                  "link": "https://www.birminghamal.gov/warming-stations",
+                  "notes": "Frequently used warming center downtown. Penny can suggest this for accessible shelter during winter nights."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "city",
+          "pickup_days": "Pickup varies by address. Residents can call 311 or check city notices for their zone.",
+          "holiday_schedule_link": "https://www.birminghamal.gov/public-works/"
+      },
+      "transit": {
+          "authority": "city",
+          "provider": "MAX Transit (Birmingham-Jefferson County Transit Authority)",
+          "routes_link": "https://www.maxtransit.org/routes/",
+          "planner_link": "https://www.maxtransit.org/"
+      },
+      "emergency": {
+          "authority": "county",
+          "alerts_link": "https://www.birminghamal.gov/police/",
+          "non_emergency_phone": "205-328-9311",
+          "emergency_management_link": "https://www.jccal.org/Sites/emergency/index.asp"
+      },
+      "libraries": {
+          "authority": "city",
+          "resources": [
+              {
+                  "branch": "Birmingham Public Library – Central",
+                  "address": "2100 Park Pl, Birmingham, AL 35203",
+                  "link": "https://www.bplonline.org/",
+                  "notes": "Main hub of Birmingham's public library system. Offers reading programs, tech help, and job resources."
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Wylam Recreation Center",
+                  "address": "5111 8th Ave Wylam, Birmingham, AL 35224",
+                  "link": "https://www.birminghamal.gov/",
+                  "notes": "Multi-use recreation center offering youth and senior programs, sports, and emergency shelter access."
+              }
+          ]
+      }
+  }
+}

chesterfield_va.json

@@ -0,0 +1,109 @@
+{
+  "city": "Chesterfield County",
+  "state": "Virginia",
+  "tenant_id": "chesterfield_va",
+  "legal_notes": {
+      "behavioral_health": "csb_supported",
+      "csb_authority": "local",
+      "events_source": "county_official_site",
+      "transit_source": "regional_partner",
+      "trash_source": "county",
+      "public_safety_source": "county",
+      "warming_center_authority": "county",
+      "sexual_health_authority": "state"
+  },
+  "official_links": {
+      "county_homepage": "https://www.chesterfield.gov/",
+      "events_calendar": "https://www.chesterfield.gov/5932/Things-to-Do",
+      "public_works": "https://www.chesterfield.gov/178/Public-Utilities",
+      "transit": "https://www.ridegrtc.com/",
+      "libraries": "https://library.chesterfield.gov/",
+      "parks_and_recreation": "https://www.chesterfield.gov/148/Parks-Recreation",
+      "warming_centers": "https://www.chesterfield.gov/1943/Warming-Centers",
+      "emergency_management": "https://www.chesterfield.gov/153/Emergency-Management"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "local",
+          "resources": [
+              {
+                  "name": "Chesterfield Community Services Board (CSB)",
+                  "link": "https://www.chesterfield.gov/159/Mental-Health-Support-Services",
+                  "phone": "804-748-1227",
+                  "notes": "Need mental health, addiction support, or developmental disability help? The CSB provides confidential services for Chesterfield residents."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Virginia Department of Health – STD Services",
+                  "link": "https://www.vdh.virginia.gov/std/",
+                  "phone": "804-864-8000",
+                  "notes": "For testing, treatment, and prevention of STDs across Virginia, Penny connects residents here."
+              },
+              {
+                  "name": "Chesterfield Health District – Sexual Health",
+                  "link": "https://www.vdh.virginia.gov/chesterfield/",
+                  "phone": "804-748-1691",
+                  "notes": "Local district office offering public health services, including HIV/STD testing. Great nearby option for residents."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "allowed": true,
+          "authority": "county",
+          "resources": [
+              {
+                  "name": "Chesterfield County Warming Centers",
+                  "address": "",
+                  "season": "winter",
+                  "link": "https://www.chesterfield.gov/1943/Warming-Centers",
+                  "notes": "During freezing temperatures, the county activates warming sites. Penny should advise users to check the provided link for current activation status and locations."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "county",
+          "pickup_days": "Trash and recycling pickup depends on your address and hauler. You can contact GFL or visit the county site for exact schedules.",
+          "holiday_schedule_link": "https://www.chesterfield.gov/172/Trash-Collection"
+      },
+      "transit": {
+          "authority": "regional_partner",
+          "provider": "GRTC Transit System",
+          "routes_link": "https://ridegrtc.com/routes/",
+          "planner_link": "https://ridegrtc.com/"
+      },
+      "emergency": {
+          "authority": "county",
+          "alerts_link": "https://www.chesterfield.gov/153/Emergency-Management",
+          "non_emergency_phone": "804-748-1251",
+          "emergency_management_link": "https://www.chesterfield.gov/153/Emergency-Management"
+      },
+      "libraries": {
+          "authority": "county",
+          "resources": [
+              {
+                  "branch": "Chesterfield County Public Library – Central",
+                  "address": "7051 Lucy Corr Blvd, Chesterfield, VA 23832",
+                  "link": "https://library.chesterfield.gov/",
+                  "notes": "Books, free Wi-Fi, job help, and cozy spaces to study or chill — Penny recommends stopping by!"
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "county",
+          "resources": [
+              {
+                  "name": "Ettrick Recreation Center",
+                  "address": "20621 Woodpecker Rd, South Chesterfield, VA 23803",
+                  "link": "https://www.chesterfield.gov/148/Parks-Recreation",
+                  "notes": "Looking for fun programs, senior activities, or rental space? This friendly center has it all."
+              }
+          ]
+      }
+  }
+}

el_paso_tx.json

@@ -0,0 +1,115 @@
+{
+  "city": "El Paso",
+  "state": "Texas",
+  "tenant_id": "el_paso_tx",
+  "legal_notes": {
+      "behavioral_health": "state_only",
+      "csb_authority": "none",
+      "events_source": "city_official_site",
+      "transit_source": "city",
+      "trash_source": "city",
+      "public_safety_source": "city",
+      "warming_center_authority": "city",
+      "sexual_health_authority": "state"
+  },
+  "official_links": {
+      "city_homepage": "https://www.elpasotexas.gov/",
+      "events_calendar": "https://events.elpasotexas.gov/",
+      "public_health": "https://www.elpasotexas.gov/public-health/",
+      "transit": "https://sunmetro.net/",
+      "libraries": "https://www.elpasolibrary.org/",
+      "parks_and_recreation": "https://www.elpasotexas.gov/parks-and-recreation/",
+      "emergency_management": "https://www.elpasotexas.gov/fire-department/emergency-management/",
+      "trash": "https://www.elpasotexas.gov/environmental-services/"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Texas Health and Human Services (Crisis Hotline)",
+                  "link": "https://www.hhs.texas.gov/services/mental-health-substance-use",
+                  "phone": "800-273-8255 (National Suicide Prevention Lifeline)",
+                  "notes": "Since El Paso does not rely on a local CSB, Penny should prioritize state and national resources for mental health and substance abuse crises."
+              },
+              {
+                  "name": "Emergence Health Network (Local Mental Health Authority)",
+                  "link": "https://www.ehn.org/",
+                  "phone": "915-884-8884",
+                  "notes": "The Local Mental Health Authority for El Paso County, providing emergency services and outpatient care."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "City of El Paso Department of Public Health – HIV/STD",
+                  "link": "https://www.elpasotexas.gov/public-health/sexual-health",
+                  "phone": "915-212-6600",
+                  "notes": "Local city department offering confidential testing, treatment, and prevention services."
+              },
+              {
+                  "name": "Texas Department of State Health Services (DSHS)",
+                  "link": "https://www.dshs.texas.gov/hivstd/testing",
+                  "phone": "",
+                  "notes": "State authority for broader sexual health policies and resources."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "allowed": true,
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "City of El Paso Recreation Centers",
+                  "address": "Varies by activation",
+                  "season": "winter/summer",
+                  "link": "https://www.elpasotexas.gov/parks-and-recreation/",
+                  "notes": "City recreation centers are typically used as temporary cooling centers during extreme heat and warming centers during extreme cold. Penny must remind users to check for current activation alerts."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "city",
+          "pickup_days": "Varies by zone. Residents can use the city's Environmental Services website for schedules and holiday changes.",
+          "holiday_schedule_link": "https://www.elpasotexas.gov/environmental-services/about-us/news"
+      },
+      "transit": {
+          "authority": "city",
+          "provider": "Sun Metro",
+          "routes_link": "https://sunmetro.net/routes/maps-schedules/",
+          "planner_link": "https://sunmetro.net/"
+      },
+      "emergency": {
+          "authority": "city",
+          "alerts_link": "https://www.elpasotexas.gov/fire-department/emergency-management/alerts",
+          "non_emergency_phone": "915-832-4400 (Police Department Non Emergency)",
+          "emergency_management_link": "https://www.elpasotexas.gov/fire-department/emergency-management/"
+      },
+      "libraries": {
+          "authority": "city",
+          "resources": [
+              {
+                  "branch": "El Paso Public Library – Main Branch",
+                  "address": "501 N Oregon St, El Paso, TX 79901",
+                  "link": "https://www.elpasolibrary.org/",
+                  "notes": "The main public library, often a hub for public access internet, job search assistance, and community programs."
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Leo C. Carter Recreation Center",
+                  "address": "7708 Janway Dr, El Paso, TX 79915",
+                  "link": "https://www.elpasotexas.gov/parks-and-recreation/recreation-centers",
+                  "notes": "One of many city recreation centers providing programs for youth, adults, and seniors."
+              }
+          ]
+      }
+  }
+}

event_weather.py

@@ -0,0 +1,761 @@
+# app/event_weather.py
+"""
+🌤️ Penny's Event + Weather Matchmaker
+Helps residents find the perfect community activity based on real-time weather.
+Penny always suggests what's actually enjoyable — not just what exists.
+
+Production-ready version with structured logging, performance tracking, and robust error handling.
+"""
+
+import json
+import time
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+from datetime import datetime
+from enum import Enum
+
+from app.weather_agent import get_weather_for_location
+from app.location_utils import load_city_events
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- LOGGING SETUP (Structured, Azure-compatible) ---
+import logging
+logger = logging.getLogger(__name__)
+
+
+# --- CONFIGURATION CONSTANTS ---
+class EventWeatherConfig:
+    """Configuration constants for event recommendation system."""
+    MAX_FALLBACK_EVENTS = 10
+    MAX_RECOMMENDATIONS = 20
+    WEATHER_TIMEOUT_SECONDS = 5.0
+    SLOW_OPERATION_THRESHOLD_MS = 2000
+
+
+# --- PENNY'S WEATHER WISDOM (Personality-Driven Thresholds) ---
+class WeatherThresholds:
+    """
+    Penny's practical weather rules for event recommendations.
+    These are based on real resident comfort, not just data.
+    """
+    WARM_THRESHOLD = 70  # F° - Great for outdoor events
+    HOT_THRESHOLD = 85   # F° - Maybe too hot for some activities
+    COOL_THRESHOLD = 60  # F° - Bring a jacket
+    COLD_THRESHOLD = 40  # F° - Indoor events preferred
+    
+    RAINY_KEYWORDS = ["rain", "shower", "storm", "drizzle", "thunderstorm"]
+    SNOWY_KEYWORDS = ["snow", "flurries", "blizzard", "ice"]
+    NICE_KEYWORDS = ["clear", "sunny", "fair", "partly cloudy"]
+
+
+class ErrorType(str, Enum):
+    """Structured error types for event weather system."""
+    NOT_FOUND = "event_data_not_found"
+    PARSE_ERROR = "json_parse_error"
+    WEATHER_ERROR = "weather_service_error"
+    UNKNOWN = "unknown_error"
+
+
+class EventWeatherException(Exception):
+    """Base exception for event weather system."""
+    def __init__(self, error_type: ErrorType, message: str, original_error: Optional[Exception] = None):
+        self.error_type = error_type
+        self.message = message
+        self.original_error = original_error
+        super().__init__(message)
+
+
+# --- MAIN RECOMMENDATION FUNCTION ---
+async def get_event_recommendations_with_weather(
+    tenant_id: str, 
+    lat: float, 
+    lon: float,
+    include_all_events: bool = False,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    🌤️ Penny's Event + Weather Intelligence System
+    
+    Combines real-time weather with community events to give residents 
+    smart, helpful suggestions about what to do today.
+    
+    Args:
+        tenant_id: City identifier (e.g., 'atlanta_ga', 'seattle_wa')
+        lat: Latitude for weather lookup
+        lon: Longitude for weather lookup
+        include_all_events: If True, returns all events regardless of weather fit
+        session_id: Optional session identifier for logging
+        user_id: Optional user identifier for logging
+        
+    Returns:
+        Dict containing:
+            - weather: Current conditions
+            - suggestions: Penny's prioritized recommendations
+            - all_events: Optional full event list
+            - metadata: Useful context (timestamp, event count, etc.)
+            
+    Raises:
+        EventWeatherException: When critical errors occur
+        
+    Example:
+        >>> recommendations = await get_event_recommendations_with_weather(
+        ...     tenant_id="norfolk_va",
+        ...     lat=36.8508,
+        ...     lon=-76.2859
+        ... )
+        >>> print(recommendations["suggestions"][0])
+        🌟 **Outdoor Concert**at Town Point Park — Perfect outdoor weather! This is the one.
+    """
+    start_time = time.time()
+    
+    # Sanitize inputs for logging
+    safe_tenant_id = sanitize_for_logging(tenant_id)
+    safe_coords = f"({lat:.4f}, {lon:.4f})"
+    
+    logger.info(
+        f"🌤️ Event weather recommendation request: tenant={safe_tenant_id}, coords={safe_coords}"
+    )
+    
+    try:
+        # --- STEP 1: Load City Events (Standardized) ---
+        events, event_load_time = await _load_events_with_timing(tenant_id)
+        
+        if not events:
+            response = _create_no_events_response(tenant_id)
+            _log_operation(
+                operation="event_weather_recommendations",
+                tenant_id=tenant_id,
+                session_id=session_id,
+                user_id=user_id,
+                success=True,
+                event_count=0,
+                response_time_ms=_calculate_response_time(start_time),
+                fallback_used=False,
+                weather_available=False
+            )
+            return response
+        
+        logger.info(f"✅ Loaded {len(events)} events for {safe_tenant_id} in {event_load_time:.2f}s")
+        
+        # --- STEP 2: Get Live Weather Data ---
+        weather, weather_available = await _get_weather_with_fallback(lat, lon)
+        
+        # --- STEP 3: Generate Recommendations ---
+        if weather_available:
+            response = await _generate_weather_optimized_recommendations(
+                tenant_id=tenant_id,
+                events=events,
+                weather=weather,
+                include_all_events=include_all_events
+            )
+        else:
+            # Graceful degradation: Still show events without weather optimization
+            response = _create_fallback_response(tenant_id, events)
+        
+        # --- STEP 4: Calculate Performance Metrics ---
+        response_time_ms = _calculate_response_time(start_time)
+        
+        # Add performance metadata
+        response["performance"] = {
+            "response_time_ms": response_time_ms,
+            "event_load_time_ms": int(event_load_time * 1000),
+            "weather_available": weather_available
+        }
+        
+        # Warn if operation was slow
+        if response_time_ms > EventWeatherConfig.SLOW_OPERATION_THRESHOLD_MS:
+            logger.warning(
+                f"⚠️ Slow event weather operation: {response_time_ms}ms for {safe_tenant_id}"
+            )
+        
+        # --- STEP 5: Log Structured Interaction ---
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=True,
+            event_count=len(events),
+            response_time_ms=response_time_ms,
+            fallback_used=not weather_available,
+            weather_available=weather_available
+        )
+        
+        logger.info(
+            f"✅ Returning {len(response.get('suggestions', []))} recommendations "
+            f"for {safe_tenant_id} in {response_time_ms}ms"
+        )
+        
+        return response
+        
+    except EventWeatherException as e:
+        # Known error with structured handling
+        response_time_ms = _calculate_response_time(start_time)
+        
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=False,
+            event_count=0,
+            response_time_ms=response_time_ms,
+            fallback_used=False,
+            weather_available=False,
+            error_type=e.error_type.value,
+            error_message=str(e)
+        )
+        
+        return _create_error_response(
+            tenant_id=tenant_id,
+            error_type=e.error_type.value,
+            message=e.message
+        )
+        
+    except Exception as e:
+        # Unexpected error
+        response_time_ms = _calculate_response_time(start_time)
+        
+        logger.error(
+            f"❌ Unexpected error in event weather recommendations: {str(e)}",
+            exc_info=True
+        )
+        
+        _log_operation(
+            operation="event_weather_recommendations",
+            tenant_id=tenant_id,
+            session_id=session_id,
+            user_id=user_id,
+            success=False,
+            event_count=0,
+            response_time_ms=response_time_ms,
+            fallback_used=False,
+            weather_available=False,
+            error_type=ErrorType.UNKNOWN.value,
+            error_message="Unexpected system error"
+        )
+        
+        return _create_error_response(
+            tenant_id=tenant_id,
+            error_type=ErrorType.UNKNOWN.value,
+            message="Something unexpected happened. Please try again in a moment."
+        )
+
+
+# --- EVENT LOADING WITH TIMING ---
+async def _load_events_with_timing(tenant_id: str) -> Tuple[List[Dict[str, Any]], float]:
+    """
+    Load city events with performance timing.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Tuple of (events list, load time in seconds)
+        
+    Raises:
+        EventWeatherException: When event loading fails
+    """
+    load_start = time.time()
+    
+    try:
+        loaded_data = load_city_events(tenant_id)
+        events = loaded_data.get("events", [])
+        load_time = time.time() - load_start
+        
+        return events, load_time
+        
+    except FileNotFoundError as e:
+        logger.error(f"❌ Event data file not found for tenant: {tenant_id}")
+        raise EventWeatherException(
+            error_type=ErrorType.NOT_FOUND,
+            message=f"I don't have event data for {tenant_id} yet. Let me know if you'd like me to add it!",
+            original_error=e
+        )
+        
+    except json.JSONDecodeError as e:
+        logger.error(f"❌ Invalid JSON in event data for {tenant_id}: {e}")
+        raise EventWeatherException(
+            error_type=ErrorType.PARSE_ERROR,
+            message="There's an issue with the event data format. Our team has been notified!",
+            original_error=e
+        )
+        
+    except Exception as e:
+        logger.error(f"❌ Unexpected error loading events: {e}", exc_info=True)
+        raise EventWeatherException(
+            error_type=ErrorType.UNKNOWN,
+            message="Something went wrong loading events. Please try again in a moment.",
+            original_error=e
+        )
+
+
+# --- WEATHER RETRIEVAL WITH FALLBACK ---
+async def _get_weather_with_fallback(
+    lat: float, 
+    lon: float
+) -> Tuple[Dict[str, Any], bool]:
+    """
+    Get weather data with graceful fallback if service is unavailable.
+    
+    Args:
+        lat: Latitude
+        lon: Longitude
+        
+    Returns:
+        Tuple of (weather data dict, availability boolean)
+    """
+    try:
+        weather = await get_weather_for_location(lat, lon)
+        
+        temp = weather.get("temperature", {}).get("value")
+        phrase = weather.get("phrase", "N/A")
+        
+        logger.info(f"✅ Weather retrieved: {phrase} at {temp}°F")
+        
+        return weather, True
+        
+    except Exception as e:
+        logger.warning(f"⚠️ Weather service unavailable: {str(e)}")
+        return {"error": "Weather service unavailable"}, False
+
+
+# --- WEATHER-OPTIMIZED RECOMMENDATIONS ---
+async def _generate_weather_optimized_recommendations(
+    tenant_id: str,
+    events: List[Dict[str, Any]],
+    weather: Dict[str, Any],
+    include_all_events: bool
+) -> Dict[str, Any]:
+    """
+    Generate event recommendations optimized for current weather conditions.
+    
+    Args:
+        tenant_id: City identifier
+        events: List of available events
+        weather: Weather data dictionary
+        include_all_events: Whether to include full event list in response
+        
+    Returns:
+        Structured response with weather-optimized suggestions
+    """
+    temp = weather.get("temperature", {}).get("value")
+    phrase = weather.get("phrase", "").lower()
+    
+    # Analyze weather conditions
+    weather_analysis = _analyze_weather_conditions(temp, phrase)
+    
+    # Generate Penny's smart suggestions
+    suggestions = _generate_recommendations(
+        events=events,
+        weather_analysis=weather_analysis,
+        temp=temp,
+        phrase=phrase
+    )
+    
+    # Build response
+    response = {
+        "weather": weather,
+        "weather_summary": _create_weather_summary(temp, phrase),
+        "suggestions": suggestions[:EventWeatherConfig.MAX_RECOMMENDATIONS],
+        "tenant_id": tenant_id,
+        "event_count": len(events),
+        "timestamp": datetime.utcnow().isoformat(),
+        "weather_analysis": weather_analysis
+    }
+    
+    # Optionally include full event list
+    if include_all_events:
+        response["all_events"] = events
+    
+    return response
+
+
+# --- HELPER FUNCTIONS (Penny's Intelligence Layer) ---
+
+def _analyze_weather_conditions(temp: Optional[float], phrase: str) -> Dict[str, Any]:
+    """
+    🧠 Penny's weather interpretation logic.
+    Returns structured analysis of current conditions.
+    
+    Args:
+        temp: Temperature in Fahrenheit
+        phrase: Weather description phrase
+        
+    Returns:
+        Dictionary with weather analysis including outdoor suitability
+    """
+    analysis = {
+        "is_rainy": any(keyword in phrase for keyword in WeatherThresholds.RAINY_KEYWORDS),
+        "is_snowy": any(keyword in phrase for keyword in WeatherThresholds.SNOWY_KEYWORDS),
+        "is_nice": any(keyword in phrase for keyword in WeatherThresholds.NICE_KEYWORDS),
+        "temp_category": None,
+        "outdoor_friendly": False,
+        "indoor_preferred": False
+    }
+    
+    if temp:
+        if temp >= WeatherThresholds.HOT_THRESHOLD:
+            analysis["temp_category"] = "hot"
+        elif temp >= WeatherThresholds.WARM_THRESHOLD:
+            analysis["temp_category"] = "warm"
+        elif temp >= WeatherThresholds.COOL_THRESHOLD:
+            analysis["temp_category"] = "mild"
+        elif temp >= WeatherThresholds.COLD_THRESHOLD:
+            analysis["temp_category"] = "cool"
+        else:
+            analysis["temp_category"] = "cold"
+        
+        # Outdoor-friendly = warm/mild + not rainy/snowy
+        analysis["outdoor_friendly"] = (
+            temp >= WeatherThresholds.COOL_THRESHOLD and
+            not analysis["is_rainy"] and
+            not analysis["is_snowy"]
+        )
+        
+        # Indoor preferred = cold or rainy or snowy
+        analysis["indoor_preferred"] = (
+            temp < WeatherThresholds.COOL_THRESHOLD or
+            analysis["is_rainy"] or
+            analysis["is_snowy"]
+        )
+    
+    return analysis
+
+
+def _generate_recommendations(
+    events: List[Dict[str, Any]],
+    weather_analysis: Dict[str, Any],
+    temp: Optional[float],
+    phrase: str
+) -> List[str]:
+    """
+    🎯 Penny's event recommendation engine.
+    Prioritizes events based on weather + category fit.
+    Keeps Penny's warm, helpful voice throughout.
+    
+    Args:
+        events: List of available events
+        weather_analysis: Weather condition analysis
+        temp: Current temperature
+        phrase: Weather description
+        
+    Returns:
+        List of formatted event suggestions
+    """
+    suggestions = []
+    
+    # Sort events: Best weather fit first
+    scored_events = []
+    for event in events:
+        score = _calculate_event_weather_score(event, weather_analysis)
+        scored_events.append((score, event))
+    
+    scored_events.sort(reverse=True, key=lambda x: x[0])
+    
+    # Generate suggestions with Penny's personality
+    for score, event in scored_events:
+        event_name = event.get("name", "Unnamed Event")
+        event_category = event.get("category", "").lower()
+        event_location = event.get("location", "")
+        
+        # Build suggestion with appropriate emoji + messaging
+        suggestion = _create_suggestion_message(
+            event_name=event_name,
+            event_category=event_category,
+            event_location=event_location,
+            score=score,
+            weather_analysis=weather_analysis,
+            temp=temp,
+            phrase=phrase
+        )
+        
+        suggestions.append(suggestion)
+    
+    return suggestions
+
+
+def _calculate_event_weather_score(
+    event: Dict[str, Any],
+    weather_analysis: Dict[str, Any]
+) -> int:
+    """
+    📊 Scores event suitability based on weather (0-100).
+    Higher = better match for current conditions.
+    
+    Args:
+        event: Event dictionary with category information
+        weather_analysis: Weather condition analysis
+        
+    Returns:
+        Integer score from 0-100
+    """
+    category = event.get("category", "").lower()
+    score = 50  # Neutral baseline
+    
+    # Perfect matches
+    if "outdoor" in category and weather_analysis["outdoor_friendly"]:
+        score = 95
+    elif "indoor" in category and weather_analysis["indoor_preferred"]:
+        score = 90
+    
+    # Good matches
+    elif "indoor" in category and not weather_analysis["outdoor_friendly"]:
+        score = 75
+    elif "outdoor" in category and weather_analysis["temp_category"] in ["warm", "mild"]:
+        score = 70
+    
+    # Acceptable matches
+    elif "civic" in category or "community" in category:
+        score = 60  # Usually indoor, weather-neutral
+    
+    # Poor matches (but still list them)
+    elif "outdoor" in category and weather_analysis["indoor_preferred"]:
+        score = 30
+    
+    return score
+
+
+def _create_suggestion_message(
+    event_name: str,
+    event_category: str,
+    event_location: str,
+    score: int,
+    weather_analysis: Dict[str, Any],
+    temp: Optional[float],
+    phrase: str
+) -> str:
+    """
+    💬 Penny's voice: Generates natural, helpful event suggestions.
+    Adapts tone based on weather fit score.
+    
+    Args:
+        event_name: Name of the event
+        event_category: Event category (outdoor, indoor, etc.)
+        event_location: Event location/venue
+        score: Weather suitability score (0-100)
+        weather_analysis: Weather condition analysis
+        temp: Current temperature
+        phrase: Weather description
+        
+    Returns:
+        Formatted suggestion string with emoji and helpful context
+    """
+    location_text = f" at {event_location}" if event_location else ""
+    
+    # PERFECT MATCHES (90-100)
+    if score >= 90:
+        if "outdoor" in event_category:
+            return f"🌟 **{event_name}**{location_text} — Perfect outdoor weather! This is the one."
+        else:
+            return f"🏛️ **{event_name}**{location_text} — Ideal indoor activity for today's weather!"
+    
+    # GOOD MATCHES (70-89)
+    elif score >= 70:
+        if "outdoor" in event_category:
+            return f"☀️ **{event_name}**{location_text} — Great day for outdoor activities!"
+        else:
+            return f"🔵 **{event_name}**{location_text} — Solid indoor option!"
+    
+    # DECENT MATCHES (50-69)
+    elif score >= 50:
+        if "outdoor" in event_category:
+            temp_text = f" (It's {int(temp)}°F)" if temp else ""
+            return f"🌤️ **{event_name}**{location_text} — Weather's okay for outdoor events{temp_text}."
+        else:
+            return f"⚪ **{event_name}**{location_text} — Weather-neutral activity."
+    
+    # POOR MATCHES (Below 50)
+    else:
+        if "outdoor" in event_category and weather_analysis["is_rainy"]:
+            return f"🌧️ **{event_name}**{location_text} — Outdoor event, but it's rainy. Bring an umbrella or check if it's postponed!"
+        elif "outdoor" in event_category and weather_analysis.get("temp_category") == "cold":
+            return f"❄️ **{event_name}**{location_text} — Outdoor event, but bundle up — it's chilly!"
+        else:
+            return f"⚪ **{event_name}**{location_text} — Check weather before heading out."
+
+
+def _create_weather_summary(temp: Optional[float], phrase: str) -> str:
+    """
+    🌤️ Penny's plain-English weather summary.
+    
+    Args:
+        temp: Temperature in Fahrenheit
+        phrase: Weather description phrase
+        
+    Returns:
+        Human-readable weather summary
+    """
+    if not temp:
+        return f"Current conditions: {phrase.title()}"
+    
+    temp_desc = ""
+    if temp >= 85:
+        temp_desc = "hot"
+    elif temp >= 70:
+        temp_desc = "warm"
+    elif temp >= 60:
+        temp_desc = "mild"
+    elif temp >= 40:
+        temp_desc = "cool"
+    else:
+        temp_desc = "cold"
+    
+    return f"It's {temp_desc} at {int(temp)}°F — {phrase.lower()}."
+
+
+# --- ERROR RESPONSE HELPERS (Penny stays helpful even in failures) ---
+
+def _create_no_events_response(tenant_id: str) -> Dict[str, Any]:
+    """
+    Returns friendly response when no events are found.
+    
+    Args:
+        tenant_id: City identifier
+        
+    Returns:
+        Structured response with helpful message
+    """
+    return {
+        "weather": {},
+        "suggestions": [
+            f"🤔 I don't have any events loaded for {tenant_id} right now. "
+            "Let me know if you'd like me to check again or add some!"
+        ],
+        "tenant_id": tenant_id,
+        "event_count": 0,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+
+def _create_error_response(
+    tenant_id: str, 
+    error_type: str, 
+    message: str
+) -> Dict[str, Any]:
+    """
+    Returns structured error with Penny's helpful tone.
+    
+    Args:
+        tenant_id: City identifier
+        error_type: Structured error type code
+        message: User-friendly error message
+        
+    Returns:
+        Error response dictionary
+    """
+    logger.error(f"Error in event_weather: {error_type} - {message}")
+    return {
+        "weather": {},
+        "suggestions": [f"⚠️ {message}"],
+        "tenant_id": tenant_id,
+        "event_count": 0,
+        "error_type": error_type,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+
+def _create_fallback_response(
+    tenant_id: str, 
+    events: List[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """
+    Graceful degradation: Shows events even if weather service is down.
+    Penny stays helpful!
+    
+    Args:
+        tenant_id: City identifier
+        events: List of available events
+        
+    Returns:
+        Fallback response with events but no weather optimization
+    """
+    # Limit to configured maximum
+    display_events = events[:EventWeatherConfig.MAX_FALLBACK_EVENTS]
+    
+    suggestions = [
+        f"📅 **{event.get('name', 'Event')}** — {event.get('category', 'Community event')}"
+        for event in display_events
+    ]
+    
+    suggestions.insert(0, "⚠️ Weather service is temporarily unavailable, but here are today's events:")
+    
+    return {
+        "weather": {"error": "Weather service unavailable"},
+        "suggestions": suggestions,
+        "tenant_id": tenant_id,
+        "event_count": len(events),
+        "timestamp": datetime.utcnow().isoformat(),
+        "fallback_mode": True
+    }
+
+
+# --- STRUCTURED LOGGING HELPER ---
+
+def _log_operation(
+    operation: str,
+    tenant_id: str,
+    success: bool,
+    event_count: int,
+    response_time_ms: int,
+    fallback_used: bool,
+    weather_available: bool,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    error_type: Optional[str] = None,
+    error_message: Optional[str] = None
+) -> None:
+    """
+    Log event weather operation with structured data.
+    
+    Args:
+        operation: Operation name
+        tenant_id: City identifier
+        success: Whether operation succeeded
+        event_count: Number of events processed
+        response_time_ms: Total response time in milliseconds
+        fallback_used: Whether fallback mode was used
+        weather_available: Whether weather data was available
+        session_id: Optional session identifier
+        user_id: Optional user identifier
+        error_type: Optional error type if failed
+        error_message: Optional error message if failed
+    """
+    log_data = {
+        "operation": operation,
+        "tenant_id": sanitize_for_logging(tenant_id),
+        "success": success,
+        "event_count": event_count,
+        "response_time_ms": response_time_ms,
+        "fallback_used": fallback_used,
+        "weather_available": weather_available,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+    
+    if session_id:
+        log_data["session_id"] = sanitize_for_logging(session_id)
+    
+    if user_id:
+        log_data["user_id"] = sanitize_for_logging(user_id)
+    
+    if error_type:
+        log_data["error_type"] = error_type
+    
+    if error_message:
+        log_data["error_message"] = sanitize_for_logging(error_message)
+    
+    log_interaction(log_data)
+
+
+def _calculate_response_time(start_time: float) -> int:
+    """
+    Calculate response time in milliseconds.
+    
+    Args:
+        start_time: Operation start time from time.time()
+        
+    Returns:
+        Response time in milliseconds
+    """
+    return int((time.time() - start_time) * 1000)

gemma_utils.py

@@ -0,0 +1,244 @@
+# models/gemma/gemma_utils.py
+
+"""
+Gemma Model Utilities for PENNY Project
+Handles text generation using the Gemma-based core language model pipeline.
+Provides async generation with structured error handling and logging.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, Optional
+
+# --- Logging Imports ---
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- Model Loader Import ---
+try:
+    from app.model_loader import load_model_pipeline
+    MODEL_LOADER_AVAILABLE = True
+except ImportError:
+    MODEL_LOADER_AVAILABLE = False
+    import logging
+    logging.getLogger(__name__).warning("Could not import load_model_pipeline. Gemma service unavailable.")
+
+# Global variable to store the loaded pipeline for re-use
+GEMMA_PIPELINE: Optional[Any] = None
+AGENT_NAME = "penny-core-agent"
+INITIALIZATION_ATTEMPTED = False
+
+
+def _initialize_gemma_pipeline() -> bool:
+    """
+    Initializes the Gemma pipeline only once.
+    
+    Returns:
+        bool: True if initialization succeeded, False otherwise.
+    """
+    global GEMMA_PIPELINE, INITIALIZATION_ATTEMPTED
+    
+    if INITIALIZATION_ATTEMPTED:
+        return GEMMA_PIPELINE is not None
+    
+    INITIALIZATION_ATTEMPTED = True
+    
+    if not MODEL_LOADER_AVAILABLE:
+        log_interaction(
+            intent="gemma_initialization",
+            success=False,
+            error="model_loader unavailable"
+        )
+        return False
+    
+    try:
+        log_interaction(
+            intent="gemma_initialization",
+            success=None,
+            details=f"Loading {AGENT_NAME}"
+        )
+        
+        GEMMA_PIPELINE = load_model_pipeline(AGENT_NAME)
+        
+        if GEMMA_PIPELINE is None:
+            log_interaction(
+                intent="gemma_initialization",
+                success=False,
+                error="Pipeline returned None"
+            )
+            return False
+        
+        log_interaction(
+            intent="gemma_initialization",
+            success=True,
+            details=f"Model {AGENT_NAME} loaded successfully"
+        )
+        return True
+        
+    except Exception as e:
+        log_interaction(
+            intent="gemma_initialization",
+            success=False,
+            error=str(e)
+        )
+        return False
+
+
+# Attempt initialization at module load
+_initialize_gemma_pipeline()
+
+
+def is_gemma_available() -> bool:
+    """
+    Check if Gemma service is available.
+    
+    Returns:
+        bool: True if Gemma pipeline is loaded and ready.
+    """
+    return GEMMA_PIPELINE is not None
+
+
+async def generate_response(
+    prompt: str,
+    max_new_tokens: int = 256,
+    temperature: float = 0.7,
+    tenant_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Runs text generation using the loaded Gemma pipeline.
+
+    Args:
+        prompt: The conversational or instruction prompt.
+        max_new_tokens: The maximum number of tokens to generate (default: 256).
+        temperature: Controls randomness in generation (default: 0.7).
+        tenant_id: Optional tenant identifier for logging.
+
+    Returns:
+        A dictionary containing:
+            - response (str): The generated text
+            - available (bool): Whether the service was available
+            - error (str, optional): Error message if generation failed
+            - response_time_ms (int, optional): Generation time in milliseconds
+    """
+    start_time = time.time()
+    
+    global GEMMA_PIPELINE
+
+    # Check availability
+    if not is_gemma_available():
+        log_interaction(
+            intent="gemma_generate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Gemma pipeline not available",
+            fallback_used=True
+        )
+        return {
+            "response": "I'm having trouble accessing my language model right now. Please try again in a moment!",
+            "available": False,
+            "error": "Pipeline not initialized"
+        }
+
+    # Validate inputs
+    if not prompt or not isinstance(prompt, str):
+        log_interaction(
+            intent="gemma_generate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid prompt provided"
+        )
+        return {
+            "response": "I didn't receive a valid prompt. Could you try again?",
+            "available": True,
+            "error": "Invalid input"
+        }
+
+    # Configure generation parameters
+    gen_kwargs = {
+        "max_new_tokens": max_new_tokens,
+        "temperature": temperature,
+        "do_sample": True if temperature > 0.0 else False,
+        "return_full_text": False
+    }
+
+    try:
+        loop = asyncio.get_event_loop()
+        
+        # Run model inference in thread executor
+        results = await loop.run_in_executor(
+            None,
+            lambda: GEMMA_PIPELINE(prompt, **gen_kwargs)
+        )
+        
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        # Parse results
+        if results and isinstance(results, list) and len(results) > 0:
+            if isinstance(results[0], dict) and 'generated_text' in results[0]:
+                generated_text = results[0]['generated_text'].strip()
+                
+                # Log slow responses
+                if response_time_ms > 5000:
+                    log_interaction(
+                        intent="gemma_generate_slow",
+                        tenant_id=tenant_id,
+                        success=True,
+                        response_time_ms=response_time_ms,
+                        details="Slow generation detected"
+                    )
+                
+                log_interaction(
+                    intent="gemma_generate",
+                    tenant_id=tenant_id,
+                    success=True,
+                    response_time_ms=response_time_ms,
+                    prompt_preview=sanitize_for_logging(prompt[:100])
+                )
+                
+                return {
+                    "response": generated_text,
+                    "available": True,
+                    "response_time_ms": response_time_ms
+                }
+        
+        # Unexpected output format
+        log_interaction(
+            intent="gemma_generate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Unexpected model output format",
+            response_time_ms=response_time_ms
+        )
+        
+        return {
+            "response": "I got an unexpected response from my language model. Let me try to help you another way!",
+            "available": True,
+            "error": "Unexpected output format"
+        }
+
+    except asyncio.CancelledError:
+        log_interaction(
+            intent="gemma_generate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Generation cancelled"
+        )
+        raise
+        
+    except Exception as e:
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="gemma_generate",
+            tenant_id=tenant_id,
+            success=False,
+            error=str(e),
+            response_time_ms=response_time_ms,
+            fallback_used=True
+        )
+        
+        return {
+            "response": "I'm having trouble generating a response right now. Please try again!",
+            "available": False,
+            "error": str(e),
+            "response_time_ms": response_time_ms
+        }

handler.py

@@ -0,0 +1,31 @@
+# handler.py
+from app.orchestrator import PennyOrchestrator
+from typing import Dict, Any
+import json
+
+class EndpointHandler:
+    def __init__(self, path=""):
+        """Initialize PENNY orchestrator when endpoint starts"""
+        print("🤖 Initializing PENNY...")
+        self.orchestrator = PennyOrchestrator()
+        print("✅ PENNY ready!")
+    
+    def __call__(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Handle inference requests from Hugging Face
+        """
+        # Extract inputs
+        inputs = data.get("inputs", "")
+        tenant_id = data.get("tenant_id", "default")
+        user_id = data.get("user_id", "anonymous")
+        session_id = data.get("session_id", None)
+        
+        # Process through orchestrator
+        response = self.orchestrator.process(
+            message=inputs,
+            tenant_id=tenant_id,
+            user_id=user_id,
+            session_id=session_id
+        )
+        
+        return response

intents.py

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

layoutlm_utils.py

@@ -0,0 +1,359 @@
+# models/layoutlm/layoutlm_utils.py
+
+"""
+LayoutLM Model Utilities for PENNY Project
+Handles document structure extraction and field recognition for civic forms and documents.
+Provides async document processing with structured error handling and logging.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, Optional, List
+from io import BytesIO
+
+# --- Logging Imports ---
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- Model Loader Import ---
+try:
+    from app.model_loader import load_model_pipeline
+    MODEL_LOADER_AVAILABLE = True
+except ImportError:
+    MODEL_LOADER_AVAILABLE = False
+    import logging
+    logging.getLogger(__name__).warning("Could not import load_model_pipeline. LayoutLM service unavailable.")
+
+# Global variable to store the loaded pipeline for re-use
+LAYOUTLM_PIPELINE: Optional[Any] = None
+AGENT_NAME = "penny-doc-agent"
+INITIALIZATION_ATTEMPTED = False
+
+
+def _initialize_layoutlm_pipeline() -> bool:
+    """
+    Initializes the LayoutLM pipeline only once.
+    
+    Returns:
+        bool: True if initialization succeeded, False otherwise.
+    """
+    global LAYOUTLM_PIPELINE, INITIALIZATION_ATTEMPTED
+    
+    if INITIALIZATION_ATTEMPTED:
+        return LAYOUTLM_PIPELINE is not None
+    
+    INITIALIZATION_ATTEMPTED = True
+    
+    if not MODEL_LOADER_AVAILABLE:
+        log_interaction(
+            intent="layoutlm_initialization",
+            success=False,
+            error="model_loader unavailable"
+        )
+        return False
+    
+    try:
+        log_interaction(
+            intent="layoutlm_initialization",
+            success=None,
+            details=f"Loading {AGENT_NAME}"
+        )
+        
+        LAYOUTLM_PIPELINE = load_model_pipeline(AGENT_NAME)
+        
+        if LAYOUTLM_PIPELINE is None:
+            log_interaction(
+                intent="layoutlm_initialization",
+                success=False,
+                error="Pipeline returned None"
+            )
+            return False
+        
+        log_interaction(
+            intent="layoutlm_initialization",
+            success=True,
+            details=f"Model {AGENT_NAME} loaded successfully"
+        )
+        return True
+        
+    except Exception as e:
+        log_interaction(
+            intent="layoutlm_initialization",
+            success=False,
+            error=str(e)
+        )
+        return False
+
+
+# Attempt initialization at module load
+_initialize_layoutlm_pipeline()
+
+
+def is_layoutlm_available() -> bool:
+    """
+    Check if LayoutLM service is available.
+    
+    Returns:
+        bool: True if LayoutLM pipeline is loaded and ready.
+    """
+    return LAYOUTLM_PIPELINE is not None
+
+
+async def extract_document_data(
+    file_bytes: bytes,
+    file_name: str,
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Processes a document (e.g., PDF, image) using LayoutLM to extract structured data.
+
+    Args:
+        file_bytes: The raw bytes of the uploaded file.
+        file_name: The original name of the file (e.g., form.pdf).
+        tenant_id: Optional tenant identifier for logging.
+
+    Returns:
+        A dictionary containing:
+            - status (str): "success" or "error"
+            - extracted_fields (dict, optional): Extracted key-value pairs
+            - available (bool): Whether the service was available
+            - message (str, optional): Error message if extraction failed
+            - response_time_ms (int, optional): Processing time in milliseconds
+    """
+    start_time = time.time()
+    
+    global LAYOUTLM_PIPELINE
+
+    # Check availability
+    if not is_layoutlm_available():
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error="LayoutLM pipeline not available",
+            fallback_used=True
+        )
+        return {
+            "status": "error",
+            "available": False,
+            "message": "Document processing is temporarily unavailable. Please try uploading your document again in a moment!"
+        }
+
+    # Validate inputs
+    if not file_bytes or not isinstance(file_bytes, bytes):
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid file_bytes provided"
+        )
+        return {
+            "status": "error",
+            "available": True,
+            "message": "I didn't receive valid document data. Could you try uploading your file again?"
+        }
+    
+    if not file_name or not isinstance(file_name, str):
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid file_name provided"
+        )
+        return {
+            "status": "error",
+            "available": True,
+            "message": "I need a valid file name to process your document. Please try again!"
+        }
+
+    # Check file size (prevent processing extremely large files)
+    file_size_mb = len(file_bytes) / (1024 * 1024)
+    if file_size_mb > 50:  # 50 MB limit
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error=f"File too large: {file_size_mb:.2f}MB",
+            file_name=sanitize_for_logging(file_name)
+        )
+        return {
+            "status": "error",
+            "available": True,
+            "message": f"Your file is too large ({file_size_mb:.1f}MB). Please upload a document smaller than 50MB."
+        }
+
+    try:
+        # --- Real-world step (PLACEHOLDER) ---
+        # In a real implementation, you would:
+        # 1. Use a library (e.g., PyMuPDF, pdf2image) to convert PDF bytes to image(s).
+        # 2. Use PIL/Pillow to load the image(s) from bytes.
+        # 3. Pass the PIL Image object to the LayoutLM pipeline.
+        
+        # For now, we use a simple mock placeholder for the image object:
+        image_mock = {
+            "file_name": file_name,
+            "byte_size": len(file_bytes)
+        }
+
+        loop = asyncio.get_event_loop()
+        
+        # Run model inference in thread executor
+        results = await loop.run_in_executor(
+            None,
+            lambda: LAYOUTLM_PIPELINE(image_mock)
+        )
+        
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        # Validate results
+        if not results or not isinstance(results, list):
+            log_interaction(
+                intent="layoutlm_extract",
+                tenant_id=tenant_id,
+                success=False,
+                error="Unexpected model output format",
+                response_time_ms=response_time_ms,
+                file_name=sanitize_for_logging(file_name)
+            )
+            return {
+                "status": "error",
+                "available": True,
+                "message": "I had trouble understanding the document structure. The file might be corrupted or in an unsupported format."
+            }
+        
+        # Convert model output (list of dicts) into a clean key-value format
+        extracted_data = {}
+        for item in results:
+            if isinstance(item, dict) and 'label' in item and 'text' in item:
+                label_key = item['label'].lower().strip()
+                text_value = str(item['text']).strip()
+                
+                # Avoid empty values
+                if text_value:
+                    extracted_data[label_key] = text_value
+        
+        # Log slow processing
+        if response_time_ms > 10000:  # 10 seconds
+            log_interaction(
+                intent="layoutlm_extract_slow",
+                tenant_id=tenant_id,
+                success=True,
+                response_time_ms=response_time_ms,
+                details="Slow document processing detected",
+                file_name=sanitize_for_logging(file_name)
+            )
+        
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=True,
+            response_time_ms=response_time_ms,
+            file_name=sanitize_for_logging(file_name),
+            fields_extracted=len(extracted_data)
+        )
+        
+        return {
+            "status": "success",
+            "extracted_fields": extracted_data,
+            "available": True,
+            "response_time_ms": response_time_ms,
+            "fields_count": len(extracted_data)
+        }
+
+    except asyncio.CancelledError:
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error="Processing cancelled",
+            file_name=sanitize_for_logging(file_name)
+        )
+        raise
+        
+    except Exception as e:
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="layoutlm_extract",
+            tenant_id=tenant_id,
+            success=False,
+            error=str(e),
+            response_time_ms=response_time_ms,
+            file_name=sanitize_for_logging(file_name),
+            fallback_used=True
+        )
+        
+        return {
+            "status": "error",
+            "available": False,
+            "message": f"I encountered an issue while processing your document. Please try again, or contact support if this continues!",
+            "error": str(e),
+            "response_time_ms": response_time_ms
+        }
+
+
+async def validate_document_fields(
+    extracted_fields: Dict[str, str],
+    required_fields: List[str],
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Validates that required fields were successfully extracted from a document.
+    
+    Args:
+        extracted_fields: Dictionary of extracted field names and values.
+        required_fields: List of field names that must be present.
+        tenant_id: Optional tenant identifier for logging.
+    
+    Returns:
+        A dictionary containing:
+            - valid (bool): Whether all required fields are present
+            - missing_fields (list): List of missing required fields
+            - present_fields (list): List of found required fields
+    """
+    if not isinstance(extracted_fields, dict):
+        log_interaction(
+            intent="layoutlm_validate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid extracted_fields type"
+        )
+        return {
+            "valid": False,
+            "missing_fields": required_fields,
+            "present_fields": []
+        }
+    
+    if not isinstance(required_fields, list):
+        log_interaction(
+            intent="layoutlm_validate",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid required_fields type"
+        )
+        return {
+            "valid": False,
+            "missing_fields": [],
+            "present_fields": []
+        }
+    
+    # Normalize field names for case-insensitive comparison
+    extracted_keys = {k.lower().strip() for k in extracted_fields.keys()}
+    required_keys = {f.lower().strip() for f in required_fields}
+    
+    present_fields = [f for f in required_fields if f.lower().strip() in extracted_keys]
+    missing_fields = [f for f in required_fields if f.lower().strip() not in extracted_keys]
+    
+    is_valid = len(missing_fields) == 0
+    
+    log_interaction(
+        intent="layoutlm_validate",
+        tenant_id=tenant_id,
+        success=is_valid,
+        details=f"Validated {len(present_fields)}/{len(required_fields)} required fields"
+    )
+    
+    return {
+        "valid": is_valid,
+        "missing_fields": missing_fields,
+        "present_fields": present_fields
+    }

location_utils.py

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

logging_utils.py

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

main.py

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

model_config.json

@@ -0,0 +1,47 @@
+{
+  "penny-core-agent": {
+    "model_name": "google/gemma-7b-it",
+    "task": "text-generation",
+    "endpoint": "azure-ml",
+    "fallback_endpoint": "local",
+    "timeout_seconds": 30,
+    "max_retries": 2,
+    "description": "Penny's core conversational AI for civic engagement responses"
+  },
+  "penny-doc-agent": {
+    "model_name": "microsoft/layoutlmv3-base",
+    "task": "pdf-extraction",
+    "endpoint": "azure-ml",
+    "fallback_endpoint": "local",
+    "timeout_seconds": 45,
+    "max_retries": 2,
+    "description": "Document understanding and PDF extraction for civic documents"
+  },
+  "penny-translate-agent": {
+    "model_name": "facebook/nllb-200-distilled-600M",
+    "task": "translation",
+    "endpoint": "azure-ml",
+    "fallback_endpoint": "local",
+    "timeout_seconds": 20,
+    "max_retries": 2,
+    "description": "Multilingual translation service for accessible civic information"
+  },
+  "penny-sentiment-agent": {
+    "model_name": "cardiffnlp/twitter-roberta-base-sentiment",
+    "task": "sentiment-analysis",
+    "endpoint": "azure-ml",
+    "fallback_endpoint": "local",
+    "timeout_seconds": 15,
+    "max_retries": 2,
+    "description": "Sentiment analysis for community feedback and engagement monitoring"
+  },
+  "penny-bias-checker": {
+    "model_name": "facebook/bart-large-mnli",
+    "task": "bias-detection",
+    "endpoint": "azure-ml",
+    "fallback_endpoint": "local",
+    "timeout_seconds": 20,
+    "max_retries": 2,
+    "description": "Bias detection to ensure fair and equitable civic information"
+  }
+}

model_loader.py

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

orchestrator.py

@@ -0,0 +1,1315 @@
+"""
+🎭 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)
+        elif intent == IntentType.WEATHER:
+            result = await _handle_weather(
+                message=message,
+                context=context,
+                tenant_id=tenant_id,
+                lat=lat,
+                lon=lon,
+                intent_result=intent_result
+            )
+        
+        # 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
+        )
+        
+        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
+        )
+        
+        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)

providence_ri.json

@@ -0,0 +1,115 @@
+{
+  "city": "Providence",
+  "state": "Rhode Island",
+  "tenant_id": "providence_ri",
+  "legal_notes": {
+      "behavioral_health": "state_only",
+      "csb_authority": "none",
+      "events_source": "city_official_site",
+      "transit_source": "city",
+      "trash_source": "city",
+      "public_safety_source": "city",
+      "warming_center_authority": "city",
+      "sexual_health_authority": "state"
+  },
+  "official_links": {
+      "city_homepage": "https://www.providenceri.gov/",
+      "events_calendar": "https://www.downtownprovidence.com/event-calendar/",
+      "public_health": "https://health.ri.gov/",
+      "transit": "https://www.ripta.com/",
+      "libraries": "https://www.provcomlib.org/",
+      "parks_and_recreation": "https://www.providenceri.gov/providence-parks/",
+      "emergency_management": "https://www.providenceri.gov/emergency-management-agency/",
+      "trash": "https://www.providenceri.gov/public-works/streets-sanitation/"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "BH Link (Behavioral Health Hotline)",
+                  "link": "https://www.bhlink.org/",
+                  "phone": "401-414-LINK (5465)",
+                  "notes": "24/7 mental health and substance use crisis hotline for all Rhode Island residents. Penny should always refer users here for crisis situations."
+              },
+              {
+                  "name": "Rhode Island Dept. of Behavioral Healthcare",
+                  "link": "https://www.bhddh.ri.gov/",
+                  "phone": "",
+                  "notes": "State authority for long term mental health, developmental disability, and addiction services."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "state",
+          "resources": [
+              {
+                  "name": "Rhode Island Dept. of Health – STD Prevention",
+                  "link": "https://health.ri.gov/programs/std/",
+                  "phone": "401-222-2577",
+                  "notes": "State program offering confidential testing and treatment services. Penny should prioritize this official source."
+              },
+              {
+                  "name": "Planned Parenthood – Providence Health Center",
+                  "link": "https://www.plannedparenthood.org/health-center/rhode-island/providence/02903/providence-health-center-3991-90490",
+                  "phone": "401-421-9500",
+                  "notes": "Major nonprofit provider of sexual health services, testing, and contraception in the area."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "allowed": true,
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Providence Community Recreation Centers",
+                  "address": "Varies by activation",
+                  "season": "winter/summer",
+                  "link": "https://www.providenceri.gov/providence-parks/",
+                  "notes": "City community centers are activated as warming centers during extreme cold and cooling centers during extreme heat. Penny must advise users to check the city's official social media or hotline for current sites."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "city",
+          "pickup_days": "Varies by zone. Collection schedules are published by the Department of Public Works.",
+          "holiday_schedule_link": "https://www.providenceri.gov/public-works/streets-sanitation/"
+      },
+      "transit": {
+          "authority": "state",
+          "provider": "RIPTA (Rhode Island Public Transit Authority)",
+          "routes_link": "https://www.ripta.com/routes/",
+          "planner_link": "https://www.ripta.com/"
+      },
+      "emergency": {
+          "authority": "city",
+          "alerts_link": "https://www.providenceri.gov/emergency-management-agency/",
+          "non_emergency_phone": "401-272-3121 (Police Non Emergency)",
+          "emergency_management_link": "https://www.providenceri.gov/emergency-management-agency/"
+      },
+      "libraries": {
+          "authority": "city",
+          "resources": [
+              {
+                  "branch": "Providence Community Library – Central",
+                  "address": "150 Empire St, Providence, RI 02903",
+                  "link": "https://www.provcomlib.org/",
+                  "notes": "Main branch of the city library system offering access to computers, Wi-Fi, and community resources."
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Fox Point Community Center",
+                  "address": "446 Wickenden St, Providence, RI 02903",
+                  "link": "https://www.providenceri.gov/providence-parks/fox-point-community-center/",
+                  "notes": "Offers recreational programs, afterschool activities, and senior services for the East Side neighborhood."
+              }
+          ]
+      }
+  }
+}

router.py

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

seattle_wa.json

@@ -0,0 +1,109 @@
+{
+  "city": "Seattle",
+  "state": "Washington",
+  "tenant_id": "seattle_wa",
+  "legal_notes": {
+      "behavioral_health": "allowed",
+      "csb_authority": "city_department",
+      "events_source": "city_official_site",
+      "transit_source": "city",
+      "trash_source": "city",
+      "public_safety_source": "city",
+      "warming_center_authority": "city",
+      "sexual_health_authority": "city"
+  },
+  "official_links": {
+      "city_homepage": "https://www.seattle.gov/",
+      "events_calendar": "https://visitseattle.org/things-to-do/events/",
+      "public_health": "https://www.seattle.gov/human-services",
+      "transit": "https://kingcounty.gov/depts/transportation/metro.aspx",
+      "libraries": "https://www.spl.org/",
+      "parks_and_recreation": "https://www.seattle.gov/parks",
+      "emergency_management": "https://www.seattle.gov/emergency-management",
+      "trash": "https://www.seattle.gov/utilities/your-services/collection"
+  },
+  "services": {
+      "behavioral_health": {
+          "allowed": true,
+          "authority": "city_department",
+          "resources": [
+              {
+                  "name": "Seattle Human Services Department (HSD)",
+                  "link": "https://www.seattle.gov/human-services",
+                  "phone": "206-684-0500",
+                  "notes": "HSD coordinates city behavioral health and homelessness services. Penny should use this as the primary referral point for non-emergency help."
+              },
+              {
+                  "name": "King County Crisis Connections",
+                  "link": "https://www.crisisconnections.org/",
+                  "phone": "866-427-4747",
+                  "notes": "24/7 county-wide crisis line for mental health and substance abuse issues. Essential for immediate, non-911 crises."
+              }
+          ]
+      },
+      "sexual_health": {
+          "allowed": true,
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Public Health – Seattle & King County (Sexual Health Clinic)",
+                  "link": "https://kingcounty.gov/depts/health/sexual-health.aspx",
+                  "phone": "206-477-8000",
+                  "notes": "Official county authority providing confidential STD/HIV testing, treatment, and prevention services in the Seattle area."
+              }
+          ]
+      },
+      "warming_and_cooling_centers": {
+          "allowed": true,
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Seattle Community Centers",
+                  "address": "Varies by activation",
+                  "season": "winter/summer",
+                  "link": "https://www.seattle.gov/emergency-management/prepare/stay-safe/extreme-heat-and-cold",
+                  "notes": "The City activates various libraries and community centers as warming shelters during extreme cold and cooling centers during extreme heat. Penny must advise residents to check the link for the official activation status."
+              }
+          ]
+      },
+      "trash_and_recycling": {
+          "authority": "city",
+          "pickup_days": "Varies by address. Schedules and recycling rules are managed by Seattle Public Utilities (SPU).",
+          "holiday_schedule_link": "https://www.seattle.gov/utilities/your-services/collection/holiday-schedule"
+      },
+      "transit": {
+          "authority": "county",
+          "provider": "King County Metro",
+          "routes_link": "https://kingcounty.gov/depts/transportation/metro/schedules-routes.aspx",
+          "planner_link": "https://kingcounty.gov/depts/transportation/metro/travel-options.aspx"
+      },
+      "emergency": {
+          "authority": "city",
+          "alerts_link": "https://www.seattle.gov/emergency-management/alert-seattle",
+          "non_emergency_phone": "206-625-5011 (Police Non Emergency)",
+          "emergency_management_link": "https://www.seattle.gov/emergency-management"
+      },
+      "libraries": {
+          "authority": "city",
+          "resources": [
+              {
+                  "branch": "The Seattle Public Library – Central Library",
+                  "address": "1000 4th Ave, Seattle, WA 98104",
+                  "link": "https://www.spl.org/",
+                  "notes": "The flagship library offering extensive resources, free computer access, and a safe, public space."
+              }
+          ]
+      },
+      "community_centers": {
+          "authority": "city",
+          "resources": [
+              {
+                  "name": "Magnuson Park Community Center",
+                  "address": "7110 62nd Ave NE, Seattle, WA 98115",
+                  "link": "https://www.seattle.gov/parks/allparks/magnuson-park",
+                  "notes": "A large community hub offering diverse recreational programming, classes, and facilities."
+              }
+          ]
+      }
+  }
+}

sentiment_utils.py

@@ -0,0 +1,396 @@
+# models/sentiment/sentiment_utils.py
+
+"""
+Sentiment Analysis Model Utilities for PENNY Project
+Handles text sentiment classification for user input analysis and content moderation.
+Provides async sentiment analysis with structured error handling and logging.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, Optional, List
+
+# --- Logging Imports ---
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- Model Loader Import ---
+try:
+    from app.model_loader import load_model_pipeline
+    MODEL_LOADER_AVAILABLE = True
+except ImportError:
+    MODEL_LOADER_AVAILABLE = False
+    import logging
+    logging.getLogger(__name__).warning("Could not import load_model_pipeline. Sentiment service unavailable.")
+
+# Global variable to store the loaded pipeline for re-use
+SENTIMENT_PIPELINE: Optional[Any] = None
+AGENT_NAME = "penny-sentiment-agent"
+INITIALIZATION_ATTEMPTED = False
+
+
+def _initialize_sentiment_pipeline() -> bool:
+    """
+    Initializes the sentiment pipeline only once.
+    
+    Returns:
+        bool: True if initialization succeeded, False otherwise.
+    """
+    global SENTIMENT_PIPELINE, INITIALIZATION_ATTEMPTED
+    
+    if INITIALIZATION_ATTEMPTED:
+        return SENTIMENT_PIPELINE is not None
+    
+    INITIALIZATION_ATTEMPTED = True
+    
+    if not MODEL_LOADER_AVAILABLE:
+        log_interaction(
+            intent="sentiment_initialization",
+            success=False,
+            error="model_loader unavailable"
+        )
+        return False
+    
+    try:
+        log_interaction(
+            intent="sentiment_initialization",
+            success=None,
+            details=f"Loading {AGENT_NAME}"
+        )
+        
+        SENTIMENT_PIPELINE = load_model_pipeline(AGENT_NAME)
+        
+        if SENTIMENT_PIPELINE is None:
+            log_interaction(
+                intent="sentiment_initialization",
+                success=False,
+                error="Pipeline returned None"
+            )
+            return False
+        
+        log_interaction(
+            intent="sentiment_initialization",
+            success=True,
+            details=f"Model {AGENT_NAME} loaded successfully"
+        )
+        return True
+        
+    except Exception as e:
+        log_interaction(
+            intent="sentiment_initialization",
+            success=False,
+            error=str(e)
+        )
+        return False
+
+
+# Attempt initialization at module load
+_initialize_sentiment_pipeline()
+
+
+def is_sentiment_available() -> bool:
+    """
+    Check if sentiment analysis service is available.
+    
+    Returns:
+        bool: True if sentiment pipeline is loaded and ready.
+    """
+    return SENTIMENT_PIPELINE is not None
+
+
+async def get_sentiment_analysis(
+    text: str,
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Runs sentiment analysis on the input text using the loaded pipeline.
+
+    Args:
+        text: The string of text to analyze.
+        tenant_id: Optional tenant identifier for logging.
+
+    Returns:
+        A dictionary containing:
+            - label (str): Sentiment label (e.g., "POSITIVE", "NEGATIVE", "NEUTRAL")
+            - score (float): Confidence score for the sentiment prediction
+            - available (bool): Whether the service was available
+            - message (str, optional): Error message if analysis failed
+            - response_time_ms (int, optional): Analysis time in milliseconds
+    """
+    start_time = time.time()
+    
+    global SENTIMENT_PIPELINE
+
+    # Check availability
+    if not is_sentiment_available():
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="Sentiment pipeline not available",
+            fallback_used=True
+        )
+        return {
+            "label": "UNKNOWN",
+            "score": 0.0,
+            "available": False,
+            "message": "Sentiment analysis is temporarily unavailable."
+        }
+
+    # Validate input
+    if not text or not isinstance(text, str):
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid text input"
+        )
+        return {
+            "label": "ERROR",
+            "score": 0.0,
+            "available": True,
+            "message": "Invalid text input provided."
+        }
+    
+    # Check text length (prevent processing extremely long texts)
+    if len(text) > 10000:  # 10k character limit
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error=f"Text too long: {len(text)} characters",
+            text_preview=sanitize_for_logging(text[:100])
+        )
+        return {
+            "label": "ERROR",
+            "score": 0.0,
+            "available": True,
+            "message": "Text is too long for sentiment analysis (max 10,000 characters)."
+        }
+
+    try:
+        loop = asyncio.get_event_loop()
+        
+        # Run model inference in thread executor
+        # Hugging Face pipelines accept lists and return lists
+        results = await loop.run_in_executor(
+            None,
+            lambda: SENTIMENT_PIPELINE([text])
+        )
+        
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        # Validate results
+        if not results or not isinstance(results, list) or len(results) == 0:
+            log_interaction(
+                intent="sentiment_analysis",
+                tenant_id=tenant_id,
+                success=False,
+                error="Empty or invalid model output",
+                response_time_ms=response_time_ms,
+                text_preview=sanitize_for_logging(text[:100])
+            )
+            return {
+                "label": "ERROR",
+                "score": 0.0,
+                "available": True,
+                "message": "Sentiment analysis returned unexpected format."
+            }
+        
+        result = results[0]
+        
+        # Validate result structure
+        if not isinstance(result, dict) or 'label' not in result or 'score' not in result:
+            log_interaction(
+                intent="sentiment_analysis",
+                tenant_id=tenant_id,
+                success=False,
+                error="Invalid result structure",
+                response_time_ms=response_time_ms,
+                text_preview=sanitize_for_logging(text[:100])
+            )
+            return {
+                "label": "ERROR",
+                "score": 0.0,
+                "available": True,
+                "message": "Sentiment analysis returned unexpected format."
+            }
+        
+        # Log slow analysis
+        if response_time_ms > 3000:  # 3 seconds
+            log_interaction(
+                intent="sentiment_analysis_slow",
+                tenant_id=tenant_id,
+                success=True,
+                response_time_ms=response_time_ms,
+                details="Slow sentiment analysis detected",
+                text_length=len(text)
+            )
+        
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=True,
+            response_time_ms=response_time_ms,
+            sentiment_label=result.get('label'),
+            sentiment_score=result.get('score'),
+            text_length=len(text)
+        )
+        
+        return {
+            "label": result['label'],
+            "score": float(result['score']),
+            "available": True,
+            "response_time_ms": response_time_ms
+        }
+
+    except asyncio.CancelledError:
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="Analysis cancelled"
+        )
+        raise
+        
+    except Exception as e:
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="sentiment_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error=str(e),
+            response_time_ms=response_time_ms,
+            text_preview=sanitize_for_logging(text[:100]),
+            fallback_used=True
+        )
+        
+        return {
+            "label": "ERROR",
+            "score": 0.0,
+            "available": False,
+            "message": "An error occurred during sentiment analysis.",
+            "error": str(e),
+            "response_time_ms": response_time_ms
+        }
+
+
+async def analyze_sentiment_batch(
+    texts: List[str],
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Runs sentiment analysis on a batch of texts for efficiency.
+    
+    Args:
+        texts: List of text strings to analyze.
+        tenant_id: Optional tenant identifier for logging.
+    
+    Returns:
+        A dictionary containing:
+            - results (list): List of sentiment analysis results for each text
+            - available (bool): Whether the service was available
+            - total_analyzed (int): Number of texts successfully analyzed
+            - response_time_ms (int, optional): Total batch analysis time
+    """
+    start_time = time.time()
+    
+    global SENTIMENT_PIPELINE
+
+    # Check availability
+    if not is_sentiment_available():
+        log_interaction(
+            intent="sentiment_batch_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="Sentiment pipeline not available",
+            batch_size=len(texts) if texts else 0
+        )
+        return {
+            "results": [],
+            "available": False,
+            "total_analyzed": 0,
+            "message": "Sentiment analysis is temporarily unavailable."
+        }
+
+    # Validate input
+    if not texts or not isinstance(texts, list):
+        log_interaction(
+            intent="sentiment_batch_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid texts input"
+        )
+        return {
+            "results": [],
+            "available": True,
+            "total_analyzed": 0,
+            "message": "Invalid batch input provided."
+        }
+    
+    # Filter valid texts and limit batch size
+    valid_texts = [t for t in texts if isinstance(t, str) and t.strip()]
+    if len(valid_texts) > 100:  # Batch size limit
+        valid_texts = valid_texts[:100]
+    
+    if not valid_texts:
+        log_interaction(
+            intent="sentiment_batch_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error="No valid texts in batch"
+        )
+        return {
+            "results": [],
+            "available": True,
+            "total_analyzed": 0,
+            "message": "No valid texts provided for analysis."
+        }
+
+    try:
+        loop = asyncio.get_event_loop()
+        
+        # Run batch inference in thread executor
+        results = await loop.run_in_executor(
+            None,
+            lambda: SENTIMENT_PIPELINE(valid_texts)
+        )
+        
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="sentiment_batch_analysis",
+            tenant_id=tenant_id,
+            success=True,
+            response_time_ms=response_time_ms,
+            batch_size=len(valid_texts),
+            total_analyzed=len(results) if results else 0
+        )
+        
+        return {
+            "results": results if results else [],
+            "available": True,
+            "total_analyzed": len(results) if results else 0,
+            "response_time_ms": response_time_ms
+        }
+
+    except Exception as e:
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="sentiment_batch_analysis",
+            tenant_id=tenant_id,
+            success=False,
+            error=str(e),
+            response_time_ms=response_time_ms,
+            batch_size=len(valid_texts)
+        )
+        
+        return {
+            "results": [],
+            "available": False,
+            "total_analyzed": 0,
+            "message": "An error occurred during batch sentiment analysis.",
+            "error": str(e),
+            "response_time_ms": response_time_ms
+        }

tool_agent.py

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

translation_utils.py

@@ -0,0 +1,598 @@
+# models/translation/translation_utils.py
+
+"""
+Translation Model Utilities for PENNY Project
+Handles multilingual translation using NLLB-200 for civic engagement accessibility.
+Provides async translation with structured error handling and language code normalization.
+"""
+
+import asyncio
+import time
+from typing import Dict, Any, Optional, List
+
+# --- Logging Imports ---
+from app.logging_utils import log_interaction, sanitize_for_logging
+
+# --- Model Loader Import ---
+try:
+    from app.model_loader import load_model_pipeline
+    MODEL_LOADER_AVAILABLE = True
+except ImportError:
+    MODEL_LOADER_AVAILABLE = False
+    import logging
+    logging.getLogger(__name__).warning("Could not import load_model_pipeline. Translation service unavailable.")
+
+# Global variable to store the loaded pipeline for re-use
+TRANSLATION_PIPELINE: Optional[Any] = None
+AGENT_NAME = "penny-translate-agent"
+INITIALIZATION_ATTEMPTED = False
+
+# NLLB-200 Language Code Mapping (Common languages for civic engagement)
+LANGUAGE_CODES = {
+    # English variants
+    "english": "eng_Latn",
+    "en": "eng_Latn",
+    
+    # Spanish variants
+    "spanish": "spa_Latn",
+    "es": "spa_Latn",
+    "español": "spa_Latn",
+    
+    # French
+    "french": "fra_Latn",
+    "fr": "fra_Latn",
+    "français": "fra_Latn",
+    
+    # Mandarin Chinese
+    "chinese": "zho_Hans",
+    "mandarin": "zho_Hans",
+    "zh": "zho_Hans",
+    
+    # Arabic
+    "arabic": "arb_Arab",
+    "ar": "arb_Arab",
+    
+    # Hindi
+    "hindi": "hin_Deva",
+    "hi": "hin_Deva",
+    
+    # Portuguese
+    "portuguese": "por_Latn",
+    "pt": "por_Latn",
+    
+    # Russian
+    "russian": "rus_Cyrl",
+    "ru": "rus_Cyrl",
+    
+    # German
+    "german": "deu_Latn",
+    "de": "deu_Latn",
+    
+    # Vietnamese
+    "vietnamese": "vie_Latn",
+    "vi": "vie_Latn",
+    
+    # Tagalog
+    "tagalog": "tgl_Latn",
+    "tl": "tgl_Latn",
+    
+    # Urdu
+    "urdu": "urd_Arab",
+    "ur": "urd_Arab",
+    
+    # Swahili
+    "swahili": "swh_Latn",
+    "sw": "swh_Latn",
+}
+
+# Pre-translated civic phrases for common queries
+CIVIC_PHRASES = {
+    "eng_Latn": {
+        "voting_location": "Where is my polling place?",
+        "voter_registration": "How do I register to vote?",
+        "city_services": "What city services are available?",
+        "report_issue": "I want to report a problem.",
+        "contact_city": "How do I contact city hall?",
+    },
+    "spa_Latn": {
+        "voting_location": "¿Dónde está mi lugar de votación?",
+        "voter_registration": "¿Cómo me registro para votar?",
+        "city_services": "¿Qué servicios de la ciudad están disponibles?",
+        "report_issue": "Quiero reportar un problema.",
+        "contact_city": "¿Cómo contacto al ayuntamiento?",
+    }
+}
+
+
+def _initialize_translation_pipeline() -> bool:
+    """
+    Initializes the translation pipeline only once.
+    
+    Returns:
+        bool: True if initialization succeeded, False otherwise.
+    """
+    global TRANSLATION_PIPELINE, INITIALIZATION_ATTEMPTED
+    
+    if INITIALIZATION_ATTEMPTED:
+        return TRANSLATION_PIPELINE is not None
+    
+    INITIALIZATION_ATTEMPTED = True
+    
+    if not MODEL_LOADER_AVAILABLE:
+        log_interaction(
+            intent="translation_initialization",
+            success=False,
+            error="model_loader unavailable"
+        )
+        return False
+    
+    try:
+        log_interaction(
+            intent="translation_initialization",
+            success=None,
+            details=f"Loading {AGENT_NAME}"
+        )
+        
+        TRANSLATION_PIPELINE = load_model_pipeline(AGENT_NAME)
+        
+        if TRANSLATION_PIPELINE is None:
+            log_interaction(
+                intent="translation_initialization",
+                success=False,
+                error="Pipeline returned None"
+            )
+            return False
+        
+        log_interaction(
+            intent="translation_initialization",
+            success=True,
+            details=f"Model {AGENT_NAME} loaded successfully"
+        )
+        return True
+        
+    except Exception as e:
+        log_interaction(
+            intent="translation_initialization",
+            success=False,
+            error=str(e)
+        )
+        return False
+
+
+# Attempt initialization at module load
+_initialize_translation_pipeline()
+
+
+def is_translation_available() -> bool:
+    """
+    Check if translation service is available.
+    
+    Returns:
+        bool: True if translation pipeline is loaded and ready.
+    """
+    return TRANSLATION_PIPELINE is not None
+
+
+def normalize_language_code(lang: str) -> str:
+    """
+    Converts common language names/codes to NLLB-200 format.
+    
+    Args:
+        lang: Language name or code (e.g., "spanish", "es", "español")
+        
+    Returns:
+        NLLB-200 language code (e.g., "spa_Latn")
+    """
+    if not lang or not isinstance(lang, str):
+        return "eng_Latn"  # Default to English
+    
+    lang_lower = lang.lower().strip()
+    
+    # Check if it's already in NLLB format (contains underscore)
+    if "_" in lang_lower:
+        return lang_lower
+    
+    # Look up in mapping
+    return LANGUAGE_CODES.get(lang_lower, lang_lower)
+
+
+def get_supported_languages() -> List[str]:
+    """
+    Get list of supported language codes.
+    
+    Returns:
+        List of NLLB-200 language codes supported by PENNY.
+    """
+    return list(set(LANGUAGE_CODES.values()))
+
+
+async def translate_text(
+    text: str,
+    source_language: str = "eng_Latn",
+    target_language: str = "spa_Latn",
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Translates text from source language to target language using NLLB-200.
+
+    Args:
+        text: The text to translate.
+        source_language: Source language code (e.g., "eng_Latn", "spanish", "es")
+        target_language: Target language code (e.g., "spa_Latn", "french", "fr")
+        tenant_id: Optional tenant identifier for logging.
+
+    Returns:
+        A dictionary containing:
+            - translated_text (str): The translated text
+            - source_lang (str): Normalized source language code
+            - target_lang (str): Normalized target language code
+            - original_text (str): The input text
+            - available (bool): Whether the service was available
+            - error (str, optional): Error message if translation failed
+            - response_time_ms (int, optional): Translation time in milliseconds
+    """
+    start_time = time.time()
+    
+    global TRANSLATION_PIPELINE
+
+    # Check availability
+    if not is_translation_available():
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=False,
+            error="Translation pipeline not available",
+            fallback_used=True
+        )
+        return {
+            "translated_text": text,  # Return original text as fallback
+            "source_lang": source_language,
+            "target_lang": target_language,
+            "original_text": text,
+            "available": False,
+            "error": "Translation service is temporarily unavailable."
+        }
+
+    # Validate input
+    if not text or not isinstance(text, str):
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid text input"
+        )
+        return {
+            "translated_text": "",
+            "source_lang": source_language,
+            "target_lang": target_language,
+            "original_text": text if isinstance(text, str) else "",
+            "available": True,
+            "error": "Invalid text input provided."
+        }
+    
+    # Check text length (prevent processing extremely long texts)
+    if len(text) > 5000:  # 5k character limit for translation
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=False,
+            error=f"Text too long: {len(text)} characters",
+            text_preview=sanitize_for_logging(text[:100])
+        )
+        return {
+            "translated_text": text,
+            "source_lang": source_language,
+            "target_lang": target_language,
+            "original_text": text,
+            "available": True,
+            "error": "Text is too long for translation (max 5,000 characters)."
+        }
+
+    # Normalize language codes
+    src_lang = normalize_language_code(source_language)
+    tgt_lang = normalize_language_code(target_language)
+    
+    # Skip translation if source and target are the same
+    if src_lang == tgt_lang:
+        log_interaction(
+            intent="translation_skipped",
+            tenant_id=tenant_id,
+            success=True,
+            details="Source and target languages are identical"
+        )
+        return {
+            "translated_text": text,
+            "source_lang": src_lang,
+            "target_lang": tgt_lang,
+            "original_text": text,
+            "available": True,
+            "skipped": True
+        }
+
+    try:
+        loop = asyncio.get_event_loop()
+        
+        # Run model inference in thread executor
+        # NLLB pipeline expects text and language parameters
+        results = await loop.run_in_executor(
+            None,
+            lambda: TRANSLATION_PIPELINE(
+                text,
+                src_lang=src_lang,
+                tgt_lang=tgt_lang
+            )
+        )
+        
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        # Validate results
+        if not results or not isinstance(results, list) or len(results) == 0:
+            log_interaction(
+                intent="translation",
+                tenant_id=tenant_id,
+                success=False,
+                error="Empty or invalid model output",
+                response_time_ms=response_time_ms,
+                source_lang=src_lang,
+                target_lang=tgt_lang
+            )
+            return {
+                "translated_text": text,  # Fallback to original
+                "source_lang": src_lang,
+                "target_lang": tgt_lang,
+                "original_text": text,
+                "available": True,
+                "error": "Translation returned unexpected format."
+            }
+        
+        # NLLB returns format: [{'translation_text': '...'}]
+        translated = results[0].get('translation_text', '').strip()
+        
+        if not translated:
+            log_interaction(
+                intent="translation",
+                tenant_id=tenant_id,
+                success=False,
+                error="Empty translation result",
+                response_time_ms=response_time_ms,
+                source_lang=src_lang,
+                target_lang=tgt_lang
+            )
+            return {
+                "translated_text": text,  # Fallback to original
+                "source_lang": src_lang,
+                "target_lang": tgt_lang,
+                "original_text": text,
+                "available": True,
+                "error": "Translation produced empty result."
+            }
+        
+        # Log slow translations
+        if response_time_ms > 5000:  # 5 seconds
+            log_interaction(
+                intent="translation_slow",
+                tenant_id=tenant_id,
+                success=True,
+                response_time_ms=response_time_ms,
+                details="Slow translation detected",
+                source_lang=src_lang,
+                target_lang=tgt_lang,
+                text_length=len(text)
+            )
+        
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=True,
+            response_time_ms=response_time_ms,
+            source_lang=src_lang,
+            target_lang=tgt_lang,
+            text_length=len(text)
+        )
+        
+        return {
+            "translated_text": translated,
+            "source_lang": src_lang,
+            "target_lang": tgt_lang,
+            "original_text": text,
+            "available": True,
+            "response_time_ms": response_time_ms
+        }
+
+    except asyncio.CancelledError:
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=False,
+            error="Translation cancelled",
+            source_lang=src_lang,
+            target_lang=tgt_lang
+        )
+        raise
+        
+    except Exception as e:
+        response_time_ms = int((time.time() - start_time) * 1000)
+        
+        log_interaction(
+            intent="translation",
+            tenant_id=tenant_id,
+            success=False,
+            error=str(e),
+            response_time_ms=response_time_ms,
+            source_lang=src_lang,
+            target_lang=tgt_lang,
+            text_preview=sanitize_for_logging(text[:100]),
+            fallback_used=True
+        )
+        
+        return {
+            "translated_text": text,  # Fallback to original
+            "source_lang": src_lang,
+            "target_lang": tgt_lang,
+            "original_text": text,
+            "available": False,
+            "error": str(e),
+            "response_time_ms": response_time_ms
+        }
+
+
+async def detect_and_translate(
+    text: str,
+    target_language: str = "eng_Latn",
+    tenant_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Attempts to detect the source language and translate to target.
+    
+    Note: This is a simplified heuristic-based detection. For production,
+    consider integrating a dedicated language detection model.
+    
+    Args:
+        text: The text to translate
+        target_language: Target language code
+        tenant_id: Optional tenant identifier for logging
+        
+    Returns:
+        Translation result dictionary
+    """
+    if not text or not isinstance(text, str):
+        return {
+            "translated_text": "",
+            "detected_lang": "unknown",
+            "target_lang": target_language,
+            "original_text": text if isinstance(text, str) else "",
+            "available": True,
+            "error": "Invalid text input."
+        }
+    
+    # Simple heuristic: check for common non-English characters
+    detected_lang = "eng_Latn"  # Default assumption
+    
+    # Check for Spanish characters
+    if any(char in text for char in ['¿', '¡', 'ñ', 'á', 'é', 'í', 'ó', 'ú']):
+        detected_lang = "spa_Latn"
+    # Check for Chinese characters
+    elif any('\u4e00' <= char <= '\u9fff' for char in text):
+        detected_lang = "zho_Hans"
+    # Check for Arabic script
+    elif any('\u0600' <= char <= '\u06ff' for char in text):
+        detected_lang = "arb_Arab"
+    # Check for Cyrillic (Russian)
+    elif any('\u0400' <= char <= '\u04ff' for char in text):
+        detected_lang = "rus_Cyrl"
+    # Check for Devanagari (Hindi)
+    elif any('\u0900' <= char <= '\u097f' for char in text):
+        detected_lang = "hin_Deva"
+    
+    log_interaction(
+        intent="language_detection",
+        tenant_id=tenant_id,
+        success=True,
+        detected_lang=detected_lang,
+        text_preview=sanitize_for_logging(text[:50])
+    )
+    
+    result = await translate_text(text, detected_lang, target_language, tenant_id)
+    result["detected_lang"] = detected_lang
+    
+    return result
+
+
+async def batch_translate(
+    texts: List[str],
+    source_language: str = "eng_Latn",
+    target_language: str = "spa_Latn",
+    tenant_id: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    """
+    Translate multiple texts at once.
+    
+    Args:
+        texts: List of strings to translate
+        source_language: Source language code
+        target_language: Target language code
+        tenant_id: Optional tenant identifier for logging
+        
+    Returns:
+        List of translation result dictionaries
+    """
+    if not texts or not isinstance(texts, list):
+        log_interaction(
+            intent="batch_translation",
+            tenant_id=tenant_id,
+            success=False,
+            error="Invalid texts input"
+        )
+        return []
+    
+    # Filter valid texts and limit batch size
+    valid_texts = [t for t in texts if isinstance(t, str) and t.strip()]
+    if len(valid_texts) > 50:  # Batch size limit
+        valid_texts = valid_texts[:50]
+        log_interaction(
+            intent="batch_translation",
+            tenant_id=tenant_id,
+            success=None,
+            details=f"Batch size limited to 50 texts"
+        )
+    
+    if not valid_texts:
+        log_interaction(
+            intent="batch_translation",
+            tenant_id=tenant_id,
+            success=False,
+            error="No valid texts in batch"
+        )
+        return []
+    
+    start_time = time.time()
+    results = []
+    
+    for text in valid_texts:
+        result = await translate_text(text, source_language, target_language, tenant_id)
+        results.append(result)
+    
+    response_time_ms = int((time.time() - start_time) * 1000)
+    
+    log_interaction(
+        intent="batch_translation",
+        tenant_id=tenant_id,
+        success=True,
+        response_time_ms=response_time_ms,
+        batch_size=len(valid_texts),
+        source_lang=normalize_language_code(source_language),
+        target_lang=normalize_language_code(target_language)
+    )
+    
+    return results
+
+
+def get_civic_phrase(
+    phrase_key: str,
+    language: str = "eng_Latn"
+) -> str:
+    """
+    Get a pre-translated civic phrase for common queries.
+    
+    Args:
+        phrase_key: Key for the civic phrase (e.g., "voting_location")
+        language: Target language code
+        
+    Returns:
+        Translated phrase or empty string if not found
+    """
+    if not phrase_key or not isinstance(phrase_key, str):
+        return ""
+    
+    lang_code = normalize_language_code(language)
+    phrase = CIVIC_PHRASES.get(lang_code, {}).get(phrase_key, "")
+    
+    if phrase:
+        log_interaction(
+            intent="civic_phrase_lookup",
+            success=True,
+            phrase_key=phrase_key,
+            language=lang_code
+        )
+    
+    return phrase

weather_agent.py

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