Initial commit

.env.example

@@ -0,0 +1,31 @@
+# =============================================================================
+# AQI Intelligence Engine — Environment Variables
+# Rename this file to .env and fill in your API keys.
+# =============================================================================
+
+# Flask/FastAPI Settings
+ENV=development
+PORT=7860
+
+# --- API Keys for Data Services ---
+
+# OpenWeather API (Required for real-time and historical AQI data)
+# Get a key from: https://openweathermap.org/api
+OPENWEATHER_API_KEY=your_openweather_api_key_here
+
+# Mappls (MapmyIndia) API Key (Used for Indian traffic and geocoding)
+# Get a key from: https://www.mappls.com/
+MAPPLS_API_KEY=your_mappls_api_key_here
+
+# NASA FIRMS API Key (Used for active fire and thermal anomaly detection)
+# Get a key from: https://firms.modaps.eosdis.nasa.gov/api/map_key/
+NASA_FIRMS_API_KEY=your_nasa_firms_api_key_here
+
+# Sentinel Hub API Key (Used for satellite imagery fetching)
+# Get a key from: https://www.sentinel-hub.com/
+SENTINEL_HUB_API_KEY=your_sentinel_hub_api_key_here
+
+# --- Hugging Face Authentication Token ---
+# Optional: Paste your Hugging Face User Access Token (read) to download gated models
+# Get a token from: https://huggingface.co/settings/tokens
+HF_TOKEN=your_hf_token_here

.gitignore

@@ -0,0 +1,42 @@
+# =============================================================================
+# Git Ignore Rules for AQI Intelligence Engine
+# =============================================================================
+
+# Virtual Environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# Python Cache & Bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Environment Variables & Secrets
+.env
+!.env.example
+
+# Model Binaries & Caches (Hugging Face models & XGBoost pkl download automatically on startup)
+models/hf_cache/
+hf_cache/
+*.bin
+*.safetensors
+*.pth
+*.pkl
+*.joblib
+
+# Logs & Temporary Files
+*.log
+tmp/
+.tmp/
+
+# IDE & OS Files
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.11-slim
+
+# System dependencies for geospatial libs
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libgdal-dev \
+    libgeos-dev \
+    libproj-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /code
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Create non-root user (required by HF Spaces)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/tmp/hf_cache \
+    TRANSFORMERS_CACHE=/tmp/hf_cache
+
+WORKDIR $HOME/app
+
+# Copy application code
+COPY --chown=user . $HOME/app
+
+# Expose port 7860 (HF Spaces default)
+EXPOSE 7860
+
+# Start FastAPI + Gradio server
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,39 @@
+---
+title: AQI Intelligence Engine
+emoji: 🌬️
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: Smart City AQI Forecast & Satellite Vision AI Engine
+---
+
+# 🌬️ AQI Intelligence Engine (Hugging Face ZeroGPU & CPU Dual Mode)
+
+An AI-powered Urban Air Quality Intelligence Platform built for Smart City Intervention, AQI forecasting (Google TimesFM 2.5 & Tuned XGBoost), satellite vision analysis (Florence-2 + Grounding DINO), and source attribution.
+
+## 🚀 Key Features
+
+1. **Dual Hardware Compatibility (CPU + ZeroGPU)**:
+   - Runs seamlessly on **ZeroGPU Space (A100 dynamic allocation)** when deployed to Hugging Face with GPU hardware.
+   - Automatically falls back to **CPU execution** on standard local machines or free CPU spaces without crashing or RAM OOM.
+2. **Interactive Gradio Control Center**:
+   - Web GUI for instant time-series AQI forecasting and satellite image pollution source analysis.
+3. **Full REST API Support**:
+   - Includes FastAPI swagger endpoints at `/docs`.
+   - Direct JSON endpoints `/forecast`, `/analyze-image`, `/health`.
+
+## 📦 Deploying to Hugging Face Spaces
+
+1. Create a new Space on Hugging Face:
+   - **Space SDK**: Gradio
+   - **Hardware**: ZeroGPU (or CPU basic)
+2. Push the contents of `backend-ai/` to your Hugging Face Space repository:
+   ```bash
+   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+   git push hf main
+   ```
+3. Your Space will build automatically and serve both the Gradio Web App and REST APIs on port 7860.

app.py

