Where should a taxi go next? We answer that question with AI —
combining demand forecasting, multi-agent simulation, and reinforcement learning
to help drivers earn $139 more per day on NYC's 263 taxi zones.
🌐 Live Demo · 📖 Documentation · ⚡ Quick Start · 📄 Paper Draft · 🏆 Leaderboard · 🚀 Roadmap · 💬 Discussions
|
0.9565 NDCG@3 (Two-Step MDP) |
+$139.40 Daily Fare Lift vs Hot Zone |
+$53.74 DQN Advantage per driver/day |
402 Tests CI Verified |
In one sentence: We built the most comprehensive open-source benchmark for AI-driven taxi repositioning — forecast demand, simulate competition, and let RL figure out where drivers should go next.
The problem is simple, the math is deep:
- NYC has 263 taxi zones. At any moment, each zone has some demand (people wanting rides) and some supply (empty taxis).
- A driver who just dropped off a passenger needs to decide: cruise here, or reposition to another zone?
- Competing drivers deplete the same pool of passengers. Every decision involves predicting demand AND anticipating what other drivers will do.
- This is a finite-horizon stochastic game with 263 actions, partial observability, and delayed rewards.
What makes this project different:
- ✅ Not just a paper — runnable API, interactive map, Docker one-click deploy
- ✅ Not just a model — 7 policies benchmarked: heuristic, MDP, DQN, Double DQN, IQL
- ✅ Not just results — paired statistical tests, bootstrap CIs, exposure audits, honest negative findings
- ✅ Not just NYC — CityAdapter interface; plug in Chicago, London, Singapore
docker compose up
# API → http://localhost:8000/docs | Demo → http://localhost:8501git clone https://github.com/caizefan34/urban-mobility-ai.git && cd urban-mobility-ai
pip install -e ".[dev,api,demo]"
# Try it
curl -X POST http://localhost:8000/v1/recommendations \
-H "Content-Type: application/json" \
-d '{"vehicle_id": "v001", "zone_id": 161}'| Strategy | NDCG@3 | Hit@3 | Utility@1 |
|---|---|---|---|
| Hot Zone (go where demand is highest) | 0.7846 | 0.5842 | 19.43 |
| Single-Step (one-step lookahead) | 0.9024 | 0.8804 | 25.06 |
| Two-Step (two-step MDP planning) | 0.9565 | 0.9714 | 27.59 |
| Strategy | Mean Daily Fare | vs Hot Zone |
|---|---|---|
| Hot Zone | $431.21 | — |
| Single-Step | $548.77 | +$117.56 |
| Two-Step | $570.61 | +$139.40 |
Two-Step vs Single-Step: +$21.84/day, bootstrap 95% CI [$5.00, $39.53], p = 0.0151.
| Algorithm | Avg Revenue vs Single-Step | 95% CI |
|---|---|---|
| DQN | +$53.74 | [+46.21, +61.57] |
| Double DQN | -$25.27 | [-32.77, -17.97] |
| Strategy | Avg Revenue/Driver (7d) | Utilization |
|---|---|---|
| Hot Zone | $1,233.41 | 7.3% |
| Two-Step | $1,508.71 | 9.5% |
| Single-Step | $1,764.56 | 11.1% |
Single-Step vs Hot Zone: +$531.16/driver over the window, bootstrap 95% CI [$525.64, $536.67], paired t p < 0.001. Revenue figures are 7-day simulator totals (finite-demand multi-agent, 30 runs) — not daily earnings.
At fixed fleet size, raising demand/supply ratio from 0.5x to 2.0x increases Single-Step utilization from 6.42% to 18.53%.
| Model | MAE | RMSE |
|---|---|---|
| Historical Average | 1.7273 | 5.9237 |
| LightGBM | 1.5114 | 5.0707 |
| Ensemble (LGB + XGB) | 1.4868 | 4.9810 |
| Model | MAE |
|---|---|
| LightGBM (non-graph) | 1.5114 |
| GraphSAGE | 1.5037 |
GraphSAGE improves MAE by 0.51% over non-graph LightGBM, but the timestamp-level 95% CI [-0.0042, +0.0200] crosses zero — the graph-neural contribution is not statistically supported at this sample size. See outputs/graph_benchmark.md.
Surprising finding: Better forecast accuracy does NOT equal better decisions. The forecast-enhanced strategy scores -$17.88/day vs the simpler historical version. This "prediction-policy gap" is one of the platform's key research contributions. See Decision-Aware Forecasting.
NYC TLC Raw Trips (2009-2024)
│
▼
Data Pipeline (chronological split, 263 zones)
│
├──────────────────┬──────────────────┐
▼ ▼ ▼
Demand Forecast OD Graph Learning Decision Engine
LightGBM/XGBoost GraphSAGE/GAT MDP / DQN / IQL
│ │ │
└──────────────────┴──────────────────┘
│
▼
Multi-Agent Simulator v2
(finite demand, explicit competition)
│
▼
Policy Evaluation
WIS / Doubly Robust / Bootstrap CI
│
┌────────────┼────────────┐
▼ ▼ ▼
REST API Docker Live Demo
This platform isn't just a model — it's a reproducible research instrument:
- Leakage-safe evaluation — strictly-prior chronological splits prevent temporal data leakage
- Paired statistical tests — every comparison backed by bootstrap CIs, Cohen's d, and p-values
- Honest negative results — graph neural features (GraphSAGE, GAT) shown NOT to help; IQL transfer documented to fail; forecast-decision gap empirically validated
- Trajectory-level OPE — Weighted Importance Sampling and sequential Doubly Robust with complete-episode bootstrap for the first time in spatiotemporal recommendation
- Single command reproduction —
make allruns the full pipeline
src/
decision/ Decision Engine api/ FastAPI REST API
forecasting/ LGB + XGB ensemble graph/ GraphSAGE, GAT
simulator/ Multi-agent v2 rl/ DQN, DoubleDQN, IQL
mdp/ MDP value iteration evaluation/ Shadow, A/B, OPE
cities/ Cross-city adapter monitoring/ Metrics, registry
scripts/ Benchmarks & runners configs/ YAML configs
tests/ 402 tests docs/ Full documentation
web/ Live Leaflet demo pages/ Landing page
notebooks/ Jupyter tutorials examples/ Usage examples
Read before citing results. These are fundamental, not implementation oversights.
- Simulator outcomes only — no congestion, no airport queues, no driver adaptation. Results are NOT production revenue estimates.
- Counterfactual identifiability — NYC TLC data lacks logged recommendations, propensities, and driver actions. Valid causal OPE requires a stochastic logging policy in deployment.
- Forecast-decision gap — empirically confirmed: better MAE → worse decisions (-$17.88/day).
- Exposure concentration — Two-Step strategy: 70.33% airport exposure, Gini 0.982. Saturation risk at scale.
| Role | How to Contribute |
|---|---|
| Researchers | Benchmark your policy, extend the methods, co-author the paper |
| Engineers | Productionize API, add K8s/Terraform, improve CI/CD |
| Domain Experts | Review simulator assumptions, add city adapters, improve docs |
| Students | Good first issues, tutorial improvements, Jupyter notebooks |
🚀 Get started: Discussions · Issues · CONTRIBUTING.md
📧 Contact: Zefan Cai — caizefan@sjtu.edu.cn — Shanghai Jiao Tong University
@software{cai2026urban_mobility,
author = {Zefan Cai},
title = {Urban Mobility Decision Intelligence: An Open-Source Platform for AI-Driven Fleet Repositioning},
year = {2026},
publisher = {GitHub},
url = {https://github.com/caizefan34/urban-mobility-ai},
note = {v3.0.0. Cite the specific commit used. Simulator outcomes, not production estimates.}
}MIT License · Built at Shanghai Jiao Tong University · v3.0.0