# Persona Engine - Quick Reference Guide

## 🚀 Quick Start

The Persona Engine automatically classifies leads into tourist personas based on trip characteristics. No manual configuration needed!

---

## 📊 7 Persona Types

| Persona | Emoji | Spend | Key Indicators |
|---------|-------|-------|----------------|
| Romantic Couple | 💑 | Very High | 2 travelers + balloon/wine |
| Luxury Traveler | ✨ | Very High | Private tours + luxury interests |
| Budget Backpacker | 🎒 | Low | Budget interests + group tours |
| Content Creator | 📸 | High | Photography + drone + viewpoints |
| Family Explorer | 👨‍👩‍👧‍👦 | Medium | 3-6 travelers + family activities |
| Solo Adventurer | 🧗 | Medium | 1 traveler + adventure activities |
| Group Tour | 👥 | High | 8+ travelers + group activities |

---

## 🎯 For Providers

### Viewing Persona Information

**On Lead Cards:**
- Persona badge shows emoji + label
- Hover for tooltip with details
- Color-coded spend potential
- Confidence score percentage

**In Lead Detail Modal:**
- Full "Turist Profili" section
- Detected signals list
- Recommended services
- Detailed description

### Using Persona Insights

1. **Prioritize High-Value Leads**
   - Focus on "Very High" spend potential (purple)
   - Target "High" spend potential (green) next

2. **Tailor Your Pitch**
   - Use recommended services as talking points
   - Reference detected signals in communication
   - Match your offerings to persona needs

3. **Quick Response**
   - High confidence (>70%) = reliable classification
   - AI-recommended leads = hot prospects
   - Fast response increases conversion

### Example Approaches

**Romantic Couple (💑):**
```
"Merhaba! Kapadokya'da romantik bir kaçamak için harika bir plan hazırlamışsınız. 
Özel balon turumuz ve gün batımı şarap tadımımız tam size göre olabilir..."
```

**Luxury Traveler (✨):**
```
"Hello! We noticed you're planning a premium Cappadocia experience. 
Our VIP private guide service and exclusive fine dining options would be perfect..."
```

**Content Creator (📸):**
```
"Hi! We see you're interested in capturing Cappadocia's beauty. 
Our sunrise balloon tour with drone permit and professional photo shoot package..."
```

---

## 🔧 For Developers

### Using PersonaBadge Component

```tsx
import { PersonaBadge } from '@/components/PersonaBadge';

// Compact mode (for cards)
<PersonaBadge 
  persona={lead.tourist_persona} 
  confidence={lead.persona_confidence}
  language="tr"
  compact
/>

// Inline mode (for lists)
<PersonaBadge 
  persona={lead.tourist_persona} 
  confidence={lead.persona_confidence}
  language="en"
/>

// Detailed mode (for modals)
<PersonaBadge 
  persona={lead.tourist_persona} 
  confidence={lead.persona_confidence}
  language="tr"
  showDetails
/>
```

### Querying High-Value Leads

```typescript
// Using Supabase RPC
const { data, error } = await supabase.rpc('get_high_value_leads');

// Returns leads with:
// - spend_potential: 'high' or 'very_high'
// - persona_confidence >= 0.7
// - status: 'new'
// Sorted by spend potential and confidence
```

### Getting Persona Statistics

```typescript
// Using Supabase RPC
const { data, error } = await supabase.rpc('get_persona_statistics');

// Returns:
// - persona_type
// - count
// - avg_confidence
// - avg_travelers
```

### Manual Persona Detection

```typescript
import { detectPersona } from '@/utils/persona-detection';

const result = detectPersona({
  number_of_travelers: 2,
  interests: ['balloon', 'wine tasting'],
  planned_activities: [...],
  start_date: '2026-03-01',
  end_date: '2026-03-05',
  email: 'user@example.com',
  country: 'USA'
});

// result.persona - Full persona object
// result.confidence - 0-1 confidence score
```

---

## 📈 For Admins

### Accessing Analytics

1. Navigate to **Admin Panel** → **Persona Analytics**
2. Or go directly to `/admin/persona-analytics`

### Understanding Charts

**Pie Chart - Persona Distribution:**
- Shows percentage of each persona type
- Larger slices = more common personas
- Click legend to filter

**Bar Chart - Spend Potential:**
- Compares total spend potential by persona
- Higher bars = more valuable segment
- Use for marketing prioritization