@@ -0,0 +1,311 @@
+"""
+AQI Intelligence Engine — Hugging Face Gradio + ZeroGPU Main Application Entry Point
+
+Supports both standalone Gradio Web Interface and REST API backend.
+Runs seamlessly on Hugging Face ZeroGPU spaces as well as standard CPU fallback.
+"""
+
+import os
+import sys
+import io
+import time
+import json
+import logging
+from PIL import Image
+import pandas as pd
+import gradio as gr
+import gradio_client.utils as client_utils
+
+# Monkey-patch Gradio Client bug where boolean OpenAPI schema fields cause TypeError
+if hasattr(client_utils, "_json_schema_to_python_type"):
+    _orig_json_schema_to_python_type = client_utils._json_schema_to_python_type
+    def safe_json_schema_to_python_type(schema, defs=None):
+        if isinstance(schema, bool):
+            return "Any"
+        try:
+            return _orig_json_schema_to_python_type(schema, defs)
+        except Exception:
+            return "Any"
+    client_utils._json_schema_to_python_type = safe_json_schema_to_python_type
+
+import asyncio
+from datetime import datetime, timezone
+
+try:
+    import spaces
+except ImportError:
+    spaces = None
+
+def gpu_decorator(func=None, duration=None):
+    """ZeroGPU decorator wrapper that applies spaces.GPU on HF or identity on CPU."""
+    if spaces is not None:
+        try:
+            if func is None:
+                return spaces.GPU(duration=duration) if duration else spaces.GPU
+            if callable(func):
+                return spaces.GPU(func)
+            return spaces.GPU
+        except Exception:
+            pass
+    if func is None:
+        return lambda f: f
+    if callable(func):
+        return func
+    return lambda f: f
+
+from config import get_device, HAS_SPACES
+from services.forecast.service import forecast_aqi
+from services.vision.service import detect_pollution_sources
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("app_hf")
+
+# Default sample AQI history for quick testing
+DEFAULT_AQI_HIST = "145, 150, 162, 178, 185, 210, 240, 260, 255, 230, 215, 195, 180, 175, 182, 198, 220, 245, 270, 290, 310, 295, 280, 260"
+
+
+async def _async_handle_forecast_ui(aqi_text_input: str, lat_val: str, lon_val: str):
+    """Async core logic for AQI Forecasting."""
+    try:
+        if not aqi_text_input or not aqi_text_input.strip():
+            return "❌ Error: Please provide at least 24 hourly AQI readings.", None, ""
+        
+        # Parse CSV string into list of floats
+        raw_vals = [x.strip() for x in aqi_text_input.split(",") if x.strip()]
+        aqi_series = [float(x) for x in raw_vals]
+
+        lat = float(lat_val) if lat_val and lat_val.strip() else None
+        lon = float(lon_val) if lon_val and lon_val.strip() else None
+
+        start_time = time.time()
+        result = await forecast_aqi(aqi_series, lat=lat, lon=lon)
+        elapsed = round(time.time() - start_time, 2)
+
+        # Build summary text
+        summary = (
+            f"### 🔮 Forecast Completed in {elapsed}s\n"
+            f"- **Active Hardware**: `{result.get('device_used', get_device())}`\n"
+            f"- **Model Used**: `{result.get('model_type', 'Google TimesFM 2.5 / XGBoost')}`\n"
+            f"- **24-Hour Horizon Avg AQI**: `{result.get('forecast_24h', {}).get('mean', 'N/A')}`\n"
+            f"- **48-Hour Horizon Avg AQI**: `{result.get('forecast_48h', {}).get('mean', 'N/A')}`\n"
+            f"- **72-Hour Horizon Avg AQI**: `{result.get('forecast_72h', {}).get('mean', 'N/A')}`\n"
+        )
+
+        # Build DataFrame for plot table
+        hourly_preds = result.get("hourly_predictions", [])
+        if hourly_preds:
+            df = pd.DataFrame(hourly_preds)
+        else:
+            df = pd.DataFrame({"step": list(range(1, len(aqi_series)+1)), "aqi": aqi_series})
+
+        formatted_json = json.dumps(result, indent=2)
+        return summary, df, formatted_json
+
+    except Exception as e:
+        logger.error(f"Forecast UI Error: {e}")
+        return f"❌ Execution Failed: {str(e)}", None, ""
+
+
+@gpu_decorator
+def handle_forecast_ui(aqi_text_input: str, lat_val: str, lon_val: str):
+    """Gradio handler for AQI Forecasting wrapped with @gpu_decorator."""
+    return asyncio.run(_async_handle_forecast_ui(aqi_text_input, lat_val, lon_val))
+
+
+async def _async_handle_vision_ui(input_image):
+    """Async core logic for Satellite Vision Pollution Detection."""
+    try:
+        if input_image is None:
+            return "❌ Error: Please upload a satellite or aerial image.", ""
+
+        start_time = time.time()
+        pil_image = Image.fromarray(input_image) if not isinstance(input_image, Image.Image) else input_image
+
+        result = await detect_pollution_sources(pil_image)
+        elapsed = round(time.time() - start_time, 2)
+
+        scene_desc = result.get("scene_description", "No detailed description.")
+        sources = result.get("pollution_sources_found", [])
+        counts = result.get("source_count", {})
+        severity = result.get("severity", "unknown").upper()
+
+        sources_str = ", ".join(sources) if sources else "None identified"
+
+        summary = (
+            f"### 🛰️ Vision Analysis Complete ({elapsed}s)\n"
+            f"- **Device Active**: `{get_device()}`\n"
+            f"- **Severity Level**: **`{severity}`**\n"
+            f"- **Identified Sources**: `{sources_str}`\n\n"
+            f"#### 📝 Scene Description:\n{scene_desc}\n\n"
+            f"#### 📊 Category Counts:\n```json\n{json.dumps(counts, indent=2)}\n```"
+        )
+
+        formatted_json = json.dumps(result, indent=2)
+        return summary, formatted_json
+
+    except Exception as e:
+        logger.error(f"Vision UI Error: {e}")
+        return f"❌ Analysis Failed: {str(e)}", ""
+
+
+@gpu_decorator
+def handle_vision_ui(input_image):
+    """Gradio handler for Satellite Vision wrapped with @gpu_decorator."""
+    return asyncio.run(_async_handle_vision_ui(input_image))
+
+
+# Build Gradio Blocks Interface
+with gr.Blocks(title="AQI Intelligence Engine — HF ZeroGPU Edition", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+        # 🌬️ AQI Intelligence Engine (ZeroGPU & CPU Compatible)
+        ### AI-Powered Urban Air Quality Forecasting & High-Resolution Satellite Vision Intelligence
+        ---
+        """
+    )
+
+    with gr.Tabs():
+        # TAB 1: FORECASTING
+        with gr.TabItem("📈 AQI Forecasting (TimesFM 2.5 & XGBoost)"):
+            gr.Markdown("Input historical hourly AQI readings to generate 24h, 48h, and 72h predictive forecasts.")
+            with gr.Row():
+                with gr.Column(scale=1):
+                    aqi_in = gr.Textbox(
+                        label="Historical Hourly AQI Readings (CSV format, min 24 hours)",
+                        value=DEFAULT_AQI_HIST,
+                        lines=4,
+                    )
+                    lat_in = gr.Textbox(label="Latitude (Optional, e.g. 28.6139)", value="28.6139")
+                    lon_in = gr.Textbox(label="Longitude (Optional, e.g. 77.2090)", value="77.2090")
+                    run_forecast_btn = gr.Button("🚀 Run Forecast", variant="primary")
+
+                with gr.Column(scale=1):
+                    forecast_summary_out = gr.Markdown(label="Forecast Overview")
+                    forecast_table_out = gr.Dataframe(label="Forecast Step Matrix")
+
+            with gr.Accordion("🔍 Raw JSON Response Payload", open=False):
+                forecast_json_out = gr.Code(language="json")
+
+            run_forecast_btn.click(
+                fn=handle_forecast_ui,
+                inputs=[aqi_in, lat_in, lon_in],
+                outputs=[forecast_summary_out, forecast_table_out, forecast_json_out],
+            )
+
+        # TAB 2: SATELLITE VISION
+        with gr.TabItem("🛰️ Satellite Vision AI (Florence-2 + Grounding DINO)"):
+            gr.Markdown("Upload satellite/aerial imagery to detect air pollution sources, smoke plumes, kiln clusters, and industrial emissions.")
+            with gr.Row():
+                with gr.Column(scale=1):
+                    image_in = gr.Image(label="Upload Satellite / Aerial Image", type="numpy")
+                    analyze_img_btn = gr.Button("🔍 Analyze Image", variant="primary")
+
+                with gr.Column(scale=1):
+                    vision_summary_out = gr.Markdown(label="Vision Intelligence Findings")
+
+            with gr.Accordion("🔍 Detailed Detections JSON", open=False):
+                vision_json_out = gr.Code(language="json")
+
+            analyze_img_btn.click(
+                fn=handle_vision_ui,
+                inputs=[image_in],
+                outputs=[vision_summary_out, vision_json_out],
+            )
+
+        # TAB 3: HARDWARE & SYSTEM STATUS
+        with gr.TabItem("⚡ Hardware & API Status"):
+            device_active = get_device()
+            gr.Markdown(
+                f"""
+                ### 🖥️ Active Deployment Info
+                - **Primary Compute Hardware**: `{device_active}`
+                - **HuggingFace `spaces` SDK Available**: `{spaces is not None}`
+                - **ZeroGPU Status**: `{"Active & Ready for dynamic GPU acceleration" if spaces is not None else "Running on standard CPU mode (Universal Compatibility)"}`
+                
+                ### 🔌 REST API Endpoints
+                When deployed on Hugging Face Spaces, you can query REST endpoints directly:
+                - `POST /forecast`: Direct historical AQI prediction payload
+                - `POST /analyze-image`: Satellite base64 image breakdown
+                - `GET /health`: Core server state & device telemetry
+                """
+            )
+
+from starlette.responses import JSONResponse
+from starlette.requests import Request
+
+# Initialize the Gradio queue — this creates the underlying FastAPI app object
+# MUST be called before registering REST routes on demo.app
+demo.queue()
+
+
+def register_api_routes(gradio_app):
+    """Register custom REST API endpoints on the Gradio FastAPI app."""
+
+    @gradio_app.post("/api/v1/forecast")
+    async def api_forecast(request: Request):
+        """REST API endpoint for historical AQI prediction."""
+        try:
+            payload = await request.json()
+            from services.forecast.service import forecast_aqi
+            aqi_hist = payload.get("aqi_history", [])
+            lat = payload.get("lat")
+            lon = payload.get("lon")
+            res = await forecast_aqi(aqi_hist, lat=lat, lon=lon)
+            return JSONResponse(res)
+        except Exception as e:
+            logger.error(f"API Forecast error: {e}")
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+    @gradio_app.post("/api/v1/analyze-image")
+    async def api_analyze_image(request: Request):
+        """REST API endpoint for satellite image pollution breakdown."""
+        try:
+            payload = await request.json()
+            import base64
+            from services.vision.service import detect_pollution_sources
+            base64_str = payload.get("image_base64", "")
+            if not base64_str:
+                return JSONResponse({"error": "No image_base64 provided"}, status_code=400)
+            if "," in base64_str:
+                base64_str = base64_str.split(",", 1)[1]
+            img_bytes = base64.b64decode(base64_str)
+            pil_img = Image.open(io.BytesIO(img_bytes)).convert("RGB")
+            res = await detect_pollution_sources(pil_img)
+            return JSONResponse(res)
+        except Exception as e:
+            logger.error(f"API Vision error: {e}")
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+    @gradio_app.get("/api/v1/health")
+    async def api_health(request: Request):
+        """Health check endpoint."""
+        return JSONResponse({
+            "status": "ok",
+            "device": get_device(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "version": "2.0.0",
+        })
+
+
+# Register REST API routes on the Gradio underlying FastAPI app
+try:
+    from fastapi.middleware.cors import CORSMiddleware
+    # Explicitly configure CORS on the underlying FastAPI app to allow direct requests from the browser
+    demo.app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    register_api_routes(demo.app)
+    logger.info("CORS middleware and REST API routes registered successfully on Gradio FastAPI app.")
+except Exception as e:
+    logger.warning(f"Could not register REST API routes or CORS (will be available via Gradio only): {e}")
+
+# Export Gradio demo as root app object for Hugging Face ZeroGPU SDK
+app = demo
+
+if __name__ == "__main__":
+    # Local development only — on HF Spaces, uvicorn runs the app directly
+    demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

config.py

@@ -0,0 +1,219 @@
+"""
+AQI Intelligence Engine — Central Configuration
+Supports local development and HuggingFace Spaces deployment.
+"""
+
+import os
+import torch
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load local environment variables from .env file if it exists
+load_dotenv(dotenv_path=Path(__file__).parent / ".env")
+
+
+# =============================================================================
+# Environment Detection
+# =============================================================================
+
+IS_HF_SPACE = os.getenv("SPACE_ID") is not None
+ENV = os.getenv("ENV", "development")
+
+# =============================================================================
+# ZeroGPU & Dynamic Device Configuration
+# =============================================================================
+
+try:
+    import spaces
+    HAS_SPACES = True
+except ImportError:
+    HAS_SPACES = False
+
+def gpu_decorator(func=None, duration=None):
+    """
+    Safely apply @spaces.GPU if in an active ZeroGPU environment,
+    otherwise return the original function as a no-op fallback.
+    """
+    if HAS_SPACES:
+        try:
+            if func is None:
+                return spaces.GPU(duration=duration) if duration else spaces.GPU
+            if callable(func):
+                return spaces.GPU(func)
+            return spaces.GPU
+        except (NotImplementedError, Exception):
+            pass
+
+    if func is None:
+        return lambda f: f
+    if callable(func):
+        return func
+    return lambda f: f
+
+def get_device() -> str:
+    """Dynamically return 'cuda' if CUDA/ZeroGPU is active, otherwise 'cpu'."""
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+def get_torch_dtype():
+    """Return torch.float16 for GPU or torch.float32 for CPU."""
+    return torch.float16 if get_device() == "cuda" else torch.float32
+
+# Backward compatibility properties
+DEVICE = get_device()
+TORCH_DTYPE = get_torch_dtype()
+
+# =============================================================================
+# Paths
+# =============================================================================
+
+BASE_DIR = Path(__file__).parent
+MODELS_DIR = Path(os.getenv("MODELS_DIR", str(BASE_DIR / "models")))
+MODELS_DIR.mkdir(parents=True, exist_ok=True)
+
+# HuggingFace cache — use /tmp on Spaces (writable), local dir otherwise
+HF_CACHE_DIR = Path("/tmp/hf_cache") if IS_HF_SPACE else MODELS_DIR / "hf_cache"
+HF_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+os.environ["HF_HOME"] = str(HF_CACHE_DIR)
+os.environ["TRANSFORMERS_CACHE"] = str(HF_CACHE_DIR)
+
+# =============================================================================
+# Model Identifiers (HuggingFace Hub)
+# =============================================================================
+
+MODELS = {
+    "timesfm": "google/timesfm-2.5-200m-pytorch",
+    "florence2": "microsoft/Florence-2-base",
+    "grounding_dino": "IDEA-Research/grounding-dino-tiny",
+    "sam2": "facebook/sam2.1-hiera-small",
+}
+
+# =============================================================================
+# Forecast Configuration
+# =============================================================================
+
+FORECAST_CONFIG = {
+    "max_context": 1024,        # Max context length for TimesFM 2.5
+    "max_horizon": 128,         # Max forecast horizon
+    "horizon_24h": 24,          # Steps for 24-hour forecast
+    "horizon_48h": 48,          # Steps for 48-hour forecast
+    "horizon_72h": 72,          # Steps for 72-hour forecast
+}
+
+# =============================================================================
+# Vision Configuration
+# =============================================================================
+
+VISION_CONFIG = {
+    "florence2_max_tokens": 1024,
+    "grounding_dino_box_threshold": 0.3,
+    "grounding_dino_text_threshold": 0.25,
+    "pollution_prompts": (
+        "smoke. fire. construction site. factory chimney. "
+        "dust cloud. burning waste. heavy vehicles. industrial plant. "
+        "brick kiln. open burning."
+    ),
+}
+
+# =============================================================================
+# SAM2 Configuration
+# =============================================================================
+
+SAM2_CONFIG = {
+    "points_per_batch": 32,
+    "pred_iou_thresh": 0.7,
+    "stability_score_thresh": 0.85,
+}
+
+# =============================================================================
+# Data API Keys & URLs
+# =============================================================================
+
+API_KEYS = {
+    "openweather": os.getenv("OPENWEATHER_API_KEY", ""),
+    "mappls": os.getenv("MAPPLS_API_KEY", ""),
+    "sentinel_hub": os.getenv("SENTINEL_HUB_API_KEY", ""),
+    "nasa_firms": os.getenv("NASA_FIRMS_API_KEY", ""),
+    # CPCB (Central Pollution Control Board) — data.gov.in
+    "cpcb_api_key": os.getenv("CPCB_API_KEY", "579b464db66ec23bdd000001cdd3946e44ce4aad7209ff7b23ac571b"),
+    # Mappls (MapMyIndia) OAuth2 credentials
+    "mappls_client_id": os.getenv("MAPPLS_CLIENT_ID", ""),
+    "mappls_client_secret": os.getenv("MAPPLS_CLIENT_SECRET", ""),
+    # Planet Insight Platform (replaces deprecated Sentinel Hub)
+    "planet_api_key": os.getenv("SENTINEL_HUB_API_KEY", ""),  # PLAK key
+    "planet_client_id": os.getenv("PLANET_INSIGHT_CLIENT_ID", ""),
+    "planet_client_secret": os.getenv("PLANET_INSIGHT_CLIENT_SECRET", ""),
+    # TomTom
+    "tomtom": os.getenv("TOMTOM_API_KEY", ""),
+    # Provider selection
+    "traffic_provider": os.getenv("TRAFFIC_PROVIDER", "mappls").lower(),
+}
+
+API_URLS = {
+    "openweather_aqi": "http://api.openweathermap.org/data/2.5/air_pollution",
+    "openweather_aqi_history": "http://api.openweathermap.org/data/2.5/air_pollution/history",
+    "openweather_aqi_forecast": "http://api.openweathermap.org/data/2.5/air_pollution/forecast",
+    "open_meteo": "https://api.open-meteo.com/v1/forecast",
+    "open_meteo_historical": "https://archive-api.open-meteo.com/v1/archive",
+    "overpass": "https://overpass-api.de/api/interpreter",
+    "nasa_firms": "https://firms.modaps.eosdis.nasa.gov/api/area/csv",
+    "worldpop": "https://www.worldpop.org/rest/data",
+    # CPCB (data.gov.in)
+    "cpcb_stations": "https://api.data.gov.in/resource/3b01bcb8-0b14-4abf-b6f2-c1bfd384ba69",
+    # Planet Insight / Sentinel Hub APIs
+    "sentinel_hub_auth": "https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token",
+    "sentinel_hub_process": "https://services.sentinel-hub.com/api/v1/process",
+    "sentinel_hub_catalog": "https://services.sentinel-hub.com/api/v1/catalog/1.0.0/search",
+    "planet_data": "https://api.planet.com/data/v1",
+    "planet_basemaps": "https://api.planet.com/basemaps/v1/mosaics",
+    # TomTom
+    "tomtom_traffic": "https://api.tomtom.com/traffic/services/4/flowSegmentData/absolute/10/json",
+}
+
+# =============================================================================
+# Cache TTL Settings (in seconds)
+# =============================================================================
+
+CACHE_TTL = {
+    "aqi": 300,             # 5 minutes
+    "weather": 900,         # 15 minutes
+    "traffic": 120,         # 2 minutes
+    "satellite": 3600,      # 1 hour
+    "fire": 600,            # 10 minutes
+    "landuse": 86400,       # 24 hours
+    "population": 86400,    # 24 hours
+    "geospatial": 86400,    # 24 hours
+    "cpcb": 1800,           # 30 minutes (CPCB stations update hourly)
+}
+
+# =============================================================================
+# India AQI Breakpoints (NAQI Standard)
+# =============================================================================
+
+AQI_BREAKPOINTS = {
+    "good": (0, 50),
+    "satisfactory": (51, 100),
+    "moderate": (101, 200),
+    "poor": (201, 300),
+    "very_poor": (301, 400),
+    "severe": (401, 500),
+}
+
+AQI_CATEGORIES = {
+    "good": {"color": "#00B050", "risk": "minimal", "advisory": "Air quality is good. No precautions needed."},
+    "satisfactory": {"color": "#92D050", "risk": "low", "advisory": "Acceptable for most. Unusually sensitive may notice symptoms."},
+    "moderate": {"color": "#FFC000", "risk": "moderate", "advisory": "May cause breathing discomfort to sensitive groups."},
+    "poor": {"color": "#FF6600", "risk": "high", "advisory": "May cause breathing discomfort to people on prolonged exposure."},
+    "very_poor": {"color": "#FF0000", "risk": "very_high", "advisory": "May cause respiratory illness on prolonged exposure."},
+    "severe": {"color": "#800000", "risk": "critical", "advisory": "Serious health effects. Everyone may experience problems."},
+}
+
+# =============================================================================
+# Server Configuration
+# =============================================================================
+
+SERVER_CONFIG = {
+    "host": "0.0.0.0",
+    "port": int(os.getenv("PORT", 7860)),
+    "reload": ENV == "development",
+    "workers": 1,  # Single worker for model memory efficiency
+}

download_models.py

@@ -0,0 +1,122 @@
+"""
+Download all HuggingFace models required by the AQI Intelligence Engine.
+Run this once before starting the server: python download_models.py
+"""
+
+import os
+import sys
+import logging
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def download_timesfm():
+    """Download Google TimesFM 2.5-200m model."""
+    logger.info("=" * 60)
+    logger.info("Downloading TimesFM 2.5-200m ...")
+    logger.info("=" * 60)
+    try:
+        from transformers import AutoModel
+        model = AutoModel.from_pretrained("google/timesfm-2.5-200m-pytorch", trust_remote_code=True)
+        logger.info(f"✅ TimesFM 2.5 downloaded successfully. Parameters: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+        del model
+    except Exception as e:
+        logger.warning(f"⚠️ TimesFM transformer download failed: {e}")
+        logger.info("Trying alternative download via timesfm library...")
+        try:
+            import timesfm
+            model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch")
+            logger.info("✅ TimesFM 2.5 downloaded via timesfm library.")
+            del model
+        except Exception as e2:
+            logger.error(f"❌ TimesFM download failed completely: {e2}")
+            logger.info("The forecast service will use fallback mode.")
+
+
+def download_florence2():
+    """Download Microsoft Florence-2-base model."""
+    logger.info("=" * 60)
+    logger.info("Downloading Florence-2-base (230M params) ...")
+    logger.info("=" * 60)
+    try:
+        from transformers import AutoProcessor, AutoModelForCausalLM
+        processor = AutoProcessor.from_pretrained("microsoft/Florence-2-base", trust_remote_code=True)
+        model = AutoModelForCausalLM.from_pretrained("microsoft/Florence-2-base", trust_remote_code=True)
+        logger.info(f"✅ Florence-2-base downloaded. Parameters: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+        del model, processor
+    except Exception as e:
+        logger.error(f"❌ Florence-2 download failed: {e}")
+
+
+def download_grounding_dino():
+    """Download Grounding DINO tiny model."""
+    logger.info("=" * 60)
+    logger.info("Downloading Grounding DINO tiny ...")
+    logger.info("=" * 60)
+    try:
+        from transformers import AutoProcessor, AutoModelForZeroShotObjectDetection
+        processor = AutoProcessor.from_pretrained("IDEA-Research/grounding-dino-tiny")
+        model = AutoModelForZeroShotObjectDetection.from_pretrained("IDEA-Research/grounding-dino-tiny")
+        logger.info(f"✅ Grounding DINO downloaded. Parameters: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+        del model, processor
+    except Exception as e:
+        logger.error(f"❌ Grounding DINO download failed: {e}")
+
+
+def download_sam2():
+    """Download SAM2.1 hiera-small model."""
+    logger.info("=" * 60)
+    logger.info("Downloading SAM2.1 hiera-small ...")
+    logger.info("=" * 60)
+    try:
+        from transformers import AutoProcessor, AutoModel
+        processor = AutoProcessor.from_pretrained("facebook/sam2.1-hiera-small")
+        model = AutoModel.from_pretrained("facebook/sam2.1-hiera-small")
+        logger.info(f"✅ SAM2.1 downloaded. Parameters: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+        del model, processor
+    except Exception as e:
+        logger.error(f"❌ SAM2.1 download failed: {e}")
+
+
+def main():
+    """Download all models."""
+    logger.info("🚀 AQI Intelligence Engine — Model Downloader")
+    logger.info(f"HF Cache: {os.environ.get('HF_HOME', 'default')}")
+    logger.info("")
+
+    import torch
+    logger.info(f"PyTorch: {torch.__version__}")
+    logger.info(f"CUDA available: {torch.cuda.is_available()}")
+    logger.info(f"Device: {'cuda' if torch.cuda.is_available() else 'cpu'}")
+    logger.info("")
+
+    download_timesfm()
+    download_florence2()
+    download_grounding_dino()
+    download_sam2()
+
+    logger.info("")
+    logger.info("=" * 60)
+    logger.info("✅ All model downloads complete!")
+    logger.info("Run the server: uvicorn main:app --reload --port 7860")
+    logger.info("=" * 60)
+
+
+if __name__ == "__main__":
+    # Set cache directory and Hugging Face token from config
+    try:
+        from config import HF_CACHE_DIR, API_KEYS
+        os.environ["HF_HOME"] = str(HF_CACHE_DIR)
+        
+        # Load HuggingFace token if present in environment/config
+        hf_token = os.getenv("HF_TOKEN")
+        if hf_token:
+            os.environ["HF_TOKEN"] = hf_token
+            # Also set the standard HF_HUB_ENABLE_HF_TRANSFER / token for Hugging Face Hub library
+            os.environ["HUGGING_FACE_HUB_TOKEN"] = hf_token
+            logger.info("🔑 Hugging Face token detected and configured.")
+    except ImportError:
+        pass
+
+    main()

download_new_model.py

@@ -0,0 +1,99 @@
+"""
+Download Script for the New Indian AQI Prediction Model (XGBoost)
+==================================================================
+Clones/downloads the tuned XGBoost model repository from Hugging Face:
+https://huggingface.co/AdityaaXD/AQI-Prediction-Model-Of-India
+"""
+
+import os
+import sys
+import subprocess
+import shutil
+import io
+from pathlib import Path
+
+# Fix Windows console encoding
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')
+
+# Base directories
+BASE_DIR = Path(__file__).parent
+MODELS_DIR = BASE_DIR / "models"
+MODELS_DIR.mkdir(parents=True, exist_ok=True)
+
+REPO_URL = "https://huggingface.co/AdityaaXD/AQI-Prediction-Model-Of-India"
+TEMP_CLONE_DIR = MODELS_DIR / "temp_aqi_model_clone"
+
+def download_model():
+    print("=" * 70)
+    print("🚀 DOWNLOADING ADITYAAXD AQI XGBOOST PREDICTION MODEL")
+    print(f"   Source Repository: {REPO_URL}")
+    print("=" * 70)
+
+    # 1. Clean up any existing temp clone dir
+    if TEMP_CLONE_DIR.exists():
+        print("🧹 Cleaning up old temp clone directory...")
+        shutil.rmtree(TEMP_CLONE_DIR)
+
+    # 2. Run download using huggingface_hub or git clone
+    print("\n📦 Downloading repository from Hugging Face Hub...")
+    download_success = False
+    try:
+        from huggingface_hub import snapshot_download
+        snapshot_download(
+            repo_id="AdityaaXD/AQI-Prediction-Model-Of-India",
+            local_dir=str(TEMP_CLONE_DIR),
+        )
+        print("✅ Repository downloaded successfully via huggingface_hub API!")
+        download_success = True
+    except Exception as e_api:
+        print(f"⚠️ huggingface_hub snapshot_download failed ({e_api}), trying git clone...")
+        try:
+            subprocess.run(
+                ["git", "clone", REPO_URL, str(TEMP_CLONE_DIR)],
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True
+            )
+            print("✅ Repository cloned successfully via Git!")
+            download_success = True
+        except Exception as e_git:
+            print(f"❌ Git clone also failed: {e_git}")
+            return False
+
+    # 3. Locate the model files (.pkl, .json, etc.) and move them to models/
+    print("\n🔍 Searching for model files in cloned repository...")
+    model_files = list(TEMP_CLONE_DIR.glob("**/*.pkl")) + list(TEMP_CLONE_DIR.glob("**/*.json")) + list(TEMP_CLONE_DIR.glob("**/*.joblib"))
+    
+    if not model_files:
+        print("⚠️ No direct pickle/json model files found. Listing all files in repository:")
+        for file in TEMP_CLONE_DIR.glob("*"):
+            if file.is_file():
+                print(f"  - {file.name}")
+        # Copy everything to a dedicated directory in models
+        dest_dir = MODELS_DIR / "AQI-Prediction-Model-Of-India"
+        if dest_dir.exists():
+            shutil.rmtree(dest_dir)
+        shutil.copytree(TEMP_CLONE_DIR, dest_dir)
+        print(f"✅ Moved all files to {dest_dir}")
+    else:
+        # Move found model files directly into models/
+        for model_file in model_files:
+            dest_path = MODELS_DIR / model_file.name
+            shutil.copy2(model_file, dest_path)
+            print(f"✨ Copied {model_file.name} -> {dest_path}")
+            
+    # 4. Cleanup temp folder
+    try:
+        print("🧹 Cleaning up temp clone directory...")
+        shutil.rmtree(TEMP_CLONE_DIR)
+        print("✅ Cleanup complete.")
+    except Exception as e:
+        print(f"⚠️ Warning: Could not clean up temp directory: {e}")
+
+    print("\n🎉 Model download and setup successfully completed!")
+    return True
+
+if __name__ == "__main__":
+    download_model()

main.py

@@ -0,0 +1,194 @@
+"""
+AQI Intelligence Engine — FastAPI Main Application
+
+The central entry point that:
+1. Loads all AI models on startup
+2. Registers all API routers
+3. Serves both locally and on HuggingFace Spaces (Docker)
+"""
+
+import logging
+import sys
+import io
+
+# Fix Windows console encoding for emoji rendering
+if sys.platform.startswith("win"):
+    try:
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')
+    except AttributeError:
+        pass
+
+import time
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from pydantic import BaseModel, Field
+from config import SERVER_CONFIG, DEVICE
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    models_loaded: bool = False
+    device: str = "cpu"
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    version: str = "2.0.0"
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+logger = logging.getLogger("aqi_engine")
+
+# Track model loading state
+models_loaded = False
+startup_time = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Load AI models on startup, clean up on shutdown."""
+    global models_loaded, startup_time
+
+    logger.info("=" * 60)
+    logger.info("🚀 AQI Intelligence Engine — Starting Up")
+    logger.info(f"   Device: {DEVICE}")
+    logger.info("=" * 60)
+
+    import asyncio
+    import anyio
+
+    async def load_models_bg():
+        global models_loaded, startup_time
+        bg_start = time.time()
+        
+        try:
+            from services.forecast.service import load_model as load_forecast
+            await anyio.to_thread.run_sync(load_forecast)
+            logger.info("✅ Forecast model loaded successfully")
+        except Exception as e:
+            logger.warning(f"Forecast model loading deferred: {e}")
+
+        # Heavy vision/segmentation models are loaded on-demand to prevent OOM crashes in container
+        logger.info("💤 Vision & Segmentation models deferred to on-demand loading")
+
+        elapsed = round(time.time() - bg_start, 2)
+        models_loaded = True
+        startup_time = elapsed
+        logger.info(f"✅ Startup models loaded in {elapsed}s")
+
+    # Start loading in background without blocking port binding
+    asyncio.create_task(load_models_bg())
+    
+    logger.info(f"📡 API docs: http://localhost:{SERVER_CONFIG['port']}/docs")
+    logger.info("=" * 60)
+
+    yield  # Application runs here
+
+    logger.info("Shutting down AQI Intelligence Engine...")
+
+
+# =============================================================================
+# FastAPI Application
+# =============================================================================
+
+app = FastAPI(
+    title="AQI Intelligence Engine",
+    description=(
+        "AI-powered Urban Air Quality Intelligence Platform for Smart City Intervention. "
+        "Provides AQI forecasting (TimesFM 2.5), satellite vision analysis (Florence-2 + "
+        "Grounding DINO), segmentation (SAM2), geospatial analysis, hotspot detection, "
+        "atmospheric dispersion modeling, source attribution, health risk assessment, "
+        "and inspector route optimization."
+    ),
+    version="2.0.0",
+    lifespan=lifespan,
+)
+
+# =============================================================================
+# CORS Middleware (allow Next.js frontend to call this API)
+# =============================================================================
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production: restrict to your Next.js domain
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# =============================================================================
+# Register Routers
+# =============================================================================
+
+from routers.services import services_router
+
+app.include_router(services_router, prefix="/api/v1")
+app.include_router(services_router)
+
+
+# =============================================================================
+# Mount Frontend Static Files & Serve index.html at Root
+# =============================================================================
+
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+import os
+
+# Create frontend directory if it doesn't exist yet
+os.makedirs("frontend", exist_ok=True)
+
+# Mount the static directory
+app.mount("/frontend", StaticFiles(directory="frontend"), name="frontend")
+
+
+
+# =============================================================================
+# Health Check
+# =============================================================================
+
+@app.get("/health", response_model=HealthResponse, tags=["System"])
+async def health_check():
+    """Health check endpoint — verifies the server and models are running."""
+    return HealthResponse(
+        status="ok",
+        models_loaded=models_loaded,
+        device=DEVICE,
+        timestamp=datetime.now(timezone.utc),
+        version="2.0.0",
+    )
+
+
+@app.get("/", tags=["System"])
+async def root():
+    """Root endpoint serving the interactive control center dashboard."""
+    index_path = os.path.join("frontend", "index.html")
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    return {
+        "name": "AQI Intelligence Engine",
+        "version": "2.0.0",
+        "message": "Frontend dashboard not built yet. Visit /docs for APIs.",
+        "docs": "/docs",
+        "health": "/health"
+    }
+
+
+# =============================================================================
+# Run with: uvicorn main:app --reload --port 7860
+# =============================================================================
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "main:app",
+        host=SERVER_CONFIG["host"],
+        port=SERVER_CONFIG["port"],
+        reload=SERVER_CONFIG["reload"],
+        workers=SERVER_CONFIG["workers"],
+        reload_excludes=["models/*", "**/models/*", "*.json", "frontend/*"],
+    )

