Spaces:

MatthewStroud
/

AI_Personas

Sleeping

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

# 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

# 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

# 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

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

Sarah Chen - Progressive urban planner focused on sustainability
Marcus Thompson - Local business owner concerned about economic impacts
Dr. Elena Rodriguez - Data-driven transportation engineer
James O'Brien - Long-time resident protective of neighborhood character
Priya Patel - Young housing justice advocate
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

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:

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:

Copy an existing persona JSON file from data/personas/
Modify the attributes to match your new persona
Save with a new filename in the same directory
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:

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

Tips for Effective Queries

Be specific: Instead of "What do you think about housing?", ask "Should we allow 4-story apartment buildings on Main Street?"
Add context: Use scenario descriptions to provide relevant details
Compare perspectives: Query multiple personas to see different viewpoints
Use realistic situations: Ground questions in actual planning decisions
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 for overview
Review example scripts in examples/ directory
Examine persona JSON files in data/personas/ to understand structure

Best Practices

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

Happy planning! 🏙️