# Recommendation & Vibe Specification

This document defines the logic for the "Vibe" engine, moving from simple similarity to a continuous, evolving listening experience.

## 1. The "Vibe" Concept
The "Vibe" is an infinite, stateful listening session. Unlike a static playlist, it is a **Rolling Window** that evolves based on user interaction.

## 2. Scoring Logic

When generating a sequence, every candidate track is assigned a score.

$$Score = (W_{genre} \cdot S_{genre}) + (W_{artist} \cdot S_{artist}) + (W_{random} \cdot R)$$

### **Scoring Components**
* **$S_{genre}$ (Genre Match):** 
    * Uses hierarchical weights (e.g., `Deep House` (1.0) $\rightarrow$ `House` (0.8) $\rightarrow$ `Electronic` (0.5)).
    * Calculated as the highest weight match between candidate and "Center Track."
* **$S_{artist}$ (Artist Similarity):** 
    * A binary or weighted score based on whether the artist is in the user's "Liked" list or frequent listening history.
* **$R$ (Randomness/Exploration):** 
    * A jitter factor to ensure the queue doesn't feel repetitive.

## 3. The Rolling Window Algorithm

The backend does not return a fixed list. It returns a **Sequence Chunk**.

### **Step-by-Step Generation**
1.  **Identify the Center:** Find the `last_successfully_played_track_id`.
2.  **Candidate Selection:**
    * **Local Pool (80%):** Tracks from the user's library similar to the center track.
    * **Probation Pool (20%):** Tracks from the `recommendation_batch` that have `probation=1`.
3.  **Constraint Application (Batch Rules):**
    * **Diversity Check:** No more than 1 track from the same artist per chunk.
    * **Genre Cap:** No more than 2 tracks from the same genre per chunk.
4.  **Chunking:** Return a sequence of $N$ tracks (e.g., 20).

## 4. The "Vibe" Session Lifecycle

A "Vibe" is represented by a `recommendation_batch` record.

| State | Description |
| :--- | :--- |
| **ACTIVE** | The user is currently listening. The stream is being generated. |
| **RESOLVED** | The session has ended naturally or timed out. |
| **FAILED** | The session was interrupted by a critical error or manual reset. |

### **Transition Logic**
* **Start:** User clicks "Start Vibe" $\rightarrow$ Create `ACTIVE` batch.
* **Progress:** User listens $\rightarrow$ Update `last_interaction_at` in the batch.
* **Termination:** 
    * **Natural:** User exits the app $\rightarrow$ Session marked `RESOLVED` after 24h.
    * **Manual:** User ends session $\rightarrow$ Mark `RESOLVED` immediately.
    * **Timeout:** No interaction for 24h $\rightarrow$ Mark `RESOLVED`.

## 5. Success/Failure Feedback Loop

The engine learns from the `feedback` table:
* **`action = 'promoted'`:** (High Score) Increase weight of this genre/artist in future seeds.
* **`action = 'disliked'`:** (Negative Signal) Decrease weight of this genre/artist.
* **`action = 'skipped'`:** (Transient Negative) Do not adjust long-term weights, but avoid this specific track in the current session window.