models/.gitkeep

@@ -0,0 +1,2 @@
+# Keep this directory for downloaded model weights
+# This directory is gitignored — models are downloaded at runtime

requirements.txt

@@ -0,0 +1,49 @@
+# =============================================================================
+# AQI Intelligence Engine — Dependencies
+# =============================================================================
+
+# --- Core API Framework & Gradio Interface ---
+fastapi>=0.115,<1.0.0
+uvicorn[standard]>=0.32
+pydantic>=2.10
+python-multipart>=0.0.12
+gradio>=4.44.0,<5.0.0
+starlette>=0.36.0,<1.0.0
+jinja2>=3.1.0,<3.1.5
+
+# --- AI / ML Models ---
+torch>=2.1
+transformers>=4.48
+huggingface_hub>=0.23.0,<0.25.0
+timm>=1.0
+timesfm[torch]>=2.0
+spaces>=0.28.3  # Hugging Face ZeroGPU SDK (falls back to CPU outside HF)
+
+# --- Data & Computation ---
+numpy>=1.26
+pandas>=2.2
+scipy>=1.14
+scikit-learn>=1.5
+xgboost>=2.0.0
+hdbscan>=0.8.40
+
+# --- Geospatial ---
+geopandas>=1.0
+shapely>=2.0
+h3>=4.1
+# rasterio>=1.4  # Optional: uncomment if using local raster files
+
+# --- Optimization ---
+ortools>=9.11
+
+# --- HTTP Client ---
+httpx>=0.27
+
+# --- Image Processing ---
+Pillow>=10.4
+
+# --- Caching ---
+cachetools>=5.5
+
+# --- Utilities ---
+python-dotenv>=1.0

