README.md

---
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.