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

# On macOS/Linux:
./run_web_app.sh

# On Windows:
run_web_app.bat

Option B: Direct command

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:

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:

python --version  # Should be 3.11+

Reinstall dependencies:

pip install -r requirements.txt

"No personas loaded" error

Check persona files exist:

ls data/personas/

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

API errors

Verify API key:

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:

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

# 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! 🏙️