routers/__init__.py

@@ -0,0 +1 @@
+"""Routers package — FastAPI route definitions."""

routers/services.py

@@ -0,0 +1,89 @@
+"""
+Individual service routers — stand-alone TimesFM forecast and Vision endpoints.
+"""
+
+import logging
+import base64
+import io
+import time
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from PIL import Image
+
+from services.forecast.service import forecast_aqi
+from services.vision.service import detect_pollution_sources
+
+logger = logging.getLogger("aqi_engine.services_router")
+
+services_router = APIRouter(tags=["Model Services"])
+
+class DirectForecastRequest(BaseModel):
+    aqi_history: list[float]
+    forecast_steps: int = 24
+    lat: float = None
+    lon: float = None
+
+@services_router.post("/forecast")
+async def forecast_endpoint(request: DirectForecastRequest):
+    """
+    Run TimesFM forecasting directly using the provided historical AQI list from the client.
+    """
+    try:
+        result = await forecast_aqi(
+            request.aqi_history,
+            lat=request.lat,
+            lon=request.lon
+        )
+        return result
+    except Exception as e:
+        logger.error(f"Forecast endpoint error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+class AnalysisRequest(BaseModel):
+    image_base64: str
+
+class AnalysisResponse(BaseModel):
+    scene_description: str = ""
+    detections: list = []
+    pollution_sources: list = []
+    source_count: dict = {}
+    severity: str = "unknown"
+    processing_time_seconds: float = 0
+    error: str = None
+
+@services_router.post("/analyze-image", response_model=AnalysisResponse)
+async def analyze_image_endpoint(request: AnalysisRequest):
+    """
+    Run Florence-2 and Grounding DINO on-demand for a single satellite image.
+    Uses the provided base64 image and returns detections/scene description.
+    """
+    start_time = time.time()
+    logger.info("🧠 Vision AI analysis requested for base64 image")
+    try:
+        if not request.image_base64:
+            return AnalysisResponse(error="No image data provided")
+
+        # Decode base64 to PIL Image
+        base64_str = request.image_base64
+        if "," in base64_str:
+            base64_str = base64_str.split(",", 1)[1]
+        img_data = base64.b64decode(base64_str)
+        pil_image = Image.open(io.BytesIO(img_data)).convert("RGB")
+
+        # Run vision pipeline
+        vision_result = await detect_pollution_sources(pil_image)
+
+        elapsed = round(time.time() - start_time, 2)
+        return AnalysisResponse(
+            scene_description=vision_result.get("scene_description", ""),
+            detections=vision_result.get("detections", []),
+            pollution_sources=vision_result.get("pollution_sources_found", []),
+            source_count=vision_result.get("source_count", {}),
+            severity=vision_result.get("severity", "unknown"),
+            processing_time_seconds=elapsed,
+        )
+
+    except Exception as e:
+        logger.error(f"Vision analysis endpoint failed: {e}")
+        return AnalysisResponse(error=str(e))

services/__init__.py

@@ -0,0 +1 @@
+"""Services package — all AI service modules."""

services/forecast/__init__.py

@@ -0,0 +1 @@
+""""""

services/forecast/service.py

@@ -0,0 +1,621 @@
+"""
+AQI Forecasting Service — Tuned XGBoost (India Flagship) & Google TimesFM 2.5.
+
+Combines high-accuracy local tabular regression (XGBoost) with general-purpose
+univariate time series foundation models (TimesFM).
+"""
+
+import logging
+import joblib
+import pandas as pd
+from datetime import datetime, timezone, timedelta
+from typing import Optional
+
+import numpy as np
+import torch
+import httpx
+
+from config import get_device, get_torch_dtype, MODELS, FORECAST_CONFIG, AQI_BREAKPOINTS, API_KEYS
+
+logger = logging.getLogger(__name__)
+
+# Global model references — loaded once at startup
+_xgboost_model = None
+_scaler = None
+_timesfm_model = None
+_model_type = None  # "xgboost", "timesfm_native", "transformers", or "fallback"
+
+
+def load_model() -> bool:
+    """
+    Load the forecasting models into memory.
+    Prioritizes loading the tuned XGBoost flagship model, and falls back to
+    TimesFM or statistical baselines if it is not available.
+    """
+    global _timesfm_model, _xgboost_model, _scaler, _model_type
+
+    if _xgboost_model is not None or _timesfm_model is not None:
+        return True
+
+    # Attempt 1: Tuned XGBoost Model (Flagship model of Breathe Easy)
+    try:
+        import os
+        from pathlib import Path
+        
+        # Paths for model checkpoints
+        base_dir = Path(__file__).parent.parent.parent
+        model_path = base_dir / "models" / "best_xgboost_tuned.pkl"
+        scaler_path = base_dir / "models" / "scaler.pkl"
+
+        if not (model_path.exists() and scaler_path.exists()):
+            logger.info("XGBoost model files not found locally. Attempting automatic download from Hugging Face Hub...")
+            try:
+                from download_new_model import download_model
+                download_model()
+            except Exception as e_dl:
+                logger.warning(f"Automatic XGBoost model download failed: {e_dl}")
+
+        if model_path.exists() and scaler_path.exists():
+            logger.info("Loading Tuned XGBoost model & StandardScaler...")
+            _xgboost_model = joblib.load(str(model_path))
+            _scaler = joblib.load(str(scaler_path))
+            _model_type = "xgboost"
+            logger.info("✅ Tuned XGBoost model and Scaler loaded successfully!")
+            return True
+        else:
+            logger.warning(f"XGBoost model files still not found after download attempt. Trying TimesFM...")
+    except Exception as e:
+        logger.warning(f"Failed to load tuned XGBoost model: {e}")
+
+    # Attempt 2: timesfm native library (Google Research standard)
+    try:
+        import timesfm
+        logger.info("Loading TimesFM 2.5 via native timesfm library...")
+        _timesfm_model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+            MODELS["timesfm"]
+        )
+        _timesfm_model.compile(
+            timesfm.ForecastConfig(
+                max_context=FORECAST_CONFIG["max_context"],
+                max_horizon=FORECAST_CONFIG["max_horizon"],
+                use_continuous_quantile_head=True,
+            )
+        )
+        _model_type = "timesfm_native"
+        logger.info("✅ TimesFM loaded via native library")
+        return True
+    except Exception as e:
+        logger.warning(f"Native timesfm loading failed: {e}")
+
+    # Attempt 3: HuggingFace transformers
+    try:
+        from transformers import AutoModel
+        device = get_device()
+        logger.info(f"Loading TimesFM 2.5 via transformers on {device}...")
+        _timesfm_model = AutoModel.from_pretrained(
+            MODELS["timesfm"],
+            trust_remote_code=True,
+            dtype=get_torch_dtype(),
+        ).to(device).eval()
+        _model_type = "transformers"
+        logger.info(f"✅ TimesFM loaded via transformers on {device}")
+        return True
+    except Exception as e:
+        logger.warning(f"transformers loading failed: {e}")
+
+    logger.error("❌ No forecasting models could be loaded. Using statistical fallback.")
+    _model_type = "fallback"
+    return False
+
+
+async def forecast_aqi(
+    historical_aqi: list[float],
+    weather_data: Optional[dict] = None,
+    traffic_data: Optional[dict] = None,
+    lat: Optional[float] = None,
+    lon: Optional[float] = None,
+) -> dict:
+    """
+    Forecast AQI for 24h, 48h, and 72h horizons.
+    Integrates univariate TimesFM foundation predictions with meteorological
+    forecasts and traffic congestion covariates. If the tuned XGBoost model
+    is loaded, it runs the flagship tabular prediction instead.
+
+    Args:
+        historical_aqi: List of hourly AQI values (oldest first, at least 24 values).
+        weather_data: Optional weather forecast dict for covariate context.
+        traffic_data: Optional traffic data dict.
+        lat: Optional latitude for XGBoost telemetry fetch.
+        lon: Optional longitude for XGBoost telemetry fetch.
+
+    Returns:
+        Forecast dict with point estimates, quantiles, and metadata.
+    """
+    # Ensure models are loaded
+    load_model()
+
+    if len(historical_aqi) < 24:
+        logger.warning(f"Only {len(historical_aqi)} historical points. Padding.")
+        # Pad with mean of available data
+        mean_val = np.mean(historical_aqi) if historical_aqi else 150
+        historical_aqi = [mean_val] * (24 - len(historical_aqi)) + historical_aqi
+
+    # Clean data: interpolate NaN/None values
+    series = np.array(historical_aqi, dtype=np.float32)
+    series = _interpolate_missing(series)
+
+    # Determine forecast horizon
+    horizon = FORECAST_CONFIG["horizon_72h"]
+
+    # Dispatch to appropriate model
+    quantile_forecast = None
+    
+    if _model_type == "xgboost" and lat is not None and lon is not None:
+        logger.info("🔮 Running forecasting using tuned XGBoost model...")
+        point_forecast, quantile_forecast = await _forecast_xgboost(series, horizon, lat, lon)
+        if point_forecast is None:
+            # Telemetry fetch failed, fallback to statistical
+            logger.warning("XGBoost failed, falling back to statistical method.")
+            point_forecast, quantile_forecast = _forecast_statistical(series, horizon)
+    else:
+        if _model_type == "timesfm_native":
+            point_forecast, quantile_forecast = _forecast_native(series, horizon)
+        elif _model_type == "transformers":
+            point_forecast, quantile_forecast = _forecast_transformers(series, horizon)
+        else:
+            point_forecast, quantile_forecast = _forecast_statistical(series, horizon)
+
+        # --- Multivariate Meteorology & Traffic Adjustments for TimesFM/Statistical ---
+        base_forecast = np.copy(point_forecast)
+        point_forecast = _apply_multivariate_adjustments(
+            point_forecast, float(series[-1]), weather_data, traffic_data
+        )
+        if quantile_forecast is not None:
+            adjusted_quantiles = np.copy(quantile_forecast)
+            for t in range(len(point_forecast)):
+                ratio = point_forecast[t] / max(base_forecast[t], 1)
+                adjusted_quantiles[t] = quantile_forecast[t] * ratio
+            quantile_forecast = adjusted_quantiles
+
+    # Extract 24h/48h/72h forecasts
+    current_aqi = float(series[-1])
+    h24 = min(FORECAST_CONFIG["horizon_24h"], len(point_forecast)) - 1
+    h48 = min(FORECAST_CONFIG["horizon_48h"], len(point_forecast)) - 1
+    h72 = min(FORECAST_CONFIG["horizon_72h"], len(point_forecast)) - 1
+
+    forecasts = {}
+    for label, idx in [("24h", h24), ("48h", h48), ("72h", h72)]:
+        val = float(np.clip(point_forecast[idx], 0, 500))
+        if quantile_forecast is not None and len(quantile_forecast) > idx:
+            q = quantile_forecast[idx]
+            p10 = float(np.clip(q[0] if len(q) > 0 else val * 0.85, 0, 500))
+            p50 = float(np.clip(q[1] if len(q) > 1 else val, 0, 500))
+            p90 = float(np.clip(q[2] if len(q) > 2 else val * 1.15, 0, 500))
+        else:
+            p10 = float(np.clip(val * 0.85, 0, 500))
+            p50 = val
+            p90 = float(np.clip(val * 1.15, 0, 500))
+
+        forecasts[label] = {
+            "value": round(val, 1),
+            "p10": round(p10, 1),
+            "p50": round(p50, 1),
+            "p90": round(p90, 1),
+        }
+
+    # Determine trend
+    if forecasts["72h"]["value"] > current_aqi * 1.1:
+        trend = "increasing"
+    elif forecasts["72h"]["value"] < current_aqi * 0.9:
+        trend = "decreasing"
+    else:
+        trend = "stable"
+
+    # Calculate confidence based on forecast spread
+    spreads = [(f["p90"] - f["p10"]) / max(f["value"], 1) for f in forecasts.values()]
+    avg_spread = np.mean(spreads)
+    confidence = round(max(0.3, min(0.99, 1.0 - avg_spread)), 2)
+
+    # AQI category for 24h forecast
+    category = _get_aqi_category(forecasts["24h"]["value"])
+
+    hourly = [round(float(np.clip(v, 0, 500)), 1) for v in point_forecast[:horizon]]
+
+    model_label = "Tuned XGBoost Regressor (Breathe Easy)" if _model_type == "xgboost" else f"timesfm-2.5-200m ({_model_type})"
+
+    return {
+        "forecasts": forecasts,
+        "hourly": hourly,
+        "confidence": confidence,
+        "trend": trend,
+        "current_aqi": round(current_aqi, 1),
+        "category": category,
+        "model": model_label,
+    }
+
+
+def _forecast_native(series: np.ndarray, horizon: int):
+    """Forecast using native timesfm library."""
+    try:
+        point_forecast, quantile_forecast = _timesfm_model.forecast(
+            horizon=horizon,
+            inputs=[series],
+        )
+        return point_forecast[0], quantile_forecast[0] if quantile_forecast is not None else None
+    except Exception as e:
+        logger.error(f"Native forecast failed: {e}")
+        return _forecast_statistical(series, horizon)
+
+
+def _forecast_transformers(series: np.ndarray, horizon: int):
+    """Forecast using HuggingFace transformers."""
+    try:
+        device = get_device()
+        if _timesfm_model is not None and hasattr(_timesfm_model, "to"):
+            _timesfm_model.to(device)
+
+        # Convert inputs to expected shapes (batch_size=1, context_len)
+        past_values = torch.tensor(series, dtype=torch.float32).unsqueeze(0).to(device)
+        
+        # Construct past_values_padding: False everywhere (valid data)
+        past_values_padding = torch.zeros_like(past_values, dtype=torch.bool).to(device)
+        
+        # freq parameter (0 corresponds to standard frequency indicator for transformers implementation)
+        freq = torch.zeros((1,), dtype=torch.long).to(device)
+
+        with torch.no_grad():
+            outputs = _timesfm_model(
+                past_values=past_values,
+                past_values_padding=past_values_padding,
+                freq=freq,
+            )
+
+        mean_pred = outputs.mean_predictions.float().cpu().numpy()[0]
+
+        # Extract quantiles if available
+        quantile_pred = None
+        if hasattr(outputs, "quantile_predictions") and outputs.quantile_predictions is not None:
+            quantile_pred = outputs.quantile_predictions.float().cpu().numpy()[0]
+
+        return mean_pred[:horizon], quantile_pred[:horizon] if quantile_pred is not None else None
+    except Exception as e:
+        logger.error(f"Transformers forecast failed: {e}")
+        return _forecast_statistical(series, horizon)
+
+
+def _forecast_statistical(series: np.ndarray, horizon: int):
+    """
+    Statistical fallback when TimesFM is unavailable.
+    Uses exponential smoothing + diurnal pattern extraction.
+    """
+    logger.info("Using statistical fallback forecast.")
+    n = len(series)
+
+    # Extract diurnal pattern (24-hour cycle)
+    if n >= 48:
+        daily_pattern = np.zeros(24)
+        counts = np.zeros(24)
+        for i in range(n):
+            hour = i % 24
+            daily_pattern[hour] += series[i]
+            counts[hour] += 1
+        daily_pattern = daily_pattern / np.maximum(counts, 1)
+    else:
+        daily_pattern = np.full(24, np.mean(series))
+
+    # Exponential smoothing for trend
+    alpha = 0.3
+    level = series[-1]
+    trend_val = np.mean(np.diff(series[-24:])) if n >= 25 else 0
+
+    forecast = np.zeros(horizon)
+    for i in range(horizon):
+        hour = (n + i) % 24
+        seasonal = daily_pattern[hour] - np.mean(daily_pattern)
+        forecast[i] = level + trend_val * (i + 1) + seasonal
+
+        # Dampen trend over time
+        trend_val *= 0.95
+
+    # Add noise for quantile estimation
+    noise_std = np.std(series[-24:]) if n >= 24 else 20
+    quantiles = np.zeros((horizon, 3))
+    for i in range(horizon):
+        spread = noise_std * np.sqrt(i + 1) * 0.3
+        quantiles[i, 0] = forecast[i] - spread  # P10
+        quantiles[i, 1] = forecast[i]            # P50
+        quantiles[i, 2] = forecast[i] + spread  # P90
+
+    return forecast, quantiles
+
+
+def _interpolate_missing(series: np.ndarray) -> np.ndarray:
+    """Replace NaN values with linear interpolation."""
+    nans = np.isnan(series)
+    if not np.any(nans):
+        return series
+
+    x = np.arange(len(series))
+    series[nans] = np.interp(x[nans], x[~nans], series[~nans])
+    return series
+
+
+def _get_aqi_category(value: float) -> str:
+    """Map AQI value to NAQI category."""
+    for category, (low, high) in AQI_BREAKPOINTS.items():
+        if low <= value <= high:
+            return category.replace("_", " ").title()
+    return "Severe" if value > 400 else "Good"
+
+
+def _apply_multivariate_adjustments(
+    base_forecast: np.ndarray,
+    current_aqi: float,
+    weather_forecast: Optional[dict],
+    traffic_data: Optional[dict],
+) -> np.ndarray:
+    """
+    Adjust the univariate TimesFM forecast by integrating meteorological covariates
+    (wind speed, precipitation, humidity, temperature) and traffic congestion patterns.
+    """
+    from datetime import datetime
+    n_steps = len(base_forecast)
+    adjusted = np.copy(base_forecast)
+    
+    # 1. Extract weather forecast lists or fallback constants
+    wind_speeds = [10.0] * n_steps
+    humidities = [50.0] * n_steps
+    precip_probs = [0.0] * n_steps
+    temperatures = [25.0] * n_steps
+
+    if weather_forecast:
+        # Check if lists are available (typical forecast structure)
+        if isinstance(weather_forecast.get("wind_speed"), list) and len(weather_forecast["wind_speed"]) >= n_steps:
+            wind_speeds = weather_forecast["wind_speed"][:n_steps]
+            humidities = weather_forecast.get("humidity", [50.0] * n_steps)[:n_steps]
+            precip_probs = weather_forecast.get("precip_probability", [0.0] * n_steps)[:n_steps]
+            temperatures = weather_forecast.get("temperature", [25.0] * n_steps)[:n_steps]
+        else:
+            # Single value fallback (if current weather dict is passed)
+            wind_speeds = [float(weather_forecast.get("wind_speed", 10.0))] * n_steps
+            humidities = [float(weather_forecast.get("humidity", 50.0))] * n_steps
+            precip_probs = [float(weather_forecast.get("precipitation", 0.0)) * 10] * n_steps
+            temperatures = [float(weather_forecast.get("temperature", 25.0))] * n_steps
+
+    # 2. Extract traffic congestion index
+    congestion_index = 0.5
+    if traffic_data:
+        congestion_index = float(traffic_data.get("congestion_index", 0.5))
+
+    current_hour = datetime.now().hour
+
+    for t in range(n_steps):
+        hour = (current_hour + t) % 24
+        val = adjusted[t]
+
+        # --- A. METEOROLOGY ADJUSTMENTS ---
+        
+        # Wind Dispersion: Soften the wind speed dispersion scaling bounds to prevent over-suppression.
+        w_speed = float(wind_speeds[t])
+        wind_mult = 10.0 / max(4.0, w_speed)
+        wind_mult = np.clip(wind_mult, 0.85, 1.20)
+
+        # Precipitation Washout: Rain washes out particulate matter.
+        rain_prob = float(precip_probs[t])
+        washout_effect = 0.0
+        if rain_prob > 20:
+            washout_effect = -0.05 - 0.15 * ((rain_prob - 20) / 80)
+
+        # Humidity Pollutant Trapping: High humidity traps smog.
+        humidity = float(humidities[t])
+        humidity_effect = 0.0
+        if humidity > 70:
+            humidity_effect = 0.10 * ((humidity - 70) / 30)
+
+        # Temperature Inversion (cold trapping)
+        temp = float(temperatures[t])
+        temp_effect = 0.0
+        if temp < 15 and humidity > 75:
+            temp_effect = 0.06
+
+        # --- B. TRAFFIC CONGESTION ADJUSTMENTS ---
+        # Traffic peaks in urban areas (morning 8-10 AM, evening 6-9 PM)
+        traffic_multiplier = 0.0
+        if hour in (8, 9, 10):
+            traffic_multiplier = 0.12 * congestion_index
+        elif hour in (17, 18, 19, 20):
+            traffic_multiplier = 0.18 * congestion_index
+        elif hour in (0, 1, 2, 3, 4):
+            traffic_multiplier = -0.08  # Night-time dip
+
+        # --- C. DIURNAL AND SEASONAL OFFSET ---
+        # Add a diurnal cyclic baseline correction (peaks around morning and night, dips in afternoon)
+        # Indian cities peak around 8 AM (rush hour + inversion) and 9 PM (heavy trucks + evening cooling)
+        diurnal_offset = 8.0 * np.sin(2.0 * np.pi * (hour - 6.0) / 24.0)
+
+        # --- D. COMBINE ADJUSTMENTS ---
+        # Apply multipliers
+        weather_scale = 1.0 + humidity_effect + temp_effect + washout_effect
+        val = val * weather_scale * wind_mult
+        val = val * (1.0 + traffic_multiplier)
+        
+        # Apply additive diurnal shift
+        val += diurnal_offset
+        
+        adjusted[t] = np.clip(val, 15, 500)
+
+    return adjusted
+
+
+# =============================================================================
+# XGBoost Flagship Model Helpers
+# =============================================================================
+
+async def _fetch_full_history_covariates(lat: float, lon: float, hours: int = 168) -> list[dict]:
+    """Fetch complete pollutant history from OpenWeather."""
+    api_key = API_KEYS.get("openweather", "")
+    if not api_key:
+        return []
+
+    url = "http://api.openweathermap.org/data/2.5/air_pollution/history"
+    now = int(datetime.now(timezone.utc).timestamp())
+    start = now - (hours * 3600)
+
+    try:
+        async with httpx.AsyncClient(timeout=30) as client:
+            resp = await client.get(
+                url,
+                params={"lat": lat, "lon": lon, "start": start, "end": now, "appid": api_key},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+        records = []
+        for entry in data.get("list", []):
+            components = entry.get("components", {})
+            pm25 = components.get("pm2_5", 0)
+            aqi_val = _pm25_to_india_aqi(pm25) if pm25 > 0 else 150
+            dt = datetime.fromtimestamp(entry.get("dt", 0), tz=timezone.utc)
+
+            records.append({
+                "timestamp": dt,
+                "AQI": aqi_val,
+                "PM2.5": pm25,
+                "PM10": components.get("pm10", 0),
+                "NO": components.get("no", 0),
+                "NO2": components.get("no2", 0),
+                "SO2": components.get("so2", 0),
+                "CO": components.get("co", 0) / 1000.0,  # mg/m3
+                "O3": components.get("o3", 0),
+                "NH3": components.get("nh3", 0),
+            })
+        
+        return sorted(records, key=lambda x: x["timestamp"])
+    except Exception as e:
+        logger.error(f"Failed to fetch historical pollutants: {e}")
+        return []
+
+
+def _engineer_xgboost_features(df: pd.DataFrame, target_idx: int) -> pd.DataFrame:
+    """Engineer all 38 features for the record at target_idx."""
+    slice_df = df.iloc[:target_idx+1].copy()
+    row = slice_df.iloc[-1].copy()
+    dt = row["timestamp"]
+
+    # 1. Base pollutants
+    feats = {
+        "PM2.5": row["PM2.5"],
+        "PM10": row["PM10"],
+        "NO": row["NO"],
+        "NO2": row["NO2"],
+        "NOx": row["NO"] + row["NO2"],
+        "NH3": row["NH3"],
+        "CO": row["CO"],
+        "SO2": row["SO2"],
+        "O3": row["O3"],
+        "Benzene": 1.5,
+        "Toluene": 3.0,
+        "Xylene": 1.0,
+    }
+
+    # 2. Temporal features
+    feats["Month"] = dt.month
+    feats["DayOfWeek"] = dt.weekday()
+    feats["Year"] = dt.year
+    feats["Day"] = dt.day
+    feats["DayOfYear"] = dt.timetuple().tm_yday
+    feats["Quarter"] = (dt.month - 1) // 3 + 1
+    feats["IsWeekend"] = 1 if dt.weekday() >= 5 else 0
+
+    # 3. Cyclical encodings
+    feats["Month_sin"] = np.sin(2 * np.pi * dt.month / 12.0)
+    feats["Month_cos"] = np.cos(2 * np.pi * dt.month / 12.0)
+    feats["DOW_sin"] = np.sin(2 * np.pi * dt.weekday() / 7.0)
+    feats["DOW_cos"] = np.cos(2 * np.pi * dt.weekday() / 7.0)
+
+    # 4. Lags
+    feats["AQI_lag1"] = slice_df.iloc[-2]["AQI"] if len(slice_df) >= 2 else row["AQI"]
+    feats["AQI_lag3"] = slice_df.iloc[-4]["AQI"] if len(slice_df) >= 4 else row["AQI"]
+    feats["AQI_lag7"] = slice_df.iloc[-8]["AQI"] if len(slice_df) >= 8 else row["AQI"]
+    feats["PM25_lag1"] = slice_df.iloc[-2]["PM2.5"] if len(slice_df) >= 2 else row["PM2.5"]
+    feats["PM10_lag1"] = slice_df.iloc[-2]["PM10"] if len(slice_df) >= 2 else row["PM10"]
+
+    # 5. Rolling statistics
+    feats["AQI_roll_mean_7"] = slice_df["AQI"].iloc[-7:].mean() if len(slice_df) >= 7 else slice_df["AQI"].mean()
+    feats["AQI_roll_std_7"] = slice_df["AQI"].iloc[-7:].std() if len(slice_df) >= 7 else 0.0
+    feats["AQI_roll_mean_14"] = slice_df["AQI"].iloc[-14:].mean() if len(slice_df) >= 14 else slice_df["AQI"].mean()
+    feats["AQI_roll_std_14"] = slice_df["AQI"].iloc[-14:].std() if len(slice_df) >= 14 else 0.0
+    feats["AQI_roll_mean_30"] = slice_df["AQI"].iloc[-30:].mean() if len(slice_df) >= 30 else slice_df["AQI"].mean()
+    feats["PM25_roll_mean_7"] = slice_df["PM2.5"].iloc[-7:].mean() if len(slice_df) >= 7 else slice_df["PM2.5"].mean()
+
+    # 6. Ratios & interactions
+    feats["PM25_PM10_product"] = row["PM2.5"] * row["PM10"]
+    feats["NO2_NO_ratio"] = row["NO2"] / max(0.1, row["NO"])
+    feats["PM25_PM10_ratio"] = row["PM2.5"] / max(1.0, row["PM10"])
+
+    # 7. City Encoded (Delhi average baseline)
+    feats["City_encoded"] = 250.0
+
+    ordered_cols = [
+        'PM2.5', 'PM10', 'NO', 'NO2', 'NOx', 'NH3', 'CO', 'SO2', 'O3', 'Benzene', 'Toluene', 'Xylene',
+        'Month', 'DayOfWeek', 'Year', 'Day', 'DayOfYear', 'Quarter', 'IsWeekend', 'Month_sin', 'Month_cos',
+        'DOW_sin', 'DOW_cos', 'AQI_lag1', 'AQI_lag3', 'AQI_lag7', 'PM25_lag1', 'PM10_lag1',
+        'AQI_roll_mean_7', 'AQI_roll_std_7', 'AQI_roll_mean_14', 'AQI_roll_std_14', 'AQI_roll_mean_30',
+        'PM25_roll_mean_7', 'PM25_PM10_product', 'NO2_NO_ratio', 'PM25_PM10_ratio', 'City_encoded'
+    ]
+    return pd.DataFrame([feats])[ordered_cols]
+
+
+async def _forecast_xgboost(
+    series: np.ndarray,
+    horizon: int,
+    lat: float,
+    lon: float,
+) -> tuple[Optional[np.ndarray], Optional[np.ndarray]]:
+    """Generate forecast using the tuned XGBoost model with recursive autoregressive scaling."""
+    import httpx
+    # Fetch 144h context + forecast horizon of full pollutants history
+    total_hours = 144 + horizon
+    records = await _fetch_full_history_covariates(lat, lon, hours=total_hours)
+
+    if not records or len(records) < 144:
+        logger.warning("Could not fetch historical telemetry for XGBoost.")
+        return None, None
+
+    df = pd.DataFrame(records)
+    predictions = []
+    
+    # Context window initialization
+    rolling_df = df.iloc[:144].copy()
+
+    for step in range(horizon):
+        if 144 + step < len(df):
+            next_row = df.iloc[144 + step].copy()
+        else:
+            prev_row = rolling_df.iloc[-1].copy()
+            next_dt = prev_row["timestamp"] + timedelta(hours=1)
+            next_row = prev_row.copy()
+            next_row["timestamp"] = next_dt
+        
+        rolling_df = pd.concat([rolling_df, pd.DataFrame([next_row])], ignore_index=True)
+        
+        target_idx = len(rolling_df) - 1
+        X_df = _engineer_xgboost_features(rolling_df, target_idx)
+        
+        X_scaled = _scaler.transform(X_df)
+        pred_val = _xgboost_model.predict(X_scaled)[0]
+        pred_val = float(np.clip(pred_val, 15, 500))
+        
+        predictions.append(pred_val)
+        rolling_df.at[target_idx, "AQI"] = pred_val
+
+    # Construct confidence quantiles (P10, P50, P90)
+    noise_std = np.std(series[-24:]) if len(series) >= 24 else 20
+    quantiles = np.zeros((horizon, 3))
+    for i in range(horizon):
+        spread = noise_std * np.sqrt(i + 1) * 0.25
+        quantiles[i, 0] = predictions[i] - spread
+        quantiles[i, 1] = predictions[i]
+        quantiles[i, 2] = predictions[i] + spread
+
+    return np.array(predictions), quantiles

services/vision/__init__.py

@@ -0,0 +1 @@
+""""""

services/vision/service.py

@@ -0,0 +1,341 @@
+"""
+Vision Service — Florence-2 (scene understanding) + Grounding DINO (zero-shot detection).
+
+Two-model pipeline:
+1. Florence-2: Generates scene captions & open-vocabulary detection
+2. Grounding DINO: Zero-shot detection with pollution-specific text prompts
+"""
+
+import logging
+from typing import Optional
+
+import torch
+from PIL import Image
+
+from config import get_device, get_torch_dtype, MODELS, VISION_CONFIG
+
+logger = logging.getLogger(__name__)
+
+# Global model references
+_florence_model = None
+_florence_processor = None
+_dino_model = None
+_dino_processor = None
+
+
+def load_models() -> bool:
+    """Load Florence-2 and Grounding DINO models."""
+    success = True
+    success = _load_florence() and success
+    success = _load_grounding_dino() and success
+    return success
+
+
+def _load_florence() -> bool:
+    """Load Florence-2-base model."""
+    global _florence_model, _florence_processor
+    if _florence_model is not None:
+        return True
+
+    try:
+        from transformers import AutoProcessor, AutoModelForCausalLM, PreTrainedModel
+        logger.info("Loading Florence-2-base...")
+
+        # Apply runtime compatibility patch to PreTrainedModel base class
+        # to prevent '_supports_sdpa' or '_supports_flash_attn_2' attribute errors on dynamic HuggingFace models
+        PreTrainedModel._supports_sdpa = False
+        PreTrainedModel._supports_flash_attn_2 = False
+
+        # Apply runtime compatibility patch for Florence-2 configs on newer transformers versions
+        try:
+            from transformers.models.florence2.configuration_florence2 import Florence2LanguageConfig
+            Florence2LanguageConfig.forced_bos_token_id = None
+        except Exception:
+            pass
+
+        device = get_device()
+        dtype = get_torch_dtype()
+
+        # Try loading from local cache first (no downloads/internet check)
+        try:
+            _florence_processor = AutoProcessor.from_pretrained(
+                MODELS["florence2"],
+                trust_remote_code=True,
+                local_files_only=True
+            )
+            _florence_model = AutoModelForCausalLM.from_pretrained(
+                MODELS["florence2"],
+                torch_dtype=dtype,
+                trust_remote_code=True,
+                attn_implementation="eager",  # Avoid SDPA entirely
+                local_files_only=True
+            ).to(device).eval()
+            logger.info(f"✅ Florence-2-base loaded successfully on {device} from local cache")
+            return True
+        except Exception as e_local:
+            logger.info(f"Local cache load deferred/failed, attempting default online load: {e_local}")
+            # Fallback to standard check if local files only fails
+            _florence_processor = AutoProcessor.from_pretrained(
+                MODELS["florence2"],
+                trust_remote_code=True
+            )
+            _florence_model = AutoModelForCausalLM.from_pretrained(
+                MODELS["florence2"],
+                torch_dtype=dtype,
+                trust_remote_code=True,
+                attn_implementation="eager",
+            ).to(device).eval()
+
+        # Post-load safety check
+        if not hasattr(_florence_model, "_supports_sdpa"):
+            _florence_model._supports_sdpa = False
+
+        logger.info(f"✅ Florence-2-base loaded successfully on {device}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Florence-2 loading failed: {e}")
+        return False
+
+
+def _load_grounding_dino() -> bool:
+    """Load Grounding DINO tiny model."""
+    global _dino_model, _dino_processor
+    if _dino_model is not None:
+        return True
+
+    try:
+        from transformers import AutoProcessor, AutoModelForZeroShotObjectDetection
+        device = get_device()
+        logger.info(f"Loading Grounding DINO tiny on {device}...")
+        _dino_processor = AutoProcessor.from_pretrained(MODELS["grounding_dino"])
+        _dino_model = AutoModelForZeroShotObjectDetection.from_pretrained(
+            MODELS["grounding_dino"]
+        ).to(device).eval()
+        logger.info(f"✅ Grounding DINO loaded on {device}")
+        return True
+    except Exception as e:
+        logger.error(f"❌ Grounding DINO loading failed: {e}")
+        return False
+
+
+async def detect_pollution_sources(image: Image.Image) -> dict:
+    """
+    Run the full vision pipeline on a satellite/aerial image.
+    Supports ZeroGPU dynamic allocation and CPU fallback.
+    """
+    image = image.convert("RGB")
+
+    # Load models on-demand if they are not already loaded
+    if _florence_model is None or _dino_model is None:
+        logger.info("Vision models not loaded yet. Loading on-demand...")
+        load_models()
+
+    # Step 1: Florence-2 scene understanding
+    scene_description = await _florence_caption(image)
+    florence_detections = await _florence_detect(image)
+
+    # Step 2: Grounding DINO zero-shot detection for pollution sources
+    dino_detections = await _grounding_dino_detect(image)
+
+    # Combine and categorize detections
+    all_detections = florence_detections + dino_detections
+    pollution_sources, source_count, severity = _categorize_detections(all_detections)
+
+    return {
+        "scene_description": scene_description,
+        "detections": all_detections,
+        "pollution_sources_found": pollution_sources,
+        "source_count": source_count,
+        "severity": severity,
+        "model": "florence-2-base + grounding-dino-tiny",
+        "device_used": get_device(),
+    }
+
+
+async def _florence_caption(image: Image.Image) -> str:
+    """Generate scene description using Florence-2."""
+    if _florence_model is None or _florence_processor is None:
+        return "Vision model not loaded. Unable to describe scene."
+
+    try:
+        device = get_device()
+        _florence_model.to(device)
+        prompt = "<MORE_DETAILED_CAPTION>"
+        inputs = _florence_processor(text=prompt, images=image, return_tensors="pt").to(device)
+
+        with torch.no_grad():
+            generated_ids = _florence_model.generate(
+                input_ids=inputs["input_ids"],
+                pixel_values=inputs["pixel_values"],
+                max_new_tokens=VISION_CONFIG["florence2_max_tokens"],
+                num_beams=3,
+            )
+
+        generated_text = _florence_processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
+        parsed = _florence_processor.post_process_generation(
+            generated_text, task=prompt, image_size=(image.width, image.height)
+        )
+        return parsed.get(prompt, "No description available.")
+    except Exception as e:
+        logger.error(f"Florence-2 caption failed: {e}")
+        return f"Caption generation failed: {str(e)}"
+
+
+async def _florence_detect(image: Image.Image) -> list[dict]:
+    """Run Florence-2 open detection."""
+    if _florence_model is None or _florence_processor is None:
+        return []
+
+    try:
+        device = get_device()
+        _florence_model.to(device)
+        prompt = "<OD>"
+        inputs = _florence_processor(text=prompt, images=image, return_tensors="pt").to(device)
+
+        with torch.no_grad():
+            generated_ids = _florence_model.generate(
+                input_ids=inputs["input_ids"],
+                pixel_values=inputs["pixel_values"],
+                max_new_tokens=VISION_CONFIG["florence2_max_tokens"],
+                num_beams=3,
+            )
+
+        generated_text = _florence_processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
+        parsed = _florence_processor.post_process_generation(
+            generated_text, task=prompt, image_size=(image.width, image.height)
+        )
+
+        detections = []
+        od_result = parsed.get(prompt, {})
+        bboxes = od_result.get("bboxes", [])
+        labels = od_result.get("labels", [])
+
+        for bbox, label in zip(bboxes, labels):
+            detections.append({
+                "label": label.lower(),
+                "confidence": 0.7,  # Florence-2 doesn't return confidence
+                "bbox": {
+                    "x_min": float(bbox[0]),
+                    "y_min": float(bbox[1]),
+                    "x_max": float(bbox[2]),
+                    "y_max": float(bbox[3]),
+                },
+                "source": "florence2",
+            })
+
+        return detections
+    except Exception as e:
+        logger.error(f"Florence-2 detection failed: {e}")
+        return []
+
+
+async def _grounding_dino_detect(image: Image.Image) -> list[dict]:
+    """Run Grounding DINO zero-shot detection with pollution prompts."""
+    if _dino_model is None or _dino_processor is None:
+        return []
+
+    try:
+        device = get_device()
+        _dino_model.to(device)
+        text_prompt = VISION_CONFIG["pollution_prompts"]
+
+        inputs = _dino_processor(
+            images=image, text=text_prompt, return_tensors="pt"
+        ).to(device)
+
+        with torch.no_grad():
+            outputs = _dino_model(**inputs)
+
+        results = _dino_processor.post_process_grounded_object_detection(
+            outputs,
+            inputs.input_ids,
+            threshold=VISION_CONFIG["grounding_dino_box_threshold"],
+            text_threshold=VISION_CONFIG["grounding_dino_text_threshold"],
+            target_sizes=[image.size[::-1]],
+        )
+
+        detections = []
+        if results:
+            result = results[0]
+            boxes = result.get("boxes", [])
+            scores = result.get("scores", [])
+            labels = result.get("labels", [])  # Changed from "text_labels" to "labels"
+
+            for box, score, label in zip(boxes, scores, labels):
+                box = box.cpu().tolist() if hasattr(box, "cpu") else box
+                score_val = score.item() if hasattr(score, "item") else float(score)
+
+                detections.append({
+                    "label": label.strip().lower(),
+                    "confidence": round(score_val, 3),
+                    "bbox": {
+                        "x_min": float(box[0]),
+                        "y_min": float(box[1]),
+                        "x_max": float(box[2]),
+                        "y_max": float(box[3]),
+                    },
+                    "source": "grounding_dino",
+                })
+
+        return detections
+    except Exception as e:
+        logger.error(f"Grounding DINO detection failed: {e}")
+        return []
+
+
+def _categorize_detections(detections: list[dict]) -> tuple[list[str], dict[str, int], str]:
+    """
+    Categorize raw detections into pollution source categories.
+    Returns: (pollution_sources, source_count, severity)
+    """
+    # Mapping from detection labels to pollution categories
+    label_to_category = {
+        "smoke": "industrial_emission",
+        "fire": "burning",
+        "burning waste": "burning",
+        "open burning": "burning",
+        "construction site": "construction_dust",
+        "construction": "construction_dust",
+        "factory chimney": "industrial_emission",
+        "industrial plant": "industrial_emission",
+        "factory": "industrial_emission",
+        "dust cloud": "dust",
+        "dust": "dust",
+        "heavy vehicles": "traffic",
+        "truck": "traffic",
+        "vehicle": "traffic",
+        "car": "traffic",
+        "bus": "traffic",
+        "brick kiln": "industrial_emission",
+    }
+
+    source_count: dict[str, int] = {}
+    pollution_sources: set[str] = set()
+
+    for det in detections:
+        label = det["label"].lower()
+        for keyword, category in label_to_category.items():
+            if keyword in label:
+                pollution_sources.add(category)
+                source_count[category] = source_count.get(category, 0) + 1
+                break
+
+    # Determine severity
+    total_sources = sum(source_count.values())
+    if total_sources == 0:
+        severity = "low"
+    elif total_sources <= 3:
+        severity = "medium"
+    elif total_sources <= 8:
+        severity = "high"
+    else:
+        severity = "critical"
+
+    # Boost severity if fire/burning detected
+    if "burning" in pollution_sources or "industrial_emission" in pollution_sources:
+        if severity == "low":
+            severity = "medium"
+        elif severity == "medium":
+            severity = "high"
+
+    return sorted(list(pollution_sources)), source_count, severity