UrbanPulse-AI

๐ŸŒ† UrbanPulse AI

Intelligent Waste Management & Smart City Operations Platform

Transforming waste management through Machine Learning, Computer Vision and Route Optimization.

UrbanPulse AI is an AI-powered smart city waste management platform designed to help city operators monitor waste levels, analyze garbage images, optimize waste collection routes and manage citizen complaints through a unified dashboard.

It combines predictive machine learning, Gemini Vision AI and mathematical optimization to support smarter and more efficient urban waste management.


โšก Understand UrbanPulse AI in 60 Seconds

Problem UrbanPulse AI Solution
Waste bins fill up unpredictably ML-based fill-level forecasting
Garbage accumulation is difficult to assess Gemini Vision image analysis
Collection routes may be inefficient OR-Tools route optimization
Citizen complaints are difficult to track Digital complaint management
City operations are spread across different systems Unified smart city dashboard

In simple words: UrbanPulse AI helps predict, analyze, prioritize and organize waste management operations from one platform.


๐Ÿš€ Key Features

1. ๐Ÿค– Smart Bin Prediction

2. ๐Ÿ“ธ AI-Powered Waste Intelligence

3. ๐Ÿ—บ๏ธ Smart Collection Route Optimization

4. ๐Ÿ™๏ธ Citizen Complaint Management

5. ๐Ÿ“Š Unified Analytics Dashboard


๐Ÿง  System Architecture

flowchart TB
    USER["City Operator / Citizen"]

    USER --> UI["UrbanPulse Web Dashboard"]

    UI --> API["FastAPI Backend"]

    API --> ML["ML Prediction Engine"]
    API --> GEMINI["Gemini Vision API"]
    API --> ROUTE["OR-Tools Optimizer"]
    API --> DB[("SQLite Database")]

    ML --> PRED["Fill-Level Forecast"]
    GEMINI --> WASTE["Waste Classification & Severity"]
    ROUTE --> OPT["Optimized Collection Sequence"]
    DB --> COMPLAINT["Complaint Records"]

    PRED --> RESULT["Unified Operations Dashboard"]
    WASTE --> RESULT
    OPT --> RESULT
    COMPLAINT --> RESULT

AI/ML Workflow

flowchart TD
    A["Historical Smart Bin Dataset"] --> B["Data Cleaning"]
    B --> C["Feature Engineering"]
    C --> D["Model Training"]
    D --> E["Model Evaluation"]
    E --> F["HistGradientBoostingRegressor"]
    F --> G["FastAPI Prediction Endpoint"]
    G --> H["Dashboard Prediction"]

Waste Image Analysis Workflow

flowchart TD
    A["Upload Waste Image"] --> B["Image Validation"]
    B --> C["FastAPI Backend"]
    C --> D["Gemini Vision API"]
    D --> E["Structured AI Response"]
    E --> F["Waste Category"]
    E --> G["Accumulation & Severity"]
    E --> H["Recommended Action"]
    F --> I["Waste Intelligence Dashboard"]
    G --> I
    H --> I

Smart Collection Route Workflow

flowchart TD
    A["Bin Information"] --> B["Coordinates & Fill Levels"]
    B --> C["Distance Matrix"]
    C --> D["Google OR-Tools"]
    D --> E["Route Optimization"]
    E --> F["Optimized Stop Sequence"]
    F --> G["Map Visualization"]

๐Ÿ› ๏ธ Technology Stack

Layer Technologies
Frontend HTML5, CSS3, JavaScript
Backend Python, FastAPI
Machine Learning Scikit-learn, Pandas, NumPy
Computer Vision Google Gemini Vision API
Optimization Google OR-Tools
Database SQLite
Maps Leaflet.js, OpenStreetMap
Testing Pytest, JavaScript tests
Version Control Git, GitHub

๐Ÿ“ˆ Machine Learning Model

The Smart Bin Prediction module uses historical fill-level observations to forecast the next fill-level value.

Dataset information:

