# Persona Engine Quick Reference

## Signal Weights Reference

### Romantic Couple (💑) - Very High Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| has_balloon | 0.4 | Balloon + 2 travelers |
| has_wine_tasting | 0.35 | Wine/tasting activities |
| has_sunset_viewpoint | 0.25 | 2+ viewpoints + dawn |
| is_couple | 0.3 | Exactly 2 travelers |
| has_dawn_activities | 0.2 | Dawn time block |
| interest_romantic | 0.3 | Romantic keywords |

**Keywords:** romantic, romantik, honeymoon, balayı, couple, çift

---

### Luxury Traveler (✨) - Very High Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| has_private_balloon | 0.5 | Private + balloon |
| interest_luxury | 0.4 | Luxury keywords |
| interest_gastronomy | 0.25 | Food/gastro keywords |
| has_private_tour | 0.35 | Private/özel activities |
| short_trip_many_activities | 0.2 | ≤3 days, ≥4 activities/day, ≤3 travelers |

**Keywords:** luxury, lüks, premium, vip, exclusive, özel, gastro, food, yemek

---

### Budget Backpacker (🎒) - Low Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| interest_budget | 0.4 | Budget keywords |
| has_group_tour | 0.3 | Group tour activities |
| large_group | 0.25 | 5-10 travelers |
| interest_hiking | 0.2 | Hiking/trekking keywords |
| long_trip_few_paid | 0.2 | Long trip, few paid activities |

**Keywords:** budget, bütçe, cheap, ucuz, hiking, trek, yürüyüş, group, grup

---

### Content Creator (📸) - High Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| interest_photography | 0.45 | Photography keywords |
| interest_drone | 0.5 | Drone keywords |
| has_sunrise_balloon | 0.35 | Balloon + dawn activities |
| interest_instagram | 0.4 | Social media keywords |
| many_viewpoints | 0.3 | 3+ viewpoints |

**Keywords:** photo, fotoğraf, drone, instagram, content, sosyal medya, viewpoint, panorama, manzara

---

### Family Explorer (👨‍👩‍👧‍👦) - Medium Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| family_size | 0.3 | 3-6 travelers, no budget/private balloon |

**Keywords:** family, aile, kids, çocuk, children

---

### Solo Adventurer (🧗) - Medium Spend
| Signal | Weight | Condition |
|--------|--------|-----------|
| solo_travel | 0.4 | 1 traveler |

**Keywords:** solo, tek başına, adventure, macera

---

### Group Tour (👥) - High Spend (Total)
| Signal | Weight | Condition |
|--------|--------|-----------|
| very_large_group | 0.5 | 10+ travelers |
| has_group_activities | 0.35 | Group activity types |

**Keywords:** group, grup, friends, arkadaş, tour

---

## Confidence Score Formula

```
confidence = min(maxScore / (totalScore * 0.6), 1.0)
```

- **maxScore**: Highest individual persona score
- **totalScore**: Sum of all persona scores
- **Result**: 0.0 - 1.0 (rounded to 2 decimals)
- **Default**: 0.3 (when no signals detected)

---

## Usage Examples

### Example 1: Romantic Couple
```typescript
const input = {
  number_of_travelers: 2,
  interests: ['romantic', 'photography'],
  planned_activities: [
    { name: 'Hot Air Balloon', type: 'balloon', time_block: 'dawn' },
    { name: 'Wine Tasting', type: 'tasting' },
    { name: 'Sunset Viewpoint', type: 'viewpoint' }
  ],
  start_date: '2026-06-01',
  end_date: '2026-06-03'
};

// Result:
// Persona: romantic_couple
// Confidence: ~0.85
// Signals: ['Çift + Balon', '2 kişilik seyahat', 'Gün doğumu aktivitesi', 'Şarap tadımı', 'Romantik ilgi alanı']
```

### Example 2: Content Creator
```typescript
const input = {
  number_of_travelers: 1,
  interests: ['photography', 'drone', 'instagram'],
  planned_activities: [
    { name: 'Sunrise Balloon', type: 'balloon', time_block: 'dawn' },
    { name: 'Love Valley Viewpoint', type: 'viewpoint' },
    { name: 'Uchisar Castle Viewpoint', type: 'viewpoint' },
    { name: 'Pigeon Valley Panorama', type: 'viewpoint' }
  ],
  start_date: '2026-06-01',
  end_date: '2026-06-04'
};

// Result:
// Persona: content_creator
// Confidence: ~0.92
// Signals: ['Gün doğumu balonu', '3 panorama noktası', 'Fotoğrafçılık ilgisi', 'Drone kullanımı', 'Sosyal medya / içerik üretimi']
```

