docs/WEB_UI_GUIDE.md

# Web UI Guide

## Overview

The AI Personas Web UI provides a beautiful, interactive interface for conversing with urban planning stakeholder personas. The interface features:

- **Visual persona cards** with avatars and descriptions
- **Chat-style interface** for natural conversations
- **Conversation history** tracking within each session
- **Quick suggestion buttons** for common questions
- **Real-time responses** from Claude-powered personas

## Layout

```
┌─────────────────────────────────┬────────────────┐
│  💬 Conversation                │  👥 Personas   │
│  ┌───────────────────────────┐  │  ┌──────────┐ │
│  │ Selected: Sarah Chen      │  │  │ 🌱 Sarah │ │
│  └───────────────────────────┘  │  └──────────┘ │
│                                 │  ┌──────────┐ │
│  ┌───────────────────────────┐  │  │ 🏪 Marcus│ │
│  │ Your question: [____] Send│  │  └──────────┘ │
│  └───────────────────────────┘  │      ...      │
│                                 │                │
│  💡 Quick Suggestions           │                │
│  [Suggestion 1] [Suggestion 2]  │                │
│                                 │                │
│  📜 Conversation History        │                │
│  ┌───────────────────────────┐  │                │
│  │ 🙋 You: What about...     │  │                │
│  │ 🌱 Sarah: I think that... │  │                │
│  └───────────────────────────┘  │                │
└─────────────────────────────────┴────────────────┘
```

## The 6 Personas

Each persona has a unique visual identity:

1. **🌱 Sarah Chen** - Urban Planner
   - Progressive, sustainability-focused
   - Green theme

2. **🏪 Marcus Thompson** - Business Owner
   - Pragmatic, economy-focused
   - Orange theme

3. **🚇 Dr. Elena Rodriguez** - Transportation Engineer
   - Data-driven, safety-first
   - Blue theme

4. **🏡 James O'Brien** - Long-time Resident
   - Traditional, community-focused
   - Brown theme

5. **✊ Priya Patel** - Housing Advocate
   - Activist, equity-focused
   - Pink theme

6. **🏢 David Kim** - Real Estate Developer
   - Market-driven, growth-oriented
   - Gray theme

## Getting Started

### 1. Launch the Web App

**Option A: Using the startup script**
```bash
# On macOS/Linux:
./run_web_app.sh

# On Windows:
run_web_app.bat
```

**Option B: Direct command**
```bash
streamlit run web_app.py
```

### 2. Access the Interface

The app will automatically open in your default browser at:
```
http://localhost:8501
```

If it doesn't open automatically, manually navigate to that URL.

### 3. Select a Persona

- Look at the right panel showing 6 persona cards
- Click on any persona to select them
- The selected persona will be highlighted
- Your conversation history will be cleared when switching personas

### 4. Start Asking Questions

**Quick Start Options:**
- Click one of the suggested questions below the input box
- Type your own question in the text field
- Press Enter or click "Send"

**Example Questions:**
- "What do you think about the bike lane proposal?"
- "Should we allow food trucks downtown?"
- "What's the biggest challenge facing our community?"
- "How can we make housing more affordable?"

### 5. View Responses

- Responses appear in the conversation history
- Your questions are shown in blue boxes
- Persona responses are shown in gray boxes
- Scroll to see the full conversation

### 6. Continue the Conversation

- Ask follow-up questions
- The persona maintains context from previous messages in the session
- Switch personas to get different perspectives on the same topic

## Features

### Conversation History

Each session with a persona maintains full conversation history:
- All your questions are saved
- All responses are preserved
- Switch between personas to compare perspectives
- Clear conversation button to start fresh

### Quick Suggestions

Pre-written questions to help you get started:
- "What's the most important issue facing downtown?"
- "Should we allow food trucks in the plaza?"
- "How can we make the city more sustainable?"
- "What do you think about the affordable housing crisis?"

### Context Awareness

All responses consider:
- The downtown district environmental context
- Recent events and upcoming decisions
- The persona's values, background, and expertise
- Their communication style and typical concerns

## Tips for Effective Use

### 1. Start Broad, Then Go Specific

```
Good progression:
1. "What are your priorities for downtown?"
2. "How do you feel about new development?"
3. "What about the 500-unit condo proposal on 5th St?"
```

### 2. Compare Perspectives

Ask the same question to multiple personas:
1. Ask Sarah Chen (planner) about bike lanes
2. Switch to Marcus Thompson (business owner)
3. Ask the same question
4. See how their values shape different responses

### 3. Use Realistic Scenarios

