FastAPI + Vite scaffold for the Glassmorphic Command Center.

• cd backend
• pip install -r requirements.txt
• copy .env.example .env (Windows) and set GEMINI_API_KEY
• uvicorn app.main:app --reload --port 8000

Why app.main:app? The API lives in backend/app/main.py. Python imports that as module app.main (folder app + file main.py), not as a top-level main. Uvicorn uses <module>:<object>, so: module app.main, FastAPI instance app → app.main:app.

• cd frontend
• npm install
• copy .env.example .env (Windows) and set VITE_MAPBOX_TOKEN
• npm run dev

If GEMINI_API_KEY is missing, the backend uses deterministic fallback behavior instead of live LLM negotiation.

#Project Description

1. The Core Premise: City Hall in a Box Most AI urban planning tools fail because they treat city streets like a math equation—they calculate the most "efficient" throughput and output a sterile layout. But real city planning isn't a math problem; it is a brutal, high-stakes political negotiation.

   We built an Adversarial Urban Planning Engine. Instead of using AI as a simple optimization calculator, we engineered a persistent multi-agent simulation. We put distinct AI stakeholders with violently conflicting agendas into a LangGraph state machine and force them to fight over the layout of a Toronto intersection until they reach a Pareto-optimal compromise.

2. System Architecture: Truth vs. ReasoningTo prevent the LLMs from hallucinating impossible physics, we strictly decoupled the system into two distinct engines:

   The "Truth" Engine (Deterministic Physics): A lightning-fast Python backend that scores any proposed street layout. It calculates Throughput ($T$), Environmental Impact ($E$), Safety Index ($S$), and Walkability ($W$) using hardcoded civil engineering heuristics. The AI cannot manipulate these numbers.

   The "Reasoning" Engine (LangGraph State Machine): A cyclic, parallel Fan-Out/Fan-In architecture. The Python physics score is fed to the agents. If the score fails baseline thresholds, the agents read the failure, remember their past rejected proposals, and aggressively renegotiate a new layout.

3. The Agentic Ecosystem The simulation runs concurrent parallel nodes to prevent API latency from stalling the demo.

    The Traffic Engineer: Ruthless and pragmatic. Fights to maximize vehicular throughput and lane capacity.
   
    The Vision Zero Advocate: Uncompromising and moralistic. Demands protected bike lanes and pedestrian islands.
   
    The Local Business Coalition: Pragmatic. Demands street parking and foot traffic; hates construction delays.
   
    The Environmental Advocate: Idealistic. Demands tree canopies and reduced asphalt footprint.
   
    The Mayor (The Synthesizer): The fan-in node. Takes the screaming demands of the four parallel agents, applies the strict budget constraints, and outputs a highly structured JSON layout proposal.
   

4. The Frontend: "Glassmorphic Command Center" We built a high-fidelity 3D digital twin of downtown Toronto to act as the visual stage for the simulation.

   The Canvas: A Mapbox GL 3D map.

   The UX: Glassmorphic UI panels (backdrop-blur-md) slide in using Framer Motion to display the real-time agent debate and fluctuating physics metrics.

   The Failsafe: A "God Mode" illusion that gracefully deflects out-of-bounds clicks with a sleek UI toast ("Intersection operating within acceptable throughput margins"), ensuring the demo never crashes live on stage.

5. The Output: The Council Artifact The system doesn't just change the map—it generates a lab-grade, tangible asset. Once the LangGraph loop reaches consensus, it outputs a City Council Environmental Assessment & Budget Proposal. This includes:

    A rigid "Before vs. After" Delta Table proving the mathematical optimization.
   
    A "Summary of Compromise" detailing exactly why the AI agents rejected previous layouts and how they settled on the final design.
   
    An itemized construction cost quote.
   

6. The "+5 Years" Feature (Emergence) To prove the system has true persistent state memory (MemorySaver), the user can trigger a "+5 Years" population spike. The baseline traffic demand multiplies by 1.20, immediately causing the previously agreed-upon layout to mathematically fail its safety/throughput thresholds. The agents instantly panic, reference their past negotiations, and are forced to redesign the intersection on the fly.