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.
| 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.
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
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"]
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
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"]
| 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 |
The Smart Bin Prediction module uses historical fill-level observations to forecast the next fill-level value.
Dataset information:
latestFullness.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.
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
git clone https://github.com/shivamdwivedicse/UrbanPulse-AI.git
cd UrbanPulse-AI
Windows PowerShell:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
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.
python -m uvicorn backend.main:app --reload
| 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 |
Run the automated Python test suite:
python -m pytest -q
The project has successfully passed 62 automated Python tests in the current development environment.
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.
UrbanPulse AI is currently a working prototype and decision-support platform.
These limitations are documented to distinguish demonstrated functionality from future deployment capabilities.
Shivam Dwivedi
B.Tech Computer Science & Engineering
Interests: Artificial Intelligence, Machine Learning, Data Science and Smart City Technologies.
GitHub: shivamdwivedicse
If you find this project interesting, consider giving this repository a star.
UrbanPulse AI โ Building cleaner, smarter and more sustainable cities through AI.