### Example 3: Luxury Traveler
```typescript
const input = {
  number_of_travelers: 2,
  interests: ['luxury', 'gastronomy'],
  planned_activities: [
    { name: 'Private Hot Air Balloon', type: 'private_balloon' },
    { name: 'Private Cave Hotel Tour', type: 'private_tour' },
    { name: 'Fine Dining Experience', type: 'restaurant' }
  ],
  start_date: '2026-06-01',
  end_date: '2026-06-02'
};

// Result:
// Persona: luxury_traveler
// Confidence: ~0.95
// Signals: ['Özel balon turu', 'Özel tur aktivitesi', 'Lüks ilgi alanı', 'Gastronomi ilgisi', 'Yoğun kısa seyahat']
```

---

## Admin Dashboard Usage

### High-Value Leads Query
```sql
SELECT * FROM get_high_value_leads();
```
Returns leads with:
- Spend potential: high or very_high
- Confidence: ≥ 0.7
- Status: new
- Sorted by: spend potential DESC, confidence DESC, created_at DESC

### Persona Statistics Query
```sql
SELECT * FROM get_persona_statistics();
```
Returns:
- persona_type
- count (number of leads)
- avg_confidence (average confidence score)
- avg_travelers (average number of travelers)

---

## Provider Dashboard Features

### Persona Badge Display
- **Compact Mode**: Shows emoji, label, confidence in table view
- **Detailed Mode**: Shows full persona info in lead detail modal
- **Language**: Turkish for providers, English for admins
- **Color Coding**: Spend potential color-coded (purple = very_high, green = high, blue = medium, gray = low)

### Lead Prioritization
Providers should prioritize leads in this order:
1. **Very High Spend** (💑 Romantic Couple, ✨ Luxury Traveler) - Confidence ≥ 0.7
2. **High Spend** (📸 Content Creator, 👥 Group Tour) - Confidence ≥ 0.6
3. **Medium Spend** (👨‍👩‍👧‍👦 Family Explorer, 🧗 Solo Adventurer) - Confidence ≥ 0.5
4. **Low Spend** (🎒 Budget Backpacker) - All confidence levels

---

## Tuning Guide

### Adjusting Signal Weights
To increase/decrease persona detection sensitivity:

1. **Increase Weight** - Make signal more important
   ```typescript
   has_private_balloon: { type: 'luxury_traveler', weight: 0.6 } // was 0.5
   ```

2. **Decrease Weight** - Make signal less important
   ```typescript
   interest_budget: { type: 'budget_backpacker', weight: 0.3 } // was 0.4
   ```

3. **Add New Signal** - Create new detection rule
   ```typescript
   has_spa_activity: { type: 'romantic_couple', weight: 0.25 }
   ```

### Adjusting Confidence Threshold
To change minimum confidence for high-value leads:

```sql
-- In get_high_value_leads() function
WHERE l.persona_confidence >= 0.8  -- was 0.7
```

---

## Troubleshooting

### Low Confidence Scores
**Problem**: All leads getting low confidence (< 0.5)

**Solutions**:
1. Check if activities have `type` field populated
2. Verify interests array is not empty
3. Add more keywords to signal detection
4. Adjust confidence formula divisor (0.6 → 0.5)

### Wrong Persona Detection
**Problem**: Leads assigned to wrong persona

**Solutions**:
1. Review detected signals in lead detail modal
2. Adjust signal weights for competing personas
3. Add more specific keywords
4. Check for keyword conflicts (e.g., "budget luxury")

### Missing Signals
**Problem**: Expected signals not detected

**Solutions**:
1. Verify activity names/types contain keywords
2. Check for typos in keywords
3. Add Turkish/English variations
4. Use lowercase comparison (already implemented)

---

## Best Practices

### For Developers
1. Always test persona detection with real trip data
2. Monitor confidence score distribution
3. Track conversion rates by persona
4. Adjust weights based on business feedback
5. Keep signal definitions centralized
6. Document any weight changes

### For Admins
1. Review persona statistics weekly
2. Identify underperforming personas
3. Adjust lead pricing based on persona
4. Train providers on persona characteristics
5. Monitor high-value lead conversion rates
6. Use persona data for marketing insights

### For Providers
1. Read key signals to understand customer needs
2. Tailor communication based on persona
3. Offer recommended services first
4. Adjust pricing based on spend potential
5. Track which personas convert best
6. Provide feedback on persona accuracy