Champion Model: HistGradientBoostingRegressor

Features used:

Reported evaluation:

Metric Result
MAE 1.3166
RMSE 1.6212
Rยฒ 0.4878

The model output is on the datasetโ€™s original 0โ€“10 scale.

These results represent historical test-set performance, not guaranteed real-world performance.


๐Ÿ“ Project Structure

UrbanPulse-AI/
โ”‚
โ”œโ”€โ”€ backend/
โ”‚   โ”œโ”€โ”€ api/
โ”‚   โ”‚   โ”œโ”€โ”€ routes_complaints.py
โ”‚   โ”‚   โ”œโ”€โ”€ routes_optimization.py
โ”‚   โ”‚   โ””โ”€โ”€ routes_waste.py
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ database/
โ”‚   โ”‚   โ””โ”€โ”€ complaint_repository.py
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ schemas/
โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ””โ”€โ”€ main.py
โ”‚
โ”œโ”€โ”€ frontend/
โ”‚   โ”œโ”€โ”€ assets/
โ”‚   โ”‚   โ”œโ”€โ”€ css/
โ”‚   โ”‚   โ””โ”€โ”€ js/
โ”‚   โ”œโ”€โ”€ home.html
โ”‚   โ””โ”€โ”€ index.html
โ”‚
โ”œโ”€โ”€ ml/
โ”‚   โ”œโ”€โ”€ models/
โ”‚   โ”œโ”€โ”€ notebooks/
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ evaluation/
โ”‚
โ”œโ”€โ”€ datasets/
โ”‚   โ””โ”€โ”€ processed/
โ”‚
โ”œโ”€โ”€ tests/
โ”‚
โ”œโ”€โ”€ docs/
โ”‚
โ”œโ”€โ”€ .env.example
โ”œโ”€โ”€ .gitignore
โ””โ”€โ”€ requirements.txt

โš™๏ธ Run Locally

Prerequisites

1. Clone the repository

git clone https://github.com/shivamdwivedicse/UrbanPulse-AI.git

cd UrbanPulse-AI

2. Create a virtual environment

Windows PowerShell:

python -m venv .venv

.\.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip

pip install -r requirements.txt

4. Configure environment variables

Copy-Item .env.example .env

Add your Gemini API key inside .env:

GEMINI_API_KEY=your_gemini_api_key

Never commit your actual .env file or API key.

5. Start the application

python -m uvicorn backend.main:app --reload

6. Open UrbanPulse AI

Resource Local URL
Application http://127.0.0.1:8000/
Dashboard http://127.0.0.1:8000/dashboard
API Documentation http://127.0.0.1:8000/docs
Health Check http://127.0.0.1:8000/health

๐Ÿงช Testing

Run the automated Python test suite:

python -m pytest -q

The project has successfully passed 62 automated Python tests in the current development environment.


๐ŸŒ Deployment

UrbanPulse AI is designed as a FastAPI application serving its frontend and backend from one application.

Recommended hosting: Render Web Service.

Deployment configuration:

Build Command:
pip install -r requirements.txt

Start Command:
uvicorn backend.main:app --host 0.0.0.0 --port $PORT

Configure GEMINI_API_KEY in the hosting providerโ€™s environment variables.

Persistent storage must be configured for SQLite complaint records and uploaded files if they need to survive restarts and redeployments.


โš ๏ธ Important Project Scope & Limitations

UrbanPulse AI is currently a working prototype and decision-support platform.

These limitations are documented to distinguish demonstrated functionality from future deployment capabilities.


๐Ÿ”ฎ Future Enhancements


๐Ÿ‘จโ€๐Ÿ’ป Project Author

Shivam Dwivedi

B.Tech Computer Science & Engineering

Interests: Artificial Intelligence, Machine Learning, Data Science and Smart City Technologies.

GitHub: shivamdwivedicse


โญ Support

If you find this project interesting, consider giving this repository a star.

UrbanPulse AI โ€” Building cleaner, smarter and more sustainable cities through AI.