```
Weak: "What do you think?"
Strong: "The city is considering a $50M bond for affordable
        housing. It would add 200 units but increase property
        taxes by $150/year. What's your position?"
```

### 4. Ask Follow-up Questions

```
Initial: "Should we add more bike lanes?"
Follow-up: "What about concerns from business owners?"
Follow-up: "How would you address parking issues?"
```

### 5. Explore Trade-offs

```
Good questions:
- "How would you balance economic growth with affordability?"
- "What's more important: parking or bike infrastructure?"
- "How do we develop without displacing residents?"
```

## Use Cases

### 1. Planning Proposal Testing

**Before a public meeting:**
- Present your proposal to all 6 personas
- Identify likely concerns and objections
- Prepare responses to different stakeholder viewpoints
- Refine your communication strategy

### 2. Community Engagement Prep

**Before stakeholder outreach:**
- Understand different value systems
- Learn characteristic language patterns
- Identify potential allies and opponents
- Develop inclusive framing

### 3. Scenario Exploration

**Test different approaches:**
- Ask about Option A vs. Option B
- See which approach gets broader support
- Understand trade-offs from multiple perspectives

### 4. Training & Education

**For planning students/professionals:**
- Learn to think from diverse perspectives
- Understand stakeholder motivations
- Practice responsive communication
- Build empathy across different viewpoints

### 5. Policy Analysis

**Evaluate proposed policies:**
- Get immediate feedback from different angles
- Identify unintended consequences
- Understand equity implications
- Find opportunities for compromise

## Technical Details

### Performance

- First query may take 3-5 seconds (model initialization)
- Subsequent queries: 2-4 seconds each
- Conversation history is stored in browser session
- No data is saved between sessions (privacy-preserving)

### Browser Compatibility

Tested and working on:
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

### Port Configuration

Default port: `8501`

To use a different port:
```bash
streamlit run web_app.py --server.port 8502
```

### Customization

The web app reads from:
- `data/personas/*.json` - Persona definitions
- `data/contexts/*.json` - Environmental contexts
- `.env` - API configuration

Any changes to these files will be reflected after refreshing the browser.

## Troubleshooting

### App won't start

**Check Python version:**
```bash
python --version  # Should be 3.11+
```

**Reinstall dependencies:**
```bash
pip install -r requirements.txt
```

### "No personas loaded" error

**Check persona files exist:**
```bash
ls data/personas/
```

Should show 6 JSON files. If not, verify git repository is complete.

### API errors

**Verify API key:**
```bash
cat .env | grep ANTHROPIC_API_KEY
```

Should show your API key. If missing, add it to `.env`.

### Slow responses

**Check model configuration:**

In `.env`, you're using:
```
LLM_MODEL=claude-3-haiku-20240307
```

This is the fastest model. For better quality (but slower), you could upgrade to Sonnet or Opus.

### Persona not responding

**Check browser console:**
- Right-click → Inspect → Console tab
- Look for error messages
- Common issue: API rate limits

**Refresh the page:**
- Clears session state
- Reinitializes connections

### Clear stuck session

**Browser refresh:** Press F5 or Ctrl+R

**Clear cache:**
```bash
streamlit cache clear
```

## Keyboard Shortcuts

While in the text input field:
- **Enter**: Send message
- **Shift+Enter**: New line (in the future, for multi-line input)
- **Escape**: Clear input field

## Privacy & Data

### What's Stored

**In browser session (temporary):**
- Selected persona
- Conversation history
- Current question

**Not stored:**
- No conversation logs saved to disk
- No personal data collected
- No tracking or analytics

**Cleared when:**
- Switching personas
- Clicking "Clear Conversation"
- Closing browser tab
- Refreshing page

### API Usage

- Questions are sent to Anthropic Claude API
- Responses are generated by the LLM
- Conversation data follows Anthropic's privacy policy
- No training on your queries (as per Anthropic policy)

## Advanced Features (Coming Soon)

Planned enhancements:
- Export conversation to PDF/Markdown
- Share conversation links
- Multi-persona comparison view
- Voice input/output
- Mobile responsive design improvements
- Dark mode
- Custom persona builder

## Support

If you encounter issues:

1. Check this guide first
2. Review main README.md
3. Check GitHub issues
4. Verify all dependencies installed
5. Ensure API key is configured

## Quick Command Reference

```bash
# Start app
streamlit run web_app.py

# Start on different port
streamlit run web_app.py --server.port 8502

# Clear cache
streamlit cache clear

# View Streamlit config
streamlit config show

# Run in headless mode (no browser)
streamlit run web_app.py --server.headless true
```

---

**Enjoy exploring diverse urban planning perspectives! 🏙️**