docs/GETTING_STARTED.md

# Getting Started with AI Personas

This guide will help you set up and start using the AI Personas system for urban planning.

## Prerequisites

- Python 3.11 or higher
- Anthropic API key (get one at https://console.anthropic.com/)
- Basic understanding of urban planning concepts (helpful but not required)

## Installation

### 1. Clone and Setup

```bash
cd AI_Personas

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure API Key

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

# Edit .env and add your Anthropic API key
# ANTHROPIC_API_KEY=your_actual_key_here
```

**Important:** Never commit your `.env` file to version control!

## Quick Start

### Test the System

```bash
# Run a simple test query
python examples/phase1_simple_query.py
```

This will query Sarah Chen (our urban planner persona) about a bike lane proposal.

### Interactive CLI

```bash
# Launch the interactive command-line interface
python -m src.cli
```

The CLI allows you to:
- Query individual personas interactively
- Query all personas with the same question
- Browse available personas and contexts
- Experiment with different scenarios

### Query Multiple Perspectives

```bash
# See how all 6 stakeholders respond to the same issue
python examples/phase1_multiple_perspectives.py
```

This demonstrates the power of the system: seeing diverse stakeholder perspectives on the same urban planning issue.

## Understanding the System

### The 6 Personas

The system includes 6 diverse urban planning stakeholders:

1. **Sarah Chen** - Progressive urban planner focused on sustainability
2. **Marcus Thompson** - Local business owner concerned about economic impacts
3. **Dr. Elena Rodriguez** - Data-driven transportation engineer
4. **James O'Brien** - Long-time resident protective of neighborhood character
5. **Priya Patel** - Young housing justice advocate
6. **David Kim** - Market-driven real estate developer

Each persona has:
- Detailed demographics and background
- Core values and priorities
- Communication style and language patterns
- Domain expertise
- Typical concerns

### Environmental Contexts

Contexts provide situational information that influences responses:

- **Built environment**: Density, transit access, amenities
- **Social context**: Demographics, community characteristics
- **Economic context**: Housing costs, employment, development
- **Temporal context**: Time, season, recent events

The system currently includes one sample context: `downtown_district`

## Basic Usage Examples

### Python API

```python
from src.pipeline.query_engine import QueryEngine

# Initialize
engine = QueryEngine()

# Query a single persona
response = engine.query(
    persona_id="sarah_chen",
    question="What do you think about adding bike lanes?",
    context_id="downtown_district"
)

print(f"{response.persona_name}: {response.response}")

# Query multiple personas
responses = engine.query_multiple(
    persona_ids=["sarah_chen", "marcus_thompson", "elena_rodriguez"],
    question="Should we reduce parking for bike lanes?",
    context_id="downtown_district"
)

for r in responses:
    print(f"\n{r.persona_name} ({r.persona_role}):")
    print(r.response)
```

### Custom Scenarios

You can add scenario descriptions for more specific queries:

```python
scenario = """
The city is considering a $50M bond measure to fund:
- 20 miles of protected bike lanes
- Three new bus rapid transit lines
- Pedestrian improvements in 10 neighborhoods
This would increase property taxes by $200/year for median homeowner.
"""

response = engine.query(
    persona_id="james_obrien",
    question="Would you support this bond measure?",
    context_id="downtown_district",
    scenario_description=scenario
)
```

## Creating Custom Personas

To add your own personas:

1. Copy an existing persona JSON file from `data/personas/`
2. Modify the attributes to match your new persona
3. Save with a new filename in the same directory
4. The system will automatically load it on next run

Key fields to customize:
- `persona_id`: Unique identifier (use snake_case)
- `name`, `role`, `tagline`: Basic identity
- `demographics`: Age, education, occupation, etc.
- `psychographics`: Values, priorities, political leaning
- `behavioral_profile`: Communication and decision-making style
- `background_story`: Narrative context

## Creating Custom Contexts

To add environmental contexts:

1. Copy `data/contexts/downtown_district.json`
2. Modify the fields to match your location
3. Save with a new filename in the same directory

## Tips for Effective Queries

1. **Be specific**: Instead of "What do you think about housing?", ask "Should we allow 4-story apartment buildings on Main Street?"

2. **Add context**: Use scenario descriptions to provide relevant details

3. **Compare perspectives**: Query multiple personas to see different viewpoints

4. **Use realistic situations**: Ground questions in actual planning decisions

5. **Consider timing**: Recent events in temporal context can influence responses

## Troubleshooting

### "No personas loaded"
- Check that JSON files exist in `data/personas/`
- Verify JSON syntax is valid
- Check file permissions

### "Anthropic API key must be provided"
- Ensure `.env` file exists
- Verify `ANTHROPIC_API_KEY` is set correctly
- Check that you've activated the virtual environment

### "Persona not found"
- Run `python -m src.cli` and select option 3 to list available personas
- Check spelling of persona_id (must match exactly)

### Poor quality responses
- Try adjusting temperature (lower = more consistent, higher = more creative)
- Provide more context via scenario descriptions
- Ensure persona definitions are detailed and realistic

## Next Steps

### Phase 2: Population Distributions (Coming Soon)

Phase 2 will enable:
- Generating 100s of persona variants with statistical distributions
- Analyzing response distributions (mean, variance, clusters)
- Visualizing how a population would respond

### Phase 3: Opinion Dynamics (Coming Soon)

Phase 3 will enable:
- Modeling influence between personas
- Running simulations to find opinion equilibria
- Discovering consensus and polarization patterns

## Support

- Check the main [README.md](../README.md) for overview
- Review example scripts in `examples/` directory
- Examine persona JSON files in `data/personas/` to understand structure

## Best Practices

1. **Version control personas**: Treat persona definitions as code
2. **Document assumptions**: Add notes in metadata fields
3. **Iterate on personas**: Refine based on response quality
4. **Mix perspectives**: Use diverse personas for balanced analysis
5. **Ground in reality**: Base personas on real stakeholder research

Happy planning! 🏙️