README.md

metadata

title: AI Personas for Urban Planning
emoji: 🏙️
colorFrom: blue
colorTo: purple
sdk: streamlit
sdk_version: 1.40.1
app_file: web_app.py
pinned: false

AI Personas for Urban Planning

A multi-phase persona simulation system for urban planning and built environment design, enabling stakeholder perspective analysis and opinion dynamics modeling.

Overview

This system allows users to:

• Phase 1 ✅: Query synthetic personas representing urban stakeholders and receive contextually-aware responses
• Phase 2 ✅: Generate response distributions from populations of persona variants
• Phase 3 ✅: Model multi-persona interactions to discover opinion equilibria using scale-free and small-world networks

Project Structure

AI_Personas/
├── src/
│   ├── personas/          # Persona data models and database
│   ├── context/           # Environmental/built environment context
│   ├── llm/               # LLM integration (Anthropic Claude)
│   ├── pipeline/          # Phase 1: Query-response pipeline
│   ├── population/        # Phase 2: Population sampling and analysis
│   └── influence/         # Phase 3: Social influence networks & equilibrium
├── data/
│   ├── personas/          # Persona JSON definitions
│   └── contexts/          # Environmental context data
├── pages/
│   ├── 1_💬_Chat.py      # Phase 1 web interface
│   ├── 2_📊_Population_Analysis.py  # Phase 2 web interface
│   └── 3_🌐_Opinion_Equilibria.py   # Phase 3 web interface
├── tests/
├── web_app.py             # Main Streamlit app entry point
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
└── README.md

🎨 Web UI (Multi-Page!)

Beautiful visual interface with three integrated pages:

# Launch the web interface
streamlit run web_app.py

Page 1: Chat with Personas 💬

Phase 1: Individual persona conversations

• 👥 Visual persona cards with avatars and color themes
• 💬 Chat-style conversation interface
• 📜 Full conversation history
• 🎯 Quick suggestion buttons
• 🌆 Contextual awareness (built environment, social context)

Page 2: Population Analysis 📊

Phase 2: Response distributions from persona populations

• 🔢 Query 100+ persona variants simultaneously
• 📊 Position distribution visualizations (support/oppose/neutral)
• 😊 Sentiment analysis across populations
• 🏷️ Theme extraction and clustering (affordability, equity, sustainability, etc.)
• 📈 Interactive Plotly charts and statistical summaries
• ⚙️ Configurable variation levels (Conservative/Moderate/Diverse)
• 💾 Export results as reports

Page 3: Opinion Equilibria 🌐 ✨ NEW!

Phase 3: Multi-persona influence and opinion dynamics

• 🕸️ Scale-free and small-world network topologies (Barabási-Albert, Watts-Strogatz)
• 🔄 Multi-round opinion dynamics simulation
• 📈 Opinion evolution timeline visualization
• 🎯 Equilibrium detection and convergence analysis
• 👥 Opinion cluster identification
• ⭐ Opinion leader detection (influence centrality)
• 🌐 Interactive network graph visualization
• 📊 Consensus strength metrics
• 💾 Export equilibrium reports

Quick Start

1. Installation

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuration

# Copy environment template
cp .env.example .env

# Edit .env and add your Anthropic API key

3. Run Example

# Phase 1: Single persona query
python examples/phase1_single_query.py

# Interactive CLI
python -m src.cli

Personas

The system includes 6 synthetic personas representing diverse urban planning stakeholders:

1. Sarah Chen - Urban Planner (30s, progressive, sustainability-focused)
2. Marcus Thompson - Local Business Owner (50s, pragmatic, economy-focused)
3. Dr. Elena Rodriguez - Transportation Engineer (40s, data-driven, efficiency-focused)
4. James O'Brien - Long-time Resident (65+, traditional, community-focused)
5. Priya Patel - Housing Advocate (20s, activist, equity-focused)
6. David Kim - Real Estate Developer (40s, market-driven, growth-focused)

Phase Roadmap

