README.md

---
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:**

```bash
# 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

```bash
# 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

```bash
# Copy environment template
cp .env.example .env

# Edit .env and add your Anthropic API key
```

### 3. Run Example

```bash
# 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

```python
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)

```python
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)

```python
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