**Bar Chart - Confidence Scores:**
- Shows average detection confidence
- Higher = more reliable classifications
- Monitor for quality assurance

**Statistics Table:**
- Detailed breakdown per persona
- Lead count, confidence, travelers
- Export for reporting

### Key Metrics to Monitor

1. **High-Value Lead Percentage**
   - Target: >30% high/very_high spend
   - Action: Adjust marketing if too low

2. **Average Confidence Score**
   - Target: >0.6 overall
   - Action: Review detection logic if low

3. **Persona Distribution**
   - Look for unexpected patterns
   - Adjust offerings to match demand

4. **Conversion by Persona**
   - Track which personas convert best
   - Optimize pricing and services

---

## 🎨 Color Coding

### Spend Potential Colors

- 🟣 **Very High** - Purple - Premium leads
- 🟢 **High** - Green - Valuable leads
- 🔵 **Medium** - Blue - Standard leads
- ⚫ **Low** - Gray - Budget leads

### Badge Styles

- **Primary** - Persona label
- **Outline** - Spend potential
- **Secondary** - Confidence score
- **Gradient** - AI recommendations

---

## 🔍 Detection Signals

### What Triggers Each Persona?

**Romantic Couple:**
- 2 travelers
- Balloon tours (especially dawn)
- Wine tasting
- Sunset viewpoints
- "Romantic" in interests

**Luxury Traveler:**
- Private tours
- "Luxury" in interests
- High activity density
- Premium services
- Small group (2-4)

**Budget Backpacker:**
- "Budget" in interests
- Group tours
- Hiking activities
- Long trip, few paid activities
- Solo or large group

**Content Creator:**
- "Photography" in interests
- "Drone" in interests
- Many viewpoints (3+)
- Sunrise activities
- Instagram/social media

**Family Explorer:**
- 3-6 travelers
- Family-friendly activities
- Not budget-focused
- Moderate spend

**Solo Adventurer:**
- 1 traveler
- Adventure activities
- Hiking/trekking
- Local experiences

**Group Tour:**
- 8+ travelers
- Group activities
- Organized tours
- Bus transfers

---

## 💡 Best Practices

### For Providers

1. **Check Persona First**
   - Review before contacting lead
   - Tailor your message
   - Reference relevant services

2. **Use Recommended Services**
   - Start with suggested offerings
   - Highlight matching features
   - Build custom packages

3. **Monitor Confidence**
   - High confidence (>70%) = reliable
   - Medium confidence (40-70%) = likely
   - Low confidence (<40%) = uncertain

4. **Track Conversion**
   - Note which personas convert
   - Adjust approach by persona
   - Share insights with team

### For Admins

1. **Regular Monitoring**
   - Check analytics weekly
   - Look for trends
   - Identify opportunities

2. **Quality Assurance**
   - Review low-confidence leads
   - Validate persona accuracy
   - Adjust detection if needed

3. **Strategic Planning**
   - Align marketing with personas
   - Develop persona-specific campaigns
   - Optimize provider offerings

4. **Data Export**
   - Export statistics regularly
   - Share with stakeholders
   - Track performance over time

---

## 🐛 Troubleshooting

### Persona Not Detected

**Possible Causes:**
- No activities added to trip
- Generic interests only
- Insufficient trip data

**Solution:**
- Ensure trip has activities
- Add specific interests
- Complete trip details

### Low Confidence Score

**Possible Causes:**
- Mixed signals
- Ambiguous trip characteristics
- Multiple persona indicators

**Solution:**
- Review detected signals
- Check for conflicting data
- Consider as "general traveler"

### Wrong Persona Detected

**Possible Causes:**
- Unusual trip combination
- Edge case scenario
- Detection logic needs tuning

**Solution:**
- Review signals in detail
- Report to development team
- Use confidence score as guide

---

## 📞 Support

For technical issues or questions:
- Check PERSONA_ENGINE_SUMMARY.md for details
- Review TODO.md for implementation status
- Contact development team for assistance

---

## 🎉 Success Tips

1. **Trust the System** - High confidence scores are reliable
2. **Personalize Outreach** - Use persona insights in communication
3. **Track Results** - Monitor conversion by persona
4. **Iterate** - Adjust approach based on data
5. **Share Feedback** - Help improve the system

---

*Quick Reference Guide v1.0*
*Last Updated: 2026-02-25*
