Separate simulators contradict
If Behavioral and Ecological ran independent physics, you could get trips up alongside emissions flat because they modeled different realities. A unified trajectory dataset eliminates that class of inconsistency.
One kernel. Five modules. Full provenance.
A single SUMO and LLM-persona simulation produces one unified trajectory dataset. Five impact modules score that same reality in parallel, streamed to a Next.js and Deck.gl cockpit in under 90 seconds (target).
Architecture
A natural-language query or map drop flows through the Azure OpenAI orchestrator into the unified simulation kernel. All five impact modules consume the same trajectory dataset, which is why Behavioral cannot contradict Ecological on the same run.
Input
NL query or map drop
Orchestrator
Azure OpenAI gpt-5.4
Parse to simulation plan
Unified kernel
SUMO + Persona Pool + Bias Auditor
One trajectory dataset, per-agent and per-tick
Behavioral
Social
Economic
Ecological
Societal
Synthesis agent
Visualization
Next.js + Deck.gl
Streams trajectories, scores, and brief
Why one unified kernel?
Why SUMO, not social simulators?
OASIS and MiroFish simulate social-media dynamics, not physical agents in cities. Eclipse SUMO (DLR) is the open-source urban mobility standard with native intermodal support, the correct engine for pre-construction transport impact.
90-second pipeline
Real-time interactive visualization is the product's defining capability. The architecture targets a hard latency budget: pre-warmed persona pool, delta simulations against a nightly baseline, parallel module execution, and progressive UI streaming.
- 010-5s
Parse
6% of budgetNatural-language query to structured simulation plan (Azure OpenAI)
- 025-15s
Retrieve
11% of budgetGraphRAG knowledge retrieval from ChromaDB corpus
- 0315-60s
Simulate
50% of budgetSUMO agent run with pre-warmed persona pool and delta against nightly baseline
- 0460-80s
Score
22% of budgetFive impact modules compute in parallel on one trajectory dataset
- 0580-90s
Synthesize
11% of budgetSynthesis agent generates plain-language brief with citations
Honest status
The target budget is 90 seconds end-to-end. Cold runs currently land around 123 s, while repeated runs served from the trajectory cache return in under 1 s. Per-stage timings are shown in-product to guide optimization.
Tech stack
Deliberate technology choices, each made for a documented reason.
- Simulation
- Eclipse SUMO via TraCI Python API
- OSMnx network ingestion
- AI and ML
- Azure OpenAI gpt-5.4 (orchestration, synthesis, personas)
- openai SDK to Azure AI Foundry v1 endpoint
- Microsoft GraphRAG + ChromaDB
- XGBoost corridor volume forecaster
- Backend
- FastAPI + WebSocket progressive stream
- Postgres + PostGIS (in-memory fallback)
- Redis (persona pool, baseline, trajectory cache)
- Frontend
- Next.js 14 App Router
- Tailwind CSS v4 + shadcn/ui
- Mapbox GL JS + Deck.gl TripsLayer
Data sources
Every input dataset carries a confidence tier (High, Medium, or Low) propagated through to impact module outputs. The confidence layer in the UI surfaces where the simulation is sure versus estimating.
Tier 1Day 1 downloadable
OSM Geofabrik PH, PSA census, Sentinel-2, PAGASA, NOAH, OpenWeather
Tier 2FOI-pending
LTFRB Region VI routes, PSA APIS barangay-level, Iloilo City CLUP
Tier 3Institutional outreach
Clean Air Asia SMMR data inventory, ICLEI roadmap data
Tier 4Academic baseline
Calderon 2014 BRT model, Macalalag 2021 bike study, Philippine Geomatics 2021
Full catalog in MATRIX_Iloilo_Data_Sources.md. Licensing: OSM ODbL, PSA open data, ESA Copernicus, RA 10173 compliance.
Glass-box and bias auditor
No number ships without equation_id, input_dataset_ids, and a computed confidence. The LLM narrates and cites. It never originates a number.
Every number is traceable
Each result carries the equation that produced it, the datasets it drew from, and a computed confidence level. Open the Inspect drawer on any figure to see its full provenance.
Honest by construction
Outputs are confidence-anchored ranges, not false-precision point estimates. The AI narrates and cites the results. It never originates a number. A bias auditor keeps a public audit log.
One reality, five lenses
A single agent-based simulation feeds all five impact modules, so the dimensions can never contradict each other. You score one simulated reality, not five disconnected guesses.
Bias mitigations
Mode-share anchor
Persona generation constrained to match Iloilo ground-truth mode share. Deviations beyond ±3% trigger reweighting.
Public bias audit log
A bias auditor runs after every persona batch and logs adjustments keyed to scenario_id.
Confidence floor
Dimensions below the confidence threshold are flagged directional only, not reported as precise.
Open methodology
Every simulation logs assumptions, data sources, and confidence anchors for reproducibility.
Validation
Validation machinery is shipped and tested. VAL-01 against Calderon 2014 is a published FAIL: live normalized RMSE is compared to the pass threshold (≤ 0.30) in the in-product validation ledger. Iloilo corridor volumes are directional, not city-calibrated. Uncalibrated demand is why the gate fails — it is not a reason to hide the RMSE.
VAL-01
Calderon 2014 BRT RMSE
Back-test against the Calderon et al. (2014) BRT corridor model for Iloilo City. The live NRMSE and pass threshold are published in validation_report.json and shown as FAIL in the simulator's validation panel.
VAL-02
2024 flood IoU
Flood intersection-over-union against 2024 Iloilo flood events. Fixture labeled PROVISIONAL until a real fixture replaces the placeholder.
Next steps
The path to a VAL-01 PASS is still calibration: aligning simulated demand and mode share to an independent volume source. Until then the FAIL, the live NRMSE, and the 0.30 threshold stay on screen so planners are not shown a silent High-confidence magnitude. We are in contact with Iloilo CPDO for corridor and transit data; official data-sharing moves slowly, so we do not overpromise a date.