# Surprise Me Feature - Quick Summary

## What is "Surprise Me"?

A lightweight video recommendation system for personal video collections that helps users **rediscover** content they might have forgotten about or haven't watched yet.

## Key Concept

Unlike YouTube's complex ML-based recommendations, "Surprise Me" focuses on:
- ✨ **Rediscovery**: Surface videos you've forgotten
- 🎲 **Variety**: Mix content from different libraries
- 🎯 **Simplicity**: No complex ML, just smart queries
- 📊 **Personal**: Uses YOUR ratings, bookmarks, and viewing patterns

## UI Location

**Sidebar Item** (NOT a tab):
```
Sidebar Navigation:
├── Home
├── Settings  
├── Videos
├── Photos
├── Texts
├── Bookmarks
├── 🎲 Surprise Me  ← NEW standalone page at /surprise-me
├── Clusters
└── Folder Viewer
```

When clicked → navigates to dedicated `/surprise-me` page

## Recommendation Algorithms

### 1. **Smart Mix** (Default) 
Balanced combination of all algorithms:
- 30% Weighted Random
- 25% Forgotten Gems  
- 20% Similar to Favorites
- 15% Unwatched First
- 10% Time-Based

### 2. **Weighted Random**
Smart randomization considering:
- How long since last viewed (prefer older)
- Video ratings (slight boost for higher rated)
- Library diversity (ensure variety)

### 3. **Forgotten Gems**
Videos you showed interest in but haven't watched recently:
- Bookmarked videos (30+ days ago)
- Highly-rated videos (4+ stars, 60+ days)
- Videos from bookmarked folders

### 4. **Similar to Favorites**
Find videos from same folders as your 4+ star videos

### 5. **Time-Based**
- Recently added but unwatched
- Seasonal (same time last year)
- Archive discoveries (old, never watched)

### 6. **Pure Random**
Complete serendipity - totally random selection

### 7. **Unwatched First**
Prioritize videos never accessed before

## Technical Architecture

### New Database Table
```sql
media_access (
  media_id,
  access_type: 'view' | 'play' | 'bookmark' | 'rate',
  created_at
)
```

Tracks when users interact with videos for better recommendations.

### New API Endpoints

**GET `/api/videos/recommendations`**
- Query params: `algorithm`, `limit`, `exclude_recent_days`
- Returns: Array of recommended videos with reasons

**POST `/api/media-access/:id`**
- Tracks user interactions for recommendation improvement

### New Components

1. **`/src/app/surprise-me/page.tsx`** - Main page
2. **`/src/lib/recommendation-service.ts`** - Algorithm logic
3. **Modified `sidebar.tsx`** - Add Surprise Me item

## User Flow

1. User clicks "🎲 Surprise Me" in sidebar
2. Page loads with 20 recommended videos (default: Smart Mix)
3. Each video card shows:
   - Thumbnail
   - Title, path, size
   - Rating/bookmark status
   - **Recommendation reason** badge (e.g., "From your favorite library")
4. User can:
   - Click video to watch
   - Click "Refresh" for new recommendations
   - Change algorithm via dropdown
   - Bookmark/rate directly from cards

## Implementation Phases

### Phase 1: Foundation ✅
- [x] Design documentation
- [ ] Database migration
- [ ] Basic service structure

### Phase 2: Core (Week 1)
- [ ] 3 basic algorithms (Weighted Random, Unwatched, Pure Random)
- [ ] API endpoint
- [ ] Basic UI page

### Phase 3: Advanced (Week 2)
- [ ] 4 advanced algorithms
- [ ] Smart Mix
- [ ] Polished UI

### Phase 4: Integration (Week 3)
- [ ] Auto-track video views
- [ ] Recommendation badges
- [ ] Performance optimization

## Benefits

### For Users
- 🎯 **Discover new content** in their own library
- ⏰ **Save time** deciding what to watch
- 💎 **Rediscover forgotten favorites**
- 🎲 **Serendipitous discoveries**
- 📚 **Explore entire collection** systematically

### Technical
- 🚀 **Lightweight** - no ML infrastructure needed
- ⚡ **Fast** - simple SQL queries with indexes
- 📈 **Scalable** - works with 1K to 100K+ videos
- 🔧 **Maintainable** - pure SQL, no black boxes
- 🎨 **Extensible** - easy to add new algorithms

## Example Scenarios

### Scenario: Large Movie Collection
**Problem**: User has 5,000 movies but always watches the same 50

**Solution**: 
- Unwatched First: Shows 100s of movies never opened
- Forgotten Gems: Surfaces 4-star movies from 2 years ago
- Similar to Favorites: Finds movies in same genre folders

### Scenario: New Content Added
**Problem**: User adds 200 new videos but forgets about them

**Solution**:
- Time-Based: "Recently added" shows last 7 days
- Smart Mix: Includes 30% new content automatically

### Scenario: Bored, Want Something Different
**Problem**: User wants to watch something but doesn't know what

**Solution**:
- Pure Random: Complete surprise from entire collection
- Weighted Random: Random but slightly favors good stuff

## Why This Design?

### Lightweight Approach
- ✅ No complex ML training
- ✅ No external dependencies
- ✅ Works offline
- ✅ Instant results
- ✅ Easy to understand and debug

### Personal-Focused
- ✅ Designed for single user
- ✅ Leverages existing data (bookmarks, ratings)
- ✅ Respects user's organizational structure
- ✅ No privacy concerns (all local)

### Practical
- ✅ Solves real problem (content discovery)
- ✅ Easy to implement incrementally
- ✅ Low maintenance overhead
- ✅ Clear success metrics

## Success Metrics

- **80%** of users try the feature
- **30%** click-through rate on recommendations
- **50%** of recommendations are unwatched videos
- **High** diversity across libraries/folders

## Future Enhancements

- 🎵 Playlist generation from recommendations
- 📊 Statistics dashboard
- 🎯 "Similar videos" on player page
- 📅 "Video of the Day" feature
- 🔍 Advanced filters (by library, rating, size)
- 💾 Save recommendation sets
- 🚫 "Not interested" exclusions

---

**See Full Design**: [SURPRISE_ME_RECOMMENDATION_DESIGN.md](./SURPRISE_ME_RECOMMENDATION_DESIGN.md)

**Status**: 📝 Design Complete → Ready for Implementation  
**Next Step**: Database schema migration