38980-vm/app-9w9pd00g5j41/QUICK_REFERENCE.md

Analyze-Trip Enhancement - Quick Reference Card

🎯 What Changed?

The analyze-trip edge function now calculates real distances and times to make intelligent, data-driven recommendations with full transparency.

---

📐 Density Score Formula

density_score = (distance_km × 5 + time_hours × 10) ÷ place_count

Thresholds

Score	Level	Recommendation	Confidence
0-19	🟢 Low	❌ No tour	0.0-0.48
20-34	🟡 Moderate	⚠️ Optional	0.50-0.70
35-49	🟠 High	⭐ Recommend	0.70-0.85
50+	🔴 Very High	🔥 Highly Recommend	0.85-1.0

---

🔍 What Gets Calculated?

For Each Place

• ✅ Distance from previous place (km)
• ✅ Travel time from previous place (minutes)
• ✅ Visit duration (minutes)

For Each Day

• ✅ Total places
• ✅ Total distance (km)
• ✅ Total travel time (minutes)
• ✅ Total visit time (minutes)
• ✅ Density score
• ✅ Density level

For Entire Trip

• ✅ Total days
• ✅ Total places
• ✅ Total distance (km)
• ✅ Total time (hours)
• ✅ Average density score
• ✅ Maximum density score

---

🧠 Decision Factors

The AI considers these factors (in order of importance):

1. Density Score (PRIMARY) - How packed is the itinerary?
2. Total Distance - >100km suggests organized transport
3. Time Commitment - >8h/day suggests professional guidance
4. Group Size - ≥4 travelers benefit from private guide
5. Place Count - ≥5 places/day requires efficient routing
6. Activity Type - Museums, historical sites benefit from guides

---

📊 Response Structure

{
  "recommend": true,
  "confidence": 0.82,
  "recommended_type": "daily_tour",
  "daily_tour_slug": "red_tour",
  
  "debug_info": {
    "dailyMetrics": [
      {
        "dayNumber": 1,
        "densityScore": 42.8,
        "densityLevel": "high",
        "totalDistanceKm": 85.0,
        "totalTimeMinutes": 518,
        "places": [...]
      }
    ],
    
    "overallMetrics": {
      "maxDensityScore": 42.8,
      "totalDistanceKm": 85.0,
      "totalTimeHours": 8.6
    },
    
    "decisionFactors": [
      {
        "factor": "High Density Day",
        "value": 42.8,
        "impact": "positive",
        "reasoning": "..."
      }
    ],
    
    "recommendation_reasoning": "..."
  }
}

---

🚀 Quick Examples

Example 1: High Density → Recommend Tour

5 places, 85km, 8.5 hours
density = (85×5 + 8.5×10) ÷ 5 = 102 ÷ 5 = 20.4
Level: MODERATE → Optional tour (confidence: 0.52)

Example 2: Very High Density → Highly Recommend

4 places, 90km, 9.25 hours
density = (90×5 + 9.25×10) ÷ 4 = 542.5 ÷ 4 = 135.6
Level: VERY HIGH → Highly recommend (confidence: 0.94)

Example 3: Low Density → No Tour

3 places, 8km, 3.5 hours
density = (8×5 + 3.5×10) ÷ 3 = 75 ÷ 3 = 25
Level: MODERATE → Optional (confidence: 0.55)

---

🔧 Usage

API Call (No Changes)

const response = await supabase.functions.invoke('analyze-trip', {
  body: {
    destination: 'Cappadocia',
    days: [
      {
        date: '2024-06-15',
        places: [
          { name: 'Göreme Museum', type: 'museum', lat: 38.6425, lng: 34.8317, duration: '2 hours' },
          { name: 'Uchisar Castle', type: 'historical', lat: 38.6267, lng: 34.8050, duration: '1.5 hours' }
        ]
      }
    ],
    travelers: 2,
    interests: ['history', 'nature']
  }
});

const { recommend, confidence, debug_info } = response.data;

Access Debug Info

// Overall metrics
console.log(debug_info.overallMetrics.maxDensityScore);
console.log(debug_info.overallMetrics.totalDistanceKm);

// Daily breakdown
debug_info.dailyMetrics.forEach(day => {
  console.log(`Day ${day.dayNumber}: ${day.densityScore} (${day.densityLevel})`);
});

// Decision factors
debug_info.decisionFactors.forEach(factor => {
  console.log(`${factor.factor}: ${factor.value} (${factor.impact})`);
});

---

📁 Documentation Files

1. ANALYZE_TRIP_ENHANCEMENT.md - Complete feature documentation
2. DENSITY_SCORE_GUIDE.md - Visual guide with examples
3. BEFORE_AFTER_COMPARISON.md - Detailed comparison
4. ENHANCEMENT_SUMMARY.md - Implementation summary
5. test-analyze-trip.js - Test script

---

✅ Key Benefits

Accuracy

• Real distance calculations (Haversine formula)
• Actual time estimates (travel + visit)
• Data-driven confidence scores

Transparency

• See exactly why recommendation was made
• Understand which days are complex
• Know what factors influenced decision

Intelligence

• Density-based scoring (not just place count)
• Adaptive thresholds
• Nuanced recommendations

---

🎓 Rule of Thumb

Quick Mental Calculation:

• 5+ places over 80+ km → Likely HIGH density
• 2-3 nearby places → Likely LOW density
• 8+ hours with lots of travel → Likely HIGH density

When to Recommend Tour:

• Density score ≥35
• OR total distance >100km
• OR daily time >8 hours
• OR 4+ travelers with complex itinerary

---

🔮 Future Enhancements

• Real-time traffic data
• Weather-based adjustments
• Seasonal crowd factors
• User feedback loop
• ML pattern recognition

---

Status: ✅ Deployed and Active Version: 2.0 (Enhanced) Date: February 7, 2024