agent-urban-planning

Open-source Python library for agent-based urban planning simulation with closed-form, hybrid, and full-LLM decision engines. Companion to the NeurIPS Datasets & Benchmarks 2026 paper.

🚀 Quickstart

pip install agent-urban-planning and run a 5-variant smoke test in under 10 seconds.

Quickstart

📊 Berlin replication

Reproduce the paper’s V1-V5 Berlin baseline + East-West Express shock.

Berlin V1-V5 replication

🤖 Full LLM (V5)

Deep-dive on the score-all-96 + rebalance + stage-2 cap pattern (paper headline).

Full LLM hierarchical engine (V5)

🔧 Custom engines

Subclass agent_urban_planning.DecisionEngine for research extensions.

Custom decision engine

What it is

A modular agent-based modeling framework for spatial-equilibrium urban policy simulation. Five reference decision-engine variants ship as first-class API classes, configurable via kwargs:

Paper variant	One-line description	API call
V1 Baseline-softmax	Closed-form Cobb-Douglas + Fréchet softmax	aup.UtilityEngine(mode="softmax")
V2 Baseline-ABM argmax	ABM with Fréchet idiosyncratic shocks	aup.UtilityEngine(mode="argmax", noise="frechet")
V3 Normal-ABM argmax	ABM with Gaussian shocks	aup.UtilityEngine(mode="argmax", noise="normal")
V4 Hybrid-ABM	LLM-elicited preferences + closed-form choice	aup.HybridDecisionEngine(elicitor=...)
V5 LLM-ABM (paper headline)	Full LLM-as-decision-maker, score-all-96	aup.LLMDecisionEngine(response_format="score_all", rebalance_instruction=True, stage2_top_k_residences=10)

Citation

If you use this software in your research, please cite the accompanying paper. See CITATION.cff in the repo root for full metadata.