Phase 1: Single Persona Query-Response ✅ COMPLETE

• ✓ Query individual personas with contextual awareness
• ✓ Anthropic Claude integration
• ✓ Environmental context system
• ✓ Beautiful chat interface with persona cards
• ✓ Conversation history and quick suggestions

Phase 2: Population Response Distribution ✅ COMPLETE

• ✓ Generate persona variants with configurable variation levels
• ✓ Parallel querying of persona populations (100+)
• ✓ Response clustering and statistical analysis
• ✓ Position detection (support/oppose/neutral)
• ✓ Sentiment analysis and theme extraction
• ✓ Interactive Plotly visualizations
• ✓ Export functionality

Phase 3: Multi-Persona Influence & Equilibrium ✅ COMPLETE

• ✓ Scale-free network topology (Barabási-Albert model)
• ✓ Small-world network topology (Watts-Strogatz model)
• ✓ Fully connected network option
• ✓ Opinion dynamics simulation (multi-round interactions)
• ✓ Influence weight calculation based on persona characteristics
• ✓ Equilibrium detection algorithms
• ✓ Opinion leader identification (centrality analysis)
• ✓ Opinion cluster detection and stability metrics
• ✓ Interactive network graph visualization
• ✓ Consensus strength metrics
• ✓ Opinion evolution timeline charts
• ✓ Export equilibrium reports

Technology Stack

• Python 3.11+: Core language
• FastAPI: REST API layer
• SQLite/PostgreSQL: Persona and context storage
• Anthropic Claude: LLM (will support Be.FM from Stanford)
• Pydantic: Data validation
• NumPy/SciPy: Statistical analysis (Phase 2)
• NetworkX: Graph modeling (Phase 3)

Usage Examples

Query a Persona

from src.pipeline.query_engine import QueryEngine

engine = QueryEngine()

# Ask a persona about a planning issue
response = engine.query(
    persona_id="sarah_chen",
    question="What do you think about the proposed bike lane on Main Street?",
    context={
        "location": "downtown_district",
        "time": "rush_hour",
        "recent_events": ["community_meeting_last_week"]
    }
)

print(response)

Get Population Distribution (Phase 2)

from src.population.sampler import PopulationSampler

sampler = PopulationSampler(base_persona="sarah_chen", n_variants=100)
distribution = sampler.query_population(
    question="Rate your support for the bike lane (1-10)"
)

# distribution.mean, distribution.std, distribution.histogram

Model Opinion Dynamics (Phase 3)

from src.personas.database import PersonaDatabase
from src.llm.anthropic_client import AnthropicClient
from src.influence.dynamics import OpinionDynamicsEngine
from src.influence.equilibrium import EquilibriumDetector
from src.influence.network import InfluenceNetwork

# Initialize
persona_db = PersonaDatabase()
persona_db.load_from_directory("data/personas")
llm_client = AnthropicClient()

# Select personas for discussion
persona_ids = ["sarah_chen", "marcus_thompson", "david_kim"]

# Run opinion dynamics with scale-free network
engine = OpinionDynamicsEngine(persona_db, llm_client)
results = engine.run_dynamics(
    persona_ids=persona_ids,
    question="Should we allow high-rise development downtown?",
    max_rounds=5,
    network_type="scale_free",  # or "small_world", "fully_connected"
)

# Analyze equilibrium
personas = [persona_db.get_persona(pid) for pid in persona_ids]
influence_network = InfluenceNetwork(personas, network_type="scale_free")
detector = EquilibriumDetector()
equilibrium = detector.analyze_equilibrium(results, influence_network, max_rounds=5)

# Results
print(f"Equilibrium reached: {equilibrium.reached_equilibrium}")
print(f"Consensus strength: {equilibrium.consensus_strength:.0%}")
print(f"Majority position: {equilibrium.majority_position.value}")
print(f"Opinion leaders: {[l['persona_name'] for l in equilibrium.opinion_leaders[:3]]}")

Contributing

This project is under active development. Contributions welcome!

License

MIT License